Imager - Perl extension for Generating 24 bit Images


NAME

Imager - Perl extension for Generating 24 bit Images


SYNOPSIS

  # Thumbnail example
  #!/usr/bin/perl -w
  use strict;
  use Imager;
  die "Usage: thumbmake.pl filename\n" if !-f $ARGV[0];
  my $file = shift;
  my $format;
  # see Imager::Files for information on the read() method
  my $img = Imager->new(file=>$file)
    or die Imager->errstr();
  $file =~ s/\.[^.]*$//;
  # Create smaller version
  # documented in Imager::Transformations
  my $thumb = $img->scale(scalefactor=>.3);
  # Autostretch individual channels
  $thumb->filter(type=>'autolevels');
  # try to save in one of these formats
  SAVE:
  for $format ( qw( png gif jpeg tiff ppm ) ) {
    # Check if given format is supported
    if ($Imager::formats{$format}) {
      $file.="_low.$format";
      print "Storing image as: $file\n";
      # documented in Imager::Files
      $thumb->write(file=>$file) or
        die $thumb->errstr;
      last SAVE;
    }
  }


DESCRIPTION

Imager is a module for creating and altering images. It can read and write various image formats, draw primitive shapes like lines,and polygons, blend multiple images together in various ways, scale, crop, render text and more.

Overview of documentation

Basic Overview

An Image object is created with $img = Imager->new(). Examples:

  $img=Imager->new();                         # create empty image
  $img->read(file=>'lena.png',type=>'png') or # read image from file
     die $img->errstr();                      # give an explanation
                                              # if something failed

or if you want to create an empty image:

  $img=Imager->new(xsize=>400,ysize=>300,channels=>4);

This example creates a completely black image of width 400 and height 300 and 4 channels.


ERROR HANDLING

In general a method will return false when it fails, if it does use the errstr() method to find out why:

errstr()
Returns the last error message in that context.

If the last error you received was from calling an object method, such as read, call errstr() as an object method to find out why:

  my $image = Imager->new;
  $image->read(file => 'somefile.gif')
     or die $image->errstr;

If it was a class method then call errstr() as a class method:

  my @imgs = Imager->read_multi(file => 'somefile.gif')
    or die Imager->errstr;

Note that in some cases object methods are implemented in terms of class methods so a failing object method may set both.

The Imager->new method is described in detail in the Imager::ImageTypes manpage.


METHOD INDEX

Where to find information on methods for Imager class objects.

addcolors() - addcolors() in the Imager::ImageTypes manpage - add colors to a paletted image

addtag() - addtag() in the Imager::ImageTypes manpage - add image tags

align_string() - align_string() in the Imager::Draw manpage - draw text aligned on a point

alphachannel() - alphachannel() in the Imager::ImageTypes manpage - return the channel index of the alpha channel (if any).

arc() - arc() in the Imager::Draw manpage - draw a filled arc

bits() - bits() in the Imager::ImageTypes manpage - number of bits per sample for the image

box() - box() in the Imager::Draw manpage - draw a filled or outline box.

check_file_limits() - check_file_limits() in the Imager::Files manpage

circle() - circle() in the Imager::Draw manpage - draw a filled circle

close_log() - close_log() in the Imager::ImageTypes manpage - close the Imager debugging log.

colorchannels() - colorchannels() in the Imager::ImageTypes manpage - the number of channels used for color.

colorcount() - colorcount() in the Imager::ImageTypes manpage - the number of colors in an image's palette (paletted images only)

colormodel() - colorcount() in the Imager::ImageTypes manpage - how color is represented.

combine() - combine() in the Imager::Transformations manpage - combine channels from one or more images.

combines() - combines() in the Imager::Draw manpage - return a list of the different combine type keywords

compose() - compose() in the Imager::Transformations manpage - compose one image over another.

convert() - convert() in the Imager::Transformations manpage - transform the color space

copy() - copy() in the Imager::Transformations manpage - make a duplicate of an image

crop() - crop() in the Imager::Transformations manpage - extract part of an image

def_guess_type() - def_guess_type() in the Imager::Files manpage - default function used to guess the output file format based on the output file name

deltag() - deltag() in the Imager::ImageTypes manpage - delete image tags

difference() - difference() in the Imager::Filters manpage - produce a difference images from two input images.

errstr() - errstr() - the error from the last failed operation.

filter() - filter() in the Imager::Filters manpage - image filtering

findcolor() - findcolor() in the Imager::ImageTypes manpage - search the image palette, if it has one

flip() - flip() in the Imager::Transformations manpage - flip an image, vertically, horizontally

flood_fill() - flood_fill() in the Imager::Draw manpage - fill an enclosed or same color area

