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;

  Imager->set_file_limits(width=>$max_width, height=>$max_height)

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.

read

Reading writing to and from files is simple, use the CWread() method to read an image:

  my $img = Imager->new;
  $img->read(file=>$filename, type=>$type)
    or die "Cannot read $filename: ", $img->errstr;

write

and the CWwrite() method to write an image:

  $img->write(file=>$filename, type=>$type)
    or die "Cannot write $filename: ", $img->errstr;

read_multi

If you're reading from a format that supports multiple images per file, use the CWread_multi() method:

  my @imgs = Imager->read_multi(file=>$filename, type=>$type)
    or die "Cannot read $filename: ", Imager->errstr;

write_multi

and if you want to write multiple images to a single file use the CWwrite_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.

The CWtype parameter is a lowercase representation of the file type, and can be any of the following:

  bmp   Windows BitMaP (BMP)
  gif   Graphics Interchange Format (GIF)
  jpeg  JPEG/JFIF
  png   Portable Network Graphics (PNG)
  pnm   Portable aNyMap (PNM)
  raw   Raw
  rgb   SGI .rgb files
  tga   TARGA
  tiff  Tagged Image File Format (TIFF)

When you read an image, Imager may set some tags, possibly including information about the spatial resolution, textual information, and animation information. See Tags in Imager::ImageTypes for specifics.

The open() method is a historical alias for the read() method.

When reading or writing you can specify one of a variety of sources or targets:

file

The CWfile 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 CWtype.

fh

CWfh is a file handle, typically either returned from CW<IO::File-new()>>, or a glob from an CWopen call. You should call CWbinmode 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

CWfd is a file descriptor. You can get this by calling the CWfileno() 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

When reading data, CWdata is a scalar containing the image file data, when writing, CWdata 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.

callback

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 CWcallback or CWreadcb to supply the read callback, and when writing CWcallback or CWwritecb to supply the write callback. When writing you can also supply the CWmaxbuffer 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 CWclosecb 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 CW$Imager::FORMATGUESS to guess the file type when you don't supply a CWtype. The code reference is called with a single parameter, the filename of the file. The code reference is only called if a CWfile 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' };

set_file_limits

In some cases you will be receiving images from an untested source, such as submissions via CGI. To prevent such images from consuming large amounts of memory, you can set limits on the dimensions of images you read from files:

*

width - limit the width in pixels of the image

*

height - limit the height in pixels of the image

*

bytes - limits the amount of storage used by the image. This depends on the width, height, channels and sample size of the image. For paletted images this is calculated as if the image was expanded to a direct color image. To set the limits, call the class method set_file_limits:

  Imager->set_file_limits(width=>$max_width, height=>$max_height);

You can pass any or all of the limits above, any limits you do not pass are left as they were. Any limit of zero is treated as unlimited. By default, all of the limits are zero, or unlimited. You can reset all of the limited to their defaults by passing in the reset parameter as a true value:

  # no limits
  Imager->set_file_limits(reset=>1);

This can be used with the other limits to reset all but the limit you pass:

  # only width is limited
  Imager->set_file_limits(reset=>1, width=>100);

  # only bytes is limited
  Imager->set_file_limits(reset=>1, bytes=>10_000_000);

get_file_limits

You can get the current limits with the get_file_limits() method:

  my ($max_width, $max_height, $max_bytes) =
     Imager->get_file_limits();

The different image formats can write different image type, and some have different options to control how the images are written.

When you call CWwrite() or CWwrite_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 CWImager::init() function with the CWwarn_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 CWjpegquality 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;

The following tags are set in a JPEG image when read, and can be set to control output:

jpeg_density_unit

The value of the density unit field in the JFIF header. This is ignored on writing if the i_aspect_only tag is non-zero. The CWi_xres and CWi_yres tags are expressed in pixels per inch no matter the value of this tag, they will be converted to/from the value stored in the JPEG file.

jpeg_density_unit_name

