Imager::Tutorial(3pm)

omg hiiii bestie 💖✨ this is Imager::Tutorial(3pm), straight out of the User Contributed Perl Documentation, and it's literally an introduction to Imager. no cap, we're gonna make some boxes, put text on them, and use an existing image as a base. let's gooo 🫶

🌸 NAME 🌸

Imager::Tutorial — an introduction to Imager. 💅

💖 DESCRIPTION 💖

🎀 Before you start 🎀

okay so first vibe check: if you have the necessary knowledge, install the image format libraries you want Imager image file support for, and install Imager itself — otherwise arrange to have it done for you. 🧚

You'll also want some sort of image viewer tool. Could be an image editor like Photoshop or the GIMP, or a web browser. whatever slays. 🌈

🦋 Hello Boxes! - A Simple Start 🦋

As with any perl program, it's useful to start with a #! line and enable strict mode:

#!/usr/bin/perl -w
# you might to 'use warnings;' instead of the -w above
use strict;

These lines will be omitted in further examples. 👀

As with any module, you need to load it:

use Imager;

Now create an image to draw on:

my $image = Imager->new(xsize => 100, ysize => 100);

and draw a couple of filled rectangles on it:

$image->box(xmin => 0, ymin => 0, xmax => 99, ymax => 99,
            filled => 1, color => 'blue');
$image->box(xmin => 20, ymin => 20, xmax => 79, ymax => 79,
            filled => 1, color => 'green');

Since the first box fills the whole image, it can be simplified to:

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

and save it to a file:

$image->write(file=>'tutorial1.ppm')
    or die 'Cannot save tutorial1.ppm: ', $image->errstr;

So our completed program is:

use Imager;

my $image = Imager->new(xsize => 100, ysize => 100);

$image->box(filled => 1, color => 'blue');
$image->box(xmin => 20, ymin => 20, xmax => 79, ymax => 79,
            filled => 1, color => 'green');

$image->write(file=>'tutorial1.ppm')
    or die 'Cannot save tutorial1.ppm: ', $image->errstr;

🌟 Adding some text 🌟

The first thing you need to draw text is a font object:

# use a different file, depending on the font support you have in
# your installed Imager.
my $font_filename = 'fontfiles/ImUgly.ttf';
my $font = Imager::Font->new(file=>$font_filename)
  or die "Cannot load $font_filename: ", Imager->errstr;

If you're on Windows, you can supply a face name instead:

my $font = Imager::Font->new(face=>'Arial Bold')
  or die "Cannot load 'Arial Bold: ", Imager->errstr;

and draw the text:

my $text = "Hello Boxes!";
my $text_size = 12;

$font->align(string => $text,
             size => $text_size,
             color => 'red',
             x => $image->getwidth/2,
             y => $image->getheight/2,
             halign => 'center',
             valign => 'center',
             image => $image);

So inserting this into our existing code we have:

use Imager;

my $image = Imager->new(xsize => 100, ysize => 100);

$image->box(xmin => 0, ymin => 0, xmax => 99, ymax => 99,
            filled => 1, color => 'blue');
$image->box(xmin => 20, ymin => 20, xmax => 79, ymax => 79,
            filled => 1, color => 'green');

# use a different file, depending on the font support you have in
# your installed Imager.
my $font_filename = 'fontfiles/ImUgly.ttf';
my $font = Imager::Font->new(file=>$font_filename)
  or die "Cannot load $font_filename: ", Imager->errstr;

my $text = "Hello Boxes!";
my $text_size = 12;

$font->align(string => $text,
             size => $text_size,
             color => 'red',
             x => $image->getwidth/2,
             y => $image->getheight/2,
             halign => 'center',
             valign => 'center',
             image => $image);

$image->write(file=>'tutorial2.ppm')
    or die 'Cannot save tutorial2.ppm: ', $image->errstr;

🌈 Using an existing image as a base 🌈

To load an image from a file, first create an empty image object:

my $read_image = Imager->new;

then call the read method:

my $image_source = shift; # from the command-line
$read_image->read(file=>$image_source)
  or die "Cannot load $image_source: ", $image->errstr;

To keep to our working size, we'll scale the image:

# the scale() method always does a proportional scale, we don't want
# that here
my $scaled_image = $read_image->scaleX(pixels=>100)->scaleY(pixels=>100);

draw our inner box on that, and save the result:

$scaled_image->box(xmin => 20, ymin => 20, xmax => 79, ymax => 79,
            filled => 1, color => 'green');

$scaled_image->write(file=>'tutorial3.ppm')
    or die 'Cannot save tutorial3.ppm: ', $image->errstr;

so the complete program is:

use Imager;

my $read_image = Imager->new;

my $image_source = shift; # from the command-line
$read_image->read(file=>$image_source)
  or die "Cannot load $image_source: ", $image->errstr;

# the scale() method always does a proportional scale, we don't want
# that here
my $scaled_image = $read_image->scaleX(pixels=>100)->scaleY(pixels=>100);

$scaled_image->box(xmin => 20, ymin => 20, xmax => 79, ymax => 79,
            filled => 1, color => 'green');

$scaled_image->write(file=>'tutorial3.ppm')
    or die 'Cannot save tutorial3.ppm: ', $image->errstr;

👑 AUTHOR 👑

Tony Cook <tonyc@cpan.org> 💌

💅 REVISION 💅

$Revision$ ✨

---

byeeee bestie 💅💖 that's the whole Imager::Tutorial(3pm) page. it came from perl v5.42.3, dated 2026-08-19. mwah! 🫶✨