getchannels() - getchannels() in the Imager::ImageTypes manpage - the number of samples per pixel for an image

getcolorcount() - getcolorcount() in the Imager::ImageTypes manpage - the number of different colors used by an image (works for direct color images)

getcolors() - getcolors() in the Imager::ImageTypes manpage - get colors from the image palette, if it has one

getcolorusage() - getcolorusage() in the Imager::ImageTypes manpage

getcolorusagehash() - getcolorusagehash() in the Imager::ImageTypes manpage

get_file_limits() - get_file_limits() in the Imager::Files manpage

getheight() - getheight() in the Imager::ImageTypes manpage - height of the image in pixels

getmask() - getmask() in the Imager::ImageTypes manpage - write mask for the image

getpixel() - getpixel() in the Imager::Draw manpage - retrieve one or more pixel colors

getsamples() - getsamples() in the Imager::Draw manpage - retrieve samples from a row or partial row of pixels.

getscanline() - getscanline() in the Imager::Draw manpage - retrieve colors for a row or partial row of pixels.

getwidth() - getwidth() in the Imager::ImageTypes manpage - width of the image in pixels.

img_set() - img_set() in the Imager::ImageTypes manpage - re-use an Imager object for a new image.

init() - init() in the Imager::ImageTypes manpage

is_bilevel() - is_bilevel() in the Imager::ImageTypes manpage - returns whether image write functions should write the image in their bilevel (blank and white, no gray levels) format

is_logging() is_logging() in the Imager::ImageTypes manpage - test if the debug log is active.

line() - line() in the Imager::Draw manpage - draw an interval

load_plugin() - load_plugin() in the Imager::Filters manpage

log() - log() in the Imager::ImageTypes manpage - send a message to the debugging log.

make_palette() - make_palette() in the Imager::ImageTypes manpage - produce a color palette from one or more input images.

map() - map() in the Imager::Transformations manpage - remap color channel values

masked() - masked() in the Imager::ImageTypes manpage - make a masked image

matrix_transform() - matrix_transform() in the Imager::Engines manpage

maxcolors() - maxcolors() in the Imager::ImageTypes manpage

NC() - NC() in the Imager::Handy manpage

NCF() - NCF() in the Imager::Handy manpage

new() - new() in the Imager::ImageTypes manpage

newcolor() - newcolor() in the Imager::Handy manpage

newcolour() - newcolour() in the Imager::Handy manpage

newfont() - newfont() in the Imager::Handy manpage

NF() - NF() in the Imager::Handy manpage

open() - read() in the Imager::Files manpage - an alias for read()

open_log() - open_log() in the Imager::ImageTypes manpage - open the debug log.

parseiptc() - parseiptc() in the Imager::Files manpage - parse IPTC data from a JPEG image

paste() - paste() in the Imager::Transformations manpage - draw an image onto an image

polygon() - polygon() in the Imager::Draw manpage

polyline() - polyline() in the Imager::Draw manpage

polypolygon() - polypolygon() in the Imager::Draw manpage

preload() - preload() in the Imager::Files manpage

read() - read() in the Imager::Files manpage - read a single image from an image file

read_multi() - read_multi() in the Imager::Files manpage - read multiple images from an image file

read_types() - read_types() in the Imager::Files manpage - list image types Imager can read.

register_filter() - register_filter() in the Imager::Filters manpage

register_reader() - register_reader() in the Imager::Files manpage

register_writer() - register_writer() in the Imager::Files manpage

rotate() - rotate() in the Imager::Transformations manpage

rubthrough() - rubthrough() in the Imager::Transformations manpage - draw an image onto an image and use the alpha channel

scale() - scale() in the Imager::Transformations manpage

scale_calculate() - scale_calculate() in the Imager::Transformations manpage

scaleX() - scaleX() in the Imager::Transformations manpage

scaleY() - scaleY() in the Imager::Transformations manpage

setcolors() - setcolors() in the Imager::ImageTypes manpage - set palette colors in a paletted image

set_file_limits() - set_file_limits() in the Imager::Files manpage

setmask() - setmask() in the Imager::ImageTypes manpage

setpixel() - setpixel() in the Imager::Draw manpage

setsamples() - setsamples() in the Imager::Draw manpage

setscanline() - setscanline() in the Imager::Draw manpage

settag() - settag() in the Imager::ImageTypes manpage

string() - string() in the Imager::Draw manpage - draw text on an image

tags() - tags() in the Imager::ImageTypes manpage - fetch image tags

to_paletted() - to_paletted() in the Imager::ImageTypes manpage

to_rgb16() - to_rgb16() in the Imager::ImageTypes manpage

to_rgb8() - to_rgb8() in the Imager::ImageTypes manpage

