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