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