=head1 SYNOPSIS
+ use Imager;
my $img = ...;
$img->write(file=>$filename, type=>$type)
or die "Cannot write: ",$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
print join " ", keys %Imager::formats;
This will include some other information identifying libraries rather
-than file formats.
+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:
$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_partial> 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;
-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 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</Tags> for specifics.
+animation information. See L<Imager::ImageTypes/Tags> for specifics.
+
+The open() method is a historical alias for the read() method.
=head2 Input and output
=over
-=item file
+=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;
-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>.
+ my $image = Imager->new;
+ $image->read(file => 'example.tif')
+ or die $image->errstr;
-=item fh
+=item *
-C<fh> is a file handle, typically either returned from
+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.
-=item fd
+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.
-C<fd> is a file descriptor. You can get this by calling the
+ $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.
-=item data
+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;
-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
+C<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 C<giflib> 4 or
+higher, and you may need to patch C<giflib> to use this option for
+writing.
-Imager will make calls back to your supplied coderefs to read, write
-and seek from/to/through the image file.
+ 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 *
+
+C<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
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
-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.
+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.
+
+The default function value of C<$Imager::FORMATGUESS> is
+C<\&Imager::def_guess_type>.
+
+=over
-Return either a valid Imager file type, or undef.
+=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 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 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.
+
+=for stopwords aNy PixMaps BitMap
+
=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.
+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 PBM
-(Portable BitMap), PGM and PPM formats.
+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
+=for stopwords composited
+
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.
+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
+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;
-PNM does not support the spatial resolution tags.
+The following tags are set in a JPEG image when read, and can be set
+to control output:
-=head2 GIF (Graphics Interchange Format)
+=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.
-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.
+=item C<jpeg_density_unit_name>
-These options can be specified when calling write_multi() or when
-writing a single image with the C<gifquant> option set to 'gen'
+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.
-Note that some viewers will ignore some of these options
-(gif_user_input in particular).
+=item C<jpeg_comment>
-=over 4
+Text comment.
-=item gif_each_palette
+=back
+
+JPEG supports the spatial resolution tags C<i_xres>, C<i_yres> and
+C<i_aspect_only>.
-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.
+=for stopwords EXIF
-=item interlace
+If an C<APP1> block containing EXIF information is found, then any of the
+following tags can be set when reading a JPEG image:
-The images are written interlaced if this is non-zero.
+=over
-=item gif_delays
+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
-A reference to an array containing the delays between images, in 1/100
-seconds.
+=back
-If you want the same delay for every frame you can simply set this to
-the delay in 1/100 seconds.
+The following derived tags can also be set when reading a JPEG image:
-=item gif_user_input
+=over
-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.
+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
-=item gif_disposal
+=back
-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.
+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>.
-=item gif_tran_color
+eg.
-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.
+ 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";
-=item gif_positions
+ # for the exiftest.jpg in the Imager distribution the output would be:
+ Imager Development Notes
+ 0
+ Auto exposure
-A reference to an array of references to arrays which represent screen
-positions for each image.
+Imager will not write EXIF tags to any type of image, if you need more
+advanced EXIF handling, consider L<Image::ExifTool>.
-=item gif_loop_count
+=for stopwords IPTC
-If this is non-zero the Netscape loop extension block is generated,
-which makes the animation of the images repeat.
+=over
-This is currently unimplemented due to some limitations in giflib.
+=item parseiptc()
-=item gif_eliminate_unused
+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.
-If this is true, when you write a paletted image any unused colors
-will be eliminated from its palette. This is set by default.
+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->read()>> you can supply a
+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
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:
+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
+=item *
+
+gif_left - the offset of the image from the left of the "screen"
+("Image Left Position")
+
+=item *
-the offset of the image from the left of the "screen" ("Image Left
-Position")
+gif_top - the offset of the image from the top of the "screen" ("Image
+Top Position")
-=item gif_top
+=item *
-the offset of the image from the top of the "screen" ("Image Top Position")
+gif_interlace - non-zero if the image was interlaced ("Interlace
+Flag")
-=item gif_interlace
+=item *
-non-zero if the image was interlaced ("Interlace Flag")
+gif_screen_width, gif_screen_height - the size of the logical
+screen. When writing this is used as the minimum. If any image being
+written would extend beyond this then the screen size is extended.
+("Logical Screen Width", "Logical Screen Height").
-=item gif_screen_width
+=item *
-=item gif_screen_height
+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.
-the size of the logical screen ("Logical Screen Width",
-"Logical Screen Height")
+=item *
-=item gif_local_map
+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.
-Non-zero if this image had a local color map.
+=item *
-=item gif_background
+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")
-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 *
-=item gif_trans_index
+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<Quantization
+options>) for this value to be used.
-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 *
-=item gif_delay
+gif_delay - The delay until the next frame is displayed, in 1/100 of a
+second. ("Delay Time").
-The delay until the next frame is displayed, in 1/100 of a second.
-("Delay Time").
+=item *
-=item gif_user_input
+gif_user_input - whether or not a user input is expected before
+continuing (view dependent) ("User Input Flag").
-whether or not a user input is expected before continuing (view dependent)
-("User Input Flag").
+=item *
-=item gif_disposal
+gif_disposal - how the next frame is displayed ("Disposal Method")
-how the next frame is displayed ("Disposal Method")
+=item *
-=item gif_loop
+gif_loop - the number of loops from the Netscape Loop extension. This
+may be zero to loop forever.
-the number of loops from the Netscape Loop extension. This may be zero.
+=item *
-=item gif_comment
+gif_comment - the first block of the first GIF comment before each
+image.
-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
+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.
+
+=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<datachannels> and
+C<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";
+
+Read parameters:
+
+=over
+
+=item *
+
+raw_interleave - controls the ordering of samples within the image.
+Default: 1. Alternatively and historically spelled C<interleave>.
+Possible values:
+
+=over
+
+=item *
+
+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:
+
+ 012012012012
+
+=item *
+
+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:
+
+ 000011112222
+
+This is the default.
+
+=back
+
+Unfortunately, historically, the default C<raw_interleave> for read
+has been 1, while writing only supports the C<raw_interleave> = 0
+format.
+
+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.
+
+=item *
+
+raw_storechannels - the number of channels to store in the image.
+Range: 1 to 4. Default: 3. Alternatively and historically spelled
+C<storechannels>.
+
+=item *
+
+raw_datachannels - the number of channels to read from the file.
+Range: 1 or more. Default: 3. Alternatively and historically spelled
+C<datachannels>.
+
+=back
+
+ $img->read(file=>'foo.raw', xsize=100, ysize=>100, raw_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 hot spot. 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 scan line
+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 =E<gt> 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');
+
+=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 *
+
+i_comment - the C<IMAGENAME> field from the image. Also written to
+the file when writing.
+
+=item *
+
+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.
+
+=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:
+
+=for stopwords STDOUT
+
+=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 web color map:
+
+ 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 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:
+
+ 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 off extra
+colors if it is possible. If you specify 128 colors and there are
+only 2 colors used - it will have a 128 color table anyway.
-=head2 BMP (BitMaP)
+=head1 SEE ALSO
-=head2 TGA (TarGA)
+Imager(3)
=cut
projects / imager.git / blobdiff