Imager(3pm)

💖 NAME 💖

okay so Imager(3pm) is the manual page for Imager — a Perl extension for Generating 24 bit Images. yes, capital G, capital I, icon behavior 💅 It’s your bestie for creating and altering images: reading and writing formats, drawing, blending, scaling, cropping, rendering text, and more.

✨ SYNOPSIS ✨

here’s the thumbnail example, no cap:

  # 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. it’s giving “image toolkit but make it Perl” and honestly? obsessed 🫶

🌈 Overview of documentation 🌈

• Imager — this document right here: Synopsis, Example, Table of Contents and Overview. meta much? 💅
• 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. little void-core moment, but make it fashion 🖤

😭 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. iykyk 👑

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

📇 METHOD INDEX 📇

okay bestie so this is the master map — every method in the Imager universe and which module's docs actually explain it. think of it as the group chat directory: you got a name, you got the module they live in, and a one-line vibe check. click through, iykyk 💅

• addcolors() — addcolors() in Imager::ImageTypes — adds colors to a paletted image
• add_file_magic() — add_file_magic() in Imager::Files — adds magic to Imager's file type detector
• addtag() — addtag() in Imager::ImageTypes — adds image tags
• add_type_extensions() — add_file_magic() in Imager::Files — adds magic for new image file types
• add_type_extensions($type, $ext, ...) — in Imager::Files — adds extensions for new image file types
• align_string() — align_string() in Imager::Draw — draws text aligned on a point
• alphachannel() — alphachannel() in Imager::ImageTypes — returns the channel index of the alpha channel (if any)
• arc() — arc() in Imager::Draw — draws a filled arc
• bits() — bits() in Imager::ImageTypes — number of bits per sample for the image
• box() — box() in Imager::Draw — draws a filled or outline box
• check_file_limits() — check_file_limits() in Imager::Files
• circle() — circle() in Imager::Draw — draws a filled circle
• close_log() — close_log() in Imager::ImageTypes — closes 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 — combines channels from one or more images
• combines() — combines() in Imager::Draw — returns a list of the different combine type keywords
• compose() — compose() in Imager::Transformations — composes one image over another
• convert() — convert() in Imager::Transformations — transforms the color space
• copy() — copy() in Imager::Transformations — makes a duplicate of an image
• crop() — crop() in Imager::Transformations — extracts part of an image
• def_guess_type() — def_guess_type() in Imager::Files — the default function used to guess the output file format based on the output file name
• deltag() — deltag() in Imager::ImageTypes — deletes image tags
• difference() — difference() in Imager::Filters — produces 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 — searches the image palette, if it has one
• flip() — flip() in Imager::Transformations — flips an image, vertically, horizontally
• flood_fill() — flood_fill() in Imager::Draw — fills 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 — gets 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 — retrieves one or more pixel colors
• getsamples() — getsamples() in Imager::Draw — retrieves samples from a row or partial row of pixels
• getscanline() — getscanline() in Imager::Draw — retrieves 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-uses 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 — tests if the debug log is active
• line() — line() in Imager::Draw — draws an interval
• load_plugin() — load_plugin() in Imager::Filters
• log() — log() in Imager::ImageTypes — sends a message to the debugging log
• make_palette() — make_palette() in Imager::ImageTypes — produces a color palette from one or more input images
• map() — map() in Imager::Transformations — remaps color channel values
• masked() — masked() in Imager::ImageTypes — makes 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 — opens the debug log
• parseiptc() — parseiptc() in Imager::Files — parses IPTC data from a JPEG image
• paste() — paste() in Imager::Transformations — draws 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 — reads a single image from an image file
• read_multi() — read_multi() in Imager::Files — reads multiple images from an image file
• read_types() — read_types() in Imager::Files — lists 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 — produces a difference images from two input images
• rotate() — rotate() in Imager::Transformations
• rubthrough() — rubthrough() in Imager::Transformations — draws an image onto an image and uses 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 — sets 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 — draws text on an image
• tags() — tags() in Imager::ImageTypes — fetches 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 — converts to double per sample image
• transform() — transform() in Imager::Engines
• transform2() — transform2() in Imager::Engines
• trim() — trim() in Imager::Transformations — returns a cropped image based on border transparency or border colors
• trim_rect() — trim_rect() in Imager::Transformations — returns 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 — writes an image to a file
• write_multi() — write_multi() in Imager::Files — writes multiple image to an image file
• write_types() — read_types() in Imager::Files — lists image types Imager can write

---

pro tip bestie: a bunch of these cross-reference lines point at a different method name than the one you searched — like colormodel() sending you to colorcount(), or write_types() sending you to read_types(). that's not a typo on my end, that's literally what the docs say, so follow the breadcrumbs fr fr 🫶

🔎 CONCEPT INDEX 🔎

okay so this is basically the group chat's "who's who" of Imager — you look up a thing you wanna do and it tells you which page has the tea. find your vibe, click through, slay 💅

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

bestie, if you're stuck, the mailing list is genuinely the best place to get help with Imager. that's the main character of support channels, no cap.

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 👀 (yes, the receipts are public).

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 💖 (like, the bug report is only as iconic as the info you give it)

---

🌈 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. lowkey the tests are the vibe check, ngl.

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. (the whole squad fr fr 🫶)

---

💜 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. (legal girlies stay winning ✨)

---

⭐ SEE ALSO ⭐

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)

http://imager.perl.org/

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

other perl imaging modules include:

GD(3), Image::Magick(3), 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.

---

and that's the whole page, bestie!! this lil' beauty came from perl v5.42.3, dated 2026-08-19, and it's Imager(3pm) 💅✨ go forth and make iconic images 🦋💖🎀