to_rgb_double() - to_rgb_double() in the Imager::ImageTypes manpage - convert to double per sample image.

transform() - transform() in the Imager::Engines manpage

transform2() - transform2() in the Imager::Engines manpage

type() - type() in the Imager::ImageTypes manpage - type of image (direct vs paletted)

unload_plugin() - unload_plugin() in the Imager::Filters manpage

virtual() - virtual() in the Imager::ImageTypes manpage - whether the image has it's own data

write() - write() in the Imager::Files manpage - write an image to a file

write_multi() - write_multi() in the Imager::Files manpage - write multiple image to an image file.

write_types() - read_types() in the Imager::Files manpage - list image types Imager can write.


CONCEPT INDEX

animated GIF - Writing an animated GIF in the Imager::Files manpage

aspect ratio - i_xres, i_yres, i_aspect_only in Common Tags in the Imager::ImageTypes manpage.

blend - alpha blending one image onto another rubthrough() in the Imager::Transformations manpage

blur - gaussian in the Imager::Filters manpage, conv in the Imager::Filters manpage

boxes, drawing - box() in the Imager::Draw manpage

changes between image - Image Difference in the Imager::Filters manpage

channels, combine into one image - combine() in the Imager::Transformations manpage

color - the Imager::Color manpage

color names - the Imager::Color manpage, the Imager::Color::Table manpage

combine modes - Combine Types in the Imager::Draw manpage

compare images - Image Difference in the Imager::Filters manpage

contrast - contrast in the Imager::Filters manpage, autolevels in the Imager::Filters manpage

convolution - conv in the Imager::Filters manpage

cropping - crop() in the Imager::Transformations manpage

CUR files - ICO (Microsoft Windows Icon) and CUR (Microsoft Windows Cursor) in the Imager::Files manpage

diff images - Image Difference in the Imager::Filters manpage

dpi - i_xres, i_yres in Common Tags in the Imager::ImageTypes manpage, Image spatial resolution in the Imager::Cookbook manpage

drawing boxes - box() in the Imager::Draw manpage

drawing lines - line() in the Imager::Draw manpage

drawing text - string() in the Imager::Draw manpage, align_string() in the Imager::Draw manpage

error message - ERROR HANDLING

files, font - the Imager::Font manpage

files, image - the Imager::Files manpage

filling, types of fill - the Imager::Fill manpage

filling, boxes - box() in the Imager::Draw manpage

filling, flood fill - flood_fill() in the Imager::Draw manpage

flood fill - flood_fill() in the Imager::Draw manpage

fonts - the Imager::Font manpage

fonts, drawing with - string() in the Imager::Draw manpage, align_string() in the Imager::Draw manpage, the Imager::Font::Wrap manpage

fonts, metrics - bounding_box() in the Imager::Font manpage, the Imager::Font::BBox manpage

fonts, multiple master - MULTIPLE MASTER FONTS in the Imager::Font manpage

fountain fill - Fountain fills in the Imager::Fill manpage, fountain in the Imager::Filters manpage, the Imager::Fountain manpage, gradgen in the Imager::Filters manpage

GIF files - GIF in the Imager::Files manpage

GIF files, animated - Writing an animated GIF in the Imager::Files manpage

gradient fill - Fountain fills in the Imager::Fill manpage, fountain in the Imager::Filters manpage, the Imager::Fountain manpage, gradgen in the Imager::Filters manpage

gray scale, convert image to - convert() in the Imager::Transformations manpage

gaussian blur - gaussian in the Imager::Filters manpage

hatch fills - Hatched fills in the Imager::Fill manpage

ICO files - ICO (Microsoft Windows Icon) and CUR (Microsoft Windows Cursor) in the Imager::Files manpage

invert image - hardinvert in the Imager::Filters manpage, hardinvertall in the Imager::Filters manpage

JPEG - JPEG in the Imager::Files manpage

limiting image sizes - Limiting the sizes of images you read in the Imager::Files manpage

lines, drawing - line() in the Imager::Draw manpage

matrix - the Imager::Matrix2d manpage, Matrix Transformations in the Imager::Engines manpage, transform() in the Imager::Font manpage

metadata, image - Tags in the Imager::ImageTypes manpage, the Image::ExifTool manpage

mosaic - mosaic in the Imager::Filters manpage

noise, filter - noise in the Imager::Filters manpage

noise, rendered - turbnoise in the Imager::Filters manpage, radnoise in the Imager::Filters manpage

paste - paste() in the Imager::Transformations manpage, rubthrough() in the Imager::Transformations manpage

pseudo-color image - to_paletted() in the Imager::ImageTypes manpage, new() in the Imager::ImageTypes manpage

posterize - postlevels in the Imager::Filters manpage

