Imager::Cookbook - recipes working with Imager
Various simple and not so simple ways to do things with Imager.
This is described in detail in Imager::Files.
my $image = Imager->new; $image->read(file=>$filename) or die $image->errstr;
See Imager::Files.
$image->write(file=>$filename) or die $image->errstr;
# build an array of images to use in the gif my @images; # synthesize the images or read them from files, it doesn't matter ... # write the gif Imager->write_multi({ file=>$filename, type=>'gif' }, @images) or die Imager->errstr;
See "Writing an animated GIF" in Imager::Files for a more detailed example.
Some formats, like GIF and TIFF support multiple images per file. Use the read_multi() method to read them:
my @images = Imager->read_multi(file=>$filename) or die Imager->errstr;
To create a simple RGB image, supply the image width and height to the new() method:
my $rgb = Imager->new(xsize=>$width, ysize=>$height);
If you also want an alpha channel:
my $rgb_alpha = Imager->new(xsize=>$width, ysize=>$height, channels=>4);
To make a grayscale image:
my $gray = Imager->new(xsize=>$width, ysize=>$height, channels=>1);
and a grayscale image with an alpha channel:
my $gray_alpha = Imager->new(xsize=>$width, ysize=>$height, channels=>2);
When a new image is created this way all samples are set to zero - black for 1 or 3 channel images, transparent black for 2 or 4 channel images.
You can also create paletted images and images with more than 8-bits per channel, see Imager::ImageTypes for more details.
To set the background of a new image to a solid color, use the box() method with no limits, and filled=>1:
filled=>1
$image->box(filled=>1, color=>$color);
As always, a color can be specified as an Imager::Color object:
my $white = Imager::Color->new(255, 255, 255); $image->box(filled=>1, color=>$white);
or you supply any single scalar that Imager::Color's new() method accepts as a color description:
$image->box(filled=>1, color=>'white'); $image->box(filled=>1, color=>'#FF0000'); $image->box(filled=>1, color=>[ 255, 255, 255 ]);
You can also fill the image with a fill object:
use Imager::Fill; # create the fill object my $fill = Imager::Fill->new(hatch=>'check1x1') $image->box(fill=>$fill); # let Imager create one automatically $image->box(fill=>{ hatch=>'check1x1' });
See Imager::Fill for information on Imager's fill objects.
As with any CGI script it's up to you to validate data and set limits on any parameters supplied to Imager.
For example, if you allow the caller to set the size of an output image you should limit the size to prevent the client from specifying an image size that will consume all available memory.
This is beside any any other controls you need over access to data.
See CGI for a module useful for processing CGI submitted data.
This is similar to writing to a file, but you also need to supply the information needed by the web browser to identify the file format:
my $img = ....; # create the image and generate the contents ++$|; # make sure the content type isn't buffered print "Content-Type: image/png\n\n"; binmode STDOUT; $img->write(fd=>fileno(STDOUT), type=>'png') or die $img->errstr;
You need to set the Content-Type header depending on the file format you send to the web browser.
If you want to supply a content-length header, write the image to a scalar as a buffer:
my $img = ....; # create the image and generate the contents my $data; $img->write(type=>'png', data=>\$data) or die $img->errstr; print "Content-Type: image/png\n"; print "Content-Length: ",length($data),"\n\n"; binmode STDOUT; print $data;
See samples/samp-scale.cgi and samples/samp-image.cgi for a couple of simple examples of producing an image from CGI.
samples/samp-scale.cgi
samples/samp-image.cgi
There's occasionally confusion on how to display an image generated by Imager in a page generated by a CGI.
Your web browser handles this process as two requests, one for the HTML page, and another for the image itself.
Each request needs to perform validation since an attacker can control the values supplied to both requests.
How you make the data available to the image generation code depends on your application.
See samples/samp-form.cgi and samples/samp-image.cgi in the Imager distribution for one approach. The POD in samp-form.cgi also discusses some of the issues involved.
samples/samp-form.cgi
samp-form.cgi
WARNING: file format attacks have become a common attack vector, make sure you have up to date image file format libraries, otherwise trying to parse uploaded files, whether with Imager or some other tool, may result in a remote attacker being able to run their own code on your system. Currently Imager makes no attempt to place size limits on a read image file. This may result in consumption of large amounts of memory. Future versions of Imager may provide mechanisms to limit the sizes of images read from files.
WARNING
If your HTML form uses the correct magic, it can upload files to your CGI script, in particular, you need to use method="post" and enctype="multipart/form-data" in the form tag, and use type="file" in the input, for example:
method="post"
enctype="multipart/form-data"
form
type="file"
input
<form action="/cgi-bin/yourprogram" method="post" enctype="multipart/form-data"> <input type="file" name="myimage" /> <input type="submit value="Upload Image" /> </form>
To process the form:
first check that the user supplied a file
get the file handle
have Imager read the image
# returns the client's name for the file, don't open this locally my $cgi = CGI->new; # 1. check the user supplied a file my $filename = $cgi->param('myimage'); if ($filename) { # 2. get the file handle my $fh = $cgi->upload('myimage'); if ($fh) { binmode $fh; # 3. have Imager read the image my $img = Imager->new; if ($img->read(fh=>$fh)) { # we can now process the image } } # else, you probably have an incorrect form or input tag } # else, the user didn't select a file
See samples/samp-scale.cgi and samples/samp-tags.cgi in the Imager distribution for example code.
samples/samp-tags.cgi
First make a new image with space for the border:
my $border_width = ...; my $border_height = ...; my $out = Imager->new(xsize => $source->getwidth() + 2 * $border_width, ysize => $source->getheight() + 2 * $border_height, bits => $source->bits, channels => $source->getchannels);
Then paste the source image into the new image:
$out->paste(left => $border_width, top => $border_height, img => $source);
Whether you draw the border before or after pasting the original image depends on whether you want the border to overlap the image, for example a semi-tranparent border drawn after pasting the source image could overlap the edge without hiding it.
If you want a solid border you could just fill the image before pasting the source for simplicity:
$out->box(filled=>1, color=>'red'); $out->paste(left => $border_width, top => $border_height, img => $source);
This requires that you have Imager installed with Freetype 2.x support installed, and that the font be created using the Freetype 2.x driver, for example:
my $font = Imager::Font->new(file=>$fontfile, type=>'ft2');
First you need a transformation matrix, for shearing that could be:
my $angle_in_radians = ...; my $tan_angle = sin($angle_rads) / cos($angle_rads); # shear horizontally, supply this as y instead to do it vertically my $matrix = Imager::Matrix2d->shear(x=>$tan_angle);
For rotation that would be:
my $matrix = Imager::Matrix2d->rotate(radians => $angle_in_radians);
or:
my $matrix = Imager::Matrix2d->rotate(degrees => $angle_in_degrees);
Feed that to the font object:
$font->transform(matrix => $matrix);
and draw the text as normal:
$image->string(string => $text, x => $where_x, y => $where_y, color => $color, font => $font);
See samples/slant_text.pl for a comprehensive example, including calculating the transformed bounding box to create an image to fit the transformed text into.
Keywords: DPI
Tony Cook <tony@develop-help.com>
Imager, Imager::Files, Imager::Draw.
To install Imager, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Imager
CPAN shell
perl -MCPAN -e shell install Imager
For more information on module installation, please visit the detailed CPAN module installation guide.