/ 
Imager-0.49
River stage three • 120 direct dependents • 144 total dependents
/ Imager::Tutorial
Security Advisories (6)
CVE-2016-1238 (2016-08-02)

Imager would search the default current directory entry in @INC when searching for file format support modules.

CVE-2008-1928 (2008-04-24)

Buffer overflow in Imager 0.42 through 0.63 allows attackers to cause a denial of service (crash) via an image based fill in which the number of input channels is different from the number of output channels.

CPANSA-Imager-2014-01 (2014-01-03)

When drawing on an image with an alpha channel where the source minimum is greater than zero, Imager would read from beyond the end of a malloc() allocated buffer. In rare circumstances this could lead to some of the source image not being written to the target image, or possibly to a segmentation fault.

CVE-2007-2459 (2007-05-02)

Heap-based buffer overflow in the BMP reader (bmp.c) in Imager perl module (libimager-perl) 0.45 through 0.56 allows remote attackers to cause a denial of service (application crash) and possibly execute arbitrary code via crafted 8-bit/pixel compressed BMP files.

CVE-2006-0053 (2006-04-10)

Imager (libimager-perl) before 0.50 allows user-assisted attackers to cause a denial of service (segmentation fault) by writing a 2- or 4-channel JPEG image (or a 2-channel TGA image) to a scalar, which triggers a NULL pointer dereference.

CVE-2024-53901 (2024-11-17)

"invalid next size" backtrace on use of trim on certain images

NAME

Imager::Tutorial - an introduction to Imager.

DESCRIPTION

Before you start

If you have the necessary knowledge, install the image format libraries you want Imager image file support for, and Imager itself, otherwise arrange to have it done.

You will also want some sort of image viewer tool, whether an image editor like Photoshop or the GIMP, or a web browser.

Hello Boxes! - A Simple Start

As with any perl program it's useful to start with a #! line, and to 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 a 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 <tony@imager.perl.org>

REVISION

$Revision: 811 $