Ubuntu Manpage: Image::Info - Extract meta information from image files (DEPRECATED)

Provided by: libimage-info-perl_1.28-1.1_all

NAME

       Image::Info - Extract meta information from image files (DEPRECATED)

SYNOPSIS

        use Image::Info qw(image_info dim);

        my $info = image_info("image.jpg");
        if (my $error = $info->{error}) {
            die "Can't parse image info: $error\n";
        }
        my $color = $info->{color_type};

        my $type = image_type("image.jpg");
        if (my $error = $type->{error}) {
            die "Can't determine file type: $error\n";
        }
        die "No gif files allowed!" if $type->{file_type} eq 'GIF';

        my($w, $h) = dim($info);

DESCRIPTION

       Please note that this module is deprecated and should not be used.  Alternatively, try one of the
       following modules:

       Image::Size, Image::ExifTool.

       The code in this module is old, unreviewed, hackish, still has numerous bugs and is incomplete in quite a
       few cases.

       While this module is sort-of maintained (e.g. the most critical security-related bugs are fixed), no new
       features will be added and numerous minor bugs are very likely sprinkled through the entire code base.
       You have been warned.

       This module provide functions to extract various kind of meta information from image files.

   EXPORTS
       Exports nothing by default, but can export the following methods on request:

               image_info
               image_type
               dim
               html_dim
               determine_file_type

   METHODS
       The following functions are provided by the "Image::Info" module:

       image_info( $file )
       image_info( \$imgdata )
       image_info( $file, key => value,... )
           This  function  takes  the  name  of  a file or a file handle as argument and will return one or more
           hashes (actually hash references) describing the images inside the file.  If there is only one  image
           in  the  file  only  one  hash  is returned.  In scalar context, only the hash for the first image is
           returned.

           In case of error, a hash containing the "error" key will be returned.  The corresponding  value  will
           be an appropriate error message.

           If  a  reference  to  a  scalar  is passed as argument to this function, then it is assumed that this
           scalar contains the raw image data directly.

           The image_info() function also take optional  key/value  style  arguments  that  can  influence  what
           information  is  returned.  See  Image::Info::XPM and other Image::Info submodules for the parameters
           that they take.

       image_type( \$imgdata )
           Returns a hash with only one key, "file_type". The value will be the type of the file. On error, sets
           the two keys "error" and "Errno".

           This function is a dramatically faster alternative to the image_info function for situations in which
           you only need to find the image type.

           It uses only the internal file-type detection to do this, and thus does not need to load any  of  the
           image  type-specific driver modules, and does not access to entire file. It also only needs access to
           the first 11 bytes of the file.

           To maintain some level of compatibility with image_info, image_type returns in the same format,  with
           the same error message style. That is, it returns a HASH reference, with the "$type->{error}" key set
           if there was an error.

           On  success, the HASH reference will contain the single key 'file_type', which represents the type of
           the file, expressed as the type code used for the various drivers ('GIF', 'JPEG', 'TIFF' and so on).

           If there are multiple images within the file they will be ignored, as this function provides only the
           type of the overall file, not of the various images within it. This function will not return multiple
           hashes if the file contains multiple images.

           Of course, in all (or at least effectively all) cases the type of the images inside the file is going
           to be the same as that of the file itself.

       dim( $info_hash )
           Takes a hash as returned from image_info() and returns the dimensions ($width, $height) of the image.
           In scalar context returns the dimensions as a string.

       html_dim( $info_hash )
           Returns the dimensions as a string suitable for embedding directly into HTML or SVG <img>-tags. E.g.:

              print "<img src="..." @{[html_dim($info)]}>\n";

       determine_file_format( $filedata )
           Determines the file format from the passed file data (a normal Perl scalar containing the first bytes
           of the file), and returns either undef for an unknown file format, or a string describing the format,
           like "BMP" or "JPEG".

Image descriptions

The image_info() function returns meta information about each image in the form of a reference to a hash.
The hash keys used are in most cases based on the TIFF element names. All lower case keys are mandatory
for all file formats and will always be there unless an error occured (in which case the "error" key will
be present.) Mixed case keys will only be present when the corresponding information element is
available in the image.

The following key names are common for any image format:

