Imager::Files - working with image files

Adding New Formats

       To support a new format for reading, call the register_reader() class method:

       register_reader()
           Registers single or multiple image read functions.

           Parameters:

           •   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.

           •   single - a code ref to read a single image from a file.  This is supplied:

               •   the object that read() was called on,

               •   an Imager::IO object that should be used to read the file, and

               •   all the parameters supplied to the read() method.

               The single parameter is required.

           •   multiple - a code ref which is called to read multiple images from a file. This is supplied:

               •   an Imager::IO object that should be used to read the file, and

               •   all the parameters supplied to the read_multi() method.

           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;
                },
               );

       register_writer()
           Registers single or multiple image write functions.

           Parameters:

           •   type - the identifier of the file format.  This is typically the extension in lowercase.

               This parameter is required.

           •   single - a code ref to write a single image to a file.  This is supplied:

               •   the object that write() was called on,

               •   an Imager::IO object that should be used to write the file, and

               •   all the parameters supplied to the write() method.

               The single parameter is required.

           •   multiple - a code ref which is called to write multiple images to a file. This is supplied:

               •   the class name write_multi() was called on, this is typically "Imager".

               •   an Imager::IO object that should be used to write the file, and

               •   all the parameters supplied to the read_multi() method.

       add_type_extensions($type, $ext, ...)
           This  class method can be used to add extensions to the map used by "def_guess_type" when working out
           the file type a filename extension.

             Imager->add_type_extension(mytype => "mytype", "mytypish");
             ...
             $im->write(file => "foo.mytypish") # use the mytype handler

       If you name the reader module "Imager::File::"your-format-name where 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 "Imager::File::"your-format-name"Reader" and Imager will attempt to autoload it.

       If your module can only handle  writing  then  you  can  name  your  module  "Imager::File::"your-format-name"Writer" and Imager will attempt to autoload it.

Author

       Tony Cook <tonyc@cpan.org>, Arnar M. Hrafnkelsson

perl v5.40.1                                       2025-03-16                                 Imager::Files(3pm)

