1Image::Base(3) User Contributed Perl Documentation Image::Base(3)
2
6 Image::Base - base class for loading, manipulating and saving images.
7
9 # base class only
10 package My::Image::Class;
11 use base 'Image::Base';
12
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 use Image::Xpm ;
19 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 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 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 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 # Filename: mylibrary.pl
42 package Image::Base ; # Switch to this class to build on it.
43 sub mytransform {
45 my $self = shift ;
46 my $class = ref( $self ) || $self ;
47 # Perform your transformation here; might be drawing a line or filling
49 # a rectangle or whatever... getting/setting pixels using $self->xy().
50 }
51 package main ; # Switch back to the default package.
53 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
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 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 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 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 line()
76 $i->line( $x0, $y0, $x1, $y1, $colour ) ;
77 Draw a line from point ($x0,$y0) to point ($x1,$y1) in colour $colour.
79 ***
81 *****
82 ****
83 ***
84 ellipse()
86 $i->ellipse( $x0, $y0, $x1, $y1, $colour ) ;
87 $i->ellipse( $x0, $y0, $x1, $y1, $colour, $fill ) ;
88 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 *********
94 ** **
95 * *
96 ** **
97 *********
98 rectangle()
100 $i->rectangle( $x0, $y0, $x1, $y1, $colour ) ;
101 $i->rectangle( $x0, $y0, $x1, $y1, $colour, $fill ) ;
102 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 ***************
108 * *
109 * *
110 * *
111 ***************
112 diamond()
114 $i->diamond( $x0, $y0, $x1, $y1, $colour ) ;
115 $i->diamond( $x0, $y0, $x1, $y1, $colour, $fill ) ;
116 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 ***
122 **** ****
123 *** ***
124 **** ****
125 ***
126 new()
128 Virtual - must be overridden.
129 Recommend that it at least supports "-file" (filename), "-width" and
131 "-height".
132 new_from_serialised()
134 Not implemented. Recommended for inheritors. Should accept a string
135 serialised using serialise() and return an object (reference).
136 serialise()
138 Not implemented. Recommended for inheritors. Should return a string
139 representation (ideally compressed).
140 get()
142 my $width = $i->get( -width ) ;
143 my( $hotx, $hoty ) = $i->get( -hotx, -hoty ) ;
144 Get any of the object's attributes. Multiple attributes may be
146 requested in a single call.
147 See "xy" get/set colours of the image itself.
149 set()
151 Virtual - must be overridden.
152 Set any of the object's attributes. Multiple attributes may be set in a
154 single call; some attributes are read-only.
155 See "xy" get/set colours of the image itself.
157 xy()
159 Virtual - must be overridden. Expected to provide the following
160 functionality:
161 $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 Get/set colours using x, y coordinates; coordinates start at 0.
166 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 $colour = xy( $x, $y ) ; # e.g. #123456
172 xy( $x, $y, $colour ) ; # Return value is class specific
173 We don't normally pick up the return value when setting the colour.
175 load()
177 Virtual - must be overridden. Expected to provide the following
178 functionality:
179 $i->load ;
181 $i->load( 'test.xpm' ) ;
182 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 save()
187 Virtual - must be overridden. Expected to provide the following
188 functionality:
189 $i->save ;
191 $i->save( 'test.xpm' ) ;
192 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 The save format depends on the "Image::Base" subclass. Some implement
197 a "-file_format" attribute if multiple formats can be saved.
198 add_colours()
200 Add colours to the image palette, if applicable.
201 $i->add_colours( $name, $name, ...)
203 The drawing functions add colours as necessary, so this is just a way
205 to pre-load the palette.
206 "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
212 The attributes for "new()", "get()" and "set()" are up to the
213 subclasses, but the common settings, when available, include
214 "-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 "-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
224 "save()".
225 "-file_format" (string)
227 The name of the file format loaded or to save as. This is
228 generally an abbreviation like "XPM", set by "load()" or "set()"
229 and then used by "save()".
230 "-hotx" (integers, or maybe -1 or maybe "undef")
232 "-hoty"
233 The coordinates of the "hotspot" position. Images which can be a
234 mouse cursor or similar have a position within the image which is
235 the active pixel for clicking etc. For example XPM and CUR (cursor
236 form of ICO) formats have hotspot positions.
237 "-zlib_compression" (integer -1 to 9, or "undef")
239 The compression level for images which use Zlib, such as PNG. 0 is
240 no compression, 9 is maximum compression. -1 is the Zlib compiled-
241 in default (usually 6). "undef" means no setting to use an image
242 library default if it has one, or the Zlib default.
243 For reference, PNG format doesn't record the compression level used
245 in the file, so for it "-zlib_compression" can be "set()" to
246 control a "save()", but generally won't read back from a "load()".
247 "-quality_percent" (integer 0 to 100, or "undef")
249 The quality level for saving lossy image formats such as JPEG. 0
250 is the worst quality, 100 is the best. Lower quality should mean a
251 smaller file, but fuzzier. "undef" means no setting which gives
252 some image library default.
253
255 Lines
256 Sloping lines are drawn by a basic Bressenham line drawing algorithm
257 with integer-only calculations. It ends up drawing the same set of
258 pixels no matter which way around the two endpoints are passed.
259 Would there be merit in rounding odd numbers of pixels according to
261 which way around line ends are given? Eg. a line 0,0 to 4,1 might do 2
262 pixels on y=0 and 3 on y=1, but 4,1 to 0,0 the other way around. Or
263 better to have consistency either way around? For reference, in the
264 X11 drawing model the order of the ends doesn't matter for "wide"
265 lines, but for implementation-dependent "thin" lines it's only
266 encouraged, not required.
267 Ellipses
269 Ellipses are drawn with the midpoint ellipse algorithm. This algorithm
270 chooses between points x,y or x,y-1 according to whether the position
271 x,y-0.5 is inside or outside the ellipse (and similarly x+0.5,y on the
272 vertical parts).
273 The current ellipse code ends up with 0.5's in the values, which means
275 floating point, but is still exact since binary fractions like 0.5 are
276 exactly representable. Some rearrangement and factors of 2 could make
277 it all-integer. The "discriminator" in the calculation may exceed
278 53-bits of float mantissa at around 160,000 pixels wide or high. That
279 might affect the accuracy of the pixels chosen, but should be no worse
280 than that.
281 Diamond
283 The current code draws a diamond with the Bressenham line algorithm
284 along each side. Just one line is calculated and is then replicated to
285 the four sides, which ensures the result is symmetric. Rounding in the
286 line (when width not a multiple or height, or vice versa) is biased
287 towards making the pointier vertices narrower. That tends to look
288 better, especially when the diamond is small.
289 Image Libraries
291 The subclasses like GD or PNGwriter which are front-ends to other
292 drawing libraries don't necessarily use these base algorithms, but can
293 be expected to something sensible within the given line endpoints or
294 ellipse bounding box. (Among the image libraries it's surprising how
295 variable the quality of the ellipse drawing is.)
296
298 Image::Xpm, Image::Xbm, Image::Pbm, Image::Base::GD,
299 Image::Base::Imager, Image::Base::Imlib2, Image::Base::Magick,
300 Image::Base::PNGwriter, Image::Base::SVG, Image::Base::SVGout,
301 Image::Base::Text, Image::Base::Multiplex
302 Image::Base::Gtk2::Gdk::Drawable, Image::Base::Gtk2::Gdk::Image,
304 Image::Base::Gtk2::Gdk::Pixbuf, Image::Base::Gtk2::Gdk::Pixmap,
305 Image::Base::Gtk2::Gdk::Window
306 Image::Base::Prima::Drawable, Image::Base::Prima::Image
308 Image::Base::Tk::Canvas, Image::Base::Tk::Photo
310 Image::Base::Wx::Bitmap, Image::Base::Wx::DC, Image::Base::Wx::Image
312 Image::Base::X11::Protocol::Drawable,
314 Image::Base::X11::Protocol::Pixmap, Image::Base::X11::Protocol::Window
315 "http://user42.tuxfamily.org/image-base/index.html"
317
319 Mark Summerfield. I can be contacted as <summer@perlpress.com> - please
320 include the word 'imagebase' in the subject line.
321
323 Copyright (c) Mark Summerfield 2000. All Rights Reserved.
324 Copyright (c) Kevin Ryde 2010, 2011, 2012.
326 This module may be used/distributed/modified under the LGPL.
328perl v5.32.0 2020-07-28 Image::Base(3)