Image::Base(3pm)

1Image::Base(3)        User Contributed Perl Documentation       Image::Base(3)
2
3
4

NAME

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

SYNOPSIS

9        # base class only
10        package My::Image::Class;
11        use base 'Image::Base';
12

DESCRIPTION

14       This is a base class for image.  It shouldn't be used directly.  Known
15       inheritors are "Image::Xbm" and "Image::Xpm" and in see "SEE ALSO"
16       below.
17
18           use Image::Xpm ;
19
20           my $i = Image::Xpm->new( -file => 'test.xpm' ) ;
21           $i->line( 1, 1, 3, 7, 'red' ) ;
22           $i->ellipse( 3, 3, 6, 7, '#ff00cc' ) ;
23           $i->rectangle( 4, 2, 9, 8, 'blue' ) ;
24
25       Subclasses like "Image::Xpm" and "Image::Xbm" are stand-alone Perl code
26       implementations of the respective formats.  They're good for drawing
27       and manipulating image files with a modest amount of code and
28       dependencies.
29
30       Other inheritors like "Image::Base::GD" are front-ends to big image
31       libraries.  They can be handy for pointing generic "Image::Base" style
32       code at a choice of modules and supported file formats.  Some
33       inheritors like "Image::Base::X11::Protocol::Drawable" even go to a
34       window etc for direct display.
35
36   More Methods
37       If you want to create your own algorithms to manipulate images in terms
38       of (x,y,colour) then you could extend this class (without changing the
39       file), like this:
40
41           # Filename: mylibrary.pl
42           package Image::Base ; # Switch to this class to build on it.
43
44           sub mytransform {
45               my $self  = shift ;
46               my $class = ref( $self ) || $self ;
47
48               # Perform your transformation here; might be drawing a line or filling
49               # a rectangle or whatever... getting/setting pixels using $self->xy().
50           }
51
52           package main ; # Switch back to the default package.
53
54       Now if you "require" mylibrary.pl after you've "use"d Image::Xpm or any
55       other Image::Base inheriting classes then all these classes will
56       inherit your mytransform() method.
57

FUNCTIONS

59   new_from_image()
60           my $bitmap = Image::Xbm->new( -file => 'bitmap.xbm' ) ;
61           my $pixmap = $bitmap->new_from_image( 'Image::Xpm', -cpp => 1 ) ;
62           $pixmap->save( 'pixmap.xpm' ) ;
63
64       Note that the above will only work if you've installed Image::Xbm and
65       Image::Xpm, but will work correctly for any image object that inherits
66       from Image::Base and respects its API.
67
68       You can use this method to transform an image to another image of the
69       same type but with some different characteristics, e.g.
70
71           my $p = Image::Xpm->new( -file => 'test1.xpm' ) ;
72           my $q = $p->new_from_image( ref $p, -cpp => 2, -file => 'test2.xpm' ) ;
73           $q->save ;
74
75   line()
76           $i->line( $x0, $y0, $x1, $y1, $colour ) ;
77
78       Draw a line from point ($x0,$y0) to point ($x1,$y1) in colour $colour.
79
80                       ***
81                  *****
82              ****
83           ***
84
85   ellipse()
86           $i->ellipse( $x0, $y0, $x1, $y1, $colour ) ;
87           $i->ellipse( $x0, $y0, $x1, $y1, $colour, $fill ) ;
88
89       Draw an oval enclosed by the rectangle whose top left is ($x0,$y0) and
90       bottom right is ($x1,$y1) using a line colour of $colour.  If optional
91       argument $fill is true then the ellipse is filled.
92
93              *********
94            **         **
95           *             *
96            **         **
97              *********
98
99   rectangle()
100           $i->rectangle( $x0, $y0, $x1, $y1, $colour ) ;
101           $i->rectangle( $x0, $y0, $x1, $y1, $colour, $fill ) ;
102
103       Draw a rectangle whose top left is ($x0,$y0) and bottom right is
104       ($x1,$y1) using a line colour of $colour. If $fill is true then the
105       rectangle will be filled.
106
107           ***************
108           *             *
109           *             *
110           *             *
111           ***************
112
113   diamond()
114           $i->diamond( $x0, $y0, $x1, $y1, $colour ) ;
115           $i->diamond( $x0, $y0, $x1, $y1, $colour, $fill ) ;
116
117       Draw a diamond shape within the rectangle top left ($x0,$y0) and bottom
118       right ($x1,$y1) using a $colour.  If optional argument $fill is true
119       then the diamond is filled.  For example
120
121                  ***
122              ****   ****
123           ***           ***
124              ****   ****
125                  ***
126
127   new()
128       Virtual - must be overridden.
129
130       Recommend that it at least supports "-file" (filename), "-width" and
131       "-height".
132
133   new_from_serialised()
134       Not implemented. Recommended for inheritors. Should accept a string
135       serialised using serialise() and return an object (reference).
136
137   serialise()
138       Not implemented. Recommended for inheritors. Should return a string
139       representation (ideally compressed).
140
141   get()
142           my $width = $i->get( -width ) ;
143           my( $hotx, $hoty ) = $i->get( -hotx, -hoty ) ;
144
145       Get any of the object's attributes. Multiple attributes may be
146       requested in a single call.
147
148       See "xy" get/set colours of the image itself.
149
150   set()
151       Virtual - must be overridden.
152
153       Set any of the object's attributes. Multiple attributes may be set in a
154       single call; some attributes are read-only.
155
156       See "xy" get/set colours of the image itself.
157
158   xy()
159       Virtual - must be overridden. Expected to provide the following
160       functionality:
161
162           $i->xy( 4, 11, '#123454' ) ;    # Set the colour at point 4,11
163           my $colour = $i->xy( 9, 17 ) ;  # Get the colour at point 9,17
164
165       Get/set colours using x, y coordinates; coordinates start at 0.
166
167       When called to set the colour the value returned is class specific;
168       when called to get the colour the value returned is the colour name,
169       e.g. 'blue' or '#f0f0f0', etc, e.g.
170
171           $colour = xy( $x, $y ) ;  # e.g. #123456
172           xy( $x, $y, $colour ) ;   # Return value is class specific
173
174       We don't normally pick up the return value when setting the colour.
175
176   load()
177       Virtual - must be overridden. Expected to provide the following
178       functionality:
179
180           $i->load ;
181           $i->load( 'test.xpm' ) ;
182
183       Load the image from the "-file" attribute filename.  Or if a filename
184       parameter is given then set "-file" to that name and load it.
185
186   save()
187       Virtual - must be overridden. Expected to provide the following
188       functionality:
189
190           $i->save ;
191           $i->save( 'test.xpm' ) ;
192
193       Save the image to the "-file" attribute filename.  Or if a filename
194       parameter is given then set "-file" to that name and save to there.
195
196       The save format depends on the "Image::Base" subclass.  Some implement
197       a "-file_format" attribute if multiple formats can be saved.
198
199   add_colours()
200       Add colours to the image palette, if applicable.
201
202           $i->add_colours( $name, $name, ...)
203
204       The drawing functions add colours as necessary, so this is just a way
205       to pre-load the palette.
206
207       add_colours() does nothing for images which don't have a palette or
208       can't take advantage of pre-loading colour names.  The base code in
209       "Image::Base" is a no-op.
210