file_media_type
This is the MIME type that is appropriate for the given file format. The corresponding value is a
string like: "image/png" or "image/jpeg".

file_ext
The is the suggested file name extention for a file of the given file format. The value is a 3
letter, lowercase string like "png", "jpg".

width
This is the number of pixels horizontally in the image.

height
This is the number of pixels vertically in the image. (TIFF use the name ImageLength for this
field.)

color_type
The value is a short string describing what kind of values the pixels encode. The value can be one
of the following:

Gray
GrayA
RGB
RGBA
CMYK
YCbCr
CIELab

These names can also be prefixed by "Indexed-" if the image is composed of indexes into a palette.
Of these, only "Indexed-RGB" is likely to occur.

It is similar to the TIFF field PhotometricInterpretation, but this name was found to be too long, so
we used the PNG inpired term instead.

resolution
The value of this field normally gives the physical size of the image on screen or paper. When the
unit specifier is missing then this field denotes the squareness of pixels in the image.

The syntax of this field is:

The <res>, <xres> and <yres> fields are numbers. The <unit> is a string like "dpi", "dpm" or "dpcm"
(denoting "dots per inch/cm/meter).

SamplesPerPixel
This says how many channels there are in the image. For some image formats this number might be
higher than the number implied from the "color_type".

BitsPerSample
This says how many bits are used to encode each of samples. The value is a reference to an array
containing numbers. The number of elements in the array should be the same as "SamplesPerPixel".

Comment
Textual comments found in the file. The value is a reference to an array if there are multiple
comments found.

Interlace
If the image is interlaced, then this tell which interlace method is used.

Compression
This tells you which compression algorithm is used.

Gamma
A number.

LastModificationTime
A ISO date string

Supported Image Formats

The following image file formats are supported:

BMP This module supports the Microsoft Device Independent Bitmap format (BMP, DIB, RLE).

For more information see Image::Info::BMP.

GIF Both GIF87a and GIF89a are supported and the version number is found as "GIF_Version" for the first
image. GIF files can contain multiple images, and information for all images will be returned if
image_info() is called in list context. The Netscape-2.0 extention to loop animation sequences is
represented by the "GIF_Loop" key for the first image. The value is either "forever" or a number
indicating loop count.

JPEG
For JPEG files we extract information both from "JFIF" and "Exif" application chunks.

"Exif" is the file format written by most digital cameras. This encode things like timestamp, camera
model, focal length, exposure time, aperture, flash usage, GPS position, etc. The following web page
contain description of the fields that can be present:

http://www.ba.wakwak.com/~tsuruzoh/Computer/Digicams/exif-e.html

The "Exif" spec can be found at:

http://www.exif.org/specifications.html

PNG Information from IHDR, PLTE, gAMA, pHYs, tEXt, tIME chunks are extracted. The sequence of chunks are
also given by the "PNG_Chunks" key.

PBM/PGM/PPM
All information available is extracted.

SVG Provides a plethora of attributes and metadata of an SVG vector grafic.

TIFF
The "TIFF" spec can be found at: <http://partners.adobe.com/public/developer/tiff/>

The EXIF spec can be found at: <http://www.exif.org/>

XBM See Image::Info::XBM for details.

XPM See Image::Info::XPM for details.

CAVEATS

       Note that while the module is still maintained, no new features will be added and  numerous  bugs  remain
       throughout the code base.

       Especially  the  EXIF  parsing  code  is  buggy,  not  tested  at  all,  and  quite  incomplete (a lot of
       manufacturer's MakerNotes and tags are not parsed at all). If you want a stable, feature-complete, up-to-
       date and tested EXIF parsing library, please use Image::ExifTool.

       Likewise, the image parsing code is quite hackish and seems to contain an endless  supply  of  bugs  that
       crash, or hang with malformed input.

AUTHORS

       Copyright 1999-2004 Gisle Aas.

       See the CREDITS file for a list of contributors and authors.

       Now maintained by Tels - (c) 2006 - 2008.

LICENSE

       This  library  is  free  software;  you can redistribute it and/or modify it under the same terms as Perl
       v5.8.8 itself.

perl v5.20.2                                       2015-10-24                                   Image::Info(3pm)