Bugs

       When  saving  GIF  images  the  program does NOT try to shave off extra colors if it is possible.  If you
       specify 128 colors and there are only 2 colors used - it will have a 128 color table anyway.

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 "read_types()" or "write_types()" methods useful.

       read()
           Reading writing to and from files is simple, use the read() method to read an image:

             my $img = Imager->new;
             $img->read(file=>$filename, type=>$type)
               or die "Cannot read $filename: ", $img->errstr;

           In most cases Imager can auto-detect the file type, so you can just supply the file name:

             $img->read(file => $filename)
               or die "Cannot read $filename: ", $img->errstr;

           The  read()  method  accepts  the  "allow_incomplete" parameter.  If this is non-zero then read() can
           return true on an incomplete image and set the "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;

       write()
           and the write() method to write an image:

             $img->write(file=>$filename, type=>$type)
               or die "Cannot write $filename: ", $img->errstr;

       read_multi()
           If you're reading from a format that supports multiple images per file, use the 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 "type" automatically.

       write_multi()
           and if you want to write multiple images to a single file use the write_multi() method:

             Imager->write_multi({ file=> $filename, type=>$type }, @images)
               or die "Cannot write $filename: ", Imager->errstr;

       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 "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.

       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 "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.

       When  writing,  if  the  "filename" includes an extension that Imager recognizes, then you don't need the
       "type", but you may want to provide one anyway.  See "Guessing types" for information on controlling this
       recognition.

       The "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)

       Support for other formats can be found on CPAN, including:

         apng        Imager::File::APNG
         avif        Imager::File::AVIF
         heif/heic   Imager::File::HEIF
         qoi         Imager::File::QOI
         webp        Imager::File::WEBP

       When you read an image, Imager may set some  tags,  possibly  including  information  about  the  spatial
       resolution,  textual  information,  and  animation  information.   See  "Tags"  in Imager::ImageTypes for
       specifics.

       The open() method is a historical alias for the read() method.

   Inputandoutput
       When reading or writing you can specify one of a variety of sources or targets:

       •   "file" - The "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 "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;

       •   "fh" - "fh" is a file handle, typically returned from an "open" call.  You should call  "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;

       •   "fd"  -  "fd"  is  a  file  descriptor.   You can get this by calling the 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;

       •   "data" - When reading data, "data" is a scalar containing the image file data, or a reference to such
           a scalar.  When writing, "data" is a reference to the scalar to save the image file data to.

             my $data;
             $image->write(data => \$data, type => 'tiff')
               or die $image->errstr;

             my $data = $row->{someblob}; # eg. from a database
             my @images = Imager->read_multi(data => $data)
               or die Imager->errstr;

             # from Imager 0.99
             my @images = Imager->read_multi(data => \$data)
               or die Imager->errstr;

       •   "callback",  "readcb",  "writecb", "seekcb", "closecb" - Imager will make calls back to your supplied
           coderefs to read, write and seek from/to/through the image  file.   See  "I/O  Callbacks"  below  for
           details.

       •   "io" - an Imager::IO object.

         By  default  Imager will use buffered I/O when reading or writing an image.  You can disabled buffering
       for output by supplying a "buffered => 0" parameter to write() or write_multi().

   I/OCallbacks
       When reading from a file you can use either "callback" or "readcb" to supply the read callback, and  when
       writing "callback" or "writecb" to supply the write callback.

       Whether reading or writing a "TIFF" image, "seekcb" and "readcb" are required.

       If  a file handler attempts to use "readcb", "writecb" or "seekcb" and you haven't supplied one, the call
       will fail, failing the image read or write, returning an error message indicating that  the  callback  is
       missing:

         # attempting to read a TIFF image without a seekcb
         open my $fh, "<", $filename or die;
         my $rcb = sub {
           my $val;
           read($fh, $val, $_[0]) or return "";
           return $val;
         };
         my $im = Imager->new(callback => $rcb)
           or die Imager->errstr
         # dies with (wrapped here):
         # Error opening file: (Iolayer): Failed to read directory at offset 0:
         # (Iolayer): Seek error accessing TIFF directory: seek callback called
         # but no seekcb supplied

       You  can also provide a "closecb" parameter called when writing the file is complete.  If no "closecb" is
       supplied the default will succeed silently.

         # contrived
         my $data;
         sub mywrite {
           $data .= unpack("H*", shift);
           1;
         }
         Imager->write_multi({ callback => \&mywrite, type => 'gif'}, @images)
           or die Imager->errstr;

       "readcb"

       The read callback is called with 2 parameters:

       •   "size" - the minimum amount of data required.

       •   "maxsize" - previously this was the maximum amount of data returnable -  currently  it's  always  the
           same as "size"

       Your read callback should return the data as a scalar:

       •   on success, a string containing the bytes read.

       •   on end of file, an empty string

       •   on error, "undef".

       If your return value contains more data than "size" Imager will panic.

       Your return value must not contain any characters over "\xFF" or Imager will panic.

       "writecb"

       Your write callback takes exactly one parameter, a scalar containing the data to be written.

       Return true for success.

       "seekcb"

       The  seek  callback  takes 2 parameters, a POSITION, and a WHENCE, defined in the same way as perl's seek
       function.

       Previously you always needed a "seekcb" callback  if  you  called  Imager's  "read()"  or  "read_multi()"
       without  a  "type"  parameter,  but this is no longer necessary unless the file handler requires seeking,
       such as for TIFF files.

       Returns the new position in the file, or -1 on failure.

       "closecb"

       You can also supply a "closecb" which is called with no parameters when there  is  no  more  data  to  be
       written.  This could be used to flush buffered data.

       Return true on success.

   Guessingtypes
       When  writing  to a file, if you don't supply a "type" parameter Imager will attempt to guess it from the
       file name.  This is done by calling the code reference stored in $Imager::FORMATGUESS.  This is only done
       when write() or write_multi() is called with a "file" parameter,  or  if  read()  or  read_multi()  can't
       determine the type from the file's header.

       The default function value of $Imager::FORMATGUESS is "\&Imager::def_guess_type".

       def_guess_type()
           This is the default function Imager uses to derive a file type from a file name.  This is a function,
           not a method.

           Accepts a single parameter, the file name and returns the type or undef.

       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:

           "xpm", "mng", "jng", "ilbm", "pcx", "fits", "psd" (Photoshop), "eps", Utah "RLE".

       You can now add to the magic database Imager uses for detecting file types:

       add_file_magic()
             Imager->add_file_magic(name => $name, bits => $bits, mask => $mask)

           Adds to list of magic, the parameters are all required.  The parameters are:

           •   "name" - the file type name to return on match.

           •   "bits" - a binary string to match.

           •   "mask" - a mask controlling which parts of bits are significant.

           While  mask  is mostly a bit mask, some byte values are translated, the space character is treated as
           all zeros ("\x00"), and the "x" character as all ones ("\xFF").

           New magic entries take priority over old entries.

           You can add more than one magic entry for a given name.

             Imager->add_file_magic(name => "heif",
                                    bits => "    ftypheif"
                                    mask => "    xxxxxxxx");

   Limitingthesizesofimagesyoureadset_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:

           •   width - limit the width in pixels of the image

           •   height - limit the height in pixels of the image

           •   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.

           To set the limits, call the class method set_file_limits:

             Imager->set_file_limits(width=>$max_width, height=>$max_height);

           You can pass any or all of the limits above, any limits you do not pass are left as they were.

           Any limit of zero for width or height is treated as unlimited.

           A limit of zero for bytes is treated as one gigabyte, but higher bytes limits can be set explicitly.

           By default, the width and height limits are zero, or unlimited.  The default memory size limit is one
           gigabyte.

           You can reset all limits to their defaults with the reset parameter:

             # no limits
             Imager->set_file_limits(reset=>1);

           This can be used with the other limits to reset all but the limit you pass:

             # only width is limited
             Imager->set_file_limits(reset=>1, width=>100);

             # only bytes is limited
             Imager->set_file_limits(reset=>1, bytes=>10_000_000);

       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();

       check_file_limits()
           Intended for use by file handlers to check that the size of a  file  is  within  the  limits  set  by
           set_file_limits().

           Parameters:

           •   "width",  "height"  -  the  width and height of the image in pixels.  Must be a positive integer.
               Required.

           •   "channels" - the number of channels in the image, including the alpha channel if any.  Must be  a
               positive integer between 1 and 4 inclusive.  Default: 3.

           •   "sample_size"  -  the  number of bytes stored per sample.  Must be a positive integer or "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  "float"  since  Imager
               doesn't have 32-bit/sample images.

