lib/Image/Info.pm

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