FM / perl-Image-Base

/usr/share/doc/perl-Image-Base

Name	Size	Mode	Actions
README	4848	0644	edit dl rm

Edit: /usr/share/doc/perl-Image-Base/README (4848B)

=head1 NAME

Image::Base - base class for loading, manipulating and saving images.

=head1 SYNOPSIS

This class should not be used directly. Known inheritors are Image::Xbm and
Image::Xpm.

use Image::Xpm ;

my $i = Image::Xpm->new( -file => 'test.xpm' ) ;
    $i->line( 1, 1, 3, 7, 'red' ) ;
    $i->ellipse( 3, 3, 6, 7, '#ff00cc' ) ;
    $i->rectangle( 4, 2, 9, 8, 'blue' ) ;

If you want to create your own algorithms to manipulate images in terms of
(x,y,colour) then you could extend this class (without changing the file),
like this:

# Filename: mylibrary.pl
    package Image::Base ; # Switch to this class to build on it.
    
    sub mytransform {
        my $self  = shift ;
        my $class = ref( $self ) || $self ;

# Perform your transformation here; might be drawing a line or filling
        # a rectangle or whatever... getting/setting pixels using $self->xy().
    }

package main ; # Switch back to the default package.

Now if you C<require> mylibrary.pl after you've C<use>d Image::Xpm or any
other Image::Base inheriting classes then all these classes will inherit your
C<mytransform()> method.

=head1 DESCRIPTION

=head2 new_from_image()

my $bitmap = Image::Xbm->new( -file => 'bitmap.xbm' ) ;
    my $pixmap = $bitmap->new_from_image( 'Image::Xpm', -cpp => 1 ) ;
    $pixmap->save( 'pixmap.xpm' ) ;

Note that the above will only work if you've installed Image::Xbm and
Image::Xpm, but will work correctly for any image object that inherits from
Image::Base and respects its API.

You can use this method to transform an image to another image of the same
type but with some different characteristics, e.g.

my $p = Image::Xpm->new( -file => 'test1.xpm' ) ;
    my $q = $p->new_from_image( ref $p, -cpp => 2, -file => 'test2.xpm' ) ;
    $q->save ;

=head2 line()

$i->line( $x0, $y0, $x1, $y1, $colour ) ;

Draw a line from point ($x0,$y0) to point ($x1,$y1) in colour $colour.

=head2 ellipse()

$i->ellipse( $x0, $y0, $x1, $y1, $colour ) ;

Draw an oval enclosed by the rectangle whose top left is ($x0,$y0) and bottom
right is ($x1,$y1) using a line colour of $colour.

=head2 rectangle()

$i->rectangle( $x0, $y0, $x1, $y1, $colour, $fill ) ;

Draw a rectangle whose top left is ($x0,$y0) and bottom right is ($x1,$y1)
using a line colour of $colour. If C<$fill> is true then the rectangle will be
filled.

=head2 new()

Virtual - must be overridden.

Recommend that it at least supports C<-file> (filename), C<-width> and
C<-height>.

=head2 new_from_serialised()

Not implemented. Recommended for inheritors. Should accept a string serialised
using serialise() and return an object (reference).

=head2 serialise()

Not implemented. Recommended for inheritors. Should return a string
representation (ideally compressed).

=head2 get()
     
    my $width = $i->get( -width ) ;
    my( $hotx, $hoty ) = $i->get( -hotx, -hoty ) ;

Get any of the object's attributes. Multiple attributes may be requested in a
single call.

See C<xy> get/set colours of the image itself.

=head2 set()

Virtual - must be overridden.

Set any of the object's attributes. Multiple attributes may be set in a single
call; some attributes are read-only.

See C<xy> get/set colours of the image itself.

=head2 xy()

Virtual - must be overridden. Expected to provide the following functionality:

$i->xy( 4, 11, '#123454' ) ;    # Set the colour at point 4,11
    my $v = $i->xy( 9, 17 ) ;       # Get the colour at point 9,17

Get/set colours using x, y coordinates; coordinates start at 0.

When called to set the colour the value returned is class specific; when
called to get the colour the value returned is the colour name, e.g. 'blue' or
'#f0f0f0', etc, e.g.

$colour = xy( $x, $y ) ;  # e.g. #123456 
    xy( $x, $y, $colour ) ;   # Return value is class specific

We don't normally pick up the return value when setting the colour.

=head2 load()

Virtual - must be overridden. Expected to provide the following functionality:

$i->load ;
    $i->load( 'test.xpm' ) ;

Load the image whose name is given, or if none is given load the image whose
name is in the C<-file> attribute.

=head2 save()

Virtual - must be overridden. Expected to provide the following functionality:

$i->save ;
    $i->save( 'test.xpm' ) ;

Save the image using the name given, or if none is given save the image using
the name in the C<-file> attribute. The image is saved in xpm format.

=head1 CHANGES

2000/05/05

Added some basic drawing methods. Minor documentation changes.

