The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Image-Base-Imager-14
River stage zero No dependents
++
/ Image::Base::Imager

NAME

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

SYNOPSIS

 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');

CLASS HIERARCHY

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

    Image::Base
      Image::Base::Imager

DESCRIPTION

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 the following. See Imager::Files for the full list.

    PNG
    JPEG
    TIFF
    PNM
    GIF
    BMP
    ICO  (including CUR)

The Imager "raw" format is the image RGB bytes and nothing else. It can't be read with load() here since the read requires size and further parameters describing the data. Writing a raw file with save() works.

Colour Names

Colour names are anything recognised by Imager::Color. As of Imager 0.80 this means named colours from

    /usr/share/gimp/palettes/Named_Colors   GIMP, if available
    /usr/share/X11/rgb.txt                  X11, if available
    Imager::Color::Table                    copy of rgb.txt

Or hex forms

    "#RGB"
    "#RRGGBB"

An Imager::Color object can also be given instead of a string.

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 drawing might give close-colour merging rather than allocating as drawing proceeds.

FUNCTIONS

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 with an odd number of pixels (ie. width==height and odd) are drawn with Imager and ellipses and even circles 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 -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.

ATTRIBUTES

-width (integer)
-height (integer)

Setting these changes the size of the image.

-imager

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 then 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 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.

SEE ALSO

Image::Base, Imager

HOME PAGE

http://user42.tuxfamily.org/image-base-imager/index.html

LICENSE

Image-Base-Imager is Copyright 2010, 2011, 2012, 2019 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 <http://www.gnu.org/licenses/>.