1Image::Size(3) User Contributed Perl Documentation Image::Size(3)
2
6 Image::Size - read the dimensions of an image in several popular for‐
7 mats
8
10 use Image::Size;
11 # Get the size of globe.gif
12 ($globe_x, $globe_y) = imgsize("globe.gif");
13 # Assume X=60 and Y=40 for remaining examples
14 use Image::Size 'html_imgsize';
16 # Get the size as 'width="X" height="Y"' for HTML generation
17 $size = html_imgsize("globe.gif");
18 # $size == 'width="60" height="40"'
19 use Image::Size 'attr_imgsize';
21 # Get the size as a list passable to routines in CGI.pm
22 @attrs = attr_imgsize("globe.gif");
23 # @attrs == ('-width', 60, '-height', 40)
24 use Image::Size;
26 # Get the size of an in-memory buffer
27 ($buf_x, $buf_y) = imgsize(\$buf);
28 # Assuming that $buf was the data, imgsize() needed a reference to a scalar
29
31 The Image::Size library is based upon the "wwwis" script written by
32 Alex Knowles (alex@ed.ac.uk), a tool to examine HTML and add 'width'
33 and 'height' parameters to image tags. The sizes are cached internally
34 based on file name, so multiple calls on the same file name (such as
35 images used in bulleted lists, for example) do not result in repeated
36 computations.
37 Image::Size provides three interfaces for possible import:
39 imgsize(stream)
41 Returns a three-item list of the X and Y dimensions (width and
42 height, in that order) and image type of stream. Errors are noted
43 by undefined (undef) values for the first two elements, and an
44 error string in the third. The third element can be (and usually
45 is) ignored, but is useful when sizing data whose type is unknown.
46 html_imgsize(stream)
48 Returns the width and height (X and Y) of stream pre-formatted as a
49 single string 'width="X" height="Y"' suitable for addition into
50 generated HTML IMG tags. If the underlying call to "imgsize" fails,
51 undef is returned. The format returned is dually suited to both
52 HTML and XHTML.
53 attr_imgsize(stream)
55 Returns the width and height of stream as part of a 4-element list
56 useful for routines that use hash tables for the manipulation of
57 named parameters, such as the Tk or CGI libraries. A typical return
58 value looks like "("-width", X, "-height", Y)". If the underlying
59 call to "imgsize" fails, undef is returned.
60 By default, only "imgsize()" is exported. Any one or combination of the
62 three may be explicitly imported, or all three may be with the tag
63 :all.
64 Input Types
66 The sort of data passed as stream can be one of three forms:
68 string
70 If an ordinary scalar (string) is passed, it is assumed to be a
71 file name (either absolute or relative to the current working
72 directory of the process) and is searched for and opened (if found)
73 as the source of data. Possible error messages (see DIAGNOSTICS
74 below) may include file-access problems.
75 scalar reference
77 If the passed-in stream is a scalar reference, it is interpreted as
78 pointing to an in-memory buffer containing the image data.
79 # Assume that &read_data gets data somewhere (WWW, etc.)
81 $img = &read_data;
82 ($x, $y, $id) = imgsize(\$img);
83 # $x and $y are dimensions, $id is the type of the image
84 Open file handle
86 The third option is to pass in an open filehandle (such as an
87 object of the "IO::File" class, for example) that has already been
88 associated with the target image file. The file pointer will neces‐
89 sarily move, but will be restored to its original position before
90 subroutine end.
91 # $fh was passed in, is IO::File reference:
93 ($x, $y, $id) = imgsize($fh);
94 # Same as calling with filename, but more abstract.
95 Recognized Formats
97 Image::Size natively understands and sizes data in the following for‐
99 mats:
100 GIF
102 JPG
103 XBM
104 XPM
105 PPM family (PPM/PGM/PBM)
106 XV thumbnails
107 PNG
108 MNG
109 TIF
110 BMP
111 PSD (Adobe PhotoShop)
112 SWF (ShockWave/Flash)
113 CWS (FlashMX, compressed SWF, Flash 6)
114 PCD (Kodak PhotoCD, see notes below)
115 Additionally, if the Image::Magick module is present, the file types
117 supported by it are also supported by Image::Size. See also "CAVEATS".
118 When using the "imgsize" interface, there is a third, unused value
120 returned if the programmer wishes to save and examine it. This value is
121 the identity of the data type, expressed as a 2-3 letter abbreviation
122 as listed above. This is useful when operating on open file handles or
123 in-memory data, where the type is as unknown as the size. The two sup‐
124 port routines ignore this third return value, so those wishing to use
125 it must use the base "imgsize" routine.
126 Note that when the Image::Magick fallback is used (for all non-natively
128 supported files), the data type identity comes directly from the 'for‐
129 mat' parameter reported by Image::Magick, so it may not meet the 2-3
130 letter abbreviation format. For example, a WBMP file might be reported
131 as 'Wireless Bitmap (level 0) image' in this case.
132 Information Cacheing and $NO_CACHE
134 When a filename is passed to any of the sizing routines, the default
136 behavior of the library is to cache the resulting information. The mod‐
137 ification-time of the file is also recorded, to determine whether the
138 cache should be purged and updated. This was originally added due to
139 the fact that a number of CGI applications were using this library to
140 generate attributes for pages that often used the same graphical ele‐
141 ment many times over.
142 However, the cacheing can lead to problems when the files are generated
144 dynamically, at a rate that exceeds the resolution of the modification-
145 time value on the filesystem. Thus, the optionally-importable control
146 variable $NO_CACHE has been introduced. If this value is anything that
147 evaluates to a non-false value (be that the value 1, any non-null
148 string, etc.) then the cacheing is disabled until such time as the pro‐
149 gram re-enables it by setting the value to false.
150 The parameter $NO_CACHE may be imported as with the imgsize routine,
152 and is also imported when using the import tag ":all". If the program‐
153 mer chooses not to import it, it is still accessible by the fully-qual‐
154 ified package name, $Image::Size::NO_CACHE.
155 Sizing PhotoCD Images
157 With version 2.95, support for the Kodak PhotoCD image format is
159 included. However, these image files are not quite like the others. One
160 file is the source of the image in any of a range of pre-set resolu‐
161 tions (all with the same aspect ratio). Supporting this here is tricky,
162 since there is nothing inherent in the file to limit it to a specific
163 resolution.
164 The library addresses this by using a scale mapping, and requiring the
166 user (you) to specify which scale is preferred for return. Like the
167 $NO_CACHE setting described earlier, this is an importable scalar vari‐
168 able that may be used within the application that uses Image::Size.
169 This parameter is called $PCD_SCALE, and is imported by the same name.
170 It, too, is also imported when using the tag ":all" or may be refer‐
171 enced as $Image::Size::PCD_SCALE.
172 The parameter should be set to one of the following values:
174 base/16
176 base/4
177 base
178 base4
179 base16
180 base64
181 Note that not all PhotoCD disks will have included the "base64" resolu‐
183 tion. The actual resolutions are not listed here, as they are constant
184 and can be found in any documentation on the PCD format. The value of
185 $PCD_SCALE is treated in a case-insensitive manner, so "base" is the
186 same as "Base" or "BaSe". The default scale is set to "base".
187 Also note that the library makes no effort to read enough of the PCD
189 file to verify that the requested resolution is available. The point of
190 this library is to read as little as necessary so as to operate effi‐
191 ciently. Thus, the only real difference to be found is in whether the
192 orientation of the image is portrait or landscape. That is in fact all
193 that the library extracts from the image file.
194 Controlling Behavior with GIF Images
196 GIF images present a sort of unusual situation when it comes to reading
198 size. Because GIFs can be a series of sub-images to be isplayed as an
199 animated sequence, what part does the user want to get the size for?
200 When dealing with GIF files, the user may control the behavior by set‐
202 ting the global value $Image::Size::GIF_BEHAVIOR. Like the PCD setting,
203 this may be imported when loading the library. Three values are recog‐
204 nized by the GIF-handling code:
205 0 This is the default value. When this value is chosen, the returned
207 dimensions are those of the "screen". The "screen" is the display
208 area that the GIF declares in the first data block of the file. No
209 sub-images will be greater than this in size; if they are, the
210 specification dictates that they be cropped to fit within the box.
211 This is also the fastest method for sizing the GIF, as it reads the
213 least amount of data from the image stream.
214 1 If this value is set, then the size of the first sub-image within
216 the GIF is returned. For plain (non-animated) GIF files, this would
217 be the same as the screen (though it doesn't have to be,
218 strictly-speaking).
219 When the first image descriptor block is read, the code immediately
221 returns, making this only slightly-less efficient than the previous
222 setting.
223 2 If this value is chosen, then the code loops through all the sub-
225 images of the animated GIF, and returns the dimensions of the
226 largest of them.
227 This option requires that the full GIF image be read, in order to
229 ensure that the largest is found.
230 Any value outside this range will produce an error in the GIF code
232 before any image data is read.
233 The value of dimensions other than the view-port ("screen") is dubious.
235 However, some users have asked for that functionality.
236
238 The base routine, "imgsize", returns undef as the first value in its
239 list when an error has occured. The third element contains a descrip‐
240 tive error message.
241 The other two routines simply return undef in the case of error.
243
245 The attr_imgsize interface is also well-suited to use with the Tk
246 extension:
247 $image = $widget->Photo(-file => $img_path, attr_imgsize($img_path));
249 Since the "Tk::Image" classes use dashed option names as "CGI" does, no
251 further translation is needed.
252 This package is also well-suited for use within an Apache web server
254 context. File sizes are cached upon read (with a check against the
255 modified time of the file, in case of changes), a useful feature for a
256 mod_perl environment in which a child process endures beyond the life‐
257 time of a single request. Other aspects of the mod_perl environment
258 cooperate nicely with this module, such as the ability to use a sub-
259 request to fetch the full pathname for a file within the server space.
260 This complements the HTML generation capabilities of the CGI module, in
261 which "CGI::img" wants a URL but "attr_imgsize" needs a file path:
262 # Assume $Q is an object of class CGI, $r is an Apache request object.
264 # $imgpath is a URL for something like "/img/redball.gif".
265 $r->print($Q->img({ -src => $imgpath,
266 attr_imgsize($r->lookup_uri($imgpath)->filename) }));
267 The advantage here, besides not having to hard-code the server document
269 root, is that Apache passes the sub-request through the usual request
270 lifecycle, including any stages that would re-write the URL or other‐
271 wise modify it.
272
274 Caching of size data can only be done on inputs that are file names.
275 Open file handles and scalar references cannot be reliably transformed
276 into a unique key for the table of cache data. Buffers could be cached
277 using the MD5 module, and perhaps in the future I will make that an
278 option. I do not, however, wish to lengthen the dependancy list by
279 another item at this time.
280 As Image::Magick operates on file names, not handles, the use of it is
282 restricted to cases where the input to "imgsize" is provided as file
283 name.
284
286 The Image::Magick and Image::Info Perl modules at CPAN.
287
289 Perl module interface by Randy J. Ray (rjray@blackperl.com), original
290 image-sizing code by Alex Knowles (alex@ed.ac.uk) and Andrew Tong
291 (werdna@ugcs.caltech.edu), used with their joint permission.
292 Some bug fixes submitted by Bernd Leibing (bernd.leib‐
294 ing@rz.uni-ulm.de). PPM/PGM/PBM sizing code contributed by Carsten
295 Dominik (dominik@strw.LeidenUniv.nl). Tom Metro (tmetro@vl.com) re-
296 wrote the JPG and PNG code, and also provided a PNG image for the test
297 suite. Dan Klein (dvk@lonewolf.com) contributed a re-write of the GIF
298 code. Cloyce Spradling (cloyce@headgear.org) contributed TIFF sizing
299 code and test images. Aldo Calpini (a.calpini@romagiubileo.it) sug‐
300 gested support of BMP images (which I really should have already
301 thought of :-) and provided code to work with. A patch to allow
302 html_imgsize to produce valid output for XHTML, as well as some docu‐
303 mentation fixes was provided by Charles Levert
304 (charles@comm.polymtl.ca). The ShockWave/Flash support was provided by
305 Dmitry Dorofeev (dima@yasp.com). Though I neglected to take note of who
306 supplied the PSD (PhotoShop) code, a bug was identified by Alex Wes‐
307 lowski <aweslowski@rpinteractive.com>, who also provided a test image.
308 PCD support was adapted from a script made available by Phil Greenspun,
309 as guided to my attention by Matt Mueller mueller@wetafx.co.nz. A thor‐
310 ough read of the documentation and source by Philip Newton Philip.New‐
311 ton@datenrevision.de found several typos and a small buglet. Ville
312 Skyttä (ville.skytta@iki.fi) provided the MNG and the Image::Magick
313 fallback code.
314perl v5.8.8 2006-09-16 Image::Size(3)