Imager

Section: User Contributed Perl Documentation (3)
Updated: 2008-03-29
Index Return to Main Contents
 

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;

  my $img = Imager->new();
  # see Imager::Files for information on the read() method
  $img->read(file=>$file) or die $img->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 jpg 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

*
Imager - This document - Synopsis, Example, Table of Contents and Overview.
*
Imager::Tutorial - a brief introduction to Imager.
*
Imager::Cookbook - how to do various things with Imager.
*
Imager::ImageTypes - Basics of constructing image objects with "new()": Direct type/virtual images, RGB(A)/paletted images, 8/16/double bits/channel, color maps, channel masks, image tags, color quantization. Also discusses basic image information methods.
*
Imager::Files - IO interaction, reading/writing images, format specific tags.
*
Imager::Draw - Drawing Primitives, lines, boxes, circles, arcs, flood fill.
*
Imager::Color - Color specification.
*
Imager::Fill - Fill pattern specification.
*
Imager::Font - General font rendering, bounding boxes and font metrics.
*
Imager::Transformations - Copying, scaling, cropping, flipping, blending, pasting, convert and map.
*
Imager::Engines - Programmable transformations through "transform()", "transform2()" and "matrix_transform()".
*
Imager::Filters - Filters, sharpen, blur, noise, convolve etc. and filter plugins.
*
Imager::Expr - Expressions for evaluation engine used by transform2().
*
Imager::Matrix2d - Helper class for affine transformations.
*
Imager::Fountain - Helper for making gradient profiles.
*
Imager::API - using Imager's C API
*
Imager::APIRef - API function reference
*
Imager::Inline - using Imager's C API from Inline::C
*
Imager::ExtUtils - tools to get access to Imager's C API.
 

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 Imager::ImageTypes.  

METHOD INDEX

Where to find information on methods for Imager class objects.

addcolors() - ``addcolors'' in Imager::ImageTypes

addtag() - ``addtag'' in Imager::ImageTypes - add image tags

align_string() - ``align_string'' in Imager::Draw

arc() - ``arc'' in Imager::Draw

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

box() - ``box'' in Imager::Draw

circle() - ``circle'' in Imager::Draw

colorcount() - ``colorcount'' in Imager::Draw

combines() - ``combines'' in Imager::Draw

compose() - ``compose'' in Imager::Transformations

convert() - ``Color transformations'' in Imager::Transformations - transform the color space

copy() - ``copy'' in Imager::Transformations

crop() - ``crop'' in Imager::Transformations - extract part of an image

def_guess_type() - ``def_guess_type'' in Imager::Files

deltag() - ``deltag'' in Imager::ImageTypes - delete image tags

difference() - ``Image Difference'' in Imager::Filters

errstr() - ``Basic Overview''

filter() - Imager::Filters

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

flip() - ``flip'' in Imager::Transformations

flood_fill() - ``flood_fill'' in Imager::Draw

getchannels() - ``getchannels'' in Imager::ImageTypes

getcolorcount() - ``getcolorcount'' in Imager::ImageTypes

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

getcolorusage() - ``getcolorusage'' in Imager::ImageTypes

getcolorusagehash() - ``getcolorusagehash'' in Imager::ImageTypes

get_file_limits() - ``Limiting the sizes of images you read'' in Imager::Files

getheight() - ``getwidth'' in Imager::ImageTypes

getmask() - ``getmask'' in Imager::ImageTypes

getpixel() - ``getpixel'' in Imager::Draw

getsamples() - ``getsamples'' in Imager::Draw

getscanline() - ``getscanline'' in Imager::Draw

getwidth() - ``getwidth'' in Imager::ImageTypes

img_set() - ``img_set'' in Imager::ImageTypes

init() - ``init'' in Imager::ImageTypes

is_bilevel() - ``is_bilevel'' in Imager::ImageTypes

line() - ``line'' in Imager::Draw

load_plugin() - ``load_plugin'' in Imager::Filters

map() - ``Color Mappings'' in Imager::Transformations - remap color channel values

masked() - ``masked'' in Imager::ImageTypes - make a masked image

