- writing a 2 or 4 channel image to a JPEG will now write that image as

[imager.git] / lib / Imager / Files.pod

=head1 NAME

Imager::Files - working with image files

=head1 SYNOPSIS

  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)

  my @read_types = Imager->read_types;
  my @write_types = Imager->write_types;

=head1 DESCRIPTION

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.  For new code you might find the L</read_types> or
L</write_types> methods useful.

=over 

=item read

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

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

In most cases Imager can auto-detect the file type, so you can just
supply the filename:

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

The read() method accepts the C<allow_partial> parameter.  If this is
non-zero then read() can return true on an incomplete image and set
the C<i_incomplete> tag.

=item write

and the C<write()> method to write an image:

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

=item read_multi

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

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

As with the read() method, Imager will normally detect the C<type>
automatically.

=item write_multi

and if you want to write multiple images to a single file use the
C<write_multi()> method:

  Imager->write_multi({ file=> $filename, type=>$type }, @images)
    or die "Cannot write $filename: ", Imager->errstr;

=item read_types

This is a class method that returns a list of the image file types
that Imager can read.

  my @types = Imager->read_types;

These types are the possible values for the C<type> parameter, not
necessarily the extension of the files you're reading.

It is possible for extra file read handlers to be loaded when
attempting to read a file, which may modify the list of available read
types.

=item write_types

This is a class method that returns a list of the image file types
that Imager can write.

  my @types = Imager->write_types;

Note that these are the possible values for the C<type> parameter, not
necessarily the extension of the files you're writing.

It is possible for extra file write handlers to be loaded when
attempting to write a file, which may modify the list of available
write types.

=back

When writing, if the I<filename> includes an extension that Imager
recognizes, then you don't need the I<type>, but you may want to
provide one anyway.  See L</Guessing types> for information on
controlling this recognition.

The C<type> 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
  sgi   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 L<Imager::ImageTypes/Tags> for specifics.

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

=head2 Input and output

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

=over

=item *

file - The C<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 C<type>.

  # write in tiff format
  $image->write(file => "example.tif")
    or die $image->errstr;

  $image->write(file => 'foo.tmp', type => 'tiff')
    or die $image->errstr;

  my $image = Imager->new;
  $image->read(file => 'example.tif')
    or die $image->errstr;

=item 

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

  $image->write(fh => \*STDOUT, type => 'gif')
    or die $image->errstr;

  # for example, a file uploaded via CGI.pm
  $image->read(fd => $cgi->param('file')) 
    or die $image->errstr;

=item 

fd - C<fd> is a file descriptor.  You can get this by calling the
C<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.

  $image->write(fd => file(STDOUT), type => 'gif')
    or die $image->errstr;

=item 

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

  my $data;
  $image->write(data => \$data, type => 'tiff')
    or die $image->errstr;

  my $data = $row->{someblob}; # eg. from a database
  my @images = Imager->read_multi(data => $data)
    or die Imager->errstr;

=item *

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 C<callback> or C<readcb>
to supply the read callback, and when writing C<callback> or
C<writecb> to supply the write callback.

When writing you can also supply the C<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 I<POSITION>, and a I<WHENCE>,
defined in the same way as perl's seek function.

You can also supply a C<closecb> which is called with no parameters
when there is no more data to be written.  This could be used to flush
buffered data.

  # contrived
  my $data;
  sub mywrite {
    $data .= unpack("H*", shift);
    1;
  }
  Imager->write_multi({ callback => \&mywrite, type => 'gif'}, @images)
    or die Imager->errstr;

Note that for reading you'll almost always need to provide a
C<seekcb>.

=back

=head2 Guessing types

When writing to a file, if you don't supply a C<type> parameter Imager
will attempt to guess it from the filename.  This is done by calling
the code reference stored in C<$Imager::FORMATGUESS>.  This is only
done when write() or write_multi() is called with a C<file> parameter.

The default function value of C<$Imager::FORMATGUESS> is
C<\&Imager::def_guess_type>.

=over

=item def_guess_type

This is the default function Imager uses to derive a file type from a
file name.  This is a function, not a method.

Accepts a single parameter, the filename and returns the type or
undef.

=back