This is set when reading a JPEG file to the name of the unit given by CWjpeg_density_unit. Possible results include CWinch, CWcentimeter, CWnone (the CWi_aspect_only tag is also set reading these files). If the value of jpeg_density_unit is unknown then this tag isn't set.

jpeg_comment

Text comment.

JPEG supports the spatial resolution tags CWi_xres, CWi_yres and CWi_aspect_only.

If an APP1 block containing EXIF information is found, then any of the following tags can be set: exif_aperture exif_artist exif_brightness exif_color_space exif_contrast exif_copyright exif_custom_rendered exif_date_time exif_date_time_digitized exif_date_time_original exif_digital_zoom_ratio exif_exposure_bias exif_exposure_index exif_exposure_mode exif_exposure_program exif_exposure_time exif_f_number exif_flash exif_flash_energy exif_flashpix_version exif_focal_length exif_focal_length_in_35mm_film exif_focal_plane_resolution_unit exif_focal_plane_x_resolution exif_focal_plane_y_resolution exif_gain_control exif_image_description exif_image_unique_id exif_iso_speed_rating exif_make exif_max_aperture exif_metering_mode exif_model exif_orientation exif_related_sound_file exif_resolution_unit exif_saturation exif_scene_capture_type exif_sensing_method exif_sharpness exif_shutter_speed exif_software exif_spectral_sensitivity exif_sub_sec_time exif_sub_sec_time_digitized exif_sub_sec_time_original exif_subject_distance exif_subject_distance_range exif_subject_location exif_tag_light_source exif_user_comment exif_version exif_white_balance exif_x_resolution exif_y_resolution

The following derived tags can also be set: exif_color_space_name exif_contrast_name exif_custom_rendered_name exif_exposure_mode_name exif_exposure_program_name exif_flash_name exif_focal_plane_resolution_unit_name exif_gain_control_name exif_light_source_name exif_metering_mode_name exif_resolution_unit_name exif_saturation_name exif_scene_capture_type_name exif_sensing_method_name exif_sharpness_name exif_subject_distance_range_name exif_white_balance_name

The derived tags are for enumerated fields, when the value for the base field is valid then the text that appears in the EXIF specification for that value appears in the derived field. So for example if CWexf_metering_mode is CW5 then CWexif_metering_mode_name is set to CWPattern.

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 CW$img->read() you can supply a reference to a scalar in the CWcolors 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 CWread_multi() and use the CWgetcolors() 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:

gif_left

the offset of the image from the left of the screen (Image Left Position)

gif_top

the offset of the image from the top of the screen (Image Top Position)

gif_interlace

non-zero if the image was interlaced (Interlace Flag)

gif_screen_width

gif_screen_height

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 CWgif_left and CWgif_top is beyond this size then the screen size will be expanded.

gif_local_map

Non-zero if this image had a local color map. If set for an image when writing the image is quantized separately from the other images in the file.

gif_background

The index in the global colormap of the logical screen's background color. This is only set if the current image uses the global colormap. You can set this on write too, but for it to choose the color you want, you will need to supply only paletted images and set the CWgif_eliminate_unused tag to 0.

gif_trans_index

The index of the color in the colormap used for transparency. If the image has a transparency then it is returned as a 4 channel image with the alpha set to zero in this palette entry. This value is not used when writing. (Transparent Color Index)

gif_trans_color

A reference to an Imager::Color object, which is the colour to use for the palette entry used to represent transparency in the palette. You need to set the transp option (see Quantization options) for this value to be used.

gif_delay

The delay until the next frame is displayed, in 1/100 of a second. (Delay Time).

gif_user_input

whether or not a user input is expected before continuing (view dependent) (User Input Flag).

gif_disposal

how the next frame is displayed (Disposal Method)

gif_loop

the number of loops from the Netscape Loop extension. This may be zero.

gif_comment

the first block of the first gif comment before each image.

gif_eliminate_unused

If this is true, when you write a paletted image any unused colors will be eliminated from its palette. This is set by default.

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.

gif_each_palette

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 CWgif_local_map in new code.

interlace

