1Imager::Files(3)      User Contributed Perl Documentation     Imager::Files(3)
2
3
4

NAME

6       Imager::Files - working with image files
7

SYNOPSIS

9         use Imager;
10         my $img = ...;
11         $img->write(file=>$filename, type=>$type)
12           or die "Cannot write: ",$img->errstr;
13
14         # type is optional if we can guess the format from the filename
15         $img->write(file => "foo.png")
16           or die "Cannot write: ",$img->errstr;
17
18         $img = Imager->new;
19         $img->read(file=>$filename, type=>$type)
20           or die "Cannot read: ", $img->errstr;
21
22         # type is optional if we can guess the type from the file data
23         # and we normally can guess
24         $img->read(file => $filename)
25           or die "Cannot read: ", $img->errstr;
26
27         Imager->write_multi({ file=> $filename, ... }, @images)
28           or die "Cannot write: ", Imager->errstr;
29
30         my @imgs = Imager->read_multi(file=>$filename)
31           or die "Cannot read: ", Imager->errstr;
32
33         Imager->set_file_limits(width=>$max_width, height=>$max_height)
34
35         my @read_types = Imager->read_types;
36         my @write_types = Imager->write_types;
37
38         # we can write/write_multi to things other than filenames
39         my $data;
40         $img->write(data => \$data, type => $type) or die;
41
42         open my $fh, "+>:raw", ... ;
43         $img->write(fh => $fh, type => $type) or die;
44
45         $img->write(fd => fileno($fh), type => $type) or die;
46
47         # some file types need seek callbacks too
48         $img->write(callback => \&write_callback, type => $type) or die;
49
50         # and similarly for read/read_multi
51         $img->read(data => $data) or die;
52         $img->read(fh => $fh) or die;
53         $img->read(fd => fileno($fh)) or die;
54         $img->read(callback => \&read_callback) or die;
55
56         use Imager 0.68;
57         my $img = Imager->new(file => $filename)
58           or die Imager->errstr;
59
60         Imager->add_file_magic(name => $name, bits => $bits, mask => $mask);
61

DESCRIPTION

