Imager - Perl extension for Generating 24 bit Images |
Imager - Perl extension for Generating 24 bit Images
# 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; } }
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.
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.
the Imager::Files manpage - IO interaction, reading/writing images, format
specific tags.
the Imager::Draw manpage - Drawing Primitives, lines, boxes, circles, arcs,
flood fill.
the Imager::Color manpage - Color specification.
the Imager::Fill manpage - Fill pattern specification.
the Imager::Font manpage - General font rendering, bounding boxes and font
metrics.
the Imager::Transformations manpage - Copying, scaling, cropping, flipping,
blending, pasting, convert and map.
the Imager::Engines manpage - Programmable transformations through
transform()
, transform2()
and matrix_transform()
.
the Imager::Filters manpage - Filters, sharpen, blur, noise, convolve etc. and
filter plug-ins.
the Imager::Expr manpage - Expressions for evaluation engine used by
transform2().
the Imager::Matrix2d manpage - Helper class for affine transformations.
the Imager::Fountain manpage - Helper for making gradient profiles.
the Imager::IO manpage - Imager I/O abstraction.
the Imager::API manpage - using Imager's C API
the Imager::APIRef manpage - API function reference
the Imager::Inline manpage - using Imager's C API from Inline::C
the Imager::ExtUtils manpage - tools to get access to Imager's C API.
the Imager::Security manpage - brief security notes.
the Imager::Threads manpage - brief information on working with threads.
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.
In general a method will return false when it fails, if it does use
the errstr()
method to find out why:
errstr()
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.
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.
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
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:
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.
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.
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.
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.
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.
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)
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 |