PNG files - the Imager::Files manpage, PNG in the Imager::Files manpage

PNM - PNM (Portable aNy Map) in the Imager::Files manpage

rectangles, drawing - box() in the Imager::Draw manpage

resizing an image - scale() in the Imager::Transformations manpage, crop() in the Imager::Transformations manpage

RGB (SGI) files - SGI (RGB, BW) in the Imager::Files manpage

saving an image - the Imager::Files manpage

scaling - scale() in the Imager::Transformations manpage

security - the Imager::Security manpage

SGI files - SGI (RGB, BW) in the Imager::Files manpage

sharpen - unsharpmask in the Imager::Filters manpage, conv in the Imager::Filters manpage

size, image - getwidth() in the Imager::ImageTypes manpage, getheight() in the Imager::ImageTypes manpage

size, text - bounding_box() in the Imager::Font manpage

tags, image metadata - Tags in the Imager::ImageTypes manpage

text, drawing - string() in the Imager::Draw manpage, align_string() in the Imager::Draw manpage, the Imager::Font::Wrap manpage

text, wrapping text in an area - the Imager::Font::Wrap manpage

text, measuring - bounding_box() in the Imager::Font manpage, the Imager::Font::BBox manpage

threads - the Imager::Threads manpage

tiles, color - mosaic in the Imager::Filters manpage

transparent images - the Imager::ImageTypes manpage, Transparent PNG in the Imager::Cookbook manpage

unsharp mask - unsharpmask in the Imager::Filters manpage

watermark - watermark in the Imager::Filters manpage

writing an image to a file - the Imager::Files manpage


SUPPORT

The best place to get help with Imager is the mailing list.

To subscribe send a message with subscribe in the body to:

   imager-devel+request@molar.is

or use the form at:

http://www.molar.is/en/lists/imager-devel/

where you can also find the mailing list archive.

You can report bugs by pointing your browser at:

https://rt.cpan.org/NoAuth/ReportBug.html?Queue=Imager

or by sending an email to:

bug-Imager@rt.cpan.org

Please remember to include the versions of Imager, perl, supporting libraries, and any relevant code. If you have specific images that cause the problems, please include those too.

If you don't want to publish your email address on a mailing list you can use CPAN::Forum:

  http://www.cpanforum.com/dist/Imager

You will need to register to post.


CONTRIBUTING TO IMAGER

Feedback

I like feedback.

If you like or dislike Imager, you can add a public review of Imager at CPAN Ratings:

  http://cpanratings.perl.org/dist/Imager

This requires a Bitcard account (http://www.bitcard.org).

You can also send email to the maintainer below.

If you send me a bug report via email, it will be copied to Request Tracker.

Patches

I accept patches, preferably against the master branch in git. Please include an explanation of the reason for why the patch is needed or useful.

Your patch should include regression tests where possible, otherwise it will be delayed until I get a chance to write them.

To browse Imager's git repository:

  http://git.imager.perl.org/imager.git

To clone:

  git clone git://git.imager.perl.org/imager.git

My preference is that patches are provided in the format produced by git format-patch, for example, if you made your changes in a branch from master you might do:

  git format-patch -k --stdout master >my-patch.txt

and then attach that to your bug report, either by adding it as an attachment in your email client, or by using the Request Tracker attachment mechanism.


AUTHOR

Tony Cook <tonyc@cpan.org> is the current maintainer for Imager.

Arnar M. Hrafnkelsson is the original author of Imager.

Many others have contributed to Imager, please see the README for a complete list.


LICENSE

Imager is licensed under the same terms as perl itself.

A test font, generated by the Debian packaged Fontforge, FT2/fontfiles/MMOne.pfb, contains a Postscript operator definition copyrighted by Adobe. See adobe.txt in the source for license information.


SEE ALSO

the perl manpage(1), the Imager::ImageTypes manpage(3), the Imager::Files manpage(3), the Imager::Draw manpage(3), the Imager::Color manpage(3), the Imager::Fill manpage(3), the Imager::Font manpage(3), the Imager::Transformations manpage(3), the Imager::Engines manpage(3), the Imager::Filters manpage(3), the Imager::Expr manpage(3), the Imager::Matrix2d manpage(3), the Imager::Fountain manpage(3)

http://imager.perl.org/

the Affix::Infix2Postfix manpage(3), the Parse::RecDescent manpage(3)

Other perl imaging modules include:

GD(3), the Image::Magick manpage(3), Graphics::Magick(3), the Prima::Image manpage, IPA.

For manipulating image metadata see the Image::ExifTool manpage.

If you're trying to use Imager for array processing, you should probably using PDL.

 Imager - Perl extension for Generating 24 bit Images