Imager::Cookbook(3pm)

🌸 NAME 🌸

Imager::Cookbook(3pm) from the User Contributed Perl Documentation is literally Imager::Cookbook, aka your recipe box for working with Imager. That's the whole name vibe, bestie. 💖

✨ DESCRIPTION ✨

Okay so this is the stash of ways—some super simple, some not so simple—to do stuff with Imager. Think recipe collection, but make it image code. 🎀

---

🦋 FILES 🦋

The full detailed tea on files lives in Imager::Files. Go there for the deep lore.

🖼️ Reading an image from a file

You can read an image like this:

my $image = Imager->new;

$image->read(file=>$filename) or die $image->errstr;

Or, alternate iconic route:

my $image = Imager->new(file => $filename)
  or die Imager->errstr;

See Imager::Files for more. 💅

🎀 Writing an image to a file

Write it out with:

$image->write(file=>$filename) or die $image->errstr;

🌈 Write an animated GIF

Build the images first, then write the GIF:

# build an array of images to use in the gif
my  @images;
# synthesize the images or read them from files, it doesn't matter
...

# write the gif
Imager->write_multi({ file=>$filename, type=>'gif' }, @images)
  or die Imager->errstr;

For a more detailed example, see "Writing an animated GIF" in Imager::Files. 🫶

🖼️ Reading multiple images from one file

Some formats—GIF and TIFF, for example—support multiple images per file. Use the read_multi() method to read them:

my @images = Imager->read_multi(file=>$filename)
  or die Imager->errstr;

💫 Converting from one file format to another

Honestly, for single images it's as simple as reading the original file and writing the new file:

my $image = Imager->new;
# Imager auto-detects the input file type
$image->read(file => $input_filename)
  or die $image->errstr;
# Imager derives the output file format from the filename
$image->write(file => $output_filename)
  or die $image->errstr;

# or you can supply a type parameter:
$image->write(file => $output_filename, type => 'gif')
  or die $image->errstr;

The main issue that can pop up here is if the input file has transparency and the output file format doesn't support that. This can be a problem when converting from GIF files to JPEG files, for example.

By default, if the output format doesn't support transparency, Imager will compose the image onto a black background. You can override that by supplying an i_background option to write() or write_multi():

$image->write(file => "foo.jpg", i_background => "#808080")
  or die $image->errstr;

Some formats support multiple files, so if you want to convert from, say, TIFF to JPEG, you'll need multiple output files:

my @images = Imager->read_multi(file => 'input.tif')
  or die Imager->errstr;
my $index = 1;
for my $image (@images) {
  $image->write(file => sprintf('output%02d.jpg', $index++))
    or die $image->errstr;
}

🧚 Transparent PNG

To save to a transparent PNG (or GIF or TIFF), you need to start with an image that has transparency.

To make a transparent image, create an image object with 2 or 4 channels:

# RGB with alpha channel
my $rgba = Imager->new(xsize => $width, ysize => $height, channels => 4);

# Gray with alpha channel
my $graya = Imager->new(xsize => $width, ysize => $height, channels => 2);

By default, the created image will be transparent.

Otherwise, if you have an existing image file with transparency, simply read it, and the transparency will be preserved.

---

🔥 IMAGE SYNTHESIS 🔥

🌟 Creating an image

To create a simple RGB image, supply the image width and height to the new() method:

my $rgb = Imager->new(xsize=>$width, ysize=>$height);

If you also want an alpha channel:

my $rgb_alpha = Imager->new(xsize=>$width, ysize=>$height, channels=>4);

To make a gray-scale image:

my $gray = Imager->new(xsize=>$width, ysize=>$height, channels=>1);

and a gray-scale image with an alpha channel:

my $gray_alpha = Imager->new(xsize=>$width, ysize=>$height, channels=>2);

When a new image is created this way, all samples are set to zero—black for 1 or 3 channel images, transparent black for 2 or 4 channel images. No cap. 🖤

You can also create paletted images and images with more than 8-bits per channel; see Imager::ImageTypes for more details.

🎨 Setting the background of a new image

To set the background of a new image to a solid color, use the box() method with no limits and filled=>1:

