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         my $fh = ... ; # eg. IO::File
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()"
79           method 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       When you read an image, Imager may set some tags, possibly including
171       information about the spatial resolution, textual information, and
172       animation information.  See "Tags" in Imager::ImageTypes for specifics.
173
174       The open() method is a historical alias for the read() method.
175
176   Input and output
177       When reading or writing you can specify one of a variety of sources or
178       targets:
179
180       •   "file" - The "file" parameter is the name of the image file to be
181           written to or read from.  If Imager recognizes the extension of the
182           file you do not need to supply a "type".
183
184             # write in tiff format
185             $image->write(file => "example.tif")
186               or die $image->errstr;
187
188             $image->write(file => 'foo.tmp', type => 'tiff')
189               or die $image->errstr;
190
191             my $image = Imager->new;
192             $image->read(file => 'example.tif')
193               or die $image->errstr;
194
195       •   "fh" - "fh" is a file handle, typically either returned from
196           "<IO::File-"new()>>, or a glob from an "open" call.  You should
197           call "binmode" on the handle before passing it to Imager.
198
199           Imager will set the handle to autoflush to make sure any buffered
200           data is flushed , since Imager will write to the file descriptor
201           (from fileno()) rather than writing at the perl level.
202
203             $image->write(fh => \*STDOUT, type => 'gif')
204               or die $image->errstr;
205
206             # for example, a file uploaded via CGI.pm
207             $image->read(fd => $cgi->param('file'))
208               or die $image->errstr;
209
210       •   "fd" - "fd" is a file descriptor.  You can get this by calling the
211           "fileno()" function on a file handle, or by using one of the
212           standard file descriptor numbers.
213
214           If you get this from a perl file handle, you may need to flush any
215           buffered output, otherwise it may appear in the output stream after
216           the image.
217
218             $image->write(fd => file(STDOUT), type => 'gif')
219               or die $image->errstr;
220
221       •   "data" - When reading data, "data" is a scalar containing the image
222           file data, or a reference to such a scalar.  When writing, "data"
223           is a reference to the scalar to save the image file data to.
224
225             my $data;
226             $image->write(data => \$data, type => 'tiff')
227               or die $image->errstr;
228
229             my $data = $row->{someblob}; # eg. from a database
230             my @images = Imager->read_multi(data => $data)
231               or die Imager->errstr;
232
233             # from Imager 0.99
234             my @images = Imager->read_multi(data => \$data)
235               or die Imager->errstr;
236
237       •   "callback", "readcb", "writecb", "seekcb", "closecb" - Imager will
238           make calls back to your supplied coderefs to read, write and seek
239           from/to/through the image file.  See "I/O Callbacks" below for
240           details.
241
242       •   "io" - an Imager::IO object.
243
244       By default Imager will use buffered I/O when reading or writing an
245       image.  You can disabled buffering for output by supplying a "buffered
246       => 0" parameter to "write()" or "write_multi()".
247
248   I/O Callbacks
249       When reading from a file you can use either "callback" or "readcb" to
250       supply the read callback, and when writing "callback" or "writecb" to
251       supply the write callback.
252
253       Whether reading or writing a "TIFF" image, "seekcb" and "readcb" are
254       required.
255
256       If a file handler attempts to use "readcb", "writecb" or "seekcb" and
257       you haven't supplied one, the call will fail, failing the image read or
258       write, returning an error message indicating that the callback is
259       missing:
260
261         # attempting to read a TIFF image without a seekcb
262         open my $fh, "<", $filename or die;
263         my $rcb = sub {
264           my $val;
265           read($fh, $val, $_[0]) or return "";
266           return $val;
267         };
268         my $im = Imager->new(callback => $rcb)
269           or die Imager->errstr
270         # dies with (wrapped here):
271         # Error opening file: (Iolayer): Failed to read directory at offset 0:
272         # (Iolayer): Seek error accessing TIFF directory: seek callback called
273         # but no seekcb supplied
274
275       You can also provide a "closecb" parameter called when writing the file
276       is complete.  If no "closecb" is supplied the default will succeed
277       silently.
278
279         # contrived
280         my $data;
281         sub mywrite {
282           $data .= unpack("H*", shift);
283           1;
284         }
285         Imager->write_multi({ callback => \&mywrite, type => 'gif'}, @images)
286           or die Imager->errstr;
287
288       "readcb"
289
290       The read callback is called with 2 parameters:
291
292       •   "size" - the minimum amount of data required.
293
294       •   "maxsize" - previously this was the maximum amount of data
295           returnable - currently it's always the same as "size"
296
297       Your read callback should return the data as a scalar:
298
299       •   on success, a string containing the bytes read.
300
301       •   on end of file, an empty string
302
303       •   on error, "undef".
304
305       If your return value contains more data than "size" Imager will panic.
306
307       Your return value must not contain any characters over "\xFF" or Imager
308       will panic.
309
310       "writecb"
311
312       Your write callback takes exactly one parameter, a scalar containing
313       the data to be written.
314
315       Return true for success.
316
317       "seekcb"
318
319       The seek callback takes 2 parameters, a POSITION, and a WHENCE, defined
320       in the same way as perl's seek function.
321
322       Previously you always needed a "seekcb" callback if you called Imager's
323       "read()" or "read_multi()" without a "type" parameter, but this is no
324       longer necessary unless the file handler requires seeking, such as for
325       TIFF files.
326
327       Returns the new position in the file, or -1 on failure.
328
329       "closecb"
330
331       You can also supply a "closecb" which is called with no parameters when
332       there is no more data to be written.  This could be used to flush
333       buffered data.
334
335       Return true on success.
336
337   Guessing types
338       When writing to a file, if you don't supply a "type" parameter Imager
339       will attempt to guess it from the file name.  This is done by calling
340       the code reference stored in $Imager::FORMATGUESS.  This is only done
341       when write() or write_multi() is called with a "file" parameter, or if
342       read() or read_multi() can't determine the type from the file's header.
343
344       The default function value of $Imager::FORMATGUESS is
345       "\&Imager::def_guess_type".
346
347       def_guess_type()
348           This is the default function Imager uses to derive a file type from
349           a file name.  This is a function, not a method.
350
351           Accepts a single parameter, the file name and returns the type or
352           undef.
353
354       You can replace function with your own implementation if you have some
355       specialized need.  The function takes a single parameter, the name of
356       the file, and should return either a file type or under.
357
358         # I'm writing jpegs to weird filenames
359         local $Imager::FORMATGUESS = sub { 'jpeg' };
360
361       When reading a file Imager examines beginning of the file for
362       identifying information.  The current implementation attempts to detect
363       the following image types beyond those supported by Imager:
364
365           "xpm", "mng", "jng", "ilbm", "pcx", "fits", "psd" (Photoshop),
366           "eps", Utah "RLE".
367
368       You can now add to the magic database Imager uses for detecting file
369       types:
370
371       add_file_magic()
372             Imager->add_file_magic(name => $name, bits => $bits, mask => $mask)
373
374           Adds to list of magic, the parameters are all required.  The
375           parameters are:
376
377           •   "name" - the file type name to return on match.
378
379           •   "bits" - a binary string to match.
380
381           •   "mask" - a mask controlling which parts of bits are
382               significant.
383
384           While mask is mostly a bit mask, some byte values are translated,
385           the space character is treated as all zeros ("\x00"), and the "x"
386           character as all ones ("\xFF").
387
388           New magic entries take priority over old entries.
389
390           You can add more than one magic entry for a given name.
391
392             Imager->add_file_magic(name => "heif",
393                                    bits => "    ftypheif"
394                                    mask => "    xxxxxxxx");
395
396   Limiting the sizes of images you read
397       set_file_limits()
398           In some cases you will be receiving images from an untested source,
399           such as submissions via CGI.  To prevent such images from consuming
400           large amounts of memory, you can set limits on the dimensions of
401           images you read from files:
402
403           •   width - limit the width in pixels of the image
404
405           •   height - limit the height in pixels of the image
406
407           •   bytes - limits the amount of storage used by the image.  This
408               depends on the width, height, channels and sample size of the
409               image.  For paletted images this is calculated as if the image
410               was expanded to a direct color image.
411
412           To set the limits, call the class method set_file_limits:
413
414             Imager->set_file_limits(width=>$max_width, height=>$max_height);
415
416           You can pass any or all of the limits above, any limits you do not
417           pass are left as they were.
418
419           Any limit of zero for width or height is treated as unlimited.
420
421           A limit of zero for bytes is treated as one gigabyte, but higher
422           bytes limits can be set explicitly.
423
424           By default, the width and height limits are zero, or unlimited.
425           The default memory size limit is one gigabyte.
426
427           You can reset all limits to their defaults with the reset
428           parameter:
429
430             # no limits
431             Imager->set_file_limits(reset=>1);
432
433           This can be used with the other limits to reset all but the limit
434           you pass:
435
436             # only width is limited
437             Imager->set_file_limits(reset=>1, width=>100);
438
439             # only bytes is limited
440             Imager->set_file_limits(reset=>1, bytes=>10_000_000);
441
442       get_file_limits()
443           You can get the current limits with the get_file_limits() method:
444
445             my ($max_width, $max_height, $max_bytes) =
446                Imager->get_file_limits();
447
448       check_file_limits()
449           Intended for use by file handlers to check that the size of a file
450           is within the limits set by "set_file_limits()".
451
452           Parameters:
453
454           •   "width", "height" - the width and height of the image in
455               pixels.  Must be a positive integer. Required.
456
457           •   "channels" - the number of channels in the image, including the
458               alpha channel if any.  Must be a positive integer between 1 and
459               4 inclusive.  Default: 3.
460
461           •   "sample_size" - the number of bytes stored per sample.  Must be
462               a positive integer or "float".  Note that this should be the
463               sample size of the Imager image you will be creating, not the
464               sample size in the source, eg. if the source has 32-bit samples
465               this should be "float" since Imager doesn't have 32-bit/sample
466               images.
467

