=head1 SYNOPSIS
+ use Imager;
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;
+ # type is optional if we can guess the format from the filename
+ $img->write(file => "foo.png")
+ or die "Cannot write: ",$img->errstr;
+
+ $img = Imager->new;
+ $img->read(file=>$filename, type=>$type)
+ or die "Cannot read: ", $img->errstr;
+
+ # type is optional if we can guess the type from the file data
+ # and we normally can guess
+ $img->read(file => $filename)
+ 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;
+
+ # we can write/write_multi to things other than filenames
+ my $data;
+ $img->write(data => \$data, type => $type) or die;
+
+ my $fh = ... ; # eg. IO::File
+ $img->write(fh => $fh, type => $type) or die;
+
+ $img->write(fd => fileno($fh), type => $type) or die;
+
+ # some file types need seek callbacks too
+ $img->write(callback => \&write_callback, type => $type) or die;
+
+ # and similarly for read/read_multi
+ $img->read(data => $data) or die;
+ $img->read(fh => $fh) or die;
+ $img->read(fd => fileno($fh)) or die;
+ $img->read(callback => \&read_callback) or die;
+
+ use Imager 0.68;
+ my $img = Imager->new(file => $filename)
+ or die 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. 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 file name:
+
+ $img->read(file => $filename)
+ or die "Cannot read $filename: ", $img->errstr;
+
+The read() method accepts the C<allow_incomplete> parameter. If this
+is non-zero then read() can return true on an incomplete image and set
+the C<i_incomplete> tag.
+
+From Imager 0.68 you can supply most read() parameters to the new()
+method to read the image file on creation. If the read fails, check
+Imager->errstr() for the cause:
+
+ use Imager 0.68;
+ my $img = Imager->new(file => $filename)
+ or die "Cannot read $filename: ", Imager->errstr;
+
+=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 C<filename> includes an extension that Imager
+recognizes, then you don't need the C<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 *
+
+C<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 *
+
+C<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 *
+
+C<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 *
+
+C<data> - When reading data, C<data> is a scalar containing the image
+file data, or a reference to such a scalar. When writing, C<data> is
+a reference to the scalar to save the image file data to.
+
+ 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;
+
+ # from Imager 0.99
+ my @images = Imager->read_multi(data => \$data)
+ or die Imager->errstr;
+
+=item *
+
+C<callback>, C<readcb>, C<writecb>, C<seekcb>, C<closecb> - Imager
+will make calls back to your supplied coderefs to read, write and seek
+from/to/through the image file. See L</"I/O Callbacks"> below for details.
+
+=item *
+
+C<io> - an L<Imager::IO> object.
+
+=back
+
+X<buffering>X<unbuffered>By default Imager will use buffered I/O when
+reading or writing an image. You can disabled buffering for output by
+supplying a C<< buffered => 0 >> parameter to C<write()> or
+C<write_multi()>.
+
+=head2 I/O Callbacks
+
+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.
+
+Whether reading or writing a C<TIFF> image, C<seekcb> and C<readcb>
+are required.
+
+If a file handler attempts to use C<readcb>, C<writecb> or C<seekcb>
+and you haven't supplied one, the call will fail, failing the image
+read or write, returning an error message indicating that the callback
+is missing:
+
+ # attempting to read a TIFF image without a seekcb
+ open my $fh, "<", $filename or die;
+ my $rcb = sub {
+ my $val;
+ read($fh, $val, $_[0]) or return "";
+ return $val;
+ };
+ my $im = Imager->new(callback => $rcb)
+ or die Imager->errstr
+ # dies with (wrapped here):
+ # Error opening file: (Iolayer): Failed to read directory at offset 0:
+ # (Iolayer): Seek error accessing TIFF directory: seek callback called
+ # but no seekcb supplied
+
+You can also provide a C<closecb> parameter called when writing the
+file is complete. If no C<closecb> is supplied the default will
+succeed silently.
+
+ # contrived
+ my $data;
+ sub mywrite {
+ $data .= unpack("H*", shift);
+ 1;
+ }
+ Imager->write_multi({ callback => \&mywrite, type => 'gif'}, @images)
+ or die Imager->errstr;
+
+=head3 C<readcb>
+
+The read callback is called with 2 parameters:
+
+=over
+
+=item *
+
+C<size> - the minimum amount of data required.
+
+=item *
+
+C<maxsize> - previously this was the maximum amount of data returnable
+- currently it's always the same as C<size>
+
+=back
+
+Your read callback should return the data as a scalar:
+
+=over
+
+=item *
+
+on success, a string containing the bytes read.
+
+=item *
+
+on end of file, an empty string
+
+=item *
+
+on error, C<undef>.
+
+=back
+
+If your return value contains more data than C<size> Imager will
+panic.
+
+Your return value must not contain any characters over C<\xFF> or
+Imager will panic.
+
+=head3 C<writecb>
+
+Your write callback takes exactly one parameter, a scalar containing
+the data to be written.
+
+Return true for success.
+
+=head3 C<seekcb>
+
+The seek callback takes 2 parameters, a I<POSITION>, and a I<WHENCE>,
+defined in the same way as perl's seek function.
+
+Previously you always needed a C<seekcb> callback if you called
+Imager's L</read()> or L</read_multi()> without a C<type> parameter,
+but this is no longer necessary unless the file handler requires
+seeking, such as for TIFF files.
+
+Returns the new position in the file, or -1 on failure.
+
+=head3 C<closecb>
+
+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.
+
+Return true on success.
+
+=head2 Guessing types
+X<FORMATGUESS>
+
+When writing to a file, if you don't supply a C<type> parameter Imager
+will attempt to guess it from the file name. 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,
+or if read() or read_multi() can't determine the type from the file's
+header.
+
+The default function value of C<$Imager::FORMATGUESS> is
+C<\&Imager::def_guess_type>.
+
+=over
+
+=item def_guess_type()
+X<methods, 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 file name 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:
+
+=for stopwords Photoshop
+
+=over
+
+C<xpm>, C<mng>, C<jng>, C<ilbm>, C<pcx>, C<fits>, C<psd> (Photoshop), C<eps>, Utah
+C<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 for width or height is treated as unlimited.
+
+A limit of zero for bytes is treated as one gigabyte, but higher bytes
+limits can be set explicitly.
+
+By default, the width and height limits are zero, or unlimited. The
+default memory size limit is one gigabyte.
+
+You can reset all limits to their defaults with the reset parameter:
+
+ # 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();
+
+=item check_file_limits()
+X<class methods, check_file_limits()>X<check_file_limits()>
+
+Intended for use by file handlers to check that the size of a file is
+within the limits set by C<set_file_limits()>.
+
+Parameters:
+
+=over
+
+=item *
+
+C<width>, C<height> - the width and height of the image in pixels.
+Must be a positive integer. Required.
+
+=item *
+
+C<channels> - the number of channels in the image, including the alpha
+channel if any. Must be a positive integer between 1 and 4
+inclusive. Default: 3.
+
+=item *
+
+C<sample_size> - the number of bytes stored per sample. Must be a
+positive integer or C<"float">. Note that this should be the sample
+size of the Imager image you will be creating, not the sample size in
+the source, eg. if the source has 32-bit samples this should be
+C<"float"> since Imager doesn't have 32-bit/sample images.
+
+=back
+
+=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.
+
+=for stopwords aNy PixMaps BitMap
+
+=head2 PNM (Portable aNy Map)
+
+Imager can write C<PGM> (Portable Gray Map) and C<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
+C<PBM> (Portable BitMap), C<PGM> and C<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>C<pnm_maxval> - the C<maxvals> number from the PGM/PPM header.
+Always set to 2 for a C<PBM> file.
+
+=item *
+
+X<pnm_type>C<pnm_type> - the type number from the C<PNM> header, 1 for ASCII
+C<PBM> files, 2 for ASCII C<PGM> files, 3 for ASCII c<PPM> files, 4 for binary
+C<PBM> files, 5 for binary C<PGM> files, 6 for binary C<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 C<PGM>/C<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 ranging from 0 (worst
+quality) to 100 (best quality) when writing a JPEG file, which
+defaults to 75.
+
+ $img->write(file=>'foo.jpg', jpegquality=>90) or die $img->errstr;
+
+If you write an image with an alpha channel to a JPEG file then it
+will be composed against the background set by the C<i_background>
+parameter (or tag), or black if not supplied.
+
+Imager will read a gray scale 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 *
+
+C<jpeg_density_unit> - The value of the density unit field in the
+C<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 *
+
+C<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 C<jpeg_density_unit>
+is unknown then this tag isn't set.
+
+=item *
+
+C<jpeg_comment> - Text comment.
+
+=item *
+
+C<jpeg_progressive> - Whether the JPEG file is a progressive
+file. (Imager 0.84)
+
+=back
+
+JPEG supports the spatial resolution tags C<i_xres>, C<i_yres> and
+C<i_aspect_only>.
+
+You can also set the following tags when writing to an image, they are
+not set in the image when reading:
+
+=over
+
+C<jpeg_optimize> - set to a non-zero integer to compute optimal
+Huffman coding tables for the image. This will increase memory usage
+and processing time (about 12% in my simple tests) but can
+significantly reduce file size without a loss of quality.
+
+=back
+
+=for stopwords EXIF
+
+If an C<APP1> block containing EXIF information is found, then any of the
+following tags can be set when reading a JPEG image:
+
+=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 when reading a JPEG image:
+
+=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
+
+Imager will not write EXIF tags to any type of image, if you need more
+advanced EXIF handling, consider L<Image::ExifTool>.
+
+=for stopwords IPTC
+
+=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
+
+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 color map of the logical
+screen's background color. This is only set if the current image uses
+the global color map. 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 color map 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
+color to use for the palette entry used to represent transparency in
+the palette. You need to set the C<transp> option (see
+L<Imager::ImageTypes/"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 C<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 color table
+(the first uses the global color 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 C<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 multiple 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 behavior by calling read with the
+C<gif_consolidate> parameter set to a true value:
+
+ $img->read(file=>$some_gif_file, gif_consolidate=>1);
+
+As with the to_paletted() method, if you supply a colors parameter as
+a reference to an array, this will be filled with Imager::Color
+objects of the color table generated for the image file.
+
+=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.
+
+When writing direct color images to TIFF the sample size of the
+output file depends on the input:
+
+=over
+
+=item *
+
+double/sample - written as 32-bit/sample TIFF
+
+=item *
+
+16-bit/sample - written as 16-bit/sample TIFF
+
+=item *
+
+8-bit/sample - written as 8-bit/sample TIFF
+
+=back
+
+For paletted images:
+
+=over
+
+=item *
+
+C<< $img->is_bilevel >> is true - the image is written as bi-level
+
+=item *
+
+otherwise - image is written as paletted.
+
+=back
+
+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 gray scale 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 *
+
+C<class> - If set to 'fax' the image will be written as a bi-level fax
+image.
+
+=item *
+
+C<fax_fine> - By default when C<class> is set to 'fax' the image is
+written in fine mode, you can select normal mode by setting
+C<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.
+
+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 *
+
+8-bit/sample gray, RGB or CMYK images, including a possible alpha
+channel as an 8-bit/sample image.
+
+=item *
+
+16-bit gray, RGB, or CMYK image, including a possible alpha channel as
+a 16-bit/sample image.
+
+=item *
+
+32-bit gray, 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
+
+=item *
+
+other images are read using C<tifflib>'s RGBA interface as
+8-bit/sample images.
+
+=back
+
+The following tags are set in a TIFF image when read, and can be set
+to control output:
+
+=over
+
+=item *
+
+C<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.
+
+=for stopwords LZW
+
+Imager attempts to check that your build of C<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 C<libtiff> is configured with
+C<libjpeg>'s location.
+
+ $im->write(file => 'foo.tif', tiff_compression => 'lzw')
+ or die $im->errstr;
+
+=item *
+
+C<tags, tiff_jpegquality>C<tiff_jpegquality> - If C<tiff_compression>
+is 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 *
+
+X<tags, tiff_resolutionunit>C<tiff_resolutionunit> - The value of the
+C<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 *
+
+X<tags, tiff_resolutionunit_name>C<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 *
+
+X<tags, tiff_bitspersample>C<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 *
+
+X<tags, tiff_photometric>C<tiff_photometric> - Value of the
+C<PhotometricInterpretation> tag from the image. This value is not
+used when writing an image, it is only set on a read image.
+
+=item *
+
+C<tiff_documentname>, C<tiff_imagedescription>, C<tiff_make>,
+C<tiff_model>, C<tiff_pagename>, C<tiff_software>, C<tiff_datetime>,
+C<tiff_artist>, C<tiff_hostcomputer> - Various strings describing the
+image. C<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";
+
+If you read an image with multiple alpha channels, then only the first
+alpha channel will be read.
+
+When reading a C<TIFF> image with callbacks, the C<seekcb> callback
+parameter is also required.
+
+When writing a C<TIFF> image with callbacks, the C<seekcb> and
+C<readcb> parameters are also required.
+
+C<TIFF> is a random access file format, it cannot be read from or
+written to unseekable streams such as pipes or sockets.
+
+=head2 BMP (Windows 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 multiple 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:
+
+=for stopwords RLE
+
+=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
+
+=for stopwords Targa
+
+=head2 TGA (Targa)
+
+When storing Targa images RLE compression can be activated with the
+C<compress> parameter, the C<idstring> parameter can be used to set the
+Targa comment field and the C<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 C<xsize> and C<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 C<raw_datachannels> and
+C<raw_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,
+ raw_datachannels => 4, raw_storechannels => 3,
+ raw_interleave => 0)
+ or die "Cannot read raw image\n";
+
+In general, if you supply C<raw_storechannels> you should also supply
+C<raw_datachannels>
- Imager->write_multi({ file=> $filename, ... }, @images)
- or die "Cannot write: ", Imager->errstr;
+Read parameters:
- my @imgs = Imager->read_multi(file=>$filename)
- or die "Cannot read: ", Imager->errstr;
+=over
-=head1 DESCRIPTION
+=item *
-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.
+C<raw_interleave> - controls the ordering of samples within the image.
+Default: 1. Alternatively and historically spelled C<interleave>.
+Possible values:
-To see which image formats Imager is compiled to support the following
-code snippet is sufficient:
+=over
- use Imager;
- print join " ", keys %Imager::formats;
+=item *
-This will include some other information identifying libraries rather
-than file formats.
+0 - samples are pixel by pixel, so all samples for the first pixel,
+then all samples for the second pixel and so on. eg. for a four pixel
+scan line the channels would be laid out as:
-Reading writing to and from files is simple, use the C<read()>
-method to read an image:
+ 012012012012
- my $img = Imager->new;
- $img->read(file=>$filename, type=>$type)
- or die "Cannot read $filename: ", $img->errstr;
+=item *
-and the C<write()> method to write an image:
+1 - samples are line by line, so channel 0 for the entire scan line is
+followed by channel 1 for the entire scan line and so on. eg. for a
+four pixel scan line the channels would be laid out as:
- $img->write(file=>$filename, type=>$type)
- or die "Cannot write $filename: ", $img->errstr;
+ 000011112222
-If you're reading from a format that supports multiple images per
-file, use the C<read_multi()> method:
+This is the default.
- my @imgs = Imager->read_multi(file=>$filename, type=>$type)
- or die "Cannot read $filename: ", Imager->errstr;
+=back
-and if you want to write multiple images to a single file use the
-C<write_multi()> method:
+Unfortunately, historically, the default C<raw_interleave> for read
+has been 1, while writing only supports the C<raw_interleave> = 0
+format.
- Imager->write_multi({ file=> $filename, type=>$type }, @images)
- or die "Cannot write $filename: ", Imager->errstr;
+For future compatibility, you should always supply the
+C<raw_interleave> (or C<interleave>) parameter. As of 0.68, Imager
+will warn if you attempt to read a raw image without a
+C<raw_interleave> parameter.
-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.
+=item *
-The C<type> parameter is a lowercase representation of the file type,
-and can be any of the following:
+C<raw_storechannels> - the number of channels to store in the image.
+Range: 1 to 4. Default: 3. Alternatively and historically spelled
+C<storechannels>.
- 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)
+=item *
-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.
+C<raw_datachannels> - the number of channels to read from the file.
+Range: 1 or more. Default: 3. Alternatively and historically spelled
+C<datachannels>.
-=head2 Input and output
+=back
-When reading or writing you can specify one of a variety of sources or
-targets:
+ $img->read(file=>'foo.raw', xsize=100, ysize=>100, raw_interleave=>1)
+ or die "Cannot read raw image\n";
-=over
+=head2 PNG
-=item file
+=head3 PNG Image modes
-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>.
+PNG files can be read and written in the following modes:
-=item fh
+=over
-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 *
-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.
+bi-level - written as a 1-bit per sample gray scale image
-=item fd
+=item *
-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.
+paletted - Imager gray scale paletted images are written as RGB
+paletted images. PNG palettes can include alpha values for each entry
+and this is honored as an Imager four channel paletted image.
-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.
+=item *
-=item data
+8 and 16-bit per sample gray scale, optionally with an alpha channel.
-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 *
-=item callback
+8 and 16-bit per sample RGB, optionally with an alpha channel.
-Imager will make calls back to your supplied coderefs to read, write
-and seek from/to/through the image file.
+=back
-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.
+Unlike GIF, there is no automatic conversion to a paletted image,
+since PNG supports direct color.
-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.
+=head3 PNG Text tags
-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.
+Text tags are retrieved from and written to PNG C<tEXT> or C<zTXT>
+chunks. The following standard tags from the PNG specification are
+directly supported:
-Your write callback takes exactly one parameter, a scalar containing
-the data to be written. Return true for success.
+=over
-The seek callback takes 2 parameters, a I<POSITION>, and a I<WHENCE>,
-defined in the same way as perl's seek function.
+=item *
-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.
+C<i_comment>X<tags,i_comment> - keyword of "Comment".
-=back
+=item *
-=head2 Guessing types
+C<png_author>X<tags,PNG,png_author> - keyword "Author".
-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.
+=item *
-Return either a valid Imager file type, or undef.
+C<png_copyright>X<tags,PNG,png_copyright> - keyword "Copyright".
- # I'm writing jpegs to weird filenames
- local $Imager::FORMATGUESS = sub { 'jpeg' };
+=item *
-=head1 TYPE SPECIFIC INFORMATION
+C<png_creation_time>X<tags,PNG,png_creation_time> - keyword "Creation Time".
-The different image formats can write different image type, and some have
-different options to control how the images are written.
+=item *
-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.
+C<png_description>X<tags,PNG,png_description> - keyword "Description".
-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:
+=item *
- Imager::init(warn_obsolete=>0);
+C<png_disclaimer>X<tags,PNG,png_disclaimer> - keyword "Disclaimer".
-At some point in the future these obsolete options will no longer be
-supported.
+=item *
-=head2 PNM (Portable aNy Map)
+C<png_software>X<tags,PNG,png_software> - keyword "Software".
-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.
+=item *
- $img->write(file=>'foo.ppm') or die $img->errstr;
+C<png_title>X<tags,PNG,png_title> - keyword "Title".
-Imager can read both the ASCII and binary versions of each of the PBM
-(Portable BitMap), PGM and PPM formats.
+=item *
- $img->read(file=>'foo.ppm') or die $img->errstr;
+C<png_warning>X<tags,PNG,png_warning> - keyword "Warning".
-PNM does not support the spatial resolution tags.
+=back
-=head2 JPEG
+Each of these tags has a corresponding C<< I<base-tag-name>_compressed
+>> tag, eg. C<png_comment_compressed>. When reading, if the PNG chunk
+is compressed this tag will be set to 1, but is otherwise unset. When
+writing, Imager will honor the compression tag if set and non-zero,
+otherwise the chunk text will be compressed if the value is longer
+than 1000 characters, as recommended by the C<libpng> documentation.
-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.
+PNG C<tEXT> or C<zTXT> chunks outside of those above are read into or
+written from Imager tags named like:
- $img->write(file=>'foo.jpg', jpegquality=>90) or die $img->errstr;
+=over
-Imager will read a grayscale JPEG as a 1 channel image and a color
-JPEG as a 3 channel image.
+=item *
- $img->read(file=>'foo.jpg') or die $img->errstr;
+C<< png_textI<N>_key >> - the key for the text chunk. This can be 1
+to 79 characters, may not contain any leading, trailing or consecutive
+spaces, and may contain only Latin-1 characters from 32-126, 161-255.
-PNM does not support the spatial resolution tags.
+=item *
-=head2 GIF (Graphics Interchange Format)
+C<< png_textI<N>_text >> - the text for the text chunk. This may not
+contain any C<NUL> characters.
-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.
+=item *
-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.
+C<< png_textI<N>_compressed >> - whether or not the text chunk is
+compressed. This behaves similarly to the C<<
+I<base-tag-name>_compressed >> tags described above.
-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.
+=back
-GIF does not support the spatial resolution tags.
+Where I<N> starts from 0. When writing both the C<..._key> and
+C<..._text> tags must be present or the write will fail. If the key
+or text do not satisfy the requirements above the write will fail.
-Imager will set the following tags in each image when reading, and can
-use most of them when writing to GIF:
+=head3 Other PNG metadata tags
=over
-=item gif_left
+=item *
+
+X<tags, png_interlace>C<png_interlace>, C<png_interlace_name> - only
+set when reading, C<png_interlace> is set to the type of interlacing
+used by the file, 0 for one, 1 for Adam7. C<png_interlace_name> is
+set to a keyword describing the interlacing, either C<none> or
+C<adam7>.
+
+=item *
+
+X<tags, png_srgb_intent>C<png_srgb_intent> - the sRGB rendering intent
+for the image. an integer from 0 to 3, per the PNG specification. If
+this chunk is found in the PNG file the C<gAMA> and C<cHRM> are
+ignored and the C<png_gamma> and C<png_chroma_...> tags are not set.
+Similarly when writing if C<png_srgb_intent> is set the C<gAMA> and
+C<cHRM> chunks are not written.
+
+=item *
-the offset of the image from the left of the "screen" ("Image Left
-Position")
+X<tags, png_gamma>C<png_gamma> - the gamma of the image. This value is
+not currently used by Imager when processing the image, but this may
+change in the future.
-=item gif_top
+=item *
-the offset of the image from the top of the "screen" ("Image Top Position")
+X<tags, png_chroma_...>C<png_chroma_white_x>, C<png_chroma_white_y>,
+C<png_chroma_red_x>, C<png_chroma_red_y>, C<png_chroma_green_x>,
+C<png_chroma_green_y>, C<png_chroma_blue_x>, C<png_chroma_blue_y> -
+the primary chromaticities of the image, defining the color model.
+This is currently not used by Imager when processing the image, but
+this may change in the future.
-=item gif_interlace
+=item *
-non-zero if the image was interlaced ("Interlace Flag")
+C<i_xres>, C<i_yres>, C<i_aspect_only> - processed per
+I<Imager::ImageTypes/CommonTags>.
-=item gif_screen_width
+=item *
-=item gif_screen_height
+X<tags, png_bits>C<png_bits> - the number of bits per sample in the
+representation. Ignored when writing.
-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").
+=item *
-When writing this is used as a minimum, if the combination of the
-image size and the image's C<gif_left> and C<gif_top> is beyond this
-size then the screen size will be expanded.
+X<tags, png_time>C<png_time> - the creation time of the file formatted
+as C<< I<year>-I<month>-I<day>TI<hour>:I<minute>:I<second> >>. This
+is stored as time data structure in the file, not a string. If you
+set C<png_time> and it cannot be parsed as above, writing the PNG file
+will fail.
-=item gif_local_map
+=item *
-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.
+C<i_background> - set from the C<sBKG> when reading an image file.
-=item gif_background
+=back
+
+X<compression>X<png_compression_level>You can control the level of
+F<zlib> compression used when writing with the
+C<png_compression_level> parameter. This can be an integer between 0
+(uncompressed) and 9 (best compression).
-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.
+=for stopwords
+CRC
-=item gif_trans_index
+X<png_ignore_benign_errors>If you're using F<libpng> 1.6 or later, or
+an earlier release configured with C<PNG_BENIGN_ERRORS_SUPPORTED>, you
+can choose to ignore file format errors the authors of F<libpng>
+consider I<benign>, this includes at least CRC errors and palette
+index overflows. Do this by supplying a true value for the
+C<png_ignore_benign_errors> parameter to the read() method:
-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")
+ $im->read(file => "foo.png", png_ignore_benign_errors => 1)
+ or die $im->errstr;
-=item gif_trans_color
+=head2 ICO (Microsoft Windows Icon) and CUR (Microsoft Windows Cursor)
-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.
+Icon and Cursor files are very similar, the only differences being a
+number in the header and the storage of the cursor hot spot. I've
+treated them separately so that you're not messing with tags to
+distinguish between them.
-=item gif_delay
+The following tags are set when reading an icon image and are used
+when writing it:
-The delay until the next frame is displayed, in 1/100 of a second.
-("Delay Time").
+=over
-=item gif_user_input
+=item ico_mask
-whether or not a user input is expected before continuing (view dependent)
-("User Input Flag").
+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.
-=item gif_disposal
+Rather than requiring a binary bitmap this is accepted in a specific format:
-how the next frame is displayed ("Disposal Method")
+=over
-=item gif_loop
+=item *
-the number of loops from the Netscape Loop extension. This may be zero.
+first line consisting of the 0 placeholder, the 1 placeholder and a
+newline.
-=item gif_comment
+=item *
-the first block of the first gif comment before each image.
+following lines which contain 0 and 1 placeholders for each scan line
+of the image, starting from the top of the image.
-=item gif_eliminate_unused
+=back
-If this is true, when you write a paletted image any unused colors
-will be eliminated from its palette. This is set by default.
+When reading an image, '.' is used as the 0 placeholder and '*' as the
+1 placeholder. An example:
+
+ .*
+ ..........................******
+ ..........................******
+ ..........................******
+ ..........................******
+ ...........................*****
+ ............................****
+ ............................****
+ .............................***
+ .............................***
+ .............................***
+ .............................***
+ ..............................**
+ ..............................**
+ ...............................*
+ ...............................*
+ ................................
+ ................................
+ ................................
+ ................................
+ ................................
+ ................................
+ *...............................
+ **..............................
+ **..............................
+ ***.............................
+ ***.............................
+ ****............................
+ ****............................
+ *****...........................
+ *****...........................
+ *****...........................
+ *****...........................
=back
-Where applicable, the ("name") is the name of that field from the GIF89
-standard.
+The following tags are set when reading an icon:
-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 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 gif_each_palette
+=item cur_mask
-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.
+This is the same as the ico_mask above.
-Use C<gif_local_map> in new code.
+=item cur_hotspotx
-=item interlace
+=item cur_hotspoty
-The images are written interlaced if this is non-zero.
+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.
-Use C<gif_interlace> in new code.
+=back
-=item gif_delays
+The following parameters can be supplied to read() or read_multi() to
+control reading of ICO/CUR files:
-A reference to an array containing the delays between images, in 1/100
-seconds.
+=over
-Use C<gif_delay> in new code.
+=item *
-=item gif_positions
+C<ico_masked> - if true, the default, then the icon/cursors mask is
+applied as an alpha channel to the image, unless that image already
+has an alpha channel. This may result in a paletted image being
+returned as a direct color image. Default: 1
-A reference to an array of references to arrays which represent screen
-positions for each image.
+ # 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;
-New code should use the C<gif_left> and C<gif_top> tags.
+This was introduced in Imager 0.60. Previously reading ICO images
+acted as if C<ico_masked =E<gt> 0>.
-=item gif_loop_count
+=item *
-If this is non-zero the Netscape loop extension block is generated,
-which makes the animation of the images repeat.
+C<ico_alpha_masked> - if true, then the icon/cursor mask is applied as
+an alpha channel to images that already have an alpha mask. Note that
+this will only make pixels transparent, not opaque. Default: 0.
-This is currently unimplemented due to some limitations in giflib.
+Note: If you get different results between C<ico_alpha_masked> being
+set to 0 and 1, your mask may break when used with the Win32 API.
=back
-=head2 TIFF (Tagged Image File Format)
+C<cur_bits> is set when reading a cursor.
-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.
+Examples:
-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 $img = Imager->new(xsize => 32, ysize => 32, channels => 4);
+ $im->box(color => 'FF0000');
+ $im->write(file => 'box.ico');
- my $bilevel = $img->to_paletted(colors=>[ NC(0,0,0), NC(255,255,255) ],
- make_colors => 'none',
- translate => 'errdiff',
- errdiff => 'stucki');
+ $im->settag(name => 'cur_hotspotx', value => 16);
+ $im->settag(name => 'cur_hotspoty', value => 16);
+ $im->write(file => 'box.cur');
+
+=for stopwords BW
+
+=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 class
+=item *
-If set to 'fax' the image will be written as a bi-level fax image.
+i_comment - the C<IMAGENAME> field from the image. Also written to
+the file when writing.
-=item fax_fine
+=item *
-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.
+sgi_pixmin, sgi_pixmax - the C<PIXMIN> and C<PIXMAX> fields from the
+image. On reading image data is expanded from this range to the full
+range of samples in the image.
-=back
+=item *
-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.
+sgi_bpc - the number of bytes per sample for the image. Ignored when
+writing.
-TIFF supports the spatial resolution tags. See the
-C<tiff_resolutionunit> tag for some extra options.
+=item *
-The following tags are set in a TIFF image when read, and can be set
-to control output:
+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 tiff_resolutionunit
+=item register_reader()
-The value of the ResolutionUnit tag. This is ignored on writing if
-the i_aspect_only tag is non-zero.
+Registers single or multiple image read functions.
-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.
+Parameters:
-=item tiff_resolutionunit_name
+=over
-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 *
-=item tiff_documentname
+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.
-=item tiff_imagedescription
+This parameter is required.
-=item tiff_make
+=item *
-=item tiff_model
+single - a code ref to read a single image from a file. This is
+supplied:
-=item tiff_pagename
+=over
+
+=item *
-=item tiff_software
+the object that read() was called on,
-=item tiff_datetime
+=item *
-=item tiff_artist
+an Imager::IO object that should be used to read the file, and
-=item tiff_hostcomputer
+=item *
-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.
+all the parameters supplied to the read() method.
=back
-=head2 BMP (BitMaP)
+The single parameter is required.
-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.
+=item *
-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.
+multiple - a code ref which is called to read multiple images from a
+file. This is supplied:
-BMP has no support for multi-image files.
+=over
-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.
+=item *
-The following tags are set when you read an image from a BMP file:
+an Imager::IO object that should be used to read the file, and
-=over
+=item *
-=item bmp_compression
+all the parameters supplied to the read_multi() method.
-The type of compression, if any. This can be any of the following
-values:
+=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 BI_RGB (0)
+=item *
-Uncompressed.
+type - the identifier of the file format. This is typically the
+extension in lowercase.
-=item BI_RLE8 (1)
+This parameter is required.
-8-bits/pixel paletted value RLE compression.
+=item *
-=item BI_RLE4 (2)
+single - a code ref to write a single image to a file. This is
+supplied:
-4-bits/pixel paletted value RLE compression.
+=over
-=item BI_BITFIELDS (3)
+=item *
-Packed RGB values.
+the object that write() was called on,
-=back
+=item *
-=item bmp_compression_name
+an Imager::IO object that should be used to write the file, and
-The bmp_compression value as a BI_* string
+=item *
-=item bmp_important_colors
+all the parameters supplied to the write() method.
-The number of important colors as defined by the writer of the image.
+=back
-=item bmp_used_colors
+The single parameter is required.
-Number of color used from the BMP header
+=item *
-=item bmp_filesize
+multiple - a code ref which is called to write multiple images to a
+file. This is supplied:
-The file size from the BMP header
+=over
-=item bmp_bit_count
+=item *
-Number of bits stored per pixel. (24, 8, 4 or 1)
+the class name write_multi() was called on, this is typically
+C<Imager>.
-=back
+=item *
-=head2 TGA (TarGA)
+an Imager::IO object that should be used to write the file, and
-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.
+=item *
+all the parameters supplied to the read_multi() method.
-Tags:
+=back
-=over
+=back
-=item tga_idstring
+=back
-=item tga_bitspp
+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.
-=item compressed
+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.
-=back
+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.
-=head2 RAW
+=head1 PRELOADING FILE MODULES
+=over
-When reading raw images you need to supply the width and height of the
-image in the xsize and ysize options:
+=item preload()
- $img->read(file=>'foo.raw', xsize=>100, ysize=>100)
- or die "Cannot read raw image\n";
+This preloads the file support modules included with or that have been
+included with Imager in the past. This is intended for use in forking
+servers such as mod_perl.
-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:
+If the module is not available no error occurs.
- $img->read(file=>'foo.raw', xsize=>100, ysize=>100, datachannels=>4,
- storechannels=>3)
- or die "Cannot read raw image\n";
+Preserves $@.
-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:
+ use Imager;
+ Imager->preload;
- $img->read(file=>'foo.raw', xsize=100, ysize=>100, interleave=>1)
- or die "Cannot read raw image\n";
+=back
=head1 EXAMPLES
Once you have an image the basic mechanism is:
+=for stopwords STDOUT
+
=over
=item 1.
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:
+could either use the standard web 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
+By default all of the images will use the same global color map, which
will produce a smaller image. If your images have significant color
differences, you may want to generate a new palette for each image:
=head1 BUGS
-When saving Gif images the program does NOT try to shave of extra
+When saving GIF images the program does NOT try to shave off 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.
+only 2 colors used - it will have a 128 color table anyway.
=head1 SEE ALSO
Imager(3)
+=head1 AUTHOR
+
+Tony Cook <tonyc@cpan.org>, Arnar M. Hrafnkelsson
+
=cut
projects / imager.git / blobdiff