You can replace function with your own implementation if you have some
specialized need.  The function takes a single parameter, the name of
the file, and should return either a file type or under.

  # I'm writing jpegs to weird filenames
  local $Imager::FORMATGUESS = sub { 'jpeg' };

When reading a file Imager examines beginning of the file for
identifying information.  The current implementation attempts to
detect the following image types beyond those supported by Imager:

=over

xpm, mng, jng, SGI RGB, ilbm, pcx, fits, psd (Photoshop), eps, Utah
RLE

=back

=head2 Limiting the sizes of images you read

=over

=item 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:

=over

=item *

width - limit the width in pixels of the image

=item *

height - limit the height in pixels of the image

=item *

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.

=back

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

=item 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();

=back

=head1 TYPE SPECIFIC INFORMATION

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

When you call C<write()> or C<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 C<Imager::init()> function with
the C<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.

=head2 PNM (Portable aNy Map)

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.

The following tags are set when reading a PNM file:

=over

=item *

X<pnm_maxval>pnm_maxval - the maxvals number from the PGM/PPM header.
Always set to 2 for a PBM file.

=item *

X<pnm_type>pnm_type - the type number from the PNM header, 1 for ASCII
PBM files, 2 for ASCII PGM files, 3 for ASCII PPM files, 4 for binary
PBM files, 5 for binary PGM files, 6 for binary PPM files.

=back

The following tag is checked when writing an image with more than
8-bits/sample:

=over

=item *

X<pnm_write_wide_data>pnm_write_wide_data - if this is non-zero then
write() can write PGM/PPM files with 16-bits/sample.  Some
applications, for example GIMP 2.2, and tools can only read
8-bit/sample binary PNM files, so Imager will only write a 16-bit
image when this tag is non-zero.

=back

=head2 JPEG

You can supply a C<jpegquality> parameter (0-100) when writing a JPEG
file, which defaults to 75%.  If you write an image with an alpha
channel to a jpeg file then it will be composited against the
background set by the C<i_background> parameter (or tag).

  $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:

=over

=item jpeg_density_unit

The value of the density unit field in the JFIF header.  This is
ignored on writing if the C<i_aspect_only> tag is non-zero.

The C<i_xres> and C<i_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.

=item jpeg_density_unit_name

This is set when reading a JPEG file to the name of the unit given by
C<jpeg_density_unit>.  Possible results include C<inch>,
C<centimeter>, C<none> (the C<i_aspect_only> tag is also set reading
these files).  If the value of jpeg_density_unit is unknown then this
tag isn't set.

=item jpeg_comment

Text comment.

=back

JPEG supports the spatial resolution tags C<i_xres>, C<i_yres> and
C<i_aspect_only>.

If an APP1 block containing EXIF information is found, then any of the
following tags can be set:

=over

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

=back

The following derived tags can also be set:

=over

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

=back

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 C<exf_metering_mode> is C<5> then
C<exif_metering_mode_name> is set to C<Pattern>.

eg.

  my $image = Imager->new;
  $image->read(file => 'exiftest.jpg')
    or die "Cannot load image: ", $image->errstr;
  print $image->tags(name => "exif_image_description"), "\n";
  print $image->tags(name => "exif_exposure_mode"), "\n";
  print $image->tags(name => "exif_exposure_mode_name"), "\n";

  # for the exiftest.jpg in the Imager distribution the output would be:
  Imager Development Notes
  0
  Auto exposure

=over

=item parseiptc

Historically, Imager saves IPTC data when reading a JPEG image, the
parseiptc() method returns a list of key/value pairs resulting from a
simple decoding of that data.

Any future IPTC data decoding is likely to go into tags.

=back

=head2 GIF (Graphics Interchange Format)

When writing one of more GIF images you can use the same
L<Quantization Options|Imager::ImageTypes> 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 C<$img-E<gt>read()> you can supply a
reference to a scalar in the C<colors> parameter, if the image is read
the scalar will be filled with a reference to an anonymous array of
L<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 C<read_multi()> and
use the C<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:

=over

=item *

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

=item *

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

=item *

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

=item *

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 then the screen size is extended.
("Logical Screen Width", "Logical Screen Height").

=item *

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.

=item *

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 C<gif_eliminate_unused> tag to 0.

=item *

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

=item *

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 L<Quantization
options>) for this value to be used.

=item *

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

=item *

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

=item *

