View on
Kevin Ryde > Image-Base-Imager-11 > Image::Base::Imager



Annotate this POD


View/Report Bugs
Module Version: 11   Source  


Image::Base::Imager -- draw images using Imager


 use Image::Base::Imager;
 my $image = Image::Base::Imager->new (-width => 100,
                                       -height => 100);
 $image->rectangle (0,0, 99,99, 'white');
 $image->xy (20,20, 'black');
 $image->line (50,50, 70,70, '#FF00FF');
 $image->line (50,50, 70,70, '#0000AAAA9999');
 $image->save ('/some/filename.png');


Image::Base::Imager is a subclass of Image::Base,



Image::Base::Imager extends Image::Base to create or update image files using the Imager module.

As of Imager 0.80 the supported file formats for read and write include PNG, JPEG, TIFF, PNM, GIF, BMP, and ICO (including CUR). See Imager::Files for the full list.

Colour names are anything recognised by Imager::Color. As of Imager 0.80 this means the GIMP Named_Colors if you have the GIMP installed, the X11 rgb.txt, hex "#RGB", "#RRGGBB", etc. The system rgb.txt is used if available, otherwise a copy in Imager::Color::Table. An Imager::Color object can also be given.

Paletted Images

For a paletted image, if Imager is given a colour not already in the palette then it converts the whole image to RGB. Image::Base::Imager doesn't try do anything about that yet. An add_colours can pre-load the palette.

The Image::Base intention is just to throw colour names at drawing functions, so perhaps Image::Base::Imager should extend the palette when necessary, or choose a close colour if full. But an $imager->to_paletted after all drawing might come out better than colours as drawing proceeds.


See "FUNCTIONS" in Image::Base for the behaviour common to all Image-Base classes.

$image = Image::Base::Imager->new (key=>value,...)

Create and return a new image object. A new image can be started with -width and -height,

    $image = Image::Base::Imager->new (-width => 200, -height => 100);

Or an existing file can be read,

    $image = Image::Base::Imager->new (-file => '/some/filename.png');

Or an Imager object can be given,

    $image = Image::Base::Imager->new (-imager => $iobj);
$image->ellipse ($x1,$y1, $x2,$y2, $colour, $fill)

Draw an ellipse within the rectangle with top-left corner $x1,$y1 and bottom-right $x2,$y2. Optional $fill true means a filled ellipse.

In the current implementation circles an odd number of pixels (ie. width==height and odd) are drawn with Imager and ellipses and even circles as such go to Image::Base. This is a bit inconsistent but uses the features of Imager as far as possible and its drawing should be faster.

$i->diamond ($x0, $y0, $x1, $y1, $colour)
$i->diamond ($x0, $y0, $x1, $y1, $colour, $fill)

Draw a diamond shape within the rectangle top left $x0,$y0 and bottom right $x1,$y1 using $colour. If optional argument $fill is true then the diamond is filled.

For reference, in the current implementation unfilled diamonds use the Imager polyline() but filled diamonds use the Image::Base code since the Imager filled polygon() is always blurred by anti-aliasing and don't want that (or not by default).

$image->save ()
$image->save ($filename)

Save to -file, or with a $filename argument set -file then save to that.

The file format is taken from the -file_format (see below) if that was set by a load or explicit set, otherwise Imager follows the filename extension. In both cases if format or extension is unrecognised then save() croaks.

$image->add_colours ($name, $name, ...)

Add colours to the image palette. Colour names are the same as to the drawing functions.

    $image->add_colours ('red', 'green', '#FF00FF');

For a non-paletted image add_colours does nothing since in that case each pixel has RGB component values, rather than an index into a palette.


-width (integer)
-height (integer)

Setting these changes the size of the image.


The underlying Imager object.

-file_format (string or undef)

The file format as a string like "png" or "jpeg", or undef if unknown or never set.

After load() the -file_format is the format read. Setting -file_format can change the format for a subsequent save().

This is held in the imager "i_format" tag and passed as the type when saving. If undef when saving, Imager will look at the filename extension.

There's no attempt to check or validate the -file_format value, since it's possible to add new formats to Imager at run time. Expect save() to croak if the format is unknown.

-hotx (integer or undef, default undef)
-hoty (integer or undef, default undef)

The cursor hotspot in CUR images (variant of ICO). These are the cur_hotspotx and cur_hotspoty tags in the Imager object.

-ncolours (integer, read-only)

The number of colours allocated in the palette, or undef on a non-paletted image. (The Imager colorcount.)

This is similar to the -ncolours of Image::Xpm.

-quality_percent (0 to 100 or undef)

The image quality when saving to JPEG format, or to TIFF format with jpeg compression method. JPEG compresses by reducing colours and resolution in ways that are not too noticeable to the human eye. 100 means full quality, no such reductions. undef means the Imager default, which is 75.

-quality_percent becomes the jpegquality and tiff_jpegquality options to the Imager write (see "JPEG" in Imager::Files and "TIFF" in Imager::Files). TIFF is only affected if its tiff_compression tag is set to "jpeg" using Imager settag() (the default is "packbits").

There's no -zlib_compression currently since believe Imager version 0.79 doesn't have anything to apply that to PNG saving.


Image::Base, Imager



Image-Base-Imager is Copyright 2010, 2011, 2012 Kevin Ryde

Image-Base-Imager is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 3, or (at your option) any later version.

Image-Base-Imager is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with Image-Base-Imager. If not, see <>.

syntax highlighting: