Pair Networks


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 $im = 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

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() - Imager::ImageTypes/addcolors - add colors to a paletted image

addtag() - Imager::ImageTypes/addtag - add image tags

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

arc() - Imager::Draw/arc - draw a filled arc

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

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

circle() - Imager::Draw/circle - draw a filled circle

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

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

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

convert() - Imager::Transformations/"Color transformations" - transform the color space

copy() - Imager::Transformations/copy - make a duplicate of an image

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

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

deltag() - Imager::ImageTypes/deltag - delete image tags

difference() - Imager::Filters/"Image Difference" - produce a difference images from two input images.

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

filter() - Imager::Filters - image filtering

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

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

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

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

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

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

getcolorusage() - Imager::ImageTypes/getcolorusage

getcolorusagehash() - Imager::ImageTypes/getcolorusagehash

get_file_limits() - Imager::Files/"Limiting the sizes of images you read"

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

getmask() - Imager::ImageTypes/getmask - write mask for the image

getpixel() - Imager::Draw/getpixel - retrieve one or more pixel colors

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

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

getwidth() - Imager::ImageTypes/getwidth - width of the image in pixels.

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

init() - Imager::ImageTypes/init

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

line() - Imager::Draw/line - draw an interval

load_plugin() - Imager::Filters/load_plugin

map() - Imager::Transformations/"Color Mappings" - remap color channel values

masked() - Imager::ImageTypes/masked - make a masked image

matrix_transform() - Imager::Engines/matrix_transform

maxcolors() - Imager::ImageTypes/maxcolors

NC() - Imager::Handy/NC

NCF() - Imager::Handy/NCF

new() - Imager::ImageTypes/new

newcolor() - Imager::Handy/newcolor

newcolour() - Imager::Handy/newcolour

newfont() - Imager::Handy/newfont

NF() - Imager::Handy/NF

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

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

paste() - Imager::Transformations/paste - draw an image onto an image

polygon() - Imager::Draw/polygon

polyline() - Imager::Draw/polyline

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

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

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

register_filter() - Imager::Filters/register_filter

register_reader() - Imager::Files/register_reader

register_writer() - Imager::Files/register_writer

rotate() - Imager::Transformations/rotate

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

scale() - Imager::Transformations/scale

scale_calculate() - Imager::Transformations/scale_calculate

scaleX() - Imager::Transformations/scaleX

scaleY() - Imager::Transformations/scaleY

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

set_file_limits() - Imager::Files/"Limiting the sizes of images you read"

setmask() - Imager::ImageTypes/setmask

setpixel() - Imager::Draw/setpixel

setsamples() - Imager::Draw/setsamples

setscanline() - Imager::Draw/setscanline

settag() - Imager::ImageTypes/settag

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

tags() - Imager::ImageTypes/tags - fetch image tags

to_paletted() - Imager::ImageTypes/to_paletted

to_rgb16() - Imager::ImageTypes/to_rgb16

to_rgb8() - Imager::ImageTypes/to_rgb8

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

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

type() - Imager::ImageTypes/type - type of image (direct vs paletted)

unload_plugin() - Imager::Filters/unload_plugin

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

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

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

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


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

aspect ratio - Imager::ImageTypes/i_xres, Imager::ImageTypes/i_yres, Imager::ImageTypes/i_aspect_only

blend - alpha blending one image onto another Imager::Transformations/rubthrough

blur - Imager::Filters/guassian, Imager::Filters/conv

boxes, drawing - Imager::Draw/box

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

color - Imager::Color

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

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

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

contrast - Imager::Filters/contrast, Imager::Filters/autolevels

convolution - Imager::Filters/conv

cropping - Imager::Transformations/crop

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

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

dpi - Imager::ImageTypes/i_xres, Imager::Cookbook/"Image spatial resolution"

drawing boxes - Imager::Draw/box

drawing lines - Imager::Draw/line

drawing text - Imager::Draw/string, Imager::Draw/align_string

error message - "ERROR HANDLING"

files, font - Imager::Font

files, image - Imager::Files

filling, types of fill - Imager::Fill

filling, boxes - Imager::Draw/box

filling, flood fill - Imager::Draw/flood_fill

flood fill - Imager::Draw/flood_fill

fonts - Imager::Font

fonts, drawing with - Imager::Draw/string, Imager::Draw/align_string, Imager::Font::Wrap

fonts, metrics - Imager::Font/bounding_box, Imager::Font::BBox

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

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

GIF files - Imager::Files/"GIF"

GIF files, animated - Imager::File/"Writing an animated GIF"

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

gray scale, convert image to - Imager::Transformations/convert

guassian blur - Imager::Filters/guassian

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

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

invert image - Imager::Filters/hardinvert, Imager::Filters/hardinvertall

JPEG - Imager::Files/"JPEG"

limiting image sizes - Imager::Files/"Limiting the sizes of images you read"

lines, drawing - Imager::Draw/line

matrix - Imager::Matrix2d, Imager::Transformations/"Matrix Transformations", Imager::Font/transform

metadata, image - Imager::ImageTypes/"Tags"

mosaic - Imager::Filters/mosaic

noise, filter - Imager::Filters/noise

noise, rendered - Imager::Filters/turbnoise, Imager::Filters/radnoise

paste - Imager::Transformations/paste, Imager::Transformations/rubthrough

pseudo-color image - Imager::ImageTypes/to_paletted, Imager::ImageTypes/new

posterize - Imager::Filters/postlevels

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

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

rectangles, drawing - Imager::Draw/box

resizing an image - Imager::Transformations/scale, Imager::Transformations/crop

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

saving an image - Imager::Files

scaling - Imager::Transformations/scale

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

sharpen - Imager::Filters/unsharpmask, Imager::Filters/conv

size, image - Imager::ImageTypes/getwidth, Imager::ImageTypes/getheight

size, text - Imager::Font/bounding_box

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

text, drawing - Imager::Draw/string, Imager::Draw/align_string, Imager::Font::Wrap

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

text, measuring - Imager::Font/bounding_box, Imager::Font::BBox

tiles, color - Imager::Filters/mosaic

unsharp mask - Imager::Filters/unsharpmask

watermark - Imager::Filters/watermark

writing an image to a file - Imager::Files


Imager doesn't support perl threads.

Imager has limited code to prevent double frees if you create images, colors etc, and then create a thread, but has no code to prevent two threads entering Imager's error handling code, and none is likely to be added.


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 by pointing your browser 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.

If you don't want to publish your email address on a mailing list you can use CPAN::Forum:

You will need to register to post.



I like feedback.

If you like or dislike Imager, you can add a public review of Imager at CPAN Ratings:

This requires a Bitcard account (

You can also send email to the maintainer below.

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


I accept patches, preferably against the main branch in subversion. You should include an explanation of the reason for why the patch is needed or useful.

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


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.


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).