matrix_transform() - ``matrix_transform'' in Imager::Engines

maxcolors() - ``maxcolors'' in Imager::ImageTypes

NC() - ``NC'' in Imager::Handy

NCF() - ``NCF'' in Imager::Handy

new() - ``new'' in Imager::ImageTypes

newcolor() - ``newcolor'' in Imager::Handy

newcolour() - ``newcolour'' in Imager::Handy

newfont() - ``newfont'' in Imager::Handy

NF() - ``NF'' in Imager::Handy

open() - Imager::Files - an alias for read()

parseiptc() - ``parseiptc'' in Imager::Files - parse IPTC data from a JPEG image

paste() - ``paste'' in Imager::Transformations - draw an image onto an image

polygon() - ``polygon'' in Imager::Draw

polyline() - ``polyline'' in Imager::Draw

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

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

read_types() - ``read_types'' in Imager::Files - list image types Imager can read.

register_filter() - ``register_filter'' in Imager::Filters

register_reader() - ``register_reader'' in Imager::Filters

register_writer() - ``register_writer'' in Imager::Filters

rotate() - ``rotate'' in Imager::Transformations

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

scale() - ``scale'' in Imager::Transformations

scale_calculate() - ``scale_calculate'' in Imager::Transformations

scaleX() - ``scaleX'' in Imager::Transformations

scaleY() - ``scaleY'' in Imager::Transformations

setcolors() - ``setcolors'' in Imager::ImageTypes - set palette colors in a paletted image

set_file_limits() - ``Limiting the sizes of images you read'' in Imager::Files

setmask() - ``setmask'' in Imager::ImageTypes

setpixel() - ``setpixel'' in Imager::Draw

setsamples() - ``setsamples'' in Imager::Draw

setscanline() - ``setscanline'' in Imager::Draw

settag() - ``settag'' in Imager::ImageTypes

string() - ``string'' in Imager::Draw - draw text on an image

tags() - ``tags'' in Imager::ImageTypes - fetch image tags

to_paletted() - ``to_paletted'' in Imager::ImageTypes

to_rgb16() - ``to_rgb16'' in Imager::ImageTypes

to_rgb8() - ``to_rgb8'' in Imager::ImageTypes

transform() - ``transform'' in Imager::Engines

transform2() - ``transform2'' in Imager::Engines

type() - ``type'' in Imager::ImageTypes - type of image (direct vs paletted)

unload_plugin() - ``unload_plugin'' in Imager::Filters

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

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

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

write_types() - ``read_types'' in Imager::Files - list image types Imager can write.  

CONCEPT INDEX

animated GIF - ``Writing an animated GIF'' in Imager::Files

aspect ratio - ``i_xres'' in Imager::ImageTypes, ``i_yres'' in Imager::ImageTypes, ``i_aspect_only'' in Imager::ImageTypes

blend - alpha blending one image onto another ``rubthrough'' in Imager::Transformations

blur - ``guassian'' in Imager::Filters, ``conv'' in Imager::Filters

boxes, drawing - ``box'' in Imager::Draw

changes between image - ``Image Difference'' in Imager::Filter

color - Imager::Color

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

combine modes - ``combine'' in Imager::Fill

compare images - ``Image Difference'' in Imager::Filter

contrast - ``contrast'' in Imager::Filter, ``autolevels'' in Imager::Filter

convolution - ``conv'' in Imager::Filter

cropping - ``crop'' in Imager::Transformations

CUR files - ``ICO (Microsoft Windows Icon) and CUR (Microsoft Windows Cursor)'' in Imager::Files

"diff" images - ``Image Difference'' in Imager::Filter

dpi - ``i_xres'' in Imager::ImageTypes, ``Image spatial resolution'' in Imager::Cookbook

drawing boxes - ``box'' in Imager::Draw

drawing lines - ``line'' in Imager::Draw

drawing text - ``string'' in Imager::Draw, ``align_string'' in Imager::Draw

error message - ``Basic Overview''

files, font - Imager::Font

files, image - Imager::Files

