1Xbm(3) User Contributed Perl Documentation Xbm(3)
2
6 Image::Xbm - Load, create, manipulate and save xbm image files.
7
9 use Image::Xbm ;
10 my $j = Image::Xbm->new( -file, 'balArrow.xbm' ) ;
12 my $i = Image::Xbm->new( -width => 10, -height => 16 ) ;
14 my $h = $i->new ; # Copy of $i
16 my $p = Image::Xbm->new_from_string( "###\n#-#\n###" ) ;
18 my $q = $p->new_from_string( "H##", "#-#", "###" ) ;
20 my $s = $q->serialse ; # Compresses a little too.
22 my $t = Image::Xbm->new_from_serialsed( $s ) ;
23 $i->xybit( 5, 8, 1 ) ; # Set a bit
25 print '1' if $i->xybit( 9, 3 ) ; # Get a bit
26 print $i->xy( 4, 5 ) ; # Will print black or white
27 $i->vec( 24, 0 ) ; # Set a bit using a vector offset
29 print '1' if $i->vec( 24 ) ; # Get a bit using a vector offset
30 print $i->get( -width ) ; # Get and set object and class attributes
32 $i->set( -height, 15 ) ;
33 $i->load( 'test.xbm' ) ;
35 $i->save ;
36 print "equal\n" if $i->is_equal( $j ) ;
38 print $j->as_string ;
40 #####-
42 ###---
43 ###---
44 #--#--
45 #---#-
46 -----#
47 print $j->as_binstring ;
49 1111101110001110001001001000100000010000
51 View an xbm file from the command line:
53 % perl -MImage::Xbm -e'print Image::Xbm->new(-file,shift)->as_string' file
55 Create an xbm file from the command line:
57 % perl -MImage::Xbm -e'Image::Xbm->new_from_string("###\n#-#\n-#-")->save("test.xbm")'
59
61 This class module provides basic load, manipulate and save functional‐
62 ity for the xbm file format. It inherits from "Image::Base" which pro‐
63 vides additional manipulation functionality, e.g. "new_from_image()".
64 See the "Image::Base" pod for information on adding your own function‐
65 ality to all the "Image::Base" derived classes.
66 new()
68 my $i = Image::Xbm->new( -file => 'test.xbm' ) ;
70 my $j = Image::Xbm->new( -width => 12, -height => 18 ) ;
71 my $k = $i->new ;
72 We can create a new xbm image by reading in a file, or by creating an
74 image from scratch (all the bits are unset by default), or by copying
75 an image object that we created earlier.
76 If we set "-file" then all the other arguments are ignored (since
78 they're taken from the file). If we don't specify a file, "-width" and
79 "-height" are mandatory.
80 "-file"
82 The name of the file to read when creating the image. May contain a
83 full path. This is also the default name used for "load"ing and
84 "save"ing, though it can be overridden when you load or save.
85 "-width"
87 The width of the image; taken from the file or set when the object
88 is created; read-only.
89 "-height"
91 The height of the image; taken from the file or set when the object
92 is created; read-only.
93 "-hotx"
95 The x-coord of the image's hotspot; taken from the file or set when
96 the object is created. Set to -1 if there is no hotspot.
97 "-hoty"
99 The y-coord of the image's hotspot; taken from the file or set when
100 the object is created. Set to -1 if there is no hotspot.
101 "-bits"
103 The bit vector that stores the image; read-only.
104 new_from_string()
106 my $p = Image::Xbm->new_from_string( "###\n#-#\n###" ) ;
108 my $q = $p->new_from_string( "H##", "#-#", "###" ) ;
109 my $r = $p->new_from_string( $p->as_string ) ;
110 Create a new bitmap from a string or from an array or list of strings.
112 If you want to use different characters you can:
113 Image::Xbm->set( -setch => 'X', -unsetch => ' ' ) ;
115 my $s = $p->new_from_string( "XXX", "X X", "XhX" ) ;
116 You can also specify a hotspot by making one of the characters a 'H'
118 (set bit hotspot) or 'h' (unset bit hotspot) -- you can use different
119 characters by setting "-sethotch" and "-unsethotch" respectively.
120 new_from_serialised()
122 my $i = Image::Xbm->new_from_serialised( $s ) ;
124 Creates an image from a string created with the "serialse()" method.
126 Since such strings are a little more compressed than xbm files or
127 Image::Xbm objects they might be useful if storing a lot of bitmaps, or
128 for transferring bitmaps over comms links.
129 serialise()
131 my $s = $i->serialise ;
133 Creates a string version of the image which can be completed recreated
135 using the "new_from_serialised" method.
136 get()
138 my $width = $i->get( -width ) ;
140 my( $hotx, $hoty ) = $i->get( -hotx, -hoty ) ;
141 Get any of the object's attributes. Multiple attributes may be
143 requested in a single call.
144 See "xy" and "vec" to get/set bits of the image itself.
146 set()
148 $i->set( -hotx => 120, -hoty => 32 ) ;
150 Set any of the object's attributes. Multiple attributes may be set in a
152 single call. Except for "-setch" and "-unsetch" all attributes are
153 object attributes; some attributes are read-only.
154 See "xy" and "vec" to get/set bits of the image itself.
156 class attributes
158 Image::Xbm->set( -setch => 'X' ) ;
160 $i->set( -setch => '@', -unsetch => '*' ) ;
161 "-setch"
163 The character to print set bits as when using "as_string", default
164 is '#'. This is a class attribute accessible from the class or an
165 object via "get" and "set".
166 "-unsetch"
168 The character to print set bits as when using "as_string", default
169 is '-'. This is a class attribute accessible from the class or an
170 object via "get" and "set".
171 "-sethotch"
173 The character to print set bits as when using "as_string", default
174 is 'H'. This is a class attribute accessible from the class or an
175 object via "get" and "set".
176 "-unsethotch"
178 The character to print set bits as when using "as_string", default
179 is 'h'. This is a class attribute accessible from the class or an
180 object via "get" and "set".
181 xybit()
183 $i->xy( 4, 11, 1 ) ; # Set the bit at point 4,11
185 my $v = $i->xy( 9, 17 ) ; # Get the bit at point 9,17
186 Get/set bits using x, y coordinates; coordinates start at 0.
188 xy()
190 $i->xy( 4, 11, 'black' ) ; # Set the bit from a colour at point 4,11
192 my $v = $i->xy( 9, 17 ) ; # Get the bit as a colour at point 9,17
193 Get/set bits using colours using x, y coordinates; coordinates start at
195 0.
196 If set with a colour of 'black' or a numeric value > 0 or a string not
198 matching /^#0+$/ then the bit will be set, otherwise it will be
199 cleared.
200 If you get a colour you will always get 'black' or 'white'.
202 vec()
204 $i->vec( 43, 0 ) ; # Unset the bit at offset 43
206 my $v = $i->vec( 87 ) ; # Get the bit at offset 87
207 Get/set bits using vector offsets; offsets start at 0.
209 load()
211 $i->load ;
213 $i->load( 'test.xbm' ) ;
214 Load the image whose name is given, or if none is given load the image
216 whose name is in the "-file" attribute.
217 save()
219 $i->save ;
221 $i->save( 'test.xbm' ) ;
222 Save the image using the name given, or if none is given save the image
224 using the name in the "-file" attribute. The image is saved in xbm for‐
225 mat, e.g.
226 #define test_width 6
228 #define test_height 6
229 static unsigned char test_bits[] = {
230 0x1f, 0x07, 0x07, 0x09, 0x11, 0x20 } ;
231 is_equal()
233 print "equal\n" if $i->is_equal( $j ) ;
235 Returns true (1) if the images are equal, false (0) otherwise. Note
237 that hotspots and filenames are ignored, so we compare width, height
238 and the actual bits only.
239 as_string()
241 print $i->as_string ;
243 Returns the image as a string, e.g.
245 #####-
247 ###---
248 ###---
249 #--#--
250 #---#-
251 -----#
252 The characters used may be changed by "set"ting the "-setch" and
254 "-unsetch" characters. If you give "as_string" a parameter it will
255 print out the hotspot if present using "-sethotch" or "-unsethotch" as
256 appropriate, e.g.
257 print $n->as_string( 1 ) ;
259 H##
261 #-#
262 ###
263 as_binstring()
265 print $i->as_binstring ;
267 Returns the image as a string of 0's and 1's, e.g.
269 1111101110001110001001001000100000010000
271
273 2000/11/09
274 Added Jerrad Pierce's patch to allow load() to accept filehandles or
276 strings; will document in next release.
277 2000/05/05
279 Added new_from_serialised() and serialise() methods.
281 2000/05/04
283 Made xy() compatible with Image::Base, use xybit() for the earlier
285 functionality.
286 2000/05/01
288 Improved speed of vec(), xy() and as_string().
290 Tried use integer to improve speed but according to Benchmark it made
292 the code slower so I dropped it; interestingly perl 5.6.0 was around
293 25% slower than perl 5.004 with and without use integer.
294 2000/04/30
296 Created.
298
300 Mark Summerfield. I can be contacted as <summer@perlpress.com> - please
301 include the word 'xbm' in the subject line.
302
304 Copyright (c) Mark Summerfield 2000. All Rights Reserved.
305 This module may be used/distributed/modified under the LGPL.
307perl v5.8.8 2000-11-09 Xbm(3)