1Image::Info(3) User Contributed Perl Documentation Image::Info(3)
2
6 Image::Info - Extract meta information from image files
7
9 use Image::Info qw(image_info dim);
10 my $info = image_info("image.jpg");
12 if (my $error = $info->{error}) {
13 die "Can't parse image info: $error\n";
14 }
15 my $color = $info->{color_type};
16 my $type = image_type("image.jpg");
18 if (my $error = $type->{error}) {
19 die "Can't determine file type: $error\n";
20 }
21 die "No gif files allowed!" if $type->{file_type} eq 'GIF';
22 my($w, $h) = dim($info);
24
26 This module provide functions to extract various kind of meta informa‐
27 tion from image files.
28 EXPORTS
30 Exports nothing by default, but can export the following methods on
32 request:
33 image_info
35 image_type
36 dim
37 html_dim
38 determine_file_type
39 METHODS
41 The following functions are provided by the "Image::Info" module:
43 image_info( $file )
45 image_info( \$imgdata )
46 image_info( $file, key => value,... )
47 This function takes the name of a file or a file handle as argument
48 and will return one or more hashes (actually hash references)
49 describing the images inside the file. If there is only one image
50 in the file only one hash is returned. In scalar context, only the
51 hash for the first image is returned.
52 In case of error, and hash containing the "error" key will be
54 returned. The corresponding value will be an appropriate error
55 message.
56 If a reference to a scalar is passed as argument to this function,
58 then it is assumed that this scalar contains the raw image data
59 directly.
60 The image_info() function also take optional key/value style argu‐
62 ments that can influence what information is returned.
63 image_type( $filename )
65 Returns a hash with only one key, "file_type". The value will be
66 the type of the file. On error, sets the two keys "error" and
67 "Errno".
68 image_info( \$imgdata )
70 This function is a dramatically faster alternative to the
71 image_info function for situations in which you only need to find
72 the image type.
73 It uses only the internal file-type detection to do this, and thus
75 does not need to load any of the image type-specific driver mod‐
76 ules, and does not access to entire file. It also only needs access
77 to the first 32 bytes of the file.
78 To maintain some level of compatibility with image_info, image_type
80 returns in the same format, with the same error message style. That
81 is, it returns a HASH reference, with the $type->{error} key set if
82 there was an error.
83 On success, the HASH reference will contain the single key
85 'file_type', which represents the type of the file, expressed as
86 the type code used for the various drivers ('GIF', 'JPEG', 'TIFF'
87 and so on).
88 If there are multiple images within the file they will be ignored,
90 as this function provides only the type of the overall file, not of
91 the various images within it. This function will not return multi‐
92 ple hashes if the file contains multiple images.
93 Of course, in all (or at least effectively all) cases the type of
95 the images inside the file is going to be the same as that of the
96 file itself.
97 dim( $info_hash )
99 Takes an hash as returned from image_info() and returns the dimen‐
100 sions ($width, $height) of the image. In scalar context returns
101 the dimensions as a string.
102 html_dim( $info_hash )
104 Returns the dimensions as a string suitable for embedding directly
105 into HTML or SVG <img>-tags. E.g.:
106 print "<img src="..." @{[html_dim($info)]}>\n";
108 determine_file_format( $filedata )
110 Determines the file format from the passed file data (a normal Perl
111 scalar containing the first bytes of the file), and returns either
112 undef for an unknown file format, or a string describing the for‐
113 mat, like "BMP" or "JPEG".
114
116 The image_info() function returns meta information about each image in
117 the form of a reference to a hash. The hash keys used are in most
118 cases based on the TIFF element names. All lower case keys are manda‐
119 tory for all file formats and will always be there unless an error
120 occured (in which case the "error" key will be present.) Mixed case
121 keys will only be present when the corresponding information element is
122 available in the image.
123 The following key names are common for any image format:
125 file_media_type
127 This is the MIME type that is appropriate for the given file for‐
128 mat. The corresponding value is a string like: "image/png" or
129 "image/jpeg".
130 file_ext
132 The is the suggested file name extention for a file of the given
133 file format. The value is a 3 letter, lowercase string like "png",
134 "jpg".
135 width
137 This is the number of pixels horizontally in the image.
138 height
140 This is the number of pixels vertically in the image. (TIFF use
141 the name ImageLength for this field.)
142 color_type
144 The value is a short string describing what kind of values the pix‐
145 els encode. The value can be one of the following:
146 Gray
148 GrayA
149 RGB
150 RGBA
151 CMYK
152 YCbCr
153 CIELab
154 These names can also be prefixed by "Indexed-" if the image is com‐
156 posed of indexes into a palette. Of these, only "Indexed-RGB" is
157 likely to occur.
158 It is similar to the TIFF field PhotometricInterpretation, but this
160 name was found to be too long, so we used the PNG inpired term
161 instead.
162 resolution
164 The value of this field normally gives the physical size of the
165 image on screen or paper. When the unit specifier is missing then
166 this field denotes the squareness of pixels in the image.
167 The syntax of this field is:
169 <res> <unit>
171 <xres> "/" <yres> <unit>
172 <xres> "/" <yres>
173 The <res>, <xres> and <yres> fields are numbers. The <unit> is a
175 string like "dpi", "dpm" or "dpcm" (denoting "dots per
176 inch/cm/meter).
177 SamplesPerPixel
179 This says how many channels there are in the image. For some image
180 formats this number might be higher than the number implied from
181 the "color_type".
182 BitsPerSample
184 This says how many bits are used to encode each of samples. The
185 value is a reference to an array containing numbers. The number of
186 elements in the array should be the same as "SamplesPerPixel".
187 Comment
189 Textual comments found in the file. The value is a reference to an
190 array if there are multiple comments found.
191 Interlace
193 If the image is interlaced, then this tell which interlace method
194 is used.
195 Compression
197 This tells you which compression algorithm is used.
198 Gamma
200 A number.
201 LastModificationTime
203 A ISO date string
204
206 The following image file formats are supported:
207 BMP This module supports the Microsoft Device Independent Bitmap format
209 (BMP, DIB, RLE).
210 For more information see Image::Info::BMP.
212 GIF Both GIF87a and GIF89a are supported and the version number is
214 found as "GIF_Version" for the first image. GIF files can contain
215 multiple images, and information for all images will be returned if
216 image_info() is called in list context. The Netscape-2.0 extention
217 to loop animation sequences is represented by the "GIF_Loop" key
218 for the first image. The value is either "forever" or a number
219 indicating loop count.
220 JPEG
222 For JPEG files we extract information both from "JFIF" and "Exif"
223 application chunks.
224 "Exif" is the file format written by most digital cameras. This
226 encode things like timestamp, camera model, focal length, exposure
227 time, aperture, flash usage, GPS position, etc. The following web
228 page contain description of the fields that can be present:
229 http://www.ba.wakwak.com/~tsuruzoh/Computer/Digicams/exif-e.html
231 The "Exif" spec can be found at:
233 http://www.exif.org/specifications.html
235 PNG Information from IHDR, PLTE, gAMA, pHYs, tEXt, tIME chunks are
237 extracted. The sequence of chunks are also given by the
238 "PNG_Chunks" key.
239 PBM/PGM/PPM
241 All information available is extracted.
242 SVG Provides a plethora of attributes and metadata of an SVG vector
244 grafic.
245 TIFF
247 The "TIFF" spec can be found at: <http://partners.adobe.com/pub‐
248 lic/developer/tiff/>
249 The EXIF spec can be found at: <http://www.exif.org/>
251 XBM See Image::Info::XBM for details.
253 XPM See Image::Info::XPM for details.
255
257 Note that while the module is still maintained, no new features will be
258 added.
259 Especially the EXIF parsing code is buggy, not tested at all, and quite
261 incomplete (a lot of manufacturer's MakerNotes and tags are not parsed
262 at all). If you want a stable, feature-complete, up-to-date and tested
263 EXIF parsing library, please use Image::ExifTool.
264
266 Image::Size, Image::ExifTool
267
269 Copyright 1999-2004 Gisle Aas.
270 See the CREDITS file for a list of contributors and authors.
272 Now maintained by Tels - (c) 2006 - 2007.
274
276 This library is free software; you can redistribute it and/or modify it
277 under the same terms as Perl itself.
278perl v5.8.8 2006-03-04 Image::Info(3)