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

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

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;

and the C<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 C<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
C<write_multi()> method:

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

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.

When you read an image, Imager may set some tags, possibly including
information about the spatial resolution, textual information, and
animation information.  See L</Tags> for specifics.

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

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

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

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

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

=back

=head2 Guessing types

Imager uses the code reference in $Imager::FORMATGUESS to guess the
file type when you don't supply a C<type>.  The code reference is
called with a single parameter, the filename of the file.  The code
reference is only called if a C<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' };

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

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

=head2 JPEG

You can supply a C<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.

=head2 GIF (Graphics Interchange Format)

You can supply many different options when writing to a GIF file, and
you can write a multi-image GIF file, eg. for animation, with the
C<write_multi()> method.

These options can be specified when calling write_multi() or when
writing a single image with the C<gifquant> option set to 'gen'

Note that some viewers will ignore some of these options
(C<gif_user_input> in particular).

=over 4

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

=item interlace

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

=item gif_delays

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

If you want the same delay for every frame you can simply set this to
the delay in 1/100 seconds.

=item gif_user_input

A reference to an array contains user input flags.  If the given flag
is non-zero the image viewer should wait for input before displaying
the next image.

=item gif_disposal

A reference to an array of image disposal methods.  These define what
should be done to the image before displaying the next one.  These are
integers, where 0 means unspecified, 1 means the image should be left
in place, 2 means restore to background colour and 3 means restore to
the previous value.

=item gif_tran_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_positions

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

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

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

=back

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

GIF will set the following tags in each image when reading, but does
not use them when saving 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

=item gif_screen_height

the size of the logical screen ("Logical Screen Width", 
"Logical Screen Height")

=item gif_local_map

Non-zero if this image had a local color map.

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

=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. ("Transparent Color Index")

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

=item gif_comment

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

=back

Where applicable, the ("name") is the name of that field from the GIF89 
standard.

=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(colors=>[ NC(0,0,0), NC(255,255,255) ],
                                  make_colors => 'none',
                                  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.

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

=over

=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 tha value of this tag, they will be converted to/from the value
stored in the TIFF file.

=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

=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 it 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_important_colors

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

=back

=head2 TGA (TarGA)

Tags:

=over

=item tga_idstring

=item tga_bitspp

=item compressed

=back

=head1 EXAMPLES

writing an image from CGI (content type, flush, write to fd)

writing an animated gif

reading tags after reading an image

=cut