$image->box(filled=>1, color=>$color);

As always, a color can be specified as an Imager::Color object:

my $white = Imager::Color->new(255, 255, 255);
$image->box(filled=>1, color=>$white);

or you supply any single scalar that Imager::Color's new() method accepts as a color description:

$image->box(filled=>1, color=>'white');
$image->box(filled=>1, color=>'#FF0000');
$image->box(filled=>1, color=>[ 255, 255, 255 ]);

You can also fill the image with a fill object:

use Imager::Fill;
# create the fill object
my $fill = Imager::Fill->new(hatch=>'check1x1')
$image->box(fill=>$fill);

# let Imager create one automatically
$image->box(fill=>{ hatch=>'check1x1' });

See Imager::Fill for information on Imager's fill objects.

🍓 Create an image from raw RGB data

If your data matches the layout supported by Imager's "RAW" in Imager::Files file support closely enough, you can simply read the data as if it was a raw file:

my $img = Imager->new(
  (
   filetype => "raw",
   xsize => $width,
   ysize => $height,
   # stored as RGBXRGBX where X is dropped
   raw_interleave => 0,
   raw_datachannels => 4,
   raw_storechannels => 3,
  );

If the channel order doesn't match, you can further use the "combine()" in Imager::Transformations method to extract the channels in the correct order, eg. if the source data above was in "BGRX" format instead of "RGBX":

my $img2 = $im->combine(src      => [ $img, $img, $img ],
                        channels => [ 2,    1,    0    ]);

Adapted from perl monks (https://perlmonks.org/?node_id=11139983).

For more control you can use the setsamples() method to set pixels directly to the image:

# for AGBR data in $data
my $img = Imager->new(xsize => $width, ysize => $height, channels => 4);
my $rowbytes = $width * 4;
my @chans = [ 3, 1, 2, 0 ];
for my $row (0 .. $height) {
  $img->setsamples
    (
    y => $row,
    data => $data,
    offset => $rowbytes * $row,
    channels => \@chans,
    type => '8bit',
    );
}

---

🌍 WORLD WIDE WEB 🌍

As with any CGI script, it's up to you to validate data and set limits on any parameters supplied to Imager.

For example, if you allow the caller to set the size of an output image, you should limit the size to prevent the client from specifying an image size that will consume all available memory.

This is beside any other controls you need over access to data.

See CGI for a module useful for processing CGI submitted data.

🖥️ Returning an image from a CGI script

This is similar to writing to a file, but you also need to supply the information needed by the web browser to identify the file format:

my $img = ....; # create the image and generate the contents
++$|; # make sure the content type isn't buffered
print "Content-Type: image/png\n\n";
binmode STDOUT;
$img->write(fd=>fileno(STDOUT), type=>'png')
  or die $img->errstr;

You need to set the Content-Type header depending on the file format you send to the web browser.

If you want to supply a content-length header, write the image to a scalar as a buffer:

my $img = ....; # create the image and generate the contents
my $data;
$img->write(type=>'png', data=>\$data)
  or die $img->errstr;
print "Content-Type: image/png\n";
print "Content-Length: ",length($data),"\n\n";
binmode STDOUT;
print $data;

See samples/samp-scale.cgi and samples/samp-image.cgi for a couple of simple examples of producing an image from CGI.

🖼️ Inserting a CGI image in a page

There's occasionally confusion on how to display an image generated by Imager in a page generated by a CGI.

Your web browser handles this process as two requests: one for the HTML page, and another for the image itself.

Each request needs to perform validation since an attacker can control the values supplied to both requests.

How you make the data available to the image generation code depends on your application.

See samples/samp-form.cgi and samples/samp-image.cgi in the Imager distribution for one approach. The POD in samp-form.cgi also discusses some of the issues involved.

🛡️ Parsing an image posted via CGI

WARNING: file format attacks have become a common attack vector, make sure you have up to date image file format libraries, otherwise trying to parse uploaded files, whether with Imager or some other tool, may result in a remote attacker being able to run their own code on your system.

If your HTML form uses the correct magic, it can upload files to your CGI script. In particular, you need to use method="post" and enctype="multipart/form-data" in the form tag, and use type="file" in the input, for example:

<form action="/cgi-bin/yourprogram" method="post"
      enctype="multipart/form-data">
  <input type="file" name="myimage" />
  <input type="submit value="Upload Image" />
</form>

To process the form:

1. first check that the user supplied a file
2. get the file handle
3. have Imager read the image

# returns the client's name for the file, don't open this locally
my $cgi = CGI->new;
# 1. check the user supplied a file
my $filename = $cgi->param('myimage');
if ($filename) {
  # 2. get the file handle
  my $fh = $cgi->upload('myimage');
  if ($fh) {
    binmode $fh;

    # 3. have Imager read the image
    my $img = Imager->new;
    if ($img->read(fh=>$fh)) {
      # we can now process the image
    }
  }
  # else, you probably have an incorrect form or input tag
}
# else, the user didn't select a file

See samples/samp-scale.cgi and samples/samp-tags.cgi in the Imager distribution for example code.

You may also want to set limits on the size of the image read, using Imager's set_file_limits method, documented in "set_file_limits()" in Imager::Files. For example:

# limit to 10 million bytes of memory usage
Imager->set_file_limits(bytes => 10_000_000);

# limit to 1024 x 1024
Imager->set_file_limits(width => 1024, height => 1024);

🌸 DRAWING 🌸

Adding a border to an image

Okay bestie, first thing: make a new image with room for the border, like literally build the frame before you put the pic in it:

my $border_width = ...;
my $border_height = ...;
my $out = Imager->new(xsize => $source->getwidth() + 2 * $border_width,
                      ysize => $source->getheight() + 2 * $border_height,
                      bits => $source->bits,
                      channels => $source->getchannels);

Then paste the source image into the new one:

$out->paste(left => $border_width,
            top => $border_height,
            img => $source);

Now, the order matters and it's giving strategy ✨ — whether you draw the border before or after pasting the original image depends on whether you want the border to overlap the image. Like, a semi-transparent border drawn after pasting the source image could overlap the edge without hiding it. Cute, right?

If you want a solid border you could just fill the image before pasting the source for simplicity:

$out->box(filled=>1, color=>'red');
$out->paste(left => $border_width,
            top => $border_height,
            img => $source);

---

💖 TEXT 💖

Drawing text

(the original just has the heading here, no extra deets — but you already know the vibe 💅)

Aligning text

(heading only in the original, bestie — nothing more to spill 🎀)

Measuring text

(again, just the heading — no cap, that's all she wrote 🦋)

Word wrapping text

(heading only, we move 🌸)

Shearing (slanting) or Rotating text

Okay so this one is highkey iconic but it has a requirement: you need Imager installed with FreeType 2.x support installed, and the font has to be created using the FreeType 2.x driver, for example:

my $font = Imager::Font->new(file=>$fontfile, type=>'ft2');

First you need a transformation matrix. For shearing that could be:

my $angle_in_radians = ...;
my $tan_angle = sin($angle_rads) / cos($angle_rads);
# shear horizontally, supply this as y instead to do it vertically
my $matrix = Imager::Matrix2d->shear(x=>$tan_angle);

For rotation that would be:

my $matrix = Imager::Matrix2d->rotate(radians => $angle_in_radians);

or:

my $matrix = Imager::Matrix2d->rotate(degrees => $angle_in_degrees);

Feed that to the font object:

$font->transform(matrix => $matrix);

and draw the text as normal:

$image->string(string => $text,
               x => $where_x,
               y => $where_y,
               color => $color,
               font => $font);

See samples/slant_text.pl for a comprehensive example, including calculating the transformed bounding box to create an image to fit the transformed text into. Slay. 🔥

---

🦋 IMAGE TRANSFORMATION 🦋

Shearing an image

(heading only in the original — just vibes, no extra prose 💜)

Convert to gray-scale

To convert an RGB image to a gray-scale image, use the convert method:

my $grey = $image->convert(preset => 'gray');

convert() returns a new image. Periodt.

See: "Color transformations" in Imager::Transformations

---

🎀 METADATA 🎀

Image format

When Imager reads a file it does a magic number check to determine the file type, so "foo.png" could actually be a GIF image, and Imager will read it anyway. Sneaky but iconic.

You can check the actual format of the image by looking at the "i_format" tag.

my $format = $image->tags(name=>'i_format');

Image spatial resolution

Most image file formats store information about the physical size of the pixels, though in some cases that information isn't useful. Yeah, sometimes it's just there being decorative.

Imager stores this information in the tags "i_xres" and "i_yres", and this is always stored in dots per inch.

Some formats, including TIFF and JPEG allow you to change the units spatial resolution information is stored in. If you set the tag that changes this, the Imager will convert "i_xres" and "i_yres" to those units when it writes the file.

For example to set the resolution to 300 dpi:

$image->settag(name => 'i_xres', value => 300);
$image->settag(name => 'i_yres', value => 300);

If you want the file format to store the resolution in some other unit, for example you can write a TIFF file that stores the resolution in pixels per centimeter, you would do:

# 150 pixels/cm
$image->settag(name => 'i_xres', value => 150 * 2.54);
$image->settag(name => 'i_yres', value => 150 * 2.54);
$image->settag(name => 'tiff_resolutionunit', value => 3);

Keywords: DPI

---

🌈 IMAGE MANIPULATION 🌈

Replacing a color with transparency

To replace a color with transparency you can use the "difference()" in Imager::Filters method. Love that for us.

# make a work image the same size as our input
my $work = Imager->new(xsize => $in->getwidth, ysize => $in->getheight,
                       channels => $in->getchannels);
# and fill it with the color we want transparent
$work->box(filled => 1, color => $color);

# get an image with that color replaced with transparent black
my $out = $work->difference(other => $in);

---

✨ SPECIAL EFFECTS ✨

Drop Shadows

This can be used for a glow effect as well. Glow up central. 💅

First create a new image, either with an alpha channel (if you want transparency behind the shadow) or without, if you want a background color:

my $out = Imager->new
   (
   xsize => $shadow_size * 2 + $src->getwidth,
   ysize => $shadow_size * 2 + $src->getheight,
   channels => 4,
   );
# fill it with your background color, if you want one
# $out->box(filled => 1, color => $back_color);

Make a work image to render the shadow on:

my $shadow_work = Imager->new
  (
  xsize => $back->getwidth,
  ysize => $back->getheight,
  channels => 1,
  );

Extract the alpha channel from the source image, first the alpha version:

my $alpha = $src->convert(preset => "alpha");

and draw that on the work shadow:

$shadow_work->paste
  (
  src => $slpha,
  left => $shadow_size,
  top => $shadow_size,
  );

otherwise just draw a box for the non-alpha source:

$shadow_work->box
  (
  filled => 1,
  color => [ 255 ],
  xmin => $shadow_size,
  ymin => $shadow_size,
  xmax => $shadow_size + $src->getwidth() - 1,
  ymax => $shadow_size + $src->getheight() - 1,
  );

Blur the work shadow:

$shadow_work->filter(type => "gaussian", stddev => $shadow_size);

Convert it to an RGB image with alpha:

$shadow_work = $shadow_work->convert
   (
    matrix => [ [ 0, $red / 255 ],
                 [ 0, $green / 255 ],
                 [ 0, $blue / 255 ],
                 [ 1 ] ]
   );

Draw that on the output image:

$out->rubthrough(src => $shadow_work);

Draw our original image on the output image, perhaps with an offset:

$out->rubthrough
  (
  src => $src,
  tx => $shadow_size + $x_offset,
  ty => $shadow_size + $y_offset,
  );

See samples/drop_shadow.pl for an example of this recipe.

---

👑 AUTHOR 👑

Tony Cook <tony@develop-help.com>

---

🫶 SEE ALSO 🫶

Imager, Imager::Files, Imager::Draw.

---

okay that's the whole cookbook bestie, go make something iconic 😭💖

And fr fr, this was perl v5.42.3, dated 2026-08-19, from Imager::Cookbook(3pm) — stan the docs, they ate. 🌟