TYPE SPECIFIC INFORMATION

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

ADDING NEW FORMATS

1313       To support a new format for reading, call the register_reader() class
1314       method:
1315
1316       register_reader()
1317           Registers single or multiple image read functions.
1318
1319           Parameters:
1320
1321           •   type - the identifier of the file format, if Imager's
1322               i_test_format_probe() can identify the format then this value
1323               should match i_test_format_probe()'s result.
1324
1325               This parameter is required.
1326
1327           •   single - a code ref to read a single image from a file.  This
1328               is supplied:
1329
1330               •   the object that read() was called on,
1331
1332               •   an Imager::IO object that should be used to read the file,
1333                   and
1334
1335               •   all the parameters supplied to the read() method.
1336
1337               The single parameter is required.
1338
1339           •   multiple - a code ref which is called to read multiple images
1340               from a file. This is supplied:
1341
1342               •   an Imager::IO object that should be used to read the file,
1343                   and
1344
1345               •   all the parameters supplied to the read_multi() method.
1346
1347           Example:
1348
1349             # from Imager::File::ICO
1350             Imager->register_reader
1351               (
1352                type=>'ico',
1353                single =>
1354                sub {
1355                  my ($im, $io, %hsh) = @_;
1356                  $im->{IMG} = i_readico_single($io, $hsh{page} || 0);
1357
1358                  unless ($im->{IMG}) {
1359                    $im->_set_error(Imager->_error_as_msg);
1360                    return;
1361                  }
1362                  return $im;
1363                },
1364                multiple =>
1365                sub {
1366                  my ($io, %hsh) = @_;
1367
1368                  my @imgs = i_readico_multi($io);
1369                  unless (@imgs) {
1370                    Imager->_set_error(Imager->_error_as_msg);
1371                    return;
1372                  }
1373                  return map {
1374                    bless { IMG => $_, DEBUG => $Imager::DEBUG, ERRSTR => undef }, 'Imager'
1375                  } @imgs;
1376                },
1377               );
1378
1379       register_writer()
1380           Registers single or multiple image write functions.
1381
1382           Parameters:
1383
1384           •   type - the identifier of the file format.  This is typically
1385               the extension in lowercase.
1386
1387               This parameter is required.
1388
1389           •   single - a code ref to write a single image to a file.  This is
1390               supplied:
1391
1392               •   the object that write() was called on,
1393
1394               •   an Imager::IO object that should be used to write the file,
1395                   and
1396
1397               •   all the parameters supplied to the write() method.
1398
1399               The single parameter is required.
1400
1401           •   multiple - a code ref which is called to write multiple images
1402               to a file. This is supplied:
1403
1404               •   the class name write_multi() was called on, this is
1405                   typically "Imager".
1406
1407               •   an Imager::IO object that should be used to write the file,
1408                   and
1409
1410               •   all the parameters supplied to the read_multi() method.
1411
1412       add_type_extensions($type, $ext, ...)
1413           This class method can be used to add extensions to the map used by
1414           "def_guess_type" when working out the file type a filename
1415           extension.
1416
1417             Imager->add_type_extension(mytype => "mytype", "mytypish");
1418             ...
1419             $im->write(file => "foo.mytypish") # use the mytype handler
1420
1421       If you name the reader module "Imager::File::"your-format-name where
1422       your-format-name is a fully upper case version of the type value you
1423       would pass to read(), read_multi(), write() or write_multi() then
1424       Imager will attempt to load that module if it has no other way to read
1425       or write that format.
1426
1427       For example, if you create a module Imager::File::GIF and the user has
1428       built Imager without it's normal GIF support then an attempt to read a
1429       GIF image will attempt to load Imager::File::GIF.
1430
1431       If your module can only handle reading then you can name your module
1432       "Imager::File::"your-format-name"Reader" and Imager will attempt to
1433       autoload it.
1434
1435       If your module can only handle writing then you can name your module
1436       "Imager::File::"your-format-name"Writer" and Imager will attempt to
1437       autoload it.
1438

