man Imager () - Perl extension for Generating 24 bit Images


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;

  my $img = Imager->new();
  # see Imager::Files for information on the read() method
  $img->read(file=>$file) or die $img->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 jpg 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

Imager - This document - Synopsis Example, Table of Contents and Overview.
Imager::Tutorial - a brief introduction to Imager.
Imager::Cookbook - how to do various things with Imager.
Imager::ImageTypes - Basics of constructing image objects with CWnew(): 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.
Imager::Files - IO interaction, reading/writing images, format specific tags.
Imager::Draw - Drawing Primitives, lines, boxes, circles, arcs, flood fill.
Imager::Color - Color specification.
Imager::Fill - Fill pattern specification.
Imager::Font - General font rendering, bounding boxes and font metrics.
Imager::Transformations - Copying, scaling, cropping, flipping, blending, pasting, convert and map.
Imager::Engines - Programmable transformations through CWtransform(), CWtransform2() and CWmatrix_transform().
Imager::Filters - Filters, sharpen, blur, noise, convolve etc. and filter plugins.
Imager::Expr - Expressions for evaluation engine used by transform2().
Imager::Matrix2d - Helper class for affine transformations.
Imager::Fountain - Helper for making gradient profiles.
Imager::API - using Imager's C API
Imager::APIRef - API function reference
Imager::Inline - using Imager's C API from Inline::C
Imager::ExtUtils - tools to get access to Imager's C API.

Basic Overview

An Image object is created with CW$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.

When an operation fails which can be directly associated with an image the error message is stored can be retrieved with CW$img->errstr().

In cases where no image object is associated with an operation CW$Imager::ERRSTR is used to report errors not directly associated with an image object. You can also call CWImager-errstr> to get this value.

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


Where to find information on methods for Imager class objects.

addcolors() - addcolors in Imager::ImageTypes

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

arc() - arc in Imager::Draw

align_string() - align_string in Imager::Draw

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

box() - box in Imager::Draw

circle() - circle in Imager::Draw

colorcount() - colorcount in Imager::Draw

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

copy() - copy in Imager::Transformations

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

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

difference() - Image Difference in Imager::Filters

errstr() - Basic Overview

filter() - Imager::Filters

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

flip() - flip in Imager::Transformations

flood_fill() - flood_fill in Imager::Draw

getchannels() - getchannels in Imager::ImageTypes

getcolorcount() - getcolorcount in Imager::ImageTypes

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

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

getheight() - getwidth in Imager::ImageTypes

getpixel() - getpixel in Imager::Draw

getsamples() - getsamples in Imager::Draw

getscanline() - getscanline in Imager::Draw

getwidth() - getwidth in Imager::ImageTypes

img_set() - img_set in Imager::ImageTypes

line() - line in Imager::Draw

map() - Color Mappings 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

new() - new in Imager::ImageTypes

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

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

polygon() - polygon in Imager::Draw

polyline() - polyline in Imager::Draw

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

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

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

scaleX() - scaleX in Imager::Transformations

scaleY() - scaleY in Imager::Transformations

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

setpixel() - setpixel in Imager::Draw

setscanline() - setscanline in Imager::Draw

settag() - settag in Imager::ImageTypes

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

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_rgb8() - to_rgb8 in Imager::ImageTypes

transform() - transform in Imager::Engines

transform2() - transform2 in Imager::Engines

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

virtual() - virtual in Imager::ImageTypes - 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.


animated GIF - Writing an animated GIF in Imager::File

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

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

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

boxes, drawing - box in Imager::Draw

changes between image - Image Difference in Imager::Filter

color - Imager::Color

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

combine modes - combine in Imager::Fill

compare images - Image Difference in Imager::Filter

contrast - contrast in Imager::Filter, autolevels in Imager::Filter

convolution - conv in Imager::Filter

cropping - crop in Imager::Transformations

CWdiff images - Image Difference in Imager::Filter

dpi - i_xres in Imager::ImageTypes

drawing boxes - box in Imager::Draw

drawing lines - line in Imager::Draw

drawing text - string in Imager::Font, align in Imager::Font

error message - Basic Overview

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::Font, align in Imager::Font, 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::File

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

guassian blur - guassian in Imager::Filter

hatch fills - Hatched fills in Imager::Fill

invert image - hardinvert in Imager::Filter

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::Transformations, transform in Imager::Font

metadata, image - Tags in Imager::ImageTypes

mosaic - mosaic in Imager::Filter

noise, filter - noise in Imager::Filter

noise, rendered - turbnoise in Imager::Filter, radnoise in Imager::Filter

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::Filter

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

saving an image - Imager::Files

scaling - scale in Imager::Transformations

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

tiles, color - mosaic in Imager::Filter

unsharp mask - unsharpmask in Imager::Filter

watermark - watermark in Imager::Filter

writing an image to a file - Imager::Files


You can ask for help, report bugs or express your undying love for Imager on the Imager-devel mailing list.

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

or use the form at: <>

where you can also find the mailing list archive.

If you're into IRC, you can typically find the developers in #Imager on As with any IRC channel, the participants could be occupied or asleep, so please be patient.

You can report bugs by pointing your browser at: <>

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.


Bugs are listed individually for relevant pod pages.


Arnar M. Hrafnkelsson and Tony Cook ( among others. See the README for a complete list.