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
213       subclasses, but 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
224           "save()".
225
226       "-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
231       "-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
238       "-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
244           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
248       "-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

ALGORITHMS

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
260       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
268   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
274       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
282   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
290   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

SEE ALSO

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
303       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
307       Image::Base::Prima::Drawable, Image::Base::Prima::Image
308
309       Image::Base::Tk::Canvas, Image::Base::Tk::Photo
310
311       Image::Base::Wx::Bitmap, Image::Base::Wx::DC, Image::Base::Wx::Image
312
313       Image::Base::X11::Protocol::Drawable,
314       Image::Base::X11::Protocol::Pixmap, Image::Base::X11::Protocol::Window
315
316       "http://user42.tuxfamily.org/image-base/index.html"
317

AUTHOR

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
325       Copyright (c) Kevin Ryde 2010, 2011, 2012.
326
327       This module may be used/distributed/modified under the LGPL.
328
329
330
331perl v5.28.0                      2012-08-01                    Image::Base(3)
Impressum