1Image::Info(3)        User Contributed Perl Documentation       Image::Info(3)
2
3
4

NAME

6       Image::Info - Extract meta information from image files
7

SYNOPSIS

9        use Image::Info qw(image_info dim);
10
11        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
17        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
23        my($w, $h) = dim($info);
24

DESCRIPTION

26       This module provides functions to extract various kinds of meta
27       information from image files.
28
29   EXPORTS
30       Exports nothing by default, but can export the following methods on
31       request:
32
33               image_info
34               image_type
35               dim
36               html_dim
37               determine_file_type
38
39   METHODS
40       The following functions are provided by the "Image::Info" module:
41
42       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
51           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
55           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
59           The "image_info()" function also take optional key/value style
60           arguments that can influence what information is returned.
61
62       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
68           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
72           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
77           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
82           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
87           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
92           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
96       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
101       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
105              print "<img src="..." @{[html_dim($info)]}>\n";
106
107       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

Image descriptions

114       The "image_info()" function returns meta information about each image
115       in 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
122       The following key names are common for any image format:
123
124       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
129       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
134       width
135           This is the number of pixels horizontally in the image.
136
137       height
138           This is the number of pixels vertically in the image.  (TIFF uses
139           the name ImageLength for this field.)
140
141       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
145             Gray
146             GrayA
147             RGB
148             RGBA
149             CMYK
150             YCbCr
151             CIELab
152
153           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
157           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
161       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
166           The syntax of this field is:
167
168              <res> <unit>
169              <xres> "/" <yres> <unit>
170              <xres> "/" <yres>
171
172           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
176       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
181       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
186       Comment
187           Textual comments found in the file.  The value is a reference to an
188           array if there are multiple comments found.
189
190       Interlace
191           If the image is interlaced, then this tells which interlace method
192           is used.
193
194       Compression
195           This tells you which compression algorithm is used.
196
197       Gamma
198           A number.
199
200       LastModificationTime
201           A ISO date string
202

Supported Image Formats

204       The following image file formats are supported:
205
206       BMP This module supports the Microsoft Device Independent Bitmap format
207           (BMP, DIB, RLE).
208
209           For more information see Image::Info::BMP.
210
211       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
219       ICO This module supports the Microsoft Windows Icon Resource format
220           (.ico).
221
222       JPEG
223           For JPEG files we extract information both from "JFIF" and "Exif"
224           application chunks.
225
226           "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
230           The "Exif" spec can be found at:
231           <http://www.exif.org/specifications.html>.
232
233           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
237       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
241       PBM/PGM/PPM
242           All information available is extracted.
243
244       SVG Provides a plethora of attributes and metadata of an SVG vector
245           graphic.
246
247       TIFF
248           The "TIFF" spec can be found at:
249           <http://partners.adobe.com/public/developer/tiff/>
250
251           The EXIF spec can be found at:
252           <http://www.exif.org/specifications.html>
253
254       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
258       XBM See Image::Info::XBM for details.
259
260       XPM See Image::Info::XPM for details.
261

CAVEATS

263       While this module is fine for parsing basic image information like
264       image type, dimensions and color depth, it is probably not good enough
265       for parsing out more advanced information like EXIF data. If you want
266       an up-to-date and tested EXIF parsing library, please use
267       Image::ExifTool.
268

SEE ALSO

270       Image::Size, Image::ExifTool
271

AUTHORS

273       Copyright 1999-2004 Gisle Aas.
274
275       See the CREDITS file for a list of contributors and authors.
276
277       Tels - (c) 2006 - 2008.
278
279       Current maintainer: Slaven Rezic - (c) 2008 - 2015.
280

LICENSE

282       This library is free software; you can redistribute it and/or modify it
283       under the same terms as Perl v5.8.8 itself.
284
285
286
287perl v5.30.0                      2019-07-26                    Image::Info(3)
Impressum