---
name: "Imager"
section: "3pm"
platform: "linux"
package: "libimager-perl"
version: "1.027+dfsg-1"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/Imager"
---

# Imager(3pm)

Perl extension for Generating 24 bit Images

## NAME

Imager - Perl extension for Generating 24 bit Images

## SYNOPSIS

```
  # Thumbnail example
  #!/usr/bin/perl -w
  use strict;
  use Imager;
  die "Usage: thumbmake.pl 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
  $thumb->filter(type=>'autolevels');
  # try to save in one of these formats
  SAVE:
  for $format ( qw( png gif jpeg tiff ppm ) ) {
    # Check if given format is supported
    if ($Imager::formats{$format}) {
      $file.="_low.$format";
      print "Storing image as: $file\n";
      # documented in Imager::Files
      $thumb->write(file=>$file) or
        die $thumb->errstr;
      last SAVE;
    }
  }
```

## DESCRIPTION

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::Install - installation notes for Imager.

- •

  Imager::Tutorial - a brief introduction to Imager.

- •

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

- •

  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.

- •

  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 `transform()`, `transform2()` and `matrix_transform()`.

- •

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

- •

  Imager::Expr - Expressions for evaluation engine used by **transform2()**.

- •

  Imager::Matrix2d - Helper class for affine transformations.

- •

  Imager::Fountain - Helper for making gradient profiles.

- •

  Imager::IO - Imager I/O abstraction.

- •

  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.

- •

  Imager::Security - brief security notes.

- •

  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:

```
  $img=Imager->new(xsize=>400,ysize=>300,channels=>4);
```

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

## ERROR HANDLING

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.

## METHOD INDEX

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

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

**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

**trim()** - "**trim()**" in Imager::Transformations - return a cropped image based on border transparency or border colors.

**trim\_rect()** - "**trim\_rect()**" in Imager::Transformations - return how much **trim()** would remove.

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

## CONCEPT INDEX

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, "**trim()**" 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, "`"gaussian2"`" 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

## SUPPORT

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

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

```
   imager-devel+request@molar.is
```

or use the form at:

\<http://www.molar.is/en/lists/imager-devel/\>

where you can also find the mailing list archive.

You can report bugs either via github at:

\<https://github.com/tonycoz/imager/issues\>

or at:

\<https://rt.cpan.org/NoAuth/ReportBug.html?Queue=Imager\>

or by sending an email to:

bug-Imager@rt.cpan.org

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.

## CONTRIBUTING TO IMAGER

### Feedback

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

### Patches

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:

```
  https://github.com/tonycoz/imager.git
```

To clone:

```
  git clone git://github.com/tonycoz/imager.git
```

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

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.

## AUTHOR

Tony Cook \<tonyc@cpan.org\> 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.

## LICENSE

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.

## SEE ALSO

[perl(1)](/perl/1.md), 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)

\<http://imager.perl.org/\>

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

Other perl imaging modules include:

GD(3), [Image::Magick(3)](/Image::Magick/3.md), Graphics::Magick \<http://www.graphicsmagick.org/perl.html\>(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.