Quick Navigator

Search Site

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

Contact Us
Online Help
Domain Status
Man Pages

Virtual Servers

Topology Map

Server Agreement
Year 2038

USA Flag



Man Pages

Manual Reference Pages  -  IMAGER (3)

.ds Aq ’


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 Overview.
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 methods.
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 metrics.
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 transform2().
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:
errstr() 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

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

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

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 image

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 name

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 image

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

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

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

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 image

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 file

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

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 Imager::ImageTypes.

blend - alpha blending one image onto another rubthrough() in Imager::Transformations

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 Imager::Transformations

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 Imager::Filters

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 Imager::Draw

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

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 Imager::Filters

JPEG - JPEG in Imager::Files

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

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 Imager::Filters

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

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

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 Imager::Transformations

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 Imager::Filters

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

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 Imager::Cookbook

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 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 master branch in git. Please 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.

To browse Imager’s git repository:

To clone:

  git clone git://

My preference is that patches are provided in the format produced by 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 information.


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.

Search for    or go to Top of page |  Section 3 |  Main Index

perl v5.20.3 IMAGER (3) 2015-11-08

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