huge spelling update and spell checking patch
[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 appropriate libraries, and images can be read or written to/from
62 files, file handles, file descriptors, scalars, or through callbacks.
63
64 To see which image formats Imager is compiled to support the following
65 code snippet is sufficient:
66
67   use Imager;
68   print join " ", keys %Imager::formats;
69
70 This will include some other information identifying libraries rather
71 than file formats.  For new code you might find the L</read_types> or
72 L</write_types> methods useful.
73
74 =over 
75
76 =item read
77
78 Reading writing to and from files is simple, use the C<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 C<allow_partial> parameter.  If this is
92 non-zero then read() can return true on an incomplete image and set
93 the C<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, check
97 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 =item write
104
105 and the C<write()> method to write an image:
106
107   $img->write(file=>$filename, type=>$type)
108     or die "Cannot write $filename: ", $img->errstr;
109
110 =item read_multi
111
112 If you're reading from a format that supports multiple images per
113 file, use the C<read_multi()> method:
114
115   my @imgs = Imager->read_multi(file=>$filename, type=>$type)
116     or die "Cannot read $filename: ", Imager->errstr;
117
118 As with the read() method, Imager will normally detect the C<type>
119 automatically.
120
121 =item write_multi
122
123 and if you want to write multiple images to a single file use the
124 C<write_multi()> method:
125
126   Imager->write_multi({ file=> $filename, type=>$type }, @images)
127     or die "Cannot write $filename: ", Imager->errstr;
128
129 =item read_types
130
131 This is a class method that returns a list of the image file types
132 that Imager can read.
133
134   my @types = Imager->read_types;
135
136 These types are the possible values for the C<type> parameter, not
137 necessarily the extension of the files you're reading.
138
139 It is possible for extra file read handlers to be loaded when
140 attempting to read a file, which may modify the list of available read
141 types.
142
143 =item write_types
144
145 This is a class method that returns a list of the image file types
146 that Imager can write.
147
148   my @types = Imager->write_types;
149
150 Note that these are the possible values for the C<type> parameter, not
151 necessarily the extension of the files you're writing.
152
153 It is possible for extra file write handlers to be loaded when
154 attempting to write a file, which may modify the list of available
155 write types.
156
157 =back
158
159 When writing, if the C<filename> includes an extension that Imager
160 recognizes, then you don't need the C<type>, but you may want to
161 provide one anyway.  See L</Guessing types> for information on
162 controlling this recognition.
163
164 The C<type> parameter is a lowercase representation of the file type,
165 and can be any of the following:
166
167   bmp   Windows BitMaP (BMP)
168   gif   Graphics Interchange Format (GIF)
169   jpeg  JPEG/JFIF
170   png   Portable Network Graphics (PNG)
171   pnm   Portable aNyMap (PNM)
172   raw   Raw
173   sgi   SGI .rgb files
174   tga   TARGA
175   tiff  Tagged Image File Format (TIFF)
176
177 When you read an image, Imager may set some tags, possibly including
178 information about the spatial resolution, textual information, and
179 animation information.  See L<Imager::ImageTypes/Tags> for specifics.
180
181 The open() method is a historical alias for the read() method.
182
183 =head2 Input and output
184
185 When reading or writing you can specify one of a variety of sources or
186 targets:
187
188 =over
189
190 =item *
191
192 C<file> - The C<file> parameter is the name of the image file to be
193 written to or read from.  If Imager recognizes the extension of the
194 file you do not need to supply a C<type>.
195
196   # write in tiff format
197   $image->write(file => "example.tif")
198     or die $image->errstr;
199
200   $image->write(file => 'foo.tmp', type => 'tiff')
201     or die $image->errstr;
202
203   my $image = Imager->new;
204   $image->read(file => 'example.tif')
205     or die $image->errstr;
206
207 =item *
208
209 C<fh> - C<fh> is a file handle, typically either returned from
210 C<<IO::File->new()>>, or a glob from an C<open> call.  You should call
211 C<binmode> on the handle before passing it to Imager.
212
213 Imager will set the handle to autoflush to make sure any buffered data
214 is flushed , since Imager will write to the file descriptor (from
215 fileno()) rather than writing at the perl level.
216
217   $image->write(fh => \*STDOUT, type => 'gif')
218     or die $image->errstr;
219
220   # for example, a file uploaded via CGI.pm
221   $image->read(fd => $cgi->param('file')) 
222     or die $image->errstr;
223
224 =item *
225
226 C<fd> - C<fd> is a file descriptor.  You can get this by calling the
227 C<fileno()> function on a file handle, or by using one of the standard
228 file descriptor numbers.
229
230 If you get this from a perl file handle, you may need to flush any
231 buffered output, otherwise it may appear in the output stream after
232 the image.
233
234   $image->write(fd => file(STDOUT), type => 'gif')
235     or die $image->errstr;
236
237 =item *
238
239 C<data> - When reading data, C<data> is a scalar containing the image
240 file data, when writing, C<data> is a reference to the scalar to save
241 the image file data too.  For GIF images you will need C<giflib> 4 or
242 higher, and you may need to patch C<giflib> to use this option for
243 writing.
244
245   my $data;
246   $image->write(data => \$data, type => 'tiff')
247     or die $image->errstr;
248
249   my $data = $row->{someblob}; # eg. from a database
250   my @images = Imager->read_multi(data => $data)
251     or die Imager->errstr;
252
253 =item *
254
255 C<callback> - Imager will make calls back to your supplied coderefs to
256 read, write and seek from/to/through the image file.
257
258 When reading from a file you can use either C<callback> or C<readcb>
259 to supply the read callback, and when writing C<callback> or
260 C<writecb> to supply the write callback.
261
262 When writing you can also supply the C<maxbuffer> option to set the
263 maximum amount of data that will be buffered before your write
264 callback is called.  Note: the amount of data supplied to your
265 callback can be smaller or larger than this size.
266
267 The read callback is called with 2 parameters, the minimum amount of
268 data required, and the maximum amount that Imager will store in it's C
269 level buffer.  You may want to return the minimum if you have a slow
270 data source, or the maximum if you have a fast source and want to
271 prevent many calls to your perl callback.  The read data should be
272 returned as a scalar.
273
274 Your write callback takes exactly one parameter, a scalar containing
275 the data to be written.  Return true for success.
276
277 The seek callback takes 2 parameters, a I<POSITION>, and a I<WHENCE>,
278 defined in the same way as perl's seek function.
279
280 You can also supply a C<closecb> which is called with no parameters
281 when there is no more data to be written.  This could be used to flush
282 buffered data.
283
284   # contrived
285   my $data;
286   sub mywrite {
287     $data .= unpack("H*", shift);
288     1;
289   }
290   Imager->write_multi({ callback => \&mywrite, type => 'gif'}, @images)
291     or die Imager->errstr;
292
293 Note that for reading you'll almost always need to provide a
294 C<seekcb>.
295
296 =back
297
298 =head2 Guessing types
299
300 When writing to a file, if you don't supply a C<type> parameter Imager
301 will attempt to guess it from the file name.  This is done by calling
302 the code reference stored in C<$Imager::FORMATGUESS>.  This is only
303 done when write() or write_multi() is called with a C<file> parameter.
304
305 The default function value of C<$Imager::FORMATGUESS> is
306 C<\&Imager::def_guess_type>.
307
308 =over
309
310 =item def_guess_type
311
312 This is the default function Imager uses to derive a file type from a
313 file name.  This is a function, not a method.
314
315 Accepts a single parameter, the file name and returns the type or
316 undef.
317
318 =back
319
320 You can replace function with your own implementation if you have some
321 specialized need.  The function takes a single parameter, the name of
322 the file, and should return either a file type or under.
323
324   # I'm writing jpegs to weird filenames
325   local $Imager::FORMATGUESS = sub { 'jpeg' };
326
327 When reading a file Imager examines beginning of the file for
328 identifying information.  The current implementation attempts to
329 detect the following image types beyond those supported by Imager:
330
331 =for stopwords Photoshop
332
333 =over
334
335 C<xpm>, C<mng>, C<jng>, C<ilbm>, C<pcx>, C<fits>, C<psd> (Photoshop), C<eps>, Utah
336 C<RLE>.
337
338 =back
339
340 =head2 Limiting the sizes of images you read
341
342 =over
343
344 =item set_file_limits
345
346 In some cases you will be receiving images from an untested source,
347 such as submissions via CGI.  To prevent such images from consuming
348 large amounts of memory, you can set limits on the dimensions of
349 images you read from files:
350
351 =over
352
353 =item *
354
355 width - limit the width in pixels of the image
356
357 =item *
358
359 height - limit the height in pixels of the image
360
361 =item *
362
363 bytes - limits the amount of storage used by the image.  This depends
364 on the width, height, channels and sample size of the image.  For
365 paletted images this is calculated as if the image was expanded to a
366 direct color image.
367
368 =back
369
370 To set the limits, call the class method set_file_limits:
371
372   Imager->set_file_limits(width=>$max_width, height=>$max_height);
373
374 You can pass any or all of the limits above, any limits you do not
375 pass are left as they were.
376
377 Any limit of zero is treated as unlimited.
378
379 By default, all of the limits are zero, or unlimited.
380
381 You can reset all of the limited to their defaults by passing in the
382 reset parameter as a true value:
383
384   # no limits
385   Imager->set_file_limits(reset=>1);
386
387 This can be used with the other limits to reset all but the limit you
388 pass:
389
390   # only width is limited
391   Imager->set_file_limits(reset=>1, width=>100);
392
393   # only bytes is limited
394   Imager->set_file_limits(reset=>1, bytes=>10_000_000);
395
396 =item get_file_limits
397
398 You can get the current limits with the get_file_limits() method:
399
400   my ($max_width, $max_height, $max_bytes) =
401      Imager->get_file_limits();
402
403 =back
404
405 =head1 TYPE SPECIFIC INFORMATION
406
407 The different image formats can write different image type, and some have
408 different options to control how the images are written.
409
410 When you call C<write()> or C<write_multi()> with an option that has
411 the same name as a tag for the image format you're writing, then the
412 value supplied to that option will be used to set the corresponding
413 tag in the image.  Depending on the image format, these values will be
414 used when writing the image.
415
416 This replaces the previous options that were used when writing GIF
417 images.  Currently if you use an obsolete option, it will be converted
418 to the equivalent tag and Imager will produced a warning.  You can
419 suppress these warnings by calling the C<Imager::init()> function with
420 the C<warn_obsolete> option set to false:
421
422   Imager::init(warn_obsolete=>0);
423
424 At some point in the future these obsolete options will no longer be
425 supported.
426
427 =for stopwords aNy PixMaps BitMap
428
429 =head2 PNM (Portable aNy Map)
430
431 Imager can write C<PGM> (Portable Gray Map) and C<PPM> (Portable
432 PixMaps) files, depending on the number of channels in the image.
433 Currently the images are written in binary formats.  Only 1 and 3
434 channel images can be written, including 1 and 3 channel paletted
435 images.
436
437   $img->write(file=>'foo.ppm') or die $img->errstr;
438
439 Imager can read both the ASCII and binary versions of each of the
440 C<PBM> (Portable BitMap), C<PGM> and C<PPM> formats.
441
442   $img->read(file=>'foo.ppm') or die $img->errstr;
443
444 PNM does not support the spatial resolution tags.
445
446 The following tags are set when reading a PNM file:
447
448 =over
449
450 =item *
451
452 X<pnm_maxval>C<pnm_maxval> - the C<maxvals> number from the PGM/PPM header.
453 Always set to 2 for a C<PBM> file.
454
455 =item *
456
457 X<pnm_type>C<pnm_type> - the type number from the C<PNM> header, 1 for ASCII
458 C<PBM> files, 2 for ASCII C<PGM> files, 3 for ASCII c<PPM> files, 4 for binary
459 C<PBM> files, 5 for binary C<PGM> files, 6 for binary C<PPM> files.
460
461 =back
462
463 The following tag is checked when writing an image with more than
464 8-bits/sample:
465
466 =over
467
468 =item *
469
470 X<pnm_write_wide_data>pnm_write_wide_data - if this is non-zero then
471 write() can write C<PGM>/C<PPM> files with 16-bits/sample.  Some
472 applications, for example GIMP 2.2, and tools can only read
473 8-bit/sample binary PNM files, so Imager will only write a 16-bit
474 image when this tag is non-zero.
475
476 =back
477
478 =head2 JPEG
479
480 =for stopwords composited
481
482 You can supply a C<jpegquality> parameter (0-100) when writing a JPEG
483 file, which defaults to 75%.  If you write an image with an alpha
484 channel to a JPEG file then it will be composited against the
485 background set by the C<i_background> parameter (or tag).
486
487   $img->write(file=>'foo.jpg', jpegquality=>90) or die $img->errstr;
488
489 Imager will read a gray scale JPEG as a 1 channel image and a color
490 JPEG as a 3 channel image.
491
492   $img->read(file=>'foo.jpg') or die $img->errstr;
493
494 The following tags are set in a JPEG image when read, and can be set
495 to control output:
496
497 =over
498
499 =item C<jpeg_density_unit>
500
501 The value of the density unit field in the C<JFIF> header.  This is
502 ignored on writing if the C<i_aspect_only> tag is non-zero.
503
504 The C<i_xres> and C<i_yres> tags are expressed in pixels per inch no
505 matter the value of this tag, they will be converted to/from the value
506 stored in the JPEG file.
507
508 =item C<jpeg_density_unit_name>
509
510 This is set when reading a JPEG file to the name of the unit given by
511 C<jpeg_density_unit>.  Possible results include C<inch>,
512 C<centimeter>, C<none> (the C<i_aspect_only> tag is also set reading
513 these files).  If the value of C<jpeg_density_unit> is unknown then
514 this tag isn't set.
515
516 =item C<jpeg_comment>
517
518 Text comment.
519
520 =back
521
522 JPEG supports the spatial resolution tags C<i_xres>, C<i_yres> and
523 C<i_aspect_only>.
524
525 =for stopwords EXIF
526
527 If an C<APP1> block containing EXIF information is found, then any of the
528 following tags can be set:
529
530 =over
531
532 exif_aperture exif_artist exif_brightness exif_color_space
533 exif_contrast exif_copyright exif_custom_rendered exif_date_time
534 exif_date_time_digitized exif_date_time_original
535 exif_digital_zoom_ratio exif_exposure_bias exif_exposure_index
536 exif_exposure_mode exif_exposure_program exif_exposure_time
537 exif_f_number exif_flash exif_flash_energy exif_flashpix_version
538 exif_focal_length exif_focal_length_in_35mm_film
539 exif_focal_plane_resolution_unit exif_focal_plane_x_resolution
540 exif_focal_plane_y_resolution exif_gain_control exif_image_description
541 exif_image_unique_id exif_iso_speed_rating exif_make exif_max_aperture
542 exif_metering_mode exif_model exif_orientation exif_related_sound_file
543 exif_resolution_unit exif_saturation exif_scene_capture_type
544 exif_sensing_method exif_sharpness exif_shutter_speed exif_software
545 exif_spectral_sensitivity exif_sub_sec_time
546 exif_sub_sec_time_digitized exif_sub_sec_time_original
547 exif_subject_distance exif_subject_distance_range
548 exif_subject_location exif_tag_light_source exif_user_comment
549 exif_version exif_white_balance exif_x_resolution exif_y_resolution
550
551 =back
552
553 The following derived tags can also be set:
554
555 =over
556
557 exif_color_space_name exif_contrast_name exif_custom_rendered_name
558 exif_exposure_mode_name exif_exposure_program_name exif_flash_name
559 exif_focal_plane_resolution_unit_name exif_gain_control_name
560 exif_light_source_name exif_metering_mode_name
561 exif_resolution_unit_name exif_saturation_name
562 exif_scene_capture_type_name exif_sensing_method_name
563 exif_sharpness_name exif_subject_distance_range_name
564 exif_white_balance_name
565
566 =back
567
568 The derived tags are for enumerated fields, when the value for the
569 base field is valid then the text that appears in the EXIF
570 specification for that value appears in the derived field.  So for
571 example if C<exf_metering_mode> is C<5> then
572 C<exif_metering_mode_name> is set to C<Pattern>.
573
574 eg.
575
576   my $image = Imager->new;
577   $image->read(file => 'exiftest.jpg')
578     or die "Cannot load image: ", $image->errstr;
579   print $image->tags(name => "exif_image_description"), "\n";
580   print $image->tags(name => "exif_exposure_mode"), "\n";
581   print $image->tags(name => "exif_exposure_mode_name"), "\n";
582
583   # for the exiftest.jpg in the Imager distribution the output would be:
584   Imager Development Notes
585   0
586   Auto exposure
587
588 =for stopwords IPTC
589
590 =over
591
592 =item parseiptc()
593
594 Historically, Imager saves IPTC data when reading a JPEG image, the
595 parseiptc() method returns a list of key/value pairs resulting from a
596 simple decoding of that data.
597
598 Any future IPTC data decoding is likely to go into tags.
599
600 =back
601
602 =head2 GIF (Graphics Interchange Format)
603
604 When writing one of more GIF images you can use the same
605 L<Quantization Options|Imager::ImageTypes> as you can when converting
606 an RGB image into a paletted image.
607
608 When reading a GIF all of the sub-images are combined using the screen
609 size and image positions into one big image, producing an RGB image.
610 This may change in the future to produce a paletted image where possible.
611
612 When you read a single GIF with C<$img-E<gt>read()> you can supply a
613 reference to a scalar in the C<colors> parameter, if the image is read
614 the scalar will be filled with a reference to an anonymous array of
615 L<Imager::Color> objects, representing the palette of the image.  This
616 will be the first palette found in the image.  If you want the
617 palettes for each of the images in the file, use C<read_multi()> and
618 use the C<getcolors()> method on each image.
619
620 GIF does not support the spatial resolution tags.
621
622 Imager will set the following tags in each image when reading, and can
623 use most of them when writing to GIF:
624
625 =over
626
627 =item *
628
629 gif_left - the offset of the image from the left of the "screen"
630 ("Image Left Position")
631
632 =item *
633
634 gif_top - the offset of the image from the top of the "screen" ("Image
635 Top Position")
636
637 =item *
638
639 gif_interlace - non-zero if the image was interlaced ("Interlace
640 Flag")
641
642 =item *
643
644 gif_screen_width, gif_screen_height - the size of the logical
645 screen. When writing this is used as the minimum.  If any image being
646 written would extend beyond this then the screen size is extended.
647 ("Logical Screen Width", "Logical Screen Height").
648
649 =item *
650
651 gif_local_map - Non-zero if this image had a local color map.  If set
652 for an image when writing the image is quantized separately from the
653 other images in the file.
654
655 =item *
656
657 gif_background - The index in the global color map of the logical
658 screen's background color.  This is only set if the current image uses
659 the global color map.  You can set this on write too, but for it to
660 choose the color you want, you will need to supply only paletted
661 images and set the C<gif_eliminate_unused> tag to 0.
662
663 =item *
664
665 gif_trans_index - The index of the color in the color map used for
666 transparency.  If the image has a transparency then it is returned as
667 a 4 channel image with the alpha set to zero in this palette entry.
668 This value is not used when writing. ("Transparent Color Index")
669
670 =item *
671
672 gif_trans_color - A reference to an Imager::Color object, which is the
673 color to use for the palette entry used to represent transparency in
674 the palette.  You need to set the C<transp> option (see L<Quantization
675 options>) for this value to be used.
676
677 =item *
678
679 gif_delay - The delay until the next frame is displayed, in 1/100 of a
680 second.  ("Delay Time").
681
682 =item *
683
684 gif_user_input - whether or not a user input is expected before
685 continuing (view dependent) ("User Input Flag").
686
687 =item *
688
689 gif_disposal - how the next frame is displayed ("Disposal Method")
690
691 =item *
692
693 gif_loop - the number of loops from the Netscape Loop extension.  This
694 may be zero to loop forever.
695
696 =item *
697
698 gif_comment - the first block of the first GIF comment before each
699 image.
700
701 =item *
702
703 gif_eliminate_unused - If this is true, when you write a paletted
704 image any unused colors will be eliminated from its palette.  This is
705 set by default.
706
707 =item *
708
709 gif_colormap_size - the original size of the color map for the image.
710 The color map of the image may have been expanded to include out of
711 range color indexes.
712
713 =back
714
715 Where applicable, the ("name") is the name of that field from the C<GIF89>
716 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 =over
723
724 =item *
725
726 gif_each_palette - Each image in the GIF file has it's own palette if
727 this is non-zero.  All but the first image has a local color table
728 (the first uses the global color table.
729
730 Use C<gif_local_map> in new code.
731
732 =item *
733
734 interlace - The images are written interlaced if this is non-zero.
735
736 Use C<gif_interlace> in new code.
737
738 =item *
739
740 gif_delays - A reference to an array containing the delays between
741 images, in 1/100 seconds.
742
743 Use C<gif_delay> in new code.
744
745 =item *
746
747 gif_positions - A reference to an array of references to arrays which
748 represent screen positions for each image.
749
750 New code should use the C<gif_left> and C<gif_top> tags.
751
752 =item *
753
754 gif_loop_count - If this is non-zero the Netscape loop extension block
755 is generated, which makes the animation of the images repeat.
756
757 This is currently unimplemented due to some limitations in C<giflib>.
758
759 =back
760
761 You can supply a C<page> parameter to the C<read()> method to read
762 some page other than the first.  The page is 0 based:
763
764   # read the second image in the file
765   $image->read(file=>"example.gif", page=>1)
766     or die "Cannot read second page: ",$image->errstr,"\n";
767
768 Before release 0.46, Imager would read multiple image GIF image files
769 into a single image, overlaying each of the images onto the virtual
770 GIF screen.
771
772 As of 0.46 the default is to read the first image from the file, as if
773 called with C<< page => 0 >>.
774
775 You can return to the previous behavior by calling read with the
776 C<gif_consolidate> parameter set to a true value:
777
778   $img->read(file=>$some_gif_file, gif_consolidate=>1);
779
780 As with the to_paletted() method, if you supply a colors parameter as
781 a reference to an array, this will be filled with Imager::Color
782 objects of the color table generated for the image file.
783
784 =head2 TIFF (Tagged Image File Format)
785
786 Imager can write images to either paletted or RGB TIFF images,
787 depending on the type of the source image.  Currently if you write a
788 16-bit/sample or double/sample image it will be written as an
789 8-bit/sample image.  Only 1 or 3 channel images can be written.
790
791 If you are creating images for faxing you can set the I<class>
792 parameter set to C<fax>.  By default the image is written in fine
793 mode, but this can be overridden by setting the I<fax_fine> parameter
794 to zero.  Since a fax image is bi-level, Imager uses a threshold to
795 decide if a given pixel is black or white, based on a single channel.
796 For gray scale images channel 0 is used, for color images channel 1
797 (green) is used.  If you want more control over the conversion you can
798 use $img->to_paletted() to product a bi-level image.  This way you can
799 use dithering:
800
801   my $bilevel = $img->to_paletted(make_colors => 'mono',
802                                   translate => 'errdiff',
803                                   errdiff => 'stucki');
804
805 =over
806
807 =item class
808
809 If set to 'fax' the image will be written as a bi-level fax image.
810
811 =item fax_fine
812
813 By default when I<class> is set to 'fax' the image is written in fine
814 mode, you can select normal mode by setting I<fax_fine> to 0.
815
816 =back
817
818 Imager should be able to read any TIFF image you supply.  Paletted
819 TIFF images are read as paletted Imager images, since paletted TIFF
820 images have 16-bits/sample (48-bits/color) this means the bottom
821 8-bits are lost, but this shouldn't be a big deal.  Currently all
822 direct color images are read at 8-bits/sample.
823
824 TIFF supports the spatial resolution tags.  See the
825 C<tiff_resolutionunit> tag for some extra options.
826
827 As of Imager 0.62 Imager reads:
828
829 =over
830
831 =item *
832
833 16-bit gray, RGB, or CMYK image, including a possible alpha channel as
834 a 16-bit/sample image.
835
836 =item *
837
838 32-bit gray, RGB image, including a possible alpha channel as a
839 double/sample image.
840
841 =item *
842
843 bi-level images as paletted images containing only black and white,
844 which other formats will also write as bi-level.
845
846 =item *
847
848 tiled paletted images are now handled correctly
849
850 =back
851
852 The following tags are set in a TIFF image when read, and can be set
853 to control output:
854
855 =over
856
857 =item tiff_compression
858
859 When reading an image this is set to the numeric value of the TIFF
860 compression tag.
861
862 On writing you can set this to either a numeric compression tag value,
863 or one of the following values:
864
865   Ident     Number  Description
866   none         1    No compression
867   packbits   32773  Macintosh RLE
868   ccittrle     2    CCITT RLE
869   fax3         3    CCITT Group 3 fax encoding (T.4)
870   t4           3    As above
871   fax4         4    CCITT Group 4 fax encoding (T.6)
872   t6           4    As above
873   lzw          5    LZW
874   jpeg         7    JPEG
875   zip          8    Deflate (GZIP) Non-standard
876   deflate      8    As above.
877   oldzip     32946  Deflate with an older code.
878   ccittrlew  32771  Word aligned CCITT RLE
879
880 In general a compression setting will be ignored where it doesn't make
881 sense, eg. C<jpeg> will be ignored for compression if the image is
882 being written as bilevel.
883
884 =for stopwords LZW
885
886 Imager attempts to check that your build of C<libtiff> supports the
887 given compression, and will fallback to C<packbits> if it isn't
888 enabled.  eg. older distributions didn't include LZW compression, and
889 JPEG compression is only available if C<libtiff> is configured with
890 C<libjpeg>'s location.
891
892   $im->write(file => 'foo.tif', tiff_compression => 'lzw')
893     or die $im->errstr;
894
895 =item tiff_jpegquality
896
897 If I<tiff_compression> if C<jpeg> then this can be a number from 1 to
898 100 giving the JPEG compression quality.  High values are better
899 quality and larger files.
900
901 =item tiff_resolutionunit
902
903 The value of the C<ResolutionUnit> tag.  This is ignored on writing if
904 the i_aspect_only tag is non-zero.
905
906 The C<i_xres> and C<i_yres> tags are expressed in pixels per inch no
907 matter the value of this tag, they will be converted to/from the value
908 stored in the TIFF file.
909
910 =item tiff_resolutionunit_name
911
912 This is set when reading a TIFF file to the name of the unit given by
913 C<tiff_resolutionunit>.  Possible results include C<inch>,
914 C<centimeter>, C<none> (the C<i_aspect_only> tag is also set reading
915 these files) or C<unknown>.
916
917 =item tiff_bitspersample
918
919 Bits per sample from the image.  This value is not used when writing
920 an image, it is only set on a read image.
921
922 =item tiff_photometric
923
924 Value of the C<PhotometricInterpretation> tag from the image.  This
925 value is not used when writing an image, it is only set on a read
926 image.
927
928 =item tiff_documentname
929
930 =item tiff_imagedescription
931
932 =item tiff_make
933
934 =item tiff_model
935
936 =item tiff_pagename
937
938 =item tiff_software
939
940 =item tiff_datetime
941
942 =item tiff_artist
943
944 =item tiff_hostcomputer
945
946 Various strings describing the image.  tiff_datetime must be formatted
947 as "YYYY:MM:DD HH:MM:SS".  These correspond directly to the mixed case
948 names in the TIFF specification.  These are set in images read from a
949 TIFF and saved when writing a TIFF image.
950
951 =back
952
953 You can supply a C<page> parameter to the C<read()> method to read
954 some page other than the first.  The page is 0 based:
955
956   # read the second image in the file
957   $image->read(file=>"example.tif", page=>1)
958     or die "Cannot read second page: ",$image->errstr,"\n";
959
960 Note: Imager uses the TIFF*RGBA* family of C<libtiff> functions,
961 unfortunately these don't support alpha channels on CMYK images.  This
962 will result in a full coverage alpha channel on CMYK images with an
963 alpha channel, until this is implemented in C<libtiff> (or Imager's TIFF
964 implementation changes.)
965
966 If you read an image with multiple alpha channels, then only the first
967 alpha channel will be read.
968
969 Currently Imager's TIFF support reads all direct color images as 8-bit
970 RGB images, this may change in the future to reading 16-bit/sample
971 images.
972
973 Currently tags that control the output color type and compression are
974 ignored when writing, this may change in the future.  If you have
975 processes that rely upon Imager always producing C<packbits>
976 compressed RGB images, you should strip any tags before writing.
977
978 =head2 BMP (Windows Bitmap)
979
980 Imager can write 24-bit RGB, and 8, 4 and 1-bit per pixel paletted
981 Windows BMP files.  Currently you cannot write compressed BMP files
982 with Imager.
983
984 Imager can read 24-bit RGB, and 8, 4 and 1-bit perl pixel paletted
985 Windows BMP files.  There is some support for reading 16-bit per pixel
986 images, but I haven't found any for testing.
987
988 BMP has no support for multiple image files.
989
990 BMP files support the spatial resolution tags, but since BMP has no
991 support for storing only an aspect ratio, if C<i_aspect_only> is set
992 when you write the C<i_xres> and C<i_yres> values are scaled so the
993 smaller is 72 DPI.
994
995 The following tags are set when you read an image from a BMP file:
996
997 =over
998
999 =item bmp_compression
1000
1001 The type of compression, if any.  This can be any of the following
1002 values:
1003
1004 =for stopwords RLE
1005
1006 =over
1007
1008 =item BI_RGB (0)
1009
1010 Uncompressed.
1011
1012 =item BI_RLE8 (1)
1013
1014 8-bits/pixel paletted value RLE compression.
1015
1016 =item BI_RLE4 (2)
1017
1018 4-bits/pixel paletted value RLE compression.
1019
1020 =item BI_BITFIELDS (3)
1021
1022 Packed RGB values.
1023
1024 =back
1025
1026 =item bmp_compression_name
1027
1028 The bmp_compression value as a BI_* string
1029
1030 =item bmp_important_colors
1031
1032 The number of important colors as defined by the writer of the image.
1033
1034 =item bmp_used_colors
1035
1036 Number of color used from the BMP header
1037
1038 =item bmp_filesize
1039
1040 The file size from the BMP header
1041
1042 =item bmp_bit_count
1043
1044 Number of bits stored per pixel. (24, 8, 4 or 1)
1045
1046 =back
1047
1048 =for stopwords Targa
1049
1050 =head2 TGA (Targa)
1051
1052 When storing Targa images RLE compression can be activated with the
1053 C<compress> parameter, the C<idstring> parameter can be used to set the
1054 Targa comment field and the C<wierdpack> option can be used to use the
1055 15 and 16 bit Targa formats for RGB and RGBA data.  The 15 bit format
1056 has 5 of each red, green and blue.  The 16 bit format in addition
1057 allows 1 bit of alpha.  The most significant bits are used for each
1058 channel.
1059
1060 Tags:
1061
1062 =over
1063
1064 =item tga_idstring
1065
1066 =item tga_bitspp
1067
1068 =item compressed
1069
1070 =back
1071
1072 =head2 RAW
1073
1074 When reading raw images you need to supply the width and height of the
1075 image in the C<xsize> and C<ysize> options:
1076
1077   $img->read(file=>'foo.raw', xsize=>100, ysize=>100)
1078     or die "Cannot read raw image\n";
1079
1080 If your input file has more channels than you want, or (as is common),
1081 junk in the fourth channel, you can use the C<datachannels> and
1082 C<storechannels> options to control the number of channels in your input
1083 file and the resulting channels in your image.  For example, if your
1084 input image uses 32-bits per pixel with red, green, blue and junk
1085 values for each pixel you could do:
1086
1087   $img->read(file=>'foo.raw', xsize=>100, ysize=>100, datachannels=>4,
1088              storechannels=>3)
1089     or die "Cannot read raw image\n";
1090
1091 Read parameters:
1092
1093 =over
1094
1095 =item *
1096
1097 raw_interleave - controls the ordering of samples within the image.
1098 Default: 1.  Alternatively and historically spelled C<interleave>.
1099 Possible values:
1100
1101 =over
1102
1103 =item *
1104
1105 0 - samples are pixel by pixel, so all samples for the first pixel,
1106 then all samples for the second pixel and so on.  eg. for a four pixel
1107 scan line the channels would be laid out as:
1108
1109   012012012012
1110
1111 =item *
1112
1113 1 - samples are line by line, so channel 0 for the entire scan line is
1114 followed by channel 1 for the entire scan line and so on.  eg. for a
1115 four pixel scan line the channels would be laid out as:
1116
1117   000011112222
1118
1119 This is the default.
1120
1121 =back
1122
1123 Unfortunately, historically, the default C<raw_interleave> for read
1124 has been 1, while writing only supports the C<raw_interleave> = 0
1125 format.
1126
1127 For future compatibility, you should always supply the
1128 C<raw_interleave> (or C<interleave>) parameter.  As of 0.68, Imager
1129 will warn if you attempt to read a raw image without a
1130 C<raw_interleave> parameter.
1131
1132 =item *
1133
1134 raw_storechannels - the number of channels to store in the image.
1135 Range: 1 to 4.  Default: 3.  Alternatively and historically spelled
1136 C<storechannels>.
1137
1138 =item *
1139
1140 raw_datachannels - the number of channels to read from the file.
1141 Range: 1 or more.  Default: 3.  Alternatively and historically spelled
1142 C<datachannels>.
1143
1144 =back
1145
1146   $img->read(file=>'foo.raw', xsize=100, ysize=>100, raw_interleave=>1)
1147     or die "Cannot read raw image\n";
1148
1149 =head2 PNG
1150
1151 There are no PNG specific tags.
1152
1153 =head2 ICO (Microsoft Windows Icon) and CUR (Microsoft Windows Cursor)
1154
1155 Icon and Cursor files are very similar, the only differences being a
1156 number in the header and the storage of the cursor hot spot.  I've
1157 treated them separately so that you're not messing with tags to
1158 distinguish between them.
1159
1160 The following tags are set when reading an icon image and are used
1161 when writing it:
1162
1163 =over
1164
1165 =item ico_mask
1166
1167 This is the AND mask of the icon.  When used as an icon in Windows 1
1168 bits in the mask correspond to pixels that are modified by the source
1169 image rather than simply replaced by the source image.
1170
1171 Rather than requiring a binary bitmap this is accepted in a specific format:
1172
1173 =over
1174
1175 =item *
1176
1177 first line consisting of the 0 placeholder, the 1 placeholder and a
1178 newline.
1179
1180 =item *
1181
1182 following lines which contain 0 and 1 placeholders for each scan line
1183 of the image, starting from the top of the image.
1184
1185 =back
1186
1187 When reading an image, '.' is used as the 0 placeholder and '*' as the
1188 1 placeholder.  An example:
1189
1190   .*
1191   ..........................******
1192   ..........................******
1193   ..........................******
1194   ..........................******
1195   ...........................*****
1196   ............................****
1197   ............................****
1198   .............................***
1199   .............................***
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 =back
1225
1226 The following tags are set when reading an icon:
1227
1228 =over
1229
1230 =item ico_bits
1231
1232 The number of bits per pixel used to store the image.
1233
1234 =back
1235
1236 For cursor files the following tags are set and read when reading and
1237 writing:
1238
1239 =over
1240
1241 =item cur_mask
1242
1243 This is the same as the ico_mask above.
1244
1245 =item cur_hotspotx
1246
1247 =item cur_hotspoty
1248
1249 The "hot" spot of the cursor image.  This is the spot on the cursor
1250 that you click with.  If you set these to out of range values they are
1251 clipped to the size of the image when written to the file.
1252
1253 =back
1254
1255 The following parameters can be supplied to read() or read_multi() to
1256 control reading of ICO/CUR files:
1257
1258 =over
1259
1260 =item *
1261
1262 ico_masked - if true, the default, then the icon/cursors mask is
1263 applied as an alpha channel to the image.  This may result in a
1264 paletted image being returned as a direct color image.  Default: 1
1265
1266   # retrieve the image as stored, without using the mask as an alpha
1267   # channel
1268   $img->read(file => 'foo.ico', ico_masked => 0)
1269     or die $img->errstr;
1270
1271 This was introduced in Imager 0.60.  Previously reading ICO images
1272 acted as if C<ico_masked =E<gt> 0>.
1273
1274 =back
1275
1276 C<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 =for stopwords BW
1289
1290 =head2 SGI (RGB, BW)
1291
1292 SGI images, often called by the extensions, RGB or BW, can be stored
1293 either uncompressed or compressed using an RLE compression.
1294
1295 By default, when saving to an extension of C<rgb>, C<bw>, C<sgi>,
1296 C<rgba> the file will be saved in SGI format.  The file extension is
1297 otherwise ignored, so saving a 3-channel image to a C<.bw> file will
1298 result in a 3-channel image on disk.
1299
1300 The following tags are set when reading a SGI image:
1301
1302 =over
1303
1304 =item *
1305
1306 i_comment - the C<IMAGENAME> field from the image.  Also written to
1307 the file when writing.
1308
1309 =item *
1310
1311 sgi_pixmin, sgi_pixmax - the C<PIXMIN> and C<PIXMAX> fields from the
1312 image.  On reading image data is expanded from this range to the full
1313 range of samples in the image.
1314
1315 =item *
1316
1317 sgi_bpc - the number of bytes per sample for the image.  Ignored when
1318 writing.
1319
1320 =item *
1321
1322 sgi_rle - whether or not the image is compressed.  If this is non-zero
1323 when writing the image will be compressed.
1324
1325 =back
1326
1327 =head1 ADDING NEW FORMATS
1328
1329 To support a new format for reading, call the register_reader() class
1330 method:
1331
1332 =over
1333
1334 =item register_reader
1335
1336 Registers single or multiple image read functions.
1337
1338 Parameters:
1339
1340 =over
1341
1342 =item *
1343
1344 type - the identifier of the file format, if Imager's
1345 i_test_format_probe() can identify the format then this value should
1346 match i_test_format_probe()'s result.
1347
1348 This parameter is required.
1349
1350 =item *
1351
1352 single - a code ref to read a single image from a file.  This is
1353 supplied:
1354
1355 =over
1356
1357 =item *
1358
1359 the object that read() was called on,
1360
1361 =item *
1362
1363 an Imager::IO object that should be used to read the file, and
1364
1365 =item *
1366
1367 all the parameters supplied to the read() method.
1368
1369 =back
1370
1371 The single parameter is required.
1372
1373 =item *
1374
1375 multiple - a code ref which is called to read multiple images from a
1376 file. This is supplied:
1377
1378 =over
1379
1380 =item *
1381
1382 an Imager::IO object that should be used to read the file, and
1383
1384 =item *
1385
1386 all the parameters supplied to the read_multi() method.
1387
1388 =back
1389
1390 =back
1391
1392 Example:
1393
1394   # from Imager::File::ICO
1395   Imager->register_reader
1396     (
1397      type=>'ico',
1398      single => 
1399      sub { 
1400        my ($im, $io, %hsh) = @_;
1401        $im->{IMG} = i_readico_single($io, $hsh{page} || 0);
1402
1403        unless ($im->{IMG}) {
1404          $im->_set_error(Imager->_error_as_msg);
1405          return;
1406        }
1407        return $im;
1408      },
1409      multiple =>
1410      sub {
1411        my ($io, %hsh) = @_;
1412      
1413        my @imgs = i_readico_multi($io);
1414        unless (@imgs) {
1415          Imager->_set_error(Imager->_error_as_msg);
1416          return;
1417        }
1418        return map { 
1419          bless { IMG => $_, DEBUG => $Imager::DEBUG, ERRSTR => undef }, 'Imager'
1420        } @imgs;
1421      },
1422     );
1423
1424 =item register_writer
1425
1426 Registers single or multiple image write functions.
1427
1428 Parameters:
1429
1430 =over
1431
1432 =item *
1433
1434 type - the identifier of the file format.  This is typically the
1435 extension in lowercase.
1436
1437 This parameter is required.
1438
1439 =item *
1440
1441 single - a code ref to write a single image to a file.  This is
1442 supplied:
1443
1444 =over
1445
1446 =item *
1447
1448 the object that write() was called on,
1449
1450 =item *
1451
1452 an Imager::IO object that should be used to write the file, and
1453
1454 =item *
1455
1456 all the parameters supplied to the write() method.
1457
1458 =back
1459
1460 The single parameter is required.
1461
1462 =item *
1463
1464 multiple - a code ref which is called to write multiple images to a
1465 file. This is supplied:
1466
1467 =over
1468
1469 =item *
1470
1471 the class name write_multi() was called on, this is typically
1472 C<Imager>.
1473
1474 =item *
1475
1476 an Imager::IO object that should be used to write the file, and
1477
1478 =item *
1479
1480 all the parameters supplied to the read_multi() method.
1481
1482 =back
1483
1484 =back
1485
1486 =back
1487
1488 If you name the reader module C<Imager::File::>I<your-format-name>
1489 where I<your-format-name> is a fully upper case version of the type
1490 value you would pass to read(), read_multi(), write() or write_multi()
1491 then Imager will attempt to load that module if it has no other way to
1492 read or write that format.
1493
1494 For example, if you create a module Imager::File::GIF and the user has
1495 built Imager without it's normal GIF support then an attempt to read a
1496 GIF image will attempt to load Imager::File::GIF.
1497
1498 If your module can only handle reading then you can name your module
1499 C<Imager::File::>I<your-format-name>C<Reader> and Imager will attempt
1500 to autoload it.
1501
1502 If your module can only handle writing then you can name your module 
1503 C<Imager::File::>I<your-format-name>C<Writer> and Imager will attempt
1504 to autoload it.
1505
1506 =head1 EXAMPLES
1507
1508 =head2 Producing an image from a CGI script
1509
1510 Once you have an image the basic mechanism is:
1511
1512 =for stopwords STDOUT
1513
1514 =over
1515
1516 =item 1.
1517
1518 set STDOUT to autoflush
1519
1520 =item 2.
1521
1522 output a content-type header, and optionally a content-length header
1523
1524 =item 3.
1525
1526 put STDOUT into binmode
1527
1528 =item 4.
1529
1530 call write() with the C<fd> or C<fh> parameter.  You will need to
1531 provide the C<type> parameter since Imager can't use the extension to
1532 guess the file format you want.
1533
1534 =back
1535
1536   # write an image from a CGI script
1537   # using CGI.pm
1538   use CGI qw(:standard);
1539   $| = 1;
1540   binmode STDOUT;
1541   print header(-type=>'image/gif');
1542   $img->write(type=>'gif', fd=>fileno(STDOUT))
1543     or die $img->errstr;
1544
1545 If you want to send a content length you can send the output to a
1546 scalar to get the length:
1547
1548   my $data;
1549   $img->write(type=>'gif', data=>\$data)
1550     or die $img->errstr;
1551   binmode STDOUT;
1552   print header(-type=>'image/gif', -content_length=>length($data));
1553   print $data;
1554
1555 =head2 Writing an animated GIF
1556
1557 The basic idea is simple, just use write_multi():
1558
1559   my @imgs = ...;
1560   Imager->write_multi({ file=>$filename, type=>'gif' }, @imgs);
1561
1562 If your images are RGB images the default quantization mechanism will
1563 produce a very good result, but can take a long time to execute.  You
1564 could either use the standard web color map:
1565
1566   Imager->write_multi({ file=>$filename, 
1567                         type=>'gif',
1568                         make_colors=>'webmap' },
1569                       @imgs);
1570
1571 or use a median cut algorithm to built a fairly optimal color map:
1572
1573   Imager->write_multi({ file=>$filename,
1574                         type=>'gif',
1575                         make_colors=>'mediancut' },
1576                       @imgs);
1577
1578 By default all of the images will use the same global color map, which
1579 will produce a smaller image.  If your images have significant color
1580 differences, you may want to generate a new palette for each image:
1581
1582   Imager->write_multi({ file=>$filename,
1583                         type=>'gif',
1584                         make_colors=>'mediancut',
1585                         gif_local_map => 1 },
1586                       @imgs);
1587
1588 which will set the C<gif_local_map> tag in each image to 1.
1589 Alternatively, if you know only some images have different colors, you
1590 can set the tag just for those images:
1591
1592   $imgs[2]->settag(name=>'gif_local_map', value=>1);
1593   $imgs[4]->settag(name=>'gif_local_map', value=>1);
1594
1595 and call write_multi() without a C<gif_local_map> parameter, or supply
1596 an arrayref of values for the tag:
1597
1598   Imager->write_multi({ file=>$filename,
1599                         type=>'gif',
1600                         make_colors=>'mediancut',
1601                         gif_local_map => [ 0, 0, 1, 0, 1 ] },
1602                       @imgs);
1603
1604 Other useful parameters include C<gif_delay> to control the delay
1605 between frames and C<transp> to control transparency.
1606
1607 =head2 Reading tags after reading an image
1608
1609 This is pretty simple:
1610
1611   # print the author of a TIFF, if any
1612   my $img = Imager->new;
1613   $img->read(file=>$filename, type='tiff') or die $img->errstr;
1614   my $author = $img->tags(name=>'tiff_author');
1615   if (defined $author) {
1616     print "Author: $author\n";
1617   }
1618
1619 =head1 BUGS
1620
1621 When saving GIF images the program does NOT try to shave off extra
1622 colors if it is possible.  If you specify 128 colors and there are
1623 only 2 colors used - it will have a 128 color table anyway.
1624
1625 =head1 SEE ALSO
1626
1627 Imager(3)
1628
1629 =cut