(rt #127575) link to Imager::Install from Imager::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
9e003c1a 7 use Imager;
c2188f93
TC
8 my $img = ...;
9 $img->write(file=>$filename, type=>$type)
10 or die "Cannot write: ",$img->errstr;
11
24a462db
TC
12 # type is optional if we can guess the format from the filename
13 $img->write(file => "foo.png")
14 or die "Cannot write: ",$img->errstr;
15
c2188f93
TC
16 $img = Imager->new;
17 $img->read(file=>$filename, type=>$type)
18 or die "Cannot read: ", $img->errstr;
19
24a462db
TC
20 # type is optional if we can guess the type from the file data
21 # and we normally can guess
22 $img->read(file => $filename)
23 or die "Cannot read: ", $img->errstr;
24
c2188f93
TC
25 Imager->write_multi({ file=> $filename, ... }, @images)
26 or die "Cannot write: ", Imager->errstr;
27
28 my @imgs = Imager->read_multi(file=>$filename)
29 or die "Cannot read: ", Imager->errstr;
30
77157728
TC
31 Imager->set_file_limits(width=>$max_width, height=>$max_height)
32
f245645a
TC
33 my @read_types = Imager->read_types;
34 my @write_types = Imager->write_types;
35
24a462db
TC
36 # we can write/write_multi to things other than filenames
37 my $data;
38 $img->write(data => \$data, type => $type) or die;
39
40 my $fh = ... ; # eg. IO::File
41 $img->write(fh => $fh, type => $type) or die;
42
43 $img->write(fd => fileno($fh), type => $type) or die;
44
45 # some file types need seek callbacks too
46 $img->write(callback => \&write_callback, type => $type) or die;
47
48 # and similarly for read/read_multi
49 $img->read(data => $data) or die;
50 $img->read(fh => $fh) or die;
51 $img->read(fd => fileno($fh)) or die;
52 $img->read(callback => \&read_callback) or die;
53
2f2a6e54
TC
54 use Imager 0.68;
55 my $img = Imager->new(file => $filename)
56 or die Imager->errstr;
57
c2188f93
TC
58=head1 DESCRIPTION
59
60You can read and write a variety of images formats, assuming you have
e9304dfd
TC
61the L<appropriate libraries|Imager::Install/EXTERNAL LIBRARIES>, and
62images can be read or written to/from files, file handles, file
63descriptors, scalars, or through callbacks.
c2188f93
TC
64
65To see which image formats Imager is compiled to support the following
66code snippet is sufficient:
67
68 use Imager;
69 print join " ", keys %Imager::formats;
70
71This will include some other information identifying libraries rather
67d441b2
TC
72than file formats. For new code you might find the L</read_types()>
73or L</write_types()> methods useful.
c2188f93 74
f7450478
TC
75=over
76
6d5c85a2 77=item read()
f7450478 78
c2188f93
TC
79Reading writing to and from files is simple, use the C<read()>
80method to read an image:
81
82 my $img = Imager->new;
83 $img->read(file=>$filename, type=>$type)
84 or die "Cannot read $filename: ", $img->errstr;
85
6e85a9ac 86In most cases Imager can auto-detect the file type, so you can just
5715f7c3 87supply the file name:
6e85a9ac
TC
88
89 $img->read(file => $filename)
90 or die "Cannot read $filename: ", $img->errstr;
91
6d5c85a2
TC
92The read() method accepts the C<allow_incomplete> parameter. If this
93is non-zero then read() can return true on an incomplete image and set
9c106321
TC
94the C<i_incomplete> tag.
95
2f2a6e54
TC
96From Imager 0.68 you can supply most read() parameters to the new()
97method to read the image file on creation. If the read fails, check
98Imager->errstr() for the cause:
99
100 use Imager 0.68;
101 my $img = Imager->new(file => $filename)
102 or die "Cannot read $filename: ", Imager->errstr;
103
6d5c85a2 104=item write()
f7450478 105
c2188f93
TC
106and the C<write()> method to write an image:
107
108 $img->write(file=>$filename, type=>$type)
109 or die "Cannot write $filename: ", $img->errstr;
110
6d5c85a2 111=item read_multi()
f7450478 112
c2188f93
TC
113If you're reading from a format that supports multiple images per
114file, use the C<read_multi()> method:
115
116 my @imgs = Imager->read_multi(file=>$filename, type=>$type)
117 or die "Cannot read $filename: ", Imager->errstr;
118
6e85a9ac
TC
119As with the read() method, Imager will normally detect the C<type>
120automatically.
121
6d5c85a2 122=item write_multi()
f7450478 123
c2188f93
TC
124and if you want to write multiple images to a single file use the
125C<write_multi()> method:
126
127 Imager->write_multi({ file=> $filename, type=>$type }, @images)
128 or die "Cannot write $filename: ", Imager->errstr;
129
67d441b2 130=item read_types()
f245645a
TC
131
132This is a class method that returns a list of the image file types
133that Imager can read.
134
135 my @types = Imager->read_types;
136
137These types are the possible values for the C<type> parameter, not
138necessarily the extension of the files you're reading.
139
140It is possible for extra file read handlers to be loaded when
141attempting to read a file, which may modify the list of available read
142types.
143
67d441b2 144=item write_types()
f245645a
TC
145
146This is a class method that returns a list of the image file types
147that Imager can write.
148
149 my @types = Imager->write_types;
150
151Note that these are the possible values for the C<type> parameter, not
152necessarily the extension of the files you're writing.
153
154It is possible for extra file write handlers to be loaded when
155attempting to write a file, which may modify the list of available
156write types.
157
f7450478
TC
158=back
159
5715f7c3
TC
160When writing, if the C<filename> includes an extension that Imager
161recognizes, then you don't need the C<type>, but you may want to
6e85a9ac
TC
162provide one anyway. See L</Guessing types> for information on
163controlling this recognition.
c2188f93 164
f6af7cb4
TC
165The C<type> parameter is a lowercase representation of the file type,
166and can be any of the following:
167
168 bmp Windows BitMaP (BMP)
169 gif Graphics Interchange Format (GIF)
170 jpeg JPEG/JFIF
171 png Portable Network Graphics (PNG)
172 pnm Portable aNyMap (PNM)
173 raw Raw
f3dcbf8a 174 sgi SGI .rgb files
f6af7cb4
TC
175 tga TARGA
176 tiff Tagged Image File Format (TIFF)
177
c2188f93
TC
178When you read an image, Imager may set some tags, possibly including
179information about the spatial resolution, textual information, and
9d1c4956 180animation information. See L<Imager::ImageTypes/Tags> for specifics.
c2188f93 181
e36d02ad
TC
182The open() method is a historical alias for the read() method.
183
c2188f93
TC
184=head2 Input and output
185
186When reading or writing you can specify one of a variety of sources or
187targets:
188
189=over
190
6e85a9ac 191=item *
c2188f93 192
5715f7c3 193C<file> - The C<file> parameter is the name of the image file to be
6e85a9ac
TC
194written to or read from. If Imager recognizes the extension of the
195file you do not need to supply a C<type>.
c2188f93 196
1f106142
TC
197 # write in tiff format
198 $image->write(file => "example.tif")
199 or die $image->errstr;
200
201 $image->write(file => 'foo.tmp', type => 'tiff')
202 or die $image->errstr;
203
204 my $image = Imager->new;
205 $image->read(file => 'example.tif')
206 or die $image->errstr;
207
4b387370 208=item *
c2188f93 209
5715f7c3 210C<fh> - C<fh> is a file handle, typically either returned from
c2188f93
TC
211C<<IO::File->new()>>, or a glob from an C<open> call. You should call
212C<binmode> on the handle before passing it to Imager.
213
9d1c4956
TC
214Imager will set the handle to autoflush to make sure any buffered data
215is flushed , since Imager will write to the file descriptor (from
216fileno()) rather than writing at the perl level.
217
1f106142
TC
218 $image->write(fh => \*STDOUT, type => 'gif')
219 or die $image->errstr;
220
221 # for example, a file uploaded via CGI.pm
222 $image->read(fd => $cgi->param('file'))
223 or die $image->errstr;
224
4b387370 225=item *
c2188f93 226
5715f7c3 227C<fd> - C<fd> is a file descriptor. You can get this by calling the
c2188f93
TC
228C<fileno()> function on a file handle, or by using one of the standard
229file descriptor numbers.
230
9d1c4956
TC
231If you get this from a perl file handle, you may need to flush any
232buffered output, otherwise it may appear in the output stream after
233the image.
234
1f106142
TC
235 $image->write(fd => file(STDOUT), type => 'gif')
236 or die $image->errstr;
237
4b387370 238=item *
c2188f93 239
5715f7c3 240C<data> - When reading data, C<data> is a scalar containing the image
83e58721
TC
241file data, or a reference to such a scalar. When writing, C<data> is
242a reference to the scalar to save the image file data to.
c2188f93 243
1f106142
TC
244 my $data;
245 $image->write(data => \$data, type => 'tiff')
246 or die $image->errstr;
247
248 my $data = $row->{someblob}; # eg. from a database
b81163cc
TC
249 my @images = Imager->read_multi(data => $data)
250 or die Imager->errstr;
83e58721
TC
251
252 # from Imager 0.99
253 my @images = Imager->read_multi(data => \$data)
254 or die Imager->errstr;
1f106142 255
1f4f4966 256=item *
c2188f93 257
6d5c85a2
TC
258C<callback>, C<readcb>, C<writecb>, C<seekcb>, C<closecb> - Imager
259will make calls back to your supplied coderefs to read, write and seek
260from/to/through the image file. See L</"I/O Callbacks"> below for details.
c2188f93 261
6d5c85a2 262=item *
c2188f93 263
6d5c85a2 264C<io> - an L<Imager::IO> object.
c2188f93 265
6d5c85a2 266=back
c2188f93 267
6d5c85a2
TC
268X<buffering>X<unbuffered>By default Imager will use buffered I/O when
269reading or writing an image. You can disabled buffering for output by
270supplying a C<< buffered => 0 >> parameter to C<write()> or
271C<write_multi()>.
c2188f93 272
6d5c85a2 273=head2 I/O Callbacks
c2188f93 274
6d5c85a2
TC
275When reading from a file you can use either C<callback> or C<readcb>
276to supply the read callback, and when writing C<callback> or
277C<writecb> to supply the write callback.
278
9d5ff8a6
TC
279Whether reading or writing a C<TIFF> image, C<seekcb> and C<readcb>
280are required.
281
282If a file handler attempts to use C<readcb>, C<writecb> or C<seekcb>
283and you haven't supplied one, the call will fail, failing the image
284read or write, returning an error message indicating that the callback
285is missing:
286
287 # attempting to read a TIFF image without a seekcb
288 open my $fh, "<", $filename or die;
289 my $rcb = sub {
290 my $val;
291 read($fh, $val, $_[0]) or return "";
292 return $val;
293 };
294 my $im = Imager->new(callback => $rcb)
295 or die Imager->errstr
296 # dies with (wrapped here):
297 # Error opening file: (Iolayer): Failed to read directory at offset 0:
298 # (Iolayer): Seek error accessing TIFF directory: seek callback called
299 # but no seekcb supplied
6d5c85a2
TC
300
301You can also provide a C<closecb> parameter called when writing the
9d5ff8a6
TC
302file is complete. If no C<closecb> is supplied the default will
303succeed silently.
c2188f93 304
1f106142
TC
305 # contrived
306 my $data;
307 sub mywrite {
308 $data .= unpack("H*", shift);
309 1;
310 }
b81163cc
TC
311 Imager->write_multi({ callback => \&mywrite, type => 'gif'}, @images)
312 or die Imager->errstr;
1f106142 313
6d5c85a2
TC
314=head3 C<readcb>
315
316The read callback is called with 2 parameters:
317
318=over
319
320=item *
321
322C<size> - the minimum amount of data required.
323
324=item *
325
326C<maxsize> - previously this was the maximum amount of data returnable
327- currently it's always the same as C<size>
1f106142 328
c2188f93
TC
329=back
330
6d5c85a2
TC
331Your read callback should return the data as a scalar:
332
333=over
334
335=item *
336
337on success, a string containing the bytes read.
338
339=item *
340
341on end of file, an empty string
342
343=item *
344
345on error, C<undef>.
346
347=back
348
349If your return value contains more data than C<size> Imager will
350panic.
351
352Your return value must not contain any characters over C<\xFF> or
353Imager will panic.
354
355=head3 C<writecb>
356
357Your write callback takes exactly one parameter, a scalar containing
358the data to be written.
359
360Return true for success.
361
362=head3 C<seekcb>
363
364The seek callback takes 2 parameters, a I<POSITION>, and a I<WHENCE>,
365defined in the same way as perl's seek function.
366
367Previously you always needed a C<seekcb> callback if you called
368Imager's L</read()> or L</read_multi()> without a C<type> parameter,
369but this is no longer necessary unless the file handler requires
370seeking, such as for TIFF files.
371
372Returns the new position in the file, or -1 on failure.
373
374=head3 C<closecb>
375
376You can also supply a C<closecb> which is called with no parameters
377when there is no more data to be written. This could be used to flush
378buffered data.
379
380Return true on success.
381
c2188f93 382=head2 Guessing types
6d5c85a2 383X<FORMATGUESS>
c2188f93 384
9e00434a 385When writing to a file, if you don't supply a C<type> parameter Imager
5715f7c3 386will attempt to guess it from the file name. This is done by calling
9e00434a 387the code reference stored in C<$Imager::FORMATGUESS>. This is only
4f21e06e
TC
388done when write() or write_multi() is called with a C<file> parameter,
389or if read() or read_multi() can't determine the type from the file's
390header.
c2188f93 391
d5556805
TC
392The default function value of C<$Imager::FORMATGUESS> is
393C<\&Imager::def_guess_type>.
394
395=over
396
67d441b2 397=item def_guess_type()
6d5c85a2 398X<methods, def_guess_type()>
d5556805
TC
399
400This is the default function Imager uses to derive a file type from a
401file name. This is a function, not a method.
402
5715f7c3 403Accepts a single parameter, the file name and returns the type or
d5556805
TC
404undef.
405
406=back
9e00434a
TC
407
408You can replace function with your own implementation if you have some
409specialized need. The function takes a single parameter, the name of
410the file, and should return either a file type or under.
c2188f93
TC
411
412 # I'm writing jpegs to weird filenames
413 local $Imager::FORMATGUESS = sub { 'jpeg' };
414
9e00434a
TC
415When reading a file Imager examines beginning of the file for
416identifying information. The current implementation attempts to
417detect the following image types beyond those supported by Imager:
418
5715f7c3
TC
419=for stopwords Photoshop
420
9e00434a
TC
421=over
422
5715f7c3
TC
423C<xpm>, C<mng>, C<jng>, C<ilbm>, C<pcx>, C<fits>, C<psd> (Photoshop), C<eps>, Utah
424C<RLE>.
9e00434a
TC
425
426=back
427
77157728
TC
428=head2 Limiting the sizes of images you read
429
58a9ba58
TC
430=over
431
8d14daab 432=item set_file_limits()
58a9ba58 433
77157728
TC
434In some cases you will be receiving images from an untested source,
435such as submissions via CGI. To prevent such images from consuming
436large amounts of memory, you can set limits on the dimensions of
437images you read from files:
438
439=over
440
441=item *
442
443width - limit the width in pixels of the image
444
445=item *
446
447height - limit the height in pixels of the image
448
449=item *
450
451bytes - limits the amount of storage used by the image. This depends
452on the width, height, channels and sample size of the image. For
453paletted images this is calculated as if the image was expanded to a
454direct color image.
455
456=back
457
458To set the limits, call the class method set_file_limits:
459
460 Imager->set_file_limits(width=>$max_width, height=>$max_height);
461
462You can pass any or all of the limits above, any limits you do not
463pass are left as they were.
464
85cae6e7
TC
465Any limit of zero for width or height is treated as unlimited.
466
467A limit of zero for bytes is treated as one gigabyte, but higher bytes
468limits can be set explicitly.
77157728 469
8d14daab
TC
470By default, the width and height limits are zero, or unlimited. The
471default memory size limit is one gigabyte.
77157728 472
85cae6e7 473You can reset all limits to their defaults with the reset parameter:
77157728
TC
474
475 # no limits
476 Imager->set_file_limits(reset=>1);
477
478This can be used with the other limits to reset all but the limit you
479pass:
480
481 # only width is limited
482 Imager->set_file_limits(reset=>1, width=>100);
483
484 # only bytes is limited
485 Imager->set_file_limits(reset=>1, bytes=>10_000_000);
486
8d14daab 487=item get_file_limits()
58a9ba58 488
77157728
TC
489You can get the current limits with the get_file_limits() method:
490
491 my ($max_width, $max_height, $max_bytes) =
492 Imager->get_file_limits();
493
e1558ffe
TC
494=item check_file_limits()
495X<class methods, check_file_limits()>X<check_file_limits()>
496
497Intended for use by file handlers to check that the size of a file is
498within the limits set by C<set_file_limits()>.
499
500Parameters:
501
502=over
503
504=item *
505
506C<width>, C<height> - the width and height of the image in pixels.
507Must be a positive integer. Required.
508
509=item *
510
511C<channels> - the number of channels in the image, including the alpha
512channel if any. Must be a positive integer between 1 and 4
513inclusive. Default: 3.
514
515=item *
516
517C<sample_size> - the number of bytes stored per sample. Must be a
518positive integer or C<"float">. Note that this should be the sample
519size of the Imager image you will be creating, not the sample size in
520the source, eg. if the source has 32-bit samples this should be
521C<"float"> since Imager doesn't have 32-bit/sample images.
522
523=back
524
58a9ba58 525=back
77157728 526
c2188f93
TC
527=head1 TYPE SPECIFIC INFORMATION
528
529The different image formats can write different image type, and some have
530different options to control how the images are written.
531
97c4effc
TC
532When you call C<write()> or C<write_multi()> with an option that has
533the same name as a tag for the image format you're writing, then the
534value supplied to that option will be used to set the corresponding
535tag in the image. Depending on the image format, these values will be
536used when writing the image.
537
538This replaces the previous options that were used when writing GIF
539images. Currently if you use an obsolete option, it will be converted
540to the equivalent tag and Imager will produced a warning. You can
541suppress these warnings by calling the C<Imager::init()> function with
542the C<warn_obsolete> option set to false:
543
544 Imager::init(warn_obsolete=>0);
545
546At some point in the future these obsolete options will no longer be
547supported.
548
5715f7c3
TC
549=for stopwords aNy PixMaps BitMap
550
c2188f93
TC
551=head2 PNM (Portable aNy Map)
552
5715f7c3
TC
553Imager can write C<PGM> (Portable Gray Map) and C<PPM> (Portable
554PixMaps) files, depending on the number of channels in the image.
555Currently the images are written in binary formats. Only 1 and 3
556channel images can be written, including 1 and 3 channel paletted
557images.
c2188f93
TC
558
559 $img->write(file=>'foo.ppm') or die $img->errstr;
560
5715f7c3
TC
561Imager can read both the ASCII and binary versions of each of the
562C<PBM> (Portable BitMap), C<PGM> and C<PPM> formats.
c2188f93
TC
563
564 $img->read(file=>'foo.ppm') or die $img->errstr;
565
566PNM does not support the spatial resolution tags.
567
9c106321
TC
568The following tags are set when reading a PNM file:
569
570=over
571
572=item *
573
5715f7c3
TC
574X<pnm_maxval>C<pnm_maxval> - the C<maxvals> number from the PGM/PPM header.
575Always set to 2 for a C<PBM> file.
9c106321
TC
576
577=item *
578
5715f7c3
TC
579X<pnm_type>C<pnm_type> - the type number from the C<PNM> header, 1 for ASCII
580C<PBM> files, 2 for ASCII C<PGM> files, 3 for ASCII c<PPM> files, 4 for binary
581C<PBM> files, 5 for binary C<PGM> files, 6 for binary C<PPM> files.
9c106321
TC
582
583=back
584
585The following tag is checked when writing an image with more than
5868-bits/sample:
587
588=over
589
590=item *
591
592X<pnm_write_wide_data>pnm_write_wide_data - if this is non-zero then
5715f7c3 593write() can write C<PGM>/C<PPM> files with 16-bits/sample. Some
9c106321
TC
594applications, for example GIMP 2.2, and tools can only read
5958-bit/sample binary PNM files, so Imager will only write a 16-bit
596image when this tag is non-zero.
597
598=back
599
c2188f93
TC
600=head2 JPEG
601
9619c400
TC
602You can supply a C<jpegquality> parameter ranging from 0 (worst
603quality) to 100 (best quality) when writing a JPEG file, which
604defaults to 75.
c2188f93
TC
605
606 $img->write(file=>'foo.jpg', jpegquality=>90) or die $img->errstr;
607
9619c400
TC
608If you write an image with an alpha channel to a JPEG file then it
609will be composed against the background set by the C<i_background>
610parameter (or tag), or black if not supplied.
611
5715f7c3 612Imager will read a gray scale JPEG as a 1 channel image and a color
c2188f93
TC
613JPEG as a 3 channel image.
614
615 $img->read(file=>'foo.jpg') or die $img->errstr;
616
6d54291b
TC
617The following tags are set in a JPEG image when read, and can be set
618to control output:
619
620=over
621
92e9df65 622=item *
6d54291b 623
92e9df65
TC
624C<jpeg_density_unit> - The value of the density unit field in the
625C<JFIF> header. This is ignored on writing if the C<i_aspect_only>
626tag is non-zero.
6d54291b
TC
627
628The C<i_xres> and C<i_yres> tags are expressed in pixels per inch no
629matter the value of this tag, they will be converted to/from the value
630stored in the JPEG file.
631
92e9df65
TC
632=item *
633
634C<jpeg_density_unit_name> - This is set when reading a JPEG file to
635the name of the unit given by C<jpeg_density_unit>. Possible results
636include C<inch>, C<centimeter>, C<none> (the C<i_aspect_only> tag is
637also set reading these files). If the value of C<jpeg_density_unit>
638is unknown then this tag isn't set.
6d54291b 639
92e9df65
TC
640=item *
641
642C<jpeg_comment> - Text comment.
6d54291b 643
92e9df65 644=item *
6d54291b 645
92e9df65
TC
646C<jpeg_progressive> - Whether the JPEG file is a progressive
647file. (Imager 0.84)
6d54291b
TC
648
649=back
650
651JPEG supports the spatial resolution tags C<i_xres>, C<i_yres> and
652C<i_aspect_only>.
f7450478 653
f9152a93
TC
654You can also set the following tags when writing to an image, they are
655not set in the image when reading:
656
657=over
658
659C<jpeg_optimize> - set to a non-zero integer to compute optimal
660Huffman coding tables for the image. This will increase memory usage
661and processing time (about 12% in my simple tests) but can
662significantly reduce file size without a loss of quality.
663
664=back
665
5715f7c3
TC
666=for stopwords EXIF
667
668If an C<APP1> block containing EXIF information is found, then any of the
c560d7a9 669following tags can be set when reading a JPEG image:
f7450478
TC
670
671=over
672
673exif_aperture exif_artist exif_brightness exif_color_space
674exif_contrast exif_copyright exif_custom_rendered exif_date_time
675exif_date_time_digitized exif_date_time_original
676exif_digital_zoom_ratio exif_exposure_bias exif_exposure_index
677exif_exposure_mode exif_exposure_program exif_exposure_time
678exif_f_number exif_flash exif_flash_energy exif_flashpix_version
679exif_focal_length exif_focal_length_in_35mm_film
680exif_focal_plane_resolution_unit exif_focal_plane_x_resolution
681exif_focal_plane_y_resolution exif_gain_control exif_image_description
682exif_image_unique_id exif_iso_speed_rating exif_make exif_max_aperture
683exif_metering_mode exif_model exif_orientation exif_related_sound_file
684exif_resolution_unit exif_saturation exif_scene_capture_type
685exif_sensing_method exif_sharpness exif_shutter_speed exif_software
686exif_spectral_sensitivity exif_sub_sec_time
687exif_sub_sec_time_digitized exif_sub_sec_time_original
688exif_subject_distance exif_subject_distance_range
689exif_subject_location exif_tag_light_source exif_user_comment
690exif_version exif_white_balance exif_x_resolution exif_y_resolution
691
692=back
693
c560d7a9 694The following derived tags can also be set when reading a JPEG image:
f7450478
TC
695
696=over
697
698exif_color_space_name exif_contrast_name exif_custom_rendered_name
699exif_exposure_mode_name exif_exposure_program_name exif_flash_name
700exif_focal_plane_resolution_unit_name exif_gain_control_name
701exif_light_source_name exif_metering_mode_name
702exif_resolution_unit_name exif_saturation_name
703exif_scene_capture_type_name exif_sensing_method_name
704exif_sharpness_name exif_subject_distance_range_name
705exif_white_balance_name
706
707=back
708
709The derived tags are for enumerated fields, when the value for the
710base field is valid then the text that appears in the EXIF
711specification for that value appears in the derived field. So for
712example if C<exf_metering_mode> is C<5> then
713C<exif_metering_mode_name> is set to C<Pattern>.
c2188f93 714
cb00d347
TC
715eg.
716
717 my $image = Imager->new;
718 $image->read(file => 'exiftest.jpg')
719 or die "Cannot load image: ", $image->errstr;
720 print $image->tags(name => "exif_image_description"), "\n";
721 print $image->tags(name => "exif_exposure_mode"), "\n";
722 print $image->tags(name => "exif_exposure_mode_name"), "\n";
723
724 # for the exiftest.jpg in the Imager distribution the output would be:
725 Imager Development Notes
726 0
727 Auto exposure
728
c560d7a9
TC
729Imager will not write EXIF tags to any type of image, if you need more
730advanced EXIF handling, consider L<Image::ExifTool>.
731
5715f7c3
TC
732=for stopwords IPTC
733
f0fe9c14
TC
734=over
735
5715f7c3 736=item parseiptc()
f0fe9c14
TC
737
738Historically, Imager saves IPTC data when reading a JPEG image, the
739parseiptc() method returns a list of key/value pairs resulting from a
740simple decoding of that data.
741
742Any future IPTC data decoding is likely to go into tags.
743
744=back
745
67d441b2 746=head2 GIF
c2188f93 747
97c4effc
TC
748When writing one of more GIF images you can use the same
749L<Quantization Options|Imager::ImageTypes> as you can when converting
750an RGB image into a paletted image.
61c59c54 751
00424555
TC
752When reading a GIF all of the sub-images are combined using the screen
753size and image positions into one big image, producing an RGB image.
754This may change in the future to produce a paletted image where possible.
755
8889dffd 756When you read a single GIF with C<$img-E<gt>read()> you can supply a
00424555
TC
757reference to a scalar in the C<colors> parameter, if the image is read
758the scalar will be filled with a reference to an anonymous array of
759L<Imager::Color> objects, representing the palette of the image. This
760will be the first palette found in the image. If you want the
761palettes for each of the images in the file, use C<read_multi()> and
762use the C<getcolors()> method on each image.
763
764GIF does not support the spatial resolution tags.
765
97c4effc
TC
766Imager will set the following tags in each image when reading, and can
767use most of them when writing to GIF:
00424555
TC
768
769=over
770
b0618399 771=item *
00424555 772
b0618399
TC
773gif_left - the offset of the image from the left of the "screen"
774("Image Left Position")
00424555 775
b0618399 776=item *
00424555 777
b0618399
TC
778gif_top - the offset of the image from the top of the "screen" ("Image
779Top Position")
00424555 780
b0618399 781=item *
00424555 782
b0618399
TC
783gif_interlace - non-zero if the image was interlaced ("Interlace
784Flag")
00424555 785
b0618399 786=item *
00424555 787
b0618399
TC
788gif_screen_width, gif_screen_height - the size of the logical
789screen. When writing this is used as the minimum. If any image being
790written would extend beyond this then the screen size is extended.
791("Logical Screen Width", "Logical Screen Height").
00424555 792
b0618399 793=item *
97c4effc 794
b0618399
TC
795gif_local_map - Non-zero if this image had a local color map. If set
796for an image when writing the image is quantized separately from the
797other images in the file.
00424555 798
b0618399 799=item *
00424555 800
5715f7c3 801gif_background - The index in the global color map of the logical
b0618399 802screen's background color. This is only set if the current image uses
5715f7c3 803the global color map. You can set this on write too, but for it to
b0618399
TC
804choose the color you want, you will need to supply only paletted
805images and set the C<gif_eliminate_unused> tag to 0.
00424555 806
b0618399 807=item *
00424555 808
5715f7c3 809gif_trans_index - The index of the color in the color map used for
b0618399
TC
810transparency. If the image has a transparency then it is returned as
811a 4 channel image with the alpha set to zero in this palette entry.
812This value is not used when writing. ("Transparent Color Index")
00424555 813
b0618399 814=item *
97c4effc 815
b0618399 816gif_trans_color - A reference to an Imager::Color object, which is the
5715f7c3 817color to use for the palette entry used to represent transparency in
67d441b2
TC
818the palette. You need to set the C<transp> option (see
819L<Imager::ImageTypes/"Quantization options">) for this value to be
820used.
97c4effc 821
b0618399 822=item *
00424555 823
b0618399
TC
824gif_delay - The delay until the next frame is displayed, in 1/100 of a
825second. ("Delay Time").
00424555 826
b0618399 827=item *
00424555 828
b0618399
TC
829gif_user_input - whether or not a user input is expected before
830continuing (view dependent) ("User Input Flag").
00424555 831
b0618399 832=item *
00424555 833
b0618399 834gif_disposal - how the next frame is displayed ("Disposal Method")
00424555 835
b0618399 836=item *
00424555 837
b0618399
TC
838gif_loop - the number of loops from the Netscape Loop extension. This
839may be zero to loop forever.
00424555 840
b0618399 841=item *
00424555 842
5715f7c3 843gif_comment - the first block of the first GIF comment before each
b0618399 844image.
00424555 845
b0618399 846=item *
00424555 847
b0618399
TC
848gif_eliminate_unused - If this is true, when you write a paletted
849image any unused colors will be eliminated from its palette. This is
850set by default.
851
852=item *
97c4effc 853
b0618399
TC
854gif_colormap_size - the original size of the color map for the image.
855The color map of the image may have been expanded to include out of
856range color indexes.
97c4effc 857
00424555
TC
858=back
859
5715f7c3 860Where applicable, the ("name") is the name of that field from the C<GIF89>
00424555 861standard.
c2188f93 862
5715f7c3 863The following GIF writing options are obsolete, you should set the
97c4effc
TC
864corresponding tag in the image, either by using the tags functions, or
865by supplying the tag and value as options.
866
867=over
868
b0618399 869=item *
97c4effc 870
5715f7c3
TC
871gif_each_palette - Each image in the GIF file has it's own palette if
872this is non-zero. All but the first image has a local color table
873(the first uses the global color table.
97c4effc
TC
874
875Use C<gif_local_map> in new code.
876
b0618399 877=item *
97c4effc 878
b0618399 879interlace - The images are written interlaced if this is non-zero.
97c4effc
TC
880
881Use C<gif_interlace> in new code.
882
b0618399 883=item *
97c4effc 884
b0618399
TC
885gif_delays - A reference to an array containing the delays between
886images, in 1/100 seconds.
97c4effc
TC
887
888Use C<gif_delay> in new code.
889
b0618399 890=item *
97c4effc 891
b0618399
TC
892gif_positions - A reference to an array of references to arrays which
893represent screen positions for each image.
97c4effc
TC
894
895New code should use the C<gif_left> and C<gif_top> tags.
896
b0618399 897=item *
97c4effc 898
b0618399
TC
899gif_loop_count - If this is non-zero the Netscape loop extension block
900is generated, which makes the animation of the images repeat.
97c4effc 901
5715f7c3 902This is currently unimplemented due to some limitations in C<giflib>.
97c4effc
TC
903
904=back
905
f1adece7
TC
906You can supply a C<page> parameter to the C<read()> method to read
907some page other than the first. The page is 0 based:
908
909 # read the second image in the file
910 $image->read(file=>"example.gif", page=>1)
911 or die "Cannot read second page: ",$image->errstr,"\n";
912
5715f7c3 913Before release 0.46, Imager would read multiple image GIF image files
f1adece7
TC
914into a single image, overlaying each of the images onto the virtual
915GIF screen.
916
917As of 0.46 the default is to read the first image from the file, as if
918called with C<< page => 0 >>.
919
5715f7c3 920You can return to the previous behavior by calling read with the
f1adece7
TC
921C<gif_consolidate> parameter set to a true value:
922
923 $img->read(file=>$some_gif_file, gif_consolidate=>1);
924
5c0d0ddf
TC
925As with the to_paletted() method, if you supply a colors parameter as
926a reference to an array, this will be filled with Imager::Color
927objects of the color table generated for the image file.
928
c2188f93
TC
929=head2 TIFF (Tagged Image File Format)
930
b5dd0159 931Imager can write images to either paletted or RGB TIFF images,
38218f79
TC
932depending on the type of the source image.
933
934When writing direct color images to TIFF the sample size of the
935output file depends on the input:
936
937=over
938
939=item *
940
941double/sample - written as 32-bit/sample TIFF
942
943=item *
944
94516-bit/sample - written as 16-bit/sample TIFF
946
947=item *
948
9498-bit/sample - written as 8-bit/sample TIFF
950
951=back
952
953For paletted images:
954
955=over
956
957=item *
958
959C<< $img->is_bilevel >> is true - the image is written as bi-level
960
961=item *
962
963otherwise - image is written as paletted.
964
965=back
b5dd0159
TC
966
967If you are creating images for faxing you can set the I<class>
968parameter set to C<fax>. By default the image is written in fine
969mode, but this can be overridden by setting the I<fax_fine> parameter
970to zero. Since a fax image is bi-level, Imager uses a threshold to
971decide if a given pixel is black or white, based on a single channel.
5715f7c3 972For gray scale images channel 0 is used, for color images channel 1
b5dd0159
TC
973(green) is used. If you want more control over the conversion you can
974use $img->to_paletted() to product a bi-level image. This way you can
975use dithering:
976
bd8052a6 977 my $bilevel = $img->to_paletted(make_colors => 'mono',
b5dd0159
TC
978 translate => 'errdiff',
979 errdiff => 'stucki');
00424555 980
b5dd0159
TC
981=over
982
38218f79 983=item *
b5dd0159 984
38218f79
TC
985C<class> - If set to 'fax' the image will be written as a bi-level fax
986image.
b5dd0159 987
38218f79 988=item *
b5dd0159 989
38218f79
TC
990C<fax_fine> - By default when C<class> is set to 'fax' the image is
991written in fine mode, you can select normal mode by setting
992C<fax_fine> to 0.
b5dd0159
TC
993
994=back
995
996Imager should be able to read any TIFF image you supply. Paletted
997TIFF images are read as paletted Imager images, since paletted TIFF
998images have 16-bits/sample (48-bits/color) this means the bottom
38218f79 9998-bits are lost, but this shouldn't be a big deal.
b5dd0159
TC
1000
1001TIFF supports the spatial resolution tags. See the
1002C<tiff_resolutionunit> tag for some extra options.
00424555 1003
bd8052a6
TC
1004As of Imager 0.62 Imager reads:
1005
1006=over
1007
1008=item *
1009
38218f79
TC
10108-bit/sample gray, RGB or CMYK images, including a possible alpha
1011channel as an 8-bit/sample image.
1012
1013=item *
1014
5715f7c3 101516-bit gray, RGB, or CMYK image, including a possible alpha channel as
bd8052a6
TC
1016a 16-bit/sample image.
1017
1018=item *
1019
5715f7c3 102032-bit gray, RGB image, including a possible alpha channel as a
bd8052a6
TC
1021double/sample image.
1022
1023=item *
1024
1025bi-level images as paletted images containing only black and white,
1026which other formats will also write as bi-level.
1027
1028=item *
1029
1030tiled paletted images are now handled correctly
1031
38218f79
TC
1032=item *
1033
1034other images are read using C<tifflib>'s RGBA interface as
10358-bit/sample images.
1036
bd8052a6
TC
1037=back
1038
5df0fac7
AMH
1039The following tags are set in a TIFF image when read, and can be set
1040to control output:
1041
1042=over
1043
38218f79 1044=item *
bd8052a6 1045
38218f79
TC
1046C<tiff_compression> - When reading an image this is set to the numeric
1047value of the TIFF compression tag.
bd8052a6
TC
1048
1049On writing you can set this to either a numeric compression tag value,
1050or one of the following values:
1051
1052 Ident Number Description
1053 none 1 No compression
1054 packbits 32773 Macintosh RLE
1055 ccittrle 2 CCITT RLE
1056 fax3 3 CCITT Group 3 fax encoding (T.4)
1057 t4 3 As above
1058 fax4 4 CCITT Group 4 fax encoding (T.6)
1059 t6 4 As above
1060 lzw 5 LZW
1061 jpeg 7 JPEG
1062 zip 8 Deflate (GZIP) Non-standard
1063 deflate 8 As above.
1064 oldzip 32946 Deflate with an older code.
1065 ccittrlew 32771 Word aligned CCITT RLE
1066
1067In general a compression setting will be ignored where it doesn't make
1068sense, eg. C<jpeg> will be ignored for compression if the image is
1069being written as bilevel.
1070
5715f7c3
TC
1071=for stopwords LZW
1072
1073Imager attempts to check that your build of C<libtiff> supports the
1074given compression, and will fallback to C<packbits> if it isn't
1075enabled. eg. older distributions didn't include LZW compression, and
1076JPEG compression is only available if C<libtiff> is configured with
1077C<libjpeg>'s location.
bd8052a6
TC
1078
1079 $im->write(file => 'foo.tif', tiff_compression => 'lzw')
1080 or die $im->errstr;
1081
38218f79 1082=item *
bd8052a6 1083
38218f79
TC
1084C<tags, tiff_jpegquality>C<tiff_jpegquality> - If C<tiff_compression>
1085is C<jpeg> then this can be a number from 1 to 100 giving the JPEG
1086compression quality. High values are better quality and larger files.
bd8052a6 1087
38218f79 1088=item *
5df0fac7 1089
38218f79
TC
1090X<tags, tiff_resolutionunit>C<tiff_resolutionunit> - The value of the
1091C<ResolutionUnit> tag. This is ignored on writing if the
1092i_aspect_only tag is non-zero.
5df0fac7 1093
b5dd0159 1094The C<i_xres> and C<i_yres> tags are expressed in pixels per inch no
6d54291b 1095matter the value of this tag, they will be converted to/from the value
b5dd0159
TC
1096stored in the TIFF file.
1097
38218f79 1098=item *
3cff89e2 1099
38218f79
TC
1100X<tags, tiff_resolutionunit_name>C<tiff_resolutionunit_name> - This is
1101set when reading a TIFF file to the name of the unit given by
3cff89e2
TC
1102C<tiff_resolutionunit>. Possible results include C<inch>,
1103C<centimeter>, C<none> (the C<i_aspect_only> tag is also set reading
1104these files) or C<unknown>.
1105
38218f79 1106=item *
5df0fac7 1107
38218f79
TC
1108X<tags, tiff_bitspersample>C<tiff_bitspersample> - Bits per sample
1109from the image. This value is not used when writing an image, it is
1110only set on a read image.
5df0fac7 1111
38218f79 1112=item *
5df0fac7 1113
38218f79
TC
1114X<tags, tiff_photometric>C<tiff_photometric> - Value of the
1115C<PhotometricInterpretation> tag from the image. This value is not
1116used when writing an image, it is only set on a read image.
5df0fac7 1117
38218f79 1118=item *
5df0fac7 1119
38218f79
TC
1120C<tiff_documentname>, C<tiff_imagedescription>, C<tiff_make>,
1121C<tiff_model>, C<tiff_pagename>, C<tiff_software>, C<tiff_datetime>,
1122C<tiff_artist>, C<tiff_hostcomputer> - Various strings describing the
1123image. C<tiff_datetime> must be formatted as "YYYY:MM:DD HH:MM:SS".
1124These correspond directly to the mixed case names in the TIFF
1125specification. These are set in images read from a TIFF and saved
1126when writing a TIFF image.
5df0fac7 1127
377f56e5
TC
1128=back
1129
8f8bd9aa
TC
1130You can supply a C<page> parameter to the C<read()> method to read
1131some page other than the first. The page is 0 based:
1132
1133 # read the second image in the file
1134 $image->read(file=>"example.tif", page=>1)
1135 or die "Cannot read second page: ",$image->errstr,"\n";
1136
a50608d2
TC
1137If you read an image with multiple alpha channels, then only the first
1138alpha channel will be read.
1139
9d5ff8a6
TC
1140When reading a C<TIFF> image with callbacks, the C<seekcb> callback
1141parameter is also required.
1142
1143When writing a C<TIFF> image with callbacks, the C<seekcb> and
1144C<readcb> parameters are also required.
1145
1146C<TIFF> is a random access file format, it cannot be read from or
1147written to unseekable streams such as pipes or sockets.
1148
5715f7c3 1149=head2 BMP (Windows Bitmap)
5df0fac7 1150
b5dd0159
TC
1151Imager can write 24-bit RGB, and 8, 4 and 1-bit per pixel paletted
1152Windows BMP files. Currently you cannot write compressed BMP files
1153with Imager.
5df0fac7 1154
b5dd0159
TC
1155Imager can read 24-bit RGB, and 8, 4 and 1-bit perl pixel paletted
1156Windows BMP files. There is some support for reading 16-bit per pixel
1157images, but I haven't found any for testing.
5df0fac7 1158
5715f7c3 1159BMP has no support for multiple image files.
c2188f93 1160
b5dd0159
TC
1161BMP files support the spatial resolution tags, but since BMP has no
1162support for storing only an aspect ratio, if C<i_aspect_only> is set
1163when you write the C<i_xres> and C<i_yres> values are scaled so the
b294e724 1164smaller is 72 DPI.
5df0fac7 1165
b5dd0159 1166The following tags are set when you read an image from a BMP file:
5df0fac7
AMH
1167
1168=over
1169
1170=item bmp_compression
1171
b5dd0159
TC
1172The type of compression, if any. This can be any of the following
1173values:
1174
5715f7c3
TC
1175=for stopwords RLE
1176
b5dd0159
TC
1177=over
1178
1179=item BI_RGB (0)
1180
1181Uncompressed.
1182
1183=item BI_RLE8 (1)
1184
11858-bits/pixel paletted value RLE compression.
1186
1187=item BI_RLE4 (2)
1188
11894-bits/pixel paletted value RLE compression.
1190
1191=item BI_BITFIELDS (3)
1192
1193Packed RGB values.
1194
1195=back
5df0fac7 1196
662e3c02
TC
1197=item bmp_compression_name
1198
1199The bmp_compression value as a BI_* string
1200
5df0fac7
AMH
1201=item bmp_important_colors
1202
1203The number of important colors as defined by the writer of the image.
1204
662e3c02
TC
1205=item bmp_used_colors
1206
1207Number of color used from the BMP header
1208
1209=item bmp_filesize
1210
1211The file size from the BMP header
1212
1213=item bmp_bit_count
1214
1215Number of bits stored per pixel. (24, 8, 4 or 1)
1216
5df0fac7
AMH
1217=back
1218
5715f7c3
TC
1219=for stopwords Targa
1220
1221=head2 TGA (Targa)
b5dd0159 1222
5715f7c3
TC
1223When storing Targa images RLE compression can be activated with the
1224C<compress> parameter, the C<idstring> parameter can be used to set the
1225Targa comment field and the C<wierdpack> option can be used to use the
122615 and 16 bit Targa formats for RGB and RGBA data. The 15 bit format
f5fd108b
AMH
1227has 5 of each red, green and blue. The 16 bit format in addition
1228allows 1 bit of alpha. The most significant bits are used for each
1229channel.
1230
b5dd0159 1231Tags:
5df0fac7 1232
b5dd0159 1233=over
5df0fac7 1234
b5dd0159 1235=item tga_idstring
5df0fac7 1236
b5dd0159 1237=item tga_bitspp
5df0fac7 1238
b5dd0159 1239=item compressed
5df0fac7 1240
b5dd0159
TC
1241=back
1242
f5fd108b
AMH
1243=head2 RAW
1244
f5fd108b 1245When reading raw images you need to supply the width and height of the
5715f7c3 1246image in the C<xsize> and C<ysize> options:
f5fd108b
AMH
1247
1248 $img->read(file=>'foo.raw', xsize=>100, ysize=>100)
1249 or die "Cannot read raw image\n";
1250
1251If your input file has more channels than you want, or (as is common),
7eaf2fc1
TC
1252junk in the fourth channel, you can use the C<raw_datachannels> and
1253C<raw_storechannels> options to control the number of channels in your input
f5fd108b
AMH
1254file and the resulting channels in your image. For example, if your
1255input image uses 32-bits per pixel with red, green, blue and junk
1256values for each pixel you could do:
1257
7eaf2fc1
TC
1258 $img->read(file=>'foo.raw', xsize => 100, ysize => 100,
1259 raw_datachannels => 4, raw_storechannels => 3,
1260 raw_interleave => 0)
f5fd108b
AMH
1261 or die "Cannot read raw image\n";
1262
7eaf2fc1
TC
1263In general, if you supply C<raw_storechannels> you should also supply
1264C<raw_datachannels>
1265
500888da 1266Read parameters:
f5fd108b 1267
500888da
TC
1268=over
1269
1270=item *
1271
7eaf2fc1 1272C<raw_interleave> - controls the ordering of samples within the image.
500888da
TC
1273Default: 1. Alternatively and historically spelled C<interleave>.
1274Possible values:
1275
1276=over
1277
1278=item *
1279
12800 - samples are pixel by pixel, so all samples for the first pixel,
1281then all samples for the second pixel and so on. eg. for a four pixel
5715f7c3 1282scan line the channels would be laid out as:
500888da
TC
1283
1284 012012012012
1285
1286=item *
1287
5715f7c3
TC
12881 - samples are line by line, so channel 0 for the entire scan line is
1289followed by channel 1 for the entire scan line and so on. eg. for a
1290four pixel scan line the channels would be laid out as:
500888da
TC
1291
1292 000011112222
1293
1294This is the default.
1295
1296=back
1297
1298Unfortunately, historically, the default C<raw_interleave> for read
1299has been 1, while writing only supports the C<raw_interleave> = 0
1300format.
1301
1302For future compatibility, you should always supply the
1303C<raw_interleave> (or C<interleave>) parameter. As of 0.68, Imager
1304will warn if you attempt to read a raw image without a
1305C<raw_interleave> parameter.
1306
1307=item *
1308
7eaf2fc1 1309C<raw_storechannels> - the number of channels to store in the image.
500888da
TC
1310Range: 1 to 4. Default: 3. Alternatively and historically spelled
1311C<storechannels>.
1312
1313=item *
1314
7eaf2fc1 1315C<raw_datachannels> - the number of channels to read from the file.
500888da
TC
1316Range: 1 or more. Default: 3. Alternatively and historically spelled
1317C<datachannels>.
1318
1319=back
1320
1321 $img->read(file=>'foo.raw', xsize=100, ysize=>100, raw_interleave=>1)
f5fd108b
AMH
1322 or die "Cannot read raw image\n";
1323
f52db34b
TC
1324=head2 PNG
1325
fbc49dbe
TC
1326=head3 PNG Image modes
1327
6c38d774
TC
1328PNG files can be read and written in the following modes:
1329
1330=over
1331
1332=item *
1333
fbc49dbe 1334bi-level - written as a 1-bit per sample gray scale image
6c38d774
TC
1335
1336=item *
1337
fbc49dbe
TC
1338paletted - Imager gray scale paletted images are written as RGB
1339paletted images. PNG palettes can include alpha values for each entry
1340and this is honored as an Imager four channel paletted image.
6c38d774
TC
1341
1342=item *
1343
fbc49dbe 13448 and 16-bit per sample gray scale, optionally with an alpha channel.
6c38d774
TC
1345
1346=item *
1347
13488 and 16-bit per sample RGB, optionally with an alpha channel.
1349
fbc49dbe 1350=back
6c38d774
TC
1351
1352Unlike GIF, there is no automatic conversion to a paletted image,
1353since PNG supports direct color.
1354
fbc49dbe
TC
1355=head3 PNG Text tags
1356
6c38d774
TC
1357Text tags are retrieved from and written to PNG C<tEXT> or C<zTXT>
1358chunks. The following standard tags from the PNG specification are
1359directly supported:
1360
1361=over
1362
1363=item *
1364
1365C<i_comment>X<tags,i_comment> - keyword of "Comment".
1366
1367=item *
1368
1369C<png_author>X<tags,PNG,png_author> - keyword "Author".
1370
1371=item *
1372
1373C<png_copyright>X<tags,PNG,png_copyright> - keyword "Copyright".
1374
1375=item *
1376
1377C<png_creation_time>X<tags,PNG,png_creation_time> - keyword "Creation Time".
1378
1379=item *
1380
1381C<png_description>X<tags,PNG,png_description> - keyword "Description".
1382
1383=item *
1384
1385C<png_disclaimer>X<tags,PNG,png_disclaimer> - keyword "Disclaimer".
1386
1387=item *
1388
1389C<png_software>X<tags,PNG,png_software> - keyword "Software".
1390
1391=item *
1392
1393C<png_title>X<tags,PNG,png_title> - keyword "Title".
1394
1395=item *
1396
1397C<png_warning>X<tags,PNG,png_warning> - keyword "Warning".
1398
1399=back
f52db34b 1400
be4b66bb 1401Each of these tags has a corresponding C<< I<base-tag-name>_compressed
fbc49dbe
TC
1402>> tag, eg. C<png_comment_compressed>. When reading, if the PNG chunk
1403is compressed this tag will be set to 1, but is otherwise unset. When
1404writing, Imager will honor the compression tag if set and non-zero,
1405otherwise the chunk text will be compressed if the value is longer
1406than 1000 characters, as recommended by the C<libpng> documentation.
1407
1408PNG C<tEXT> or C<zTXT> chunks outside of those above are read into or
1409written from Imager tags named like:
1410
1411=over
1412
1413=item *
1414
1415C<< png_textI<N>_key >> - the key for the text chunk. This can be 1
1416to 79 characters, may not contain any leading, trailing or consecutive
1417spaces, and may contain only Latin-1 characters from 32-126, 161-255.
1418
1419=item *
1420
1421C<< png_textI<N>_text >> - the text for the text chunk. This may not
1422contain any C<NUL> characters.
1423
1424=item *
1425
1426C<< png_textI<N>_compressed >> - whether or not the text chunk is
1427compressed. This behaves similarly to the C<<
1428I<base-tag-name>_compressed >> tags described above.
1429
1430=back
1431
1432Where I<N> starts from 0. When writing both the C<..._key> and
1433C<..._text> tags must be present or the write will fail. If the key
1434or text do not satisfy the requirements above the write will fail.
1435
1436=head3 Other PNG metadata tags
1437
1438=over
1439
1440=item *
1441
1442X<tags, png_interlace>C<png_interlace>, C<png_interlace_name> - only
1443set when reading, C<png_interlace> is set to the type of interlacing
1444used by the file, 0 for one, 1 for Adam7. C<png_interlace_name> is
1445set to a keyword describing the interlacing, either C<none> or
1446C<adam7>.
1447
1448=item *
1449
1450X<tags, png_srgb_intent>C<png_srgb_intent> - the sRGB rendering intent
1451for the image. an integer from 0 to 3, per the PNG specification. If
1452this chunk is found in the PNG file the C<gAMA> and C<cHRM> are
28d08bb1 1453ignored and the C<png_gamma> and C<png_chroma_...> tags are not set.
fbc49dbe
TC
1454Similarly when writing if C<png_srgb_intent> is set the C<gAMA> and
1455C<cHRM> chunks are not written.
1456
1457=item *
1458
be4b66bb 1459X<tags, png_gamma>C<png_gamma> - the gamma of the image. This value is
fbc49dbe
TC
1460not currently used by Imager when processing the image, but this may
1461change in the future.
1462
1463=item *
1464
1465X<tags, png_chroma_...>C<png_chroma_white_x>, C<png_chroma_white_y>,
1466C<png_chroma_red_x>, C<png_chroma_red_y>, C<png_chroma_green_x>,
1467C<png_chroma_green_y>, C<png_chroma_blue_x>, C<png_chroma_blue_y> -
1468the primary chromaticities of the image, defining the color model.
1469This is currently not used by Imager when processing the image, but
1470this may change in the future.
1471
1472=item *
1473
1474C<i_xres>, C<i_yres>, C<i_aspect_only> - processed per
1475I<Imager::ImageTypes/CommonTags>.
1476
1477=item *
1478
1479X<tags, png_bits>C<png_bits> - the number of bits per sample in the
1480representation. Ignored when writing.
1481
1482=item *
1483
be4b66bb 1484X<tags, png_time>C<png_time> - the creation time of the file formatted
fbc49dbe
TC
1485as C<< I<year>-I<month>-I<day>TI<hour>:I<minute>:I<second> >>. This
1486is stored as time data structure in the file, not a string. If you
1487set C<png_time> and it cannot be parsed as above, writing the PNG file
1488will fail.
1489
1490=item *
1491
1492C<i_background> - set from the C<sBKG> when reading an image file.
1493
1494=back
1495
28d08bb1
TC
1496X<compression>X<png_compression_level>You can control the level of
1497F<zlib> compression used when writing with the
1498C<png_compression_level> parameter. This can be an integer between 0
1499(uncompressed) and 9 (best compression).
1500
57520a19
TC
1501=for stopwords
1502CRC
1503
79f95bf1
TC
1504X<png_ignore_benign_errors>If you're using F<libpng> 1.6 or later, or
1505an earlier release configured with C<PNG_BENIGN_ERRORS_SUPPORTED>, you
57520a19
TC
1506can choose to ignore file format errors the authors of F<libpng>
1507consider I<benign>, this includes at least CRC errors and palette
1508index overflows. Do this by supplying a true value for the
1509C<png_ignore_benign_errors> parameter to the read() method:
1510
1511 $im->read(file => "foo.png", png_ignore_benign_errors => 1)
1512 or die $im->errstr;
1513
2b405c9e
TC
1514=head2 ICO (Microsoft Windows Icon) and CUR (Microsoft Windows Cursor)
1515
1516Icon and Cursor files are very similar, the only differences being a
5715f7c3 1517number in the header and the storage of the cursor hot spot. I've
2b405c9e
TC
1518treated them separately so that you're not messing with tags to
1519distinguish between them.
1520
1521The following tags are set when reading an icon image and are used
1522when writing it:
1523
1524=over
1525
1526=item ico_mask
1527
1528This is the AND mask of the icon. When used as an icon in Windows 1
1529bits in the mask correspond to pixels that are modified by the source
1530image rather than simply replaced by the source image.
1531
1532Rather than requiring a binary bitmap this is accepted in a specific format:
1533
1534=over
1535
1536=item *
1537
1538first line consisting of the 0 placeholder, the 1 placeholder and a
1539newline.
1540
1541=item *
1542
5715f7c3 1543following lines which contain 0 and 1 placeholders for each scan line
2b405c9e
TC
1544of the image, starting from the top of the image.
1545
1546=back
1547
1548When reading an image, '.' is used as the 0 placeholder and '*' as the
15491 placeholder. An example:
1550
1551 .*
1552 ..........................******
1553 ..........................******
1554 ..........................******
1555 ..........................******
1556 ...........................*****
1557 ............................****
1558 ............................****
1559 .............................***
1560 .............................***
1561 .............................***
1562 .............................***
1563 ..............................**
1564 ..............................**
1565 ...............................*
1566 ...............................*
1567 ................................
1568 ................................
1569 ................................
1570 ................................
1571 ................................
1572 ................................
1573 *...............................
1574 **..............................
1575 **..............................
1576 ***.............................
1577 ***.............................
1578 ****............................
1579 ****............................
1580 *****...........................
1581 *****...........................
1582 *****...........................
1583 *****...........................
1584
1585=back
1586
1587The following tags are set when reading an icon:
1588
1589=over
1590
1591=item ico_bits
1592
1593The number of bits per pixel used to store the image.
1594
1595=back
1596
1597For cursor files the following tags are set and read when reading and
1598writing:
1599
1600=over
1601
1602=item cur_mask
1603
1604This is the same as the ico_mask above.
1605
1606=item cur_hotspotx
1607
1608=item cur_hotspoty
1609
1610The "hot" spot of the cursor image. This is the spot on the cursor
1611that you click with. If you set these to out of range values they are
1612clipped to the size of the image when written to the file.
1613
1614=back
1615
413dc198
TC
1616The following parameters can be supplied to read() or read_multi() to
1617control reading of ICO/CUR files:
1618
1619=over
1620
1621=item *
1622
f17a0a60
TC
1623C<ico_masked> - if true, the default, then the icon/cursors mask is
1624applied as an alpha channel to the image, unless that image already
1625has an alpha channel. This may result in a paletted image being
1626returned as a direct color image. Default: 1
413dc198
TC
1627
1628 # retrieve the image as stored, without using the mask as an alpha
1629 # channel
1630 $img->read(file => 'foo.ico', ico_masked => 0)
1631 or die $img->errstr;
1632
1633This was introduced in Imager 0.60. Previously reading ICO images
6cfee9d1 1634acted as if C<ico_masked =E<gt> 0>.
413dc198 1635
f17a0a60
TC
1636=item *
1637
1638C<ico_alpha_masked> - if true, then the icon/cursor mask is applied as
1639an alpha channel to images that already have an alpha mask. Note that
1640this will only make pixels transparent, not opaque. Default: 0.
1641
1642Note: If you get different results between C<ico_alpha_masked> being
028633be 1643set to 0 and 1, your mask may break when used with the Win32 API.
f17a0a60 1644
413dc198
TC
1645=back
1646
2b405c9e
TC
1647C<cur_bits> is set when reading a cursor.
1648
1649Examples:
1650
1651 my $img = Imager->new(xsize => 32, ysize => 32, channels => 4);
1652 $im->box(color => 'FF0000');
1653 $im->write(file => 'box.ico');
1654
1655 $im->settag(name => 'cur_hotspotx', value => 16);
1656 $im->settag(name => 'cur_hotspoty', value => 16);
1657 $im->write(file => 'box.cur');
1658
5715f7c3
TC
1659=for stopwords BW
1660
d5477d3d
TC
1661=head2 SGI (RGB, BW)
1662
1663SGI images, often called by the extensions, RGB or BW, can be stored
1664either uncompressed or compressed using an RLE compression.
1665
1666By default, when saving to an extension of C<rgb>, C<bw>, C<sgi>,
1667C<rgba> the file will be saved in SGI format. The file extension is
1668otherwise ignored, so saving a 3-channel image to a C<.bw> file will
1669result in a 3-channel image on disk.
1670
1671The following tags are set when reading a SGI image:
1672
1673=over
1674
1675=item *
1676
5715f7c3
TC
1677i_comment - the C<IMAGENAME> field from the image. Also written to
1678the file when writing.
d5477d3d
TC
1679
1680=item *
1681
5715f7c3
TC
1682sgi_pixmin, sgi_pixmax - the C<PIXMIN> and C<PIXMAX> fields from the
1683image. On reading image data is expanded from this range to the full
1684range of samples in the image.
d5477d3d
TC
1685
1686=item *
1687
1688sgi_bpc - the number of bytes per sample for the image. Ignored when
1689writing.
1690
1691=item *
1692
1693sgi_rle - whether or not the image is compressed. If this is non-zero
1694when writing the image will be compressed.
1695
1696=back
1697
53a6bbd4
TC
1698=head1 ADDING NEW FORMATS
1699
1700To support a new format for reading, call the register_reader() class
1701method:
1702
1703=over
1704
67d441b2 1705=item register_reader()
53a6bbd4
TC
1706
1707Registers single or multiple image read functions.
1708
1709Parameters:
1710
1711=over
1712
1713=item *
1714
1715type - the identifier of the file format, if Imager's
1716i_test_format_probe() can identify the format then this value should
1717match i_test_format_probe()'s result.
1718
1719This parameter is required.
1720
1721=item *
1722
1723single - a code ref to read a single image from a file. This is
1724supplied:
1725
1726=over
1727
1728=item *
1729
1730the object that read() was called on,
1731
1732=item *
1733
1734an Imager::IO object that should be used to read the file, and
1735
1736=item *
1737
1738all the parameters supplied to the read() method.
1739
1740=back
1741
1742The single parameter is required.
1743
1744=item *
1745
1746multiple - a code ref which is called to read multiple images from a
1747file. This is supplied:
1748
1749=over
1750
1751=item *
1752
1753an Imager::IO object that should be used to read the file, and
1754
1755=item *
1756
1757all the parameters supplied to the read_multi() method.
1758
1759=back
1760
1761=back
1762
1763Example:
1764
1765 # from Imager::File::ICO
1766 Imager->register_reader
1767 (
1768 type=>'ico',
1769 single =>
1770 sub {
1771 my ($im, $io, %hsh) = @_;
1772 $im->{IMG} = i_readico_single($io, $hsh{page} || 0);
1773
1774 unless ($im->{IMG}) {
1775 $im->_set_error(Imager->_error_as_msg);
1776 return;
1777 }
1778 return $im;
1779 },
1780 multiple =>
1781 sub {
1782 my ($io, %hsh) = @_;
1783
1784 my @imgs = i_readico_multi($io);
1785 unless (@imgs) {
1786 Imager->_set_error(Imager->_error_as_msg);
1787 return;
1788 }
1789 return map {
1790 bless { IMG => $_, DEBUG => $Imager::DEBUG, ERRSTR => undef }, 'Imager'
1791 } @imgs;
1792 },
1793 );
1794
67d441b2 1795=item register_writer()
2b405c9e
TC
1796
1797Registers single or multiple image write functions.
1798
1799Parameters:
1800
1801=over
1802
1803=item *
1804
1805type - the identifier of the file format. This is typically the
1806extension in lowercase.
1807
1808This parameter is required.
1809
1810=item *
1811
1812single - a code ref to write a single image to a file. This is
1813supplied:
1814
1815=over
1816
1817=item *
1818
1819the object that write() was called on,
1820
1821=item *
1822
1823an Imager::IO object that should be used to write the file, and
1824
1825=item *
1826
1827all the parameters supplied to the write() method.
1828
1829=back
1830
1831The single parameter is required.
1832
1833=item *
1834
1835multiple - a code ref which is called to write multiple images to a
1836file. This is supplied:
1837
1838=over
1839
1840=item *
1841
1842the class name write_multi() was called on, this is typically
1843C<Imager>.
1844
1845=item *
1846
1847an Imager::IO object that should be used to write the file, and
1848
1849=item *
1850
1851all the parameters supplied to the read_multi() method.
1852
1853=back
1854
1855=back
1856
504721f3
TC
1857=item add_type_extensions($type, $ext, ...)
1858
1859This class method can be used to add extensions to the map used by
1860C<def_guess_type> when working out the file type a filename extension.
1861
1862 Imager->add_type_extension(mytype => "mytype", "mytypish");
1863 ...
1864 $im->write(file => "foo.mytypish") # use the mytype handler
1865
53a6bbd4
TC
1866=back
1867
1868If you name the reader module C<Imager::File::>I<your-format-name>
1869where I<your-format-name> is a fully upper case version of the type
2b405c9e
TC
1870value you would pass to read(), read_multi(), write() or write_multi()
1871then Imager will attempt to load that module if it has no other way to
1872read or write that format.
53a6bbd4
TC
1873
1874For example, if you create a module Imager::File::GIF and the user has
1875built Imager without it's normal GIF support then an attempt to read a
1876GIF image will attempt to load Imager::File::GIF.
1877
2b405c9e
TC
1878If your module can only handle reading then you can name your module
1879C<Imager::File::>I<your-format-name>C<Reader> and Imager will attempt
1880to autoload it.
1881
1882If your module can only handle writing then you can name your module
1883C<Imager::File::>I<your-format-name>C<Writer> and Imager will attempt
1884to autoload it.
1885
2c331f9f
TC
1886=head1 PRELOADING FILE MODULES
1887
1888=over
1889
67d441b2 1890=item preload()
2c331f9f
TC
1891
1892This preloads the file support modules included with or that have been
1893included with Imager in the past. This is intended for use in forking
1894servers such as mod_perl.
1895
1896If the module is not available no error occurs.
1897
1898Preserves $@.
1899
1900 use Imager;
1901 Imager->preload;
1902
1903=back
1904
9d1c4956 1905=head1 EXAMPLES
f5fd108b 1906
9d1c4956 1907=head2 Producing an image from a CGI script
f5fd108b 1908
9d1c4956
TC
1909Once you have an image the basic mechanism is:
1910
5715f7c3
TC
1911=for stopwords STDOUT
1912
9d1c4956
TC
1913=over
1914
1915=item 1.
1916
1917set STDOUT to autoflush
1918
1919=item 2.
1920
1921output a content-type header, and optionally a content-length header
1922
1923=item 3.
1924
1925put STDOUT into binmode
1926
1927=item 4.
1928
1929call write() with the C<fd> or C<fh> parameter. You will need to
926880d8
TC
1930provide the C<type> parameter since Imager can't use the extension to
1931guess the file format you want.
9d1c4956
TC
1932
1933=back
1934
1935 # write an image from a CGI script
1936 # using CGI.pm
1937 use CGI qw(:standard);
1938 $| = 1;
1939 binmode STDOUT;
1940 print header(-type=>'image/gif');
1941 $img->write(type=>'gif', fd=>fileno(STDOUT))
1942 or die $img->errstr;
b5dd0159 1943
9d1c4956
TC
1944If you want to send a content length you can send the output to a
1945scalar to get the length:
b5dd0159 1946
9d1c4956
TC
1947 my $data;
1948 $img->write(type=>'gif', data=>\$data)
1949 or die $img->errstr;
1950 binmode STDOUT;
1951 print header(-type=>'image/gif', -content_length=>length($data));
1952 print $data;
b5dd0159 1953
9d1c4956 1954=head2 Writing an animated GIF
c2188f93 1955
9d1c4956
TC
1956The basic idea is simple, just use write_multi():
1957
1958 my @imgs = ...;
1959 Imager->write_multi({ file=>$filename, type=>'gif' }, @imgs);
1960
1961If your images are RGB images the default quantization mechanism will
1962produce a very good result, but can take a long time to execute. You
5715f7c3 1963could either use the standard web color map:
9d1c4956
TC
1964
1965 Imager->write_multi({ file=>$filename,
1966 type=>'gif',
1967 make_colors=>'webmap' },
1968 @imgs);
1969
1970or use a median cut algorithm to built a fairly optimal color map:
1971
1972 Imager->write_multi({ file=>$filename,
1973 type=>'gif',
1974 make_colors=>'mediancut' },
1975 @imgs);
1976
5715f7c3 1977By default all of the images will use the same global color map, which
9d1c4956
TC
1978will produce a smaller image. If your images have significant color
1979differences, you may want to generate a new palette for each image:
1980
1981 Imager->write_multi({ file=>$filename,
1982 type=>'gif',
1983 make_colors=>'mediancut',
1984 gif_local_map => 1 },
1985 @imgs);
1986
1987which will set the C<gif_local_map> tag in each image to 1.
1988Alternatively, if you know only some images have different colors, you
1989can set the tag just for those images:
1990
1991 $imgs[2]->settag(name=>'gif_local_map', value=>1);
1992 $imgs[4]->settag(name=>'gif_local_map', value=>1);
1993
1994and call write_multi() without a C<gif_local_map> parameter, or supply
1995an arrayref of values for the tag:
1996
1997 Imager->write_multi({ file=>$filename,
1998 type=>'gif',
1999 make_colors=>'mediancut',
2000 gif_local_map => [ 0, 0, 1, 0, 1 ] },
2001 @imgs);
2002
2003Other useful parameters include C<gif_delay> to control the delay
2004between frames and C<transp> to control transparency.
2005
2006=head2 Reading tags after reading an image
2007
2008This is pretty simple:
2009
2010 # print the author of a TIFF, if any
2011 my $img = Imager->new;
2012 $img->read(file=>$filename, type='tiff') or die $img->errstr;
2013 my $author = $img->tags(name=>'tiff_author');
2014 if (defined $author) {
2015 print "Author: $author\n";
2016 }
bac4fcee
AMH
2017
2018=head1 BUGS
2019
5715f7c3 2020When saving GIF images the program does NOT try to shave off extra
bac4fcee 2021colors if it is possible. If you specify 128 colors and there are
5715f7c3 2022only 2 colors used - it will have a 128 color table anyway.
bac4fcee 2023
97c4effc
TC
2024=head1 SEE ALSO
2025
2026Imager(3)
bac4fcee 2027
8ba1b8a6
TC
2028=head1 AUTHOR
2029
2030Tony Cook <tonyc@cpan.org>, Arnar M. Hrafnkelsson
2031
c2188f93 2032=cut