3 # Copyright 1999-2002, Gisle Aas.
5 # This library is free software; you can redistribute it and/or
6 # modify it under the same terms as Perl itself.
11 use vars qw($VERSION @EXPORT_OK);
16 *import = \&Exporter::import;
18 @EXPORT_OK = qw(image_info dim html_dim);
22 my($source, %cnf) = @_;
26 my $fh = Symbol::gensym();
27 open($fh, $source) || return _os_err("Can't open $source");
28 ${*$fh} = $source; # keep filename in case somebody wants to know
32 elsif (ref($source) eq "SCALAR") {
34 $source = IO::String->new($$source);
37 seek($source, 0, 0) or return _os_err("Can't rewind");
41 read($source, $head, 32) == 32 or return _os_err("Can't read head");
42 if (ref($source) eq "IO::String") {
43 # XXX workaround until we can trap seek() with a tied file handle
47 seek($source, 0, 0) or _os_err("Can't rewind");
50 if (my $format = determine_file_format($head)) {
52 my $mod = "Image::Info::$format";
53 my $sub = "$mod\::process_file";
54 my $info = bless [], "Image::Info::Result";
56 unless (defined &$sub) {
59 die "$mod did not define &$sub" unless defined &$sub;
62 &$sub($info, $source, \%cnf);
65 return { error => $@ } if $@;
66 return wantarray ? @$info : $info->[0];
68 return { error => "Unrecognized file format" };
73 return { error => "$_[0]: $!",
78 %%DETERMINE_FILE_FORMAT%%
82 my $img = shift || return;
83 my $x = $img->{width} || return;
84 my $y = $img->{height} || return;
85 wantarray ? ($x, $y) : "${x}x$y";
95 package Image::Info::Result;
99 my($self, $n, $key) = splice(@_, 0, 3);
100 push(@{$self->[$n]{$key}}, @_);
107 for my $k (keys %$_) {
109 $_->{$k} = $a->[0] if @$a <= 1;
115 my($self, $n, $key, $delete) = @_;
116 my $v = $delete ? delete $self->[$n]{$key} : $self->[$n]{$key};
127 Image::Info - Extract meta information from image files
131 use Image::Info qw(image_info dim);
133 my $info = image_info("image.jpg");
134 if (my $error = $info->{error}) {
135 die "Can't parse image info: $error\n";
137 my $color = $info->{color_type};
139 my($w, $h) = dim($info);
143 This module provide functions to extract various kind of meta
144 information from image files. The following functions are provided by
145 the C<Image::Info> module:
149 =item image_info( $file )
151 =item image_info( \$imgdata )
153 =item image_info( $file, key => value,... )
155 This function takes the name of a file or a file handle as argument
156 and will return one or more hashes (actually hash references)
157 describing the images inside the file. If there is only one image in
158 the file only one hash is returned. In scalar context, only the hash
159 for the first image is returned.
161 In case of error, and hash containing the "error" key will be
162 returned. The corresponding value will be an appropriate error
165 If a reference to a scalar is passed as argument to this function,
166 then it is assumed that this scalar contains the raw image data
169 The image_info() function also take optional key/value style arguments
170 that can influence what information is returned.
172 =item dim( $info_hash )
174 Takes an hash as returned from image_info() and returns the dimensions
175 ($width, $height) of the image. In scalar context returns the
176 dimensions as a string.
178 =item html_dim( $info_hash )
180 Returns the dimensions as a string suitable for embedding directly
181 into HTML <img>-tags. E.g.:
183 print "<img src="..." @{[html_dim($info)]}>\n";
187 =head1 Image descriptions
189 The image_info() function returns meta information about each image in
190 the form of a reference to a hash. The hash keys used are in most
191 cases based on the TIFF element names. All lower case keys are
192 mandatory for all file formats and will always be there unless an
193 error occured (in which case the "error" key will be present.) Mixed
194 case keys will only be present when the corresponding information
195 element is available in the image.
197 The following key names are common for any image format:
201 =item file_media_type
203 This is the MIME type that is appropriate for the given file format.
204 The corresponding value is a string like: "image/png" or "image/jpeg".
208 The is the suggested file name extention for a file of the given file
209 format. The value is a 3 letter, lowercase string like "png", "jpg".
213 This is the number of pixels horizontally in the image.
217 This is the number of pixels vertically in the image. (TIFF use the
218 name ImageLength for this field.)
222 The value is a short string describing what kind of values the pixels
223 encode. The value can be one of the following:
233 These names can also be prefixed by "Indexed-" if the image is
234 composed of indexes into a palette. Of these, only "Indexed-RGB" is
237 (It is similar to the TIFF field PhotometricInterpretation, but this
238 name was found to be too long, so we used the PNG inpired term
243 The value of this field normally gives the physical size of the image
244 on screen or paper. When the unit specifier is missing then this field
245 denotes the squareness of pixels in the image.
247 The syntax of this field is:
250 <xres> "/" <yres> <unit>
253 The <res>, <xres> and <yres> fields are numbers. The <unit> is a
254 string like C<dpi>, C<dpm> or C<dpcm> (denoting "dots per
257 =item SamplesPerPixel
259 This says how many channels there are in the image. For some image
260 formats this number might be higher than the number implied from the
265 This says how many bits are used to encode each of samples. The value
266 is a reference to an array containing numbers. The number of elements
267 in the array should be the same as C<SamplesPerPixel>.
271 Textual comments found in the file. The value is a reference to an
272 array if there are multiple comments found.
276 If the image is interlaced, then this tell which interlace method is
281 This tell which compression algorithm is used.
287 =item LastModificationTime
293 =head1 Supported Image Formats
295 The following image file formats are currently supported:
309 Copyright 1999-2001 Gisle Aas.
311 GIF fixes by Ralf Steines <metamonk@yahoo.com>.
313 ASCII, BMP SVG, XPM and XBM support added by Jerrad Pierce
314 <belg4mit@mit.edu>/<webmaster@pthbb.org>.
316 Exif MakerNote decoding by Jay Soffian <jay@loudcloud.com>.
318 TIFF support by <clarsen@emf.net>.
320 This library is free software; you can redistribute it and/or
321 modify it under the same terms as Perl itself.