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 provides functions to extract various kinds of meta
27 information from image files.
28 EXPORTS
30 Exports nothing by default, but can export the following methods on
31 request:
32 image_info
34 image_type
35 dim
36 html_dim
37 determine_file_type
38 METHODS
40 The following functions are provided by the "Image::Info" module:
41 image_info( $file )
43 image_info( \$imgdata )
44 image_info( $file, key => value,... )
45 This function takes the name of a file or a file handle as argument
46 and will return one or more hashes (actually hash references)
47 describing the images inside the file. If there is only one image
48 in the file only one hash is returned. In scalar context, only the
49 hash for the first image is returned.
50 In case of error, a hash containing the "error" key will be
52 returned. The corresponding value will be an appropriate error
53 message.
54 If a reference to a scalar is passed as an argument to this
56 function, then it is assumed that this scalar contains the raw
57 image data directly.
58 The image_info() function also take optional key/value style
60 arguments that can influence what information is returned.
61 image_type( $file )
63 image_type( \$imgdata )
64 Returns a hash with only one key, "file_type". The value will be
65 the type of the file. On error, sets the two keys "error" and
66 "Errno".
67 This function is a dramatically faster alternative to the
69 image_info function for situations in which you only need to find
70 the image type.
71 It uses only the internal file-type detection to do this, and thus
73 does not need to load any of the image type-specific driver
74 modules, and does not access to entire file. It also only needs
75 access to the first 11 bytes of the file.
76 To maintain some level of compatibility with image_info, image_type
78 returns in the same format, with the same error message style. That
79 is, it returns a HASH reference, with the "$type->{error}" key set
80 if there was an error.
81 On success, the HASH reference will contain the single key
83 "file_type", which represents the type of the file, expressed as
84 the type code used for the various drivers ('GIF', 'JPEG', 'TIFF'
85 and so on).
86 If there are multiple images within the file they will be ignored,
88 as this function provides only the type of the overall file, not of
89 the various images within it. This function will not return
90 multiple hashes if the file contains multiple images.
91 Of course, in all (or at least effectively all) cases the type of
93 the images inside the file is going to be the same as that of the
94 file itself.
95 dim( $info_hash )
97 Takes an hash as returned from image_info() and returns the
98 dimensions ($width, $height) of the image. In scalar context
99 returns the dimensions as a string.
100 html_dim( $info_hash )
102 Returns the dimensions as a string suitable for embedding directly
103 into HTML or SVG <img>-tags. E.g.:
104 print "<img src="..." @{[html_dim($info)]}>\n";
106 determine_file_format( $filedata )
108 Determines the file format from the passed file data (a normal Perl
109 scalar containing the first bytes of the file), and returns either
110 undef for an unknown file format, or a string describing the
111 format, like "BMP" or "JPEG".
112
114 The image_info() function returns meta information about each image in
115 the form of a reference to a hash. The hash keys used are in most
116 cases based on the TIFF element names. All lower case keys are
117 mandatory for all file formats and will always be there unless an error
118 occurred (in which case the "error" key will be present.) Mixed case
119 keys will only be present when the corresponding information element is
120 available in the image.
121 The following key names are common for any image format:
123 file_media_type
125 This is the MIME type that is appropriate for the given file
126 format. The corresponding value is a string like: "image/png" or
127 "image/jpeg".
128 file_ext
130 The is the suggested file name extension for a file of the given
131 file format. The value is a 3 letter, lowercase string like "png",
132 "jpg".
133 width
135 This is the number of pixels horizontally in the image.
136 height
138 This is the number of pixels vertically in the image. (TIFF uses
139 the name ImageLength for this field.)
140 color_type
142 The value is a short string describing what kind of values the
143 pixels encode. The value can be one of the following:
144 Gray
146 GrayA
147 RGB
148 RGBA
149 CMYK
150 YCbCr
151 CIELab
152 These names can also be prefixed by "Indexed-" if the image is
154 composed of indexes into a palette. Of these, only "Indexed-RGB"
155 is likely to occur.
156 It is similar to the TIFF field "PhotometricInterpretation", but
158 this name was found to be too long, so we used the PNG inspired
159 term instead.
160 resolution
162 The value of this field normally gives the physical size of the
163 image on screen or paper. When the unit specifier is missing then
164 this field denotes the squareness of pixels in the image.
165 The syntax of this field is:
167 <res> <unit>
169 <xres> "/" <yres> <unit>
170 <xres> "/" <yres>
171 The <res>, <xres> and <yres> fields are numbers. The <unit> is a
173 string like "dpi", "dpm" or "dpcm" (denoting "dots per
174 inch/cm/meter).
175 SamplesPerPixel
177 This says how many channels there are in the image. For some image
178 formats this number might be higher than the number implied from
179 the "color_type".
180 BitsPerSample
182 This says how many bits are used to encode each of samples. The
183 value is a reference to an array containing numbers. The number of
184 elements in the array should be the same as "SamplesPerPixel".
185 Comment
187 Textual comments found in the file. The value is a reference to an
188 array if there are multiple comments found.
189 Interlace
191 If the image is interlaced, then this tells which interlace method
192 is used.
193 Compression
195 This tells you which compression algorithm is used.
196 Gamma
198 A number.
199 LastModificationTime
201 A ISO date string
202
204 The following image file formats are supported:
205 BMP This module supports the Microsoft Device Independent Bitmap format
207 (BMP, DIB, RLE).
208 For more information see Image::Info::BMP.
210 GIF Both GIF87a and GIF89a are supported and the version number is
212 found as "GIF_Version" for the first image. GIF files can contain
213 multiple images, and information for all images will be returned if
214 image_info() is called in list context. The Netscape-2.0 extension
215 to loop animation sequences is represented by the "GIF_Loop" key
216 for the first image. The value is either "forever" or a number
217 indicating loop count.
218 ICO This module supports the Microsoft Windows Icon Resource format
220 (.ico).
221 JPEG
223 For JPEG files we extract information both from "JFIF" and "Exif"
224 application chunks.
225 "Exif" is the file format written by most digital cameras. This
227 encode things like timestamp, camera model, focal length, exposure
228 time, aperture, flash usage, GPS position, etc.
229 The "Exif" spec can be found at:
231 <http://www.exif.org/specifications.html>.
232 The "color_type" element may have the following values: "Gray",
234 "YCbCr", and "CMYK". Note that detecting "RGB" and "YCCK" currently
235 does not work, but will hopefully in future.
236 PNG Information from IHDR, PLTE, gAMA, pHYs, tEXt, tIME chunks are
238 extracted. The sequence of chunks are also given by the
239 "PNG_Chunks" key.
240 PBM/PGM/PPM
242 All information available is extracted.
243 SVG Provides a plethora of attributes and metadata of an SVG vector
245 graphic.
246 TIFF
248 The "TIFF" spec can be found at:
249 <http://partners.adobe.com/public/developer/tiff/>
250 The EXIF spec can be found at:
252 <http://www.exif.org/specifications.html>
253 WBMP
255 wbmp files have no magic, so cannot be used with the normal
256 Image::Info functions. See Image::Info::WBMP for more information.
257 WEBP
259 VP8 (lossy), VP8L (lossless) and VP8X (extended) files are
260 supported. Sets the key "Animation" to true if the file is an
261 animation. Otherwise sets the key "Compression" to either "VP8" or
262 "Lossless".
263 XBM See Image::Info::XBM for details.
265 XPM See Image::Info::XPM for details.
267
269 While this module is fine for parsing basic image information like
270 image type, dimensions and color depth, it is probably not good enough
271 for parsing out more advanced information like EXIF data. If you want
272 an up-to-date and tested EXIF parsing library, please use
273 Image::ExifTool.
274
276 Image::Size, Image::ExifTool
277
279 Copyright 1999-2004 Gisle Aas.
280 See the CREDITS file for a list of contributors and authors.
282 Tels - (c) 2006 - 2008.
284 Current maintainer: Slaven Rezic - (c) 2008 - 2015.
286
288 This library is free software; you can redistribute it and/or modify it
289 under the same terms as Perl v5.8.8 itself.
290perl v5.36.0 2023-01-20 Image::Info(3)