gif_disposal - how the next frame is displayed ("Disposal Method")

=item *

gif_loop - the number of loops from the Netscape Loop extension.  This
may be zero to loop forever.

=item *

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

=item *

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.

=item *

gif_colormap_size - the original size of the color map for the image.
The color map of the image may have been expanded to include out of
range color indexes.

=back

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.

=over

=item *

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

=item *

interlace - The images are written interlaced if this is non-zero.

Use C<gif_interlace> in new code.

=item *

gif_delays - A reference to an array containing the delays between
images, in 1/100 seconds.

Use C<gif_delay> in new code.

=item *

gif_positions - A reference to an array of references to arrays which
represent screen positions for each image.

New code should use the C<gif_left> and C<gif_top> tags.

=item *

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.

=back

You can supply a C<page> parameter to the C<read()> 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 C<< page => 0 >>.

You can return to the previous behaviour by calling read with the
C<gif_consolidate> parameter set to a true value:

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

=head2 TIFF (Tagged Image File Format)

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 I<class>
parameter set to C<fax>.  By default the image is written in fine
mode, but this can be overridden by setting the I<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(make_colors => 'mono',
                                  translate => 'errdiff',
                                  errdiff => 'stucki');

=over

=item class

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

=item fax_fine

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

=back

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

As of Imager 0.62 Imager reads:

=over

=item *

16-bit grey, RGB, or CMYK image, including a possible alpha channel as
a 16-bit/sample image.

=item *

32-bit grey, RGB image, including a possible alpha channel as a
double/sample image.

=item *

bi-level images as paletted images containing only black and white,
which other formats will also write as bi-level.

=item *

tiled paletted images are now handled correctly

=back

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

=over

=item tiff_compression

When reading an image this is set to the numeric value of the TIFF
compression tag.

On writing you can set this to either a numeric compression tag value,
or one of the following values:

  Ident     Number  Description
  none         1    No compression
  packbits   32773  Macintosh RLE
  ccittrle     2    CCITT RLE
  fax3         3    CCITT Group 3 fax encoding (T.4)
  t4           3    As above
  fax4         4    CCITT Group 4 fax encoding (T.6)
  t6           4    As above
  lzw          5    LZW
  jpeg         7    JPEG
  zip          8    Deflate (GZIP) Non-standard
  deflate      8    As above.
  oldzip     32946  Deflate with an older code.
  ccittrlew  32771  Word aligned CCITT RLE

In general a compression setting will be ignored where it doesn't make
sense, eg. C<jpeg> will be ignored for compression if the image is
being written as bilevel.

Imager attempts to check that your build of libtiff supports the given
compression, and will fallback to C<packbits> if it isn't enabled.
eg. older distributions didn't include LZW compression, and JPEG
compression is only available if libtiff is configured with libjpeg's
location.

  $im->write(file => 'foo.tif', tiff_compression => 'lzw')
    or die $im->errstr;

=item tiff_jpegquality

If I<tiff_compression> if C<jpeg> then this can be a number from 1 to
100 giving the JPEG compression quality.  High values are better
quality and larger files.

=item tiff_resolutionunit

The value of the ResolutionUnit tag.  This is ignored on writing if
the i_aspect_only tag is non-zero.

The C<i_xres> and C<i_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.

=item tiff_resolutionunit_name

This is set when reading a TIFF file to the name of the unit given by
C<tiff_resolutionunit>.  Possible results include C<inch>,
C<centimeter>, C<none> (the C<i_aspect_only> tag is also set reading
these files) or C<unknown>.

=item 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.

=item 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.

=item tiff_documentname

=item tiff_imagedescription

=item tiff_make

=item tiff_model

=item tiff_pagename

=item tiff_software

=item tiff_datetime

=item tiff_artist

=item 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.

=back

You can supply a C<page> parameter to the C<read()> 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";

Note: Imager uses the TIFF*RGBA* family of libtiff functions,
unfortunately these don't support alpha channels on CMYK images.  This
will result in a full coverage alpha channel on CMYK images with an
alpha channel, until this is implemented in libtiff (or Imager's TIFF
implementation changes.)

If you read an image with multiple alpha channels, then only the first
alpha channel will be read.

Currently Imager's TIFF support reads all direct color images as 8-bit
RGB images, this may change in the future to reading 16-bit/sample
images.