63       You can read and write a variety of images formats, assuming you have
64       the appropriate libraries, and images can be read or written to/from
65       files, file handles, file descriptors, scalars, or through callbacks.
66
67       To see which image formats Imager is compiled to support the following
68       code snippet is sufficient:
69
70         use Imager;
71         print join " ", keys %Imager::formats;
72
73       This will include some other information identifying libraries rather
74       than file formats.  For new code you might find the "read_types()" or
75       "write_types()" methods useful.
76
77       read()
78           Reading writing to and from files is simple, use the read() method
79           to read an image:
80
81             my $img = Imager->new;
82             $img->read(file=>$filename, type=>$type)
83               or die "Cannot read $filename: ", $img->errstr;
84
85           In most cases Imager can auto-detect the file type, so you can just
86           supply the file name:
87
88             $img->read(file => $filename)
89               or die "Cannot read $filename: ", $img->errstr;
90
91           The read() method accepts the "allow_incomplete" parameter.  If
92           this is non-zero then read() can return true on an incomplete image
93           and set the "i_incomplete" tag.
94
95           From Imager 0.68 you can supply most read() parameters to the new()
96           method to read the image file on creation.  If the read fails,
97           check Imager->errstr() for the cause:
98
99             use Imager 0.68;
100             my $img = Imager->new(file => $filename)
101               or die "Cannot read $filename: ", Imager->errstr;
102
103       write()
104           and the write() method to write an image:
105
106             $img->write(file=>$filename, type=>$type)
107               or die "Cannot write $filename: ", $img->errstr;
108
109       read_multi()
110           If you're reading from a format that supports multiple images per
111           file, use the read_multi() method:
112
113             my @imgs = Imager->read_multi(file=>$filename, type=>$type)
114               or die "Cannot read $filename: ", Imager->errstr;
115
116           As with the read() method, Imager will normally detect the "type"
117           automatically.
118
119       write_multi()
120           and if you want to write multiple images to a single file use the
121           write_multi() method:
122
123             Imager->write_multi({ file=> $filename, type=>$type }, @images)
124               or die "Cannot write $filename: ", Imager->errstr;
125
126       read_types()
127           This is a class method that returns a list of the image file types
128           that Imager can read.
129
130             my @types = Imager->read_types;
131
132           These types are the possible values for the "type" parameter, not
133           necessarily the extension of the files you're reading.
134
135           It is possible for extra file read handlers to be loaded when
136           attempting to read a file, which may modify the list of available
137           read types.
138
139       write_types()
140           This is a class method that returns a list of the image file types
141           that Imager can write.
142
143             my @types = Imager->write_types;
144
145           Note that these are the possible values for the "type" parameter,
146           not necessarily the extension of the files you're writing.
147
148           It is possible for extra file write handlers to be loaded when
149           attempting to write a file, which may modify the list of available
150           write types.
151
152       When writing, if the "filename" includes an extension that Imager
153       recognizes, then you don't need the "type", but you may want to provide
154       one anyway.  See "Guessing types" for information on controlling this
155       recognition.
156
157       The "type" parameter is a lowercase representation of the file type,
158       and can be any of the following:
159
160         bmp   Windows BitMaP (BMP)
161         gif   Graphics Interchange Format (GIF)
162         jpeg  JPEG/JFIF
163         png   Portable Network Graphics (PNG)
164         pnm   Portable aNyMap (PNM)
165         raw   Raw
166         sgi   SGI .rgb files
167         tga   TARGA
168         tiff  Tagged Image File Format (TIFF)
169
170       Support for other formats can be found on CPAN, including:
171
172         heif/heic   Imager::File::HEIF
173         qoi         Imager::File::QOI
174         webp        Imager::File::WEBP
175
176       When you read an image, Imager may set some tags, possibly including
177       information about the spatial resolution, textual information, and
178       animation information.  See "Tags" in Imager::ImageTypes for specifics.
179
180       The open() method is a historical alias for the read() method.
181
182   Input and output
183       When reading or writing you can specify one of a variety of sources or
184       targets:
185
186       •   "file" - The "file" parameter is the name of the image file to be
187           written to or read from.  If Imager recognizes the extension of the
188           file you do not need to supply a "type".
189
190             # write in tiff format
191             $image->write(file => "example.tif")
192               or die $image->errstr;
193
194             $image->write(file => 'foo.tmp', type => 'tiff')
195               or die $image->errstr;
196
197             my $image = Imager->new;
198             $image->read(file => 'example.tif')
199               or die $image->errstr;
200
201       •   "fh" - "fh" is a file handle, typically returned from an "open"
202           call.  You should call "binmode" on the handle before passing it to
203           Imager.
204
205           Imager will set the handle to autoflush to make sure any buffered
206           data is flushed , since Imager will write to the file descriptor
207           (from fileno()) rather than writing at the perl level.
208
209             $image->write(fh => \*STDOUT, type => 'gif')
210               or die $image->errstr;
211
212             # for example, a file uploaded via CGI.pm
213             $image->read(fd => $cgi->param('file'))
214               or die $image->errstr;
215
216       •   "fd" - "fd" is a file descriptor.  You can get this by calling the
217           fileno() function on a file handle, or by using one of the standard
218           file descriptor numbers.
219
220           If you get this from a perl file handle, you may need to flush any
221           buffered output, otherwise it may appear in the output stream after
222           the image.
223
224             $image->write(fd => file(STDOUT), type => 'gif')
225               or die $image->errstr;
226
227       •   "data" - When reading data, "data" is a scalar containing the image
228           file data, or a reference to such a scalar.  When writing, "data"
229           is a reference to the scalar to save the image file data to.
230
231             my $data;
232             $image->write(data => \$data, type => 'tiff')
233               or die $image->errstr;
234
235             my $data = $row->{someblob}; # eg. from a database
236             my @images = Imager->read_multi(data => $data)
237               or die Imager->errstr;
238
239             # from Imager 0.99
240             my @images = Imager->read_multi(data => \$data)
241               or die Imager->errstr;
242
243       •   "callback", "readcb", "writecb", "seekcb", "closecb" - Imager will
244           make calls back to your supplied coderefs to read, write and seek
245           from/to/through the image file.  See "I/O Callbacks" below for
246           details.
247
248       •   "io" - an Imager::IO object.
249
250       By default Imager will use buffered I/O when reading or writing an
251       image.  You can disabled buffering for output by supplying a "buffered
252       => 0" parameter to write() or write_multi().
253
254   I/O Callbacks
255       When reading from a file you can use either "callback" or "readcb" to
256       supply the read callback, and when writing "callback" or "writecb" to
257       supply the write callback.
258
259       Whether reading or writing a "TIFF" image, "seekcb" and "readcb" are
260       required.
261
262       If a file handler attempts to use "readcb", "writecb" or "seekcb" and
263       you haven't supplied one, the call will fail, failing the image read or
264       write, returning an error message indicating that the callback is
265       missing:
266
267         # attempting to read a TIFF image without a seekcb
268         open my $fh, "<", $filename or die;
269         my $rcb = sub {
270           my $val;
271           read($fh, $val, $_[0]) or return "";
272           return $val;
273         };
274         my $im = Imager->new(callback => $rcb)
275           or die Imager->errstr
276         # dies with (wrapped here):
277         # Error opening file: (Iolayer): Failed to read directory at offset 0:
278         # (Iolayer): Seek error accessing TIFF directory: seek callback called
279         # but no seekcb supplied
280
281       You can also provide a "closecb" parameter called when writing the file
282       is complete.  If no "closecb" is supplied the default will succeed
283       silently.
284
285         # contrived
286         my $data;
287         sub mywrite {
288           $data .= unpack("H*", shift);
289           1;
290         }
291         Imager->write_multi({ callback => \&mywrite, type => 'gif'}, @images)
292           or die Imager->errstr;
293
294       "readcb"
295
296       The read callback is called with 2 parameters:
297
298       •   "size" - the minimum amount of data required.
299
300       •   "maxsize" - previously this was the maximum amount of data
301           returnable - currently it's always the same as "size"
302
303       Your read callback should return the data as a scalar:
304
305       •   on success, a string containing the bytes read.
306
307       •   on end of file, an empty string
308
309       •   on error, "undef".
310
311       If your return value contains more data than "size" Imager will panic.
312
313       Your return value must not contain any characters over "\xFF" or Imager
314       will panic.
315
316       "writecb"
317
318       Your write callback takes exactly one parameter, a scalar containing
319       the data to be written.
320
321       Return true for success.
322
323       "seekcb"
324
325       The seek callback takes 2 parameters, a POSITION, and a WHENCE, defined
326       in the same way as perl's seek function.
327
328       Previously you always needed a "seekcb" callback if you called Imager's
329       "read()" or "read_multi()" without a "type" parameter, but this is no
330       longer necessary unless the file handler requires seeking, such as for
331       TIFF files.
332
333       Returns the new position in the file, or -1 on failure.
334
335       "closecb"
336
337       You can also supply a "closecb" which is called with no parameters when
338       there is no more data to be written.  This could be used to flush
339       buffered data.
340
341       Return true on success.
342
343   Guessing types
344       When writing to a file, if you don't supply a "type" parameter Imager
345       will attempt to guess it from the file name.  This is done by calling
346       the code reference stored in $Imager::FORMATGUESS.  This is only done
347       when write() or write_multi() is called with a "file" parameter, or if
348       read() or read_multi() can't determine the type from the file's header.
349
350       The default function value of $Imager::FORMATGUESS is
351       "\&Imager::def_guess_type".
352
353       def_guess_type()
354           This is the default function Imager uses to derive a file type from
355           a file name.  This is a function, not a method.
356
357           Accepts a single parameter, the file name and returns the type or
358           undef.
359
360       You can replace function with your own implementation if you have some
361       specialized need.  The function takes a single parameter, the name of
362       the file, and should return either a file type or under.
363
364         # I'm writing jpegs to weird filenames
365         local $Imager::FORMATGUESS = sub { 'jpeg' };
366
367       When reading a file Imager examines beginning of the file for
368       identifying information.  The current implementation attempts to detect
369       the following image types beyond those supported by Imager:
370
371           "xpm", "mng", "jng", "ilbm", "pcx", "fits", "psd" (Photoshop),
372           "eps", Utah "RLE".
373
374       You can now add to the magic database Imager uses for detecting file
375       types:
376
377       add_file_magic()
378             Imager->add_file_magic(name => $name, bits => $bits, mask => $mask)
379
380           Adds to list of magic, the parameters are all required.  The
381           parameters are:
382
383           •   "name" - the file type name to return on match.
384
385           •   "bits" - a binary string to match.
386
387           •   "mask" - a mask controlling which parts of bits are
388               significant.
389
390           While mask is mostly a bit mask, some byte values are translated,
391           the space character is treated as all zeros ("\x00"), and the "x"
392           character as all ones ("\xFF").
393
394           New magic entries take priority over old entries.
395
396           You can add more than one magic entry for a given name.
397
398             Imager->add_file_magic(name => "heif",
399                                    bits => "    ftypheif"
400                                    mask => "    xxxxxxxx");
401
402   Limiting the sizes of images you read
403       set_file_limits()
404           In some cases you will be receiving images from an untested source,
405           such as submissions via CGI.  To prevent such images from consuming
406           large amounts of memory, you can set limits on the dimensions of
407           images you read from files:
408
409           •   width - limit the width in pixels of the image
410
411           •   height - limit the height in pixels of the image
412
413           •   bytes - limits the amount of storage used by the image.  This
414               depends on the width, height, channels and sample size of the
415               image.  For paletted images this is calculated as if the image
416               was expanded to a direct color image.
417
418           To set the limits, call the class method set_file_limits:
419
420             Imager->set_file_limits(width=>$max_width, height=>$max_height);
421
422           You can pass any or all of the limits above, any limits you do not
423           pass are left as they were.
424
425           Any limit of zero for width or height is treated as unlimited.
426
427           A limit of zero for bytes is treated as one gigabyte, but higher
428           bytes limits can be set explicitly.
429
430           By default, the width and height limits are zero, or unlimited.
431           The default memory size limit is one gigabyte.
432
433           You can reset all limits to their defaults with the reset
434           parameter:
435
436             # no limits
437             Imager->set_file_limits(reset=>1);
438
439           This can be used with the other limits to reset all but the limit
440           you pass:
441
442             # only width is limited
443             Imager->set_file_limits(reset=>1, width=>100);
444
445             # only bytes is limited
446             Imager->set_file_limits(reset=>1, bytes=>10_000_000);
447
448       get_file_limits()
449           You can get the current limits with the get_file_limits() method:
450
451             my ($max_width, $max_height, $max_bytes) =
452                Imager->get_file_limits();
453
454       check_file_limits()
455           Intended for use by file handlers to check that the size of a file
456           is within the limits set by set_file_limits().
457
458           Parameters:
459
460           •   "width", "height" - the width and height of the image in
461               pixels.  Must be a positive integer. Required.
462
463           •   "channels" - the number of channels in the image, including the
464               alpha channel if any.  Must be a positive integer between 1 and
465               4 inclusive.  Default: 3.
466
467           •   "sample_size" - the number of bytes stored per sample.  Must be
468               a positive integer or "float".  Note that this should be the
469               sample size of the Imager image you will be creating, not the
470               sample size in the source, eg. if the source has 32-bit samples
471               this should be "float" since Imager doesn't have 32-bit/sample
472               images.
473