Examples

ProducinganimagefromaCGIscript
       Once you have an image the basic mechanism is:

       1.  set STDOUT to autoflush

       2.  output a content-type header, and optionally a content-length header

       3.  put STDOUT into binmode

       4.  call  write()  with  the "fd" or "fh" parameter.  You will need to provide the "type" parameter since
           Imager can't use the extension to guess the file format you want.

         # 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;

   WritingananimatedGIF
       The basic idea is simple, just use write_multi():

         my @imgs = ...;
         Imager->write_multi({ file=>$filename, type=>'gif' }, @imgs);

       If your images are RGB images the default quantization mechanism will produce a very good result, but can
       take a long time to execute.  You could either use the standard web color map:

         Imager->write_multi({ file=>$filename,
                               type=>'gif',
                               make_colors=>'webmap' },
                             @imgs);

       or use a median cut algorithm to built a fairly optimal color map:

         Imager->write_multi({ file=>$filename,
                               type=>'gif',
                               make_colors=>'mediancut' },
                             @imgs);

       By default all of the images will use the same global color map, which will produce a smaller image.   If
       your images have significant color differences, you may want to generate a new palette for each image:

         Imager->write_multi({ file=>$filename,
                               type=>'gif',
                               make_colors=>'mediancut',
                               gif_local_map => 1 },
                             @imgs);

       which  will  set the "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 "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 "gif_delay" to control the delay between frames and "transp"  to  control
       transparency.

   Readingtagsafterreadinganimage
       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";
         }

Name

       Imager::Files - working with image files

Preloading File Modules

preload()
           "Imager-"preload>  preloads  the  file  support modules included with or that have been included with
           Imager in the past.

           It isn't typically needed, but some cases where you might want to use it:

           •   For use in forking servers such as mod_perl to allow as many  pages  as  possible  to  be  shared
               between parent and child processes.

           •   to avoid runtime loading of a module from delaying output in an animation.

           •   if you're loading modules from a relative $ENV{PERL5LIB} and expect to change directories.

           You probably don't need it.

           If the module is not available no error occurs.

           Preserves $@.

             use Imager;
             Imager->preload;

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;

         open my $fh, "+>:raw", ... ;
         $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;

         Imager->add_file_magic(name => $name, bits => $bits, mask => $mask);

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 write() or 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 Imager::init() function with the "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.

