Info.pm.tmpl

   1 package Image::Info;
   2
   3 # Copyright 1999-2000, 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.02';  # $Date: 2000/11/10 18:17:32 $
  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 = shift;
  23
  24     if (@_) {
  25         return { error => "Extra arguments reserved for future extensions" };
  26     }
  27
  28     if (!ref $source) {
  29         require Symbol;
  30         my $fh = Symbol::gensym();
  31         open($fh, $source) || return _os_err("Can't open $source");
  32         binmode($fh);
  33         $source = $fh;
  34     }
  35     elsif (ref($source) eq "SCALAR") {
  36         require IO::String;
  37         $source = IO::String->new($$source);
  38     }
  39     else {
  40         seek($source, 0, 0) or return _os_err("Can't rewind");
  41     }
  42
  43     my $head;
  44     read($source, $head, 32) == 32 or return _os_err("Can't read head");
  45     if (ref($source) eq "IO::String") {
  46         # XXX workaround until we can trap seek() with a tied file handle
  47         $source->setpos(0);
  48     }
  49     else {
  50         seek($source, 0, 0) or _os_err("Can't rewind");
  51     }
  52
  53     if (my $format = determine_file_format($head)) {
  54         no strict 'refs';
  55         my $mod = "Image::Info::$format";
  56         my $sub = "$mod\::process_file";
  57         my $info = bless [], "Image::Info::Result";
  58         eval {
  59             unless (defined &$sub) {
  60                 eval "require $mod";
  61                 die $@ if $@;
  62                 die "$mod did not define &$sub" unless defined &$sub;
  63             }
  64
  65             &$sub($info, $source, @_);
  66             $info->clean_up;
  67         };
  68         return { error => $@ } if $@;
  69         return wantarray ? @$info : $info->[0];
  70     }
  71     return { error => "Unrecognized file format" };
  72 }
  73
  74 sub _os_err
  75 {
  76     return { error => "$_[0]: $!",
  77              Errno => $!+0,
  78            };
  79 }
  80
  81 %%DETERMINE_FILE_FORMAT%%
  82
  83 sub dim
  84 {
  85     my $img = shift || return;
  86     my $x = $img->{width} || return;
  87     my $y = $img->{height} || return;
  88     wantarray ? ($x, $y) : "${x}x$y";
  89 }
  90
  91 sub html_dim
  92 {
  93     my($x, $y) = dim($_);
  94     return unless $x;
  95     "WIDTH=$x HEIGHT=$y";
  96 }
  97
  98 package Image::Info::Result;
  99
 100 sub push_info
 101 {
 102     my($self, $n, $key) = splice(@_, 0, 3);
 103     push(@{$self->[$n]{$key}}, @_);
 104 }
 105
 106 sub clean_up
 107 {
 108     my $self = shift;
 109     for (@$self) {
 110         for my $k (keys %$_) {
 111             my $a = $_->{$k};
 112             $_->{$k} = $a->[0] if @$a <= 1;
 113         }
 114     }
 115 }
 116
 117 sub get_info {
 118     my($self, $n, $key, $delete) = @_;
 119     my $v = $delete ? delete $self->[$n]{$key} : $self->[$n]{$key};
 120     $v ||= [];
 121     @$v;
 122 }
 123
 124 1;
 125
 126 __END__
 127
 128 =head1 NAME
 129
 130 Image::Info - Extract meta information from image files
 131
 132 =head1 SYNOPSIS
 133
 134  use Image::Info qw(image_info dim);
 135
 136  my $info = image_info("image.jpg");
 137  if (my $error = $info->{error}) {
 138      die "Can't parse image info: $error\n";
 139  }
 140  my $color = $info->{color_type};
 141
 142  my($w, $h) = dim($info);
 143
 144 =head1 DESCRIPTION
 145
 146 This module provide functions to extract various kind of meta
 147 information from image files.  The following functions are provided by
 148 the C<Image::Info> module:
 149
 150 =over
 151
 152 =item image_info( $file )
 153
 154 =item image_info( \$imgdata )
 155
 156 This function takes the name of a file or a file handle as argument
 157 and will return one or more hashes (actually hash references)
 158 describing the images inside the file.  If there is only one image in
 159 the file only one hash is returned.  In scalar context, only the hash
 160 for the first image is returned.
 161
 162 In case of error, and hash containing the "error" key will be
 163 returned.  The corresponding value will be an appropriate error
 164 message.
 165
 166 If a reference to a scalar is passed as argument to this function,
 167 then it is assumed that this scalar contains the raw image data
 168 directly.
 169
 170 =item dim( $info_hash )
 171
 172 Takes an hash as returned from image_info() and returns the dimensions
 173 ($width, $height) of the image.  In scalar context returns the
 174 dimensions as a string.
 175
 176 =item html_dim( $info_hash )
 177
 178 Returns the dimensions as a string suitable for embedding directly
 179 into HTML <img>-tags. E.g.:
 180
 181    print "<img src="..." @{[html_dim($info)]}>\n";
 182
 183 =back
 184
 185 =head1 Image descriptions
 186
 187 The image_info() function returns meta information about each image in
 188 the form of a reference to a hash.  The hash keys used are in most
 189 cases based on the TIFF element names.  All lower case keys are
 190 mandatory for all file formats and will always be there unless an
 191 error occured (in which case the "error" key will be present.)  Mixed
 192 case keys will only be present when the corresponding information
 193 element is available in the image.
 194
 195 The following key names are common for any image format:
 196
 197 =over
 198
 199 =item file_media_type
 200
 201 This is the MIME type that is appropriate for the given file format.
 202 The corresponding value is a string like: "image/png" or "image/jpeg".
 203
 204 =item file_ext
 205
 206 The is the suggested file name extention for a file of the given file
 207 format.  The value is a 3 letter, lowercase string like "png", "jpg".
 208
 209 =item width
 210
 211 This is the number of pixels horizontally in the image.
 212
 213 =item height
 214
 215 This is the number of pixels vertically in the image.  (TIFF use the
 216 name ImageLength for this field.)
 217
 218 =item color_type
 219
 220 The value is a short string describing what kind of values the pixels
 221 encode.  The value can be one of the following:
 222
 223   Gray
 224   GrayA
 225   RGB
 226   RGBA
 227   CMYK
 228   YCbCr
 229   CIELab
 230
 231 These names can also be prefixed by "Indexed-" if the image is
 232 composed of indexes into a palette.  Of these, only "Indexed-RGB" is
 233 likely to occur.
 234
 235 (It is similar to the TIFF field PhotometricInterpretation, but this
 236 name was found to be too long, so we used the PNG inpired term
 237 instead.)
 238
 239 =item resolution
 240
 241 The value of this field normally gives the physical size of the image
 242 on screen or paper. When the unit specifier is missing then this field
 243 denotes the squareness of pixels in the image.
 244
 245 The syntax of this field is:
 246
 247    <res> <unit>
 248    <xres> "/" <yres> <unit>
 249    <xres> "/" <yres>
 250
 251 The <res>, <xres> and <yres> fields are numbers.  The <unit> is a
 252 string like C<dpi>, C<dpm> or C<dpcm> (denoting "dots per
 253 inch/cm/meter).
 254
 255 =item SamplesPerPixel
 256
 257 This says how many channels there are in the image.  For some image
 258 formats this number might be higher than the number implied from the
 259 C<color_type>.
 260
 261 =item BitsPerSample
 262
 263 This says how many bits are used to encode each of samples.  The value
 264 is a reference to an array containing numbers. The number of elements
 265 in the array should be the same as C<SamplesPerPixel>.
 266
 267 =item Comment
 268
 269 Textual comments found in the file.  The value is a reference to an
 270 array if there are multiple comments found.
 271
 272 =item Interlace
 273
 274 If the image is interlaced, then this tell which interlace method is
 275 used.
 276
 277 =item Compression
 278
 279 This tell which compression algorithm is used.
 280
 281 =item Gamma
 282
 283 A number.
 284
 285 =item LastModificationTime
 286
 287 A ISO date string
 288
 289 =back
 290
 291 =head1 Supported Image Formats
 292
 293 The following image file formats are currently supported:
 294
 295 =over
 296
 297 %%FORMAT_DESC%%
 298
 299 =back
 300
 301 =head1 SEE ALSO
 302
 303 L<Image::Size>
 304
 305 =head1 AUTHOR
 306
 307 Copyright 1999-2000 Gisle Aas.
 308
 309 GIF fixes by Ralf Steines <metamonk@yahoo.com>
 310
 311 SVG, X*M support added by Jerrad Pierce <belg4mit@mit.edu>/<webmaster@pthbb.org>
 312
 313 This library is free software; you can redistribute it and/or
 314 modify it under the same terms as Perl itself.
 315
 316 =cut