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