Currently tags that control the output color type and compression are
ignored when writing, this may change in the future.  If you have
processes that rely upon Imager always producing packbits compressed
RGB images, you should strip any tags before writing.

=head2 BMP (BitMaP)

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 C<i_aspect_only> is set
when you write the C<i_xres> and C<i_yres> values are scaled so the
smaller is 72 DPI.

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

=over

=item bmp_compression

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

=over

=item BI_RGB (0)

Uncompressed.

=item BI_RLE8 (1)

8-bits/pixel paletted value RLE compression.

=item BI_RLE4 (2)

4-bits/pixel paletted value RLE compression.

=item BI_BITFIELDS (3)

Packed RGB values.

=back

=item bmp_compression_name

The bmp_compression value as a BI_* string

=item bmp_important_colors

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

=item bmp_used_colors

Number of color used from the BMP header

=item bmp_filesize

The file size from the BMP header

=item bmp_bit_count

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

=back

=head2 TGA (TarGA)

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:

=over

=item tga_idstring

=item tga_bitspp

=item compressed

=back

=head2 RAW

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

=head2 PNG

There are no PNG specific tags.

=head2 ICO (Microsoft Windows Icon) and CUR (Microsoft Windows Cursor)

Icon and Cursor files are very similar, the only differences being a
number in the header and the storage of the cursor hotspot.  I've
treated them separately so that you're not messing with tags to
distinguish between them.

The following tags are set when reading an icon image and are used
when writing it:

=over

=item ico_mask

This is the AND mask of the icon.  When used as an icon in Windows 1
bits in the mask correspond to pixels that are modified by the source
image rather than simply replaced by the source image.

Rather than requiring a binary bitmap this is accepted in a specific format:

=over

=item *

first line consisting of the 0 placeholder, the 1 placeholder and a
newline.

=item *

following lines which contain 0 and 1 placeholders for each scanline
of the image, starting from the top of the image.

=back

When reading an image, '.' is used as the 0 placeholder and '*' as the
1 placeholder.  An example:

  .*
  ..........................******
  ..........................******
  ..........................******
  ..........................******
  ...........................*****
  ............................****
  ............................****
  .............................***
  .............................***
  .............................***
  .............................***
  ..............................**
  ..............................**
  ...............................*
  ...............................*
  ................................
  ................................
  ................................
  ................................
  ................................
  ................................
  *...............................
  **..............................
  **..............................
  ***.............................
  ***.............................
  ****............................
  ****............................
  *****...........................
  *****...........................
  *****...........................
  *****...........................

=back

The following tags are set when reading an icon:

=over

=item ico_bits

The number of bits per pixel used to store the image.

=back

For cursor files the following tags are set and read when reading and
writing:

=over

=item cur_mask

This is the same as the ico_mask above.

=item cur_hotspotx

=item cur_hotspoty

The "hot" spot of the cursor image.  This is the spot on the cursor
that you click with.  If you set these to out of range values they are
clipped to the size of the image when written to the file.

=back

The following parameters can be supplied to read() or read_multi() to
control reading of ICO/CUR files:

=over

=item *

ico_masked - if true, the default, then the icon/cursors mask is
applied as an alpha channel to the image.  This may result in a
paletted image being returned as a direct color image.  Default: 1

  # retrieve the image as stored, without using the mask as an alpha
  # channel
  $img->read(file => 'foo.ico', ico_masked => 0)
    or die $img->errstr;

This was introduced in Imager 0.60.  Previously reading ICO images
acted as if C<<ico_masked => 0>>.

=back

C<cur_bits> is set when reading a cursor.

Examples:

  my $img = Imager->new(xsize => 32, ysize => 32, channels => 4);
  $im->box(color => 'FF0000');
  $im->write(file => 'box.ico');

  $im->settag(name => 'cur_hotspotx', value => 16);
  $im->settag(name => 'cur_hotspoty', value => 16);
  $im->write(file => 'box.cur');

=head2 SGI (RGB, BW)

SGI images, often called by the extensions, RGB or BW, can be stored
either uncompressed or compressed using an RLE compression.

By default, when saving to an extension of C<rgb>, C<bw>, C<sgi>,
C<rgba> the file will be saved in SGI format.  The file extension is
otherwise ignored, so saving a 3-channel image to a C<.bw> file will
result in a 3-channel image on disk.

