summaryrefslogtreecommitdiff
path: root/Master/tlpkg/tlperl0/lib/Imager/Files.pod
diff options
context:
space:
mode:
Diffstat (limited to 'Master/tlpkg/tlperl0/lib/Imager/Files.pod')
-rwxr-xr-xMaster/tlpkg/tlperl0/lib/Imager/Files.pod1608
1 files changed, 1608 insertions, 0 deletions
diff --git a/Master/tlpkg/tlperl0/lib/Imager/Files.pod b/Master/tlpkg/tlperl0/lib/Imager/Files.pod
new file mode 100755
index 00000000000..b7d612bf4d4
--- /dev/null
+++ b/Master/tlpkg/tlperl0/lib/Imager/Files.pod
@@ -0,0 +1,1608 @@
+=head1 NAME
+
+Imager::Files - working with image files
+
+=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
+the appropriate libraries, and images can be read or written to/from
+files, file handles, file descriptors, scalars, or through callbacks.
+
+To see which image formats Imager is compiled to support the following
+code snippet is sufficient:
+
+ use Imager;
+ print join " ", keys %Imager::formats;
+
+This will include some other information identifying libraries rather
+than file formats. For new code you might find the L</read_types> or
+L</write_types> methods useful.
+
+=over
+
+=item read
+
+Reading writing to and from files is simple, use the C<read()>
+method to read an image:
+
+ my $img = Imager->new;
+ $img->read(file=>$filename, type=>$type)
+ or die "Cannot read $filename: ", $img->errstr;
+
+In most cases Imager can auto-detect the file type, so you can just
+supply the filename:
+
+ $img->read(file => $filename)
+ or die "Cannot read $filename: ", $img->errstr;
+
+The read() method accepts the C<allow_partial> parameter. If this is
+non-zero then read() can return true on an incomplete image and set
+the C<i_incomplete> tag.
+
+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 I<filename> includes an extension that Imager
+recognizes, then you don't need the I<type>, but you may want to
+provide one anyway. See L</Guessing types> for information on
+controlling this recognition.
+
+The C<type> parameter is a lowercase representation of the file type,
+and can be any of the following:
+
+ bmp Windows BitMaP (BMP)
+ gif Graphics Interchange Format (GIF)
+ jpeg JPEG/JFIF
+ png Portable Network Graphics (PNG)
+ pnm Portable aNyMap (PNM)
+ raw Raw
+ sgi SGI .rgb files
+ tga TARGA
+ tiff Tagged Image File Format (TIFF)
+
+When you read an image, Imager may set some tags, possibly including
+information about the spatial resolution, textual information, and
+animation information. See L<Imager::ImageTypes/Tags> for specifics.
+
+The open() method is a historical alias for the read() method.
+
+=head2 Input and output
+
+When reading or writing you can specify one of a variety of sources or
+targets:
+
+=over
+
+=item *
+
+file - The C<file> parameter is the name of the image file to be
+written to or read from. If Imager recognizes the extension of the
+file you do not need to supply a C<type>.
+
+ # write in tiff format
+ $image->write(file => "example.tif")
+ or die $image->errstr;
+
+ $image->write(file => 'foo.tmp', type => 'tiff')
+ or die $image->errstr;
+
+ my $image = Imager->new;
+ $image->read(file => 'example.tif')
+ or die $image->errstr;
+
+=item *
+
+fh - C<fh> is a file handle, typically either returned from
+C<<IO::File->new()>>, or a glob from an C<open> call. You should call
+C<binmode> on the handle before passing it to Imager.
+
+Imager will set the handle to autoflush to make sure any buffered data
+is flushed , since Imager will write to the file descriptor (from
+fileno()) rather than writing at the perl level.
+
+ $image->write(fh => \*STDOUT, type => 'gif')
+ or die $image->errstr;
+
+ # for example, a file uploaded via CGI.pm
+ $image->read(fd => $cgi->param('file'))
+ or die $image->errstr;
+
+=item *
+
+fd - C<fd> is a file descriptor. You can get this by calling the
+C<fileno()> function on a file handle, or by using one of the standard
+file descriptor numbers.
+
+If you get this from a perl file handle, you may need to flush any
+buffered output, otherwise it may appear in the output stream after
+the image.
+
+ $image->write(fd => file(STDOUT), type => 'gif')
+ or die $image->errstr;
+
+=item *
+
+data - When reading data, C<data> is a scalar containing the image
+file data, when writing, C<data> is a reference to the scalar to save
+the image file data too. For GIF images you will need giflib 4 or
+higher, and you may need to patch giflib to use this option for
+writing.
+
+ my $data;
+ $image->write(data => \$data, type => 'tiff')
+ or die $image->errstr;
+
+ my $data = $row->{someblob}; # eg. from a database
+ my @images = Imager->read_multi(data => $data)
+ or die Imager->errstr;
+
+=item *
+
+callback - Imager will make calls back to your supplied coderefs to
+read, write and seek from/to/through the image file.
+
+When reading from a file you can use either C<callback> or C<readcb>
+to supply the read callback, and when writing C<callback> or
+C<writecb> to supply the write callback.
+
+When writing you can also supply the C<maxbuffer> option to set the
+maximum amount of data that will be buffered before your write
+callback is called. Note: the amount of data supplied to your
+callback can be smaller or larger than this size.
+
+The read callback is called with 2 parameters, the minimum amount of
+data required, and the maximum amount that Imager will store in it's C
+level buffer. You may want to return the minimum if you have a slow
+data source, or the maximum if you have a fast source and want to
+prevent many calls to your perl callback. The read data should be
+returned as a scalar.
+
+Your write callback takes exactly one parameter, a scalar containing
+the data to be written. Return true for success.
+
+The seek callback takes 2 parameters, a I<POSITION>, and a I<WHENCE>,
+defined in the same way as perl's seek function.
+
+You can also supply a C<closecb> which is called with no parameters
+when there is no more data to be written. This could be used to flush
+buffered data.
+
+ # contrived
+ my $data;
+ sub mywrite {
+ $data .= unpack("H*", shift);
+ 1;
+ }
+ Imager->write_multi({ callback => \&mywrite, type => 'gif'}, @images)
+ or die Imager->errstr;
+
+Note that for reading you'll almost always need to provide a
+C<seekcb>.
+
+=back
+
+=head2 Guessing types
+
+When writing to a file, if you don't supply a C<type> parameter Imager
+will attempt to guess it from the filename. This is done by calling
+the code reference stored in C<$Imager::FORMATGUESS>. This is only
+done when write() or write_multi() is called with a C<file> parameter.
+
+The default function value of C<$Imager::FORMATGUESS> is
+C<\&Imager::def_guess_type>.
+
+=over
+
+=item def_guess_type
+
+This is the default function Imager uses to derive a file type from a
+file name. This is a function, not a method.
+
+Accepts a single parameter, the filename and returns the type or
+undef.
+
+=back
+
+You can replace function with your own implementation if you have some
+specialized need. The function takes a single parameter, the name of
+the file, and should return either a file type or under.
+
+ # I'm writing jpegs to weird filenames
+ local $Imager::FORMATGUESS = sub { 'jpeg' };
+
+When reading a file Imager examines beginning of the file for
+identifying information. The current implementation attempts to
+detect the following image types beyond those supported by Imager:
+
+=over
+
+xpm, mng, jng, SGI RGB, ilbm, pcx, fits, psd (Photoshop), eps, Utah
+RLE
+
+=back
+
+=head2 Limiting the sizes of images you read
+
+=over
+
+=item set_file_limits
+
+In some cases you will be receiving images from an untested source,
+such as submissions via CGI. To prevent such images from consuming
+large amounts of memory, you can set limits on the dimensions of
+images you read from files:
+
+=over
+
+=item *
+
+width - limit the width in pixels of the image
+
+=item *
+
+height - limit the height in pixels of the image
+
+=item *
+
+bytes - limits the amount of storage used by the image. This depends
+on the width, height, channels and sample size of the image. For
+paletted images this is calculated as if the image was expanded to a
+direct color image.
+
+=back
+
+To set the limits, call the class method set_file_limits:
+
+ Imager->set_file_limits(width=>$max_width, height=>$max_height);
+
+You can pass any or all of the limits above, any limits you do not
+pass are left as they were.
+
+Any limit of zero is treated as unlimited.
+
+By default, all of the limits are zero, or unlimited.
+
+You can reset all of the limited to their defaults by passing in the
+reset parameter as a true value:
+
+ # no limits
+ Imager->set_file_limits(reset=>1);
+
+This can be used with the other limits to reset all but the limit you
+pass:
+
+ # only width is limited
+ Imager->set_file_limits(reset=>1, width=>100);
+
+ # only bytes is limited
+ Imager->set_file_limits(reset=>1, bytes=>10_000_000);
+
+=item get_file_limits
+
+You can get the current limits with the get_file_limits() method:
+
+ my ($max_width, $max_height, $max_bytes) =
+ Imager->get_file_limits();
+
+=back
+
+=head1 TYPE SPECIFIC INFORMATION
+
+The different image formats can write different image type, and some have
+different options to control how the images are written.
+
+When you call C<write()> or C<write_multi()> with an option that has
+the same name as a tag for the image format you're writing, then the
+value supplied to that option will be used to set the corresponding
+tag in the image. Depending on the image format, these values will be
+used when writing the image.
+
+This replaces the previous options that were used when writing GIF
+images. Currently if you use an obsolete option, it will be converted
+to the equivalent tag and Imager will produced a warning. You can
+suppress these warnings by calling the C<Imager::init()> function with
+the C<warn_obsolete> option set to false:
+
+ Imager::init(warn_obsolete=>0);
+
+At some point in the future these obsolete options will no longer be
+supported.
+
+=head2 PNM (Portable aNy Map)
+
+Imager can write PGM (Portable Gray Map) and PPM (Portable PixMaps)
+files, depending on the number of channels in the image. Currently
+the images are written in binary formats. Only 1 and 3 channel images
+can be written, including 1 and 3 channel paletted images.
+
+ $img->write(file=>'foo.ppm') or die $img->errstr;
+
+Imager can read both the ASCII and binary versions of each of the PBM
+(Portable BitMap), PGM and PPM formats.
+
+ $img->read(file=>'foo.ppm') or die $img->errstr;
+
+PNM does not support the spatial resolution tags.
+
+The following tags are set when reading a PNM file:
+
+=over
+
+=item *
+
+X<pnm_maxval>pnm_maxval - the maxvals number from the PGM/PPM header.
+Always set to 2 for a PBM file.
+
+=item *
+
+X<pnm_type>pnm_type - the type number from the PNM header, 1 for ASCII
+PBM files, 2 for ASCII PGM files, 3 for ASCII PPM files, 4 for binary
+PBM files, 5 for binary PGM files, 6 for binary PPM files.
+
+=back
+
+The following tag is checked when writing an image with more than
+8-bits/sample:
+
+=over
+
+=item *
+
+X<pnm_write_wide_data>pnm_write_wide_data - if this is non-zero then
+write() can write PGM/PPM files with 16-bits/sample. Some
+applications, for example GIMP 2.2, and tools can only read
+8-bit/sample binary PNM files, so Imager will only write a 16-bit
+image when this tag is non-zero.
+
+=back
+
+=head2 JPEG
+
+You can supply a C<jpegquality> parameter (0-100) when writing a JPEG
+file, which defaults to 75%. If you write an image with an alpha
+channel to a jpeg file then it will be composited against the
+background set by the C<i_background> parameter (or tag).
+
+ $img->write(file=>'foo.jpg', jpegquality=>90) or die $img->errstr;
+
+Imager will read a grayscale JPEG as a 1 channel image and a color
+JPEG as a 3 channel image.
+
+ $img->read(file=>'foo.jpg') or die $img->errstr;
+
+The following tags are set in a JPEG image when read, and can be set
+to control output:
+
+=over
+
+=item jpeg_density_unit
+
+The value of the density unit field in the JFIF header. This is
+ignored on writing if the C<i_aspect_only> tag is non-zero.
+
+The C<i_xres> and C<i_yres> tags are expressed in pixels per inch no
+matter the value of this tag, they will be converted to/from the value
+stored in the JPEG file.
+
+=item jpeg_density_unit_name
+
+This is set when reading a JPEG file to the name of the unit given by
+C<jpeg_density_unit>. Possible results include C<inch>,
+C<centimeter>, C<none> (the C<i_aspect_only> tag is also set reading
+these files). If the value of jpeg_density_unit is unknown then this
+tag isn't set.
+
+=item jpeg_comment
+
+Text comment.
+
+=back
+
+JPEG supports the spatial resolution tags C<i_xres>, C<i_yres> and
+C<i_aspect_only>.
+
+If an APP1 block containing EXIF information is found, then any of the
+following tags can be set:
+
+=over
+
+exif_aperture exif_artist exif_brightness exif_color_space
+exif_contrast exif_copyright exif_custom_rendered exif_date_time
+exif_date_time_digitized exif_date_time_original
+exif_digital_zoom_ratio exif_exposure_bias exif_exposure_index
+exif_exposure_mode exif_exposure_program exif_exposure_time
+exif_f_number exif_flash exif_flash_energy exif_flashpix_version
+exif_focal_length exif_focal_length_in_35mm_film
+exif_focal_plane_resolution_unit exif_focal_plane_x_resolution
+exif_focal_plane_y_resolution exif_gain_control exif_image_description
+exif_image_unique_id exif_iso_speed_rating exif_make exif_max_aperture
+exif_metering_mode exif_model exif_orientation exif_related_sound_file
+exif_resolution_unit exif_saturation exif_scene_capture_type
+exif_sensing_method exif_sharpness exif_shutter_speed exif_software
+exif_spectral_sensitivity exif_sub_sec_time
+exif_sub_sec_time_digitized exif_sub_sec_time_original
+exif_subject_distance exif_subject_distance_range
+exif_subject_location exif_tag_light_source exif_user_comment
+exif_version exif_white_balance exif_x_resolution exif_y_resolution
+
+=back
+
+The following derived tags can also be set:
+
+=over
+
+exif_color_space_name exif_contrast_name exif_custom_rendered_name
+exif_exposure_mode_name exif_exposure_program_name exif_flash_name
+exif_focal_plane_resolution_unit_name exif_gain_control_name
+exif_light_source_name exif_metering_mode_name
+exif_resolution_unit_name exif_saturation_name
+exif_scene_capture_type_name exif_sensing_method_name
+exif_sharpness_name exif_subject_distance_range_name
+exif_white_balance_name
+
+=back
+
+The derived tags are for enumerated fields, when the value for the
+base field is valid then the text that appears in the EXIF
+specification for that value appears in the derived field. So for
+example if C<exf_metering_mode> is C<5> then
+C<exif_metering_mode_name> is set to C<Pattern>.
+
+eg.
+
+ my $image = Imager->new;
+ $image->read(file => 'exiftest.jpg')
+ or die "Cannot load image: ", $image->errstr;
+ print $image->tags(name => "exif_image_description"), "\n";
+ print $image->tags(name => "exif_exposure_mode"), "\n";
+ print $image->tags(name => "exif_exposure_mode_name"), "\n";
+
+ # for the exiftest.jpg in the Imager distribution the output would be:
+ Imager Development Notes
+ 0
+ Auto exposure
+
+=over
+
+=item parseiptc
+
+Historically, Imager saves IPTC data when reading a JPEG image, the
+parseiptc() method returns a list of key/value pairs resulting from a
+simple decoding of that data.
+
+Any future IPTC data decoding is likely to go into tags.
+
+=back
+
+=head2 GIF (Graphics Interchange Format)
+
+When writing one of more GIF images you can use the same
+L<Quantization Options|Imager::ImageTypes> as you can when converting
+an RGB image into a paletted image.
+
+When reading a GIF all of the sub-images are combined using the screen
+size and image positions into one big image, producing an RGB image.
+This may change in the future to produce a paletted image where possible.
+
+When you read a single GIF with C<$img-E<gt>read()> you can supply a
+reference to a scalar in the C<colors> parameter, if the image is read
+the scalar will be filled with a reference to an anonymous array of
+L<Imager::Color> objects, representing the palette of the image. This
+will be the first palette found in the image. If you want the
+palettes for each of the images in the file, use C<read_multi()> and
+use the C<getcolors()> method on each image.
+
+GIF does not support the spatial resolution tags.
+
+Imager will set the following tags in each image when reading, and can
+use most of them when writing to GIF:
+
+=over
+
+=item *
+
+gif_left - the offset of the image from the left of the "screen"
+("Image Left Position")
+
+=item *
+
+gif_top - the offset of the image from the top of the "screen" ("Image
+Top Position")
+
+=item *
+
+gif_interlace - non-zero if the image was interlaced ("Interlace
+Flag")
+
+=item *
+
+gif_screen_width, gif_screen_height - the size of the logical
+screen. When writing this is used as the minimum. If any image being
+written would extend beyond this then the screen size is extended.
+("Logical Screen Width", "Logical Screen Height").
+
+=item *
+
+gif_local_map - Non-zero if this image had a local color map. If set
+for an image when writing the image is quantized separately from the
+other images in the file.
+
+=item *
+
+gif_background - The index in the global colormap of the logical
+screen's background color. This is only set if the current image uses
+the global colormap. You can set this on write too, but for it to
+choose the color you want, you will need to supply only paletted
+images and set the C<gif_eliminate_unused> tag to 0.
+
+=item *
+
+gif_trans_index - The index of the color in the colormap used for
+transparency. If the image has a transparency then it is returned as
+a 4 channel image with the alpha set to zero in this palette entry.
+This value is not used when writing. ("Transparent Color Index")
+
+=item *
+
+gif_trans_color - A reference to an Imager::Color object, which is the
+colour to use for the palette entry used to represent transparency in
+the palette. You need to set the transp option (see L<Quantization
+options>) for this value to be used.
+
+=item *
+
+gif_delay - The delay until the next frame is displayed, in 1/100 of a
+second. ("Delay Time").
+
+=item *
+
+gif_user_input - whether or not a user input is expected before
+continuing (view dependent) ("User Input Flag").
+
+=item *
+
+gif_disposal - how the next frame is displayed ("Disposal Method")
+
+=item *
+
+gif_loop - the number of loops from the Netscape Loop extension. This
+may be zero to loop forever.
+
+=item *
+
+gif_comment - the first block of the first gif comment before each
+image.
+
+=item *
+
+gif_eliminate_unused - If this is true, when you write a paletted
+image any unused colors will be eliminated from its palette. This is
+set by default.
+
+=item *
+
+gif_colormap_size - the original size of the color map for the image.
+The color map of the image may have been expanded to include out of
+range color indexes.
+
+=back
+
+Where applicable, the ("name") is the name of that field from the GIF89
+standard.
+
+The following gif writing options are obsolete, you should set the
+corresponding tag in the image, either by using the tags functions, or
+by supplying the tag and value as options.
+
+=over
+
+=item *
+
+gif_each_palette - Each image in the gif file has it's own palette if
+this is non-zero. All but the first image has a local colour table
+(the first uses the global colour table.
+
+Use C<gif_local_map> in new code.
+
+=item *
+
+interlace - The images are written interlaced if this is non-zero.
+
+Use C<gif_interlace> in new code.
+
+=item *
+
+gif_delays - A reference to an array containing the delays between
+images, in 1/100 seconds.
+
+Use C<gif_delay> in new code.
+
+=item *
+
+gif_positions - A reference to an array of references to arrays which
+represent screen positions for each image.
+
+New code should use the C<gif_left> and C<gif_top> tags.
+
+=item *
+
+gif_loop_count - If this is non-zero the Netscape loop extension block
+is generated, which makes the animation of the images repeat.
+
+This is currently unimplemented due to some limitations in giflib.
+
+=back
+
+You can supply a C<page> parameter to the C<read()> method to read
+some page other than the first. The page is 0 based:
+
+ # read the second image in the file
+ $image->read(file=>"example.gif", page=>1)
+ or die "Cannot read second page: ",$image->errstr,"\n";
+
+Before release 0.46, Imager would read multi-image GIF image files
+into a single image, overlaying each of the images onto the virtual
+GIF screen.
+
+As of 0.46 the default is to read the first image from the file, as if
+called with C<< page => 0 >>.
+
+You can return to the previous behaviour by calling read with the
+C<gif_consolidate> parameter set to a true value:
+
+ $img->read(file=>$some_gif_file, gif_consolidate=>1);
+
+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. Currently if you write a
+16-bit/sample or double/sample image it will be written as an
+8-bit/sample image. Only 1 or 3 channel images can be written.
+
+If you are creating images for faxing you can set the I<class>
+parameter set to C<fax>. By default the image is written in fine
+mode, but this can be overridden by setting the I<fax_fine> parameter
+to zero. Since a fax image is bi-level, Imager uses a threshold to
+decide if a given pixel is black or white, based on a single channel.
+For greyscale images channel 0 is used, for color images channel 1
+(green) is used. If you want more control over the conversion you can
+use $img->to_paletted() to product a bi-level image. This way you can
+use dithering:
+
+ my $bilevel = $img->to_paletted(make_colors => 'mono',
+ translate => 'errdiff',
+ errdiff => 'stucki');
+
+=over
+
+=item class
+
+If set to 'fax' the image will be written as a bi-level fax image.
+
+=item fax_fine
+
+By default when I<class> is set to 'fax' the image is written in fine
+mode, you can select normal mode by setting I<fax_fine> to 0.
+
+=back
+
+Imager should be able to read any TIFF image you supply. Paletted
+TIFF images are read as paletted Imager images, since paletted TIFF
+images have 16-bits/sample (48-bits/color) this means the bottom
+8-bits are lost, but this shouldn't be a big deal. Currently all
+direct color images are read at 8-bits/sample.
+
+TIFF supports the spatial resolution tags. See the
+C<tiff_resolutionunit> tag for some extra options.
+
+As of Imager 0.62 Imager reads:
+
+=over
+
+=item *
+
+16-bit grey, RGB, or CMYK image, including a possible alpha channel as
+a 16-bit/sample image.
+
+=item *
+
+32-bit grey, RGB image, including a possible alpha channel as a
+double/sample image.
+
+=item *
+
+bi-level images as paletted images containing only black and white,
+which other formats will also write as bi-level.
+
+=item *
+
+tiled paletted images are now handled correctly
+
+=back
+
+The following tags are set in a TIFF image when read, and can be set
+to control output:
+
+=over
+
+=item tiff_compression
+
+When reading an image this is set to the numeric value of the TIFF
+compression tag.
+
+On writing you can set this to either a numeric compression tag value,
+or one of the following values:
+
+ Ident Number Description
+ none 1 No compression
+ packbits 32773 Macintosh RLE
+ ccittrle 2 CCITT RLE
+ fax3 3 CCITT Group 3 fax encoding (T.4)
+ t4 3 As above
+ fax4 4 CCITT Group 4 fax encoding (T.6)
+ t6 4 As above
+ lzw 5 LZW
+ jpeg 7 JPEG
+ zip 8 Deflate (GZIP) Non-standard
+ deflate 8 As above.
+ oldzip 32946 Deflate with an older code.
+ ccittrlew 32771 Word aligned CCITT RLE
+
+In general a compression setting will be ignored where it doesn't make
+sense, eg. C<jpeg> will be ignored for compression if the image is
+being written as bilevel.
+
+Imager attempts to check that your build of libtiff supports the given
+compression, and will fallback to C<packbits> if it isn't enabled.
+eg. older distributions didn't include LZW compression, and JPEG
+compression is only available if libtiff is configured with libjpeg's
+location.
+
+ $im->write(file => 'foo.tif', tiff_compression => 'lzw')
+ or die $im->errstr;
+
+=item tiff_jpegquality
+
+If I<tiff_compression> if C<jpeg> then this can be a number from 1 to
+100 giving the JPEG compression quality. High values are better
+quality and larger files.
+
+=item tiff_resolutionunit
+
+The value of the ResolutionUnit tag. This is ignored on writing if
+the i_aspect_only tag is non-zero.
+
+The C<i_xres> and C<i_yres> tags are expressed in pixels per inch no
+matter the value of this tag, they will be converted to/from the value
+stored in the TIFF file.
+
+=item tiff_resolutionunit_name
+
+This is set when reading a TIFF file to the name of the unit given by
+C<tiff_resolutionunit>. Possible results include C<inch>,
+C<centimeter>, C<none> (the C<i_aspect_only> tag is also set reading
+these files) or C<unknown>.
+
+=item tiff_bitspersample
+
+Bits per sample from the image. This value is not used when writing
+an image, it is only set on a read image.
+
+=item tiff_photometric
+
+Value of the PhotometricInterpretation tag from the image. This value
+is not used when writing an image, it is only set on a read image.
+
+=item tiff_documentname
+
+=item tiff_imagedescription
+
+=item tiff_make
+
+=item tiff_model
+
+=item tiff_pagename
+
+=item tiff_software
+
+=item tiff_datetime
+
+=item tiff_artist
+
+=item tiff_hostcomputer
+
+Various strings describing the image. tiff_datetime must be formatted
+as "YYYY:MM:DD HH:MM:SS". These correspond directly to the mixed case
+names in the TIFF specification. These are set in images read from a
+TIFF and saved when writing a TIFF image.
+
+=back
+
+You can supply a C<page> parameter to the C<read()> method to read
+some page other than the first. The page is 0 based:
+
+ # read the second image in the file
+ $image->read(file=>"example.tif", page=>1)
+ or die "Cannot read second page: ",$image->errstr,"\n";
+
+Note: Imager uses the TIFF*RGBA* family of libtiff functions,
+unfortunately these don't support alpha channels on CMYK images. This
+will result in a full coverage alpha channel on CMYK images with an
+alpha channel, until this is implemented in libtiff (or Imager's TIFF
+implementation changes.)
+
+If you read an image with multiple alpha channels, then only the first
+alpha channel will be read.
+
+Currently Imager's TIFF support reads all direct color images as 8-bit
+RGB images, this may change in the future to reading 16-bit/sample
+images.
+
+Currently tags that control the output color type and compression are
+ignored when writing, this may change in the future. If you have
+processes that rely upon Imager always producing packbits compressed
+RGB images, you should strip any tags before writing.
+
+=head2 BMP (BitMaP)
+
+Imager can write 24-bit RGB, and 8, 4 and 1-bit per pixel paletted
+Windows BMP files. Currently you cannot write compressed BMP files
+with Imager.
+
+Imager can read 24-bit RGB, and 8, 4 and 1-bit perl pixel paletted
+Windows BMP files. There is some support for reading 16-bit per pixel
+images, but I haven't found any for testing.
+
+BMP has no support for multi-image files.
+
+BMP files support the spatial resolution tags, but since BMP has no
+support for storing only an aspect ratio, if C<i_aspect_only> is set
+when you write the C<i_xres> and C<i_yres> values are scaled so the
+smaller is 72 DPI.
+
+The following tags are set when you read an image from a BMP file:
+
+=over
+
+=item bmp_compression
+
+The type of compression, if any. This can be any of the following
+values:
+
+=over
+
+=item BI_RGB (0)
+
+Uncompressed.
+
+=item BI_RLE8 (1)
+
+8-bits/pixel paletted value RLE compression.
+
+=item BI_RLE4 (2)
+
+4-bits/pixel paletted value RLE compression.
+
+=item BI_BITFIELDS (3)
+
+Packed RGB values.
+
+=back
+
+=item bmp_compression_name
+
+The bmp_compression value as a BI_* string
+
+=item bmp_important_colors
+
+The number of important colors as defined by the writer of the image.
+
+=item bmp_used_colors
+
+Number of color used from the BMP header
+
+=item bmp_filesize
+
+The file size from the BMP header
+
+=item bmp_bit_count
+
+Number of bits stored per pixel. (24, 8, 4 or 1)
+
+=back
+
+=head2 TGA (TarGA)
+
+When storing targa images rle compression can be activated with the
+'compress' parameter, the 'idstring' parameter can be used to set the
+targa comment field and the 'wierdpack' option can be used to use the
+15 and 16 bit targa formats for rgb and rgba data. The 15 bit format
+has 5 of each red, green and blue. The 16 bit format in addition
+allows 1 bit of alpha. The most significant bits are used for each
+channel.
+
+
+Tags:
+
+=over
+
+=item tga_idstring
+
+=item tga_bitspp
+
+=item compressed
+
+=back
+
+=head2 RAW
+
+When reading raw images you need to supply the width and height of the
+image in the xsize and ysize options:
+
+ $img->read(file=>'foo.raw', xsize=>100, ysize=>100)
+ or die "Cannot read raw image\n";
+
+If your input file has more channels than you want, or (as is common),
+junk in the fourth channel, you can use the datachannels and
+storechannels options to control the number of channels in your input
+file and the resulting channels in your image. For example, if your
+input image uses 32-bits per pixel with red, green, blue and junk
+values for each pixel you could do:
+
+ $img->read(file=>'foo.raw', xsize=>100, ysize=>100, datachannels=>4,
+ storechannels=>3)
+ or die "Cannot read raw image\n";
+
+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
+scanline the channels would be laid out as:
+
+ 012012012012
+
+=item *
+
+1 - samples are line by line, so channel 0 for the entire scanline is
+followed by channel 1 for the entire scanline and so on. eg. for a
+four pixel scanline 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 hotspot. I've
+treated them separately so that you're not messing with tags to
+distinguish between them.
+
+The following tags are set when reading an icon image and are used
+when writing it:
+
+=over
+
+=item ico_mask
+
+This is the AND mask of the icon. When used as an icon in Windows 1
+bits in the mask correspond to pixels that are modified by the source
+image rather than simply replaced by the source image.
+
+Rather than requiring a binary bitmap this is accepted in a specific format:
+
+=over
+
+=item *
+
+first line consisting of the 0 placeholder, the 1 placeholder and a
+newline.
+
+=item *
+
+following lines which contain 0 and 1 placeholders for each scanline
+of the image, starting from the top of the image.
+
+=back
+
+When reading an image, '.' is used as the 0 placeholder and '*' as the
+1 placeholder. An example:
+
+ .*
+ ..........................******
+ ..........................******
+ ..........................******
+ ..........................******
+ ...........................*****
+ ............................****
+ ............................****
+ .............................***
+ .............................***
+ .............................***
+ .............................***
+ ..............................**
+ ..............................**
+ ...............................*
+ ...............................*
+ ................................
+ ................................
+ ................................
+ ................................
+ ................................
+ ................................
+ *...............................
+ **..............................
+ **..............................
+ ***.............................
+ ***.............................
+ ****............................
+ ****............................
+ *****...........................
+ *****...........................
+ *****...........................
+ *****...........................
+
+=back
+
+The following tags are set when reading an icon:
+
+=over
+
+=item ico_bits
+
+The number of bits per pixel used to store the image.
+
+=back
+
+For cursor files the following tags are set and read when reading and
+writing:
+
+=over
+
+=item cur_mask
+
+This is the same as the ico_mask above.
+
+=item cur_hotspotx
+
+=item cur_hotspoty
+
+The "hot" spot of the cursor image. This is the spot on the cursor
+that you click with. If you set these to out of range values they are
+clipped to the size of the image when written to the file.
+
+=back
+
+The following parameters can be supplied to read() or read_multi() to
+control reading of ICO/CUR files:
+
+=over
+
+=item *
+
+ico_masked - if true, the default, then the icon/cursors mask is
+applied as an alpha channel to the image. This may result in a
+paletted image being returned as a direct color image. Default: 1
+
+ # retrieve the image as stored, without using the mask as an alpha
+ # channel
+ $img->read(file => 'foo.ico', ico_masked => 0)
+ or die $img->errstr;
+
+This was introduced in Imager 0.60. Previously reading ICO images
+acted as if C<ico_masked =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');
+
+=head2 SGI (RGB, BW)
+
+SGI images, often called by the extensions, RGB or BW, can be stored
+either uncompressed or compressed using an RLE compression.
+
+By default, when saving to an extension of C<rgb>, C<bw>, C<sgi>,
+C<rgba> the file will be saved in SGI format. The file extension is
+otherwise ignored, so saving a 3-channel image to a C<.bw> file will
+result in a 3-channel image on disk.
+
+The following tags are set when reading a SGI image:
+
+=over
+
+=item *
+
+i_comment - the IMAGENAME field from the image. Also written to the
+file when writing.
+
+=item *
+
+sgi_pixmin, sgi_pixmax - the PIXMIN and PIXMAX fields from the image.
+On reading image data is expanded from this range to the full range of
+samples in the image.
+
+=item *
+
+sgi_bpc - the number of bytes per sample for the image. Ignored when
+writing.
+
+=item *
+
+sgi_rle - whether or not the image is compressed. If this is non-zero
+when writing the image will be compressed.
+
+=back
+
+=head1 ADDING NEW FORMATS
+
+To support a new format for reading, call the register_reader() class
+method:
+
+=over
+
+=item register_reader
+
+Registers single or multiple image read functions.
+
+Parameters:
+
+=over
+
+=item *
+
+type - the identifier of the file format, if Imager's
+i_test_format_probe() can identify the format then this value should
+match i_test_format_probe()'s result.
+
+This parameter is required.
+
+=item *
+
+single - a code ref to read a single image from a file. This is
+supplied:
+
+=over
+
+=item *
+
+the object that read() was called on,
+
+=item *
+
+an Imager::IO object that should be used to read the file, and
+
+=item *
+
+all the parameters supplied to the read() method.
+
+=back
+
+The single parameter is required.
+
+=item *
+
+multiple - a code ref which is called to read multiple images from a
+file. This is supplied:
+
+=over
+
+=item *
+
+an Imager::IO object that should be used to read the file, and
+
+=item *
+
+all the parameters supplied to the read_multi() method.
+
+=back
+
+=back
+
+Example:
+
+ # from Imager::File::ICO
+ Imager->register_reader
+ (
+ type=>'ico',
+ single =>
+ sub {
+ my ($im, $io, %hsh) = @_;
+ $im->{IMG} = i_readico_single($io, $hsh{page} || 0);
+
+ unless ($im->{IMG}) {
+ $im->_set_error(Imager->_error_as_msg);
+ return;
+ }
+ return $im;
+ },
+ multiple =>
+ sub {
+ my ($io, %hsh) = @_;
+
+ my @imgs = i_readico_multi($io);
+ unless (@imgs) {
+ Imager->_set_error(Imager->_error_as_msg);
+ return;
+ }
+ return map {
+ bless { IMG => $_, DEBUG => $Imager::DEBUG, ERRSTR => undef }, 'Imager'
+ } @imgs;
+ },
+ );
+
+=item register_writer
+
+Registers single or multiple image write functions.
+
+Parameters:
+
+=over
+
+=item *
+
+type - the identifier of the file format. This is typically the
+extension in lowercase.
+
+This parameter is required.
+
+=item *
+
+single - a code ref to write a single image to a file. This is
+supplied:
+
+=over
+
+=item *
+
+the object that write() was called on,
+
+=item *
+
+an Imager::IO object that should be used to write the file, and
+
+=item *
+
+all the parameters supplied to the write() method.
+
+=back
+
+The single parameter is required.
+
+=item *
+
+multiple - a code ref which is called to write multiple images to a
+file. This is supplied:
+
+=over
+
+=item *
+
+the class name write_multi() was called on, this is typically
+C<Imager>.
+
+=item *
+
+an Imager::IO object that should be used to write the file, and
+
+=item *
+
+all the parameters supplied to the read_multi() method.
+
+=back
+
+=back
+
+=back
+
+If you name the reader module C<Imager::File::>I<your-format-name>
+where I<your-format-name> is a fully upper case version of the type
+value you would pass to read(), read_multi(), write() or write_multi()
+then Imager will attempt to load that module if it has no other way to
+read or write that format.
+
+For example, if you create a module Imager::File::GIF and the user has
+built Imager without it's normal GIF support then an attempt to read a
+GIF image will attempt to load Imager::File::GIF.
+
+If your module can only handle reading then you can name your module
+C<Imager::File::>I<your-format-name>C<Reader> and Imager will attempt
+to autoload it.
+
+If your module can only handle writing then you can name your module
+C<Imager::File::>I<your-format-name>C<Writer> and Imager will attempt
+to autoload it.
+
+=head1 EXAMPLES
+
+=head2 Producing an image from a CGI script
+
+Once you have an image the basic mechanism is:
+
+=over
+
+=item 1.
+
+set STDOUT to autoflush
+
+=item 2.
+
+output a content-type header, and optionally a content-length header
+
+=item 3.
+
+put STDOUT into binmode
+
+=item 4.
+
+call write() with the C<fd> or C<fh> parameter. You will need to
+provide the C<type> parameter since Imager can't use the extension to
+guess the file format you want.
+
+=back
+
+ # write an image from a CGI script
+ # using CGI.pm
+ use CGI qw(:standard);
+ $| = 1;
+ binmode STDOUT;
+ print header(-type=>'image/gif');
+ $img->write(type=>'gif', fd=>fileno(STDOUT))
+ or die $img->errstr;
+
+If you want to send a content length you can send the output to a
+scalar to get the length:
+
+ my $data;
+ $img->write(type=>'gif', data=>\$data)
+ or die $img->errstr;
+ binmode STDOUT;
+ print header(-type=>'image/gif', -content_length=>length($data));
+ print $data;
+
+=head2 Writing an animated GIF
+
+The basic idea is simple, just use write_multi():
+
+ my @imgs = ...;
+ Imager->write_multi({ file=>$filename, type=>'gif' }, @imgs);
+
+If your images are RGB images the default quantization mechanism will
+produce a very good result, but can take a long time to execute. You
+could either use the standard webmap:
+
+ Imager->write_multi({ file=>$filename,
+ type=>'gif',
+ make_colors=>'webmap' },
+ @imgs);
+
+or use a median cut algorithm to built a fairly optimal color map:
+
+ Imager->write_multi({ file=>$filename,
+ type=>'gif',
+ make_colors=>'mediancut' },
+ @imgs);
+
+By default all of the images will use the same global colormap, which
+will produce a smaller image. If your images have significant color
+differences, you may want to generate a new palette for each image:
+
+ Imager->write_multi({ file=>$filename,
+ type=>'gif',
+ make_colors=>'mediancut',
+ gif_local_map => 1 },
+ @imgs);
+
+which will set the C<gif_local_map> tag in each image to 1.
+Alternatively, if you know only some images have different colors, you
+can set the tag just for those images:
+
+ $imgs[2]->settag(name=>'gif_local_map', value=>1);
+ $imgs[4]->settag(name=>'gif_local_map', value=>1);
+
+and call write_multi() without a C<gif_local_map> parameter, or supply
+an arrayref of values for the tag:
+
+ Imager->write_multi({ file=>$filename,
+ type=>'gif',
+ make_colors=>'mediancut',
+ gif_local_map => [ 0, 0, 1, 0, 1 ] },
+ @imgs);
+
+Other useful parameters include C<gif_delay> to control the delay
+between frames and C<transp> to control transparency.
+
+=head2 Reading tags after reading an image
+
+This is pretty simple:
+
+ # print the author of a TIFF, if any
+ my $img = Imager->new;
+ $img->read(file=>$filename, type='tiff') or die $img->errstr;
+ my $author = $img->tags(name=>'tiff_author');
+ if (defined $author) {
+ print "Author: $author\n";
+ }
+
+=head1 BUGS
+
+When saving Gif images the program does NOT try to shave of extra
+colors if it is possible. If you specify 128 colors and there are
+only 2 colors used - it will have a 128 colortable anyway.
+
+=head1 SEE ALSO
+
+Imager(3)
+
+=cut