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
38 functionality for the xpm file format. It inherits from "Image::Base"
39 which provides additional manipulation functionality, e.g.
40 new_from_image(). See the "Image::Base" pod for information on adding
41 your own functionality to all the Image::Base derived classes.
42 new()
44 my $i = Image::Xpm->new(-file => 'test.xpm');
45 my $j = Image::Xpm->new(-width => 12, -height => 18);
46 my $k = $i->new;
47 We can create a new xpm image by reading in a file, or by creating an
49 image from scratch (all the pixels are white by default), or by copying
50 an image object that we created earlier.
51 If we set "-file" then all the other arguments are ignored (since
53 they're taken from the file). If we don't specify a file, "-width" and
54 "-height" are mandatory and "-cpp" will default to 1 unless specified
55 otherwise.
56 "-file"
58 The name of the file to read when creating the image. May contain a
59 full path. This is also the default name used for "load"ing and
60 "save"ing, though it can be overridden when you load or save.
61 "-width"
63 The width of the image; taken from the file or set when the object
64 is created; read-only.
65 "-height"
67 The height of the image; taken from the file or set when the object
68 is created; read-only.
69 "-cpp"
71 Characters per pixel. Commonly 1 or 2, default is 1 for images
72 created by the module; read-only.
73 See the example for how to change an image's cpp.
75 "-hotx"
77 The x-coord of the image's hotspot; taken from the file or set when
78 the object is created. Set to -1 if there is no hotspot.
79 "-hoty"
81 The y-coord of the image's hotspot; taken from the file or set when
82 the object is created. Set to -1 if there is no hotspot.
83 "-ncolours"
85 The number of unique colours in the palette. The image may not be
86 using all of them; read-only.
87 "-cindex"
89 An hash whose keys are colour names, e.g. '#123456' or 'blue' and
90 whose values are the palette names, e.g. ' ', '#', etc; read-only.
91 If you want to add more colours to the image itself simply write
92 pixels with the new colours using "xy"; if you want to add more
93 colours to the palette without necessarily using them in the image
94 use "add_colours".
95 "-palette"
97 A hash whose keys are the palette names, e.g. ' ', '#', etc. and
98 whose values are hashes of colour type x colour name pairs, e.g. "c
99 => red", etc; read-only. If you want to add more colours to the
100 image itself simply write pixels with the new colours using "xy";
101 if you want to add more colours to the palette without necessarily
102 using them in the image use "add_colours".
103 "-pixels"
105 A string of palette names which constitutes the data for the image
106 itself; read-only.
107 "-extname"
109 The name of the extension text if any; commonly XPMEXT; read-only.
110 "-extlines"
112 The lines of text of any extensions; read-only.
113 "-comments"
115 An array (possibly empty) of comment lines that were in a file that
116 was read in; they will be written out although we make no guarantee
117 regarding their placement; read-only.
118 get()
120 my $width = $i->get(-width);
121 my ($hotx, $hoty) = $i->get(-hotx, -hoty);
122 Get any of the object's attributes. Multiple attributes may be
124 requested in a single call.
125 See "xy" and "vec" to get/set colours of the image itself.
127 set()
129 $i->set(-hotx => 120, -hoty => 32);
130 Set any of the object's attributes. Multiple attributes may be set in a
132 single call; some attributes are read-only.
133 See "xy" and "vec" to get/set colours of the image itself.
135 xy()
137 $i->xy(4, 11, '#123454'); # Set the colour at point 4,11
138 my $v = $i->xy(9, 17); # Get the colour at point 9,17
139 Get/set colours using x, y coordinates; coordinates start at 0. If the
141 colour does not exist in the palette it will be added automatically.
142 When called to set the colour the value returned is characters used for
144 that colour in the palette; when called to get the colour the value
145 returned is the colour name, e.g. 'blue' or '#f0f0f0', etc, e.g.
146 $colour = xy($x, $y); # e.g. #123456
148 $cc = xy($x, $y, $colour); # e.g. !
149 We don't normally pick up the return value when setting the colour.
151 vec()
153 $i->vec(43, 0); # Unset the bit at offset 43
154 my $v = $i->vec(87); # Get the bit at offset 87
155 Get/set bits using vector offsets; offsets start at 0. The offset of a
157 pixel is ((y * width * cpp) + (x * cpp)).
158 The sort of return value depends on whether we are reading (getting) or
160 writing (setting) the colour - see "xy" for an explanation.
161 rgb2colour() and rgb2color()
163 $i->rgb2colour(0xff, 0x40, 0x80); # Returns #ff4080
164 Image::Xpm->rgb2colour(10, 20, 30); # Returns #0a141e
165 Convenience class or object methods which accept three integers and
167 return a colour name string.
168 load()
170 $i->load;
171 $i->load('test.xpm');
172 Load the image whose name is given, or if none is given load the image
174 whose name is in the "-file" attribute.
175 save()
177 $i->save;
178 $i->save('test.xpm');
179 Save the image using the name given, or if none is given save the image
181 using the name in the "-file" attribute. The image is saved in xpm
182 format.
183 add_colours() and add_colors()
185 $i->add_colours(qw(#C0C0DD red blue #123456));
186 These are for adding colours to the palette; you don't need to use them
188 to set a pixel's colour - use "xy" for that.
189 Add one or more colour names either as hex strings or as literal colour
191 names. These are always added as type 'c' colours; duplicates are
192 ignored.
193 NB If you just want to set some pixels in colours that may not be in
195 the palette, simply do so using "xy" since new colours are added
196 automatically.
197 del_colour() and del_color()
199 $i->del_colour('green');
200 Delete a colour from the palette; returns undef if the colour isn't in
202 the palette, false (0) if the colour is in the palette but also in the
203 image, or true (1) if the colour has been deleted (i.e. it was in the
204 palette but not in use in the image).
205
207 Changing the -cpp of an image:
208 my $i = Image::Xpm(-file => 'test1.xpm'); # test1.xpm has cpp == 1
209 my $j = $i->new_from_image('Image::xpm', -cpp => 2);
210 $j->save('test2.xpm');
211 # Could have written 2nd line above as:
213 my $j = $i->new_from_image(ref $i, -cpp => 2);
214
216 Mark Summerfield. I can be contacted as <summer@perlpress.com> - please
217 include the word 'xpm' in the subject line.
218
220 Copyright (c) Mark Summerfield 2000. All Rights Reserved.
221 This module may be used/distributed/modified under the GPL.
223perl v5.38.0 2023-07-20 Xpm(3)