The images are written interlaced if this is non-zero. Use CWgif_interlace in new code.

gif_delays

A reference to an array containing the delays between images, in 1/100 seconds. Use CWgif_delay in new code.

gif_positions

A reference to an array of references to arrays which represent screen positions for each image. New code should use the CWgif_left and CWgif_top tags.

gif_loop_count

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.

You can supply a CWpage parameter to the CWread() method to read some page other than the first. The page is 0 based:

  # read the second image in the file
  $image->read(file=>"example.gif", page=>1)
    or die "Cannot read second page: ",$image->errstr,"\n";

Before release 0.46, Imager would read multi-image GIF image files into a single image, overlaying each of the images onto the virtual GIF screen.

As of 0.46 the default is to read the first image from the file, as if called with CWpage => 0.

You can return to the previous behaviour by calling read with the CWgif_consolidate parameter set to a true value:

  $img->read(file=>$some_gif_file, gif_consolidate=>1);

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 CWfax. 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 CW$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');

class

If set to 'fax' the image will be written as a bi-level fax image.

fax_fine

By default when class is set to 'fax' the image is written in fine mode, you can select normal mode by setting fax_fine to 0.

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 CWtiff_resolutionunit tag for some extra options.

The following tags are set in a TIFF image when read, and can be set to control output:

tiff_resolutionunit

The value of the ResolutionUnit tag. This is ignored on writing if the i_aspect_only tag is non-zero. The CWi_xres and CWi_yres tags are expressed in pixels per inch no matter the value of this tag, they will be converted to/from the value stored in the TIFF file.

tiff_resolutionunit_name

This is set when reading a TIFF file to the name of the unit given by CWtiff_resolutionunit. Possible results include CWinch, CWcentimeter, CWnone (the CWi_aspect_only tag is also set reading these files) or CWunknown.

tiff_bitspersample

Bits per sample from the image. This value is not used when writing an image, it is only set on a read image.

tiff_photometric

Value of the PhotometricInterpretation tag from the image. This value is not used when writing an image, it is only set on a read image.

tiff_documentname

tiff_imagedescription

tiff_make

tiff_model

tiff_pagename

tiff_software

tiff_datetime

tiff_artist

tiff_hostcomputer

Various strings describing the image. tiff_datetime must be formatted as YYYY:MM:DD HH:MM:SS. These correspond directly to the mixed case names in the TIFF specification. These are set in images read from a TIFF and saved when writing a TIFF image. You can supply a CWpage parameter to the CWread() method to read some page other than the first. The page is 0 based:

  # read the second image in the file
  $image->read(file=>"example.tif", page=>1)
    or die "Cannot read second page: ",$image->errstr,"\n";

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 CWi_aspect_only is set when you write the CWi_xres and CWi_yres values are scaled so the smaller is 72 DPI.

The following tags are set when you read an image from a BMP file:

bmp_compression

The type of compression, if any. This can be any of the following values:

BI_RGB (0)

Uncompressed.

BI_RLE8 (1)

8-bits/pixel paletted value RLE compression.

BI_RLE4 (2)

4-bits/pixel paletted value RLE compression.

BI_BITFIELDS (3)

Packed RGB values.

bmp_compression_name

The bmp_compression value as a BI_* string

bmp_important_colors

The number of important colors as defined by the writer of the image.

bmp_used_colors

Number of color used from the BMP header

bmp_filesize

The file size from the BMP header

bmp_bit_count

Number of bits stored per pixel. (24, 8, 4 or 1)

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:

tga_idstring

tga_bitspp

compressed

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";

There are no PNG specific tags.

Once you have an image the basic mechanism is:

1.

set STDOUT to autoflush

2.

output a content-type header, and optionally a content-length header

3.

put STDOUT into binmode

4.

call write() with the CWfd or CWfh parameter. You will need to provide the CWtype parameter since Imager can't use the extension to guess the file format you want.

  # 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 CWgif_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 CWgif_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 CWgif_delay to control the delay between frames and CWtransp 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)