The following tags are set when reading a SGI image:

=over

=item *

i_comment - the IMAGENAME field from the image.  Also written to the
file when writing.

=item *

sgi_pixmin, sgi_pixmax - the PIXMIN and PIXMAX fields from the image.
On reading image data is expanded from this range to the full range of
samples in the image.

=item *

sgi_bpc - the number of bytes per sample for the image.  Ignored when
writing.

=item *

sgi_rle - whether or not the image is compressed.  If this is non-zero
when writing the image will be compressed.

=back

=head1 ADDING NEW FORMATS

To support a new format for reading, call the register_reader() class
method:

=over

=item register_reader

Registers single or multiple image read functions.

Parameters:

=over

=item *

type - the identifier of the file format, if Imager's
i_test_format_probe() can identify the format then this value should
match i_test_format_probe()'s result.

This parameter is required.

=item *

single - a code ref to read a single image from a file.  This is
supplied:

=over

=item *

the object that read() was called on,

=item *

an Imager::IO object that should be used to read the file, and

=item *

all the parameters supplied to the read() method.

=back

The single parameter is required.

=item *

multiple - a code ref which is called to read multiple images from a
file. This is supplied:

=over

=item *

an Imager::IO object that should be used to read the file, and

=item *

all the parameters supplied to the read_multi() method.

=back

=back

Example:

  # from Imager::File::ICO
  Imager->register_reader
    (
     type=>'ico',
     single => 
     sub { 
       my ($im, $io, %hsh) = @_;
       $im->{IMG} = i_readico_single($io, $hsh{page} || 0);

       unless ($im->{IMG}) {
         $im->_set_error(Imager->_error_as_msg);
         return;
       }
       return $im;
     },
     multiple =>
     sub {
       my ($io, %hsh) = @_;
     
       my @imgs = i_readico_multi($io);
       unless (@imgs) {
         Imager->_set_error(Imager->_error_as_msg);
         return;
       }
       return map { 
         bless { IMG => $_, DEBUG => $Imager::DEBUG, ERRSTR => undef }, 'Imager'
       } @imgs;
     },
    );

=item register_writer

Registers single or multiple image write functions.

Parameters:

=over

=item *

type - the identifier of the file format.  This is typically the
extension in lowercase.

This parameter is required.

=item *

single - a code ref to write a single image to a file.  This is
supplied:

=over

=item *

the object that write() was called on,

=item *

an Imager::IO object that should be used to write the file, and

=item *

all the parameters supplied to the write() method.

=back

The single parameter is required.

=item *

multiple - a code ref which is called to write multiple images to a
file. This is supplied:

=over

=item *

the class name write_multi() was called on, this is typically
C<Imager>.

=item *

an Imager::IO object that should be used to write the file, and

=item *

all the parameters supplied to the read_multi() method.

=back

=back

=back

If you name the reader module C<Imager::File::>I<your-format-name>
where I<your-format-name> is a fully upper case version of the type
value you would pass to read(), read_multi(), write() or write_multi()
then Imager will attempt to load that module if it has no other way to
read or write that format.

For example, if you create a module Imager::File::GIF and the user has
built Imager without it's normal GIF support then an attempt to read a
GIF image will attempt to load Imager::File::GIF.

If your module can only handle reading then you can name your module
C<Imager::File::>I<your-format-name>C<Reader> and Imager will attempt
to autoload it.

If your module can only handle writing then you can name your module 
C<Imager::File::>I<your-format-name>C<Writer> and Imager will attempt
to autoload it.

=head1 EXAMPLES

=head2 Producing an image from a CGI script

Once you have an image the basic mechanism is:

=over

=item 1.

set STDOUT to autoflush

=item 2.

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

=item 3.

put STDOUT into binmode

=item 4.

call write() with the C<fd> or C<fh> parameter.  You will need to
provide the C<type> parameter since Imager can't use the extension to
guess the file format you want.

=back

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

=head2 Writing an animated GIF

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 C<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 C<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 C<gif_delay> to control the delay
between frames and C<transp> to control transparency.

=head2 Reading tags after reading an image

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

=head1 BUGS

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.

=head1 SEE ALSO

Imager(3)

=cut