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