PRELOADING FILE MODULES

1440       preload()
1441           This preloads the file support modules included with or that have
1442           been included with Imager in the past.  This is intended for use in
1443           forking servers such as mod_perl.
1444
1445           If the module is not available no error occurs.
1446
1447           Preserves $@.
1448
1449             use Imager;
1450             Imager->preload;
1451

EXAMPLES

1453   Producing an image from a CGI script
1454       Once you have an image the basic mechanism is:
1455
1456       1.  set STDOUT to autoflush
1457
1458       2.  output a content-type header, and optionally a content-length
1459           header
1460
1461       3.  put STDOUT into binmode
1462
1463       4.  call write() with the "fd" or "fh" parameter.  You will need to
1464           provide the "type" parameter since Imager can't use the extension
1465           to guess the file format you want.
1466
1467         # write an image from a CGI script
1468         # using CGI.pm
1469         use CGI qw(:standard);
1470         $| = 1;
1471         binmode STDOUT;
1472         print header(-type=>'image/gif');
1473         $img->write(type=>'gif', fd=>fileno(STDOUT))
1474           or die $img->errstr;
1475
1476       If you want to send a content length you can send the output to a
1477       scalar to get the length:
1478
1479         my $data;
1480         $img->write(type=>'gif', data=>\$data)
1481           or die $img->errstr;
1482         binmode STDOUT;
1483         print header(-type=>'image/gif', -content_length=>length($data));
1484         print $data;
1485
1486   Writing an animated GIF
1487       The basic idea is simple, just use write_multi():
1488
1489         my @imgs = ...;
1490         Imager->write_multi({ file=>$filename, type=>'gif' }, @imgs);
1491
1492       If your images are RGB images the default quantization mechanism will
1493       produce a very good result, but can take a long time to execute.  You
1494       could either use the standard web color map:
1495
1496         Imager->write_multi({ file=>$filename,
1497                               type=>'gif',
1498                               make_colors=>'webmap' },
1499                             @imgs);
1500
1501       or use a median cut algorithm to built a fairly optimal color map:
1502
1503         Imager->write_multi({ file=>$filename,
1504                               type=>'gif',
1505                               make_colors=>'mediancut' },
1506                             @imgs);
1507
1508       By default all of the images will use the same global color map, which
1509       will produce a smaller image.  If your images have significant color
1510       differences, you may want to generate a new palette for each image:
1511
1512         Imager->write_multi({ file=>$filename,
1513                               type=>'gif',
1514                               make_colors=>'mediancut',
1515                               gif_local_map => 1 },
1516                             @imgs);
1517
1518       which will set the "gif_local_map" tag in each image to 1.
1519       Alternatively, if you know only some images have different colors, you
1520       can set the tag just for those images:
1521
1522         $imgs[2]->settag(name=>'gif_local_map', value=>1);
1523         $imgs[4]->settag(name=>'gif_local_map', value=>1);
1524
1525       and call write_multi() without a "gif_local_map" parameter, or supply
1526       an arrayref of values for the tag:
1527
1528         Imager->write_multi({ file=>$filename,
1529                               type=>'gif',
1530                               make_colors=>'mediancut',
1531                               gif_local_map => [ 0, 0, 1, 0, 1 ] },
1532                             @imgs);
1533
1534       Other useful parameters include "gif_delay" to control the delay
1535       between frames and "transp" to control transparency.
1536
1537   Reading tags after reading an image
1538       This is pretty simple:
1539
1540         # print the author of a TIFF, if any
1541         my $img = Imager->new;
1542         $img->read(file=>$filename, type='tiff') or die $img->errstr;
1543         my $author = $img->tags(name=>'tiff_author');
1544         if (defined $author) {
1545           print "Author: $author\n";
1546         }
1547

BUGS

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

SEE ALSO

1554       Imager(3)
1555

AUTHOR

1557       Tony Cook <tonyc@cpan.org>, Arnar M. Hrafnkelsson
1558
1559
1560
1561perl v5.32.1                      2021-01-27                  Imager::Files(3)
Impressum