Various changes:
[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 zero.
614
615 =item gif_comment
616
617 the first block of the first gif comment before each image.
618
619 =item gif_eliminate_unused
620
621 If this is true, when you write a paletted image any unused colors
622 will be eliminated from its palette.  This is set by default.
623
624 =back
625
626 Where applicable, the ("name") is the name of that field from the GIF89 
627 standard.
628
629 The following gif writing options are obsolete, you should set the
630 corresponding tag in the image, either by using the tags functions, or
631 by supplying the tag and value as options.
632
633 =over
634
635 =item gif_each_palette
636
637 Each image in the gif file has it's own palette if this is non-zero.
638 All but the first image has a local colour table (the first uses the
639 global colour table.
640
641 Use C<gif_local_map> in new code.
642
643 =item interlace
644
645 The images are written interlaced if this is non-zero.
646
647 Use C<gif_interlace> in new code.
648
649 =item gif_delays
650
651 A reference to an array containing the delays between images, in 1/100
652 seconds.
653
654 Use C<gif_delay> in new code.
655
656 =item gif_positions
657
658 A reference to an array of references to arrays which represent screen
659 positions for each image.
660
661 New code should use the C<gif_left> and C<gif_top> tags.
662
663 =item gif_loop_count
664
665 If this is non-zero the Netscape loop extension block is generated,
666 which makes the animation of the images repeat.
667
668 This is currently unimplemented due to some limitations in giflib.
669
670 =back
671
672 You can supply a C<page> parameter to the C<read()> method to read
673 some page other than the first.  The page is 0 based:
674
675   # read the second image in the file
676   $image->read(file=>"example.gif", page=>1)
677     or die "Cannot read second page: ",$image->errstr,"\n";
678
679 Before release 0.46, Imager would read multi-image GIF image files
680 into a single image, overlaying each of the images onto the virtual
681 GIF screen.
682
683 As of 0.46 the default is to read the first image from the file, as if
684 called with C<< page => 0 >>.
685
686 You can return to the previous behaviour by calling read with the
687 C<gif_consolidate> parameter set to a true value:
688
689   $img->read(file=>$some_gif_file, gif_consolidate=>1);
690
691 =head2 TIFF (Tagged Image File Format)
692
693 Imager can write images to either paletted or RGB TIFF images,
694 depending on the type of the source image.  Currently if you write a
695 16-bit/sample or double/sample image it will be written as an
696 8-bit/sample image.  Only 1 or 3 channel images can be written.
697
698 If you are creating images for faxing you can set the I<class>
699 parameter set to C<fax>.  By default the image is written in fine
700 mode, but this can be overridden by setting the I<fax_fine> parameter
701 to zero.  Since a fax image is bi-level, Imager uses a threshold to
702 decide if a given pixel is black or white, based on a single channel.
703 For greyscale images channel 0 is used, for color images channel 1
704 (green) is used.  If you want more control over the conversion you can
705 use $img->to_paletted() to product a bi-level image.  This way you can
706 use dithering:
707
708   my $bilevel = $img->to_paletted(colors=>[ NC(0,0,0), NC(255,255,255) ],
709                                   make_colors => 'none',
710                                   translate => 'errdiff',
711                                   errdiff => 'stucki');
712
713 =over
714
715 =item class
716
717 If set to 'fax' the image will be written as a bi-level fax image.
718
719 =item fax_fine
720
721 By default when I<class> is set to 'fax' the image is written in fine
722 mode, you can select normal mode by setting I<fax_fine> to 0.
723
724 =back
725
726 Imager should be able to read any TIFF image you supply.  Paletted
727 TIFF images are read as paletted Imager images, since paletted TIFF
728 images have 16-bits/sample (48-bits/color) this means the bottom
729 8-bits are lost, but this shouldn't be a big deal.  Currently all
730 direct color images are read at 8-bits/sample.
731
732 TIFF supports the spatial resolution tags.  See the
733 C<tiff_resolutionunit> tag for some extra options.
734
735 The following tags are set in a TIFF image when read, and can be set
736 to control output:
737
738 =over
739
740 =item tiff_resolutionunit
741
742 The value of the ResolutionUnit tag.  This is ignored on writing if
743 the i_aspect_only tag is non-zero.
744
745 The C<i_xres> and C<i_yres> tags are expressed in pixels per inch no
746 matter the value of this tag, they will be converted to/from the value
747 stored in the TIFF file.
748
749 =item tiff_resolutionunit_name
750
751 This is set when reading a TIFF file to the name of the unit given by
752 C<tiff_resolutionunit>.  Possible results include C<inch>,
753 C<centimeter>, C<none> (the C<i_aspect_only> tag is also set reading
754 these files) or C<unknown>.
755
756 =item tiff_bitspersample
757
758 Bits per sample from the image.  This value is not used when writing
759 an image, it is only set on a read image.
760
761 =item tiff_photometric
762
763 Value of the PhotometricInterpretation tag from the image.  This value
764 is not used when writing an image, it is only set on a read image.
765
766 =item tiff_documentname
767
768 =item tiff_imagedescription
769
770 =item tiff_make
771
772 =item tiff_model
773
774 =item tiff_pagename
775
776 =item tiff_software
777
778 =item tiff_datetime
779
780 =item tiff_artist
781
782 =item tiff_hostcomputer
783
784 Various strings describing the image.  tiff_datetime must be formatted
785 as "YYYY:MM:DD HH:MM:SS".  These correspond directly to the mixed case
786 names in the TIFF specification.  These are set in images read from a
787 TIFF and saved when writing a TIFF image.
788
789 =back
790
791 You can supply a C<page> parameter to the C<read()> method to read
792 some page other than the first.  The page is 0 based:
793
794   # read the second image in the file
795   $image->read(file=>"example.tif", page=>1)
796     or die "Cannot read second page: ",$image->errstr,"\n";
797
798 Note: Imager uses the TIFF*RGBA* family of libtiff functions,
799 unfortunately these don't support alpha channels on CMYK images.  This
800 will result in a full coverage alpha channel on CMYK images with an
801 alpha channel, until this is implemented in libtiff (or Imager's TIFF
802 implementation changes.)
803
804 If you read an image with multiple alpha channels, then only the first
805 alpha channel will be read.
806
807 Currently Imager's TIFF support reads all direct color images as 8-bit
808 RGB images, this may change in the future to reading 16-bit/sample
809 images.
810
811 Currently tags that control the output color type and compression are
812 ignored when writing, this may change in the future.  If you have
813 processes that rely upon Imager always producing packbits compressed
814 RGB images, you should strip any tags before writing.
815
816 =head2 BMP (BitMaP)
817
818 Imager can write 24-bit RGB, and 8, 4 and 1-bit per pixel paletted
819 Windows BMP files.  Currently you cannot write compressed BMP files
820 with Imager.
821
822 Imager can read 24-bit RGB, and 8, 4 and 1-bit perl pixel paletted
823 Windows BMP files.  There is some support for reading 16-bit per pixel
824 images, but I haven't found any for testing.
825
826 BMP has no support for multi-image files.
827
828 BMP files support the spatial resolution tags, but since BMP has no
829 support for storing only an aspect ratio, if C<i_aspect_only> is set
830 when you write the C<i_xres> and C<i_yres> values are scaled so the
831 smaller is 72 DPI.
832
833 The following tags are set when you read an image from a BMP file:
834
835 =over
836
837 =item bmp_compression
838
839 The type of compression, if any.  This can be any of the following
840 values:
841
842 =over
843
844 =item BI_RGB (0)
845
846 Uncompressed.
847
848 =item BI_RLE8 (1)
849
850 8-bits/pixel paletted value RLE compression.
851
852 =item BI_RLE4 (2)
853
854 4-bits/pixel paletted value RLE compression.
855
856 =item BI_BITFIELDS (3)
857
858 Packed RGB values.
859
860 =back
861
862 =item bmp_compression_name
863
864 The bmp_compression value as a BI_* string
865
866 =item bmp_important_colors
867
868 The number of important colors as defined by the writer of the image.
869
870 =item bmp_used_colors
871
872 Number of color used from the BMP header
873
874 =item bmp_filesize
875
876 The file size from the BMP header
877
878 =item bmp_bit_count
879
880 Number of bits stored per pixel. (24, 8, 4 or 1)
881
882 =back
883
884 =head2 TGA (TarGA)
885
886 When storing targa images rle compression can be activated with the
887 'compress' parameter, the 'idstring' parameter can be used to set the
888 targa comment field and the 'wierdpack' option can be used to use the
889 15 and 16 bit targa formats for rgb and rgba data.  The 15 bit format
890 has 5 of each red, green and blue.  The 16 bit format in addition
891 allows 1 bit of alpha.  The most significant bits are used for each
892 channel.
893
894
895 Tags:
896
897 =over
898
899 =item tga_idstring
900
901 =item tga_bitspp
902
903 =item compressed
904
905 =back
906
907 =head2 RAW
908
909 When reading raw images you need to supply the width and height of the
910 image in the xsize and ysize options:
911
912   $img->read(file=>'foo.raw', xsize=>100, ysize=>100)
913     or die "Cannot read raw image\n";
914
915 If your input file has more channels than you want, or (as is common),
916 junk in the fourth channel, you can use the datachannels and
917 storechannels options to control the number of channels in your input
918 file and the resulting channels in your image.  For example, if your
919 input image uses 32-bits per pixel with red, green, blue and junk
920 values for each pixel you could do:
921
922   $img->read(file=>'foo.raw', xsize=>100, ysize=>100, datachannels=>4,
923              storechannels=>3)
924     or die "Cannot read raw image\n";
925
926 Normally the raw image is expected to have the value for channel 1
927 immediately following channel 0 and channel 2 immediately following
928 channel 1 for each pixel.  If your input image has all the channel 0
929 values for the first line of the image, followed by all the channel 1
930 values for the first line and so on, you can use the interleave option:
931
932   $img->read(file=>'foo.raw', xsize=100, ysize=>100, interleave=>1)
933     or die "Cannot read raw image\n";
934
935 =head2 PNG
936
937 There are no PNG specific tags.
938
939 =head2 ICO (Microsoft Windows Icon) and CUR (Microsoft Windows Cursor)
940
941 Icon and Cursor files are very similar, the only differences being a
942 number in the header and the storage of the cursor hotspot.  I've
943 treated them separately so that you're not messing with tags to
944 distinguish between them.
945
946 The following tags are set when reading an icon image and are used
947 when writing it:
948
949 =over
950
951 =item ico_mask
952
953 This is the AND mask of the icon.  When used as an icon in Windows 1
954 bits in the mask correspond to pixels that are modified by the source
955 image rather than simply replaced by the source image.
956
957 Rather than requiring a binary bitmap this is accepted in a specific format:
958
959 =over
960
961 =item *
962
963 first line consisting of the 0 placeholder, the 1 placeholder and a
964 newline.
965
966 =item *
967
968 following lines which contain 0 and 1 placeholders for each scanline
969 of the image, starting from the top of the image.
970
971 =back
972
973 When reading an image, '.' is used as the 0 placeholder and '*' as the
974 1 placeholder.  An example:
975
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 =back
1011
1012 The following tags are set when reading an icon:
1013
1014 =over
1015
1016 =item ico_bits
1017
1018 The number of bits per pixel used to store the image.
1019
1020 =back
1021
1022 For cursor files the following tags are set and read when reading and
1023 writing:
1024
1025 =over
1026
1027 =item cur_mask
1028
1029 This is the same as the ico_mask above.
1030
1031 =item cur_hotspotx
1032
1033 =item cur_hotspoty
1034
1035 The "hot" spot of the cursor image.  This is the spot on the cursor
1036 that you click with.  If you set these to out of range values they are
1037 clipped to the size of the image when written to the file.
1038
1039 =back
1040
1041 C<cur_bits> is set when reading a cursor.
1042
1043 Examples:
1044
1045   my $img = Imager->new(xsize => 32, ysize => 32, channels => 4);
1046   $im->box(color => 'FF0000');
1047   $im->write(file => 'box.ico');
1048
1049   $im->settag(name => 'cur_hotspotx', value => 16);
1050   $im->settag(name => 'cur_hotspoty', value => 16);
1051   $im->write(file => 'box.cur');
1052
1053 =head1 ADDING NEW FORMATS
1054
1055 To support a new format for reading, call the register_reader() class
1056 method:
1057
1058 =over
1059
1060 =item register_reader
1061
1062 Registers single or multiple image read functions.
1063
1064 Parameters:
1065
1066 =over
1067
1068 =item *
1069
1070 type - the identifier of the file format, if Imager's
1071 i_test_format_probe() can identify the format then this value should
1072 match i_test_format_probe()'s result.
1073
1074 This parameter is required.
1075
1076 =item *
1077
1078 single - a code ref to read a single image from a file.  This is
1079 supplied:
1080
1081 =over
1082
1083 =item *
1084
1085 the object that read() was called on,
1086
1087 =item *
1088
1089 an Imager::IO object that should be used to read the file, and
1090
1091 =item *
1092
1093 all the parameters supplied to the read() method.
1094
1095 =back
1096
1097 The single parameter is required.
1098
1099 =item *
1100
1101 multiple - a code ref which is called to read multiple images from a
1102 file. This is supplied:
1103
1104 =over
1105
1106 =item *
1107
1108 an Imager::IO object that should be used to read the file, and
1109
1110 =item *
1111
1112 all the parameters supplied to the read_multi() method.
1113
1114 =back
1115
1116 =back
1117
1118 Example:
1119
1120   # from Imager::File::ICO
1121   Imager->register_reader
1122     (
1123      type=>'ico',
1124      single => 
1125      sub { 
1126        my ($im, $io, %hsh) = @_;
1127        $im->{IMG} = i_readico_single($io, $hsh{page} || 0);
1128
1129        unless ($im->{IMG}) {
1130          $im->_set_error(Imager->_error_as_msg);
1131          return;
1132        }
1133        return $im;
1134      },
1135      multiple =>
1136      sub {
1137        my ($io, %hsh) = @_;
1138      
1139        my @imgs = i_readico_multi($io);
1140        unless (@imgs) {
1141          Imager->_set_error(Imager->_error_as_msg);
1142          return;
1143        }
1144        return map { 
1145          bless { IMG => $_, DEBUG => $Imager::DEBUG, ERRSTR => undef }, 'Imager'
1146        } @imgs;
1147      },
1148     );
1149
1150 =item register_writer
1151
1152 Registers single or multiple image write functions.
1153
1154 Parameters:
1155
1156 =over
1157
1158 =item *
1159
1160 type - the identifier of the file format.  This is typically the
1161 extension in lowercase.
1162
1163 This parameter is required.
1164
1165 =item *
1166
1167 single - a code ref to write a single image to a file.  This is
1168 supplied:
1169
1170 =over
1171
1172 =item *
1173
1174 the object that write() was called on,
1175
1176 =item *
1177
1178 an Imager::IO object that should be used to write the file, and
1179
1180 =item *
1181
1182 all the parameters supplied to the write() method.
1183
1184 =back
1185
1186 The single parameter is required.
1187
1188 =item *
1189
1190 multiple - a code ref which is called to write multiple images to a
1191 file. This is supplied:
1192
1193 =over
1194
1195 =item *
1196
1197 the class name write_multi() was called on, this is typically
1198 C<Imager>.
1199
1200 =item *
1201
1202 an Imager::IO object that should be used to write the file, and
1203
1204 =item *
1205
1206 all the parameters supplied to the read_multi() method.
1207
1208 =back
1209
1210 =back
1211
1212 =back
1213
1214 If you name the reader module C<Imager::File::>I<your-format-name>
1215 where I<your-format-name> is a fully upper case version of the type
1216 value you would pass to read(), read_multi(), write() or write_multi()
1217 then Imager will attempt to load that module if it has no other way to
1218 read or write that format.
1219
1220 For example, if you create a module Imager::File::GIF and the user has
1221 built Imager without it's normal GIF support then an attempt to read a
1222 GIF image will attempt to load Imager::File::GIF.
1223
1224 If your module can only handle reading then you can name your module
1225 C<Imager::File::>I<your-format-name>C<Reader> and Imager will attempt
1226 to autoload it.
1227
1228 If your module can only handle writing then you can name your module 
1229 C<Imager::File::>I<your-format-name>C<Writer> and Imager will attempt
1230 to autoload it.
1231
1232 =head1 EXAMPLES
1233
1234 =head2 Producing an image from a CGI script
1235
1236 Once you have an image the basic mechanism is:
1237
1238 =over
1239
1240 =item 1.
1241
1242 set STDOUT to autoflush
1243
1244 =item 2.
1245
1246 output a content-type header, and optionally a content-length header
1247
1248 =item 3.
1249
1250 put STDOUT into binmode
1251
1252 =item 4.
1253
1254 call write() with the C<fd> or C<fh> parameter.  You will need to
1255 provide the C<type> parameter since Imager can't use the extension to
1256 guess the file format you want.
1257
1258 =back
1259
1260   # write an image from a CGI script
1261   # using CGI.pm
1262   use CGI qw(:standard);
1263   $| = 1;
1264   binmode STDOUT;
1265   print header(-type=>'image/gif');
1266   $img->write(type=>'gif', fd=>fileno(STDOUT))
1267     or die $img->errstr;
1268
1269 If you want to send a content length you can send the output to a
1270 scalar to get the length:
1271
1272   my $data;
1273   $img->write(type=>'gif', data=>\$data)
1274     or die $img->errstr;
1275   binmode STDOUT;
1276   print header(-type=>'image/gif', -content_length=>length($data));
1277   print $data;
1278
1279 =head2 Writing an animated GIF
1280
1281 The basic idea is simple, just use write_multi():
1282
1283   my @imgs = ...;
1284   Imager->write_multi({ file=>$filename, type=>'gif' }, @imgs);
1285
1286 If your images are RGB images the default quantization mechanism will
1287 produce a very good result, but can take a long time to execute.  You
1288 could either use the standard webmap:
1289
1290   Imager->write_multi({ file=>$filename, 
1291                         type=>'gif',
1292                         make_colors=>'webmap' },
1293                       @imgs);
1294
1295 or use a median cut algorithm to built a fairly optimal color map:
1296
1297   Imager->write_multi({ file=>$filename,
1298                         type=>'gif',
1299                         make_colors=>'mediancut' },
1300                       @imgs);
1301
1302 By default all of the images will use the same global colormap, which
1303 will produce a smaller image.  If your images have significant color
1304 differences, you may want to generate a new palette for each image:
1305
1306   Imager->write_multi({ file=>$filename,
1307                         type=>'gif',
1308                         make_colors=>'mediancut',
1309                         gif_local_map => 1 },
1310                       @imgs);
1311
1312 which will set the C<gif_local_map> tag in each image to 1.
1313 Alternatively, if you know only some images have different colors, you
1314 can set the tag just for those images:
1315
1316   $imgs[2]->settag(name=>'gif_local_map', value=>1);
1317   $imgs[4]->settag(name=>'gif_local_map', value=>1);
1318
1319 and call write_multi() without a C<gif_local_map> parameter, or supply
1320 an arrayref of values for the tag:
1321
1322   Imager->write_multi({ file=>$filename,
1323                         type=>'gif',
1324                         make_colors=>'mediancut',
1325                         gif_local_map => [ 0, 0, 1, 0, 1 ] },
1326                       @imgs);
1327
1328 Other useful parameters include C<gif_delay> to control the delay
1329 between frames and C<transp> to control transparency.
1330
1331 =head2 Reading tags after reading an image
1332
1333 This is pretty simple:
1334
1335   # print the author of a TIFF, if any
1336   my $img = Imager->new;
1337   $img->read(file=>$filename, type='tiff') or die $img->errstr;
1338   my $author = $img->tags(name=>'tiff_author');
1339   if (defined $author) {
1340     print "Author: $author\n";
1341   }
1342
1343 =head1 BUGS
1344
1345 When saving Gif images the program does NOT try to shave of extra
1346 colors if it is possible.  If you specify 128 colors and there are
1347 only 2 colors used - it will have a 128 colortable anyway.
1348
1349 =head1 SEE ALSO
1350
1351 Imager(3)
1352
1353 =cut