Info.pm.tmpl

   1 package Image::Info;
   2
   3 # Copyright 1999-2002, Gisle Aas.
   4 #
   5 # This library is free software; you can redistribute it and/or
   6 # modify it under the same terms as Perl itself.
   7
   8 use strict;
   9 use Symbol ();
  10
  11 use vars qw($VERSION @EXPORT_OK);
  12
  13 $VERSION = '1.12';
  14
  15 require Exporter;
  16 *import = \&Exporter::import;
  17
  18 @EXPORT_OK = qw(image_info dim html_dim);
  19
  20 sub image_info
  21 {
  22     my($source, %cnf) = @_;
  23
  24     if (!ref $source) {
  25         require Symbol;
  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
  29         binmode($fh);
  30         $source = $fh;
  31     }
  32     elsif (ref($source) eq "SCALAR") {
  33         require IO::String;
  34         $source = IO::String->new($$source);
  35     }
  36     else {
  37         seek($source, 0, 0) or return _os_err("Can't rewind");
  38     }
  39
  40     my $head;
  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
  44         $source->setpos(0);
  45     }
  46     else {
  47         seek($source, 0, 0) or _os_err("Can't rewind");
  48     }
  49
  50     if (my $format = determine_file_format($head)) {
  51         no strict 'refs';
  52         my $mod = "Image::Info::$format";
  53         my $sub = "$mod\::process_file";
  54         my $info = bless [], "Image::Info::Result";
  55         eval {
  56             unless (defined &$sub) {
  57                 eval "require $mod";
  58                 die $@ if $@;
  59                 die "$mod did not define &$sub" unless defined &$sub;
  60             }
  61
  62             &$sub($info, $source, \%cnf);
  63             $info->clean_up;
  64         };
  65         return { error => $@ } if $@;
  66         return wantarray ? @$info : $info->[0];
  67     }
  68     return { error => "Unrecognized file format" };
  69 }
  70
  71 sub _os_err
  72 {
  73     return { error => "$_[0]: $!",
  74              Errno => $!+0,
  75            };
  76 }
  77
  78 %%DETERMINE_FILE_FORMAT%%
  79
  80 sub dim
  81 {
  82     my $img = shift || return;
  83     my $x = $img->{width} || return;
  84     my $y = $img->{height} || return;
  85     wantarray ? ($x, $y) : "${x}x$y";
  86 }
  87
  88 sub html_dim
  89 {
  90     my($x, $y) = dim(@_);
  91     return "" unless $x;
  92     "WIDTH=$x HEIGHT=$y";
  93 }
  94
  95 package Image::Info::Result;
  96
  97 sub push_info
  98 {
  99     my($self, $n, $key) = splice(@_, 0, 3);
 100     push(@{$self->[$n]{$key}}, @_);
 101 }
 102
 103 sub clean_up
 104 {
 105     my $self = shift;
 106     for (@$self) {
 107         for my $k (keys %$_) {
 108             my $a = $_->{$k};
 109             $_->{$k} = $a->[0] if @$a <= 1;
 110         }
 111     }
 112 }
 113
 114 sub get_info {
 115     my($self, $n, $key, $delete) = @_;
 116     my $v = $delete ? delete $self->[$n]{$key} : $self->[$n]{$key};
 117     $v ||= [];
 118     @$v;
 119 }
 120
 121 1;
 122
 123 __END__
 124
 125 =head1 NAME
 126
 127 Image::Info - Extract meta information from image files
 128
 129 =head1 SYNOPSIS
 130
 131  use Image::Info qw(image_info dim);
 132
 133  my $info = image_info("image.jpg");
 134  if (my $error = $info->{error}) {
 135      die "Can't parse image info: $error\n";
 136  }
 137  my $color = $info->{color_type};
 138
 139  my($w, $h) = dim($info);
 140
 141 =head1 DESCRIPTION
 142
 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:
 146
 147 =over
 148
 149 =item image_info( $file )
 150
 151 =item image_info( \$imgdata )
 152
 153 =item image_info( $file, key => value,... )
 154
 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.
 160
 161 In case of error, and hash containing the "error" key will be
 162 returned.  The corresponding value will be an appropriate error
 163 message.
 164
 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
 167 directly.
 168
 169 The image_info() function also take optional key/value style arguments
 170 that can influence what information is returned.
 171
 172 =item dim( $info_hash )
 173
 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.
 177
 178 =item html_dim( $info_hash )
 179
 180 Returns the dimensions as a string suitable for embedding directly
 181 into HTML <img>-tags. E.g.:
 182
 183    print "<img src="..." @{[html_dim($info)]}>\n";
 184
 185 =back
 186
 187 =head1 Image descriptions
 188
 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.
 196
 197 The following key names are common for any image format:
 198
 199 =over
 200
 201 =item file_media_type
 202
 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".
 205
 206 =item file_ext
 207
 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".
 210
 211 =item width
 212
 213 This is the number of pixels horizontally in the image.
 214
 215 =item height
 216
 217 This is the number of pixels vertically in the image.  (TIFF use the
 218 name ImageLength for this field.)
 219
 220 =item color_type
 221
 222 The value is a short string describing what kind of values the pixels
 223 encode.  The value can be one of the following:
 224
 225   Gray
 226   GrayA
 227   RGB
 228   RGBA
 229   CMYK
 230   YCbCr
 231   CIELab
 232
 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
 235 likely to occur.
 236
 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
 239 instead.)
 240
 241 =item resolution
 242
 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.
 246
 247 The syntax of this field is:
 248
 249    <res> <unit>
 250    <xres> "/" <yres> <unit>
 251    <xres> "/" <yres>
 252
 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
 255 inch/cm/meter).
 256
 257 =item SamplesPerPixel
 258
 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
 261 C<color_type>.
 262
 263 =item BitsPerSample
 264
 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>.
 268
 269 =item Comment
 270
 271 Textual comments found in the file.  The value is a reference to an
 272 array if there are multiple comments found.
 273
 274 =item Interlace
 275
 276 If the image is interlaced, then this tell which interlace method is
 277 used.
 278
 279 =item Compression
 280
 281 This tell which compression algorithm is used.
 282
 283 =item Gamma
 284
 285 A number.
 286
 287 =item LastModificationTime
 288
 289 A ISO date string
 290
 291 =back
 292
 293 =head1 Supported Image Formats
 294
 295 The following image file formats are currently supported:
 296
 297 =over
 298
 299 %%FORMAT_DESC%%
 300
 301 =back
 302
 303 =head1 SEE ALSO
 304
 305 L<Image::Size>
 306
 307 =head1 AUTHORS
 308
 309 Copyright 1999-2001 Gisle Aas.
 310
 311 GIF fixes by Ralf Steines <metamonk@yahoo.com>.
 312
 313 ASCII, BMP SVG, XPM and XBM support added by Jerrad Pierce
 314 <belg4mit@mit.edu>/<webmaster@pthbb.org>.
 315
 316 Exif MakerNote decoding by Jay Soffian <jay@loudcloud.com>.
 317
 318 TIFF support by <clarsen@emf.net>.
 319
 320 This library is free software; you can redistribute it and/or
 321 modify it under the same terms as Perl itself.
 322
 323 =cut