.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Image::Info 3"
.TH Image::Info 3 2024-09-01 "perl v5.40.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH NAME
Image::Info \- Extract meta information from image files
.SH SYNOPSIS
.IX Header "SYNOPSIS"
.Vb 1
\& use Image::Info qw(image_info dim);
\&
\& my $info = image_info("image.jpg");
\& if (my $error = $info\->{error}) {
\&     die "Can\*(Aqt parse image info: $error\en";
\& }
\& my $color = $info\->{color_type};
\& 
\& my $type = image_type("image.jpg");
\& if (my $error = $type\->{error}) {
\&     die "Can\*(Aqt determine file type: $error\en";
\& }
\& die "No gif files allowed!" if $type\->{file_type} eq \*(AqGIF\*(Aq;
\& 
\& my($w, $h) = dim($info);
.Ve
.SH DESCRIPTION
.IX Header "DESCRIPTION"
This module provides functions to extract various kinds of meta
information from image files.
.SS EXPORTS
.IX Subsection "EXPORTS"
Exports nothing by default, but can export the following methods
on request:
.PP
.Vb 5
\&        image_info
\&        image_type
\&        dim
\&        html_dim
\&        determine_file_type
.Ve
.SS METHODS
.IX Subsection "METHODS"
The following functions are provided by the \f(CW\*(C`Image::Info\*(C'\fR module:
.ie n .IP "image_info( $file )" 4
.el .IP "image_info( \f(CW$file\fR )" 4
.IX Item "image_info( $file )"
.PD 0
.IP "image_info( \e$imgdata )" 4
.IX Item "image_info( $imgdata )"
.ie n .IP "image_info( $file, key => value,... )" 4
.el .IP "image_info( \f(CW$file\fR, key => value,... )" 4
.IX Item "image_info( $file, key => value,... )"
.PD
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.
.Sp
In case of error, a hash containing the "error" key will be
returned.  The corresponding value will be an appropriate error
message.
.Sp
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.
.Sp
The \f(CWimage_info()\fR function also take optional key/value style arguments
that can influence what information is returned.
.ie n .IP "image_type( $file )" 4
.el .IP "image_type( \f(CW$file\fR )" 4
.IX Item "image_type( $file )"
.PD 0
.IP "image_type( \e$imgdata )" 4
.IX Item "image_type( $imgdata )"
.PD
Returns a hash with only one key, \f(CW\*(C`file_type\*(C'\fR. The value
will be the type of the file. On error, sets the two keys
\&\f(CW\*(C`error\*(C'\fR and \f(CW\*(C`Errno\*(C'\fR.
.Sp
This function is a dramatically faster alternative to the image_info
function for situations in which you \fBonly\fR need to find the image type.
.Sp
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.
.Sp
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 \f(CW\*(C`$type\->{error}\*(C'\fR key set if
there was an error.
.Sp
On success, the HASH reference will contain the single key \f(CW\*(C`file_type\*(C'\fR,
which represents the type of the file, expressed as the type code used for
the various drivers ('GIF', 'JPEG', 'TIFF' and so on).
.Sp
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.
.Sp
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.
.ie n .IP "dim( $info_hash )" 4
.el .IP "dim( \f(CW$info_hash\fR )" 4
.IX Item "dim( $info_hash )"
Takes an hash as returned from \f(CWimage_info()\fR and returns the dimensions
($width, \f(CW$height\fR) of the image.  In scalar context returns the
dimensions as a string.
.ie n .IP "html_dim( $info_hash )" 4
.el .IP "html_dim( \f(CW$info_hash\fR )" 4
.IX Item "html_dim( $info_hash )"
Returns the dimensions as a string suitable for embedding directly
into HTML or SVG <img>\-tags. E.g.:
.Sp
.Vb 1
\&   print "<img src="..." @{[html_dim($info)]}>\en";
.Ve
.ie n .IP "determine_file_format( $filedata )" 4
.el .IP "determine_file_format( \f(CW$filedata\fR )" 4
.IX Item "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".
.SH "Image descriptions"
.IX Header "Image descriptions"
The \f(CWimage_info()\fR 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 occurred (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.
.PP
The following key names are common for any image format:
.IP file_media_type 4
.IX Item "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".
.IP file_ext 4
.IX Item "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".
.IP width 4
.IX Item "width"
This is the number of pixels horizontally in the image.
.IP height 4
.IX Item "height"
This is the number of pixels vertically in the image.  (TIFF uses the
name ImageLength for this field.)
.IP color_type 4
.IX Item "color_type"
The value is a short string describing what kind of values the pixels
encode.  The value can be one of the following:
.Sp
.Vb 7
\&  Gray
\&  GrayA
\&  RGB
\&  RGBA
\&  CMYK
\&  YCbCr
\&  CIELab
.Ve
.Sp
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.
.Sp
It is similar to the TIFF field "PhotometricInterpretation", but this
name was found to be too long, so we used the PNG inspired term
instead.
.IP resolution 4
.IX Item "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.
.Sp
The syntax of this field is:
.Sp
.Vb 3
\&   <res> <unit>
\&   <xres> "/" <yres> <unit>
\&   <xres> "/" <yres>
.Ve
.Sp
The <res>, <xres> and <yres> fields are numbers.  The <unit> is a
string like \f(CW\*(C`dpi\*(C'\fR, \f(CW\*(C`dpm\*(C'\fR or \f(CW\*(C`dpcm\*(C'\fR (denoting "dots per
inch/cm/meter).
.IP SamplesPerPixel 4
.IX Item "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
\&\f(CW\*(C`color_type\*(C'\fR.
.IP BitsPerSample 4
.IX Item "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 \f(CW\*(C`SamplesPerPixel\*(C'\fR.
.IP Comment 4
.IX Item "Comment"
Textual comments found in the file.  The value is a reference to an
array if there are multiple comments found.
.IP Interlace 4
.IX Item "Interlace"
If the image is interlaced, then this tells which interlace method is
used.
.IP Compression 4
.IX Item "Compression"
This tells you which compression algorithm is used.
.IP Gamma 4
.IX Item "Gamma"
A number.
.IP LastModificationTime 4
.IX Item "LastModificationTime"
A ISO date string
.SH "Supported Image Formats"
.IX Header "Supported Image Formats"
The following image file formats are supported:
.IP AVIF 4
.IX Item "AVIF"
Supports the basic standard info key names.
.IP BMP 4
.IX Item "BMP"
This module supports the Microsoft Device Independent Bitmap format
(BMP, DIB, RLE).
.Sp
For more information see Image::Info::BMP.
.IP GIF 4
.IX Item "GIF"
Both GIF87a and GIF89a are supported and the version number is found
as \f(CW\*(C`GIF_Version\*(C'\fR for the first image.  GIF files can contain multiple
images, and information for all images will be returned if
\&\fBimage_info()\fR is called in list context.  The Netscape\-2.0 extension to
loop animation sequences is represented by the \f(CW\*(C`GIF_Loop\*(C'\fR key for the
first image.  The value is either "forever" or a number indicating
loop count.
.IP ICO 4
.IX Item "ICO"
This module supports the Microsoft Windows Icon Resource format
(.ico).
.IP JPEG 4
.IX Item "JPEG"
For JPEG files we extract information both from \f(CW\*(C`JFIF\*(C'\fR and \f(CW\*(C`Exif\*(C'\fR
application chunks.
.Sp
\&\f(CW\*(C`Exif\*(C'\fR 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.
.Sp
The \f(CW\*(C`Exif\*(C'\fR spec can be found at:
<http://www.exif.org/specifications.html>.
.Sp
The \f(CW\*(C`color_type\*(C'\fR element may have the following values: \f(CW\*(C`Gray\*(C'\fR,
\&\f(CW\*(C`YCbCr\*(C'\fR, and \f(CW\*(C`CMYK\*(C'\fR. Note that detecting \f(CW\*(C`RGB\*(C'\fR and \f(CW\*(C`YCCK\*(C'\fR
currently does not work, but will hopefully in future.
.IP PNG 4
.IX Item "PNG"
Information from IHDR, PLTE, gAMA, pHYs, tEXt, tIME chunks are
extracted.  The sequence of chunks are also given by the \f(CW\*(C`PNG_Chunks\*(C'\fR
key.
.IP PBM/PGM/PPM 4
.IX Item "PBM/PGM/PPM"
All information available is extracted.
.IP SVG 4
.IX Item "SVG"
Provides a plethora of attributes and metadata of an SVG vector graphic.
.IP TIFF 4
.IX Item "TIFF"
The \f(CW\*(C`TIFF\*(C'\fR spec can be found at:
<http://partners.adobe.com/public/developer/tiff/>
.Sp
The EXIF spec can be found at:
<http://www.exif.org/specifications.html>
.IP WBMP 4
.IX Item "WBMP"
wbmp files have no magic, so cannot be used with the normal
Image::Info functions. See Image::Info::WBMP for more information.
.IP WEBP 4
.IX Item "WEBP"
VP8 (lossy), VP8L (lossless) and VP8X (extended) files are supported.
Sets the key \f(CW\*(C`Animation\*(C'\fR to true if the file is an animation. Otherwise
sets the key \f(CW\*(C`Compression\*(C'\fR to either \f(CW\*(C`VP8\*(C'\fR or \f(CW\*(C`Lossless\*(C'\fR.
.IP XBM 4
.IX Item "XBM"
See Image::Info::XBM for details.
.IP XPM 4
.IX Item "XPM"
See Image::Info::XPM for details.
.SH CAVEATS
.IX Header "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.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Image::Size, Image::ExifTool
.SH AUTHORS
.IX Header "AUTHORS"
Copyright 1999\-2004 Gisle Aas.
.PP
See the CREDITS file for a list of contributors and authors.
.PP
Tels \- (c) 2006 \- 2008.
.PP
Current maintainer: Slaven Rezic \- (c) 2008 \- 2015.
.SH LICENSE
.IX Header "LICENSE"
This library is free software; you can redistribute it and/or
modify it under the same terms as Perl v5.8.8 itself.