TYPE SPECIFIC INFORMATION

475       The different image formats can write different image type, and some
476       have different options to control how the images are written.
477
478       When you call write() or write_multi() with an option that has the same
479       name as a tag for the image format you're writing, then the value
480       supplied to that option will be used to set the corresponding tag in
481       the image.  Depending on the image format, these values will be used
482       when writing the image.
483
484       This replaces the previous options that were used when writing GIF
485       images.  Currently if you use an obsolete option, it will be converted
486       to the equivalent tag and Imager will produced a warning.  You can
487       suppress these warnings by calling the Imager::init() function with the
488       "warn_obsolete" option set to false:
489
490         Imager::init(warn_obsolete=>0);
491
492       At some point in the future these obsolete options will no longer be
493       supported.
494
495   PNM (Portable aNy Map)
496       Imager can write "PGM" (Portable Gray Map) and "PPM" (Portable PixMaps)
497       files, depending on the number of channels in the image.  Currently the
498       images are written in binary formats.  Only 1 and 3 channel images can
499       be written, including 1 and 3 channel paletted images.
500
501         $img->write(file=>'foo.ppm') or die $img->errstr;
502
503       Imager can read both the ASCII and binary versions of each of the "PBM"
504       (Portable BitMap), "PGM" and "PPM" formats.
505
506         $img->read(file=>'foo.ppm') or die $img->errstr;
507
508       PNM does not support the spatial resolution tags.
509
510       The following tags are set when reading a PNM file:
511
512       •   "pnm_maxval" - the "maxvals" number from the PGM/PPM header.
513           Always set to 2 for a "PBM" file.
514
515       •   "pnm_type" - the type number from the "PNM" header, 1 for ASCII
516           "PBM" files, 2 for ASCII "PGM" files, 3 for ASCII c<PPM> files, 4
517           for binary "PBM" files, 5 for binary "PGM" files, 6 for binary
518           "PPM" files.
519
520       The following tag is checked when writing an image with more than
521       8-bits/sample:
522
523       •   pnm_write_wide_data - if this is non-zero then write() can write
524           "PGM"/"PPM" files with 16-bits/sample.  Some applications, for
525           example GIMP 2.2, and tools can only read 8-bit/sample binary PNM
526           files, so Imager will only write a 16-bit image when this tag is
527           non-zero.
528
529   JPEG
530       You can supply a "jpegquality" parameter ranging from 0 (worst quality)
531       to 100 (best quality) when writing a JPEG file, which defaults to 75.
532
533         $img->write(file=>'foo.jpg', jpegquality=>90) or die $img->errstr;
534
535       If you write an image with an alpha channel to a JPEG file then it will
536       be composed against the background set by the "i_background" parameter
537       (or tag), or black if not supplied.
538
539       Imager will read a gray scale JPEG as a 1 channel image and a color
540       JPEG as a 3 channel image.
541
542         $img->read(file=>'foo.jpg') or die $img->errstr;
543
544       The following tags are set in a JPEG image when read, and can be set to
545       control output:
546
547       •   "jpeg_density_unit" - The value of the density unit field in the
548           "JFIF" header.  This is ignored on writing if the "i_aspect_only"
549           tag is non-zero.
550
551           The "i_xres" and "i_yres" tags are expressed in pixels per inch no
552           matter the value of this tag, they will be converted to/from the
553           value stored in the JPEG file.
554
555       •   "jpeg_density_unit_name" - This is set when reading a JPEG file to
556           the name of the unit given by "jpeg_density_unit".  Possible
557           results include "inch", "centimeter", "none" (the "i_aspect_only"
558           tag is also set reading these files).  If the value of
559           "jpeg_density_unit" is unknown then this tag isn't set.
560
561       •   "jpeg_comment" - Text comment.
562
563       •   "jpeg_progressive" - Whether the JPEG file is a progressive file.
564           (Imager 0.84)
565
566       JPEG supports the spatial resolution tags "i_xres", "i_yres" and
567       "i_aspect_only".
568
569       You can also set the following tags when writing to an image, they are
570       not set in the image when reading:
571
572       •   "jpeg_optimize" - set to a non-zero integer to compute optimal
573           Huffman coding tables for the image.  This will increase memory
574           usage and processing time (about 12% in my simple tests) but can
575           significantly reduce file size without a loss of quality.
576
577       •   "jpeg_compress_profile" - set to either "fastest", the default, or
578           only with "MozJPEG", to "max".  Setting this to any other value
579           will cause an error, failing the write() call.  Setting this to
580           "max" without "MozJPEG" will cause an error.
581
582             use Imager::File::JPEG;
583             my $prof = Imager::File::JPEG->is_mozjpeg ? "max" : "fastest";
584             $im->write(file => "foo.jpeg", jpeg_compress_profile => $prof)
585                or die $im->errstr;
586
587           Note that unlike "MozJPEG", Imager always defaults to "fastest".
588
589       •   "jpeg_tune" - corresponds to the "MozJPEG" "cjpeg" "-tune"
590           parameters, this can be any of:
591
592           •   "psnr"
593
594           •   "ssim"
595
596           •   "ms-ssim"
597
598           •   "hvs-psnr"
599
600           These set the same values as the "jpeg_base_quant_tbl_idx",
601           "jpeg_lambda_log_scale1", "jpeg_lambda_log_scale2" and
602           "jpeg_use_lambda_weight_tbl" tags, which can override the values
603           set by "jpeg_tune".
604
605           Unlike "cjpeg" "-tune", "jpeg_tune" doesn't force the quality to
606           75.
607
608           Requires that Imager::File::JPEG was built with "MozJPEG".
609
610       •   "jpeg_arithmetic" - if set to non-zero, use arithmetic coding when
611           writing the image.  This requires that the "libjpeg" variant that
612           Imager::File::JPEG was built with had encode support for arithmetic
613           coding enabled when it was built.
614
615
616
617
618           "jpeg_jfif" - if set to zero, disable writing the JFIF header even
619           if one is technically required, which it is for the color spaces
620           Imager works with.  This saves 18 bytes in the output file and most
621           applications including web browsers will successfully read the
622           file, but your experience may differ.
623
624           This will prevent the "i_xres", "i_yres" and "jpeg_density_units"
625           tags from having an effect.
626
627       •   "jpeg_smooth" - if set to a value from 1 to 100 apply smoothing to
628           the image to eliminate dithering noise (without modifying the
629           Imager image).  Default: 0 (no smoothing).
630
631
632
633
634           "jpeg_restart" - if set to a plain integer "N", generate a JPEG
635           restart marker every "N" rows, if set to an integer followed by
636           "B", generate a JPEG restart marker every "N" MCUs, the 8x8 pixel
637           blocks that make up a JPEG image.  Note that if this is specified
638           in rows it will be translated to MCUs by "libjpeg".
639
640           This allows a decoder to recover from corruption, but it makes the
641           file slightly larger.
642
643           Default: 0, no restart markers are produced.
644
645
646
647
648           "jpeg_sample" - control subsampling of the YCbCr components,
649           equivalent to the "-sample" parameter for "cjpeg".
650
651           Default: "2x2,1x1,1x1", default 4:2:0 JPEG subsampling.
652
653       The following options can be set on writing with "MozJPEG" and
654       correspond directly to the API options described in the "MozJPEG"
655       README-mozilla.txt.  Attempting to set them when Imager::File::JPEG has
656       been built with another "libjpeg" will result in an error.
657
658       •   "jpeg_optimize_scans", "jpeg_trellis_quant",
659           "jpeg_trellis_quant_dc", "jpeg_tresllis_eob_opt",
660           "jpeg_use_lambda_weight_tbl", "jpeg_use_scans_in_trellis",
661           "jpeg_overshoot_deringing" - boolean options, set to 0 or 1.
662
663           "jpeg_lambda_log_scale1", "jpeg_lambda_log_scale2",
664           "jpeg_trellis_delta_dc_weight" - integer options.
665
666           "jpeg_trellis_freq_split", "jpeg_trellis_num_loops",
667           "jpeg_base_quant_tbl_idx", "jpeg_dc_scan_opt_mode" - floating point
668           options.
669
670       When reading a JPEG image, the following tag will be set, and ignored
671       on writing:
672
673       •   "jpeg_read_arithmetic" - the image had been written with arithmetic
674           coding.  This uses a separate name from writing to avoid arithmetic
675           coding from being accidentally propagated to a file that might need
676           to be read by an implementation without arithmetic coding support.
677
678       If an "APP1" block containing EXIF information is found, then any of
679       the following tags can be set when reading a JPEG image:
680
681           exif_aperture exif_artist exif_brightness exif_color_space
682           exif_contrast exif_copyright exif_custom_rendered exif_date_time
683           exif_date_time_digitized exif_date_time_original
684           exif_digital_zoom_ratio exif_exposure_bias exif_exposure_index
685           exif_exposure_mode exif_exposure_program exif_exposure_time
686           exif_f_number exif_flash exif_flash_energy exif_flashpix_version
687           exif_focal_length exif_focal_length_in_35mm_film
688           exif_focal_plane_resolution_unit exif_focal_plane_x_resolution
689           exif_focal_plane_y_resolution exif_gain_control
690           exif_image_description exif_image_unique_id exif_iso_speed_rating
691           exif_make exif_max_aperture exif_metering_mode exif_model
692           exif_orientation exif_related_sound_file exif_resolution_unit
693           exif_saturation exif_scene_capture_type exif_sensing_method
694           exif_sharpness exif_shutter_speed exif_software
695           exif_spectral_sensitivity exif_sub_sec_time
696           exif_sub_sec_time_digitized exif_sub_sec_time_original
697           exif_subject_distance exif_subject_distance_range
698           exif_subject_location exif_tag_light_source exif_user_comment
699           exif_version exif_white_balance exif_x_resolution exif_y_resolution
700
701       The following derived tags can also be set when reading a JPEG image:
702
703           exif_color_space_name exif_contrast_name exif_custom_rendered_name
704           exif_exposure_mode_name exif_exposure_program_name exif_flash_name
705           exif_focal_plane_resolution_unit_name exif_gain_control_name
706           exif_light_source_name exif_metering_mode_name
707           exif_resolution_unit_name exif_saturation_name
708           exif_scene_capture_type_name exif_sensing_method_name
709           exif_sharpness_name exif_subject_distance_range_name
710           exif_white_balance_name
711
712       The derived tags are for enumerated fields, when the value for the base
713       field is valid then the text that appears in the EXIF specification for
714       that value appears in the derived field.  So for example if
715       "exf_metering_mode" is 5 then "exif_metering_mode_name" is set to
716       "Pattern".
717
718       eg.
719
720         my $image = Imager->new;
721         $image->read(file => 'exiftest.jpg')
722           or die "Cannot load image: ", $image->errstr;
723         print $image->tags(name => "exif_image_description"), "\n";
724         print $image->tags(name => "exif_exposure_mode"), "\n";
725         print $image->tags(name => "exif_exposure_mode_name"), "\n";
726
727         # for the exiftest.jpg in the Imager distribution the output would be:
728         Imager Development Notes
729         0
730         Auto exposure
731
732       Imager will not write EXIF tags to any type of image, if you need more
733       advanced EXIF handling, consider Image::ExifTool.
734
735       parseiptc()
736           Historically, Imager saves IPTC data when reading a JPEG image, the
737           parseiptc() method returns a list of key/value pairs resulting from
738           a simple decoding of that data.
739
740           Any future IPTC data decoding is likely to go into tags.
741
742   GIF
743       When writing one of more GIF images you can use the same Quantization
744       Options as you can when converting an RGB image into a paletted image.
745
746       When reading a GIF all of the sub-images are combined using the screen
747       size and image positions into one big image, producing an RGB image.
748       This may change in the future to produce a paletted image where
749       possible.
750
751       When you read a single GIF with "$img->read()" you can supply a
752       reference to a scalar in the "colors" parameter, if the image is read
753       the scalar will be filled with a reference to an anonymous array of
754       Imager::Color objects, representing the palette of the image.  This
755       will be the first palette found in the image.  If you want the palettes
756       for each of the images in the file, use read_multi() and use the
757       getcolors() method on each image.
758
759       GIF does not support the spatial resolution tags.
760
761       Imager will set the following tags in each image when reading, and can
762       use most of them when writing to GIF:
763
764       •   gif_left - the offset of the image from the left of the "screen"
765           ("Image Left Position")
766
767       •   gif_top - the offset of the image from the top of the "screen"
768           ("Image Top Position")
769
770       •   gif_interlace - non-zero if the image was interlaced ("Interlace
771           Flag")
772
773       •   gif_screen_width, gif_screen_height - the size of the logical
774           screen. When writing this is used as the minimum.  If any image
775           being written would extend beyond this then the screen size is
776           extended.  ("Logical Screen Width", "Logical Screen Height").
777
778       •   gif_local_map - Non-zero if this image had a local color map.  If
779           set for an image when writing the image is quantized separately
780           from the other images in the file.
781
782       •   gif_background - The index in the global color map of the logical
783           screen's background color.  This is only set if the current image
784           uses the global color map.  You can set this on write too, but for
785           it to choose the color you want, you will need to supply only
786           paletted images and set the "gif_eliminate_unused" tag to 0.
787
788       •   gif_trans_index - The index of the color in the color map used for
789           transparency.  If the image has a transparency then it is returned
790           as a 4 channel image with the alpha set to zero in this palette
791           entry.  This value is not used when writing. ("Transparent Color
792           Index")
793
794       •   gif_trans_color - A reference to an Imager::Color object, which is
795           the color to use for the palette entry used to represent
796           transparency in the palette.  You need to set the "transp" option
797           (see "Quantization options" in Imager::ImageTypes) for this value
798           to be used.
799
800       •   gif_delay - The delay until the next frame is displayed, in 1/100
801           of a second.  ("Delay Time").
802
803       •   gif_user_input - whether or not a user input is expected before
804           continuing (view dependent) ("User Input Flag").
805
806       •   gif_disposal - how the next frame is displayed ("Disposal Method")
807
808       •   gif_loop - the number of loops from the Netscape Loop extension.
809           This may be zero to loop forever.
810
811       •   gif_comment - the first block of the first GIF comment before each
812           image.
813
814       •   gif_eliminate_unused - If this is true, when you write a paletted
815           image any unused colors will be eliminated from its palette.  This
816           is set by default.
817
818       •   gif_colormap_size - the original size of the color map for the
819           image.  The color map of the image may have been expanded to
820           include out of range color indexes.
821
822       Where applicable, the ("name") is the name of that field from the
823       "GIF89" standard.
824
825       The following GIF writing options are obsolete, you should set the
826       corresponding tag in the image, either by using the tags functions, or
827       by supplying the tag and value as options.
828
829       •   gif_each_palette - Each image in the GIF file has it's own palette
830           if this is non-zero.  All but the first image has a local color
831           table (the first uses the global color table.
832
833           Use "gif_local_map" in new code.
834
835       •   interlace - The images are written interlaced if this is non-zero.
836
837           Use "gif_interlace" in new code.
838
839       •   gif_delays - A reference to an array containing the delays between
840           images, in 1/100 seconds.
841
842           Use "gif_delay" in new code.
843
844       •   gif_positions - A reference to an array of references to arrays
845           which represent screen positions for each image.
846
847           New code should use the "gif_left" and "gif_top" tags.
848
849       •   gif_loop_count - If this is non-zero the Netscape loop extension
850           block is generated, which makes the animation of the images repeat.
851
852           This is currently unimplemented due to some limitations in
853           "giflib".
854
855       You can supply a "page" parameter to the read() method to read some
856       page other than the first.  The page is 0 based:
857
858         # read the second image in the file
859         $image->read(file=>"example.gif", page=>1)
860           or die "Cannot read second page: ",$image->errstr,"\n";
861
862       Before release 0.46, Imager would read multiple image GIF image files
863       into a single image, overlaying each of the images onto the virtual GIF
864       screen.
865
866       As of 0.46 the default is to read the first image from the file, as if
867       called with "page => 0".
868
869       You can return to the previous behavior by calling read with the
870       "gif_consolidate" parameter set to a true value:
871
872         $img->read(file=>$some_gif_file, gif_consolidate=>1);
873
874       As with the to_paletted() method, if you supply a colors parameter as a
875       reference to an array, this will be filled with Imager::Color objects
876       of the color table generated for the image file.
877
878   TIFF (Tagged Image File Format)
879       Imager can write images to either paletted or RGB TIFF images,
880       depending on the type of the source image.
881
882       When writing direct color images to TIFF the sample size of the output
883       file depends on the input:
884
885       •   double/sample - written as 32-bit/sample TIFF
886
887       •   16-bit/sample - written as 16-bit/sample TIFF
888
889       •   8-bit/sample - written as 8-bit/sample TIFF
890
891       For paletted images:
892
893       •   "$img->is_bilevel" is true - the image is written as bi-level
894
895       •   otherwise - image is written as paletted.
896
897       If you are creating images for faxing you can set the class parameter
898       set to "fax".  By default the image is written in fine mode, but this
899       can be overridden by setting the fax_fine parameter to zero.  Since a
900       fax image is bi-level, Imager uses a threshold to decide if a given
901       pixel is black or white, based on a single channel.  For gray scale
902       images channel 0 is used, for color images channel 1 (green) is used.
903       If you want more control over the conversion you can use
904       $img->to_paletted() to product a bi-level image.  This way you can use
905       dithering:
906
907         my $bilevel = $img->to_paletted(make_colors => 'mono',
908                                         translate => 'errdiff',
909                                         errdiff => 'stucki');
910
911       •   "class" - If set to 'fax' the image will be written as a bi-level
912           fax image.
913
914       •   "fax_fine" - By default when "class" is set to 'fax' the image is
915           written in fine mode, you can select normal mode by setting
916           "fax_fine" to 0.
917
918       Imager should be able to read any TIFF image you supply.  Paletted TIFF
919       images are read as paletted Imager images, since paletted TIFF images
920       have 16-bits/sample (48-bits/color) this means the bottom 8-bits are
921       lost, but this shouldn't be a big deal.
922
923       TIFF supports the spatial resolution tags.  See the
924       "tiff_resolutionunit" tag for some extra options.
925
926       As of Imager 0.62 Imager reads:
927
928       •   8-bit/sample gray, RGB or CMYK images, including a possible alpha
929           channel as an 8-bit/sample image.
930
931       •   16-bit gray, RGB, or CMYK image, including a possible alpha channel
932           as a 16-bit/sample image.
933
934       •   32-bit gray, RGB image, including a possible alpha channel as a
935           double/sample image.
936
937       •   bi-level images as paletted images containing only black and white,
938           which other formats will also write as bi-level.
939
940       •   tiled paletted images are now handled correctly
941
942       •   other images are read using "tifflib"'s RGBA interface as
943           8-bit/sample images.
944
945       The following tags are set in a TIFF image when read, and can be set to
946       control output:
947
948       •   "tiff_compression" - When reading an image this is set to the
949           numeric value of the TIFF compression tag.
950
951           On writing you can set this to either a numeric compression tag
952           value, or one of the following values:
953
954             Ident     Number  Description
955             none         1    No compression
956             packbits   32773  Macintosh RLE
957             ccittrle     2    CCITT RLE
958             fax3         3    CCITT Group 3 fax encoding (T.4)
959             t4           3    As above
960             fax4         4    CCITT Group 4 fax encoding (T.6)
961             t6           4    As above
962             lzw          5    LZW
963             jpeg         7    JPEG
964             zip          8    Deflate (GZIP) Non-standard
965             deflate      8    As above.
966             oldzip     32946  Deflate with an older code.
967             ccittrlew  32771  Word aligned CCITT RLE
968
969           In general a compression setting will be ignored where it doesn't
970           make sense, eg. "jpeg" will be ignored for compression if the image
971           is being written as bilevel.
972
973           Imager attempts to check that your build of "libtiff" supports the
974           given compression, and will fallback to "packbits" if it isn't
975           enabled.  eg. older distributions didn't include LZW compression,
976           and JPEG compression is only available if "libtiff" is configured
977           with "libjpeg"'s location.
978
979             $im->write(file => 'foo.tif', tiff_compression => 'lzw')
980               or die $im->errstr;
981
982       •   "tags, tiff_jpegquality""tiff_jpegquality" - If "tiff_compression"
983           is "jpeg" then this can be a number from 1 to 100 giving the JPEG
984           compression quality.  High values are better quality and larger
985           files.
986
987       •   "tiff_resolutionunit" - The value of the "ResolutionUnit" tag.
988           This is ignored on writing if the i_aspect_only tag is non-zero.
989
990           The "i_xres" and "i_yres" tags are expressed in pixels per inch no
991           matter the value of this tag, they will be converted to/from the
992           value stored in the TIFF file.
993
994       •   "tiff_resolutionunit_name" - This is set when reading a TIFF file
995           to the name of the unit given by "tiff_resolutionunit".  Possible
996           results include "inch", "centimeter", "none" (the "i_aspect_only"
997           tag is also set reading these files) or "unknown".
998
999       •   "tiff_bitspersample" - Bits per sample from the image.  This value
1000           is not used when writing an image, it is only set on a read image.
1001
1002       •   "tiff_photometric" - Value of the "PhotometricInterpretation" tag
1003           from the image.  This value is not used when writing an image, it
1004           is only set on a read image.
1005
1006       •   "tiff_documentname", "tiff_imagedescription", "tiff_make",
1007           "tiff_model", "tiff_pagename", "tiff_software", "tiff_datetime",
1008           "tiff_artist", "tiff_hostcomputer" - Various strings describing the
1009           image.  "tiff_datetime" must be formatted as "YYYY:MM:DD HH:MM:SS".
1010           These correspond directly to the mixed case names in the TIFF
1011           specification.  These are set in images read from a TIFF and saved
1012           when writing a TIFF image.
1013
1014       You can supply a "page" parameter to the read() method to read some
1015       page other than the first.  The page is 0 based:
1016
1017         # read the second image in the file
1018         $image->read(file=>"example.tif", page=>1)
1019           or die "Cannot read second page: ",$image->errstr,"\n";
1020
1021       If you read an image with multiple alpha channels, then only the first
1022       alpha channel will be read.
1023
1024       When reading a "TIFF" image with callbacks, the "seekcb" callback
1025       parameter is also required.
1026
1027       When writing a "TIFF" image with callbacks, the "seekcb" and "readcb"
1028       parameters are also required.
1029
1030       "TIFF" is a random access file format, it cannot be read from or
1031       written to unseekable streams such as pipes or sockets.
1032
1033   BMP (Windows Bitmap)
1034       Imager can write 24-bit RGB, and 8, 4 and 1-bit per pixel paletted
1035       Windows BMP files.  Currently you cannot write compressed BMP files
1036       with Imager.
1037
1038       Imager can read 24-bit RGB, and 8, 4 and 1-bit perl pixel paletted
1039       Windows BMP files.  There is some support for reading 16-bit per pixel
1040       images, but I haven't found any for testing.
1041
1042       BMP has no support for multiple image files.
1043
1044       BMP files support the spatial resolution tags, but since BMP has no
1045       support for storing only an aspect ratio, if "i_aspect_only" is set
1046       when you write the "i_xres" and "i_yres" values are scaled so the
1047       smaller is 72 DPI.
1048
1049       The following tags are set when you read an image from a BMP file:
1050
1051       bmp_compression
1052           The type of compression, if any.  This can be any of the following
1053           values:
1054
1055           BI_RGB (0)
1056               Uncompressed.
1057
1058           BI_RLE8 (1)
1059               8-bits/pixel paletted value RLE compression.
1060
1061           BI_RLE4 (2)
1062               4-bits/pixel paletted value RLE compression.
1063
1064           BI_BITFIELDS (3)
1065               Packed RGB values.
1066
1067       bmp_compression_name
1068           The bmp_compression value as a BI_* string
1069
1070       bmp_important_colors
1071           The number of important colors as defined by the writer of the
1072           image.
1073
1074       bmp_used_colors
1075           Number of color used from the BMP header
1076
1077       bmp_filesize
1078           The file size from the BMP header
1079
1080       bmp_bit_count
1081           Number of bits stored per pixel. (24, 8, 4 or 1)
1082
1083   TGA (Targa)
1084       When storing Targa images RLE compression can be activated with the
1085       "compress" parameter, the "idstring" parameter can be used to set the
1086       Targa comment field and the "wierdpack" option can be used to use the
1087       15 and 16 bit Targa formats for RGB and RGBA data.  The 15 bit format
1088       has 5 of each red, green and blue.  The 16 bit format in addition
1089       allows 1 bit of alpha.  The most significant bits are used for each
1090       channel.
1091
1092       Tags:
1093
1094       tga_idstring
1095       tga_bitspp
1096       compressed
1097
1098   RAW
1099       When reading raw images you need to supply the width and height of the
1100       image in the "xsize" and "ysize" options:
1101
1102         $img->read(file=>'foo.raw', xsize=>100, ysize=>100)
1103           or die "Cannot read raw image\n";
1104
1105       If your input file has more channels than you want, or (as is common),
1106       junk in the fourth channel, you can use the "raw_datachannels" and
1107       "raw_storechannels" options to control the number of channels in your
1108       input file and the resulting channels in your image.  For example, if
1109       your input image uses 32-bits per pixel with red, green, blue and junk
1110       values for each pixel you could do:
1111
1112         $img->read(file=>'foo.raw', xsize => 100, ysize => 100,
1113                    raw_datachannels => 4, raw_storechannels => 3,
1114                    raw_interleave => 0)
1115           or die "Cannot read raw image\n";
1116
1117       In general, if you supply "raw_storechannels" you should also supply
1118       "raw_datachannels"
1119
1120       Read parameters:
1121
1122       •   "raw_interleave" - controls the ordering of samples within the
1123           image.  Default: 1.  Alternatively and historically spelled
1124           "interleave".  Possible values:
1125
1126           •   0 - samples are pixel by pixel, so all samples for the first
1127               pixel, then all samples for the second pixel and so on.  eg.
1128               for a four pixel scan line the channels would be laid out as:
1129
1130                 012012012012
1131
1132           •   1 - samples are line by line, so channel 0 for the entire scan
1133               line is followed by channel 1 for the entire scan line and so
1134               on.  eg. for a four pixel scan line the channels would be laid
1135               out as:
1136
1137                 000011112222
1138
1139               This is the default.
1140
1141           Unfortunately, historically, the default "raw_interleave" for read
1142           has been 1, while writing only supports the "raw_interleave" = 0
1143           format.
1144
1145           For future compatibility, you should always supply the
1146           "raw_interleave" (or "interleave") parameter.  As of 0.68, Imager
1147           will warn if you attempt to read a raw image without a
1148           "raw_interleave" parameter.
1149
1150       •   "raw_storechannels" - the number of channels to store in the image.
1151           Range: 1 to 4.  Default: 3.  Alternatively and historically spelled
1152           "storechannels".
1153
1154       •   "raw_datachannels" - the number of channels to read from the file.
1155           Range: 1 or more.  Default: 3.  Alternatively and historically
1156           spelled "datachannels".
1157
1158         $img->read(file=>'foo.raw', xsize=100, ysize=>100, raw_interleave=>1)
1159           or die "Cannot read raw image\n";
1160
1161   PNG
1162       PNG Image modes
1163
1164       PNG files can be read and written in the following modes:
1165
1166       •   bi-level - written as a 1-bit per sample gray scale image
1167
1168       •   paletted - Imager gray scale paletted images are written as RGB
1169           paletted images.  PNG palettes can include alpha values for each
1170           entry and this is honored as an Imager four channel paletted image.
1171
1172       •   8 and 16-bit per sample gray scale, optionally with an alpha
1173           channel.
1174
1175       •   8 and 16-bit per sample RGB, optionally with an alpha channel.
1176
1177       Unlike GIF, there is no automatic conversion to a paletted image, since
1178       PNG supports direct color.
1179
1180       PNG Text tags
1181
1182       Text tags are retrieved from and written to PNG "tEXT" or "zTXT"
1183       chunks.  The following standard tags from the PNG specification are
1184       directly supported:
1185
1186       •   "i_comment" - keyword of "Comment".
1187
1188       •   "png_author" - keyword "Author".
1189
1190       •   "png_copyright" - keyword "Copyright".
1191
1192       •   "png_creation_time" - keyword "Creation Time".
1193
1194       •   "png_description" - keyword "Description".
1195
1196       •   "png_disclaimer" - keyword "Disclaimer".
1197
1198       •   "png_software" - keyword "Software".
1199
1200       •   "png_title" - keyword "Title".
1201
1202       •   "png_warning" - keyword "Warning".
1203
1204       Each of these tags has a corresponding "base-tag-name_compressed" tag,
1205       eg. "png_comment_compressed".  When reading, if the PNG chunk is
1206       compressed this tag will be set to 1, but is otherwise unset.  When
1207       writing, Imager will honor the compression tag if set and non-zero,
1208       otherwise the chunk text will be compressed if the value is longer than
1209       1000 characters, as recommended by the "libpng" documentation.
1210
1211       PNG "tEXT" or "zTXT" chunks outside of those above are read into or
1212       written from Imager tags named like:
1213
1214       •   "png_textN_key" - the key for the text chunk.  This can be 1 to 79
1215           characters, may not contain any leading, trailing or consecutive
1216           spaces, and may contain only Latin-1 characters from 32-126,
1217           161-255.
1218
1219       •   "png_textN_text" - the text for the text chunk.  This may not
1220           contain any "NUL" characters.
1221
1222       •   "png_textN_compressed" - whether or not the text chunk is
1223           compressed.  This behaves similarly to the
1224           "base-tag-name_compressed" tags described above.
1225
1226       Where N starts from 0.  When writing both the "..._key" and "..._text"
1227       tags must be present or the write will fail.  If the key or text do not
1228       satisfy the requirements above the write will fail.
1229
1230       Other PNG metadata tags
1231
1232       •   "png_interlace", "png_interlace_name" - only set when reading,
1233           "png_interlace" is set to the type of interlacing used by the file,
1234           0 for one, 1 for Adam7.  "png_interlace_name" is set to a keyword
1235           describing the interlacing, either "none" or "adam7".
1236
1237       •   "png_srgb_intent" - the sRGB rendering intent for the image. an
1238           integer from 0 to 3, per the PNG specification.  If this chunk is
1239           found in the PNG file the "gAMA" and "cHRM" are ignored and the
1240           "png_gamma" and "png_chroma_..." tags are not set.  Similarly when
1241           writing if "png_srgb_intent" is set the "gAMA" and "cHRM" chunks
1242           are not written.
1243
1244       •   "png_gamma" - the gamma of the image. This value is not currently
1245           used by Imager when processing the image, but this may change in
1246           the future.
1247
1248       •   "png_chroma_white_x", "png_chroma_white_y", "png_chroma_red_x",
1249           "png_chroma_red_y", "png_chroma_green_x", "png_chroma_green_y",
1250           "png_chroma_blue_x", "png_chroma_blue_y" - the primary
1251           chromaticities of the image, defining the color model.  This is
1252           currently not used by Imager when processing the image, but this
1253           may change in the future.
1254
1255       •   "i_xres", "i_yres", "i_aspect_only" - processed per
1256           Imager::ImageTypes/CommonTags.
1257
1258       •   "png_bits" - the number of bits per sample in the representation.
1259           Ignored when writing.
1260
1261       •   "png_time" - the creation time of the file formatted as
1262           "year-month-dayThour:minute:second".  This is stored as time data
1263           structure in the file, not a string.  If you set "png_time" and it
1264           cannot be parsed as above, writing the PNG file will fail.
1265
1266       •   "i_background" - set from the "sBKG" when reading an image file.
1267
1268       You can control the level of zlib compression used when writing with
1269       the "png_compression_level" parameter.  This can be an integer between
1270       0 (uncompressed) and 9 (best compression).
1271
1272       If you're using libpng 1.6 or later, or an earlier release configured
1273       with "PNG_BENIGN_ERRORS_SUPPORTED", you can choose to ignore file
1274       format errors the authors of libpng consider benign, this includes at
1275       least CRC errors and palette index overflows.  Do this by supplying a
1276       true value for the "png_ignore_benign_errors" parameter to the read()
1277       method:
1278
1279         $im->read(file => "foo.png", png_ignore_benign_errors => 1)
1280           or die $im->errstr;
1281
1282   ICO (Microsoft Windows Icon) and CUR (Microsoft Windows Cursor)
1283       Icon and Cursor files are very similar, the only differences being a
1284       number in the header and the storage of the cursor hot spot.  I've
1285       treated them separately so that you're not messing with tags to
1286       distinguish between them.
1287
1288       The following tags are set when reading an icon image and are used when
1289       writing it:
1290
1291       ico_mask
1292           This is the AND mask of the icon.  When used as an icon in Windows
1293           1 bits in the mask correspond to pixels that are modified by the
1294           source image rather than simply replaced by the source image.
1295
1296           Rather than requiring a binary bitmap this is accepted in a
1297           specific format:
1298
1299           •   first line consisting of the 0 placeholder, the 1 placeholder
1300               and a newline.
1301
1302           •   following lines which contain 0 and 1 placeholders for each
1303               scan line of the image, starting from the top of the image.
1304
1305           When reading an image, '.' is used as the 0 placeholder and '*' as
1306           the 1 placeholder.  An example:
1307
1308             .*
1309             ..........................******
1310             ..........................******
1311             ..........................******
1312             ..........................******
1313             ...........................*****
1314             ............................****
1315             ............................****
1316             .............................***
1317             .............................***
1318             .............................***
1319             .............................***
1320             ..............................**
1321             ..............................**
1322             ...............................*
1323             ...............................*
1324             ................................
1325             ................................
1326             ................................
1327             ................................
1328             ................................
1329             ................................
1330             *...............................
1331             **..............................
1332             **..............................
1333             ***.............................
1334             ***.............................
1335             ****............................
1336             ****............................
1337             *****...........................
1338             *****...........................
1339             *****...........................
1340             *****...........................
1341
1342       The following tags are set when reading an icon:
1343
1344       ico_bits
1345           The number of bits per pixel used to store the image.
1346
1347       For cursor files the following tags are set and read when reading and
1348       writing:
1349
1350       cur_mask
1351           This is the same as the ico_mask above.
1352
1353       cur_hotspotx
1354       cur_hotspoty
1355           The "hot" spot of the cursor image.  This is the spot on the cursor
1356           that you click with.  If you set these to out of range values they
1357           are clipped to the size of the image when written to the file.
1358
1359       The following parameters can be supplied to read() or read_multi() to
1360       control reading of ICO/CUR files:
1361
1362       •   "ico_masked" - if true, the default, then the icon/cursors mask is
1363           applied as an alpha channel to the image, unless that image already
1364           has an alpha channel.  This may result in a paletted image being
1365           returned as a direct color image.  Default: 1
1366
1367             # retrieve the image as stored, without using the mask as an alpha
1368             # channel
1369             $img->read(file => 'foo.ico', ico_masked => 0)
1370               or die $img->errstr;
1371
1372           This was introduced in Imager 0.60.  Previously reading ICO images
1373           acted as if "ico_masked => 0".
1374
1375       •   "ico_alpha_masked" - if true, then the icon/cursor mask is applied
1376           as an alpha channel to images that already have an alpha mask.
1377           Note that this will only make pixels transparent, not opaque.
1378           Default: 0.
1379
1380           Note: If you get different results between "ico_alpha_masked" being
1381           set to 0 and 1, your mask may break when used with the Win32 API.
1382
1383       "cur_bits" is set when reading a cursor.
1384
1385       Examples:
1386
1387         my $img = Imager->new(xsize => 32, ysize => 32, channels => 4);
1388         $im->box(color => 'FF0000');
1389         $im->write(file => 'box.ico');
1390
1391         $im->settag(name => 'cur_hotspotx', value => 16);
1392         $im->settag(name => 'cur_hotspoty', value => 16);
1393         $im->write(file => 'box.cur');
1394
1395   SGI (RGB, BW)
1396       SGI images, often called by the extensions, RGB or BW, can be stored
1397       either uncompressed or compressed using an RLE compression.
1398
1399       By default, when saving to an extension of "rgb", "bw", "sgi", "rgba"
1400       the file will be saved in SGI format.  The file extension is otherwise
1401       ignored, so saving a 3-channel image to a ".bw" file will result in a
1402       3-channel image on disk.
1403
1404       The following tags are set when reading a SGI image:
1405
1406       •   i_comment - the "IMAGENAME" field from the image.  Also written to
1407           the file when writing.
1408
1409       •   sgi_pixmin, sgi_pixmax - the "PIXMIN" and "PIXMAX" fields from the
1410           image.  On reading image data is expanded from this range to the
1411           full range of samples in the image.
1412
1413       •   sgi_bpc - the number of bytes per sample for the image.  Ignored
1414           when writing.
1415
1416       •   sgi_rle - whether or not the image is compressed.  If this is non-
1417           zero when writing the image will be compressed.
1418

ADDING NEW FORMATS

1420       To support a new format for reading, call the register_reader() class
1421       method:
1422
1423       register_reader()
1424           Registers single or multiple image read functions.
1425
1426           Parameters:
1427
1428           •   type - the identifier of the file format, if Imager's
1429               i_test_format_probe() can identify the format then this value
1430               should match i_test_format_probe()'s result.
1431
1432               This parameter is required.
1433
1434           •   single - a code ref to read a single image from a file.  This
1435               is supplied:
1436
1437               •   the object that read() was called on,
1438
1439               •   an Imager::IO object that should be used to read the file,
1440                   and
1441
1442               •   all the parameters supplied to the read() method.
1443
1444               The single parameter is required.
1445
1446           •   multiple - a code ref which is called to read multiple images
1447               from a file. This is supplied:
1448
1449               •   an Imager::IO object that should be used to read the file,
1450                   and
1451
1452               •   all the parameters supplied to the read_multi() method.
1453
1454           Example:
1455
1456             # from Imager::File::ICO
1457             Imager->register_reader
1458               (
1459                type=>'ico',
1460                single =>
1461                sub {
1462                  my ($im, $io, %hsh) = @_;
1463                  $im->{IMG} = i_readico_single($io, $hsh{page} || 0);
1464
1465                  unless ($im->{IMG}) {
1466                    $im->_set_error(Imager->_error_as_msg);
1467                    return;
1468                  }
1469                  return $im;
1470                },
1471                multiple =>
1472                sub {
1473                  my ($io, %hsh) = @_;
1474
1475                  my @imgs = i_readico_multi($io);
1476                  unless (@imgs) {
1477                    Imager->_set_error(Imager->_error_as_msg);
1478                    return;
1479                  }
1480                  return map {
1481                    bless { IMG => $_, DEBUG => $Imager::DEBUG, ERRSTR => undef }, 'Imager'
1482                  } @imgs;
1483                },
1484               );
1485
1486       register_writer()
1487           Registers single or multiple image write functions.
1488
1489           Parameters:
1490
1491           •   type - the identifier of the file format.  This is typically
1492               the extension in lowercase.
1493
1494               This parameter is required.
1495
1496           •   single - a code ref to write a single image to a file.  This is
1497               supplied:
1498
1499               •   the object that write() was called on,
1500
1501               •   an Imager::IO object that should be used to write the file,
1502                   and
1503
1504               •   all the parameters supplied to the write() method.
1505
1506               The single parameter is required.
1507
1508           •   multiple - a code ref which is called to write multiple images
1509               to a file. This is supplied:
1510
1511               •   the class name write_multi() was called on, this is
1512                   typically "Imager".
1513
1514               •   an Imager::IO object that should be used to write the file,
1515                   and
1516
1517               •   all the parameters supplied to the read_multi() method.
1518
1519       add_type_extensions($type, $ext, ...)
1520           This class method can be used to add extensions to the map used by
1521           "def_guess_type" when working out the file type a filename
1522           extension.
1523
1524             Imager->add_type_extension(mytype => "mytype", "mytypish");
1525             ...
1526             $im->write(file => "foo.mytypish") # use the mytype handler
1527
1528       If you name the reader module "Imager::File::"your-format-name where
1529       your-format-name is a fully upper case version of the type value you
1530       would pass to read(), read_multi(), write() or write_multi() then
1531       Imager will attempt to load that module if it has no other way to read
1532       or write that format.
1533
1534       For example, if you create a module Imager::File::GIF and the user has
1535       built Imager without it's normal GIF support then an attempt to read a
1536       GIF image will attempt to load Imager::File::GIF.
1537
1538       If your module can only handle reading then you can name your module
1539       "Imager::File::"your-format-name"Reader" and Imager will attempt to
1540       autoload it.
1541
1542       If your module can only handle writing then you can name your module
1543       "Imager::File::"your-format-name"Writer" and Imager will attempt to
1544       autoload it.
1545

PRELOADING FILE MODULES

1547       preload()
1548           "Imager-"preload> preloads the file support modules included with
1549           or that have been included with Imager in the past.
1550
1551           It isn't typically needed, but some cases where you might want to
1552           use it:
1553
1554           •   For use in forking servers such as mod_perl to allow as many
1555               pages as possible to be shared between parent and child
1556               processes.
1557
1558           •   to avoid runtime loading of a module from delaying output in an
1559               animation.
1560
1561           •   if you're loading modules from a relative $ENV{PERL5LIB} and
1562               expect to change directories.
1563
1564           You probably don't need it.
1565
1566           If the module is not available no error occurs.
1567
1568           Preserves $@.
1569
1570             use Imager;
1571             Imager->preload;
1572

EXAMPLES

1574   Producing an image from a CGI script
1575       Once you have an image the basic mechanism is:
1576
1577       1.  set STDOUT to autoflush
1578
1579       2.  output a content-type header, and optionally a content-length
1580           header
1581
1582       3.  put STDOUT into binmode
1583
1584       4.  call write() with the "fd" or "fh" parameter.  You will need to
1585           provide the "type" parameter since Imager can't use the extension
1586           to guess the file format you want.
1587
1588         # write an image from a CGI script
1589         # using CGI.pm
1590         use CGI qw(:standard);
1591         $| = 1;
1592         binmode STDOUT;
1593         print header(-type=>'image/gif');
1594         $img->write(type=>'gif', fd=>fileno(STDOUT))
1595           or die $img->errstr;
1596
1597       If you want to send a content length you can send the output to a
1598       scalar to get the length:
1599
1600         my $data;
1601         $img->write(type=>'gif', data=>\$data)
1602           or die $img->errstr;
1603         binmode STDOUT;
1604         print header(-type=>'image/gif', -content_length=>length($data));
1605         print $data;
1606
1607   Writing an animated GIF
1608       The basic idea is simple, just use write_multi():
1609
1610         my @imgs = ...;
1611         Imager->write_multi({ file=>$filename, type=>'gif' }, @imgs);
1612
1613       If your images are RGB images the default quantization mechanism will
1614       produce a very good result, but can take a long time to execute.  You
1615       could either use the standard web color map:
1616
1617         Imager->write_multi({ file=>$filename,
1618                               type=>'gif',
1619                               make_colors=>'webmap' },
1620                             @imgs);
1621
1622       or use a median cut algorithm to built a fairly optimal color map:
1623
1624         Imager->write_multi({ file=>$filename,
1625                               type=>'gif',
1626                               make_colors=>'mediancut' },
1627                             @imgs);
1628
1629       By default all of the images will use the same global color map, which
1630       will produce a smaller image.  If your images have significant color
1631       differences, you may want to generate a new palette for each image:
1632
1633         Imager->write_multi({ file=>$filename,
1634                               type=>'gif',
1635                               make_colors=>'mediancut',
1636                               gif_local_map => 1 },
1637                             @imgs);
1638
1639       which will set the "gif_local_map" tag in each image to 1.
1640       Alternatively, if you know only some images have different colors, you
1641       can set the tag just for those images:
1642
1643         $imgs[2]->settag(name=>'gif_local_map', value=>1);
1644         $imgs[4]->settag(name=>'gif_local_map', value=>1);
1645
1646       and call write_multi() without a "gif_local_map" parameter, or supply
1647       an arrayref of values for the tag:
1648
1649         Imager->write_multi({ file=>$filename,
1650                               type=>'gif',
1651                               make_colors=>'mediancut',
1652                               gif_local_map => [ 0, 0, 1, 0, 1 ] },
1653                             @imgs);
1654
1655       Other useful parameters include "gif_delay" to control the delay
1656       between frames and "transp" to control transparency.
1657
1658   Reading tags after reading an image
1659       This is pretty simple:
1660
1661         # print the author of a TIFF, if any
1662         my $img = Imager->new;
1663         $img->read(file=>$filename, type='tiff') or die $img->errstr;
1664         my $author = $img->tags(name=>'tiff_author');
1665         if (defined $author) {
1666           print "Author: $author\n";
1667         }
1668

BUGS

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

SEE ALSO

1675       Imager(3)
1676

AUTHOR

1678       Tony Cook <tonyc@cpan.org>, Arnar M. Hrafnkelsson
1679
1680
1681
1682perl v5.38.0                      2023-07-20                  Imager::Files(3)
Impressum