1
2#############################################################################
3#
4# ATTENTION! This file is autogenerated from dev/Info.pm.tmpl - DO NOT EDIT!
5#
6#############################################################################
7
8package Image::Info;
9
10# Copyright 1999-2004, Gisle Aas.
11#
12# This library is free software; you can redistribute it and/or
13# modify it under the same terms as Perl v5.8.8 itself.
14#
15# Previously maintained by Tels - (c) 2006 - 2008.
16# Currently maintained by Slaven Rezic - (c) 2008 - 2019.
17
18use strict;
19use vars qw($VERSION @EXPORT_OK);
20
21$VERSION = '1.42';
22
23require Exporter;
24*import = \&Exporter::import;
25
26@EXPORT_OK = qw(image_info dim html_dim image_type determine_file_format);
27
28# already required and failed sub-modules are remembered here
29my %mod_failure;
30
31sub image_info
32{
33    my $source = _source(shift);
34    return $source if ref $source eq 'HASH'; # Pass on errors
35
36    # What sort of file is it?
37    my $head = _head($source);
38
39    return $head if ref($head) eq 'HASH';	# error?
40
41    my $format = determine_file_format($head)
42        or return { error => 'Unrecognized file format' };
43
44    return _image_info_for_format($format, $source);
45}
46
47# Note: this function is private, but may be used by Image::Info::*
48# implementations (i.e. the WBMP implementation)
49sub _image_info_for_format
50{
51    my($format, $source) = @_;
52
53    my $mod = "Image::Info::$format";
54    my $sub = "$mod\::process_file";
55    my $info = bless [], "Image::Info::Result";
56    eval {
57        unless (defined &$sub) {
58	    # already required and failed?
59            if (my $fail = $mod_failure{$mod}) {
60                die $fail;
61            }
62            eval "require $mod";
63            if ($@) {
64                $mod_failure{$mod} = $@;
65                die $@;
66            }
67            die "$mod did not define &$sub" unless defined &$sub;
68        }
69
70        my %cnf = @_;
71        {
72	    # call process_file()
73	    no strict 'refs';
74	    &$sub($info, $source, \%cnf);
75	}
76        $info->clean_up;
77    };
78    return { error => $@ } if $@;
79    return wantarray ? @$info : $info->[0];
80}
81
82sub image_type
83{
84    my $source = _source(shift);
85    return $source if ref $source eq 'HASH'; # Pass on errors
86
87    # What sort of file is it?
88    my $head = _head($source) or return _os_err("Can't read head");
89    my $format = determine_file_format($head)
90        or return { error => "Unrecognized file format" };
91
92    return { file_type => $format };
93}
94
95# Note: this function is private, but may be used by Image::Info::*
96# implementations (i.e. the WBMP implementation)
97sub _source
98{
99    my $source = shift;
100    if (!ref $source) {
101	my $fh;
102	if ($] < 5.006) {
103	    require Symbol;
104	    $fh = Symbol::gensym();
105	    open($fh, $source) || return _os_err("Can't open $source");
106	}
107	else {
108	    open $fh, '<', $source
109		or return _os_err("Can't open $source");
110	}
111	${*$fh} = $source;  # keep filename in case somebody wants to know
112        binmode($fh);
113        $source = $fh;
114    }
115    elsif (ref($source) eq "SCALAR") {
116	# Earlier PerlIO::scalar versions may segfault or consume lots
117	# of memory for some invalid images, see
118	# RT #100847 and img/segfault.tif
119	if (eval { require PerlIO::scalar; PerlIO::scalar->VERSION(0.21) } ||
120	    !eval { require IO::Scalar; 1 }) {
121	    open(my $s, "<", $source) or return _os_err("Can't open string");
122	    $source = $s;
123	}
124	else {
125	    $source = IO::Scalar->new($source);
126	}
127    }
128    else {
129	seek($source, 0, 0) or return _os_err("Can't rewind");
130    }
131
132    $source;
133}
134
135sub _head
136{
137    my $source = shift;
138    my $head;
139
140    # Originally was 32 bytes.
141    # In the meantime lowered to 11 bytes.
142    # But XBM probably need more because of a leading comment.
143    my $to_read = 64;
144    my $read = read($source, $head, $to_read);
145
146    return _os_err("Couldn't read any bytes") if !$read;
147
148    if (ref($source) eq "IO::String") {
149	# XXX workaround until we can trap seek() with a tied file handle
150	$source->setpos(0);
151    }
152    else {
153	seek($source, 0, 0) or return _os_err("Can't rewind");
154    }
155    $head;
156}
157
158sub _os_err
159{
160    return { error => "$_[0]: $!",
161	     Errno => $!+0,
162	   };
163}
164
165sub determine_file_format
166{
167   local($_) = @_;
168   return "JPEG" if /^\xFF\xD8/;
169   return "PNG" if /^\x89PNG\x0d\x0a\x1a\x0a/;
170   return "GIF" if /^GIF8[79]a/;
171   return "TIFF" if /^MM\x00\x2a/;
172   return "TIFF" if /^II\x2a\x00/;
173   return "BMP" if /^BM/;
174   return "ICO" if /^\000\000\001\000/;
175   return "PPM" if /^P[1-6]/;
176   return "XPM" if /(^\/\* XPM \*\/)|(static\s+char\s+\*\w+\[\]\s*=\s*{\s*"\d+)/;
177   return "XBM" if /^(?:\/\*.*\*\/\n)?#define\s/;
178   return "SVG" if /^(<\?xml|[\012\015\t ]*<svg\b)/;
179   return "WEBP" if /^RIFF.{4}WEBP/s;
180   return undef;
181}
182
183sub dim
184{
185    my $img = shift || return;
186    my $x = $img->{width} || return;
187    my $y = $img->{height} || return;
188    wantarray ? ($x, $y) : "${x}x$y";
189}
190
191sub html_dim
192{
193    my($x, $y) = dim(@_);
194    return "" unless $x;
195    "width=\"$x\" height=\"$y\"";
196}
197
198#############################################################################
199package Image::Info::Result;
200
201sub push_info
202{
203    my($self, $n, $key) = splice(@_, 0, 3);
204    push(@{$self->[$n]{$key}}, @_);
205}
206
207sub replace_info
208{
209    my($self, $n, $key) = splice(@_, 0, 3);
210    $self->[$n]{$key}[0] = $_[0];
211}
212
213sub clean_up
214{
215    my $self = shift;
216    for (@$self) {
217	for my $k (keys %$_) {
218	    my $a = $_->{$k};
219	    $_->{$k} = $a->[0] if @$a <= 1;
220	}
221    }
222}
223
224sub get_info {
225    my($self, $n, $key, $delete) = @_;
226    my $v = $delete ? delete $self->[$n]{$key} : $self->[$n]{$key};
227    $v ||= [];
228    @$v;
229}
230
2311;
232
233__END__
234
235=head1 NAME
236
237Image::Info - Extract meta information from image files
238
239=head1 SYNOPSIS
240
241 use Image::Info qw(image_info dim);
242
243 my $info = image_info("image.jpg");
244 if (my $error = $info->{error}) {
245     die "Can't parse image info: $error\n";
246 }
247 my $color = $info->{color_type};
248
249 my $type = image_type("image.jpg");
250 if (my $error = $type->{error}) {
251     die "Can't determine file type: $error\n";
252 }
253 die "No gif files allowed!" if $type->{file_type} eq 'GIF';
254
255 my($w, $h) = dim($info);
256
257=head1 DESCRIPTION
258
259This module provides functions to extract various kinds of meta
260information from image files.
261
262=head2 EXPORTS
263
264Exports nothing by default, but can export the following methods
265on request:
266
267	image_info
268	image_type
269	dim
270	html_dim
271	determine_file_type
272
273=head2 METHODS
274
275The following functions are provided by the C<Image::Info> module:
276
277=over
278
279=item image_info( $file )
280
281=item image_info( \$imgdata )
282
283=item image_info( $file, key => value,... )
284
285This function takes the name of a file or a file handle as argument
286and will return one or more hashes (actually hash references)
287describing the images inside the file.  If there is only one image in
288the file only one hash is returned.  In scalar context, only the hash
289for the first image is returned.
290
291In case of error, a hash containing the "error" key will be
292returned.  The corresponding value will be an appropriate error
293message.
294
295If a reference to a scalar is passed as an argument to this function,
296then it is assumed that this scalar contains the raw image data
297directly.
298
299The C<image_info()> function also take optional key/value style arguments
300that can influence what information is returned.
301
302=item image_type( $file )
303
304=item image_type( \$imgdata )
305
306Returns a hash with only one key, C<< file_type >>. The value
307will be the type of the file. On error, sets the two keys
308C<< error >> and C<< Errno >>.
309
310This function is a dramatically faster alternative to the image_info
311function for situations in which you B<only> need to find the image type.
312
313It uses only the internal file-type detection to do this, and thus does
314not need to load any of the image type-specific driver modules, and does
315not access to entire file. It also only needs access to the first 11
316bytes of the file.
317
318To maintain some level of compatibility with image_info, image_type
319returns in the same format, with the same error message style. That is,
320it returns a HASH reference, with the C<< $type->{error} >> key set if
321there was an error.
322
323On success, the HASH reference will contain the single key C<< file_type >>,
324which represents the type of the file, expressed as the type code used for
325the various drivers ('GIF', 'JPEG', 'TIFF' and so on).
326
327If there are multiple images within the file they will be ignored, as this
328function provides only the type of the overall file, not of the various
329images within it. This function will not return multiple hashes if the file
330contains multiple images.
331
332Of course, in all (or at least effectively all) cases the type of the images
333inside the file is going to be the same as that of the file itself.
334
335=item dim( $info_hash )
336
337Takes an hash as returned from C<image_info()> and returns the dimensions
338($width, $height) of the image.  In scalar context returns the
339dimensions as a string.
340
341=item html_dim( $info_hash )
342
343Returns the dimensions as a string suitable for embedding directly
344into HTML or SVG <img>-tags. E.g.:
345
346   print "<img src="..." @{[html_dim($info)]}>\n";
347
348=item determine_file_format( $filedata )
349
350Determines the file format from the passed file data (a normal Perl
351scalar containing the first bytes of the file), and returns
352either undef for an unknown file format, or a string describing
353the format, like "BMP" or "JPEG".
354
355=back
356
357=head1 Image descriptions
358
359The C<image_info()> function returns meta information about each image in
360the form of a reference to a hash.  The hash keys used are in most
361cases based on the TIFF element names.  All lower case keys are
362mandatory for all file formats and will always be there unless an
363error occurred (in which case the "error" key will be present.)  Mixed
364case keys will only be present when the corresponding information
365element is available in the image.
366
367The following key names are common for any image format:
368
369=over
370
371=item file_media_type
372
373This is the MIME type that is appropriate for the given file format.
374The corresponding value is a string like: "image/png" or "image/jpeg".
375
376=item file_ext
377
378The is the suggested file name extension for a file of the given file
379format.  The value is a 3 letter, lowercase string like "png", "jpg".
380
381=item width
382
383This is the number of pixels horizontally in the image.
384
385=item height
386
387This is the number of pixels vertically in the image.  (TIFF uses the
388name ImageLength for this field.)
389
390=item color_type
391
392The value is a short string describing what kind of values the pixels
393encode.  The value can be one of the following:
394
395  Gray
396  GrayA
397  RGB
398  RGBA
399  CMYK
400  YCbCr
401  CIELab
402
403These names can also be prefixed by "Indexed-" if the image is
404composed of indexes into a palette.  Of these, only "Indexed-RGB" is
405likely to occur.
406
407It is similar to the TIFF field "PhotometricInterpretation", but this
408name was found to be too long, so we used the PNG inspired term
409instead.
410
411=item resolution
412
413The value of this field normally gives the physical size of the image
414on screen or paper. When the unit specifier is missing then this field
415denotes the squareness of pixels in the image.
416
417The syntax of this field is:
418
419   <res> <unit>
420   <xres> "/" <yres> <unit>
421   <xres> "/" <yres>
422
423The <res>, <xres> and <yres> fields are numbers.  The <unit> is a
424string like C<dpi>, C<dpm> or C<dpcm> (denoting "dots per
425inch/cm/meter).
426
427=item SamplesPerPixel
428
429This says how many channels there are in the image.  For some image
430formats this number might be higher than the number implied from the
431C<color_type>.
432
433=item BitsPerSample
434
435This says how many bits are used to encode each of samples.  The value
436is a reference to an array containing numbers. The number of elements
437in the array should be the same as C<SamplesPerPixel>.
438
439=item Comment
440
441Textual comments found in the file.  The value is a reference to an
442array if there are multiple comments found.
443
444=item Interlace
445
446If the image is interlaced, then this tells which interlace method is
447used.
448
449=item Compression
450
451This tells you which compression algorithm is used.
452
453=item Gamma
454
455A number.
456
457=item LastModificationTime
458
459A ISO date string
460
461=back
462
463=head1 Supported Image Formats
464
465The following image file formats are supported:
466
467=over
468
469
470=item BMP
471
472This module supports the Microsoft Device Independent Bitmap format
473(BMP, DIB, RLE).
474
475For more information see L<Image::Info::BMP>.
476
477=item GIF
478
479Both GIF87a and GIF89a are supported and the version number is found
480as C<GIF_Version> for the first image.  GIF files can contain multiple
481images, and information for all images will be returned if
482image_info() is called in list context.  The Netscape-2.0 extension to
483loop animation sequences is represented by the C<GIF_Loop> key for the
484first image.  The value is either "forever" or a number indicating
485loop count.
486
487=item ICO
488
489This module supports the Microsoft Windows Icon Resource format
490(.ico).
491
492=item JPEG
493
494For JPEG files we extract information both from C<JFIF> and C<Exif>
495application chunks.
496
497C<Exif> is the file format written by most digital cameras. This
498encode things like timestamp, camera model, focal length, exposure
499time, aperture, flash usage, GPS position, etc.
500
501The C<Exif> spec can be found at:
502L<http://www.exif.org/specifications.html>.
503
504The C<color_type> element may have the following values: C<Gray>,
505C<YCbCr>, and C<CMYK>. Note that detecting C<RGB> and C<YCCK>
506currently does not work, but will hopefully in future.
507
508=item PNG
509
510Information from IHDR, PLTE, gAMA, pHYs, tEXt, tIME chunks are
511extracted.  The sequence of chunks are also given by the C<PNG_Chunks>
512key.
513
514=item PBM/PGM/PPM
515
516All information available is extracted.
517
518=item SVG
519
520Provides a plethora of attributes and metadata of an SVG vector graphic.
521
522=item TIFF
523
524The C<TIFF> spec can be found at:
525L<http://partners.adobe.com/public/developer/tiff/>
526
527The EXIF spec can be found at:
528L<http://www.exif.org/specifications.html>
529
530=item WBMP
531
532wbmp files have no magic, so cannot be used with the normal
533Image::Info functions. See L<Image::Info::WBMP> for more information.
534
535=item WEBP
536
537VP8 (lossy), VP8L (lossless) and VP8X (extended) files are supported.
538Sets the key C<Animation> to true if the file is an animation. Otherwise
539sets the key C<Compression> to either C<VP8> or C<Lossless>.
540
541=item XBM
542
543See L<Image::Info::XBM> for details.
544
545=item XPM
546
547See L<Image::Info::XPM> for details.
548
549=back
550
551=head1 CAVEATS
552
553While this module is fine for parsing basic image information like
554image type, dimensions and color depth, it is probably not good enough
555for parsing out more advanced information like EXIF data. If you want
556an up-to-date and tested EXIF parsing library, please use
557L<Image::ExifTool>.
558
559=head1 SEE ALSO
560
561L<Image::Size>, L<Image::ExifTool>
562
563=head1 AUTHORS
564
565Copyright 1999-2004 Gisle Aas.
566
567See the CREDITS file for a list of contributors and authors.
568
569Tels - (c) 2006 - 2008.
570
571Current maintainer: Slaven Rezic - (c) 2008 - 2015.
572
573=head1 LICENSE
574
575This library is free software; you can redistribute it and/or
576modify it under the same terms as Perl v5.8.8 itself.
577
578=cut
579
580# Local Variables:
581# mode: cperl
582# End:
583