ATTRIBUTES

212       The attributes for new(), get() and set() are up to the subclasses, but
213       the common settings, when available, include
214
215       "-width" (integers)
216       "-height"
217           The size of the image.  These might be create-only with new()
218           taking a size which is then fixed.  If the image can be resized
219           then set() of "-width" and/or "-height" does a resize.
220
221       "-file" (string)
222           Set by new() reading a file, or load() or save() if passed a
223           filename, or just by set() ready for a future load() or save().
224
225       "-file_format" (string)
226           The name of the file format loaded or to save as.  This is
227           generally an abbreviation like "XPM", set by load() or set() and
228           then used by save().
229
230       "-hotx" (integers, or maybe -1 or maybe "undef")
231       "-hoty"
232           The coordinates of the "hotspot" position.  Images which can be a
233           mouse cursor or similar have a position within the image which is
234           the active pixel for clicking etc.  For example XPM and CUR (cursor
235           form of ICO) formats have hotspot positions.
236
237       "-zlib_compression" (integer -1 to 9, or "undef")
238           The compression level for images which use Zlib, such as PNG.  0 is
239           no compression, 9 is maximum compression.  -1 is the Zlib compiled-
240           in default (usually 6).  "undef" means no setting to use an image
241           library default if it has one, or the Zlib default.
242
243           For reference, PNG format doesn't record the compression level used
244           in the file, so for it "-zlib_compression" can be set() to control
245           a save(), but generally won't read back from a load().
246
247       "-quality_percent" (integer 0 to 100, or "undef")
248           The quality level for saving lossy image formats such as JPEG.  0
249           is the worst quality, 100 is the best.  Lower quality should mean a
250           smaller file, but fuzzier.  "undef" means no setting which gives
251           some image library default.
252

ALGORITHMS

254   Lines
255       Sloping lines are drawn by a basic Bressenham line drawing algorithm
256       with integer-only calculations.  It ends up drawing the same set of
257       pixels no matter which way around the two endpoints are passed.
258
259       Would there be merit in rounding odd numbers of pixels according to
260       which way around line ends are given?  Eg. a line 0,0 to 4,1 might do 2
261       pixels on y=0 and 3 on y=1, but 4,1 to 0,0 the other way around.  Or
262       better to have consistency either way around?  For reference, in the
263       X11 drawing model the order of the ends doesn't matter for "wide"
264       lines, but for implementation-dependent "thin" lines it's only
265       encouraged, not required.
266
267   Ellipses
268       Ellipses are drawn with the midpoint ellipse algorithm.  This algorithm
269       chooses between points x,y or x,y-1 according to whether the position
270       x,y-0.5 is inside or outside the ellipse (and similarly x+0.5,y on the
271       vertical parts).
272
273       The current ellipse code ends up with 0.5's in the values, which means
274       floating point, but is still exact since binary fractions like 0.5 are
275       exactly representable.  Some rearrangement and factors of 2 could make
276       it all-integer.  The "discriminator" in the calculation may exceed
277       53-bits of float mantissa at around 160,000 pixels wide or high.  That
278       might affect the accuracy of the pixels chosen, but should be no worse
279       than that.
280
281   Diamond
282       The current code draws a diamond with the Bressenham line algorithm
283       along each side.  Just one line is calculated and is then replicated to
284       the four sides, which ensures the result is symmetric.  Rounding in the
285       line (when width not a multiple or height, or vice versa) is biased
286       towards making the pointier vertices narrower.  That tends to look
287       better, especially when the diamond is small.
288
289   Image Libraries
290       The subclasses like GD or PNGwriter which are front-ends to other
291       drawing libraries don't necessarily use these base algorithms, but can
292       be expected to something sensible within the given line endpoints or
293       ellipse bounding box.  (Among the image libraries it's surprising how
294       variable the quality of the ellipse drawing is.)
295

AUTHOR

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

COPYRIGHT

322       Copyright (c) Mark Summerfield 2000. All Rights Reserved.
323
324       Copyright (c) Kevin Ryde 2010, 2011, 2012.
325
326       This module may be used/distributed/modified under the LGPL.
327
328
329
330perl v5.36.0                      2023-01-20                    Image::Base(3)