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

FreeBSD Manual Pages


home | help
Imager(3)	      User Contributed Perl Documentation	     Imager(3)

       Imager -	Perl extension for Generating 24 bit Images

	 # Thumbnail example

	 #!/usr/bin/perl -w
	 use strict;
	 use Imager;

	 die "Usage: filename\n" if !-f $ARGV[0];
	 my $file = shift;

	 my $format;

	 # see Imager::Files for information on	the read() method
	 my $img = Imager->new(file=>$file)
	   or die Imager->errstr();

	 $file =~ s/\.[^.]*$//;

	 # Create smaller version
	 # documented in Imager::Transformations
	 my $thumb = $img->scale(scalefactor=>.3);

	 # Autostretch individual channels

	 # try to save in one of these formats

	 for $format ( qw( png gif jpeg	tiff ppm ) ) {
	   # Check if given format is supported
	   if ($Imager::formats{$format}) {
	     print "Storing image as: $file\n";
	     # documented in Imager::Files
	     $thumb->write(file=>$file)	or
	       die $thumb->errstr;
	     last SAVE;

       Imager is a module for creating and altering images.  It	can read and
       write various image formats, draw primitive shapes like lines,and
       polygons, blend multiple	images together	in various ways, scale,	crop,
       render text and more.

   Overview of documentation
       o   Imager - This document - Synopsis, Example, Table of	Contents and

       o   Imager::Install - installation notes	for Imager.

       o   Imager::Tutorial - a	brief introduction to Imager.

       o   Imager::Cookbook - how to do	various	things with Imager.

       o   Imager::ImageTypes -	Basics of constructing image objects with
	   "new()": Direct type/virtual	images,	RGB(A)/paletted	images,
	   8/16/double bits/channel, color maps, channel masks,	image tags,
	   color quantization.	Also discusses basic image information

       o   Imager::Files - IO interaction, reading/writing images, format
	   specific tags.

       o   Imager::Draw	- Drawing Primitives, lines, boxes, circles, arcs,
	   flood fill.

       o   Imager::Color - Color specification.

       o   Imager::Fill	- Fill pattern specification.

       o   Imager::Font	- General font rendering, bounding boxes and font

       o   Imager::Transformations - Copying, scaling, cropping, flipping,
	   blending, pasting, convert and map.

       o   Imager::Engines - Programmable transformations through
	   "transform()", "transform2()" and "matrix_transform()".

       o   Imager::Filters - Filters, sharpen, blur, noise, convolve etc. and
	   filter plug-ins.

       o   Imager::Expr	- Expressions for evaluation engine used by

       o   Imager::Matrix2d - Helper class for affine transformations.

       o   Imager::Fountain - Helper for making	gradient profiles.

       o   Imager::IO -	Imager I/O abstraction.

       o   Imager::API - using Imager's	C API

       o   Imager::APIRef - API	function reference

       o   Imager::Inline - using Imager's C API from Inline::C

       o   Imager::ExtUtils - tools to get access to Imager's C	API.

       o   Imager::Security - brief security notes.

       o   Imager::Threads - brief information on working with threads.

   Basic Overview
       An Image	object is created with "$img = Imager->new()".	Examples:

	 $img=Imager->new();			     # create empty image
	 $img->read(file=>'lena.png',type=>'png') or # read image from file
	    die	$img->errstr();			     # give an explanation
						     # if something failed

       or if you want to create	an empty image:


       This example creates a completely black image of	width 400 and height
       300 and 4 channels.

       In general a method will	return false when it fails, if it does use the
       "errstr()" method to find out why:

	   Returns the last error message in that context.

	   If the last error you received was from calling an object method,
	   such	as read, call errstr() as an object method to find out why:

	     my	$image = Imager->new;
	     $image->read(file => 'somefile.gif')
		or die $image->errstr;

	   If it was a class method then call errstr() as a class method:

	     my	@imgs =	Imager->read_multi(file	=> 'somefile.gif')
	       or die Imager->errstr;

	   Note	that in	some cases object methods are implemented in terms of
	   class methods so a failing object method may	set both.

       The "Imager->new" method	is described in	detail in Imager::ImageTypes.

       Where to	find information on methods for	Imager class objects.

       addcolors() - "addcolors()" in Imager::ImageTypes - add colors to a
       paletted	image

       add_file_magic()	- "add_file_magic()" in	Imager::Files -	add magic to
       Imager's	file type detector.

       addtag()	-  "addtag()" in Imager::ImageTypes - add image	tags

       add_type_extensions() - "add_file_magic()" in Imager::Files - add magic
       for new image file types.

       "add_type_extensions($type, $ext, ...)" in Imager::Files	- add
       extensions for new image	file types.

       align_string() -	"align_string()" in Imager::Draw - draw	text aligned
       on a point

       alphachannel() -	"alphachannel()" in Imager::ImageTypes - return	the
       channel index of	the alpha channel (if any).

       arc() - "arc()" in Imager::Draw - draw a	filled arc

       bits() -	"bits()" in Imager::ImageTypes - number	of bits	per sample for
       the image

       box() - "box()" in Imager::Draw - draw a	filled or outline box.

       check_file_limits() - "check_file_limits()" in Imager::Files

       circle()	- "circle()" in	Imager::Draw - draw a filled circle

       close_log() - "close_log()" in Imager::ImageTypes - close the Imager
       debugging log.

       colorchannels() - "colorchannels()" in Imager::ImageTypes - the number
       of channels used	for color.

       colorcount() - "colorcount()" in	Imager::ImageTypes - the number	of
       colors in an image's palette (paletted images only)

       colormodel() - "colorcount()" in	Imager::ImageTypes - how color is

       combine() - "combine()" in Imager::Transformations - combine channels
       from one	or more	images.

       combines() - "combines()" in Imager::Draw - return a list of the
       different combine type keywords

       compose() - "compose()" in Imager::Transformations - compose one	image
       over another.

       convert() - "convert()" in Imager::Transformations - transform the
       color space

       copy() -	"copy()" in Imager::Transformations - make a duplicate of an

       crop() -	"crop()" in Imager::Transformations - extract part of an image

       def_guess_type()	- "def_guess_type()" in	Imager::Files -	default
       function	used to	guess the output file format based on the output file

       deltag()	-  "deltag()" in Imager::ImageTypes - delete image tags

       difference() - "difference()" in	Imager::Filters	- produce a difference
       images from two input images.

       errstr()	- "errstr()" - the error from the last failed operation.

       filter()	- "filter()" in	Imager::Filters	- image	filtering

       findcolor() - "findcolor()" in Imager::ImageTypes - search the image
       palette,	if it has one

       flip() -	"flip()" in Imager::Transformations - flip an image,
       vertically, horizontally

       flood_fill() - "flood_fill()" in	Imager::Draw - fill an enclosed	or
       same color area

       getchannels() - "getchannels()" in Imager::ImageTypes - the number of
       samples per pixel for an	image

       getcolorcount() - "getcolorcount()" in Imager::ImageTypes - the number
       of different colors used	by an image (works for direct color images)

       getcolors() - "getcolors()" in Imager::ImageTypes - get colors from the
       image palette, if it has	one

       getcolorusage() - "getcolorusage()" in Imager::ImageTypes

       getcolorusagehash() - "getcolorusagehash()" in Imager::ImageTypes

       get_file_limits() - "get_file_limits()" in Imager::Files

       getheight() - "getheight()" in Imager::ImageTypes - height of the image
       in pixels

       getmask() - "getmask()" in Imager::ImageTypes - write mask for the

       getpixel() - "getpixel()" in Imager::Draw - retrieve one	or more	pixel

       getsamples() - "getsamples()" in	Imager::Draw - retrieve	samples	from a
       row or partial row of pixels.

       getscanline() - "getscanline()" in Imager::Draw - retrieve colors for a
       row or partial row of pixels.

       getwidth() - "getwidth()" in Imager::ImageTypes - width of the image in

       img_set() - "img_set()" in Imager::ImageTypes - re-use an Imager	object
       for a new image.

       init() -	"init()" in Imager::ImageTypes

       is_bilevel() - "is_bilevel()" in	Imager::ImageTypes - returns whether
       image write functions should write the image in their bilevel (blank
       and white, no gray levels) format

       is_logging() "is_logging()" in Imager::ImageTypes - test	if the debug
       log is active.

       line() -	"line()" in Imager::Draw - draw	an interval

       load_plugin() - "load_plugin()" in Imager::Filters

       log() - "log()" in Imager::ImageTypes - send a message to the debugging

       make_palette() -	"make_palette()" in Imager::ImageTypes - produce a
       color palette from one or more input images.

       map() - "map()" in Imager::Transformations - remap color	channel	values

       masked()	-  "masked()" in Imager::ImageTypes - make a masked image

       matrix_transform() - "matrix_transform()" in Imager::Engines

       maxcolors() - "maxcolors()" in Imager::ImageTypes

       NC() - "NC()" in	Imager::Handy

       NCF() - "NCF()" in Imager::Handy

       new() - "new()" in Imager::ImageTypes

       newcolor() - "newcolor()" in Imager::Handy

       newcolour() - "newcolour()" in Imager::Handy

       newfont() - "newfont()" in Imager::Handy

       NF() - "NF()" in	Imager::Handy

       open() -	"read()" in Imager::Files - an alias for read()

       open_log() - "open_log()" in Imager::ImageTypes - open the debug	log.

       parseiptc() - "parseiptc()" in Imager::Files - parse IPTC data from a
       JPEG image

       paste() - "paste()" in Imager::Transformations -	draw an	image onto an

       polygon() - "polygon()" in Imager::Draw

       polyline() - "polyline()" in Imager::Draw

       polypolygon() - "polypolygon()" in Imager::Draw

       preload() - "preload()" in Imager::Files

       read() -	"read()" in Imager::Files - read a single image	from an	image

       read_multi() - "read_multi()" in	Imager::Files -	read multiple images
       from an image file

       read_types() - "read_types()" in	Imager::Files -	list image types
       Imager can read.

       register_filter() - "register_filter()" in Imager::Filters

       register_reader() - "register_reader()" in Imager::Files

       register_writer() - "register_writer()" in Imager::Files

       rotate()	- "rotate()" in	Imager::Transformations

       rubthrough() - "rubthrough()" in	Imager::Transformations	- draw an
       image onto an image and use the alpha channel

       scale() - "scale()" in Imager::Transformations

       scale_calculate() - "scale_calculate()" in Imager::Transformations

       scaleX()	- "scaleX()" in	Imager::Transformations

       scaleY()	- "scaleY()" in	Imager::Transformations

       setcolors() - "setcolors()" in Imager::ImageTypes - set palette colors
       in a paletted image

       set_file_limits() - "set_file_limits()" in Imager::Files

       setmask() - "setmask()" in Imager::ImageTypes

       setpixel() - "setpixel()" in Imager::Draw

       setsamples() - "setsamples()" in	Imager::Draw

       setscanline() - "setscanline()" in Imager::Draw

       settag()	- "settag()" in	Imager::ImageTypes

       string()	- "string()" in	Imager::Draw - draw text on an image

       tags() -	 "tags()" in Imager::ImageTypes	- fetch	image tags

       to_paletted() -	"to_paletted()"	in Imager::ImageTypes

       to_rgb16() - "to_rgb16()" in Imager::ImageTypes

       to_rgb8() - "to_rgb8()" in Imager::ImageTypes

       to_rgb_double() - "to_rgb_double()" in Imager::ImageTypes - convert to
       double per sample image.

       transform() - "transform()" in Imager::Engines

       transform2() - "transform2()" in	Imager::Engines

       type() -	 "type()" in Imager::ImageTypes	- type of image	(direct	vs

       unload_plugin() - "unload_plugin()" in Imager::Filters

       virtual() - "virtual()" in Imager::ImageTypes - whether the image has
       it's own	data

       write() - "write()" in Imager::Files - write an image to	a file

       write_multi() - "write_multi()" in Imager::Files	- write	multiple image
       to an image file.

       write_types() - "read_types()" in Imager::Files - list image types
       Imager can write.

       animated	GIF - "Writing an animated GIF"	in Imager::Files

       aspect ratio - "i_xres",	"i_yres", "i_aspect_only" in "Common Tags" in

       blend - alpha blending one image	onto another "rubthrough()" in

       blur - ""gaussian"" in Imager::Filters, ""conv""	in Imager::Filters

       boxes, drawing -	"box()"	in Imager::Draw

       changes between image - "Image Difference" in Imager::Filters

       channels, combine into one image	- "combine()" in

       color - Imager::Color

       color names - Imager::Color, Imager::Color::Table

       combine modes - "Combine	Types" in Imager::Draw

       compare images -	"Image Difference" in Imager::Filters

       contrast	- ""contrast"" in Imager::Filters, ""autolevels"" in

       convolution - ""conv"" in Imager::Filters

       cropping	- "crop()" in Imager::Transformations

       CUR files - "ICO	(Microsoft Windows Icon) and CUR (Microsoft Windows
       Cursor)"	in Imager::Files

       "diff" images - "Image Difference" in Imager::Filters

       dpi - "i_xres", "i_yres"	in "Common Tags" in Imager::ImageTypes,	"Image
       spatial resolution" in Imager::Cookbook

       drawing boxes - "box()" in Imager::Draw

       drawing lines - "line()"	in Imager::Draw

       drawing text - "string()" in Imager::Draw, "align_string()" in

       error message - "ERROR HANDLING"

       files, font - Imager::Font

       files, image - Imager::Files

       filling,	types of fill -	Imager::Fill

       filling,	boxes -	"box()"	in Imager::Draw

       filling,	flood fill - "flood_fill()" in Imager::Draw

       flood fill - "flood_fill()" in Imager::Draw

       fonts - Imager::Font

       fonts, drawing with - "string()"	in Imager::Draw, "align_string()" in
       Imager::Draw, Imager::Font::Wrap

       fonts, metrics -	"bounding_box()" in Imager::Font, Imager::Font::BBox

       fonts, multiple master -	"MULTIPLE MASTER FONTS"	in Imager::Font

       fountain	fill - "Fountain fills"	in Imager::Fill, ""fountain"" in
       Imager::Filters,	Imager::Fountain, ""gradgen"" in Imager::Filters

       GIF files - "GIF" in Imager::Files

       GIF files, animated - "Writing an animated GIF" in Imager::Files

       gradient	fill - "Fountain fills"	in Imager::Fill, ""fountain"" in
       Imager::Filters,	Imager::Fountain, ""gradgen"" in Imager::Filters

       gray scale, convert image to - "convert()" in Imager::Transformations

       gaussian	blur - ""gaussian"" in Imager::Filters,	""gaussian2"" in

       hatch fills - "Hatched fills" in	Imager::Fill

       ICO files - "ICO	(Microsoft Windows Icon) and CUR (Microsoft Windows
       Cursor)"	in Imager::Files

       invert image - ""hardinvert"" in	Imager::Filters, ""hardinvertall"" in

       JPEG - "JPEG" in	Imager::Files

       limiting	image sizes - "Limiting	the sizes of images you	read" in

       lines, drawing -	"line()" in Imager::Draw

       matrix -	Imager::Matrix2d, "Matrix Transformations" in Imager::Engines,
       "transform()" in	Imager::Font

       metadata, image - "Tags"	in Imager::ImageTypes, Image::ExifTool

       mosaic -	""mosaic"" in Imager::Filters

       noise, filter - ""noise"" in Imager::Filters

       noise, rendered - ""turbnoise"" in Imager::Filters, ""radnoise""	in

       paste - "paste()" in Imager::Transformations, "rubthrough()" in

       pseudo-color image - "to_paletted()" in Imager::ImageTypes, "new()" in

       posterize - ""postlevels"" in Imager::Filters

       PNG files - Imager::Files, "PNG"	in Imager::Files

       PNM - "PNM (Portable aNy	Map)" in Imager::Files

       rectangles, drawing - "box()" in	Imager::Draw

       resizing	an image - "scale()" in	Imager::Transformations, "crop()" in

       RGB (SGI) files - "SGI (RGB, BW)" in Imager::Files

       saving an image - Imager::Files

       scaling - "scale()" in Imager::Transformations

       security	- Imager::Security

       SGI files - "SGI	(RGB, BW)" in Imager::Files

       sharpen - ""unsharpmask"" in Imager::Filters, ""conv"" in

       size, image - "getwidth()" in Imager::ImageTypes, "getheight()" in

       size, text - "bounding_box()" in	Imager::Font

       tags, image metadata - "Tags" in	Imager::ImageTypes

       text, drawing - "string()" in Imager::Draw, "align_string()" in
       Imager::Draw, Imager::Font::Wrap

       text, wrapping text in an area -	Imager::Font::Wrap

       text, measuring - "bounding_box()" in Imager::Font, Imager::Font::BBox

       threads - Imager::Threads

       tiles, color - ""mosaic"" in Imager::Filters

       transparent images - Imager::ImageTypes,	"Transparent PNG" in

       unsharp mask - ""unsharpmask"" in Imager::Filters

       watermark - ""watermark"" in Imager::Filters

       writing an image	to a file - Imager::Files

       The best	place to get help with Imager is the mailing list.

       To subscribe send a message with	"subscribe" in the body	to:

       or use the form at:


       where you can also find the mailing list	archive.

       You can report bugs either via github at:


       or at:


       or by sending an	email to:

       Please remember to include the versions of Imager, perl,	supporting
       libraries, and any relevant code.  If you have specific images that
       cause the problems, please include those	too.

       I like feedback.

       You can send email to the maintainer below.

       If you send me a	bug report via email, it will be copied	to Request

       I accept	patches, preferably against the	master branch in git.  Please
       include an explanation of the reason for	why the	patch is needed	or

       Your patch should include regression tests where	possible, otherwise it
       will be delayed until I get a chance to write them.

       To browse Imager's git repository:

       To clone:

	 git clone git://

       Or you can create a fork	as usual on github and submit a	github pull

       Patches can either be submitted as a github pull	request	or by using
       "git format-patch", for example,	if you made your changes in a branch
       from master you might do:

	 git format-patch -k --stdout master >my-patch.txt

       and then	attach that to your bug	report,	either by adding it as an
       attachment in your email	client,	or by using the	Request	Tracker
       attachment mechanism.

       Tony Cook <> is the current maintainer for	Imager.

       Arnar M.	Hrafnkelsson is	the original author of Imager.

       Many others have	contributed to Imager, please see the "README" for a
       complete	list.

       Imager is licensed under	the same terms as perl itself.

       A test font, generated by the Debian packaged Fontforge,
       FT2/fontfiles/MMOne.pfb,	contains a Postscript operator definition
       copyrighted by Adobe.  See adobe.txt in the source for license

       perl(1),	Imager::ImageTypes(3), Imager::Files(3), Imager::Draw(3),
       Imager::Color(3), Imager::Fill(3), Imager::Font(3),
       Imager::Transformations(3), Imager::Engines(3), Imager::Filters(3),
       Imager::Expr(3),	Imager::Matrix2d(3), Imager::Fountain(3)


       Affix::Infix2Postfix(3),	Parse::RecDescent(3)

       Other perl imaging modules include:

       GD(3), Image::Magick(3),	Graphics::Magick
       <>(3), Prima::Image, IPA.

       For manipulating	image metadata see Image::ExifTool.

       If you're trying	to use Imager for array	processing, you	should
       probably	using PDL.

perl v5.32.1			  2020-06-14			     Imager(3)


Want to link to this manual page? Use this URL:

home | help