1Xpm(3) User Contributed Perl Documentation Xpm(3)
2
6 Image::Xpm - Load, create, manipulate and save xpm image files.
7
9 use Image::Xpm;
10 my $j = Image::Xpm->new(-file, 'Camel.xpm');
12 my $i = Image::Xpm->new(-width => 10, -height => 16);
14 my $h = $i->new; # Copy of $i
16 $i->xy(5, 8, 'red'); # Set a colour (& add to palette if necessary)
18 print $i->xy(9, 3); # Get a colour
19 $i->xy(120, 130, '#1256DD');
21 $i->xy(120, 130, $i->rgb2colour(66, 0x4D, 31));
22 $i->vec(24, '#808080'); # Set a colour using a vector offset
24 print $i->vec(24); # Get a colour using a vector offset
25 print $i->get(-width); # Get and set object attributes
27 $i->set(-height, 15);
28 $i->load('test.xpm');
30 $i->save;
31 # Changing just the palette
33 $i->add_colours(qw(red green blue #123456 #C0C0C0));
34 $i->del_colour('blue');
35
37 This class module provides basic load, manipulate and save functional‐
38 ity for the xpm file format. It inherits from "Image::Base" which pro‐
39 vides additional manipulation functionality, e.g. "new_from_image()".
40 See the "Image::Base" pod for information on adding your own function‐
41 ality to all the Image::Base derived classes.
42 new()
44 my $i = Image::Xpm->new(-file => 'test.xpm');
46 my $j = Image::Xpm->new(-width => 12, -height => 18);
47 my $k = $i->new;
48 We can create a new xpm image by reading in a file, or by creating an
50 image from scratch (all the pixels are white by default), or by copying
51 an image object that we created earlier.
52 If we set "-file" then all the other arguments are ignored (since
54 they're taken from the file). If we don't specify a file, "-width" and
55 "-height" are mandatory and "-cpp" will default to 1 unless specified
56 otherwise.
57 "-file"
59 The name of the file to read when creating the image. May contain a
60 full path. This is also the default name used for "load"ing and
61 "save"ing, though it can be overridden when you load or save.
62 "-width"
64 The width of the image; taken from the file or set when the object
65 is created; read-only.
66 "-height"
68 The height of the image; taken from the file or set when the object
69 is created; read-only.
70 "-cpp"
72 Characters per pixel. Commonly 1 or 2, default is 1 for images cre‐
73 ated by the module; read-only.
74 See the example for how to change an image's cpp.
76 "-hotx"
78 The x-coord of the image's hotspot; taken from the file or set when
79 the object is created. Set to -1 if there is no hotspot.
80 "-hoty"
82 The y-coord of the image's hotspot; taken from the file or set when
83 the object is created. Set to -1 if there is no hotspot.
84 "-ncolours"
86 The number of unique colours in the palette. The image may not be
87 using all of them; read-only.
88 "-cindex"
90 An hash whose keys are colour names, e.g. '#123456' or 'blue' and
91 whose values are the palette names, e.g. ' ', '#', etc; read-only.
92 If you want to add more colours to the image itself simply write
93 pixels with the new colours using "xy"; if you want to add more
94 colours to the palette without necessarily using them in the image
95 use "add_colours".
96 "-palette"
98 A hash whose keys are the palette names, e.g. ' ', '#', etc. and
99 whose values are hashes of colour type x colour name pairs, e.g. "c
100 => red", etc; read-only. If you want to add more colours to the
101 image itself simply write pixels with the new colours using "xy";
102 if you want to add more colours to the palette without necessarily
103 using them in the image use "add_colours".
104 "-pixels"
106 A string of palette names which constitutes the data for the image
107 itself; read-only.
108 "-extname"
110 The name of the extension text if any; commonly XPMEXT; read-only.
111 "-extlines"
113 The lines of text of any extensions; read-only.
114 "-comments"
116 An array (possibly empty) of comment lines that were in a file that
117 was read in; they will be written out although we make no guarantee
118 regarding their placement; read-only.
119 get()
121 my $width = $i->get(-width);
123 my ($hotx, $hoty) = $i->get(-hotx, -hoty);
124 Get any of the object's attributes. Multiple attributes may be
126 requested in a single call.
127 See "xy" and "vec" to get/set colours of the image itself.
129 set()
131 $i->set(-hotx => 120, -hoty => 32);
133 Set any of the object's attributes. Multiple attributes may be set in a
135 single call; some attributes are read-only.
136 See "xy" and "vec" to get/set colours of the image itself.
138 xy()
140 $i->xy(4, 11, '#123454'); # Set the colour at point 4,11
142 my $v = $i->xy(9, 17); # Get the colour at point 9,17
143 Get/set colours using x, y coordinates; coordinates start at 0. If the
145 colour does not exist in the palette it will be added automatically.
146 When called to set the colour the value returned is characters used for
148 that colour in the palette; when called to get the colour the value
149 returned is the colour name, e.g. 'blue' or '#f0f0f0', etc, e.g.
150 $colour = xy($x, $y); # e.g. #123456
152 $cc = xy($x, $y, $colour); # e.g. !
153 We don't normally pick up the return value when setting the colour.
155 vec()
157 $i->vec(43, 0); # Unset the bit at offset 43
159 my $v = $i->vec(87); # Get the bit at offset 87
160 Get/set bits using vector offsets; offsets start at 0. The offset of a
162 pixel is ((y * width * cpp) + (x * cpp)).
163 The sort of return value depends on whether we are reading (getting) or
165 writing (setting) the colour - see "xy" for an explanation.
166 rgb2colour() and rgb2color()
168 $i->rgb2colour(0xff, 0x40, 0x80); # Returns #ff4080
170 Image::Xpm->rgb2colour(10, 20, 30); # Returns #0a141e
171 Convenience class or object methods which accept three integers and
173 return a colour name string.
174 load()
176 $i->load;
178 $i->load('test.xpm');
179 Load the image whose name is given, or if none is given load the image
181 whose name is in the "-file" attribute.
182 save()
184 $i->save;
186 $i->save('test.xpm');
187 Save the image using the name given, or if none is given save the image
189 using the name in the "-file" attribute. The image is saved in xpm for‐
190 mat.
191 add_colours() and add_colors()
193 $i->add_colours(qw(#C0C0DD red blue #123456));
195 These are for adding colours to the palette; you don't need to use them
197 to set a pixel's colour - use "xy" for that.
198 Add one or more colour names either as hex strings or as literal colour
200 names. These are always added as type 'c' colours; duplicates are
201 ignored.
202 NB If you just want to set some pixels in colours that may not be in
204 the palette, simply do so using "xy" since new colours are added auto‐
205 matically.
206 del_colour() and del_color()
208 $i->del_colour('green');
210 Delete a colour from the palette; returns undef if the colour isn't in
212 the palette, false (0) if the colour is in the palette but also in the
213 image, or true (1) if the colour has been deleted (i.e. it was in the
214 palette but not in use in the image).
215
217 Changing the -cpp of an image:
218 my $i = Image::Xpm(-file => 'test1.xpm'); # test1.xpm has cpp == 1
220 my $j = $i->new_from_image('Image::xpm', -cpp => 2);
221 $j->save('test2.xpm');
222 # Could have written 2nd line above as:
224 my $j = $i->new_from_image(ref $i, -cpp => 2);
225
227 2000/11/09
228 Added Jerrad Pierce's patch to allow load() to accept filehandles or
230 strings; will document in next release.
231 2000/10/19
233 Fixed bugs in xy() and vec() reported by Pat Gunn.
235 2000/05/25
237 Fixed a bug in the test file; fixed a bug in save() which affected xpm
239 extensions.
240 2000/05/04
242 Fixed bugs in xy(), vec(), save() and load(). Improved the test pro‐
244 gram.
245 2000/05/03
247 Created.
249
251 Mark Summerfield. I can be contacted as <summer@perlpress.com> - please
252 include the word 'xpm' in the subject line.
253
255 Copyright (c) Mark Summerfield 2000. All Rights Reserved.
256 This module may be used/distributed/modified under the GPL.
258perl v5.8.8 2000-11-09 Xpm(3)