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