PNM(PortableaNyMap)
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:

•
"pnm_maxval" - the "maxvals" number from the PGM/PPM header. Always set to 2 for a "PBM" file.

•
"pnm_type" - the type number from the "PNM" header, 1 for ASCII "PBM" files, 2 for ASCII "PGM"
files, 3 for ASCII c<PPM> files, 4 for binary "PBM" files, 5 for binary "PGM" files, 6 for binary
"PPM" files.

The following tag is checked when writing an image with more than 8-bits/sample:

•
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.

JPEG
You can supply a "jpegquality" parameter ranging from 0 (worst quality) to 100 (best quality) when
writing a JPEG file, which defaults to 75.

$img->write(file=>'foo.jpg', jpegquality=>90) or die $img->errstr;

If you write an image with an alpha channel to a JPEG file then it will be composed against the
background set by the "i_background" parameter (or tag), or black if not supplied.

Imager will read a gray scale JPEG as a 1 channel image and a color JPEG as a 3 channel image.

$img->read(file=>'foo.jpg') or die $img->errstr;

The following tags are set in a JPEG image when read, and can be set to control output:

• "jpeg_density_unit" - 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.

The "i_xres" and "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.

• "jpeg_density_unit_name" - This is set when reading a JPEG file to the name of the unit given by
"jpeg_density_unit". Possible results include "inch", "centimeter", "none" (the "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.

• "jpeg_comment" - Text comment.

• "jpeg_progressive" - Whether the JPEG file is a progressive file. (Imager 0.84)

JPEG supports the spatial resolution tags "i_xres", "i_yres" and "i_aspect_only".

You can also set the following tags when writing to an image, they are not set in the image when reading:

• "jpeg_optimize" - set to a non-zero integer to compute optimal Huffman coding tables for the image.
This will increase memory usage and processing time (about 12% in my simple tests) but can
significantly reduce file size without a loss of quality.

• "jpeg_compress_profile" - set to either "fastest", the default, or only with "MozJPEG", to "max".
Setting this to any other value will cause an error, failing the write() call. Setting this to "max"
without "MozJPEG" will cause an error.

use Imager::File::JPEG;
my $prof = Imager::File::JPEG->is_mozjpeg ? "max" : "fastest";
$im->write(file => "foo.jpeg", jpeg_compress_profile => $prof)
or die $im->errstr;

Note that unlike "MozJPEG", Imager always defaults to "fastest".

• "jpeg_tune" - corresponds to the "MozJPEG" "cjpeg" "-tune" parameters, this can be any of:

• "psnr"

• "ssim"

• "ms-ssim"

• "hvs-psnr"

These set the same values as the "jpeg_base_quant_tbl_idx", "jpeg_lambda_log_scale1",
"jpeg_lambda_log_scale2" and "jpeg_use_lambda_weight_tbl" tags, which can override the values set by
"jpeg_tune".

Unlike "cjpeg" "-tune", "jpeg_tune" doesn't force the quality to 75.

Requires that Imager::File::JPEG was built with "MozJPEG".

• "jpeg_arithmetic" - if set to non-zero, use arithmetic coding when writing the image. This requires
that the "libjpeg" variant that Imager::File::JPEG was built with had encode support for arithmetic
coding enabled when it was built.

•

"jpeg_jfif" - if set to zero, disable writing the JFIF header even if one is technically required,
which it is for the color spaces Imager works with. This saves 18 bytes in the output file and most
applications including web browsers will successfully read the file, but your experience may differ.

This will prevent the "i_xres", "i_yres" and "jpeg_density_units" tags from having an effect.

• "jpeg_smooth" - if set to a value from 1 to 100 apply smoothing to the image to eliminate dithering
noise (without modifying the Imager image). Default: 0 (no smoothing).

•

"jpeg_restart" - if set to a plain integer "N", generate a JPEG restart marker every "N" rows, if set
to an integer followed by "B", generate a JPEG restart marker every "N" MCUs, the 8x8 pixel blocks
that make up a JPEG image. Note that if this is specified in rows it will be translated to MCUs by
"libjpeg".

This allows a decoder to recover from corruption, but it makes the file slightly larger.

Default: 0, no restart markers are produced.

•

"jpeg_sample" - control subsampling of the YCbCr components, equivalent to the "-sample" parameter
for "cjpeg".

Default: "2x2,1x1,1x1", default 4:2:0 JPEG subsampling.

The following options can be set on writing with "MozJPEG" and correspond directly to the API options
described in the "MozJPEG" README-mozilla.txt. Attempting to set them when Imager::File::JPEG has been
built with another "libjpeg" will result in an error.

• "jpeg_optimize_scans", "jpeg_trellis_quant", "jpeg_trellis_quant_dc", "jpeg_tresllis_eob_opt",
"jpeg_use_lambda_weight_tbl", "jpeg_use_scans_in_trellis", "jpeg_overshoot_deringing" - boolean
options, set to 0 or 1.

"jpeg_lambda_log_scale1", "jpeg_lambda_log_scale2", "jpeg_trellis_delta_dc_weight" - integer options.

"jpeg_trellis_freq_split", "jpeg_trellis_num_loops", "jpeg_base_quant_tbl_idx",
"jpeg_dc_scan_opt_mode" - floating point options.

When reading a JPEG image, the following tag will be set, and ignored on writing:

• "jpeg_read_arithmetic" - the image had been written with arithmetic coding. This uses a separate
name from writing to avoid arithmetic coding from being accidentally propagated to a file that might
need to be read by an implementation without arithmetic coding support.

If an "APP1" block containing EXIF information is found, then any of the following tags can be set when
reading a JPEG image:

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

The following derived tags can also be set when reading a JPEG image:

exif_color_space_name exif_contrast_name exif_custom_rendered_name exif_exposure_mode_name
exif_exposure_program_name exif_flash_name exif_focal_plane_resolution_unit_name
exif_gain_control_name exif_light_source_name exif_metering_mode_name exif_resolution_unit_name
exif_saturation_name exif_scene_capture_type_name exif_sensing_method_name exif_sharpness_name
exif_subject_distance_range_name exif_white_balance_name

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
"exf_metering_mode" is 5 then "exif_metering_mode_name" is set to "Pattern".

eg.

my $image = Imager->new;
$image->read(file => 'exiftest.jpg')
or die "Cannot load image: ", $image->errstr;
print $image->tags(name => "exif_image_description"), "\n";
print $image->tags(name => "exif_exposure_mode"), "\n";
print $image->tags(name => "exif_exposure_mode_name"), "\n";

# for the exiftest.jpg in the Imager distribution the output would be:
Imager Development Notes
0
Auto exposure

Imager will not write EXIF tags to any type of image, if you need more advanced EXIF handling, consider
Image::ExifTool.

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.

GIF
When writing one of more GIF images you can use the same Quantization Options 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 "$img->read()" you can supply a reference to a scalar in the "colors"
parameter, if the image is read the scalar will be filled with a reference to an anonymous array of
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 read_multi() and use the
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:

• gif_left - the offset of the image from the left of the "screen" ("Image Left Position")

• gif_top - the offset of the image from the top of the "screen" ("Image Top Position")

• gif_interlace - non-zero if the image was interlaced ("Interlace Flag")

• gif_screen_width, gif_screen_height - the size of the logical screen. When writing this is used as
the minimum. If any image being written would extend beyond this then the screen size is extended.
("Logical Screen Width", "Logical Screen Height").

• 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.

• 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
"gif_eliminate_unused" 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")

• 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 "transp" option (see
"Quantization options" in Imager::ImageTypes) for this value to be used.

• gif_delay - 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").

• gif_disposal - 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.

• gif_comment - 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.

• 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.

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.

• 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 "gif_local_map" in new code.

• interlace - The images are written interlaced if this is non-zero.

Use "gif_interlace" in new code.

• gif_delays - A reference to an array containing the delays between images, in 1/100 seconds.

Use "gif_delay" in new code.

• gif_positions - A reference to an array of references to arrays which represent screen positions for
each image.

New code should use the "gif_left" and "gif_top" tags.

• 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".

You can supply a "page" parameter to the read() method to read some page other than the first. The page
is 0 based:

# read the second image in the file
$image->read(file=>"example.gif", page=>1)
or die "Cannot read second page: ",$image->errstr,"\n";

Before release 0.46, Imager would read multiple image GIF image files into a single image, overlaying
each of the images onto the virtual GIF screen.

As of 0.46 the default is to read the first image from the file, as if called with "page => 0".

You can return to the previous behavior by calling read with the "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.

TIFF(TaggedImageFileFormat)
Imager can write images to either paletted or RGB TIFF images, depending on the type of the source image.

When writing direct color images to TIFF the sample size of the output file depends on the input:

• double/sample - written as 32-bit/sample TIFF

• 16-bit/sample - written as 16-bit/sample TIFF

• 8-bit/sample - written as 8-bit/sample TIFF

For paletted images:

• "$img->is_bilevel" is true - the image is written as bi-level

• otherwise - image is written as paletted.

If you are creating images for faxing you can set the class parameter set to "fax". By default the image
is written in fine mode, but this can be overridden by setting the fax_fine parameter to zero. Since a
fax image is bi-level, Imager uses a threshold to decide if a given pixel is black or white, based on a
single channel. For gray scale images channel 0 is used, for color images channel 1 (green) is used. If
you want more control over the conversion you can use $img->to_paletted() to product a bi-level image.
This way you can use dithering:

my $bilevel = $img->to_paletted(make_colors => 'mono',
translate => 'errdiff',
errdiff => 'stucki');

• "class" - If set to 'fax' the image will be written as a bi-level fax image.

• "fax_fine" - By default when "class" is set to 'fax' the image is written in fine mode, you can
select normal mode by setting "fax_fine" to 0.

Imager should be able to read any TIFF image you supply. Paletted TIFF images are read as paletted
Imager images, since paletted TIFF images have 16-bits/sample (48-bits/color) this means the bottom
8-bits are lost, but this shouldn't be a big deal.

TIFF supports the spatial resolution tags. See the "tiff_resolutionunit" tag for some extra options.

As of Imager 0.62 Imager reads:

• 8-bit/sample gray, RGB or CMYK images, including a possible alpha channel as an 8-bit/sample image.

• 16-bit gray, RGB, or CMYK image, including a possible alpha channel as a 16-bit/sample image.

• 32-bit gray, RGB image, including a possible alpha channel as a double/sample image.

• bi-level images as paletted images containing only black and white, which other formats will also
write as bi-level.

• tiled paletted images are now handled correctly

• other images are read using "tifflib"'s RGBA interface as 8-bit/sample images.

The following tags are set in a TIFF image when read, and can be set to control output:

• "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. "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 "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;

• "tags, tiff_jpegquality""tiff_jpegquality" - If "tiff_compression" is "jpeg" then this can be a
number from 1 to 100 giving the JPEG compression quality. High values are better quality and larger
files.

•
"tiff_resolutionunit" - The value of the "ResolutionUnit" tag. This is ignored on writing if the
i_aspect_only tag is non-zero.

The "i_xres" and "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.

•
"tiff_resolutionunit_name" - This is set when reading a TIFF file to the name of the unit given by
"tiff_resolutionunit". Possible results include "inch", "centimeter", "none" (the "i_aspect_only"
tag is also set reading these files) or "unknown".

•
"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.

•
"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.

• "tiff_documentname", "tiff_imagedescription", "tiff_make", "tiff_model", "tiff_pagename",
"tiff_software", "tiff_datetime", "tiff_artist", "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.

You can supply a "page" parameter to the read() method to read some page other than the first. The page
is 0 based:

# read the second image in the file
$image->read(file=>"example.tif", page=>1)
or die "Cannot read second page: ",$image->errstr,"\n";

If you read an image with multiple alpha channels, then only the first alpha channel will be read.

When reading a "TIFF" image with callbacks, the "seekcb" callback parameter is also required.

When writing a "TIFF" image with callbacks, the "seekcb" and "readcb" parameters are also required.

"TIFF" is a random access file format, it cannot be read from or written to unseekable streams such as
pipes or sockets.

BMP(WindowsBitmap)
Imager can write 24-bit RGB, and 8, 4 and 1-bit per pixel paletted Windows BMP files. Currently you
cannot write compressed BMP files with Imager.

Imager can read 24-bit RGB, and 8, 4 and 1-bit perl pixel paletted Windows BMP files. There is some
support for reading 16-bit per pixel images, but I haven't found any for testing.

BMP has no support for multiple image files.

BMP files support the spatial resolution tags, but since BMP has no support for storing only an aspect
ratio, if "i_aspect_only" is set when you write the "i_xres" and "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:

bmp_compression
The type of compression, if any. This can be any of the following values:

BI_RGB (0)
Uncompressed.

BI_RLE8 (1)
8-bits/pixel paletted value RLE compression.

BI_RLE4 (2)
4-bits/pixel paletted value RLE compression.

BI_BITFIELDS (3)
Packed RGB values.

bmp_compression_name
The bmp_compression value as a BI_* string

bmp_important_colors
The number of important colors as defined by the writer of the image.

bmp_used_colors
Number of color used from the BMP header

bmp_filesize
The file size from the BMP header

bmp_bit_count
Number of bits stored per pixel. (24, 8, 4 or 1)

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:

tga_idstring
tga_bitspp
compressed

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 "raw_datachannels" and "raw_storechannels" options to control the number of channels in your
input file and the resulting channels in your image. For example, if your input image uses 32-bits per
pixel with red, green, blue and junk values for each pixel you could do:

$img->read(file=>'foo.raw', xsize => 100, ysize => 100,
raw_datachannels => 4, raw_storechannels => 3,
raw_interleave => 0)
or die "Cannot read raw image\n";

In general, if you supply "raw_storechannels" you should also supply "raw_datachannels"

Read parameters:

• "raw_interleave" - controls the ordering of samples within the image. Default: 1. Alternatively and
historically spelled "interleave". Possible values:

• 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

• 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.

Unfortunately, historically, the default "raw_interleave" for read has been 1, while writing only
supports the "raw_interleave" = 0 format.

For future compatibility, you should always supply the "raw_interleave" (or "interleave") parameter.
As of 0.68, Imager will warn if you attempt to read a raw image without a "raw_interleave" parameter.

• "raw_storechannels" - the number of channels to store in the image. Range: 1 to 4. Default: 3.
Alternatively and historically spelled "storechannels".

• "raw_datachannels" - the number of channels to read from the file. Range: 1 or more. Default: 3.
Alternatively and historically spelled "datachannels".

$img->read(file=>'foo.raw', xsize=100, ysize=>100, raw_interleave=>1)
or die "Cannot read raw image\n";

PNGPNGImagemodes

PNG files can be read and written in the following modes:

• bi-level - written as a 1-bit per sample gray scale image

• 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.

• 8 and 16-bit per sample gray scale, optionally with an alpha channel.

• 8 and 16-bit per sample RGB, optionally with an alpha channel.

Unlike GIF, there is no automatic conversion to a paletted image, since PNG supports direct color.

PNGTexttags

Text tags are retrieved from and written to PNG "tEXT" or "zTXT" chunks. The following standard tags
from the PNG specification are directly supported:

• "i_comment" - keyword of "Comment".

• "png_author" - keyword "Author".

• "png_copyright" - keyword "Copyright".

• "png_creation_time" - keyword "Creation Time".

• "png_description" - keyword "Description".

• "png_disclaimer" - keyword "Disclaimer".

• "png_software" - keyword "Software".

• "png_title" - keyword "Title".

• "png_warning" - keyword "Warning".

Each of these tags has a corresponding "base-tag-name_compressed" tag, eg. "png_comment_compressed".
When reading, if the PNG chunk is compressed this tag will be set to 1, but is otherwise unset. When
writing, Imager will honor the compression tag if set and non-zero, otherwise the chunk text will be
compressed if the value is longer than 1000 characters, as recommended by the "libpng" documentation.

PNG "tEXT" or "zTXT" chunks outside of those above are read into or written from Imager tags named like:

• "png_textN_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.

• "png_textN_text" - the text for the text chunk. This may not contain any "NUL" characters.

• "png_textN_compressed" - whether or not the text chunk is compressed. This behaves similarly to the
"base-tag-name_compressed" tags described above.

Where N starts from 0. When writing both the "..._key" and "..._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.

OtherPNGmetadatatags

•
"png_interlace", "png_interlace_name" - only set when reading, "png_interlace" is set to the type of
interlacing used by the file, 0 for one, 1 for Adam7. "png_interlace_name" is set to a keyword
describing the interlacing, either "none" or "adam7".

•
"png_srgb_intent" - the sRGB rendering intent for the image. an integer from 0 to 3, per the PNG
specification. If this chunk is found in the PNG file the "gAMA" and "cHRM" are ignored and the
"png_gamma" and "png_chroma_..." tags are not set. Similarly when writing if "png_srgb_intent" is
set the "gAMA" and "cHRM" chunks are not written.

•
"png_gamma" - the gamma of the image. This value is not currently used by Imager when processing the
image, but this may change in the future.

•
"png_chroma_white_x", "png_chroma_white_y", "png_chroma_red_x", "png_chroma_red_y",
"png_chroma_green_x", "png_chroma_green_y", "png_chroma_blue_x", "png_chroma_blue_y" - the primary
chromaticities of the image, defining the color model. This is currently not used by Imager when
processing the image, but this may change in the future.

• "i_xres", "i_yres", "i_aspect_only" - processed per Imager::ImageTypes/CommonTags.

•
"png_bits" - the number of bits per sample in the representation. Ignored when writing.

•
"png_time" - the creation time of the file formatted as "year-month-dayThour:minute:second". This
is stored as time data structure in the file, not a string. If you set "png_time" and it cannot be
parsed as above, writing the PNG file will fail.

• "i_background" - set from the "sBKG" when reading an image file.

You can control the level of zlib compression used when writing with the "png_compression_level"
parameter. This can be an integer between 0 (uncompressed) and 9 (best compression).

If you're using libpng 1.6 or later, or an earlier release configured with
"PNG_BENIGN_ERRORS_SUPPORTED", you can choose to ignore file format errors the authors of libpng consider
benign, this includes at least CRC errors and palette index overflows. Do this by supplying a true value
for the "png_ignore_benign_errors" parameter to the read() method:

$im->read(file => "foo.png", png_ignore_benign_errors => 1)
or die $im->errstr;

ICO(MicrosoftWindowsIcon)andCUR(MicrosoftWindowsCursor)
Icon and Cursor files are very similar, the only differences being a number in the header and the storage
of the cursor hot spot. I've treated them separately so that you're not messing with tags to distinguish
between them.

The following tags are set when reading an icon image and are used when writing it:

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:

• first line consisting of the 0 placeholder, the 1 placeholder and a newline.

• following lines which contain 0 and 1 placeholders for each scan line of the image, starting from
the top of the image.

When reading an image, '.' is used as the 0 placeholder and '*' as the 1 placeholder. An example:

.*
..........................******
..........................******
..........................******
..........................******
...........................*****
............................****
............................****
.............................***
.............................***
.............................***
.............................***
..............................**
..............................**
...............................*
...............................*
................................
................................
................................
................................
................................
................................
*...............................
**..............................
**..............................
***.............................
***.............................
****............................
****............................
*****...........................
*****...........................
*****...........................
*****...........................

The following tags are set when reading an icon:

ico_bits
The number of bits per pixel used to store the image.

For cursor files the following tags are set and read when reading and writing:

cur_mask
This is the same as the ico_mask above.

cur_hotspotx
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.

The following parameters can be supplied to read() or read_multi() to control reading of ICO/CUR files:

• "ico_masked" - if true, the default, then the icon/cursors mask is applied as an alpha channel to the
image, unless that image already has an alpha channel. This may result in a paletted image being
returned as a direct color image. Default: 1

# 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 "ico_masked => 0".

• "ico_alpha_masked" - if true, then the icon/cursor mask is applied as an alpha channel to images that
already have an alpha mask. Note that this will only make pixels transparent, not opaque. Default:
0.

Note: If you get different results between "ico_alpha_masked" being set to 0 and 1, your mask may
break when used with the Win32 API.

"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');

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 "rgb", "bw", "sgi", "rgba" the file will be saved in SGI
format. The file extension is otherwise ignored, so saving a 3-channel image to a ".bw" file will result
in a 3-channel image on disk.

The following tags are set when reading a SGI image:

• i_comment - the "IMAGENAME" field from the image. Also written to the file when writing.

• 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_bpc - the number of bytes per sample for the image. Ignored when writing.

• sgi_rle - whether or not the image is compressed. If this is non-zero when writing the image will be
compressed.