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¶
- •
- Imager - This document - Synopsis, Example, Table of Contents and
Overview.
- •
- Imager::Install - installation notes for Imager.
- •
- 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
plug-ins.
- •
- Imager::Expr - Expressions for evaluation engine used by
transform2().
- •
- Imager::Matrix2d - Helper class for affine transformations.
- •
- Imager::Fountain - Helper for making gradient profiles.
- •
- Imager::IO - Imager I/O abstraction.
- •
- 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.
- •
- Imager::Security - brief security notes.
- •
- Imager::Threads - brief information on working with threads.
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 - add
colors to a paletted image
addtag() - "
addtag()" in Imager::ImageTypes - add image
tags
align_string() - "
align_string()" in Imager::Draw - draw
text aligned on a point
arc() - "
arc()" in Imager::Draw - draw a filled arc
bits() - "
bits()" in Imager::ImageTypes - number of bits
per sample for the image
box() - "
box()" in Imager::Draw - draw a filled or
outline box.
check_file_limits() - "
check_file_limits()" in
Imager::Files
circle() - "
circle()" in Imager::Draw - draw a filled
circle
close_log() - "
close_log()" in Imager::ImageTypes -
close the Imager debugging log.
colorcount() - "
colorcount()" in Imager::ImageTypes -
the number of colors in an image's palette (paletted images only)
combine() - "
combine()" in Imager::Transformations -
combine channels from one or more images.
combines() - "
combines()" in Imager::Draw - return a
list of the different combine type keywords
compose() - "
compose()" in Imager::Transformations -
compose one image over another.
convert() - "
convert()" in Imager::Transformations -
transform the color space
copy() - "
copy()" in Imager::Transformations - make a
duplicate of an image
crop() - "
crop()" in Imager::Transformations - extract
part of an image
def_guess_type() - "
def_guess_type()" in Imager::Files -
default function used to guess the output file format based on the output file
name
deltag() - "
deltag()" in Imager::ImageTypes - delete
image tags
difference() - "
difference()" in Imager::Filters -
produce a difference images from two input images.
errstr() - "
errstr()" - the error from the last failed
operation.
filter() - "
filter()" in Imager::Filters - image
filtering
findcolor() - "
findcolor()" in Imager::ImageTypes -
search the image palette, if it has one
flip() - "
flip()" in Imager::Transformations - flip an
image, vertically, horizontally
flood_fill() - "
flood_fill()" in Imager::Draw - fill an
enclosed or same color area
getchannels() - "
getchannels()" in Imager::ImageTypes -
the number of samples per pixel for an image
getcolorcount() - "
getcolorcount()" in
Imager::ImageTypes - the number of different colors used by an image (works
for direct color images)
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() - "
get_file_limits()" in Imager::Files
getheight() - "
getheight()" in Imager::ImageTypes -
height of the image in pixels
getmask() - "
getmask()" in Imager::ImageTypes - write
mask for the image
getpixel() - "
getpixel()" in Imager::Draw - retrieve one
or more pixel colors
getsamples() - "
getsamples()" in Imager::Draw - retrieve
samples from a row or partial row of pixels.
getscanline() - "
getscanline()" in Imager::Draw -
retrieve colors for a row or partial row of pixels.
getwidth() - "
getwidth()" in Imager::ImageTypes - width
of the image in pixels.
img_set() - "
img_set()" in Imager::ImageTypes - re-use
an Imager object for a new image.
init() - "
init()" in Imager::ImageTypes
is_bilevel() - "
is_bilevel()" in Imager::ImageTypes -
returns whether image write functions should write the image in their bilevel
(blank and white, no gray levels) format
is_logging() "
is_logging()" in Imager::ImageTypes - test
if the debug log is active.
line() - "
line()" in Imager::Draw - draw an interval
load_plugin() - "
load_plugin()" in Imager::Filters
log() - "
log()" in Imager::ImageTypes - send a message
to the debugging log.
make_palette() - "
make_palette()" in Imager::ImageTypes
- produce a color palette from one or more input images.
map() - "
map()" 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() - "
read()" in Imager::Files - an alias for
read()
open_log() - "
open_log()" in Imager::ImageTypes - open
the debug log.
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
preload() - "
preload()" in Imager::Files
read() - "
read()" in Imager::Files - read a single image
from an image file
read_multi() - "
read_multi()" in 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::Files
register_writer() - "
register_writer()" in Imager::Files
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() - "
set_file_limits()" 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
to_rgb_double() - "
to_rgb_double()" in
Imager::ImageTypes - convert to double per sample image.
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() - "
write()" in Imager::Files - write an image to
a file
write_multi() - "
write_multi()" in 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", "i_yres", "i_aspect_only"
in "Common Tags" in Imager::ImageTypes.
blend - alpha blending one image onto another "
rubthrough()"
in Imager::Transformations
blur - "gaussian" in Imager::Filters, "conv" in
Imager::Filters
boxes, drawing - "
box()" in Imager::Draw
changes between image - "Image Difference" in Imager::Filters
channels, combine into one image - "
combine()" in
Imager::Transformations
color - Imager::Color
color names - Imager::Color, Imager::Color::Table
combine modes - "Combine Types" in Imager::Draw
compare images - "Image Difference" in Imager::Filters
contrast - "contrast" in Imager::Filters, "autolevels" in
Imager::Filters
convolution - "conv" in Imager::Filters
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::Filters
dpi - "i_xres", "i_yres" in "Common Tags" 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 - "ERROR HANDLING"
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::Files
gradient fill - "Fountain fills" in Imager::Fill, "fountain"
in Imager::Filters, Imager::Fountain, "gradgen" in Imager::Filters
gray scale, convert image to - "
convert()" in
Imager::Transformations
gaussian blur - "gaussian" in Imager::Filters
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::Filters,
"hardinvertall" in Imager::Filters
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::Engines, "
transform()" in Imager::Font
metadata, image - "Tags" in Imager::ImageTypes, Image::ExifTool
mosaic - "mosaic" in Imager::Filters
noise, filter - "noise" in Imager::Filters
noise, rendered - "turbnoise" in Imager::Filters, "radnoise"
in Imager::Filters
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::Filters
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
security - Imager::Security
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
threads - Imager::Threads
tiles, color - "mosaic" in Imager::Filters
transparent images - Imager::ImageTypes, "Transparent PNG" in
Imager::Cookbook
unsharp mask - "unsharpmask" in Imager::Filters
watermark - "watermark" in Imager::Filters
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:
where you can also find the mailing list archive.
You can report bugs by pointing your browser at:
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¶
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
<
http://www.graphicsmagick.org/perl.html>(3), Prima::Image, IPA.
For manipulating image metadata see Image::ExifTool.
If you're trying to use Imager for array processing, you should probably using
PDL.