=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;
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
or die "Cannot read $filename: ", $img->errstr;
In most cases Imager can auto-detect the file type, so you can just
-supply the filename:
+supply the file name:
$img->read(file => $filename)
or die "Cannot read $filename: ", $img->errstr;
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:
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
+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.
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)
=item *
-file - The C<file> parameter is the name of the image file to be
+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>.
$image->read(file => 'example.tif')
or die $image->errstr;
-=item
+=item *
-fh - 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.
$image->read(fd => $cgi->param('file'))
or die $image->errstr;
-=item
+=item *
-fd - C<fd> is a file descriptor. You can get this by calling the
+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.
$image->write(fd => file(STDOUT), type => 'gif')
or die $image->errstr;
-=item
+=item *
-data - When reading data, C<data> is a scalar containing the image
+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 giflib 4 or
-higher, and you may need to patch giflib to use this option for
+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.
my $data;
=item *
-callback - Imager will make calls back to your supplied coderefs to
+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>
=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
+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.
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
+Accepts a single parameter, the file name and returns the type or
undef.
=back
identifying information. The current implementation attempts to
detect the following image types beyond those supported by Imager:
+=for stopwords Photoshop
+
=over
-xpm, mng, jng, SGI RGB, ilbm, pcx, fits, psd (Photoshop), eps, Utah
-RLE
+C<xpm>, C<mng>, C<jng>, C<ilbm>, C<pcx>, C<fits>, C<psd> (Photoshop), C<eps>, Utah
+C<RLE>.
=back
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;
=item *
-X<pnm_maxval>pnm_maxval - the maxvals number from the PGM/PPM header.
-Always set to 2 for a PBM file.
+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>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.
+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
=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
+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.
=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;
=over
-=item jpeg_density_unit
+=item C<jpeg_density_unit>
-The value of the density unit field in the JFIF header. This is
+The value of the density unit field in the C<JFIF> header. This is
ignored on writing if the C<i_aspect_only> tag is non-zero.
The C<i_xres> and C<i_yres> tags are expressed in pixels per inch no
matter the value of this tag, they will be converted to/from the value
stored in the JPEG file.
-=item jpeg_density_unit_name
+=item C<jpeg_density_unit_name>
This is set when reading a JPEG file to the name of the unit given by
C<jpeg_density_unit>. Possible results include C<inch>,
C<centimeter>, C<none> (the C<i_aspect_only> tag is also set reading
-these files). If the value of jpeg_density_unit is unknown then this
-tag isn't set.
+these files). If the value of C<jpeg_density_unit> is unknown then
+this tag isn't set.
-=item jpeg_comment
+=item C<jpeg_comment>
Text comment.
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:
+=for stopwords EXIF
+
+If an C<APP1> block containing EXIF information is found, then any of the
+following tags can be set when reading a JPEG image:
=over
=back
-The following derived tags can also be set:
+The following derived tags can also be set when reading a JPEG image:
=over
0
Auto exposure
+Imager will not write EXIF tags to any type of image, if you need more
+advanced EXIF handling, consider L<Image::ExifTool>.
+
+=for stopwords IPTC
+
=over
-=item parseiptc
+=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
=item *
-gif_background - The index in the global colormap of the logical
+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 colormap. You can set this on write too, but for it to
+the global color map. You can set this on write too, but for it to
choose the color you want, you will need to supply only paletted
images and set the C<gif_eliminate_unused> tag to 0.
=item *
-gif_trans_index - The index of the color in the colormap used for
+gif_trans_index - The index of the color in the color map used for
transparency. If the image has a transparency then it is returned as
a 4 channel image with the alpha set to zero in this palette entry.
This value is not used when writing. ("Transparent Color Index")
=item *
gif_trans_color - A reference to an Imager::Color object, which is the
-colour to use for the palette entry used to represent transparency in
-the palette. You need to set the transp option (see L<Quantization
+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.
=item *
=item *
-gif_comment - the first block of the first gif comment before each
+gif_comment - the first block of the first GIF comment before each
image.
=item *
=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
+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.
=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.
+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.
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<giflib>.
=back
$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<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.
+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 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<class> - If set to 'fax' the image will be written as a bi-level fax
+image.
-=item fax_fine
+=item *
-By default when I<class> is set to 'fax' the image is written in fine
-mode, you can select normal mode by setting I<fax_fine> to 0.
+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. 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<tiff_resolutionunit> tag for some extra options.
-The following tags are set in a TIFF image when read, and can be set
-to control output:
+As of Imager 0.62 Imager reads:
=over
-=item tiff_resolutionunit
+=item *
-The value of the ResolutionUnit tag. This is ignored on writing if
-the i_aspect_only tag is non-zero.
+8-bit/sample gray, RGB or CMYK images, including a possible alpha
+channel as an 8-bit/sample image.
-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 *
-=item tiff_resolutionunit_name
+16-bit gray, RGB, or CMYK image, including a possible alpha channel as
+a 16-bit/sample image.
-This is set when reading a TIFF file to the name of the unit given by
-C<tiff_resolutionunit>. Possible results include C<inch>,
-C<centimeter>, C<none> (the C<i_aspect_only> tag is also set reading
-these files) or C<unknown>.
+=item *
-=item tiff_bitspersample
+32-bit gray, RGB image, including a possible alpha channel as a
+double/sample image.
-Bits per sample from the image. This value is not used when writing
-an image, it is only set on a read image.
+=item *
-=item tiff_photometric
+bi-level images as paletted images containing only black and white,
+which other formats will also write as bi-level.
-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 *
-=item tiff_documentname
+tiled paletted images are now handled correctly
-=item tiff_imagedescription
+=item *
-=item tiff_make
+other images are read using C<tifflib>'s RGBA interface as
+8-bit/sample images.
-=item tiff_model
+=back
-=item tiff_pagename
+The following tags are set in a TIFF image when read, and can be set
+to control output:
-=item tiff_software
+=over
-=item tiff_datetime
+=item *
-=item tiff_artist
+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 tiff_hostcomputer
+=item *
-Various strings describing the image. tiff_datetime must be formatted
-as "YYYY:MM:DD HH:MM:SS". These correspond directly to the mixed case
-names in the TIFF specification. These are set in images read from a
-TIFF and saved when writing a TIFF image.
+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
$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)
+=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
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<i_aspect_only> is set
The type of compression, if any. This can be any of the following
values:
+=for stopwords RLE
+
=over
=item BI_RGB (0)
=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<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
=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<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 datachannels and
-storechannels options to control the number of channels in your input
+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:
storechannels=>3)
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:
+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>.
- $img->read(file=>'foo.raw', xsize=100, ysize=>100, interleave=>1)
+=back
+
+ $img->read(file=>'foo.raw', xsize=100, ysize=>100, raw_interleave=>1)
or die "Cannot read raw image\n";
=head2 PNG
=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
+number in the header and the storage of the cursor hot spot. I've
treated them separately so that you're not messing with tags to
distinguish between them.
=item *
-following lines which contain 0 and 1 placeholders for each scanline
+following lines which contain 0 and 1 placeholders for each scan line
of the image, starting from the top of the image.
=back
or die $img->errstr;
This was introduced in Imager 0.60. Previously reading ICO images
-acted as if C<<ico_masked => 0>>.
+acted as if C<ico_masked =E<gt> 0>.
=back
$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
=item *
-i_comment - the IMAGENAME field from the image. Also written to the
-file when writing.
+i_comment - the C<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.
+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 *
Once you have an image the basic mechanism is:
+=for stopwords STDOUT
+
=over
=item 1.
If your images are RGB images the default quantization mechanism will
produce a very good result, but can take a long time to execute. You
-could either use the standard webmap:
+could either use the standard web color map:
Imager->write_multi({ file=>$filename,
type=>'gif',
make_colors=>'mediancut' },
@imgs);
-By default all of the images will use the same global colormap, which
+By default all of the images will use the same global color map, which
will produce a smaller image. If your images have significant color
differences, you may want to generate a new palette for each image:
=head1 BUGS
-When saving Gif images the program does NOT try to shave of extra
+When saving GIF images the program does NOT try to shave off extra
colors if it is possible. If you specify 128 colors and there are
-only 2 colors used - it will have a 128 colortable anyway.
+only 2 colors used - it will have a 128 color table anyway.
=head1 SEE ALSO
projects / imager.git / blobdiff