Imager::Files - working with image files
my $img = ...;
$img->write(file=>$filename, type=>$type)
or die "Cannot write: ",$img->errstr;
$img = Imager->new;
$img->read(file=>$filename, type=>$type)
or die "Cannot read: ", $img->errstr;
Imager->write_multi({ file=> $filename, ... }, @images)
or die "Cannot write: ", Imager->errstr;
my @imgs = Imager->read_multi(file=>$filename)
or die "Cannot read: ", Imager->errstr;
You can read and write a variety of images formats, assuming you have the appropriate libraries, and images can be read or written to/from files, file handles, file descriptors, scalars, or through callbacks.
To see which image formats Imager is compiled to support the following code snippet is sufficient:
use Imager; print join " ", keys %Imager::formats;
This will include some other information identifying libraries rather than file formats.
Reading writing to and from files is simple, use the read()
method to read an image:
my $img = Imager->new;
$img->read(file=>$filename, type=>$type)
or die "Cannot read $filename: ", $img->errstr;
and the write() method to write an image:
$img->write(file=>$filename, type=>$type)
or die "Cannot write $filename: ", $img->errstr;
If you're reading from a format that supports multiple images per
file, use the read_multi() method:
my @imgs = Imager->read_multi(file=>$filename, type=>$type)
or die "Cannot read $filename: ", Imager->errstr;
and if you want to write multiple images to a single file use the
write_multi() method:
Imager->write_multi({ file=> $filename, type=>$type }, @images)
or die "Cannot write $filename: ", Imager->errstr;
If the filename includes an extension that Imager recognizes, then you don't need the type, but you may want to provide one anyway. See /Guessing types for information on controlling this recognition.
When you read an image, Imager may set some tags, possibly including information about the spatial resolution, textual information, and animation information. See Imager::ImageTypes/Tags for specifics.
When reading or writing you can specify one of a variety of sources or targets:
file parameter is the name of the image file to be written to
or read from. If Imager recognizes the extension of the file you do
not need to supply a type.
fh is a file handle, typically either returned from
<IO::File-new()>>, or a glob from an open call. You should call
binmode on the handle before passing it to Imager.
Imager will set the handle to autoflush to make sure any buffered data is flushed , since Imager will write to the file descriptor (from fileno()) rather than writing at the perl level.
fd is a file descriptor. You can get this by calling the
fileno() function on a file handle, or by using one of the standard
file descriptor numbers.
If you get this from a perl file handle, you may need to flush any buffered output, otherwise it may appear in the output stream after the image.
data is a scalar containing the image file data,
when writing, data is a reference to the scalar to save the image
file data too. For GIF images you will need giflib 4 or higher, and
you may need to patch giflib to use this option for writing.
Imager will make calls back to your supplied coderefs to read, write and seek from/to/through the image file.
When reading from a file you can use either callback or readcb
to supply the read callback, and when writing callback or
writecb to supply the write callback.
When writing you can also supply the maxbuffer option to set the
maximum amount of data that will be buffered before your write
callback is called. Note: the amount of data supplied to your
callback can be smaller or larger than this size.
The read callback is called with 2 parameters, the minimum amount of data required, and the maximum amount that Imager will store in it's C level buffer. You may want to return the minimum if you have a slow data source, or the maximum if you have a fast source and want to prevent many calls to your perl callback. The read data should be returned as a scalar.
Your write callback takes exactly one parameter, a scalar containing the data to be written. Return true for success.
The seek callback takes 2 parameters, a POSITION, and a WHENCE, defined in the same way as perl's seek function.
You can also supply a closecb which is called with no parameters
when there is no more data to be written. This could be used to flush
buffered data.
Imager uses the code reference in $Imager::FORMATGUESS to guess the
file type when you don't supply a type. The code reference is
called with a single parameter, the filename of the file. The code
reference is only called if a file parameter is supplied to the
file access method.
Return either a valid Imager file type, or undef.
# I'm writing jpegs to weird filenames
local $Imager::FORMATGUESS = sub { 'jpeg' };
The different image formats can write different image type, and some have different options to control how the images are written.
When you call write() or write_multi() with an option that has
the same name as a tag for the image format you're writing, then the
value supplied to that option will be used to set the corresponding
tag in the image. Depending on the image format, these values will be
used when writing the image.
This replaces the previous options that were used when writing GIF
images. Currently if you use an obsolete option, it will be converted
to the equivalent tag and Imager will produced a warning. You can
suppress these warnings by calling the Imager::init() function with
the warn_obsolete option set to false:
Imager::init(warn_obsolete=>0);
At some point in the future these obsolete options will no longer be supported.
Imager can write PGM (Portable Gray Map) and PPM (Portable PixMaps) files, depending on the number of channels in the image. Currently the images are written in binary formats. Only 1 and 3 channel images can be written, including 1 and 3 channel paletted images.
$img->write(file=>'foo.ppm') or die $img->errstr;
Imager can read both the ASCII and binary versions of each of the PBM (Portable BitMap), PGM and PPM formats.
$img->read(file=>'foo.ppm') or die $img->errstr;
PNM does not support the spatial resolution tags.
You can supply a jpegquality parameter (0-100) when writing a JPEG
file, which defaults to 75%. Only 1 and 3 channel images
can be written, including 1 and 3 channel paletted images.
$img->write(file=>'foo.jpg', jpegquality=>90) or die $img->errstr;
Imager will read a grayscale JPEG as a 1 channel image and a color JPEG as a 3 channel image.
$img->read(file=>'foo.jpg') or die $img->errstr;
PNM does not support the spatial resolution tags.
When writing one of more GIF images you can use the same Quantization Options as you can when converting an RGB image into a paletted image.
When reading a GIF all of the sub-images are combined using the screen size and image positions into one big image, producing an RGB image. This may change in the future to produce a paletted image where possible.
When you read a single GIF with $img->read() you can supply a
reference to a scalar in the colors parameter, if the image is read
the scalar will be filled with a reference to an anonymous array of
Imager::Color objects, representing the palette of the image. This
will be the first palette found in the image. If you want the
palettes for each of the images in the file, use read_multi() and
use the getcolors() method on each image.
GIF does not support the spatial resolution tags.
Imager will set the following tags in each image when reading, and can use most of them when writing to GIF:
the size of the logical screen. When writing this is used as the minimum. If any image being written would extend beyond this the screen size is extended. ("Logical Screen Width", "Logical Screen Height").
When writing this is used as a minimum, if the combination of the
image size and the image's gif_left and gif_top is beyond this
size then the screen size will be expanded.
gif_eliminate_unused tag to 0.
Where applicable, the ("name") is the name of that field from the GIF89 standard.
The following gif writing options are obsolete, you should set the corresponding tag in the image, either by using the tags functions, or by supplying the tag and value as options.
Each image in the gif file has it's own palette if this is non-zero. All but the first image has a local colour table (the first uses the global colour table.
Use gif_local_map in new code.
The images are written interlaced if this is non-zero.
Use gif_interlace in new code.
A reference to an array containing the delays between images, in 1/100 seconds.
Use gif_delay in new code.
A reference to an array of references to arrays which represent screen positions for each image.
New code should use the gif_left and gif_top tags.
If this is non-zero the Netscape loop extension block is generated, which makes the animation of the images repeat.
This is currently unimplemented due to some limitations in giflib.
Imager can write images to either paletted or RGB TIFF images, depending on the type of the source image. Currently if you write a 16-bit/sample or double/sample image it will be written as an 8-bit/sample image. Only 1 or 3 channel images can be written.
If you are creating images for faxing you can set the class
parameter set to fax. By default the image is written in fine
mode, but this can be overridden by setting the fax_fine parameter
to zero. Since a fax image is bi-level, Imager uses a threshold to
decide if a given pixel is black or white, based on a single channel.
For greyscale images channel 0 is used, for color images channel 1
(green) is used. If you want more control over the conversion you can
use $img->to_paletted() to product a bi-level image. This way you can
use dithering:
my $bilevel = $img->to_paletted(colors=>[ NC(0,0,0), NC(255,255,255) ],
make_colors => 'none',
translate => 'errdiff',
errdiff => 'stucki');
Imager should be able to read any TIFF image you supply. Paletted TIFF images are read as paletted Imager images, since paletted TIFF images have 16-bits/sample (48-bits/color) this means the bottom 8-bits are lost, but this shouldn't be a big deal. Currently all direct color images are read at 8-bits/sample.
TIFF supports the spatial resolution tags. See the
tiff_resolutionunit tag for some extra options.
The following tags are set in a TIFF image when read, and can be set to control output:
The value of the ResolutionUnit tag. This is ignored on writing if the i_aspect_only tag is non-zero.
The i_xres and i_yres tags are expressed in pixels per inch no
matter tha value of this tag, they will be converted to/from the value
stored in the TIFF file.
Imager can write 24-bit RGB, and 8, 4 and 1-bit per pixel paletted Windows BMP files. Currently you cannot write compressed BMP files with Imager.
Imager can read 24-bit RGB, and 8, 4 and 1-bit perl pixel paletted Windows BMP files. There is some support for reading 16-bit per pixel images, but I haven't found any for testing.
BMP has no support for multi-image files.
BMP files support the spatial resolution tags, but since BMP has no
support for storing only an aspect ratio, if i_aspect_only is set
when you write the i_xres and i_yres values are scaled so the
smaller it 72 DPI.
The following tags are set when you read an image from a BMP file:
The type of compression, if any. This can be any of the following values:
When storing targa images rle compression can be activated with the 'compress' parameter, the 'idstring' parameter can be used to set the targa comment field and the 'wierdpack' option can be used to use the 15 and 16 bit targa formats for rgb and rgba data. The 15 bit format has 5 of each red, green and blue. The 16 bit format in addition allows 1 bit of alpha. The most significant bits are used for each channel.
Tags:
When reading raw images you need to supply the width and height of the image in the xsize and ysize options:
$img->read(file=>'foo.raw', xsize=>100, ysize=>100)
or die "Cannot read raw image\n";
If your input file has more channels than you want, or (as is common), junk in the fourth channel, you can use the datachannels and storechannels options to control the number of channels in your input file and the resulting channels in your image. For example, if your input image uses 32-bits per pixel with red, green, blue and junk values for each pixel you could do:
$img->read(file=>'foo.raw', xsize=>100, ysize=>100, datachannels=>4,
storechannels=>3)
or die "Cannot read raw image\n";
Normally the raw image is expected to have the value for channel 1 immediately following channel 0 and channel 2 immediately following channel 1 for each pixel. If your input image has all the channel 0 values for the first line of the image, followed by all the channel 1 values for the first line and so on, you can use the interleave option:
$img->read(file=>'foo.raw', xsize=100, ysize=>100, interleave=>1)
or die "Cannot read raw image\n";
Once you have an image the basic mechanism is:
fd or fh parameter. You will need to
provide the type parameter since
# write an image from a CGI script
# using CGI.pm
use CGI qw(:standard);
$| = 1;
binmode STDOUT;
print header(-type=>'image/gif');
$img->write(type=>'gif', fd=>fileno(STDOUT))
or die $img->errstr;
If you want to send a content length you can send the output to a scalar to get the length:
my $data;
$img->write(type=>'gif', data=>\$data)
or die $img->errstr;
binmode STDOUT;
print header(-type=>'image/gif', -content_length=>length($data));
print $data;
The basic idea is simple, just use write_multi():
my @imgs = ...;
Imager->write_multi({ file=>$filename, type=>'gif' }, @imgs);
If your images are RGB images the default quantization mechanism will produce a very good result, but can take a long time to execute. You could either use the standard webmap:
Imager->write_multi({ file=>$filename,
type=>'gif',
make_colors=>'webmap' },
@imgs);
or use a median cut algorithm to built a fairly optimal color map:
Imager->write_multi({ file=>$filename,
type=>'gif',
make_colors=>'mediancut' },
@imgs);
By default all of the images will use the same global colormap, which will produce a smaller image. If your images have significant color differences, you may want to generate a new palette for each image:
Imager->write_multi({ file=>$filename,
type=>'gif',
make_colors=>'mediancut',
gif_local_map => 1 },
@imgs);
which will set the gif_local_map tag in each image to 1.
Alternatively, if you know only some images have different colors, you
can set the tag just for those images:
$imgs[2]->settag(name=>'gif_local_map', value=>1); $imgs[4]->settag(name=>'gif_local_map', value=>1);
and call write_multi() without a gif_local_map parameter, or supply
an arrayref of values for the tag:
Imager->write_multi({ file=>$filename,
type=>'gif',
make_colors=>'mediancut',
gif_local_map => [ 0, 0, 1, 0, 1 ] },
@imgs);
Other useful parameters include gif_delay to control the delay
between frames and transp to control transparency.
This is pretty simple:
# print the author of a TIFF, if any
my $img = Imager->new;
$img->read(file=>$filename, type='tiff') or die $img->errstr;
my $author = $img->tags(name=>'tiff_author');
if (defined $author) {
print "Author: $author\n";
}
When saving Gif images the program does NOT try to shave of extra colors if it is possible. If you specify 128 colors and there are only 2 colors used - it will have a 128 colortable anyway.
Imager(3)