X-Git-Url: http://git.imager.perl.org/imager.git/blobdiff_plain/2b405c9e0e655ef3c1a219f53195da7ddb6eadbc..d1d8320e239118f4f19e7b53cb1cb540a561fa45:/lib/Imager/Files.pod
diff --git a/lib/Imager/Files.pod b/lib/Imager/Files.pod
index bf641924..1b893a1d 100644
--- a/lib/Imager/Files.pod
+++ b/lib/Imager/Files.pod
@@ -4,14 +4,24 @@ 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;
@@ -20,6 +30,31 @@ Imager::Files - working with image files
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
@@ -33,11 +68,12 @@ code snippet is sufficient:
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
+or L methods useful.
=over
-=item read
+=item read()
Reading writing to and from files is simple, use the C
method to read an image:
@@ -46,14 +82,32 @@ method to read an image:
$img->read(file=>$filename, type=>$type)
or die "Cannot read $filename: ", $img->errstr;
-=item write
+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 parameter. If this
+is non-zero then read() can return true on an incomplete image and set
+the C 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 method to write an image:
$img->write(file=>$filename, type=>$type)
or die "Cannot write $filename: ", $img->errstr;
-=item read_multi
+=item read_multi()
If you're reading from a format that supports multiple images per
file, use the C method:
@@ -61,7 +115,10 @@ file, use the C method:
my @imgs = Imager->read_multi(file=>$filename, type=>$type)
or die "Cannot read $filename: ", Imager->errstr;
-=item write_multi
+As with the read() method, Imager will normally detect the C
+automatically.
+
+=item write_multi()
and if you want to write multiple images to a single file use the
C method:
@@ -69,12 +126,40 @@ C 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 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 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
-If the I includes an extension that Imager recognizes, then
-you don't need the I, but you may want to provide one anyway.
-See L for information on controlling this
-recognition.
+When writing, if the C includes an extension that Imager
+recognizes, then you don't need the C, but you may want to
+provide one anyway. See L for information on
+controlling this recognition.
The C parameter is a lowercase representation of the file type,
and can be any of the following:
@@ -85,7 +170,7 @@ and can be any of the following:
png Portable Network Graphics (PNG)
pnm Portable aNyMap (PNM)
raw Raw
- rgb SGI .rgb files
+ sgi SGI .rgb files
tga TARGA
tiff Tagged Image File Format (TIFF)
@@ -102,15 +187,26 @@ targets:
=over
-=item file
+=item *
+
+C - The C 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.
+
+ # 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 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.
+ my $image = Imager->new;
+ $image->read(file => 'example.tif')
+ or die $image->errstr;
-=item fh
+=item *
-C is a file handle, typically either returned from
+C - C is a file handle, typically either returned from
C<new()>>, or a glob from an C call. You should call
C on the handle before passing it to Imager.
@@ -118,9 +214,16 @@ 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.
-=item fd
+ $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 is a file descriptor. You can get this by calling the
+C - C is a file descriptor. You can get this by calling the
C function on a file handle, or by using one of the standard
file descriptor numbers.
@@ -128,64 +231,204 @@ If you get this from a perl file handle, you may need to flush any
buffered output, otherwise it may appear in the output stream after
the image.
-=item data
+ $image->write(fd => file(STDOUT), type => 'gif')
+ or die $image->errstr;
+
+=item *
+
+C - When reading data, C is a scalar containing the image
+file data, or a reference to such a scalar. When writing, C is
+a reference to the scalar to save the image file data to.
-When reading data, C is a scalar containing the image file data,
-when writing, C 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;
+
+ # from Imager 0.99
+ my @images = Imager->read_multi(data => \$data)
+ or die Imager->errstr;
+
+=item *
+
+C, C, C, C, C - Imager
+will make calls back to your supplied coderefs to read, write and seek
+from/to/through the image file. See L below for details.
+
+=item *
+
+C - an L object.
+
+=back
-=item callback
+XXBy default Imager will use buffered I/O when
+reading or writing an image. You can disabled buffering for output by
+supplying a C<< buffered => 0 >> parameter to C or
+C.
-Imager will make calls back to your supplied coderefs to read, write
-and seek from/to/through the image file.
+=head2 I/O Callbacks
When reading from a file you can use either C or C
to supply the read callback, and when writing C or
C to supply the write callback.
-When writing you can also supply the C 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.
+Whether reading or writing a C image, C and C
+are required.
+
+If a file handler attempts to use C, C or C
+and you haven't supplied one, the call will fail, failing the image
+read or write, returning an error message indicating that the callback
+is missing:
+
+ # attempting to read a TIFF image without a seekcb
+ open my $fh, "<", $filename or die;
+ my $rcb = sub {
+ my $val;
+ read($fh, $val, $_[0]) or return "";
+ return $val;
+ };
+ my $im = Imager->new(callback => $rcb)
+ or die Imager->errstr
+ # dies with (wrapped here):
+ # Error opening file: (Iolayer): Failed to read directory at offset 0:
+ # (Iolayer): Seek error accessing TIFF directory: seek callback called
+ # but no seekcb supplied
+
+You can also provide a C parameter called when writing the
+file is complete. If no C is supplied the default will
+succeed silently.
+
+ # contrived
+ my $data;
+ sub mywrite {
+ $data .= unpack("H*", shift);
+ 1;
+ }
+ Imager->write_multi({ callback => \&mywrite, type => 'gif'}, @images)
+ or die Imager->errstr;
+
+=head3 C
-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.
+The read callback is called with 2 parameters:
+
+=over
+
+=item *
+
+C - the minimum amount of data required.
+
+=item *
+
+C - previously this was the maximum amount of data returnable
+- currently it's always the same as C
+
+=back
+
+Your read callback should return the data as a scalar:
+
+=over
+
+=item *
+
+on success, a string containing the bytes read.
+
+=item *
+
+on end of file, an empty string
+
+=item *
+
+on error, C.
+
+=back
+
+If your return value contains more data than C Imager will
+panic.
+
+Your return value must not contain any characters over C<\xFF> or
+Imager will panic.
+
+=head3 C
Your write callback takes exactly one parameter, a scalar containing
-the data to be written. Return true for success.
+the data to be written.
+
+Return true for success.
+
+=head3 C
The seek callback takes 2 parameters, a I, and a I,
defined in the same way as perl's seek function.
+Previously you always needed a C callback if you called
+Imager's L or L without a C parameter,
+but this is no longer necessary unless the file handler requires
+seeking, such as for TIFF files.
+
+Returns the new position in the file, or -1 on failure.
+
+=head3 C
+
You can also supply a C which is called with no parameters
when there is no more data to be written. This could be used to flush
buffered data.
-=back
+Return true on success.
=head2 Guessing types
+X
+
+When writing to a file, if you don't supply a C 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 parameter,
+or if read() or read_multi() can't determine the type from the file's
+header.
+
+The default function value of C<$Imager::FORMATGUESS> is
+C<\&Imager::def_guess_type>.
-Imager uses the code reference in $Imager::FORMATGUESS to guess the
-file type when you don't supply a C. The code reference is
-called with a single parameter, the filename of the file. The code
-reference is only called if a C parameter is supplied to the
-file access method.
+=over
+
+=item def_guess_type()
+X
-Return either a valid Imager file type, or undef.
+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, C, C, C, C, C, C (Photoshop), C, Utah
+C.
+
+=back
+
=head2 Limiting the sizes of images you read
=over
-=item set_file_limits
+=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
@@ -218,12 +461,15 @@ To set the limits, call the class method set_file_limits:
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.
+Any limit of zero for width or height is treated as unlimited.
+
+A limit of zero for bytes is treated as one gigabyte, but higher bytes
+limits can be set explicitly.
-By default, all of the limits are zero, or unlimited.
+By default, the width and height limits are zero, or unlimited. The
+default memory size limit is one gigabyte.
-You can reset all of the limited to their defaults by passing in the
-reset parameter as a true value:
+You can reset all limits to their defaults with the reset parameter:
# no limits
Imager->set_file_limits(reset=>1);
@@ -237,13 +483,44 @@ pass:
# only bytes is limited
Imager->set_file_limits(reset=>1, bytes=>10_000_000);
-=item get_file_limits
+=item get_file_limits()
You can get the current limits with the get_file_limits() method:
my ($max_width, $max_height, $max_bytes) =
Imager->get_file_limits();
+=item check_file_limits()
+XX
+
+Intended for use by file handlers to check that the size of a file is
+within the limits set by C.
+
+Parameters:
+
+=over
+
+=item *
+
+C, C - the width and height of the image in pixels.
+Must be a positive integer. Required.
+
+=item *
+
+C - the number of channels in the image, including the alpha
+channel if any. Must be a positive integer between 1 and 4
+inclusive. Default: 3.
+
+=item *
+
+C - the number of bytes stored per sample. Must be a
+positive integer or C<"float">. Note that this should be the sample
+size of the Imager image you will be creating, not the sample size in
+the source, eg. if the source has 32-bit samples this should be
+C<"float"> since Imager doesn't have 32-bit/sample images.
+
+=back
+
=back
=head1 TYPE SPECIFIC INFORMATION
@@ -268,31 +545,70 @@ the C option set to false:
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 (Portable Gray Map) and C (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 (Portable BitMap), C and C 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 *
+
+XC - the C number from the PGM/PPM header.
+Always set to 2 for a C file.
+
+=item *
+
+XC - the type number from the C header, 1 for ASCII
+C files, 2 for ASCII C files, 3 for ASCII c files, 4 for binary
+C files, 5 for binary C files, 6 for binary C files.
+
+=back
+
+The following tag is checked when writing an image with more than
+8-bits/sample:
+
+=over
+
+=item *
+
+Xpnm_write_wide_data - if this is non-zero then
+write() can write C/C 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 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.
+You can supply a C parameter ranging from 0 (worst
+quality) to 100 (best quality) when writing a JPEG file, which
+defaults to 75.
$img->write(file=>'foo.jpg', jpegquality=>90) or die $img->errstr;
-Imager will read a grayscale JPEG as a 1 channel image and a color
+If you write an image with an alpha channel to a JPEG file then it
+will be composed against the background set by the C
+parameter (or tag), or black if not supplied.
+
+Imager will read a gray scale JPEG as a 1 channel image and a color
JPEG as a 3 channel image.
$img->read(file=>'foo.jpg') or die $img->errstr;
@@ -302,34 +618,54 @@ to control output:
=over
-=item jpeg_density_unit
+=item *
-The value of the density unit field in the JFIF header. This is
-ignored on writing if the i_aspect_only tag is non-zero.
+C - The value of the density unit field in the
+C header. This is ignored on writing if the C
+tag is non-zero.
The C and C 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
+=item *
-This is set when reading a JPEG file to the name of the unit given by
-C. Possible results include C,
-C, C (the C tag is also set reading
-these files). If the value of jpeg_density_unit is unknown then this
-tag isn't set.
+C - This is set when reading a JPEG file to
+the name of the unit given by C. Possible results
+include C, C, C (the C tag is
+also set reading these files). If the value of C
+is unknown then this tag isn't set.
+
+=item *
+
+C - Text comment.
-=item jpeg_comment
+=item *
-Text comment.
+C - Whether the JPEG file is a progressive
+file. (Imager 0.84)
=back
JPEG supports the spatial resolution tags C, C and
C.
-If an APP1 block containing EXIF information is found, then any of the
-following tags can be set:
+You can also set the following tags when writing to an image, they are
+not set in the image when reading:
+
+=over
+
+C - set to a non-zero integer to compute optimal
+Huffman coding tables for the image. This will increase memory usage
+and processing time (about 12% in my simple tests) but can
+significantly reduce file size without a loss of quality.
+
+=back
+
+=for stopwords EXIF
+
+If an C block containing EXIF information is found, then any of the
+following tags can be set when reading a JPEG image:
=over
@@ -354,7 +690,7 @@ exif_version exif_white_balance exif_x_resolution exif_y_resolution
=back
-The following derived tags can also be set:
+The following derived tags can also be set when reading a JPEG image:
=over
@@ -375,7 +711,38 @@ specification for that value appears in the derived field. So for
example if C is C<5> then
C is set to C.
-=head2 GIF (Graphics Interchange Format)
+eg.
+
+ my $image = Imager->new;
+ $image->read(file => 'exiftest.jpg')
+ or die "Cannot load image: ", $image->errstr;
+ print $image->tags(name => "exif_image_description"), "\n";
+ print $image->tags(name => "exif_exposure_mode"), "\n";
+ print $image->tags(name => "exif_exposure_mode_name"), "\n";
+
+ # for the exiftest.jpg in the Imager distribution the output would be:
+ Imager Development Notes
+ 0
+ Auto exposure
+
+Imager will not write EXIF tags to any type of image, if you need more
+advanced EXIF handling, consider L.
+
+=for stopwords IPTC
+
+=over
+
+=item parseiptc()
+
+Historically, Imager saves IPTC data when reading a JPEG image, the
+parseiptc() method returns a list of key/value pairs resulting from a
+simple decoding of that data.
+
+Any future IPTC data decoding is likely to go into tags.
+
+=back
+
+=head2 GIF
When writing one of more GIF images you can use the same
L as you can when converting
@@ -400,132 +767,138 @@ use most of them when writing to GIF:
=over
-=item gif_left
+=item *
-the offset of the image from the left of the "screen" ("Image Left
-Position")
+gif_left - the offset of the image from the left of the "screen"
+("Image Left Position")
-=item gif_top
+=item *
-the offset of the image from the top of the "screen" ("Image Top Position")
+gif_top - the offset of the image from the top of the "screen" ("Image
+Top Position")
-=item gif_interlace
+=item *
-non-zero if the image was interlaced ("Interlace Flag")
+gif_interlace - non-zero if the image was interlaced ("Interlace
+Flag")
-=item gif_screen_width
+=item *
-=item gif_screen_height
+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").
-the size of the logical screen. When writing this is used as the
-minimum. If any image being written would extend beyond this the
-screen size is extended. ("Logical Screen Width", "Logical Screen
-Height").
+=item *
-When writing this is used as a minimum, if the combination of the
-image size and the image's C and C is beyond this
-size then the screen size will be expanded.
+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_local_map
+=item *
-Non-zero if this image had a local color map. If set for an image
-when writing the image is quantized separately from the other images
-in the file.
+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 tag to 0.
-=item gif_background
+=item *
-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 tag to 0.
+gif_trans_index - The index of the color in the color map used for
+transparency. If the image has a transparency then it is returned as
+a 4 channel image with the alpha set to zero in this palette entry.
+This value is not used when writing. ("Transparent Color Index")
-=item gif_trans_index
+=item *
-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")
+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 option (see
+L) for this value to be
+used.
-=item gif_trans_color
+=item *
-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) for this
-value to be used.
+gif_delay - The delay until the next frame is displayed, in 1/100 of a
+second. ("Delay Time").
-=item gif_delay
+=item *
-The delay until the next frame is displayed, in 1/100 of a second.
-("Delay Time").
+gif_user_input - whether or not a user input is expected before
+continuing (view dependent) ("User Input Flag").
-=item gif_user_input
+=item *
-whether or not a user input is expected before continuing (view dependent)
-("User Input Flag").
+gif_disposal - how the next frame is displayed ("Disposal Method")
-=item gif_disposal
+=item *
-how the next frame is displayed ("Disposal Method")
+gif_loop - the number of loops from the Netscape Loop extension. This
+may be zero to loop forever.
-=item gif_loop
+=item *
-the number of loops from the Netscape Loop extension. This may be zero.
+gif_comment - the first block of the first GIF comment before each
+image.
-=item gif_comment
+=item *
-the first block of the first gif comment before each image.
+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_eliminate_unused
+=item *
-If this is true, when you write a paletted image any unused colors
-will be eliminated from its palette. This is set by default.
+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
standard.
-The following gif writing options are obsolete, you should set the
+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
+=item *
-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.
+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 in new code.
-=item interlace
+=item *
-The images are written interlaced if this is non-zero.
+interlace - The images are written interlaced if this is non-zero.
Use C in new code.
-=item gif_delays
+=item *
-A reference to an array containing the delays between images, in 1/100
-seconds.
+gif_delays - A reference to an array containing the delays between
+images, in 1/100 seconds.
Use C in new code.
-=item gif_positions
+=item *
-A reference to an array of references to arrays which represent screen
-positions for each image.
+gif_positions - A reference to an array of references to arrays which
+represent screen positions for each image.
New code should use the C and C tags.
-=item gif_loop_count
+=item *
-If this is non-zero the Netscape loop extension block is generated,
-which makes the animation of the images repeat.
+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.
+This is currently unimplemented due to some limitations in C.
=back
@@ -536,115 +909,222 @@ some page other than the first. The page is 0 based:
$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
+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 behaviour by calling read with the
+You can return to the previous behavior by calling read with the
C 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.
+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
parameter set to C. By default the image is written in fine
mode, but this can be overridden by setting the I 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
+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(colors=>[ NC(0,0,0), NC(255,255,255) ],
- make_colors => 'none',
+ my $bilevel = $img->to_paletted(make_colors => 'mono',
translate => 'errdiff',
errdiff => 'stucki');
=over
-=item class
+=item *
-If set to 'fax' the image will be written as a bi-level fax image.
+C - If set to 'fax' the image will be written as a bi-level fax
+image.
-=item fax_fine
+=item *
-By default when I is set to 'fax' the image is written in fine
-mode, you can select normal mode by setting I to 0.
+C - By default when C is set to 'fax' the image is
+written in fine mode, you can select normal mode by setting
+C 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.
+8-bits are lost, but this shouldn't be a big deal.
TIFF supports the spatial resolution tags. See the
C 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'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 tiff_resolutionunit
+=item *
+
+C - 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 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 supports the
+given compression, and will fallback to C if it isn't
+enabled. eg. older distributions didn't include LZW compression, and
+JPEG compression is only available if C is configured with
+C's location.
+
+ $im->write(file => 'foo.tif', tiff_compression => 'lzw')
+ or die $im->errstr;
+
+=item *
+
+CC - If C
+is C then this can be a number from 1 to 100 giving the JPEG
+compression quality. High values are better quality and larger files.
+
+=item *
-The value of the ResolutionUnit tag. This is ignored on writing if
-the i_aspect_only tag is non-zero.
+XC - The value of the
+C tag. This is ignored on writing if the
+i_aspect_only tag is non-zero.
The C and C 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
+=item *
-This is set when reading a TIFF file to the name of the unit given by
+XC - This is
+set when reading a TIFF file to the name of the unit given by
C. Possible results include C,
C, C (the C tag is also set reading
these files) or C.
-=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 *
-=item tiff_pagename
+XC - 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_software
+=item *
-=item tiff_datetime
+XC - Value of the
+C tag from the image. This value is not
+used when writing an image, it is only set on a read image.
-=item tiff_artist
+=item *
-=item tiff_hostcomputer
+C, C, C,
+C, C, C, C,
+C, C - Various strings describing the
+image. C 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.
-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 parameter to the C method to read
some page other than the first. The page is 0 based:
@@ -653,9 +1133,19 @@ some page other than the first. The page is 0 based:
$image->read(file=>"example.tif", page=>1)
or die "Cannot read second page: ",$image->errstr,"\n";
-=back
+If you read an image with multiple alpha channels, then only the first
+alpha channel will be read.
+
+When reading a C image with callbacks, the C callback
+parameter is also required.
+
+When writing a C image with callbacks, the C and
+C parameters are also required.
-=head2 BMP (BitMaP)
+C is a random access file format, it cannot be read from or
+written to unseekable streams such as pipes or sockets.
+
+=head2 BMP (Windows Bitmap)
Imager can write 24-bit RGB, and 8, 4 and 1-bit per pixel paletted
Windows BMP files. Currently you cannot write compressed BMP files
@@ -665,7 +1155,7 @@ 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 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 is set
@@ -681,6 +1171,8 @@ The following tags are set when you read an image from a BMP file:
The type of compression, if any. This can be any of the following
values:
+=for stopwords RLE
+
=over
=item BI_RGB (0)
@@ -723,17 +1215,18 @@ Number of bits stored per pixel. (24, 8, 4 or 1)
=back
-=head2 TGA (TarGA)
+=for stopwords Targa
+
+=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
+When storing Targa images RLE compression can be activated with the
+C parameter, the C parameter can be used to set the
+Targa comment field and the C 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
@@ -749,39 +1242,278 @@ Tags:
=head2 RAW
When reading raw images you need to supply the width and height of the
-image in the xsize and ysize options:
+image in the C and C 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
+junk in the fourth channel, you can use the C and
+C 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)
+ $img->read(file=>'foo.raw', xsize => 100, ysize => 100,
+ raw_datachannels => 4, raw_storechannels => 3,
+ raw_interleave => 0)
or die "Cannot read raw image\n";
-Normally the raw image is expected to have the value for channel 1
-immediately following channel 0 and channel 2 immediately following
-channel 1 for each pixel. If your input image has all the channel 0
-values for the first line of the image, followed by all the channel 1
-values for the first line and so on, you can use the interleave option:
+In general, if you supply C you should also supply
+C
+
+Read parameters:
+
+=over
+
+=item *
+
+C - controls the ordering of samples within the image.
+Default: 1. Alternatively and historically spelled C.
+Possible values:
- $img->read(file=>'foo.raw', xsize=100, ysize=>100, interleave=>1)
+=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 for read
+has been 1, while writing only supports the C = 0
+format.
+
+For future compatibility, you should always supply the
+C (or C) parameter. As of 0.68, Imager
+will warn if you attempt to read a raw image without a
+C parameter.
+
+=item *
+
+C - the number of channels to store in the image.
+Range: 1 to 4. Default: 3. Alternatively and historically spelled
+C.
+
+=item *
+
+C - the number of channels to read from the file.
+Range: 1 or more. Default: 3. Alternatively and historically spelled
+C.
+
+=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.
+=head3 PNG Image modes
+
+PNG files can be read and written in the following modes:
+
+=over
+
+=item *
+
+bi-level - written as a 1-bit per sample gray scale image
+
+=item *
+
+paletted - Imager gray scale paletted images are written as RGB
+paletted images. PNG palettes can include alpha values for each entry
+and this is honored as an Imager four channel paletted image.
+
+=item *
+
+8 and 16-bit per sample gray scale, optionally with an alpha channel.
+
+=item *
+
+8 and 16-bit per sample RGB, optionally with an alpha channel.
+
+=back
+
+Unlike GIF, there is no automatic conversion to a paletted image,
+since PNG supports direct color.
+
+=head3 PNG Text tags
+
+Text tags are retrieved from and written to PNG C or C
+chunks. The following standard tags from the PNG specification are
+directly supported:
+
+=over
+
+=item *
+
+CX - keyword of "Comment".
+
+=item *
+
+CX - keyword "Author".
+
+=item *
+
+CX - keyword "Copyright".
+
+=item *
+
+CX - keyword "Creation Time".
+
+=item *
+
+CX - keyword "Description".
+
+=item *
+
+CX - keyword "Disclaimer".
+
+=item *
+
+CX - keyword "Software".
+
+=item *
+
+CX - keyword "Title".
+
+=item *
+
+CX - keyword "Warning".
+
+=back
+
+Each of these tags has a corresponding C<< I_compressed
+>> tag, eg. C. When reading, if the PNG chunk
+is compressed this tag will be set to 1, but is otherwise unset. When
+writing, Imager will honor the compression tag if set and non-zero,
+otherwise the chunk text will be compressed if the value is longer
+than 1000 characters, as recommended by the C documentation.
+
+PNG C or C chunks outside of those above are read into or
+written from Imager tags named like:
+
+=over
+
+=item *
+
+C<< png_textI_key >> - the key for the text chunk. This can be 1
+to 79 characters, may not contain any leading, trailing or consecutive
+spaces, and may contain only Latin-1 characters from 32-126, 161-255.
+
+=item *
+
+C<< png_textI_text >> - the text for the text chunk. This may not
+contain any C characters.
+
+=item *
+
+C<< png_textI_compressed >> - whether or not the text chunk is
+compressed. This behaves similarly to the C<<
+I_compressed >> tags described above.
+
+=back
+
+Where I starts from 0. When writing both the C<..._key> and
+C<..._text> tags must be present or the write will fail. If the key
+or text do not satisfy the requirements above the write will fail.
+
+=head3 Other PNG metadata tags
+
+=over
+
+=item *
+
+XC, C - only
+set when reading, C is set to the type of interlacing
+used by the file, 0 for one, 1 for Adam7. C is
+set to a keyword describing the interlacing, either C or
+C.
+
+=item *
+
+XC - the sRGB rendering intent
+for the image. an integer from 0 to 3, per the PNG specification. If
+this chunk is found in the PNG file the C and C are
+ignored and the C and C tags are not set.
+Similarly when writing if C is set the C and
+C chunks are not written.
+
+=item *
+
+XC - the gamma of the image. This value is
+not currently used by Imager when processing the image, but this may
+change in the future.
+
+=item *
+
+XC, C,
+C, C, C,
+C, C, C -
+the primary chromaticities of the image, defining the color model.
+This is currently not used by Imager when processing the image, but
+this may change in the future.
+
+=item *
+
+C, C, C - processed per
+I.
+
+=item *
+
+XC - the number of bits per sample in the
+representation. Ignored when writing.
+
+=item *
+
+XC - the creation time of the file formatted
+as C<< I-I-ITI:I:I >>. This
+is stored as time data structure in the file, not a string. If you
+set C and it cannot be parsed as above, writing the PNG file
+will fail.
+
+=item *
+
+C - set from the C when reading an image file.
+
+=back
+
+XXYou can control the level of
+F compression used when writing with the
+C parameter. This can be an integer between 0
+(uncompressed) and 9 (best compression).
+
+=for stopwords
+CRC
+
+XIf you're using F 1.6 or later, or
+an earlier release configured with C