GSP
Quick Navigator

Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Support
Contact Us
Online Help
Handbooks
Domain Status
Man Pages

FAQ
Virtual Servers
Pricing
Billing
Technical

Network
Facilities
Connectivity
Topology Map

Miscellaneous
Server Agreement
Year 2038
Credits
 

USA Flag

 

 

Man Pages


Manual Reference Pages  -  IMAGE::INFO (3)

.ds Aq ’

NAME

Image::Info - Extract meta information from image files

CONTENTS

SYNOPSIS



 use Image::Info qw(image_info dim);

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

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

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



DESCRIPTION

This module provide functions to extract various kinds 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 an 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.

image_type( $file )
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 <B>onlyB> 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 an 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 extension 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 uses 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:



   <res> <unit>
   <xres> "/" <yres> <unit>
   <xres> "/" <yres>



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 tells 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 extension 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.
ICO This module supports the Microsoft Windows Icon Resource format (.ico).
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 Exif spec can be found at: <http://www.exif.org/specifications.html>.

The color_type element may have the following values: Gray, YCbCr, and CMYK. Note that detecting RGB and YCCK currently does not work, but will hopefully in future.

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/specifications.html>

WBMP wbmp files have no magic, so cannot be used with the normal Image::Info functions. See Image::Info::WBMP for more information.
XBM See Image::Info::XBM for details.
XPM See Image::Info::XPM for details.

CAVEATS

While this module is fine for parsing basic image information like image type, dimensions and color depth, it is probably not good enough for parsing out more advanced information like EXIF data. If you want an up-to-date and tested EXIF parsing library, please use Image::ExifTool.

SEE ALSO

Image::Size, Image::ExifTool

AUTHORS

Copyright 1999-2004 Gisle Aas.

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

Tels - (c) 2006 - 2008.

Current maintainer: Slaven Rezic - (c) 2008 - 2015.

LICENSE

This library is free software; you can redistribute it and/or modify it under the same terms as Perl v5.8.8 itself.
Search for    or go to Top of page |  Section 3 |  Main Index


perl v5.20.3 IMAGE::INFO (3) 2015-04-20

Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with manServer 1.07.