(rt #127575) link to Imager::Install from Imager::Files
[imager.git] / lib / Imager / Files.pod
1 =head1 NAME
2
3 Imager::Files - working with image files
4
5 =head1 SYNOPSIS
6
7   use Imager;
8   my $img = ...;
9   $img->write(file=>$filename, type=>$type)
10     or die "Cannot write: ",$img->errstr;
11
12   # type is optional if we can guess the format from the filename
13   $img->write(file => "foo.png")
14     or die "Cannot write: ",$img->errstr;
15
16   $img = Imager->new;
17   $img->read(file=>$filename, type=>$type)
18     or die "Cannot read: ", $img->errstr;
19
20   # type is optional if we can guess the type from the file data
21   # and we normally can guess
22   $img->read(file => $filename)
23     or die "Cannot read: ", $img->errstr;
24
25   Imager->write_multi({ file=> $filename, ... }, @images)
26     or die "Cannot write: ", Imager->errstr;
27
28   my @imgs = Imager->read_multi(file=>$filename)
29     or die "Cannot read: ", Imager->errstr;
30
31   Imager->set_file_limits(width=>$max_width, height=>$max_height)
32
33   my @read_types = Imager->read_types;
34   my @write_types = Imager->write_types;
35
36   # we can write/write_multi to things other than filenames
37   my $data;
38   $img->write(data => \$data, type => $type) or die;
39
40   my $fh = ... ; # eg. IO::File
41   $img->write(fh => $fh, type => $type) or die;
42
43   $img->write(fd => fileno($fh), type => $type) or die;
44
45   # some file types need seek callbacks too
46   $img->write(callback => \&write_callback, type => $type) or die;
47
48   # and similarly for read/read_multi
49   $img->read(data => $data) or die;
50   $img->read(fh => $fh) or die;
51   $img->read(fd => fileno($fh)) or die;
52   $img->read(callback => \&read_callback) or die;
53
54   use Imager 0.68;
55   my $img = Imager->new(file => $filename)
56     or die Imager->errstr;
57
58 =head1 DESCRIPTION
59
60 You can read and write a variety of images formats, assuming you have
61 the L<appropriate libraries|Imager::Install/EXTERNAL LIBRARIES>, and
62 images can be read or written to/from files, file handles, file
63 descriptors, scalars, or through callbacks.
64
65 To see which image formats Imager is compiled to support the following
66 code snippet is sufficient:
67
68   use Imager;
69   print join " ", keys %Imager::formats;
70
71 This will include some other information identifying libraries rather
72 than file formats.  For new code you might find the L</read_types()>
73 or L</write_types()> methods useful.
74
75 =over 
76
77 =item read()
78
79 Reading writing to and from files is simple, use the C<read()>
80 method to read an image:
81
82   my $img = Imager->new;
83   $img->read(file=>$filename, type=>$type)
84     or die "Cannot read $filename: ", $img->errstr;
85
86 In most cases Imager can auto-detect the file type, so you can just
87 supply the file name:
88
89   $img->read(file => $filename)
90     or die "Cannot read $filename: ", $img->errstr;
91
92 The read() method accepts the C<allow_incomplete> parameter.  If this
93 is non-zero then read() can return true on an incomplete image and set
94 the C<i_incomplete> tag.
95
96 From Imager 0.68 you can supply most read() parameters to the new()
97 method to read the image file on creation.  If the read fails, check
98 Imager->errstr() for the cause:
99
100   use Imager 0.68;
101   my $img = Imager->new(file => $filename)
102     or die "Cannot read $filename: ", Imager->errstr;
103
104 =item write()
105
106 and the C<write()> method to write an image:
107
108   $img->write(file=>$filename, type=>$type)
109     or die "Cannot write $filename: ", $img->errstr;
110
111 =item read_multi()
112
113 If you're reading from a format that supports multiple images per
114 file, use the C<read_multi()> method:
115
116   my @imgs = Imager->read_multi(file=>$filename, type=>$type)
117     or die "Cannot read $filename: ", Imager->errstr;
118
119 As with the read() method, Imager will normally detect the C<type>
120 automatically.
121
122 =item write_multi()
123
124 and if you want to write multiple images to a single file use the
125 C<write_multi()> method:
126
127   Imager->write_multi({ file=> $filename, type=>$type }, @images)
128     or die "Cannot write $filename: ", Imager->errstr;
129
130 =item read_types()
131
132 This is a class method that returns a list of the image file types
133 that Imager can read.
134
135   my @types = Imager->read_types;
136
137 These types are the possible values for the C<type> parameter, not
138 necessarily the extension of the files you're reading.
139
140 It is possible for extra file read handlers to be loaded when
141 attempting to read a file, which may modify the list of available read
142 types.
143
144 =item write_types()
145
146 This is a class method that returns a list of the image file types
147 that Imager can write.
148
149   my @types = Imager->write_types;
150
151 Note that these are the possible values for the C<type> parameter, not
152 necessarily the extension of the files you're writing.
153
154 It is possible for extra file write handlers to be loaded when
155 attempting to write a file, which may modify the list of available
156 write types.
157
158 =back
159
160 When writing, if the C<filename> includes an extension that Imager
161 recognizes, then you don't need the C<type>, but you may want to
162 provide one anyway.  See L</Guessing types> for information on
163 controlling this recognition.
164
165 The C<type> parameter is a lowercase representation of the file type,
166 and can be any of the following:
167
168   bmp   Windows BitMaP (BMP)
169   gif   Graphics Interchange Format (GIF)
170   jpeg  JPEG/JFIF
171   png   Portable Network Graphics (PNG)
172   pnm   Portable aNyMap (PNM)
173   raw   Raw
174   sgi   SGI .rgb files
175   tga   TARGA
176   tiff  Tagged Image File Format (TIFF)
177
178 When you read an image, Imager may set some tags, possibly including
179 information about the spatial resolution, textual information, and
180 animation information.  See L<Imager::ImageTypes/Tags> for specifics.
181
182 The open() method is a historical alias for the read() method.
183
184 =head2 Input and output
185
186 When reading or writing you can specify one of a variety of sources or
187 targets:
188
189 =over
190
191 =item *
192
193 C<file> - The C<file> parameter is the name of the image file to be
194 written to or read from.  If Imager recognizes the extension of the
195 file you do not need to supply a C<type>.
196
197   # write in tiff format
198   $image->write(file => "example.tif")
199     or die $image->errstr;
200
201   $image->write(file => 'foo.tmp', type => 'tiff')
202     or die $image->errstr;
203
204   my $image = Imager->new;
205   $image->read(file => 'example.tif')
206     or die $image->errstr;
207
208 =item *
209
210 C<fh> - C<fh> is a file handle, typically either returned from
211 C<<IO::File->new()>>, or a glob from an C<open> call.  You should call
212 C<binmode> on the handle before passing it to Imager.
213
214 Imager will set the handle to autoflush to make sure any buffered data
215 is flushed , since Imager will write to the file descriptor (from
216 fileno()) rather than writing at the perl level.
217
218   $image->write(fh => \*STDOUT, type => 'gif')
219     or die $image->errstr;
220
221   # for example, a file uploaded via CGI.pm
222   $image->read(fd => $cgi->param('file')) 
223     or die $image->errstr;
224
225 =item *
226
227 C<fd> - C<fd> is a file descriptor.  You can get this by calling the
228 C<fileno()> function on a file handle, or by using one of the standard
229 file descriptor numbers.
230
231 If you get this from a perl file handle, you may need to flush any
232 buffered output, otherwise it may appear in the output stream after
233 the image.
234
235   $image->write(fd => file(STDOUT), type => 'gif')
236     or die $image->errstr;
237
238 =item *
239
240 C<data> - When reading data, C<data> is a scalar containing the image
241 file data, or a reference to such a scalar.  When writing, C<data> is
242 a reference to the scalar to save the image file data to.
243
244   my $data;
245   $image->write(data => \$data, type => 'tiff')
246     or die $image->errstr;
247
248   my $data = $row->{someblob}; # eg. from a database
249   my @images = Imager->read_multi(data => $data)
250     or die Imager->errstr;
251
252   # from Imager 0.99
253   my @images = Imager->read_multi(data => \$data)
254     or die Imager->errstr;
255
256 =item *
257
258 C<callback>, C<readcb>, C<writecb>, C<seekcb>, C<closecb> - Imager
259 will make calls back to your supplied coderefs to read, write and seek
260 from/to/through the image file.  See L</"I/O Callbacks"> below for details.
261
262 =item *
263
264 C<io> - an L<Imager::IO> object.
265
266 =back
267
268 X<buffering>X<unbuffered>By default Imager will use buffered I/O when
269 reading or writing an image.  You can disabled buffering for output by
270 supplying a C<< buffered => 0 >> parameter to C<write()> or
271 C<write_multi()>.
272
273 =head2 I/O Callbacks
274
275 When reading from a file you can use either C<callback> or C<readcb>
276 to supply the read callback, and when writing C<callback> or
277 C<writecb> to supply the write callback.
278
279 Whether reading or writing a C<TIFF> image, C<seekcb> and C<readcb>
280 are required.
281
282 If a file handler attempts to use C<readcb>, C<writecb> or C<seekcb>
283 and you haven't supplied one, the call will fail, failing the image
284 read or write, returning an error message indicating that the callback
285 is missing:
286
287   # attempting to read a TIFF image without a seekcb
288   open my $fh, "<", $filename or die;
289   my $rcb = sub {
290     my $val;
291     read($fh, $val, $_[0]) or return "";
292     return $val;
293   };
294   my $im = Imager->new(callback => $rcb)
295     or die Imager->errstr
296   # dies with (wrapped here):
297   # Error opening file: (Iolayer): Failed to read directory at offset 0:
298   # (Iolayer): Seek error accessing TIFF directory: seek callback called
299   # but no seekcb supplied
300
301 You can also provide a C<closecb> parameter called when writing the
302 file is complete.  If no C<closecb> is supplied the default will
303 succeed silently.
304
305   # contrived
306   my $data;
307   sub mywrite {
308     $data .= unpack("H*", shift);
309     1;
310   }
311   Imager->write_multi({ callback => \&mywrite, type => 'gif'}, @images)
312     or die Imager->errstr;
313
314 =head3 C<readcb>
315
316 The read callback is called with 2 parameters:
317
318 =over
319
320 =item *
321
322 C<size> - the minimum amount of data required.
323
324 =item *
325
326 C<maxsize> - previously this was the maximum amount of data returnable
327 - currently it's always the same as C<size>
328
329 =back
330
331 Your read callback should return the data as a scalar:
332
333 =over
334
335 =item *
336
337 on success, a string containing the bytes read.
338
339 =item *
340
341 on end of file, an empty string
342
343 =item *
344
345 on error, C<undef>.
346
347 =back
348
349 If your return value contains more data than C<size> Imager will
350 panic.
351
352 Your return value must not contain any characters over C<\xFF> or
353 Imager will panic.
354
355 =head3 C<writecb>
356
357 Your write callback takes exactly one parameter, a scalar containing
358 the data to be written.
359
360 Return true for success.
361
362 =head3 C<seekcb>
363
364 The seek callback takes 2 parameters, a I<POSITION>, and a I<WHENCE>,
365 defined in the same way as perl's seek function.
366
367 Previously you always needed a C<seekcb> callback if you called
368 Imager's L</read()> or L</read_multi()> without a C<type> parameter,
369 but this is no longer necessary unless the file handler requires
370 seeking, such as for TIFF files.
371
372 Returns the new position in the file, or -1 on failure.
373
374 =head3 C<closecb>
375
376 You can also supply a C<closecb> which is called with no parameters
377 when there is no more data to be written.  This could be used to flush
378 buffered data.
379
380 Return true on success.
381
382 =head2 Guessing types
383 X<FORMATGUESS>
384
385 When writing to a file, if you don't supply a C<type> parameter Imager
386 will attempt to guess it from the file name.  This is done by calling
387 the code reference stored in C<$Imager::FORMATGUESS>.  This is only
388 done when write() or write_multi() is called with a C<file> parameter,
389 or if read() or read_multi() can't determine the type from the file's
390 header.
391
392 The default function value of C<$Imager::FORMATGUESS> is
393 C<\&Imager::def_guess_type>.
394
395 =over
396
397 =item def_guess_type()
398 X<methods, def_guess_type()>
399
400 This is the default function Imager uses to derive a file type from a
401 file name.  This is a function, not a method.
402
403 Accepts a single parameter, the file name and returns the type or
404 undef.
405
406 =back
407
408 You can replace function with your own implementation if you have some
409 specialized need.  The function takes a single parameter, the name of
410 the file, and should return either a file type or under.
411
412   # I'm writing jpegs to weird filenames
413   local $Imager::FORMATGUESS = sub { 'jpeg' };
414
415 When reading a file Imager examines beginning of the file for
416 identifying information.  The current implementation attempts to
417 detect the following image types beyond those supported by Imager:
418
419 =for stopwords Photoshop
420
421 =over
422
423 C<xpm>, C<mng>, C<jng>, C<ilbm>, C<pcx>, C<fits>, C<psd> (Photoshop), C<eps>, Utah
424 C<RLE>.
425
426 =back
427
428 =head2 Limiting the sizes of images you read
429
430 =over
431
432 =item set_file_limits()
433
434 In some cases you will be receiving images from an untested source,
435 such as submissions via CGI.  To prevent such images from consuming
436 large amounts of memory, you can set limits on the dimensions of
437 images you read from files:
438
439 =over
440
441 =item *
442
443 width - limit the width in pixels of the image
444
445 =item *
446
447 height - limit the height in pixels of the image
448
449 =item *
450
451 bytes - limits the amount of storage used by the image.  This depends
452 on the width, height, channels and sample size of the image.  For
453 paletted images this is calculated as if the image was expanded to a
454 direct color image.
455
456 =back
457
458 To set the limits, call the class method set_file_limits:
459
460   Imager->set_file_limits(width=>$max_width, height=>$max_height);
461
462 You can pass any or all of the limits above, any limits you do not
463 pass are left as they were.
464
465 Any limit of zero for width or height is treated as unlimited.
466
467 A limit of zero for bytes is treated as one gigabyte, but higher bytes
468 limits can be set explicitly.
469
470 By default, the width and height limits are zero, or unlimited.  The
471 default memory size limit is one gigabyte.
472
473 You can reset all limits to their defaults with the reset parameter:
474
475   # no limits
476   Imager->set_file_limits(reset=>1);
477
478 This can be used with the other limits to reset all but the limit you
479 pass:
480
481   # only width is limited
482   Imager->set_file_limits(reset=>1, width=>100);
483
484   # only bytes is limited
485   Imager->set_file_limits(reset=>1, bytes=>10_000_000);
486
487 =item get_file_limits()
488
489 You can get the current limits with the get_file_limits() method:
490
491   my ($max_width, $max_height, $max_bytes) =
492      Imager->get_file_limits();
493
494 =item check_file_limits()
495 X<class methods, check_file_limits()>X<check_file_limits()>
496
497 Intended for use by file handlers to check that the size of a file is
498 within the limits set by C<set_file_limits()>.
499
500 Parameters:
501
502 =over
503
504 =item *
505
506 C<width>, C<height> - the width and height of the image in pixels.
507 Must be a positive integer. Required.
508
509 =item *
510
511 C<channels> - the number of channels in the image, including the alpha
512 channel if any.  Must be a positive integer between 1 and 4
513 inclusive.  Default: 3.
514
515 =item *
516
517 C<sample_size> - the number of bytes stored per sample.  Must be a
518 positive integer or C<"float">.  Note that this should be the sample
519 size of the Imager image you will be creating, not the sample size in
520 the source, eg. if the source has 32-bit samples this should be
521 C<"float"> since Imager doesn't have 32-bit/sample images.
522
523 =back
524
525 =back
526
527 =head1 TYPE SPECIFIC INFORMATION
528
529 The different image formats can write different image type, and some have
530 different options to control how the images are written.
531
532 When you call C<write()> or C<write_multi()> with an option that has
533 the same name as a tag for the image format you're writing, then the
534 value supplied to that option will be used to set the corresponding
535 tag in the image.  Depending on the image format, these values will be
536 used when writing the image.
537
538 This replaces the previous options that were used when writing GIF
539 images.  Currently if you use an obsolete option, it will be converted
540 to the equivalent tag and Imager will produced a warning.  You can
541 suppress these warnings by calling the C<Imager::init()> function with
542 the C<warn_obsolete> option set to false:
543
544   Imager::init(warn_obsolete=>0);
545
546 At some point in the future these obsolete options will no longer be
547 supported.
548
549 =for stopwords aNy PixMaps BitMap
550
551 =head2 PNM (Portable aNy Map)
552
553 Imager can write C<PGM> (Portable Gray Map) and C<PPM> (Portable
554 PixMaps) files, depending on the number of channels in the image.
555 Currently the images are written in binary formats.  Only 1 and 3
556 channel images can be written, including 1 and 3 channel paletted
557 images.
558
559   $img->write(file=>'foo.ppm') or die $img->errstr;
560
561 Imager can read both the ASCII and binary versions of each of the
562 C<PBM> (Portable BitMap), C<PGM> and C<PPM> formats.
563
564   $img->read(file=>'foo.ppm') or die $img->errstr;
565
566 PNM does not support the spatial resolution tags.
567
568 The following tags are set when reading a PNM file:
569
570 =over
571
572 =item *
573
574 X<pnm_maxval>C<pnm_maxval> - the C<maxvals> number from the PGM/PPM header.
575 Always set to 2 for a C<PBM> file.
576
577 =item *
578
579 X<pnm_type>C<pnm_type> - the type number from the C<PNM> header, 1 for ASCII
580 C<PBM> files, 2 for ASCII C<PGM> files, 3 for ASCII c<PPM> files, 4 for binary
581 C<PBM> files, 5 for binary C<PGM> files, 6 for binary C<PPM> files.
582
583 =back
584
585 The following tag is checked when writing an image with more than
586 8-bits/sample:
587
588 =over
589
590 =item *
591
592 X<pnm_write_wide_data>pnm_write_wide_data - if this is non-zero then
593 write() can write C<PGM>/C<PPM> files with 16-bits/sample.  Some
594 applications, for example GIMP 2.2, and tools can only read
595 8-bit/sample binary PNM files, so Imager will only write a 16-bit
596 image when this tag is non-zero.
597
598 =back
599
600 =head2 JPEG
601
602 You can supply a C<jpegquality> parameter ranging from 0 (worst
603 quality) to 100 (best quality) when writing a JPEG file, which
604 defaults to 75.
605
606   $img->write(file=>'foo.jpg', jpegquality=>90) or die $img->errstr;
607
608 If you write an image with an alpha channel to a JPEG file then it
609 will be composed against the background set by the C<i_background>
610 parameter (or tag), or black if not supplied.
611
612 Imager will read a gray scale JPEG as a 1 channel image and a color
613 JPEG as a 3 channel image.
614
615   $img->read(file=>'foo.jpg') or die $img->errstr;
616
617 The following tags are set in a JPEG image when read, and can be set
618 to control output:
619
620 =over
621
622 =item *
623
624 C<jpeg_density_unit> - The value of the density unit field in the
625 C<JFIF> header.  This is ignored on writing if the C<i_aspect_only>
626 tag is non-zero.
627
628 The C<i_xres> and C<i_yres> tags are expressed in pixels per inch no
629 matter the value of this tag, they will be converted to/from the value
630 stored in the JPEG file.
631
632 =item *
633
634 C<jpeg_density_unit_name> - This is set when reading a JPEG file to
635 the name of the unit given by C<jpeg_density_unit>.  Possible results
636 include C<inch>, C<centimeter>, C<none> (the C<i_aspect_only> tag is
637 also set reading these files).  If the value of C<jpeg_density_unit>
638 is unknown then this tag isn't set.
639
640 =item *
641
642 C<jpeg_comment> - Text comment.
643
644 =item *
645
646 C<jpeg_progressive> - Whether the JPEG file is a progressive
647 file. (Imager 0.84)
648
649 =back
650
651 JPEG supports the spatial resolution tags C<i_xres>, C<i_yres> and
652 C<i_aspect_only>.
653
654 You can also set the following tags when writing to an image, they are
655 not set in the image when reading:
656
657 =over
658
659 C<jpeg_optimize> - set to a non-zero integer to compute optimal
660 Huffman coding tables for the image.  This will increase memory usage
661 and processing time (about 12% in my simple tests) but can
662 significantly reduce file size without a loss of quality.
663
664 =back
665
666 =for stopwords EXIF
667
668 If an C<APP1> block containing EXIF information is found, then any of the
669 following tags can be set when reading a JPEG image:
670
671 =over
672
673 exif_aperture exif_artist exif_brightness exif_color_space
674 exif_contrast exif_copyright exif_custom_rendered exif_date_time
675 exif_date_time_digitized exif_date_time_original
676 exif_digital_zoom_ratio exif_exposure_bias exif_exposure_index
677 exif_exposure_mode exif_exposure_program exif_exposure_time
678 exif_f_number exif_flash exif_flash_energy exif_flashpix_version
679 exif_focal_length exif_focal_length_in_35mm_film
680 exif_focal_plane_resolution_unit exif_focal_plane_x_resolution
681 exif_focal_plane_y_resolution exif_gain_control exif_image_description
682 exif_image_unique_id exif_iso_speed_rating exif_make exif_max_aperture
683 exif_metering_mode exif_model exif_orientation exif_related_sound_file
684 exif_resolution_unit exif_saturation exif_scene_capture_type
685 exif_sensing_method exif_sharpness exif_shutter_speed exif_software
686 exif_spectral_sensitivity exif_sub_sec_time
687 exif_sub_sec_time_digitized exif_sub_sec_time_original
688 exif_subject_distance exif_subject_distance_range
689 exif_subject_location exif_tag_light_source exif_user_comment
690 exif_version exif_white_balance exif_x_resolution exif_y_resolution
691
692 =back
693
694 The following derived tags can also be set when reading a JPEG image:
695
696 =over
697
698 exif_color_space_name exif_contrast_name exif_custom_rendered_name
699 exif_exposure_mode_name exif_exposure_program_name exif_flash_name
700 exif_focal_plane_resolution_unit_name exif_gain_control_name
701 exif_light_source_name exif_metering_mode_name
702 exif_resolution_unit_name exif_saturation_name
703 exif_scene_capture_type_name exif_sensing_method_name
704 exif_sharpness_name exif_subject_distance_range_name
705 exif_white_balance_name
706
707 =back
708
709 The derived tags are for enumerated fields, when the value for the
710 base field is valid then the text that appears in the EXIF
711 specification for that value appears in the derived field.  So for
712 example if C<exf_metering_mode> is C<5> then
713 C<exif_metering_mode_name> is set to C<Pattern>.
714
715 eg.
716
717   my $image = Imager->new;
718   $image->read(file => 'exiftest.jpg')
719     or die "Cannot load image: ", $image->errstr;
720   print $image->tags(name => "exif_image_description"), "\n";
721   print $image->tags(name => "exif_exposure_mode"), "\n";
722   print $image->tags(name => "exif_exposure_mode_name"), "\n";
723
724   # for the exiftest.jpg in the Imager distribution the output would be:
725   Imager Development Notes
726   0
727   Auto exposure
728
729 Imager will not write EXIF tags to any type of image, if you need more
730 advanced EXIF handling, consider L<Image::ExifTool>.
731
732 =for stopwords IPTC
733
734 =over
735
736 =item parseiptc()
737
738 Historically, Imager saves IPTC data when reading a JPEG image, the
739 parseiptc() method returns a list of key/value pairs resulting from a
740 simple decoding of that data.
741
742 Any future IPTC data decoding is likely to go into tags.
743
744 =back
745
746 =head2 GIF
747
748 When writing one of more GIF images you can use the same
749 L<Quantization Options|Imager::ImageTypes> as you can when converting
750 an RGB image into a paletted image.
751
752 When reading a GIF all of the sub-images are combined using the screen
753 size and image positions into one big image, producing an RGB image.
754 This may change in the future to produce a paletted image where possible.
755
756 When you read a single GIF with C<$img-E<gt>read()> you can supply a
757 reference to a scalar in the C<colors> parameter, if the image is read
758 the scalar will be filled with a reference to an anonymous array of
759 L<Imager::Color> objects, representing the palette of the image.  This
760 will be the first palette found in the image.  If you want the
761 palettes for each of the images in the file, use C<read_multi()> and
762 use the C<getcolors()> method on each image.
763
764 GIF does not support the spatial resolution tags.
765
766 Imager will set the following tags in each image when reading, and can
767 use most of them when writing to GIF:
768
769 =over
770
771 =item *
772
773 gif_left - the offset of the image from the left of the "screen"
774 ("Image Left Position")
775
776 =item *
777
778 gif_top - the offset of the image from the top of the "screen" ("Image
779 Top Position")
780
781 =item *
782
783 gif_interlace - non-zero if the image was interlaced ("Interlace
784 Flag")
785
786 =item *
787
788 gif_screen_width, gif_screen_height - the size of the logical
789 screen. When writing this is used as the minimum.  If any image being
790 written would extend beyond this then the screen size is extended.
791 ("Logical Screen Width", "Logical Screen Height").
792
793 =item *
794
795 gif_local_map - Non-zero if this image had a local color map.  If set
796 for an image when writing the image is quantized separately from the
797 other images in the file.
798
799 =item *
800
801 gif_background - The index in the global color map of the logical
802 screen's background color.  This is only set if the current image uses
803 the global color map.  You can set this on write too, but for it to
804 choose the color you want, you will need to supply only paletted
805 images and set the C<gif_eliminate_unused> tag to 0.
806
807 =item *
808
809 gif_trans_index - The index of the color in the color map used for
810 transparency.  If the image has a transparency then it is returned as
811 a 4 channel image with the alpha set to zero in this palette entry.
812 This value is not used when writing. ("Transparent Color Index")
813
814 =item *
815
816 gif_trans_color - A reference to an Imager::Color object, which is the
817 color to use for the palette entry used to represent transparency in
818 the palette.  You need to set the C<transp> option (see
819 L<Imager::ImageTypes/"Quantization options">) for this value to be
820 used.
821
822 =item *
823
824 gif_delay - The delay until the next frame is displayed, in 1/100 of a
825 second.  ("Delay Time").
826
827 =item *
828
829 gif_user_input - whether or not a user input is expected before
830 continuing (view dependent) ("User Input Flag").
831
832 =item *
833
834 gif_disposal - how the next frame is displayed ("Disposal Method")
835
836 =item *
837
838 gif_loop - the number of loops from the Netscape Loop extension.  This
839 may be zero to loop forever.
840
841 =item *
842
843 gif_comment - the first block of the first GIF comment before each
844 image.
845
846 =item *
847
848 gif_eliminate_unused - If this is true, when you write a paletted
849 image any unused colors will be eliminated from its palette.  This is
850 set by default.
851
852 =item *
853
854 gif_colormap_size - the original size of the color map for the image.
855 The color map of the image may have been expanded to include out of
856 range color indexes.
857
858 =back
859
860 Where applicable, the ("name") is the name of that field from the C<GIF89>
861 standard.
862
863 The following GIF writing options are obsolete, you should set the
864 corresponding tag in the image, either by using the tags functions, or
865 by supplying the tag and value as options.
866
867 =over
868
869 =item *
870
871 gif_each_palette - Each image in the GIF file has it's own palette if
872 this is non-zero.  All but the first image has a local color table
873 (the first uses the global color table.
874
875 Use C<gif_local_map> in new code.
876
877 =item *
878
879 interlace - The images are written interlaced if this is non-zero.
880
881 Use C<gif_interlace> in new code.
882
883 =item *
884
885 gif_delays - A reference to an array containing the delays between
886 images, in 1/100 seconds.
887
888 Use C<gif_delay> in new code.
889
890 =item *
891
892 gif_positions - A reference to an array of references to arrays which
893 represent screen positions for each image.
894
895 New code should use the C<gif_left> and C<gif_top> tags.
896
897 =item *
898
899 gif_loop_count - If this is non-zero the Netscape loop extension block
900 is generated, which makes the animation of the images repeat.
901
902 This is currently unimplemented due to some limitations in C<giflib>.
903
904 =back
905
906 You can supply a C<page> parameter to the C<read()> method to read
907 some page other than the first.  The page is 0 based:
908
909   # read the second image in the file
910   $image->read(file=>"example.gif", page=>1)
911     or die "Cannot read second page: ",$image->errstr,"\n";
912
913 Before release 0.46, Imager would read multiple image GIF image files
914 into a single image, overlaying each of the images onto the virtual
915 GIF screen.
916
917 As of 0.46 the default is to read the first image from the file, as if
918 called with C<< page => 0 >>.
919
920 You can return to the previous behavior by calling read with the
921 C<gif_consolidate> parameter set to a true value:
922
923   $img->read(file=>$some_gif_file, gif_consolidate=>1);
924
925 As with the to_paletted() method, if you supply a colors parameter as
926 a reference to an array, this will be filled with Imager::Color
927 objects of the color table generated for the image file.
928
929 =head2 TIFF (Tagged Image File Format)
930
931 Imager can write images to either paletted or RGB TIFF images,
932 depending on the type of the source image.
933
934 When writing direct color images to TIFF the sample size of the
935 output file depends on the input:
936
937 =over
938
939 =item *
940
941 double/sample - written as 32-bit/sample TIFF
942
943 =item *
944
945 16-bit/sample - written as 16-bit/sample TIFF
946
947 =item *
948
949 8-bit/sample - written as 8-bit/sample TIFF
950
951 =back
952
953 For paletted images:
954
955 =over
956
957 =item *
958
959 C<< $img->is_bilevel >> is true - the image is written as bi-level
960
961 =item *
962
963 otherwise - image is written as paletted.
964
965 =back
966
967 If you are creating images for faxing you can set the I<class>
968 parameter set to C<fax>.  By default the image is written in fine
969 mode, but this can be overridden by setting the I<fax_fine> parameter
970 to zero.  Since a fax image is bi-level, Imager uses a threshold to
971 decide if a given pixel is black or white, based on a single channel.
972 For gray scale images channel 0 is used, for color images channel 1
973 (green) is used.  If you want more control over the conversion you can
974 use $img->to_paletted() to product a bi-level image.  This way you can
975 use dithering:
976
977   my $bilevel = $img->to_paletted(make_colors => 'mono',
978                                   translate => 'errdiff',
979                                   errdiff => 'stucki');
980
981 =over
982
983 =item *
984
985 C<class> - If set to 'fax' the image will be written as a bi-level fax
986 image.
987
988 =item *
989
990 C<fax_fine> - By default when C<class> is set to 'fax' the image is
991 written in fine mode, you can select normal mode by setting
992 C<fax_fine> to 0.
993
994 =back
995
996 Imager should be able to read any TIFF image you supply.  Paletted
997 TIFF images are read as paletted Imager images, since paletted TIFF
998 images have 16-bits/sample (48-bits/color) this means the bottom
999 8-bits are lost, but this shouldn't be a big deal.
1000
1001 TIFF supports the spatial resolution tags.  See the
1002 C<tiff_resolutionunit> tag for some extra options.
1003
1004 As of Imager 0.62 Imager reads:
1005
1006 =over
1007
1008 =item *
1009
1010 8-bit/sample gray, RGB or CMYK images, including a possible alpha
1011 channel as an 8-bit/sample image.
1012
1013 =item *
1014
1015 16-bit gray, RGB, or CMYK image, including a possible alpha channel as
1016 a 16-bit/sample image.
1017
1018 =item *
1019
1020 32-bit gray, RGB image, including a possible alpha channel as a
1021 double/sample image.
1022
1023 =item *
1024
1025 bi-level images as paletted images containing only black and white,
1026 which other formats will also write as bi-level.
1027
1028 =item *
1029
1030 tiled paletted images are now handled correctly
1031
1032 =item *
1033
1034 other images are read using C<tifflib>'s RGBA interface as
1035 8-bit/sample images.
1036
1037 =back
1038
1039 The following tags are set in a TIFF image when read, and can be set
1040 to control output:
1041
1042 =over
1043
1044 =item *
1045
1046 C<tiff_compression> - When reading an image this is set to the numeric
1047 value of the TIFF compression tag.
1048
1049 On writing you can set this to either a numeric compression tag value,
1050 or one of the following values:
1051
1052   Ident     Number  Description
1053   none         1    No compression
1054   packbits   32773  Macintosh RLE
1055   ccittrle     2    CCITT RLE
1056   fax3         3    CCITT Group 3 fax encoding (T.4)
1057   t4           3    As above
1058   fax4         4    CCITT Group 4 fax encoding (T.6)
1059   t6           4    As above
1060   lzw          5    LZW
1061   jpeg         7    JPEG
1062   zip          8    Deflate (GZIP) Non-standard
1063   deflate      8    As above.
1064   oldzip     32946  Deflate with an older code.
1065   ccittrlew  32771  Word aligned CCITT RLE
1066
1067 In general a compression setting will be ignored where it doesn't make
1068 sense, eg. C<jpeg> will be ignored for compression if the image is
1069 being written as bilevel.
1070
1071 =for stopwords LZW
1072
1073 Imager attempts to check that your build of C<libtiff> supports the
1074 given compression, and will fallback to C<packbits> if it isn't
1075 enabled.  eg. older distributions didn't include LZW compression, and
1076 JPEG compression is only available if C<libtiff> is configured with
1077 C<libjpeg>'s location.
1078
1079   $im->write(file => 'foo.tif', tiff_compression => 'lzw')
1080     or die $im->errstr;
1081
1082 =item *
1083
1084 C<tags, tiff_jpegquality>C<tiff_jpegquality> - If C<tiff_compression>
1085 is C<jpeg> then this can be a number from 1 to 100 giving the JPEG
1086 compression quality.  High values are better quality and larger files.
1087
1088 =item *
1089
1090 X<tags, tiff_resolutionunit>C<tiff_resolutionunit> - The value of the
1091 C<ResolutionUnit> tag.  This is ignored on writing if the
1092 i_aspect_only tag is non-zero.
1093
1094 The C<i_xres> and C<i_yres> tags are expressed in pixels per inch no
1095 matter the value of this tag, they will be converted to/from the value
1096 stored in the TIFF file.
1097
1098 =item *
1099
1100 X<tags, tiff_resolutionunit_name>C<tiff_resolutionunit_name> - This is
1101 set when reading a TIFF file to the name of the unit given by
1102 C<tiff_resolutionunit>.  Possible results include C<inch>,
1103 C<centimeter>, C<none> (the C<i_aspect_only> tag is also set reading
1104 these files) or C<unknown>.
1105
1106 =item *
1107
1108 X<tags, tiff_bitspersample>C<tiff_bitspersample> - Bits per sample
1109 from the image.  This value is not used when writing an image, it is
1110 only set on a read image.
1111
1112 =item *
1113
1114 X<tags, tiff_photometric>C<tiff_photometric> - Value of the
1115 C<PhotometricInterpretation> tag from the image.  This value is not
1116 used when writing an image, it is only set on a read image.
1117
1118 =item *
1119
1120 C<tiff_documentname>, C<tiff_imagedescription>, C<tiff_make>,
1121 C<tiff_model>, C<tiff_pagename>, C<tiff_software>, C<tiff_datetime>,
1122 C<tiff_artist>, C<tiff_hostcomputer> - Various strings describing the
1123 image.  C<tiff_datetime> must be formatted as "YYYY:MM:DD HH:MM:SS".
1124 These correspond directly to the mixed case names in the TIFF
1125 specification.  These are set in images read from a TIFF and saved
1126 when writing a TIFF image.
1127
1128 =back
1129
1130 You can supply a C<page> parameter to the C<read()> method to read
1131 some page other than the first.  The page is 0 based:
1132
1133   # read the second image in the file
1134   $image->read(file=>"example.tif", page=>1)
1135     or die "Cannot read second page: ",$image->errstr,"\n";
1136
1137 If you read an image with multiple alpha channels, then only the first
1138 alpha channel will be read.
1139
1140 When reading a C<TIFF> image with callbacks, the C<seekcb> callback
1141 parameter is also required.
1142
1143 When writing a C<TIFF> image with callbacks, the C<seekcb> and
1144 C<readcb> parameters are also required.
1145
1146 C<TIFF> is a random access file format, it cannot be read from or
1147 written to unseekable streams such as pipes or sockets.
1148
1149 =head2 BMP (Windows Bitmap)
1150
1151 Imager can write 24-bit RGB, and 8, 4 and 1-bit per pixel paletted
1152 Windows BMP files.  Currently you cannot write compressed BMP files
1153 with Imager.
1154
1155 Imager can read 24-bit RGB, and 8, 4 and 1-bit perl pixel paletted
1156 Windows BMP files.  There is some support for reading 16-bit per pixel
1157 images, but I haven't found any for testing.
1158
1159 BMP has no support for multiple image files.
1160
1161 BMP files support the spatial resolution tags, but since BMP has no
1162 support for storing only an aspect ratio, if C<i_aspect_only> is set
1163 when you write the C<i_xres> and C<i_yres> values are scaled so the
1164 smaller is 72 DPI.
1165
1166 The following tags are set when you read an image from a BMP file:
1167
1168 =over
1169
1170 =item bmp_compression
1171
1172 The type of compression, if any.  This can be any of the following
1173 values:
1174
1175 =for stopwords RLE
1176
1177 =over
1178
1179 =item BI_RGB (0)
1180
1181 Uncompressed.
1182
1183 =item BI_RLE8 (1)
1184
1185 8-bits/pixel paletted value RLE compression.
1186
1187 =item BI_RLE4 (2)
1188
1189 4-bits/pixel paletted value RLE compression.
1190
1191 =item BI_BITFIELDS (3)
1192
1193 Packed RGB values.
1194
1195 =back
1196
1197 =item bmp_compression_name
1198
1199 The bmp_compression value as a BI_* string
1200
1201 =item bmp_important_colors
1202
1203 The number of important colors as defined by the writer of the image.
1204
1205 =item bmp_used_colors
1206
1207 Number of color used from the BMP header
1208
1209 =item bmp_filesize
1210
1211 The file size from the BMP header
1212
1213 =item bmp_bit_count
1214
1215 Number of bits stored per pixel. (24, 8, 4 or 1)
1216
1217 =back
1218
1219 =for stopwords Targa
1220
1221 =head2 TGA (Targa)
1222
1223 When storing Targa images RLE compression can be activated with the
1224 C<compress> parameter, the C<idstring> parameter can be used to set the
1225 Targa comment field and the C<wierdpack> option can be used to use the
1226 15 and 16 bit Targa formats for RGB and RGBA data.  The 15 bit format
1227 has 5 of each red, green and blue.  The 16 bit format in addition
1228 allows 1 bit of alpha.  The most significant bits are used for each
1229 channel.
1230
1231 Tags:
1232
1233 =over
1234
1235 =item tga_idstring
1236
1237 =item tga_bitspp
1238
1239 =item compressed
1240
1241 =back
1242
1243 =head2 RAW
1244
1245 When reading raw images you need to supply the width and height of the
1246 image in the C<xsize> and C<ysize> options:
1247
1248   $img->read(file=>'foo.raw', xsize=>100, ysize=>100)
1249     or die "Cannot read raw image\n";
1250
1251 If your input file has more channels than you want, or (as is common),
1252 junk in the fourth channel, you can use the C<raw_datachannels> and
1253 C<raw_storechannels> options to control the number of channels in your input
1254 file and the resulting channels in your image.  For example, if your
1255 input image uses 32-bits per pixel with red, green, blue and junk
1256 values for each pixel you could do:
1257
1258   $img->read(file=>'foo.raw', xsize => 100, ysize => 100,
1259              raw_datachannels => 4, raw_storechannels => 3,
1260              raw_interleave => 0)
1261     or die "Cannot read raw image\n";
1262
1263 In general, if you supply C<raw_storechannels> you should also supply
1264 C<raw_datachannels>
1265
1266 Read parameters:
1267
1268 =over
1269
1270 =item *
1271
1272 C<raw_interleave> - controls the ordering of samples within the image.
1273 Default: 1.  Alternatively and historically spelled C<interleave>.
1274 Possible values:
1275
1276 =over
1277
1278 =item *
1279
1280 0 - samples are pixel by pixel, so all samples for the first pixel,
1281 then all samples for the second pixel and so on.  eg. for a four pixel
1282 scan line the channels would be laid out as:
1283
1284   012012012012
1285
1286 =item *
1287
1288 1 - samples are line by line, so channel 0 for the entire scan line is
1289 followed by channel 1 for the entire scan line and so on.  eg. for a
1290 four pixel scan line the channels would be laid out as:
1291
1292   000011112222
1293
1294 This is the default.
1295
1296 =back
1297
1298 Unfortunately, historically, the default C<raw_interleave> for read
1299 has been 1, while writing only supports the C<raw_interleave> = 0
1300 format.
1301
1302 For future compatibility, you should always supply the
1303 C<raw_interleave> (or C<interleave>) parameter.  As of 0.68, Imager
1304 will warn if you attempt to read a raw image without a
1305 C<raw_interleave> parameter.
1306
1307 =item *
1308
1309 C<raw_storechannels> - the number of channels to store in the image.
1310 Range: 1 to 4.  Default: 3.  Alternatively and historically spelled
1311 C<storechannels>.
1312
1313 =item *
1314
1315 C<raw_datachannels> - the number of channels to read from the file.
1316 Range: 1 or more.  Default: 3.  Alternatively and historically spelled
1317 C<datachannels>.
1318
1319 =back
1320
1321   $img->read(file=>'foo.raw', xsize=100, ysize=>100, raw_interleave=>1)
1322     or die "Cannot read raw image\n";
1323
1324 =head2 PNG
1325
1326 =head3 PNG Image modes
1327
1328 PNG files can be read and written in the following modes:
1329
1330 =over
1331
1332 =item *
1333
1334 bi-level - written as a 1-bit per sample gray scale image
1335
1336 =item *
1337
1338 paletted - Imager gray scale paletted images are written as RGB
1339 paletted images.  PNG palettes can include alpha values for each entry
1340 and this is honored as an Imager four channel paletted image.
1341
1342 =item *
1343
1344 8 and 16-bit per sample gray scale, optionally with an alpha channel.
1345
1346 =item *
1347
1348 8 and 16-bit per sample RGB, optionally with an alpha channel.
1349
1350 =back
1351
1352 Unlike GIF, there is no automatic conversion to a paletted image,
1353 since PNG supports direct color.
1354
1355 =head3 PNG Text tags
1356
1357 Text tags are retrieved from and written to PNG C<tEXT> or C<zTXT>
1358 chunks.  The following standard tags from the PNG specification are
1359 directly supported:
1360
1361 =over
1362
1363 =item *
1364
1365 C<i_comment>X<tags,i_comment> - keyword of "Comment".
1366
1367 =item *
1368
1369 C<png_author>X<tags,PNG,png_author> - keyword "Author".
1370
1371 =item *
1372
1373 C<png_copyright>X<tags,PNG,png_copyright> - keyword "Copyright".
1374
1375 =item *
1376
1377 C<png_creation_time>X<tags,PNG,png_creation_time> - keyword "Creation Time".
1378
1379 =item *
1380
1381 C<png_description>X<tags,PNG,png_description> - keyword "Description".
1382
1383 =item *
1384
1385 C<png_disclaimer>X<tags,PNG,png_disclaimer> - keyword "Disclaimer".
1386
1387 =item *
1388
1389 C<png_software>X<tags,PNG,png_software> - keyword "Software".
1390
1391 =item *
1392
1393 C<png_title>X<tags,PNG,png_title> - keyword "Title".
1394
1395 =item *
1396
1397 C<png_warning>X<tags,PNG,png_warning> - keyword "Warning".
1398
1399 =back
1400
1401 Each of these tags has a corresponding C<< I<base-tag-name>_compressed
1402 >> tag, eg. C<png_comment_compressed>.  When reading, if the PNG chunk
1403 is compressed this tag will be set to 1, but is otherwise unset.  When
1404 writing, Imager will honor the compression tag if set and non-zero,
1405 otherwise the chunk text will be compressed if the value is longer
1406 than 1000 characters, as recommended by the C<libpng> documentation.
1407
1408 PNG C<tEXT> or C<zTXT> chunks outside of those above are read into or
1409 written from Imager tags named like:
1410
1411 =over
1412
1413 =item *
1414
1415 C<< png_textI<N>_key >> - the key for the text chunk.  This can be 1
1416 to 79 characters, may not contain any leading, trailing or consecutive
1417 spaces, and may contain only Latin-1 characters from 32-126, 161-255.
1418
1419 =item *
1420
1421 C<< png_textI<N>_text >> - the text for the text chunk.  This may not
1422 contain any C<NUL> characters.
1423
1424 =item *
1425
1426 C<< png_textI<N>_compressed >> - whether or not the text chunk is
1427 compressed.  This behaves similarly to the C<<
1428 I<base-tag-name>_compressed >> tags described above.
1429
1430 =back
1431
1432 Where I<N> starts from 0.  When writing both the C<..._key> and
1433 C<..._text> tags must be present or the write will fail.  If the key
1434 or text do not satisfy the requirements above the write will fail.
1435
1436 =head3 Other PNG metadata tags
1437
1438 =over
1439
1440 =item *
1441
1442 X<tags, png_interlace>C<png_interlace>, C<png_interlace_name> - only
1443 set when reading, C<png_interlace> is set to the type of interlacing
1444 used by the file, 0 for one, 1 for Adam7.  C<png_interlace_name> is
1445 set to a keyword describing the interlacing, either C<none> or
1446 C<adam7>.
1447
1448 =item *
1449
1450 X<tags, png_srgb_intent>C<png_srgb_intent> - the sRGB rendering intent
1451 for the image. an integer from 0 to 3, per the PNG specification.  If
1452 this chunk is found in the PNG file the C<gAMA> and C<cHRM> are
1453 ignored and the C<png_gamma> and C<png_chroma_...> tags are not set.
1454 Similarly when writing if C<png_srgb_intent> is set the C<gAMA> and
1455 C<cHRM> chunks are not written.
1456
1457 =item *
1458
1459 X<tags, png_gamma>C<png_gamma> - the gamma of the image. This value is
1460 not currently used by Imager when processing the image, but this may
1461 change in the future.
1462
1463 =item *
1464
1465 X<tags, png_chroma_...>C<png_chroma_white_x>, C<png_chroma_white_y>,
1466 C<png_chroma_red_x>, C<png_chroma_red_y>, C<png_chroma_green_x>,
1467 C<png_chroma_green_y>, C<png_chroma_blue_x>, C<png_chroma_blue_y> -
1468 the primary chromaticities of the image, defining the color model.
1469 This is currently not used by Imager when processing the image, but
1470 this may change in the future.
1471
1472 =item *
1473
1474 C<i_xres>, C<i_yres>, C<i_aspect_only> - processed per
1475 I<Imager::ImageTypes/CommonTags>.
1476
1477 =item *
1478
1479 X<tags, png_bits>C<png_bits> - the number of bits per sample in the
1480 representation.  Ignored when writing.
1481
1482 =item *
1483
1484 X<tags, png_time>C<png_time> - the creation time of the file formatted
1485 as C<< I<year>-I<month>-I<day>TI<hour>:I<minute>:I<second> >>.  This
1486 is stored as time data structure in the file, not a string.  If you
1487 set C<png_time> and it cannot be parsed as above, writing the PNG file
1488 will fail.
1489
1490 =item *
1491
1492 C<i_background> - set from the C<sBKG> when reading an image file.
1493
1494 =back
1495
1496 X<compression>X<png_compression_level>You can control the level of
1497 F<zlib> compression used when writing with the
1498 C<png_compression_level> parameter.  This can be an integer between 0
1499 (uncompressed) and 9 (best compression).
1500
1501 =for stopwords
1502 CRC
1503
1504 X<png_ignore_benign_errors>If you're using F<libpng> 1.6 or later, or
1505 an earlier release configured with C<PNG_BENIGN_ERRORS_SUPPORTED>, you
1506 can choose to ignore file format errors the authors of F<libpng>
1507 consider I<benign>, this includes at least CRC errors and palette
1508 index overflows.  Do this by supplying a true value for the
1509 C<png_ignore_benign_errors> parameter to the read() method:
1510
1511   $im->read(file => "foo.png", png_ignore_benign_errors => 1)
1512     or die $im->errstr;
1513
1514 =head2 ICO (Microsoft Windows Icon) and CUR (Microsoft Windows Cursor)
1515
1516 Icon and Cursor files are very similar, the only differences being a
1517 number in the header and the storage of the cursor hot spot.  I've
1518 treated them separately so that you're not messing with tags to
1519 distinguish between them.
1520
1521 The following tags are set when reading an icon image and are used
1522 when writing it:
1523
1524 =over
1525
1526 =item ico_mask
1527
1528 This is the AND mask of the icon.  When used as an icon in Windows 1
1529 bits in the mask correspond to pixels that are modified by the source
1530 image rather than simply replaced by the source image.
1531
1532 Rather than requiring a binary bitmap this is accepted in a specific format:
1533
1534 =over
1535
1536 =item *
1537
1538 first line consisting of the 0 placeholder, the 1 placeholder and a
1539 newline.
1540
1541 =item *
1542
1543 following lines which contain 0 and 1 placeholders for each scan line
1544 of the image, starting from the top of the image.
1545
1546 =back
1547
1548 When reading an image, '.' is used as the 0 placeholder and '*' as the
1549 1 placeholder.  An example:
1550
1551   .*
1552   ..........................******
1553   ..........................******
1554   ..........................******
1555   ..........................******
1556   ...........................*****
1557   ............................****
1558   ............................****
1559   .............................***
1560   .............................***
1561   .............................***
1562   .............................***
1563   ..............................**
1564   ..............................**
1565   ...............................*
1566   ...............................*
1567   ................................
1568   ................................
1569   ................................
1570   ................................
1571   ................................
1572   ................................
1573   *...............................
1574   **..............................
1575   **..............................
1576   ***.............................
1577   ***.............................
1578   ****............................
1579   ****............................
1580   *****...........................
1581   *****...........................
1582   *****...........................
1583   *****...........................
1584
1585 =back
1586
1587 The following tags are set when reading an icon:
1588
1589 =over
1590
1591 =item ico_bits
1592
1593 The number of bits per pixel used to store the image.
1594
1595 =back
1596
1597 For cursor files the following tags are set and read when reading and
1598 writing:
1599
1600 =over
1601
1602 =item cur_mask
1603
1604 This is the same as the ico_mask above.
1605
1606 =item cur_hotspotx
1607
1608 =item cur_hotspoty
1609
1610 The "hot" spot of the cursor image.  This is the spot on the cursor
1611 that you click with.  If you set these to out of range values they are
1612 clipped to the size of the image when written to the file.
1613
1614 =back
1615
1616 The following parameters can be supplied to read() or read_multi() to
1617 control reading of ICO/CUR files:
1618
1619 =over
1620
1621 =item *
1622
1623 C<ico_masked> - if true, the default, then the icon/cursors mask is
1624 applied as an alpha channel to the image, unless that image already
1625 has an alpha channel.  This may result in a paletted image being
1626 returned as a direct color image.  Default: 1
1627
1628   # retrieve the image as stored, without using the mask as an alpha
1629   # channel
1630   $img->read(file => 'foo.ico', ico_masked => 0)
1631     or die $img->errstr;
1632
1633 This was introduced in Imager 0.60.  Previously reading ICO images
1634 acted as if C<ico_masked =E<gt> 0>.
1635
1636 =item *
1637
1638 C<ico_alpha_masked> - if true, then the icon/cursor mask is applied as
1639 an alpha channel to images that already have an alpha mask.  Note that
1640 this will only make pixels transparent, not opaque.  Default: 0.
1641
1642 Note: If you get different results between C<ico_alpha_masked> being
1643 set to 0 and 1, your mask may break when used with the Win32 API.
1644
1645 =back
1646
1647 C<cur_bits> is set when reading a cursor.
1648
1649 Examples:
1650
1651   my $img = Imager->new(xsize => 32, ysize => 32, channels => 4);
1652   $im->box(color => 'FF0000');
1653   $im->write(file => 'box.ico');
1654
1655   $im->settag(name => 'cur_hotspotx', value => 16);
1656   $im->settag(name => 'cur_hotspoty', value => 16);
1657   $im->write(file => 'box.cur');
1658
1659 =for stopwords BW
1660
1661 =head2 SGI (RGB, BW)
1662
1663 SGI images, often called by the extensions, RGB or BW, can be stored
1664 either uncompressed or compressed using an RLE compression.
1665
1666 By default, when saving to an extension of C<rgb>, C<bw>, C<sgi>,
1667 C<rgba> the file will be saved in SGI format.  The file extension is
1668 otherwise ignored, so saving a 3-channel image to a C<.bw> file will
1669 result in a 3-channel image on disk.
1670
1671 The following tags are set when reading a SGI image:
1672
1673 =over
1674
1675 =item *
1676
1677 i_comment - the C<IMAGENAME> field from the image.  Also written to
1678 the file when writing.
1679
1680 =item *
1681
1682 sgi_pixmin, sgi_pixmax - the C<PIXMIN> and C<PIXMAX> fields from the
1683 image.  On reading image data is expanded from this range to the full
1684 range of samples in the image.
1685
1686 =item *
1687
1688 sgi_bpc - the number of bytes per sample for the image.  Ignored when
1689 writing.
1690
1691 =item *
1692
1693 sgi_rle - whether or not the image is compressed.  If this is non-zero
1694 when writing the image will be compressed.
1695
1696 =back
1697
1698 =head1 ADDING NEW FORMATS
1699
1700 To support a new format for reading, call the register_reader() class
1701 method:
1702
1703 =over
1704
1705 =item register_reader()
1706
1707 Registers single or multiple image read functions.
1708
1709 Parameters:
1710
1711 =over
1712
1713 =item *
1714
1715 type - the identifier of the file format, if Imager's
1716 i_test_format_probe() can identify the format then this value should
1717 match i_test_format_probe()'s result.
1718
1719 This parameter is required.
1720
1721 =item *
1722
1723 single - a code ref to read a single image from a file.  This is
1724 supplied:
1725
1726 =over
1727
1728 =item *
1729
1730 the object that read() was called on,
1731
1732 =item *
1733
1734 an Imager::IO object that should be used to read the file, and
1735
1736 =item *
1737
1738 all the parameters supplied to the read() method.
1739
1740 =back
1741
1742 The single parameter is required.
1743
1744 =item *
1745
1746 multiple - a code ref which is called to read multiple images from a
1747 file. This is supplied:
1748
1749 =over
1750
1751 =item *
1752
1753 an Imager::IO object that should be used to read the file, and
1754
1755 =item *
1756
1757 all the parameters supplied to the read_multi() method.
1758
1759 =back
1760
1761 =back
1762
1763 Example:
1764
1765   # from Imager::File::ICO
1766   Imager->register_reader
1767     (
1768      type=>'ico',
1769      single => 
1770      sub { 
1771        my ($im, $io, %hsh) = @_;
1772        $im->{IMG} = i_readico_single($io, $hsh{page} || 0);
1773
1774        unless ($im->{IMG}) {
1775          $im->_set_error(Imager->_error_as_msg);
1776          return;
1777        }
1778        return $im;
1779      },
1780      multiple =>
1781      sub {
1782        my ($io, %hsh) = @_;
1783      
1784        my @imgs = i_readico_multi($io);
1785        unless (@imgs) {
1786          Imager->_set_error(Imager->_error_as_msg);
1787          return;
1788        }
1789        return map { 
1790          bless { IMG => $_, DEBUG => $Imager::DEBUG, ERRSTR => undef }, 'Imager'
1791        } @imgs;
1792      },
1793     );
1794
1795 =item register_writer()
1796
1797 Registers single or multiple image write functions.
1798
1799 Parameters:
1800
1801 =over
1802
1803 =item *
1804
1805 type - the identifier of the file format.  This is typically the
1806 extension in lowercase.
1807
1808 This parameter is required.
1809
1810 =item *
1811
1812 single - a code ref to write a single image to a file.  This is
1813 supplied:
1814
1815 =over
1816
1817 =item *
1818
1819 the object that write() was called on,
1820
1821 =item *
1822
1823 an Imager::IO object that should be used to write the file, and
1824
1825 =item *
1826
1827 all the parameters supplied to the write() method.
1828
1829 =back
1830
1831 The single parameter is required.
1832
1833 =item *
1834
1835 multiple - a code ref which is called to write multiple images to a
1836 file. This is supplied:
1837
1838 =over
1839
1840 =item *
1841
1842 the class name write_multi() was called on, this is typically
1843 C<Imager>.
1844
1845 =item *
1846
1847 an Imager::IO object that should be used to write the file, and
1848
1849 =item *
1850
1851 all the parameters supplied to the read_multi() method.
1852
1853 =back
1854
1855 =back
1856
1857 =item add_type_extensions($type, $ext, ...)
1858
1859 This class method can be used to add extensions to the map used by
1860 C<def_guess_type> when working out the file type a filename extension.
1861
1862   Imager->add_type_extension(mytype => "mytype", "mytypish");
1863   ...
1864   $im->write(file => "foo.mytypish") # use the mytype handler
1865
1866 =back
1867
1868 If you name the reader module C<Imager::File::>I<your-format-name>
1869 where I<your-format-name> is a fully upper case version of the type
1870 value you would pass to read(), read_multi(), write() or write_multi()
1871 then Imager will attempt to load that module if it has no other way to
1872 read or write that format.
1873
1874 For example, if you create a module Imager::File::GIF and the user has
1875 built Imager without it's normal GIF support then an attempt to read a
1876 GIF image will attempt to load Imager::File::GIF.
1877
1878 If your module can only handle reading then you can name your module
1879 C<Imager::File::>I<your-format-name>C<Reader> and Imager will attempt
1880 to autoload it.
1881
1882 If your module can only handle writing then you can name your module 
1883 C<Imager::File::>I<your-format-name>C<Writer> and Imager will attempt
1884 to autoload it.
1885
1886 =head1 PRELOADING FILE MODULES
1887
1888 =over
1889
1890 =item preload()
1891
1892 This preloads the file support modules included with or that have been
1893 included with Imager in the past.  This is intended for use in forking
1894 servers such as mod_perl.
1895
1896 If the module is not available no error occurs.
1897
1898 Preserves $@.
1899
1900   use Imager;
1901   Imager->preload;
1902
1903 =back
1904
1905 =head1 EXAMPLES
1906
1907 =head2 Producing an image from a CGI script
1908
1909 Once you have an image the basic mechanism is:
1910
1911 =for stopwords STDOUT
1912
1913 =over
1914
1915 =item 1.
1916
1917 set STDOUT to autoflush
1918
1919 =item 2.
1920
1921 output a content-type header, and optionally a content-length header
1922
1923 =item 3.
1924
1925 put STDOUT into binmode
1926
1927 =item 4.
1928
1929 call write() with the C<fd> or C<fh> parameter.  You will need to
1930 provide the C<type> parameter since Imager can't use the extension to
1931 guess the file format you want.
1932
1933 =back
1934
1935   # write an image from a CGI script
1936   # using CGI.pm
1937   use CGI qw(:standard);
1938   $| = 1;
1939   binmode STDOUT;
1940   print header(-type=>'image/gif');
1941   $img->write(type=>'gif', fd=>fileno(STDOUT))
1942     or die $img->errstr;
1943
1944 If you want to send a content length you can send the output to a
1945 scalar to get the length:
1946
1947   my $data;
1948   $img->write(type=>'gif', data=>\$data)
1949     or die $img->errstr;
1950   binmode STDOUT;
1951   print header(-type=>'image/gif', -content_length=>length($data));
1952   print $data;
1953
1954 =head2 Writing an animated GIF
1955
1956 The basic idea is simple, just use write_multi():
1957
1958   my @imgs = ...;
1959   Imager->write_multi({ file=>$filename, type=>'gif' }, @imgs);
1960
1961 If your images are RGB images the default quantization mechanism will
1962 produce a very good result, but can take a long time to execute.  You
1963 could either use the standard web color map:
1964
1965   Imager->write_multi({ file=>$filename, 
1966                         type=>'gif',
1967                         make_colors=>'webmap' },
1968                       @imgs);
1969
1970 or use a median cut algorithm to built a fairly optimal color map:
1971
1972   Imager->write_multi({ file=>$filename,
1973                         type=>'gif',
1974                         make_colors=>'mediancut' },
1975                       @imgs);
1976
1977 By default all of the images will use the same global color map, which
1978 will produce a smaller image.  If your images have significant color
1979 differences, you may want to generate a new palette for each image:
1980
1981   Imager->write_multi({ file=>$filename,
1982                         type=>'gif',
1983                         make_colors=>'mediancut',
1984                         gif_local_map => 1 },
1985                       @imgs);
1986
1987 which will set the C<gif_local_map> tag in each image to 1.
1988 Alternatively, if you know only some images have different colors, you
1989 can set the tag just for those images:
1990
1991   $imgs[2]->settag(name=>'gif_local_map', value=>1);
1992   $imgs[4]->settag(name=>'gif_local_map', value=>1);
1993
1994 and call write_multi() without a C<gif_local_map> parameter, or supply
1995 an arrayref of values for the tag:
1996
1997   Imager->write_multi({ file=>$filename,
1998                         type=>'gif',
1999                         make_colors=>'mediancut',
2000                         gif_local_map => [ 0, 0, 1, 0, 1 ] },
2001                       @imgs);
2002
2003 Other useful parameters include C<gif_delay> to control the delay
2004 between frames and C<transp> to control transparency.
2005
2006 =head2 Reading tags after reading an image
2007
2008 This is pretty simple:
2009
2010   # print the author of a TIFF, if any
2011   my $img = Imager->new;
2012   $img->read(file=>$filename, type='tiff') or die $img->errstr;
2013   my $author = $img->tags(name=>'tiff_author');
2014   if (defined $author) {
2015     print "Author: $author\n";
2016   }
2017
2018 =head1 BUGS
2019
2020 When saving GIF images the program does NOT try to shave off extra
2021 colors if it is possible.  If you specify 128 colors and there are
2022 only 2 colors used - it will have a 128 color table anyway.
2023
2024 =head1 SEE ALSO
2025
2026 Imager(3)
2027
2028 =head1 AUTHOR
2029
2030 Tony Cook <tonyc@cpan.org>, Arnar M. Hrafnkelsson
2031
2032 =cut