2000/05/04

Created.

=head1 AUTHOR

Mark Summerfield. I can be contacted as <summer@perlpress.com> -
please include the word 'imagebase' in the subject line.

=head1 COPYRIGHT

This module may be used/distributed/modified under the LGPL.

=cut

=head1 NAME Image::Base - base class for loading, manipulating and saving images. =head1 SYNOPSIS This class should not be used directly. Known inheritors are Image::Xbm and Image::Xpm. use Image::Xpm ; my $i = Image::Xpm->new( -file => 'test.xpm' ) ; $i->line( 1, 1, 3, 7, 'red' ) ; $i->ellipse( 3, 3, 6, 7, '#ff00cc' ) ; $i->rectangle( 4, 2, 9, 8, 'blue' ) ; If you want to create your own algorithms to manipulate images in terms of (x,y,colour) then you could extend this class (without changing the file), like this: # Filename: mylibrary.pl package Image::Base ; # Switch to this class to build on it. sub mytransform { my $self = shift ; my $class = ref( $self ) || $self ; # Perform your transformation here; might be drawing a line or filling # a rectangle or whatever... getting/setting pixels using $self->xy(). } package main ; # Switch back to the default package. Now if you C mylibrary.pl after you've Cd Image::Xpm or any other Image::Base inheriting classes then all these classes will inherit your C method. =head1 DESCRIPTION =head2 new_from_image() my $bitmap = Image::Xbm->new( -file => 'bitmap.xbm' ) ; my $pixmap = $bitmap->new_from_image( 'Image::Xpm', -cpp => 1 ) ; $pixmap->save( 'pixmap.xpm' ) ; Note that the above will only work if you've installed Image::Xbm and Image::Xpm, but will work correctly for any image object that inherits from Image::Base and respects its API. You can use this method to transform an image to another image of the same type but with some different characteristics, e.g. my $p = Image::Xpm->new( -file => 'test1.xpm' ) ; my $q = $p->new_from_image( ref $p, -cpp => 2, -file => 'test2.xpm' ) ; $q->save ; =head2 line() $i->line( $x0, $y0, $x1, $y1, $colour ) ; Draw a line from point ($x0,$y0) to point ($x1,$y1) in colour $colour. =head2 ellipse() $i->ellipse( $x0, $y0, $x1, $y1, $colour ) ; Draw an oval enclosed by the rectangle whose top left is ($x0,$y0) and bottom right is ($x1,$y1) using a line colour of $colour. =head2 rectangle() $i->rectangle( $x0, $y0, $x1, $y1, $colour, $fill ) ; Draw a rectangle whose top left is ($x0,$y0) and bottom right is ($x1,$y1) using a line colour of $colour. If C<$fill> is true then the rectangle will be filled. =head2 new() Virtual - must be overridden. Recommend that it at least supports C<-file> (filename), C<-width> and C<-height>. =head2 new_from_serialised() Not implemented. Recommended for inheritors. Should accept a string serialised using serialise() and return an object (reference). =head2 serialise() Not implemented. Recommended for inheritors. Should return a string representation (ideally compressed). =head2 get() my $width = $i->get( -width ) ; my( $hotx, $hoty ) = $i->get( -hotx, -hoty ) ; Get any of the object's attributes. Multiple attributes may be requested in a single call. See C get/set colours of the image itself. =head2 set() Virtual - must be overridden. Set any of the object's attributes. Multiple attributes may be set in a single call; some attributes are read-only. See C get/set colours of the image itself. =head2 xy() Virtual - must be overridden. Expected to provide the following functionality: $i->xy( 4, 11, '#123454' ) ; # Set the colour at point 4,11 my $v = $i->xy( 9, 17 ) ; # Get the colour at point 9,17 Get/set colours using x, y coordinates; coordinates start at 0. When called to set the colour the value returned is class specific; when called to get the colour the value returned is the colour name, e.g. 'blue' or '#f0f0f0', etc, e.g. $colour = xy( $x, $y ) ; # e.g. #123456 xy( $x, $y, $colour ) ; # Return value is class specific We don't normally pick up the return value when setting the colour. =head2 load() Virtual - must be overridden. Expected to provide the following functionality: $i->load ; $i->load( 'test.xpm' ) ; Load the image whose name is given, or if none is given load the image whose name is in the C<-file> attribute. =head2 save() Virtual - must be overridden. Expected to provide the following functionality: $i->save ; $i->save( 'test.xpm' ) ; Save the image using the name given, or if none is given save the image using the name in the C<-file> attribute. The image is saved in xpm format. =head1 CHANGES 2000/05/05 Added some basic drawing methods. Minor documentation changes. 2000/05/04 Created. =head1 AUTHOR Mark Summerfield. I can be contacted as - please include the word 'imagebase' in the subject line. =head1 COPYRIGHT Copyright (c) Mark Summerfield 2000. All Rights Reserved. This module may be used/distributed/modified under the LGPL. =cut