- added experimental EXIF decoding when reading JPEG files.
[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 =item write
50
51 and the C<write()> method to write an image:
52
53   $img->write(file=>$filename, type=>$type)
54     or die "Cannot write $filename: ", $img->errstr;
55
56 =item read_multi
57
58 If you're reading from a format that supports multiple images per
59 file, use the C<read_multi()> method:
60
61   my @imgs = Imager->read_multi(file=>$filename, type=>$type)
62     or die "Cannot read $filename: ", Imager->errstr;
63
64 =item write_multi
65
66 and if you want to write multiple images to a single file use the
67 C<write_multi()> method:
68
69   Imager->write_multi({ file=> $filename, type=>$type }, @images)
70     or die "Cannot write $filename: ", Imager->errstr;
71
72 =back
73
74 If the I<filename> includes an extension that Imager recognizes, then
75 you don't need the I<type>, but you may want to provide one anyway.
76 See L</Guessing types> for information on controlling this
77 recognition.
78
79 The C<type> parameter is a lowercase representation of the file type,
80 and can be any of the following:
81
82   bmp   Windows BitMaP (BMP)
83   gif   Graphics Interchange Format (GIF)
84   jpeg  JPEG/JFIF
85   png   Portable Network Graphics (PNG)
86   pnm   Portable aNyMap (PNM)
87   raw   Raw
88   rgb   SGI .rgb files
89   tga   TARGA
90   tiff  Tagged Image File Format (TIFF)
91
92 When you read an image, Imager may set some tags, possibly including
93 information about the spatial resolution, textual information, and
94 animation information.  See L<Imager::ImageTypes/Tags> for specifics.
95
96 The open() method is a historical alias for the read() method.
97
98 =head2 Input and output
99
100 When reading or writing you can specify one of a variety of sources or
101 targets:
102
103 =over
104
105 =item file
106
107 The C<file> parameter is the name of the image file to be written to
108 or read from.  If Imager recognizes the extension of the file you do
109 not need to supply a C<type>.
110
111 =item fh
112
113 C<fh> is a file handle, typically either returned from
114 C<<IO::File->new()>>, or a glob from an C<open> call.  You should call
115 C<binmode> on the handle before passing it to Imager.
116
117 Imager will set the handle to autoflush to make sure any buffered data
118 is flushed , since Imager will write to the file descriptor (from
119 fileno()) rather than writing at the perl level.
120
121 =item fd
122
123 C<fd> is a file descriptor.  You can get this by calling the
124 C<fileno()> function on a file handle, or by using one of the standard
125 file descriptor numbers.
126
127 If you get this from a perl file handle, you may need to flush any
128 buffered output, otherwise it may appear in the output stream after
129 the image.
130
131 =item data
132
133 When reading data, C<data> is a scalar containing the image file data,
134 when writing, C<data> is a reference to the scalar to save the image
135 file data too.  For GIF images you will need giflib 4 or higher, and
136 you may need to patch giflib to use this option for writing.
137
138 =item callback
139
140 Imager will make calls back to your supplied coderefs to read, write
141 and seek from/to/through the image file.
142
143 When reading from a file you can use either C<callback> or C<readcb>
144 to supply the read callback, and when writing C<callback> or
145 C<writecb> to supply the write callback.
146
147 When writing you can also supply the C<maxbuffer> option to set the
148 maximum amount of data that will be buffered before your write
149 callback is called.  Note: the amount of data supplied to your
150 callback can be smaller or larger than this size.
151
152 The read callback is called with 2 parameters, the minimum amount of
153 data required, and the maximum amount that Imager will store in it's C
154 level buffer.  You may want to return the minimum if you have a slow
155 data source, or the maximum if you have a fast source and want to
156 prevent many calls to your perl callback.  The read data should be
157 returned as a scalar.
158
159 Your write callback takes exactly one parameter, a scalar containing
160 the data to be written.  Return true for success.
161
162 The seek callback takes 2 parameters, a I<POSITION>, and a I<WHENCE>,
163 defined in the same way as perl's seek function.
164
165 You can also supply a C<closecb> which is called with no parameters
166 when there is no more data to be written.  This could be used to flush
167 buffered data.
168
169 =back
170
171 =head2 Guessing types
172
173 Imager uses the code reference in $Imager::FORMATGUESS to guess the
174 file type when you don't supply a C<type>.  The code reference is
175 called with a single parameter, the filename of the file.  The code
176 reference is only called if a C<file> parameter is supplied to the
177 file access method.
178
179 Return either a valid Imager file type, or undef.
180
181   # I'm writing jpegs to weird filenames
182   local $Imager::FORMATGUESS = sub { 'jpeg' };
183
184 =head2 Limiting the sizes of images you read
185
186 In some cases you will be receiving images from an untested source,
187 such as submissions via CGI.  To prevent such images from consuming
188 large amounts of memory, you can set limits on the dimensions of
189 images you read from files:
190
191 =over
192
193 =item *
194
195 width - limit the width in pixels of the image
196
197 =item *
198
199 height - limit the height in pixels of the image
200
201 =item *
202
203 bytes - limits the amount of storage used by the image.  This depends
204 on the width, height, channels and sample size of the image.  For
205 paletted images this is calculated as if the image was expanded to a
206 direct color image.
207
208 =back
209
210 To set the limits, call the class method set_file_limits:
211
212   Imager->set_file_limits(width=>$max_width, height=>$max_height);
213
214 You can pass any or all of the limits above, any limits you do not
215 pass are left as they were.
216
217 Any limit of zero is treated as unlimited.
218
219 By default, all of the limits are zero, or unlimited.
220
221 You can reset all of the limited to their defaults by passing in the
222 reset parameter as a true value:
223
224   # no limits
225   Imager->set_file_limits(reset=>1);
226
227 This can be used with the other limits to reset all but the limit you
228 pass:
229
230   # only width is limited
231   Imager->set_file_limits(reset=>1, width=>100);
232
233   # only bytes is limited
234   Imager->set_file_limits(reset=>1, bytes=>10_000_000);
235
236 You can get the current limits with the get_file_limits() method:
237
238   my ($max_width, $max_height, $max_bytes) =
239      Imager->get_file_limits();
240
241
242 =head1 TYPE SPECIFIC INFORMATION
243
244 The different image formats can write different image type, and some have
245 different options to control how the images are written.
246
247 When you call C<write()> or C<write_multi()> with an option that has
248 the same name as a tag for the image format you're writing, then the
249 value supplied to that option will be used to set the corresponding
250 tag in the image.  Depending on the image format, these values will be
251 used when writing the image.
252
253 This replaces the previous options that were used when writing GIF
254 images.  Currently if you use an obsolete option, it will be converted
255 to the equivalent tag and Imager will produced a warning.  You can
256 suppress these warnings by calling the C<Imager::init()> function with
257 the C<warn_obsolete> option set to false:
258
259   Imager::init(warn_obsolete=>0);
260
261 At some point in the future these obsolete options will no longer be
262 supported.
263
264 =head2 PNM (Portable aNy Map)
265
266 Imager can write PGM (Portable Gray Map) and PPM (Portable PixMaps)
267 files, depending on the number of channels in the image.  Currently
268 the images are written in binary formats.  Only 1 and 3 channel images
269 can be written, including 1 and 3 channel paletted images.
270
271   $img->write(file=>'foo.ppm') or die $img->errstr;
272
273 Imager can read both the ASCII and binary versions of each of the PBM
274 (Portable BitMap), PGM and PPM formats.
275
276   $img->read(file=>'foo.ppm') or die $img->errstr;
277
278 PNM does not support the spatial resolution tags.
279
280 =head2 JPEG
281
282 You can supply a C<jpegquality> parameter (0-100) when writing a JPEG
283 file, which defaults to 75%.  Only 1 and 3 channel images
284 can be written, including 1 and 3 channel paletted images.
285
286   $img->write(file=>'foo.jpg', jpegquality=>90) or die $img->errstr;
287
288 Imager will read a grayscale JPEG as a 1 channel image and a color
289 JPEG as a 3 channel image.
290
291   $img->read(file=>'foo.jpg') or die $img->errstr;
292
293 JPEG does not support the spatial resolution tags.
294
295 If an APP1 block containing EXIF information is found, then any of the
296 following tags can be set:
297
298 =over
299
300 exif_aperture exif_artist exif_brightness exif_color_space
301 exif_contrast exif_copyright exif_custom_rendered exif_date_time
302 exif_date_time_digitized exif_date_time_original
303 exif_digital_zoom_ratio exif_exposure_bias exif_exposure_index
304 exif_exposure_mode exif_exposure_program exif_exposure_time
305 exif_f_number exif_flash exif_flash_energy exif_flashpix_version
306 exif_focal_length exif_focal_length_in_35mm_film
307 exif_focal_plane_resolution_unit exif_focal_plane_x_resolution
308 exif_focal_plane_y_resolution exif_gain_control exif_image_description
309 exif_image_unique_id exif_iso_speed_rating exif_make exif_max_aperture
310 exif_metering_mode exif_model exif_orientation exif_related_sound_file
311 exif_resolution_unit exif_saturation exif_scene_capture_type
312 exif_sensing_method exif_sharpness exif_shutter_speed exif_software
313 exif_spectral_sensitivity exif_sub_sec_time
314 exif_sub_sec_time_digitized exif_sub_sec_time_original
315 exif_subject_distance exif_subject_distance_range
316 exif_subject_location exif_tag_light_source exif_user_comment
317 exif_version exif_white_balance exif_x_resolution exif_y_resolution
318
319 =back
320
321 The following derived tags can also be set:
322
323 =over
324
325 exif_color_space_name exif_contrast_name exif_custom_rendered_name
326 exif_exposure_mode_name exif_exposure_program_name exif_flash_name
327 exif_focal_plane_resolution_unit_name exif_gain_control_name
328 exif_light_source_name exif_metering_mode_name
329 exif_resolution_unit_name exif_saturation_name
330 exif_scene_capture_type_name exif_sensing_method_name
331 exif_sharpness_name exif_subject_distance_range_name
332 exif_white_balance_name
333
334 =back
335
336 The derived tags are for enumerated fields, when the value for the
337 base field is valid then the text that appears in the EXIF
338 specification for that value appears in the derived field.  So for
339 example if C<exf_metering_mode> is C<5> then
340 C<exif_metering_mode_name> is set to C<Pattern>.
341
342 =head2 GIF (Graphics Interchange Format)
343
344 When writing one of more GIF images you can use the same
345 L<Quantization Options|Imager::ImageTypes> as you can when converting
346 an RGB image into a paletted image.
347
348 When reading a GIF all of the sub-images are combined using the screen
349 size and image positions into one big image, producing an RGB image.
350 This may change in the future to produce a paletted image where possible.
351
352 When you read a single GIF with C<$img-E<gt>read()> you can supply a
353 reference to a scalar in the C<colors> parameter, if the image is read
354 the scalar will be filled with a reference to an anonymous array of
355 L<Imager::Color> objects, representing the palette of the image.  This
356 will be the first palette found in the image.  If you want the
357 palettes for each of the images in the file, use C<read_multi()> and
358 use the C<getcolors()> method on each image.
359
360 GIF does not support the spatial resolution tags.
361
362 Imager will set the following tags in each image when reading, and can
363 use most of them when writing to GIF:
364
365 =over
366
367 =item gif_left
368
369 the offset of the image from the left of the "screen" ("Image Left
370 Position")
371
372 =item gif_top
373
374 the offset of the image from the top of the "screen" ("Image Top Position")
375
376 =item gif_interlace
377
378 non-zero if the image was interlaced ("Interlace Flag")
379
380 =item gif_screen_width
381
382 =item gif_screen_height
383
384 the size of the logical screen. When writing this is used as the
385 minimum.  If any image being written would extend beyond this the
386 screen size is extended.  ("Logical Screen Width", "Logical Screen
387 Height").
388
389 When writing this is used as a minimum, if the combination of the
390 image size and the image's C<gif_left> and C<gif_top> is beyond this
391 size then the screen size will be expanded.
392
393 =item gif_local_map
394
395 Non-zero if this image had a local color map.  If set for an image
396 when writing the image is quantized separately from the other images
397 in the file.
398
399 =item gif_background
400
401 The index in the global colormap of the logical screen's background
402 color.  This is only set if the current image uses the global
403 colormap.  You can set this on write too, but for it to choose the
404 color you want, you will need to supply only paletted images and set
405 the C<gif_eliminate_unused> tag to 0.
406
407 =item gif_trans_index
408
409 The index of the color in the colormap used for transparency.  If the
410 image has a transparency then it is returned as a 4 channel image with
411 the alpha set to zero in this palette entry.  This value is not used
412 when writing. ("Transparent Color Index")
413
414 =item gif_trans_color
415
416 A reference to an Imager::Color object, which is the colour to use for
417 the palette entry used to represent transparency in the palette.  You
418 need to set the transp option (see L<Quantization options>) for this
419 value to be used.
420
421 =item gif_delay
422
423 The delay until the next frame is displayed, in 1/100 of a second. 
424 ("Delay Time").
425
426 =item gif_user_input
427
428 whether or not a user input is expected before continuing (view dependent) 
429 ("User Input Flag").
430
431 =item gif_disposal
432
433 how the next frame is displayed ("Disposal Method")
434
435 =item gif_loop
436
437 the number of loops from the Netscape Loop extension.  This may be zero.
438
439 =item gif_comment
440
441 the first block of the first gif comment before each image.
442
443 =item gif_eliminate_unused
444
445 If this is true, when you write a paletted image any unused colors
446 will be eliminated from its palette.  This is set by default.
447
448 =back
449
450 Where applicable, the ("name") is the name of that field from the GIF89 
451 standard.
452
453 The following gif writing options are obsolete, you should set the
454 corresponding tag in the image, either by using the tags functions, or
455 by supplying the tag and value as options.
456
457 =over
458
459 =item gif_each_palette
460
461 Each image in the gif file has it's own palette if this is non-zero.
462 All but the first image has a local colour table (the first uses the
463 global colour table.
464
465 Use C<gif_local_map> in new code.
466
467 =item interlace
468
469 The images are written interlaced if this is non-zero.
470
471 Use C<gif_interlace> in new code.
472
473 =item gif_delays
474
475 A reference to an array containing the delays between images, in 1/100
476 seconds.
477
478 Use C<gif_delay> in new code.
479
480 =item gif_positions
481
482 A reference to an array of references to arrays which represent screen
483 positions for each image.
484
485 New code should use the C<gif_left> and C<gif_top> tags.
486
487 =item gif_loop_count
488
489 If this is non-zero the Netscape loop extension block is generated,
490 which makes the animation of the images repeat.
491
492 This is currently unimplemented due to some limitations in giflib.
493
494 =back
495
496 You can supply a C<page> parameter to the C<read()> method to read
497 some page other than the first.  The page is 0 based:
498
499   # read the second image in the file
500   $image->read(file=>"example.gif", page=>1)
501     or die "Cannot read second page: ",$image->errstr,"\n";
502
503 Before release 0.46, Imager would read multi-image GIF image files
504 into a single image, overlaying each of the images onto the virtual
505 GIF screen.
506
507 As of 0.46 the default is to read the first image from the file, as if
508 called with C<< page => 0 >>.
509
510 You can return to the previous behaviour by calling read with the
511 C<gif_consolidate> parameter set to a true value:
512
513   $img->read(file=>$some_gif_file, gif_consolidate=>1);
514
515 =head2 TIFF (Tagged Image File Format)
516
517 Imager can write images to either paletted or RGB TIFF images,
518 depending on the type of the source image.  Currently if you write a
519 16-bit/sample or double/sample image it will be written as an
520 8-bit/sample image.  Only 1 or 3 channel images can be written.
521
522 If you are creating images for faxing you can set the I<class>
523 parameter set to C<fax>.  By default the image is written in fine
524 mode, but this can be overridden by setting the I<fax_fine> parameter
525 to zero.  Since a fax image is bi-level, Imager uses a threshold to
526 decide if a given pixel is black or white, based on a single channel.
527 For greyscale images channel 0 is used, for color images channel 1
528 (green) is used.  If you want more control over the conversion you can
529 use $img->to_paletted() to product a bi-level image.  This way you can
530 use dithering:
531
532   my $bilevel = $img->to_paletted(colors=>[ NC(0,0,0), NC(255,255,255) ],
533                                   make_colors => 'none',
534                                   translate => 'errdiff',
535                                   errdiff => 'stucki');
536
537 =over
538
539 =item class
540
541 If set to 'fax' the image will be written as a bi-level fax image.
542
543 =item fax_fine
544
545 By default when I<class> is set to 'fax' the image is written in fine
546 mode, you can select normal mode by setting I<fax_fine> to 0.
547
548 =back
549
550 Imager should be able to read any TIFF image you supply.  Paletted
551 TIFF images are read as paletted Imager images, since paletted TIFF
552 images have 16-bits/sample (48-bits/color) this means the bottom
553 8-bits are lost, but this shouldn't be a big deal.  Currently all
554 direct color images are read at 8-bits/sample.
555
556 TIFF supports the spatial resolution tags.  See the
557 C<tiff_resolutionunit> tag for some extra options.
558
559 The following tags are set in a TIFF image when read, and can be set
560 to control output:
561
562 =over
563
564 =item tiff_resolutionunit
565
566 The value of the ResolutionUnit tag.  This is ignored on writing if
567 the i_aspect_only tag is non-zero.
568
569 The C<i_xres> and C<i_yres> tags are expressed in pixels per inch no
570 matter tha value of this tag, they will be converted to/from the value
571 stored in the TIFF file.
572
573 =item tiff_resolutionunit_name
574
575 This is set when reading a TIFF file to the name of the unit given by
576 C<tiff_resolutionunit>.  Possible results include C<inch>,
577 C<centimeter>, C<none> (the C<i_aspect_only> tag is also set reading
578 these files) or C<unknown>.
579
580 =item tiff_bitspersample
581
582 Bits per sample from the image.  This value is not used when writing
583 an image, it is only set on a read image.
584
585 =item tiff_photometric
586
587 Value of the PhotometricInterpretation tag from the image.  This value
588 is not used when writing an image, it is only set on a read image.
589
590 =item tiff_documentname
591
592 =item tiff_imagedescription
593
594 =item tiff_make
595
596 =item tiff_model
597
598 =item tiff_pagename
599
600 =item tiff_software
601
602 =item tiff_datetime
603
604 =item tiff_artist
605
606 =item tiff_hostcomputer
607
608 Various strings describing the image.  tiff_datetime must be formatted
609 as "YYYY:MM:DD HH:MM:SS".  These correspond directly to the mixed case
610 names in the TIFF specification.  These are set in images read from a
611 TIFF and saved when writing a TIFF image.
612
613 You can supply a C<page> parameter to the C<read()> method to read
614 some page other than the first.  The page is 0 based:
615
616   # read the second image in the file
617   $image->read(file=>"example.tif", page=>1)
618     or die "Cannot read second page: ",$image->errstr,"\n";
619
620 =back
621
622 =head2 BMP (BitMaP)
623
624 Imager can write 24-bit RGB, and 8, 4 and 1-bit per pixel paletted
625 Windows BMP files.  Currently you cannot write compressed BMP files
626 with Imager.
627
628 Imager can read 24-bit RGB, and 8, 4 and 1-bit perl pixel paletted
629 Windows BMP files.  There is some support for reading 16-bit per pixel
630 images, but I haven't found any for testing.
631
632 BMP has no support for multi-image files.
633
634 BMP files support the spatial resolution tags, but since BMP has no
635 support for storing only an aspect ratio, if C<i_aspect_only> is set
636 when you write the C<i_xres> and C<i_yres> values are scaled so the
637 smaller is 72 DPI.
638
639 The following tags are set when you read an image from a BMP file:
640
641 =over
642
643 =item bmp_compression
644
645 The type of compression, if any.  This can be any of the following
646 values:
647
648 =over
649
650 =item BI_RGB (0)
651
652 Uncompressed.
653
654 =item BI_RLE8 (1)
655
656 8-bits/pixel paletted value RLE compression.
657
658 =item BI_RLE4 (2)
659
660 4-bits/pixel paletted value RLE compression.
661
662 =item BI_BITFIELDS (3)
663
664 Packed RGB values.
665
666 =back
667
668 =item bmp_compression_name
669
670 The bmp_compression value as a BI_* string
671
672 =item bmp_important_colors
673
674 The number of important colors as defined by the writer of the image.
675
676 =item bmp_used_colors
677
678 Number of color used from the BMP header
679
680 =item bmp_filesize
681
682 The file size from the BMP header
683
684 =item bmp_bit_count
685
686 Number of bits stored per pixel. (24, 8, 4 or 1)
687
688 =back
689
690 =head2 TGA (TarGA)
691
692 When storing targa images rle compression can be activated with the
693 'compress' parameter, the 'idstring' parameter can be used to set the
694 targa comment field and the 'wierdpack' option can be used to use the
695 15 and 16 bit targa formats for rgb and rgba data.  The 15 bit format
696 has 5 of each red, green and blue.  The 16 bit format in addition
697 allows 1 bit of alpha.  The most significant bits are used for each
698 channel.
699
700
701 Tags:
702
703 =over
704
705 =item tga_idstring
706
707 =item tga_bitspp
708
709 =item compressed
710
711 =back
712
713 =head2 RAW
714
715 When reading raw images you need to supply the width and height of the
716 image in the xsize and ysize options:
717
718   $img->read(file=>'foo.raw', xsize=>100, ysize=>100)
719     or die "Cannot read raw image\n";
720
721 If your input file has more channels than you want, or (as is common),
722 junk in the fourth channel, you can use the datachannels and
723 storechannels options to control the number of channels in your input
724 file and the resulting channels in your image.  For example, if your
725 input image uses 32-bits per pixel with red, green, blue and junk
726 values for each pixel you could do:
727
728   $img->read(file=>'foo.raw', xsize=>100, ysize=>100, datachannels=>4,
729              storechannels=>3)
730     or die "Cannot read raw image\n";
731
732 Normally the raw image is expected to have the value for channel 1
733 immediately following channel 0 and channel 2 immediately following
734 channel 1 for each pixel.  If your input image has all the channel 0
735 values for the first line of the image, followed by all the channel 1
736 values for the first line and so on, you can use the interleave option:
737
738   $img->read(file=>'foo.raw', xsize=100, ysize=>100, interleave=>1)
739     or die "Cannot read raw image\n";
740
741 =head2 PNG
742
743 There are no PNG specific tags.
744
745 =head1 EXAMPLES
746
747 =head2 Producing an image from a CGI script
748
749 Once you have an image the basic mechanism is:
750
751 =over
752
753 =item 1.
754
755 set STDOUT to autoflush
756
757 =item 2.
758
759 output a content-type header, and optionally a content-length header
760
761 =item 3.
762
763 put STDOUT into binmode
764
765 =item 4.
766
767 call write() with the C<fd> or C<fh> parameter.  You will need to
768 provide the C<type> parameter since Imager can't use the extension to
769 guess the file format you want.
770
771 =back
772
773   # write an image from a CGI script
774   # using CGI.pm
775   use CGI qw(:standard);
776   $| = 1;
777   binmode STDOUT;
778   print header(-type=>'image/gif');
779   $img->write(type=>'gif', fd=>fileno(STDOUT))
780     or die $img->errstr;
781
782 If you want to send a content length you can send the output to a
783 scalar to get the length:
784
785   my $data;
786   $img->write(type=>'gif', data=>\$data)
787     or die $img->errstr;
788   binmode STDOUT;
789   print header(-type=>'image/gif', -content_length=>length($data));
790   print $data;
791
792 =head2 Writing an animated GIF
793
794 The basic idea is simple, just use write_multi():
795
796   my @imgs = ...;
797   Imager->write_multi({ file=>$filename, type=>'gif' }, @imgs);
798
799 If your images are RGB images the default quantization mechanism will
800 produce a very good result, but can take a long time to execute.  You
801 could either use the standard webmap:
802
803   Imager->write_multi({ file=>$filename, 
804                         type=>'gif',
805                         make_colors=>'webmap' },
806                       @imgs);
807
808 or use a median cut algorithm to built a fairly optimal color map:
809
810   Imager->write_multi({ file=>$filename,
811                         type=>'gif',
812                         make_colors=>'mediancut' },
813                       @imgs);
814
815 By default all of the images will use the same global colormap, which
816 will produce a smaller image.  If your images have significant color
817 differences, you may want to generate a new palette for each image:
818
819   Imager->write_multi({ file=>$filename,
820                         type=>'gif',
821                         make_colors=>'mediancut',
822                         gif_local_map => 1 },
823                       @imgs);
824
825 which will set the C<gif_local_map> tag in each image to 1.
826 Alternatively, if you know only some images have different colors, you
827 can set the tag just for those images:
828
829   $imgs[2]->settag(name=>'gif_local_map', value=>1);
830   $imgs[4]->settag(name=>'gif_local_map', value=>1);
831
832 and call write_multi() without a C<gif_local_map> parameter, or supply
833 an arrayref of values for the tag:
834
835   Imager->write_multi({ file=>$filename,
836                         type=>'gif',
837                         make_colors=>'mediancut',
838                         gif_local_map => [ 0, 0, 1, 0, 1 ] },
839                       @imgs);
840
841 Other useful parameters include C<gif_delay> to control the delay
842 between frames and C<transp> to control transparency.
843
844 =head2 Reading tags after reading an image
845
846 This is pretty simple:
847
848   # print the author of a TIFF, if any
849   my $img = Imager->new;
850   $img->read(file=>$filename, type='tiff') or die $img->errstr;
851   my $author = $img->tags(name=>'tiff_author');
852   if (defined $author) {
853     print "Author: $author\n";
854   }
855
856 =head1 BUGS
857
858 When saving Gif images the program does NOT try to shave of extra
859 colors if it is possible.  If you specify 128 colors and there are
860 only 2 colors used - it will have a 128 colortable anyway.
861
862 =head1 SEE ALSO
863
864 Imager(3)
865
866 =cut