filling, types of fill - Imager::Fill

filling, boxes - ``box'' in Imager::Draw

filling, flood fill - ``flood_fill'' in Imager::Draw

flood fill - ``flood_fill'' in Imager::Draw

fonts - Imager::Font

fonts, drawing with - ``string'' in Imager::Draw, ``align_string'' in Imager::Draw, Imager::Font::Wrap

fonts, metrics - ``bounding_box'' in Imager::Font, Imager::Font::BBox

fonts, multiple master - ``MULTIPLE MASTER FONTS'' in Imager::Font

fountain fill - ``Fountain fills'' in Imager::Fill, ``fountain'' in Imager::Filters, Imager::Fountain, ``gradgen'' in Imager::Filters

GIF files - ``GIF'' in Imager::Files

GIF files, animated - ``Writing an animated GIF'' in Imager::File

gradient fill - ``Fountain fills'' in Imager::Fill, ``fountain'' in Imager::Filters, Imager::Fountain, ``gradgen'' in Imager::Filters

grayscale, convert image to - ``convert'' in Imager::Transformations

guassian blur - ``guassian'' in Imager::Filter

hatch fills - ``Hatched fills'' in Imager::Fill

ICO files - ``ICO (Microsoft Windows Icon) and CUR (Microsoft Windows Cursor)'' in Imager::Files

invert image - ``hardinvert'' in Imager::Filter

JPEG - ``JPEG'' in Imager::Files

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

lines, drawing - ``line'' in Imager::Draw

matrix - Imager::Matrix2d, ``Matrix Transformations'' in Imager::Transformations, ``transform'' in Imager::Font

metadata, image - ``Tags'' in Imager::ImageTypes

mosaic - ``mosaic'' in Imager::Filter

noise, filter - ``noise'' in Imager::Filter

noise, rendered - ``turbnoise'' in Imager::Filter, ``radnoise'' in Imager::Filter

paste - ``paste'' in Imager::Transformations, ``rubthrough'' in Imager::Transformations

pseudo-color image - ``to_paletted'' in Imager::ImageTypes, ``new'' in Imager::ImageTypes

posterize - ``postlevels'' in Imager::Filter

png files - Imager::Files, ``PNG'' in Imager::Files

pnm - ``PNM (Portable aNy Map)'' in Imager::Files

rectangles, drawing - ``box'' in Imager::Draw

resizing an image - ``scale'' in Imager::Transformations, ``crop'' in Imager::Transformations

RGB (SGI) files - ``SGI (RGB, BW)'' in Imager::Files

saving an image - Imager::Files

scaling - ``scale'' in Imager::Transformations

SGI files - ``SGI (RGB, BW)'' in Imager::Files

sharpen - ``unsharpmask'' in Imager::Filters, ``conv'' in Imager::Filters

size, image - ``getwidth'' in Imager::ImageTypes, ``getheight'' in Imager::ImageTypes

size, text - ``bounding_box'' in Imager::Font

tags, image metadata - ``Tags'' in Imager::ImageTypes

text, drawing - ``string'' in Imager::Draw, ``align_string'' in Imager::Draw, Imager::Font::Wrap

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

text, measuring - ``bounding_box'' in Imager::Font, Imager::Font::BBox

tiles, color - ``mosaic'' in Imager::Filter

unsharp mask - ``unsharpmask'' in Imager::Filter

watermark - ``watermark'' in Imager::Filter

writing an image to a file - Imager::Files  

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

Patches

I accept patches, preferably against the main branch in subversion. You should 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.  

AUTHOR

Tony Cook <tony@imager.perl.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.  

SEE ALSO

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

<http://imager.perl.org/>

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

Other perl imaging modules include:

GD(3), Image::Magick(3), Graphics::Magick(3).


 

Index

NAME
SYNOPSIS
DESCRIPTION
Overview of documentation
Basic Overview
ERROR HANDLING
METHOD INDEX
CONCEPT INDEX
SUPPORT
CONTRIBUTING TO IMAGER
Feedback
Patches
AUTHOR
SEE ALSO

linux.jgfs.net manual pages