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