1Xpm(3)                User Contributed Perl Documentation               Xpm(3)
2
3
4

NAME

6       Image::Xpm - Load, create, manipulate and save xpm image files.
7

SYNOPSIS

9           use Image::Xpm;
10
11           my $j = Image::Xpm->new(-file, 'Camel.xpm');
12
13           my $i = Image::Xpm->new(-width => 10, -height => 16);
14
15           my $h = $i->new; # Copy of $i
16
17           $i->xy(5, 8, 'red');       # Set a colour (& add to palette if necessary)
18           print $i->xy(9, 3);        # Get a colour
19
20           $i->xy(120, 130, '#1256DD');
21           $i->xy(120, 130, $i->rgb2colour(66, 0x4D, 31));
22
23           $i->vec(24, '#808080');    # Set a colour using a vector offset
24           print $i->vec(24);         # Get a colour using a vector offset
25
26           print $i->get(-width);     # Get and set object attributes
27           $i->set(-height, 15);
28
29           $i->load('test.xpm');
30           $i->save;
31
32           # Changing just the palette
33           $i->add_colours(qw(red green blue #123456 #C0C0C0));
34           $i->del_colour('blue');
35

DESCRIPTION

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
43   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
48       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
52       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
57       "-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
62       "-width"
63           The width of the image; taken from the file or set when the object
64           is created; read-only.
65
66       "-height"
67           The height of the image; taken from the file or set when the object
68           is created; read-only.
69
70       "-cpp"
71           Characters per pixel. Commonly 1 or 2, default is 1 for images
72           created by the module; read-only.
73
74           See the example for how to change an image's cpp.
75
76       "-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
80       "-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
84       "-ncolours"
85           The number of unique colours in the palette. The image may not be
86           using all of them; read-only.
87
88       "-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
96       "-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
104       "-pixels"
105           A string of palette names which constitutes the data for the image
106           itself; read-only.
107
108       "-extname"
109           The name of the extension text if any; commonly XPMEXT; read-only.
110
111       "-extlines"
112           The lines of text of any extensions; read-only.
113
114       "-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
119   get()
120           my $width = $i->get(-width);
121           my ($hotx, $hoty) = $i->get(-hotx, -hoty);
122
123       Get any of the object's attributes. Multiple attributes may be
124       requested in a single call.
125
126       See "xy" and "vec" to get/set colours of the image itself.
127
128   set()
129           $i->set(-hotx => 120, -hoty => 32);
130
131       Set any of the object's attributes. Multiple attributes may be set in a
132       single call; some attributes are read-only.
133
134       See "xy" and "vec" to get/set colours of the image itself.
135
136   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
140       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
143       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
147           $colour = xy($x, $y);            # e.g. #123456
148           $cc     = xy($x, $y, $colour);   # e.g. !
149
150       We don't normally pick up the return value when setting the colour.
151
152   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
156       Get/set bits using vector offsets; offsets start at 0. The offset of a
157       pixel is ((y * width * cpp) + (x * cpp)).
158
159       The sort of return value depends on whether we are reading (getting) or
160       writing (setting) the colour - see "xy" for an explanation.
161
162   rgb2colour() and rgb2color()
163           $i->rgb2colour(0xff, 0x40, 0x80);    # Returns #ff4080
164           Image::Xpm->rgb2colour(10, 20, 30);  # Returns #0a141e
165
166       Convenience class or object methods which accept three integers and
167       return a colour name string.
168
169   load()
170           $i->load;
171           $i->load('test.xpm');
172
173       Load the image whose name is given, or if none is given load the image
174       whose name is in the "-file" attribute.
175
176   save()
177           $i->save;
178           $i->save('test.xpm');
179
180       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
184   add_colours() and add_colors()
185           $i->add_colours(qw(#C0C0DD red blue #123456));
186
187       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
190       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
194       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
198   del_colour() and del_color()
199           $i->del_colour('green');
200
201       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

EXAMPLE

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
212           # Could have written 2nd line above as:
213           my $j = $i->new_from_image(ref $i, -cpp => 2);
214

AUTHOR

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
222       This module may be used/distributed/modified under the GPL.
223
224
225
226perl v5.34.0                      2021-07-22                            Xpm(3)
Impressum