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