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
62 functionality for the xbm file format. It inherits from "Image::Base"
63 which provides additional manipulation functionality, e.g.
64 new_from_image(). See the "Image::Base" pod for information on adding
65 your own functionality to all the "Image::Base" derived classes.
66 new()
68 my $i = Image::Xbm->new( -file => 'test.xbm' ) ;
69 my $j = Image::Xbm->new( -width => 12, -height => 18 ) ;
70 my $k = $i->new ;
71 We can create a new xbm image by reading in a file, or by creating an
73 image from scratch (all the bits are unset by default), or by copying
74 an image object that we created earlier.
75 If we set "-file" then all the other arguments are ignored (since
77 they're taken from the file). If we don't specify a file, "-width" and
78 "-height" are mandatory.
79 "-file"
81 The name of the file to read when creating the image. May contain a
82 full path. This is also the default name used for "load"ing and
83 "save"ing, though it can be overridden when you load or save.
84 "-width"
86 The width of the image; taken from the file or set when the object
87 is created; read-only.
88 "-height"
90 The height of the image; taken from the file or set when the object
91 is created; read-only.
92 "-hotx"
94 The x-coord of the image's hotspot; taken from the file or set when
95 the object is created. Set to -1 if there is no hotspot.
96 "-hoty"
98 The y-coord of the image's hotspot; taken from the file or set when
99 the object is created. Set to -1 if there is no hotspot.
100 "-bits"
102 The bit vector that stores the image; read-only.
103 new_from_string()
105 my $p = Image::Xbm->new_from_string( "###\n#-#\n###" ) ;
106 my $q = $p->new_from_string( "H##", "#-#", "###" ) ;
107 my $r = $p->new_from_string( $p->as_string ) ;
108 Create a new bitmap from a string or from an array or list of strings.
110 If you want to use different characters you can:
111 Image::Xbm->set( -setch => 'X', -unsetch => ' ' ) ;
113 my $s = $p->new_from_string( "XXX", "X X", "XhX" ) ;
114 You can also specify a hotspot by making one of the characters a 'H'
116 (set bit hotspot) or 'h' (unset bit hotspot) -- you can use different
117 characters by setting "-sethotch" and "-unsethotch" respectively.
118 new_from_serialised()
120 my $i = Image::Xbm->new_from_serialised( $s ) ;
121 Creates an image from a string created with the serialse() method.
123 Since such strings are a little more compressed than xbm files or
124 Image::Xbm objects they might be useful if storing a lot of bitmaps, or
125 for transferring bitmaps over comms links.
126 serialise()
128 my $s = $i->serialise ;
129 Creates a string version of the image which can be completed recreated
131 using the "new_from_serialised" method.
132 get()
134 my $width = $i->get( -width ) ;
135 my( $hotx, $hoty ) = $i->get( -hotx, -hoty ) ;
136 Get any of the object's attributes. Multiple attributes may be
138 requested in a single call.
139 See "xy" and "vec" to get/set bits of the image itself.
141 set()
143 $i->set( -hotx => 120, -hoty => 32 ) ;
144 Set any of the object's attributes. Multiple attributes may be set in a
146 single call. Except for "-setch" and "-unsetch" all attributes are
147 object attributes; some attributes are read-only.
148 See "xy" and "vec" to get/set bits of the image itself.
150 class attributes
152 Image::Xbm->set( -setch => 'X' ) ;
153 $i->set( -setch => '@', -unsetch => '*' ) ;
154 "-setch"
156 The character to print set bits as when using "as_string", default
157 is '#'. This is a class attribute accessible from the class or an
158 object via "get" and "set".
159 "-unsetch"
161 The character to print set bits as when using "as_string", default
162 is '-'. This is a class attribute accessible from the class or an
163 object via "get" and "set".
164 "-sethotch"
166 The character to print set bits as when using "as_string", default
167 is 'H'. This is a class attribute accessible from the class or an
168 object via "get" and "set".
169 "-unsethotch"
171 The character to print set bits as when using "as_string", default
172 is 'h'. This is a class attribute accessible from the class or an
173 object via "get" and "set".
174 xybit()
176 $i->xy( 4, 11, 1 ) ; # Set the bit at point 4,11
177 my $v = $i->xy( 9, 17 ) ; # Get the bit at point 9,17
178 Get/set bits using x, y coordinates; coordinates start at 0.
180 xy()
182 $i->xy( 4, 11, 'black' ) ; # Set the bit from a colour at point 4,11
183 my $v = $i->xy( 9, 17 ) ; # Get the bit as a colour at point 9,17
184 Get/set bits using colours using x, y coordinates; coordinates start at
186 0.
187 If set with a colour of 'black' or a numeric value > 0 or a string not
189 matching /^#0+$/ then the bit will be set, otherwise it will be
190 cleared.
191 If you get a colour you will always get 'black' or 'white'.
193 vec()
195 $i->vec( 43, 0 ) ; # Unset the bit at offset 43
196 my $v = $i->vec( 87 ) ; # Get the bit at offset 87
197 Get/set bits using vector offsets; offsets start at 0.
199 load()
201 $i->load ;
202 $i->load( 'test.xbm' ) ;
203 Load the image whose name is given, or if none is given load the image
205 whose name is in the "-file" attribute.
206 save()
208 $i->save ;
209 $i->save( 'test.xbm' ) ;
210 Save the image using the name given, or if none is given save the image
212 using the name in the "-file" attribute. The image is saved in xbm
213 format, e.g.
214 #define test_width 6
216 #define test_height 6
217 static unsigned char test_bits[] = {
218 0x1f, 0x07, 0x07, 0x09, 0x11, 0x20 } ;
219 is_equal()
221 print "equal\n" if $i->is_equal( $j ) ;
222 Returns true (1) if the images are equal, false (0) otherwise. Note
224 that hotspots and filenames are ignored, so we compare width, height
225 and the actual bits only.
226 as_string()
228 print $i->as_string ;
229 Returns the image as a string, e.g.
231 #####-
233 ###---
234 ###---
235 #--#--
236 #---#-
237 -----#
238 The characters used may be changed by "set"ting the "-setch" and
240 "-unsetch" characters. If you give "as_string" a parameter it will
241 print out the hotspot if present using "-sethotch" or "-unsethotch" as
242 appropriate, e.g.
243 print $n->as_string( 1 ) ;
245 H##
247 #-#
248 ###
249 as_binstring()
251 print $i->as_binstring ;
252 Returns the image as a string of 0's and 1's, e.g.
254 1111101110001110001001001000100000010000
256
258 2016/02/23 (Slaven Rezic)
259 Make sure macro/variable names are always sane.
261 More strict parsing of bits.
263 2000/11/09
265 Added Jerrad Pierce's patch to allow load() to accept filehandles or
267 strings; will document in next release.
268 2000/05/05
270 Added new_from_serialised() and serialise() methods.
272 2000/05/04
274 Made xy() compatible with Image::Base, use xybit() for the earlier
276 functionality.
277 2000/05/01
279 Improved speed of vec(), xy() and as_string().
281 Tried use integer to improve speed but according to Benchmark it made
283 the code slower so I dropped it; interestingly perl 5.6.0 was around
284 25% slower than perl 5.004 with and without use integer.
285 2000/04/30
287 Created.
289
291 Mark Summerfield. I can be contacted as <summer@perlpress.com> - please
292 include the word 'xbm' in the subject line.
293
295 Copyright (c) Mark Summerfield 2000. All Rights Reserved.
296 This module may be used/distributed/modified under the LGPL.
298perl v5.38.0 2023-07-20 Xbm(3)