Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
Image::Info(3)	      User Contributed Perl Documentation	Image::Info(3)

NAME
       Image::Info - Extract meta information from image files

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
       This module provides 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 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 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
       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.

       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 inspired
	   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
	   graphic.

       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.

       WEBP
	   VP8 (lossy),	VP8L (lossless)	and VP8X (extended) files are
	   supported.  Sets the	key "Animation"	to true	if the file is an
	   animation. Otherwise	sets the key "Compression" to either "VP8" or
	   "Lossless".

       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.

perl v5.32.0			  2019-10-19			Image::Info(3)

NAME | SYNOPSIS | DESCRIPTION | Image descriptions | Supported Image Formats | CAVEATS | SEE ALSO | AUTHORS | LICENSE

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Image::Info&sektion=3&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help