lib/Image/Info.pm

   1 # This file is autogenerated from Info.pm.tmpl.
   2 # Please do not edit!!
   3
   4 package Image::Info;
   5
   6 # Copyright 1999-2003, Gisle Aas.
   7 #
   8 # This library is free software; you can redistribute it and/or
   9 # modify it under the same terms as Perl itself.
  10
  11 use strict;
  12 use Symbol ();
  13
  14 use vars qw($VERSION @EXPORT_OK);
  15
  16 $VERSION = '1.15';
  17
  18 require Exporter;
  19 *import = \&Exporter::import;
  20
  21 @EXPORT_OK = qw(image_info dim html_dim);
  22
  23 my %mod_failure;
  24
  25 sub image_info
  26 {
  27     my($source, %cnf) = @_;
  28
  29     if (!ref $source) {
  30         require Symbol;
  31         my $fh = Symbol::gensym();
  32         open($fh, $source) || return _os_err("Can't open $source");
  33         ${*$fh} = $source;  # keep filename in case somebody wants to know
  34         binmode($fh);
  35         $source = $fh;
  36     }
  37     elsif (ref($source) eq "SCALAR") {
  38         if ($] >= 5.008) {
  39             open(my $s, "<", $source) or return _os_err("Can't open string");
  40             $source = $s;
  41         }
  42         else {
  43             require IO::String;
  44             $source = IO::String->new($$source);
  45         }
  46     }
  47     else {
  48         seek($source, 0, 0) or return _os_err("Can't rewind");
  49     }
  50
  51     my $head;
  52     read($source, $head, 32) or return _os_err("Can't read head");
  53     if (ref($source) eq "IO::String") {
  54         # XXX workaround until we can trap seek() with a tied file handle
  55         $source->setpos(0);
  56     }
  57     else {
  58         seek($source, 0, 0) or _os_err("Can't rewind");
  59     }
  60
  61     if (my $format = determine_file_format($head)) {
  62         no strict 'refs';
  63         my $mod = "Image::Info::$format";
  64         my $sub = "$mod\::process_file";
  65         my $info = bless [], "Image::Info::Result";
  66         eval {
  67             unless (defined &$sub) {
  68                 if (my $fail = $mod_failure{$mod}) {
  69                     die $fail;
  70                 }
  71                 eval "require $mod";
  72                 if ($@) {
  73                     $mod_failure{$mod} = $@;
  74                     die $@;
  75                 }
  76                 die "$mod did not define &$sub" unless defined &$sub;
  77             }
  78
  79             &$sub($info, $source, \%cnf);
  80             $info->clean_up;
  81         };
  82         return { error => $@ } if $@;
  83         return wantarray ? @$info : $info->[0];
  84     }
  85     return { error => "Unrecognized file format" };
  86 }
  87
  88 sub _os_err
  89 {
  90     return { error => "$_[0]: $!",
  91              Errno => $!+0,
  92            };
  93 }
  94
  95 sub determine_file_format
  96 {
  97    local($_) = @_;
  98    return "BMP" if /^BM/;
  99    return "GIF" if /^GIF8[79]a/;
 100    return "JPEG" if /^\xFF\xD8/;
 101    return "PNG" if /^\x89PNG\x0d\x0a\x1a\x0a/;
 102    return "PPM" if /^P[1-6]/;;
 103    return "SVG" if /^<\?xml/;
 104    return "TIFF" if /^MM\x00\x2a/;
 105    return "TIFF" if /^II\x2a\x00/;
 106    return "XBM" if /^#define\s+/;
 107    return "XPM" if /(^\/\* XPM \*\/)|(static\s+char\s+\*\w+\[\]\s*=\s*{\s*"\d+)/;
 108    return undef;
 109 }
 110
 111 sub dim
 112 {
 113     my $img = shift || return;
 114     my $x = $img->{width} || return;
 115     my $y = $img->{height} || return;
 116     wantarray ? ($x, $y) : "${x}x$y";
 117 }
 118
 119 sub html_dim
 120 {
 121     my($x, $y) = dim(@_);
 122     return "" unless $x;
 123     "WIDTH=$x HEIGHT=$y";
 124 }
 125
 126 package Image::Info::Result;
 127
 128 sub push_info
 129 {
 130     my($self, $n, $key) = splice(@_, 0, 3);
 131     push(@{$self->[$n]{$key}}, @_);
 132 }
 133
 134 sub clean_up
 135 {
 136     my $self = shift;
 137     for (@$self) {
 138         for my $k (keys %$_) {
 139             my $a = $_->{$k};
 140             $_->{$k} = $a->[0] if @$a <= 1;
 141         }
 142     }
 143 }
 144
 145 sub get_info {
 146     my($self, $n, $key, $delete) = @_;
 147     my $v = $delete ? delete $self->[$n]{$key} : $self->[$n]{$key};
 148     $v ||= [];
 149     @$v;
 150 }
 151
 152 1;
 153
 154 __END__
 155
 156 =head1 NAME
 157
 158 Image::Info - Extract meta information from image files
 159
 160 =head1 SYNOPSIS
 161
 162  use Image::Info qw(image_info dim);
 163
 164  my $info = image_info("image.jpg");
 165  if (my $error = $info->{error}) {
 166      die "Can't parse image info: $error\n";
 167  }
 168  my $color = $info->{color_type};
 169
 170  my($w, $h) = dim($info);
 171
 172 =head1 DESCRIPTION
 173
 174 This module provide functions to extract various kind of meta
 175 information from image files.  The following functions are provided by
 176 the C<Image::Info> module:
 177
 178 =over
 179
 180 =item image_info( $file )
 181
 182 =item image_info( \$imgdata )
 183
 184 =item image_info( $file, key => value,... )
 185
 186 This function takes the name of a file or a file handle as argument
 187 and will return one or more hashes (actually hash references)
 188 describing the images inside the file.  If there is only one image in
 189 the file only one hash is returned.  In scalar context, only the hash
 190 for the first image is returned.
 191
 192 In case of error, and hash containing the "error" key will be
 193 returned.  The corresponding value will be an appropriate error
 194 message.
 195
 196 If a reference to a scalar is passed as argument to this function,
 197 then it is assumed that this scalar contains the raw image data
 198 directly.
 199
 200 The image_info() function also take optional key/value style arguments
 201 that can influence what information is returned.
 202
 203 =item dim( $info_hash )
 204
 205 Takes an hash as returned from image_info() and returns the dimensions
 206 ($width, $height) of the image.  In scalar context returns the
 207 dimensions as a string.
 208
 209 =item html_dim( $info_hash )
 210
 211 Returns the dimensions as a string suitable for embedding directly
 212 into HTML <img>-tags. E.g.:
 213
 214    print "<img src="..." @{[html_dim($info)]}>\n";
 215
 216 =back
 217
 218 =head1 Image descriptions
 219
 220 The image_info() function returns meta information about each image in
 221 the form of a reference to a hash.  The hash keys used are in most
 222 cases based on the TIFF element names.  All lower case keys are
 223 mandatory for all file formats and will always be there unless an
 224 error occured (in which case the "error" key will be present.)  Mixed
 225 case keys will only be present when the corresponding information
 226 element is available in the image.
 227
 228 The following key names are common for any image format:
 229
 230 =over
 231
 232 =item file_media_type
 233
 234 This is the MIME type that is appropriate for the given file format.
 235 The corresponding value is a string like: "image/png" or "image/jpeg".
 236
 237 =item file_ext
 238
 239 The is the suggested file name extention for a file of the given file
 240 format.  The value is a 3 letter, lowercase string like "png", "jpg".
 241
 242 =item width
 243
 244 This is the number of pixels horizontally in the image.
 245
 246 =item height
 247
 248 This is the number of pixels vertically in the image.  (TIFF use the
 249 name ImageLength for this field.)
 250
 251 =item color_type
 252
 253 The value is a short string describing what kind of values the pixels
 254 encode.  The value can be one of the following:
 255
 256   Gray
 257   GrayA
 258   RGB
 259   RGBA
 260   CMYK
 261   YCbCr
 262   CIELab
 263
 264 These names can also be prefixed by "Indexed-" if the image is
 265 composed of indexes into a palette.  Of these, only "Indexed-RGB" is
 266 likely to occur.
 267
 268 (It is similar to the TIFF field PhotometricInterpretation, but this
 269 name was found to be too long, so we used the PNG inpired term
 270 instead.)
 271
 272 =item resolution
 273
 274 The value of this field normally gives the physical size of the image
 275 on screen or paper. When the unit specifier is missing then this field
 276 denotes the squareness of pixels in the image.
 277
 278 The syntax of this field is:
 279
 280    <res> <unit>
 281    <xres> "/" <yres> <unit>
 282    <xres> "/" <yres>
 283
 284 The <res>, <xres> and <yres> fields are numbers.  The <unit> is a
 285 string like C<dpi>, C<dpm> or C<dpcm> (denoting "dots per
 286 inch/cm/meter).
 287
 288 =item SamplesPerPixel
 289
 290 This says how many channels there are in the image.  For some image
 291 formats this number might be higher than the number implied from the
 292 C<color_type>.
 293
 294 =item BitsPerSample
 295
 296 This says how many bits are used to encode each of samples.  The value
 297 is a reference to an array containing numbers. The number of elements
 298 in the array should be the same as C<SamplesPerPixel>.
 299
 300 =item Comment
 301
 302 Textual comments found in the file.  The value is a reference to an
 303 array if there are multiple comments found.
 304
 305 =item Interlace
 306
 307 If the image is interlaced, then this tell which interlace method is
 308 used.
 309
 310 =item Compression
 311
 312 This tell which compression algorithm is used.
 313
 314 =item Gamma
 315
 316 A number.
 317
 318 =item LastModificationTime
 319
 320 A ISO date string
 321
 322 =back
 323
 324 =head1 Supported Image Formats
 325
 326 The following image file formats are currently supported:
 327
 328 =over
 329
 330
 331 =item BMP
 332
 333 This module supports the Microsoft Device Independent Bitmap format
 334 (BMP, DIB, RLE).
 335
 336 For more information see L<Image::Info::BMP>.
 337
 338 =item GIF
 339
 340 Both GIF87a and GIF89a are supported and the version number is found
 341 as C<GIF_Version> for the first image.  GIF files can contain multiple
 342 images, and information for all images will be returned if
 343 image_info() is called in list context.  The Netscape-2.0 extention to
 344 loop animation sequences is represented by the C<GIF_Loop> key for the
 345 first image.  The value is either "forever" or a number indicating
 346 loop count.
 347
 348 =item JPEG
 349
 350 For JPEG files we extract information both from C<JFIF> and C<Exif>
 351 application chunks.
 352
 353 C<Exif> is the file format written by most digital cameras.  This
 354 encode things like timestamp, camera model, focal length, exposure
 355 time, aperture, flash usage, GPS position, etc.  The following web
 356 page contain description of the fields that can be present:
 357
 358  http://www.ba.wakwak.com/~tsuruzoh/Computer/Digicams/exif-e.html
 359
 360 The C<Exif> spec can be found at:
 361
 362  http://www.pima.net/standards/it10/PIMA15740/exif.htm
 363
 364 =item PNG
 365
 366 Information from IHDR, PLTE, gAMA, pHYs, tEXt, tIME chunks are
 367 extracted.  The sequence of chunks are also given by the C<PNG_Chunks>
 368 key.
 369
 370 =item PBM/PGM/PPM
 371
 372 All information available is extracted.
 373
 374 =item SVG
 375
 376 SVG also provides (for) a plethora of attributes and metadata of an image.
 377 See L<Image::Info::SVG> for details.
 378
 379 =item TIFF
 380
 381 The C<TIFF> spec can be found at:
 382 http://partners.adobe.com/asn/developer/PDFS/TN/TIFF6.pdf
 383
 384 Also good writeup on exif spec at:
 385 http://www.ba.wakwak.com/~tsuruzoh/Computer/Digicams/exif-e.html
 386
 387 =item TIFF
 388
 389 =item XBM
 390
 391 See L<Image::Info::XBM> for details.
 392
 393 =item XPM
 394
 395 See L<Image::Info::XPM> for details.
 396
 397 =back
 398
 399 =head1 SEE ALSO
 400
 401 L<Image::Size>
 402
 403 =head1 AUTHORS
 404
 405 Copyright 1999-2001 Gisle Aas.
 406
 407 GIF fixes by Ralf Steines <metamonk@yahoo.com>.
 408
 409 ASCII, BMP SVG, XPM and XBM support added by Jerrad Pierce
 410 <belg4mit@mit.edu>/<webmaster@pthbb.org>.
 411
 412 Exif MakerNote decoding by Jay Soffian <jay@loudcloud.com>.
 413
 414 TIFF support by <clarsen@emf.net>.
 415
 416 This library is free software; you can redistribute it and/or
 417 modify it under the same terms as Perl itself.
 418
 419 =cut