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