1Imager::Files(3) User Contributed Perl Documentation Imager::Files(3)
2
6 Imager::Files - working with image files
7
9 use Imager;
10 my $img = ...;
11 $img->write(file=>$filename, type=>$type)
12 or die "Cannot write: ",$img->errstr;
13 # type is optional if we can guess the format from the filename
15 $img->write(file => "foo.png")
16 or die "Cannot write: ",$img->errstr;
17 $img = Imager->new;
19 $img->read(file=>$filename, type=>$type)
20 or die "Cannot read: ", $img->errstr;
21 # type is optional if we can guess the type from the file data
23 # and we normally can guess
24 $img->read(file => $filename)
25 or die "Cannot read: ", $img->errstr;
26 Imager->write_multi({ file=> $filename, ... }, @images)
28 or die "Cannot write: ", Imager->errstr;
29 my @imgs = Imager->read_multi(file=>$filename)
31 or die "Cannot read: ", Imager->errstr;
32 Imager->set_file_limits(width=>$max_width, height=>$max_height)
34 my @read_types = Imager->read_types;
36 my @write_types = Imager->write_types;
37 # we can write/write_multi to things other than filenames
39 my $data;
40 $img->write(data => \$data, type => $type) or die;
41 my $fh = ... ; # eg. IO::File
43 $img->write(fh => $fh, type => $type) or die;
44 $img->write(fd => fileno($fh), type => $type) or die;
46 # some file types need seek callbacks too
48 $img->write(callback => \&write_callback, type => $type) or die;
49 # and similarly for read/read_multi
51 $img->read(data => $data) or die;
52 $img->read(fh => $fh) or die;
53 $img->read(fd => fileno($fh)) or die;
54 $img->read(callback => \&read_callback) or die;
55 use Imager 0.68;
57 my $img = Imager->new(file => $filename)
58 or die Imager->errstr;
59 Imager->add_file_magic(name => $name, bits => $bits, mask => $mask);
61
63 You can read and write a variety of images formats, assuming you have
64 the appropriate libraries, and images can be read or written to/from
65 files, file handles, file descriptors, scalars, or through callbacks.
66 To see which image formats Imager is compiled to support the following
68 code snippet is sufficient:
69 use Imager;
71 print join " ", keys %Imager::formats;
72 This will include some other information identifying libraries rather
74 than file formats. For new code you might find the "read_types()" or
75 "write_types()" methods useful.
76 read()
78 Reading writing to and from files is simple, use the "read()"
79 method to read an image:
80 my $img = Imager->new;
82 $img->read(file=>$filename, type=>$type)
83 or die "Cannot read $filename: ", $img->errstr;
84 In most cases Imager can auto-detect the file type, so you can just
86 supply the file name:
87 $img->read(file => $filename)
89 or die "Cannot read $filename: ", $img->errstr;
90 The read() method accepts the "allow_incomplete" parameter. If
92 this is non-zero then read() can return true on an incomplete image
93 and set the "i_incomplete" tag.
94 From Imager 0.68 you can supply most read() parameters to the new()
96 method to read the image file on creation. If the read fails,
97 check Imager->errstr() for the cause:
98 use Imager 0.68;
100 my $img = Imager->new(file => $filename)
101 or die "Cannot read $filename: ", Imager->errstr;
102 write()
104 and the "write()" method to write an image:
105 $img->write(file=>$filename, type=>$type)
107 or die "Cannot write $filename: ", $img->errstr;
108 read_multi()
110 If you're reading from a format that supports multiple images per
111 file, use the "read_multi()" method:
112 my @imgs = Imager->read_multi(file=>$filename, type=>$type)
114 or die "Cannot read $filename: ", Imager->errstr;
115 As with the read() method, Imager will normally detect the "type"
117 automatically.
118 write_multi()
120 and if you want to write multiple images to a single file use the
121 "write_multi()" method:
122 Imager->write_multi({ file=> $filename, type=>$type }, @images)
124 or die "Cannot write $filename: ", Imager->errstr;
125 read_types()
127 This is a class method that returns a list of the image file types
128 that Imager can read.
129 my @types = Imager->read_types;
131 These types are the possible values for the "type" parameter, not
133 necessarily the extension of the files you're reading.
134 It is possible for extra file read handlers to be loaded when
136 attempting to read a file, which may modify the list of available
137 read types.
138 write_types()
140 This is a class method that returns a list of the image file types
141 that Imager can write.
142 my @types = Imager->write_types;
144 Note that these are the possible values for the "type" parameter,
146 not necessarily the extension of the files you're writing.
147 It is possible for extra file write handlers to be loaded when
149 attempting to write a file, which may modify the list of available
150 write types.
151 When writing, if the "filename" includes an extension that Imager
153 recognizes, then you don't need the "type", but you may want to provide
154 one anyway. See "Guessing types" for information on controlling this
155 recognition.
156 The "type" parameter is a lowercase representation of the file type,
158 and can be any of the following:
159 bmp Windows BitMaP (BMP)
161 gif Graphics Interchange Format (GIF)
162 jpeg JPEG/JFIF
163 png Portable Network Graphics (PNG)
164 pnm Portable aNyMap (PNM)
165 raw Raw
166 sgi SGI .rgb files
167 tga TARGA
168 tiff Tagged Image File Format (TIFF)
169 When you read an image, Imager may set some tags, possibly including
171 information about the spatial resolution, textual information, and
172 animation information. See "Tags" in Imager::ImageTypes for specifics.
173 The open() method is a historical alias for the read() method.
175 Input and output
177 When reading or writing you can specify one of a variety of sources or
178 targets:
179 • "file" - The "file" parameter is the name of the image file to be
181 written to or read from. If Imager recognizes the extension of the
182 file you do not need to supply a "type".
183 # write in tiff format
185 $image->write(file => "example.tif")
186 or die $image->errstr;
187 $image->write(file => 'foo.tmp', type => 'tiff')
189 or die $image->errstr;
190 my $image = Imager->new;
192 $image->read(file => 'example.tif')
193 or die $image->errstr;
194 • "fh" - "fh" is a file handle, typically either returned from
196 "<IO::File-"new()>>, or a glob from an "open" call. You should
197 call "binmode" on the handle before passing it to Imager.
198 Imager will set the handle to autoflush to make sure any buffered
200 data is flushed , since Imager will write to the file descriptor
201 (from fileno()) rather than writing at the perl level.
202 $image->write(fh => \*STDOUT, type => 'gif')
204 or die $image->errstr;
205 # for example, a file uploaded via CGI.pm
207 $image->read(fd => $cgi->param('file'))
208 or die $image->errstr;
209 • "fd" - "fd" is a file descriptor. You can get this by calling the
211 "fileno()" function on a file handle, or by using one of the
212 standard file descriptor numbers.
213 If you get this from a perl file handle, you may need to flush any
215 buffered output, otherwise it may appear in the output stream after
216 the image.
217 $image->write(fd => file(STDOUT), type => 'gif')
219 or die $image->errstr;
220 • "data" - When reading data, "data" is a scalar containing the image
222 file data, or a reference to such a scalar. When writing, "data"
223 is a reference to the scalar to save the image file data to.
224 my $data;
226 $image->write(data => \$data, type => 'tiff')
227 or die $image->errstr;
228 my $data = $row->{someblob}; # eg. from a database
230 my @images = Imager->read_multi(data => $data)
231 or die Imager->errstr;
232 # from Imager 0.99
234 my @images = Imager->read_multi(data => \$data)
235 or die Imager->errstr;
236 • "callback", "readcb", "writecb", "seekcb", "closecb" - Imager will
238 make calls back to your supplied coderefs to read, write and seek
239 from/to/through the image file. See "I/O Callbacks" below for
240 details.
241 • "io" - an Imager::IO object.
243 By default Imager will use buffered I/O when reading or writing an
245 image. You can disabled buffering for output by supplying a "buffered
246 => 0" parameter to "write()" or "write_multi()".
247 I/O Callbacks
249 When reading from a file you can use either "callback" or "readcb" to
250 supply the read callback, and when writing "callback" or "writecb" to
251 supply the write callback.
252 Whether reading or writing a "TIFF" image, "seekcb" and "readcb" are
254 required.
255 If a file handler attempts to use "readcb", "writecb" or "seekcb" and
257 you haven't supplied one, the call will fail, failing the image read or
258 write, returning an error message indicating that the callback is
259 missing:
260 # attempting to read a TIFF image without a seekcb
262 open my $fh, "<", $filename or die;
263 my $rcb = sub {
264 my $val;
265 read($fh, $val, $_[0]) or return "";
266 return $val;
267 };
268 my $im = Imager->new(callback => $rcb)
269 or die Imager->errstr
270 # dies with (wrapped here):
271 # Error opening file: (Iolayer): Failed to read directory at offset 0:
272 # (Iolayer): Seek error accessing TIFF directory: seek callback called
273 # but no seekcb supplied
274 You can also provide a "closecb" parameter called when writing the file
276 is complete. If no "closecb" is supplied the default will succeed
277 silently.
278 # contrived
280 my $data;
281 sub mywrite {
282 $data .= unpack("H*", shift);
283 1;
284 }
285 Imager->write_multi({ callback => \&mywrite, type => 'gif'}, @images)
286 or die Imager->errstr;
287 "readcb"
289 The read callback is called with 2 parameters:
291 • "size" - the minimum amount of data required.
293 • "maxsize" - previously this was the maximum amount of data
295 returnable - currently it's always the same as "size"
296 Your read callback should return the data as a scalar:
298 • on success, a string containing the bytes read.
300 • on end of file, an empty string
302 • on error, "undef".
304 If your return value contains more data than "size" Imager will panic.
306 Your return value must not contain any characters over "\xFF" or Imager
308 will panic.
309 "writecb"
311 Your write callback takes exactly one parameter, a scalar containing
313 the data to be written.
314 Return true for success.
316 "seekcb"
318 The seek callback takes 2 parameters, a POSITION, and a WHENCE, defined
320 in the same way as perl's seek function.
321 Previously you always needed a "seekcb" callback if you called Imager's
323 "read()" or "read_multi()" without a "type" parameter, but this is no
324 longer necessary unless the file handler requires seeking, such as for
325 TIFF files.
326 Returns the new position in the file, or -1 on failure.
328 "closecb"
330 You can also supply a "closecb" which is called with no parameters when
332 there is no more data to be written. This could be used to flush
333 buffered data.
334 Return true on success.
336 Guessing types
338 When writing to a file, if you don't supply a "type" parameter Imager
339 will attempt to guess it from the file name. This is done by calling
340 the code reference stored in $Imager::FORMATGUESS. This is only done
341 when write() or write_multi() is called with a "file" parameter, or if
342 read() or read_multi() can't determine the type from the file's header.
343 The default function value of $Imager::FORMATGUESS is
345 "\&Imager::def_guess_type".
346 def_guess_type()
348 This is the default function Imager uses to derive a file type from
349 a file name. This is a function, not a method.
350 Accepts a single parameter, the file name and returns the type or
352 undef.
353 You can replace function with your own implementation if you have some
355 specialized need. The function takes a single parameter, the name of
356 the file, and should return either a file type or under.
357 # I'm writing jpegs to weird filenames
359 local $Imager::FORMATGUESS = sub { 'jpeg' };
360 When reading a file Imager examines beginning of the file for
362 identifying information. The current implementation attempts to detect
363 the following image types beyond those supported by Imager:
364 "xpm", "mng", "jng", "ilbm", "pcx", "fits", "psd" (Photoshop),
366 "eps", Utah "RLE".
367 You can now add to the magic database Imager uses for detecting file
369 types:
370 add_file_magic()
372 Imager->add_file_magic(name => $name, bits => $bits, mask => $mask)
373 Adds to list of magic, the parameters are all required. The
375 parameters are:
376 • "name" - the file type name to return on match.
378 • "bits" - a binary string to match.
380 • "mask" - a mask controlling which parts of bits are
382 significant.
383 While mask is mostly a bit mask, some byte values are translated,
385 the space character is treated as all zeros ("\x00"), and the "x"
386 character as all ones ("\xFF").
387 New magic entries take priority over old entries.
389 You can add more than one magic entry for a given name.
391 Imager->add_file_magic(name => "heif",
393 bits => " ftypheif"
394 mask => " xxxxxxxx");
395 Limiting the sizes of images you read
397 set_file_limits()
398 In some cases you will be receiving images from an untested source,
399 such as submissions via CGI. To prevent such images from consuming
400 large amounts of memory, you can set limits on the dimensions of
401 images you read from files:
402 • width - limit the width in pixels of the image
404 • height - limit the height in pixels of the image
406 • bytes - limits the amount of storage used by the image. This
408 depends on the width, height, channels and sample size of the
409 image. For paletted images this is calculated as if the image
410 was expanded to a direct color image.
411 To set the limits, call the class method set_file_limits:
413 Imager->set_file_limits(width=>$max_width, height=>$max_height);
415 You can pass any or all of the limits above, any limits you do not
417 pass are left as they were.
418 Any limit of zero for width or height is treated as unlimited.
420 A limit of zero for bytes is treated as one gigabyte, but higher
422 bytes limits can be set explicitly.
423 By default, the width and height limits are zero, or unlimited.
425 The default memory size limit is one gigabyte.
426 You can reset all limits to their defaults with the reset
428 parameter:
429 # no limits
431 Imager->set_file_limits(reset=>1);
432 This can be used with the other limits to reset all but the limit
434 you pass:
435 # only width is limited
437 Imager->set_file_limits(reset=>1, width=>100);
438 # only bytes is limited
440 Imager->set_file_limits(reset=>1, bytes=>10_000_000);
441 get_file_limits()
443 You can get the current limits with the get_file_limits() method:
444 my ($max_width, $max_height, $max_bytes) =
446 Imager->get_file_limits();
447 check_file_limits()
449 Intended for use by file handlers to check that the size of a file
450 is within the limits set by "set_file_limits()".
451 Parameters:
453 • "width", "height" - the width and height of the image in
455 pixels. Must be a positive integer. Required.
456 • "channels" - the number of channels in the image, including the
458 alpha channel if any. Must be a positive integer between 1 and
459 4 inclusive. Default: 3.
460 • "sample_size" - the number of bytes stored per sample. Must be
462 a positive integer or "float". Note that this should be the
463 sample size of the Imager image you will be creating, not the
464 sample size in the source, eg. if the source has 32-bit samples
465 this should be "float" since Imager doesn't have 32-bit/sample
466 images.
467
469 The different image formats can write different image type, and some
470 have different options to control how the images are written.
471 When you call "write()" or "write_multi()" with an option that has the
473 same name as a tag for the image format you're writing, then the value
474 supplied to that option will be used to set the corresponding tag in
475 the image. Depending on the image format, these values will be used
476 when writing the image.
477 This replaces the previous options that were used when writing GIF
479 images. Currently if you use an obsolete option, it will be converted
480 to the equivalent tag and Imager will produced a warning. You can
481 suppress these warnings by calling the "Imager::init()" function with
482 the "warn_obsolete" option set to false:
483 Imager::init(warn_obsolete=>0);
485 At some point in the future these obsolete options will no longer be
487 supported.
488 PNM (Portable aNy Map)
490 Imager can write "PGM" (Portable Gray Map) and "PPM" (Portable PixMaps)
491 files, depending on the number of channels in the image. Currently the
492 images are written in binary formats. Only 1 and 3 channel images can
493 be written, including 1 and 3 channel paletted images.
494 $img->write(file=>'foo.ppm') or die $img->errstr;
496 Imager can read both the ASCII and binary versions of each of the "PBM"
498 (Portable BitMap), "PGM" and "PPM" formats.
499 $img->read(file=>'foo.ppm') or die $img->errstr;
501 PNM does not support the spatial resolution tags.
503 The following tags are set when reading a PNM file:
505 • "pnm_maxval" - the "maxvals" number from the PGM/PPM header.
507 Always set to 2 for a "PBM" file.
508 • "pnm_type" - the type number from the "PNM" header, 1 for ASCII
510 "PBM" files, 2 for ASCII "PGM" files, 3 for ASCII c<PPM> files, 4
511 for binary "PBM" files, 5 for binary "PGM" files, 6 for binary
512 "PPM" files.
513 The following tag is checked when writing an image with more than
515 8-bits/sample:
516 • pnm_write_wide_data - if this is non-zero then write() can write
518 "PGM"/"PPM" files with 16-bits/sample. Some applications, for
519 example GIMP 2.2, and tools can only read 8-bit/sample binary PNM
520 files, so Imager will only write a 16-bit image when this tag is
521 non-zero.
522 JPEG
524 You can supply a "jpegquality" parameter ranging from 0 (worst quality)
525 to 100 (best quality) when writing a JPEG file, which defaults to 75.
526 $img->write(file=>'foo.jpg', jpegquality=>90) or die $img->errstr;
528 If you write an image with an alpha channel to a JPEG file then it will
530 be composed against the background set by the "i_background" parameter
531 (or tag), or black if not supplied.
532 Imager will read a gray scale JPEG as a 1 channel image and a color
534 JPEG as a 3 channel image.
535 $img->read(file=>'foo.jpg') or die $img->errstr;
537 The following tags are set in a JPEG image when read, and can be set to
539 control output:
540 • "jpeg_density_unit" - The value of the density unit field in the
542 "JFIF" header. This is ignored on writing if the "i_aspect_only"
543 tag is non-zero.
544 The "i_xres" and "i_yres" tags are expressed in pixels per inch no
546 matter the value of this tag, they will be converted to/from the
547 value stored in the JPEG file.
548 • "jpeg_density_unit_name" - This is set when reading a JPEG file to
550 the name of the unit given by "jpeg_density_unit". Possible
551 results include "inch", "centimeter", "none" (the "i_aspect_only"
552 tag is also set reading these files). If the value of
553 "jpeg_density_unit" is unknown then this tag isn't set.
554 • "jpeg_comment" - Text comment.
556 • "jpeg_progressive" - Whether the JPEG file is a progressive file.
558 (Imager 0.84)
559 JPEG supports the spatial resolution tags "i_xres", "i_yres" and
561 "i_aspect_only".
562 You can also set the following tags when writing to an image, they are
564 not set in the image when reading:
565 "jpeg_optimize" - set to a non-zero integer to compute optimal
567 Huffman coding tables for the image. This will increase memory
568 usage and processing time (about 12% in my simple tests) but can
569 significantly reduce file size without a loss of quality.
570 If an "APP1" block containing EXIF information is found, then any of
572 the following tags can be set when reading a JPEG image:
573 exif_aperture exif_artist exif_brightness exif_color_space
575 exif_contrast exif_copyright exif_custom_rendered exif_date_time
576 exif_date_time_digitized exif_date_time_original
577 exif_digital_zoom_ratio exif_exposure_bias exif_exposure_index
578 exif_exposure_mode exif_exposure_program exif_exposure_time
579 exif_f_number exif_flash exif_flash_energy exif_flashpix_version
580 exif_focal_length exif_focal_length_in_35mm_film
581 exif_focal_plane_resolution_unit exif_focal_plane_x_resolution
582 exif_focal_plane_y_resolution exif_gain_control
583 exif_image_description exif_image_unique_id exif_iso_speed_rating
584 exif_make exif_max_aperture exif_metering_mode exif_model
585 exif_orientation exif_related_sound_file exif_resolution_unit
586 exif_saturation exif_scene_capture_type exif_sensing_method
587 exif_sharpness exif_shutter_speed exif_software
588 exif_spectral_sensitivity exif_sub_sec_time
589 exif_sub_sec_time_digitized exif_sub_sec_time_original
590 exif_subject_distance exif_subject_distance_range
591 exif_subject_location exif_tag_light_source exif_user_comment
592 exif_version exif_white_balance exif_x_resolution exif_y_resolution
593 The following derived tags can also be set when reading a JPEG image:
595 exif_color_space_name exif_contrast_name exif_custom_rendered_name
597 exif_exposure_mode_name exif_exposure_program_name exif_flash_name
598 exif_focal_plane_resolution_unit_name exif_gain_control_name
599 exif_light_source_name exif_metering_mode_name
600 exif_resolution_unit_name exif_saturation_name
601 exif_scene_capture_type_name exif_sensing_method_name
602 exif_sharpness_name exif_subject_distance_range_name
603 exif_white_balance_name
604 The derived tags are for enumerated fields, when the value for the base
606 field is valid then the text that appears in the EXIF specification for
607 that value appears in the derived field. So for example if
608 "exf_metering_mode" is 5 then "exif_metering_mode_name" is set to
609 "Pattern".
610 eg.
612 my $image = Imager->new;
614 $image->read(file => 'exiftest.jpg')
615 or die "Cannot load image: ", $image->errstr;
616 print $image->tags(name => "exif_image_description"), "\n";
617 print $image->tags(name => "exif_exposure_mode"), "\n";
618 print $image->tags(name => "exif_exposure_mode_name"), "\n";
619 # for the exiftest.jpg in the Imager distribution the output would be:
621 Imager Development Notes
622 0
623 Auto exposure
624 Imager will not write EXIF tags to any type of image, if you need more
626 advanced EXIF handling, consider Image::ExifTool.
627 parseiptc()
629 Historically, Imager saves IPTC data when reading a JPEG image, the
630 parseiptc() method returns a list of key/value pairs resulting from
631 a simple decoding of that data.
632 Any future IPTC data decoding is likely to go into tags.
634 GIF
636 When writing one of more GIF images you can use the same Quantization
637 Options as you can when converting an RGB image into a paletted image.
638 When reading a GIF all of the sub-images are combined using the screen
640 size and image positions into one big image, producing an RGB image.
641 This may change in the future to produce a paletted image where
642 possible.
643 When you read a single GIF with "$img->read()" you can supply a
645 reference to a scalar in the "colors" parameter, if the image is read
646 the scalar will be filled with a reference to an anonymous array of
647 Imager::Color objects, representing the palette of the image. This
648 will be the first palette found in the image. If you want the palettes
649 for each of the images in the file, use "read_multi()" and use the
650 "getcolors()" method on each image.
651 GIF does not support the spatial resolution tags.
653 Imager will set the following tags in each image when reading, and can
655 use most of them when writing to GIF:
656 • gif_left - the offset of the image from the left of the "screen"
658 ("Image Left Position")
659 • gif_top - the offset of the image from the top of the "screen"
661 ("Image Top Position")
662 • gif_interlace - non-zero if the image was interlaced ("Interlace
664 Flag")
665 • gif_screen_width, gif_screen_height - the size of the logical
667 screen. When writing this is used as the minimum. If any image
668 being written would extend beyond this then the screen size is
669 extended. ("Logical Screen Width", "Logical Screen Height").
670 • gif_local_map - Non-zero if this image had a local color map. If
672 set for an image when writing the image is quantized separately
673 from the other images in the file.
674 • gif_background - The index in the global color map of the logical
676 screen's background color. This is only set if the current image
677 uses the global color map. You can set this on write too, but for
678 it to choose the color you want, you will need to supply only
679 paletted images and set the "gif_eliminate_unused" tag to 0.
680 • gif_trans_index - The index of the color in the color map used for
682 transparency. If the image has a transparency then it is returned
683 as a 4 channel image with the alpha set to zero in this palette
684 entry. This value is not used when writing. ("Transparent Color
685 Index")
686 • gif_trans_color - A reference to an Imager::Color object, which is
688 the color to use for the palette entry used to represent
689 transparency in the palette. You need to set the "transp" option
690 (see "Quantization options" in Imager::ImageTypes) for this value
691 to be used.
692 • gif_delay - The delay until the next frame is displayed, in 1/100
694 of a second. ("Delay Time").
695 • gif_user_input - whether or not a user input is expected before
697 continuing (view dependent) ("User Input Flag").
698 • gif_disposal - how the next frame is displayed ("Disposal Method")
700 • gif_loop - the number of loops from the Netscape Loop extension.
702 This may be zero to loop forever.
703 • gif_comment - the first block of the first GIF comment before each
705 image.
706 • gif_eliminate_unused - If this is true, when you write a paletted
708 image any unused colors will be eliminated from its palette. This
709 is set by default.
710 • gif_colormap_size - the original size of the color map for the
712 image. The color map of the image may have been expanded to
713 include out of range color indexes.
714 Where applicable, the ("name") is the name of that field from the
716 "GIF89" standard.
717 The following GIF writing options are obsolete, you should set the
719 corresponding tag in the image, either by using the tags functions, or
720 by supplying the tag and value as options.
721 • gif_each_palette - Each image in the GIF file has it's own palette
723 if this is non-zero. All but the first image has a local color
724 table (the first uses the global color table.
725 Use "gif_local_map" in new code.
727 • interlace - The images are written interlaced if this is non-zero.
729 Use "gif_interlace" in new code.
731 • gif_delays - A reference to an array containing the delays between
733 images, in 1/100 seconds.
734 Use "gif_delay" in new code.
736 • gif_positions - A reference to an array of references to arrays
738 which represent screen positions for each image.
739 New code should use the "gif_left" and "gif_top" tags.
741 • gif_loop_count - If this is non-zero the Netscape loop extension
743 block is generated, which makes the animation of the images repeat.
744 This is currently unimplemented due to some limitations in
746 "giflib".
747 You can supply a "page" parameter to the "read()" method to read some
749 page other than the first. The page is 0 based:
750 # read the second image in the file
752 $image->read(file=>"example.gif", page=>1)
753 or die "Cannot read second page: ",$image->errstr,"\n";
754 Before release 0.46, Imager would read multiple image GIF image files
756 into a single image, overlaying each of the images onto the virtual GIF
757 screen.
758 As of 0.46 the default is to read the first image from the file, as if
760 called with "page => 0".
761 You can return to the previous behavior by calling read with the
763 "gif_consolidate" parameter set to a true value:
764 $img->read(file=>$some_gif_file, gif_consolidate=>1);
766 As with the to_paletted() method, if you supply a colors parameter as a
768 reference to an array, this will be filled with Imager::Color objects
769 of the color table generated for the image file.
770 TIFF (Tagged Image File Format)
772 Imager can write images to either paletted or RGB TIFF images,
773 depending on the type of the source image.
774 When writing direct color images to TIFF the sample size of the output
776 file depends on the input:
777 • double/sample - written as 32-bit/sample TIFF
779 • 16-bit/sample - written as 16-bit/sample TIFF
781 • 8-bit/sample - written as 8-bit/sample TIFF
783 For paletted images:
785 • "$img->is_bilevel" is true - the image is written as bi-level
787 • otherwise - image is written as paletted.
789 If you are creating images for faxing you can set the class parameter
791 set to "fax". By default the image is written in fine mode, but this
792 can be overridden by setting the fax_fine parameter to zero. Since a
793 fax image is bi-level, Imager uses a threshold to decide if a given
794 pixel is black or white, based on a single channel. For gray scale
795 images channel 0 is used, for color images channel 1 (green) is used.
796 If you want more control over the conversion you can use
797 $img->to_paletted() to product a bi-level image. This way you can use
798 dithering:
799 my $bilevel = $img->to_paletted(make_colors => 'mono',
801 translate => 'errdiff',
802 errdiff => 'stucki');
803 • "class" - If set to 'fax' the image will be written as a bi-level
805 fax image.
806 • "fax_fine" - By default when "class" is set to 'fax' the image is
808 written in fine mode, you can select normal mode by setting
809 "fax_fine" to 0.
810 Imager should be able to read any TIFF image you supply. Paletted TIFF
812 images are read as paletted Imager images, since paletted TIFF images
813 have 16-bits/sample (48-bits/color) this means the bottom 8-bits are
814 lost, but this shouldn't be a big deal.
815 TIFF supports the spatial resolution tags. See the
817 "tiff_resolutionunit" tag for some extra options.
818 As of Imager 0.62 Imager reads:
820 • 8-bit/sample gray, RGB or CMYK images, including a possible alpha
822 channel as an 8-bit/sample image.
823 • 16-bit gray, RGB, or CMYK image, including a possible alpha channel
825 as a 16-bit/sample image.
826 • 32-bit gray, RGB image, including a possible alpha channel as a
828 double/sample image.
829 • bi-level images as paletted images containing only black and white,
831 which other formats will also write as bi-level.
832 • tiled paletted images are now handled correctly
834 • other images are read using "tifflib"'s RGBA interface as
836 8-bit/sample images.
837 The following tags are set in a TIFF image when read, and can be set to
839 control output:
840 • "tiff_compression" - When reading an image this is set to the
842 numeric value of the TIFF compression tag.
843 On writing you can set this to either a numeric compression tag
845 value, or one of the following values:
846 Ident Number Description
848 none 1 No compression
849 packbits 32773 Macintosh RLE
850 ccittrle 2 CCITT RLE
851 fax3 3 CCITT Group 3 fax encoding (T.4)
852 t4 3 As above
853 fax4 4 CCITT Group 4 fax encoding (T.6)
854 t6 4 As above
855 lzw 5 LZW
856 jpeg 7 JPEG
857 zip 8 Deflate (GZIP) Non-standard
858 deflate 8 As above.
859 oldzip 32946 Deflate with an older code.
860 ccittrlew 32771 Word aligned CCITT RLE
861 In general a compression setting will be ignored where it doesn't
863 make sense, eg. "jpeg" will be ignored for compression if the image
864 is being written as bilevel.
865 Imager attempts to check that your build of "libtiff" supports the
867 given compression, and will fallback to "packbits" if it isn't
868 enabled. eg. older distributions didn't include LZW compression,
869 and JPEG compression is only available if "libtiff" is configured
870 with "libjpeg"'s location.
871 $im->write(file => 'foo.tif', tiff_compression => 'lzw')
873 or die $im->errstr;
874 • "tags, tiff_jpegquality""tiff_jpegquality" - If "tiff_compression"
876 is "jpeg" then this can be a number from 1 to 100 giving the JPEG
877 compression quality. High values are better quality and larger
878 files.
879 • "tiff_resolutionunit" - The value of the "ResolutionUnit" tag.
881 This is ignored on writing if the i_aspect_only tag is non-zero.
882 The "i_xres" and "i_yres" tags are expressed in pixels per inch no
884 matter the value of this tag, they will be converted to/from the
885 value stored in the TIFF file.
886 • "tiff_resolutionunit_name" - This is set when reading a TIFF file
888 to the name of the unit given by "tiff_resolutionunit". Possible
889 results include "inch", "centimeter", "none" (the "i_aspect_only"
890 tag is also set reading these files) or "unknown".
891 • "tiff_bitspersample" - Bits per sample from the image. This value
893 is not used when writing an image, it is only set on a read image.
894 • "tiff_photometric" - Value of the "PhotometricInterpretation" tag
896 from the image. This value is not used when writing an image, it
897 is only set on a read image.
898 • "tiff_documentname", "tiff_imagedescription", "tiff_make",
900 "tiff_model", "tiff_pagename", "tiff_software", "tiff_datetime",
901 "tiff_artist", "tiff_hostcomputer" - Various strings describing the
902 image. "tiff_datetime" must be formatted as "YYYY:MM:DD HH:MM:SS".
903 These correspond directly to the mixed case names in the TIFF
904 specification. These are set in images read from a TIFF and saved
905 when writing a TIFF image.
906 You can supply a "page" parameter to the "read()" method to read some
908 page other than the first. The page is 0 based:
909 # read the second image in the file
911 $image->read(file=>"example.tif", page=>1)
912 or die "Cannot read second page: ",$image->errstr,"\n";
913 If you read an image with multiple alpha channels, then only the first
915 alpha channel will be read.
916 When reading a "TIFF" image with callbacks, the "seekcb" callback
918 parameter is also required.
919 When writing a "TIFF" image with callbacks, the "seekcb" and "readcb"
921 parameters are also required.
922 "TIFF" is a random access file format, it cannot be read from or
924 written to unseekable streams such as pipes or sockets.
925 BMP (Windows Bitmap)
927 Imager can write 24-bit RGB, and 8, 4 and 1-bit per pixel paletted
928 Windows BMP files. Currently you cannot write compressed BMP files
929 with Imager.
930 Imager can read 24-bit RGB, and 8, 4 and 1-bit perl pixel paletted
932 Windows BMP files. There is some support for reading 16-bit per pixel
933 images, but I haven't found any for testing.
934 BMP has no support for multiple image files.
936 BMP files support the spatial resolution tags, but since BMP has no
938 support for storing only an aspect ratio, if "i_aspect_only" is set
939 when you write the "i_xres" and "i_yres" values are scaled so the
940 smaller is 72 DPI.
941 The following tags are set when you read an image from a BMP file:
943 bmp_compression
945 The type of compression, if any. This can be any of the following
946 values:
947 BI_RGB (0)
949 Uncompressed.
950 BI_RLE8 (1)
952 8-bits/pixel paletted value RLE compression.
953 BI_RLE4 (2)
955 4-bits/pixel paletted value RLE compression.
956 BI_BITFIELDS (3)
958 Packed RGB values.
959 bmp_compression_name
961 The bmp_compression value as a BI_* string
962 bmp_important_colors
964 The number of important colors as defined by the writer of the
965 image.
966 bmp_used_colors
968 Number of color used from the BMP header
969 bmp_filesize
971 The file size from the BMP header
972 bmp_bit_count
974 Number of bits stored per pixel. (24, 8, 4 or 1)
975 TGA (Targa)
977 When storing Targa images RLE compression can be activated with the
978 "compress" parameter, the "idstring" parameter can be used to set the
979 Targa comment field and the "wierdpack" option can be used to use the
980 15 and 16 bit Targa formats for RGB and RGBA data. The 15 bit format
981 has 5 of each red, green and blue. The 16 bit format in addition
982 allows 1 bit of alpha. The most significant bits are used for each
983 channel.
984 Tags:
986 tga_idstring
988 tga_bitspp
989 compressed
990 RAW
992 When reading raw images you need to supply the width and height of the
993 image in the "xsize" and "ysize" options:
994 $img->read(file=>'foo.raw', xsize=>100, ysize=>100)
996 or die "Cannot read raw image\n";
997 If your input file has more channels than you want, or (as is common),
999 junk in the fourth channel, you can use the "raw_datachannels" and
1000 "raw_storechannels" options to control the number of channels in your
1001 input file and the resulting channels in your image. For example, if
1002 your input image uses 32-bits per pixel with red, green, blue and junk
1003 values for each pixel you could do:
1004 $img->read(file=>'foo.raw', xsize => 100, ysize => 100,
1006 raw_datachannels => 4, raw_storechannels => 3,
1007 raw_interleave => 0)
1008 or die "Cannot read raw image\n";
1009 In general, if you supply "raw_storechannels" you should also supply
1011 "raw_datachannels"
1012 Read parameters:
1014 • "raw_interleave" - controls the ordering of samples within the
1016 image. Default: 1. Alternatively and historically spelled
1017 "interleave". Possible values:
1018 • 0 - samples are pixel by pixel, so all samples for the first
1020 pixel, then all samples for the second pixel and so on. eg.
1021 for a four pixel scan line the channels would be laid out as:
1022 012012012012
1024 • 1 - samples are line by line, so channel 0 for the entire scan
1026 line is followed by channel 1 for the entire scan line and so
1027 on. eg. for a four pixel scan line the channels would be laid
1028 out as:
1029 000011112222
1031 This is the default.
1033 Unfortunately, historically, the default "raw_interleave" for read
1035 has been 1, while writing only supports the "raw_interleave" = 0
1036 format.
1037 For future compatibility, you should always supply the
1039 "raw_interleave" (or "interleave") parameter. As of 0.68, Imager
1040 will warn if you attempt to read a raw image without a
1041 "raw_interleave" parameter.
1042 • "raw_storechannels" - the number of channels to store in the image.
1044 Range: 1 to 4. Default: 3. Alternatively and historically spelled
1045 "storechannels".
1046 • "raw_datachannels" - the number of channels to read from the file.
1048 Range: 1 or more. Default: 3. Alternatively and historically
1049 spelled "datachannels".
1050 $img->read(file=>'foo.raw', xsize=100, ysize=>100, raw_interleave=>1)
1052 or die "Cannot read raw image\n";
1053 PNG
1055 PNG Image modes
1056 PNG files can be read and written in the following modes:
1058 • bi-level - written as a 1-bit per sample gray scale image
1060 • paletted - Imager gray scale paletted images are written as RGB
1062 paletted images. PNG palettes can include alpha values for each
1063 entry and this is honored as an Imager four channel paletted image.
1064 • 8 and 16-bit per sample gray scale, optionally with an alpha
1066 channel.
1067 • 8 and 16-bit per sample RGB, optionally with an alpha channel.
1069 Unlike GIF, there is no automatic conversion to a paletted image, since
1071 PNG supports direct color.
1072 PNG Text tags
1074 Text tags are retrieved from and written to PNG "tEXT" or "zTXT"
1076 chunks. The following standard tags from the PNG specification are
1077 directly supported:
1078 • "i_comment" - keyword of "Comment".
1080 • "png_author" - keyword "Author".
1082 • "png_copyright" - keyword "Copyright".
1084 • "png_creation_time" - keyword "Creation Time".
1086 • "png_description" - keyword "Description".
1088 • "png_disclaimer" - keyword "Disclaimer".
1090 • "png_software" - keyword "Software".
1092 • "png_title" - keyword "Title".
1094 • "png_warning" - keyword "Warning".
1096 Each of these tags has a corresponding "base-tag-name_compressed" tag,
1098 eg. "png_comment_compressed". When reading, if the PNG chunk is
1099 compressed this tag will be set to 1, but is otherwise unset. When
1100 writing, Imager will honor the compression tag if set and non-zero,
1101 otherwise the chunk text will be compressed if the value is longer than
1102 1000 characters, as recommended by the "libpng" documentation.
1103 PNG "tEXT" or "zTXT" chunks outside of those above are read into or
1105 written from Imager tags named like:
1106 • "png_textN_key" - the key for the text chunk. This can be 1 to 79
1108 characters, may not contain any leading, trailing or consecutive
1109 spaces, and may contain only Latin-1 characters from 32-126,
1110 161-255.
1111 • "png_textN_text" - the text for the text chunk. This may not
1113 contain any "NUL" characters.
1114 • "png_textN_compressed" - whether or not the text chunk is
1116 compressed. This behaves similarly to the
1117 "base-tag-name_compressed" tags described above.
1118 Where N starts from 0. When writing both the "..._key" and "..._text"
1120 tags must be present or the write will fail. If the key or text do not
1121 satisfy the requirements above the write will fail.
1122 Other PNG metadata tags
1124 • "png_interlace", "png_interlace_name" - only set when reading,
1126 "png_interlace" is set to the type of interlacing used by the file,
1127 0 for one, 1 for Adam7. "png_interlace_name" is set to a keyword
1128 describing the interlacing, either "none" or "adam7".
1129 • "png_srgb_intent" - the sRGB rendering intent for the image. an
1131 integer from 0 to 3, per the PNG specification. If this chunk is
1132 found in the PNG file the "gAMA" and "cHRM" are ignored and the
1133 "png_gamma" and "png_chroma_..." tags are not set. Similarly when
1134 writing if "png_srgb_intent" is set the "gAMA" and "cHRM" chunks
1135 are not written.
1136 • "png_gamma" - the gamma of the image. This value is not currently
1138 used by Imager when processing the image, but this may change in
1139 the future.
1140 • "png_chroma_white_x", "png_chroma_white_y", "png_chroma_red_x",
1142 "png_chroma_red_y", "png_chroma_green_x", "png_chroma_green_y",
1143 "png_chroma_blue_x", "png_chroma_blue_y" - the primary
1144 chromaticities of the image, defining the color model. This is
1145 currently not used by Imager when processing the image, but this
1146 may change in the future.
1147 • "i_xres", "i_yres", "i_aspect_only" - processed per
1149 Imager::ImageTypes/CommonTags.
1150 • "png_bits" - the number of bits per sample in the representation.
1152 Ignored when writing.
1153 • "png_time" - the creation time of the file formatted as
1155 "year-month-dayThour:minute:second". This is stored as time data
1156 structure in the file, not a string. If you set "png_time" and it
1157 cannot be parsed as above, writing the PNG file will fail.
1158 • "i_background" - set from the "sBKG" when reading an image file.
1160 You can control the level of zlib compression used when writing with
1162 the "png_compression_level" parameter. This can be an integer between
1163 0 (uncompressed) and 9 (best compression).
1164 If you're using libpng 1.6 or later, or an earlier release configured
1166 with "PNG_BENIGN_ERRORS_SUPPORTED", you can choose to ignore file
1167 format errors the authors of libpng consider benign, this includes at
1168 least CRC errors and palette index overflows. Do this by supplying a
1169 true value for the "png_ignore_benign_errors" parameter to the read()
1170 method:
1171 $im->read(file => "foo.png", png_ignore_benign_errors => 1)
1173 or die $im->errstr;
1174 ICO (Microsoft Windows Icon) and CUR (Microsoft Windows Cursor)
1176 Icon and Cursor files are very similar, the only differences being a
1177 number in the header and the storage of the cursor hot spot. I've
1178 treated them separately so that you're not messing with tags to
1179 distinguish between them.
1180 The following tags are set when reading an icon image and are used when
1182 writing it:
1183 ico_mask
1185 This is the AND mask of the icon. When used as an icon in Windows
1186 1 bits in the mask correspond to pixels that are modified by the
1187 source image rather than simply replaced by the source image.
1188 Rather than requiring a binary bitmap this is accepted in a
1190 specific format:
1191 • first line consisting of the 0 placeholder, the 1 placeholder
1193 and a newline.
1194 • following lines which contain 0 and 1 placeholders for each
1196 scan line of the image, starting from the top of the image.
1197 When reading an image, '.' is used as the 0 placeholder and '*' as
1199 the 1 placeholder. An example:
1200 .*
1202 ..........................******
1203 ..........................******
1204 ..........................******
1205 ..........................******
1206 ...........................*****
1207 ............................****
1208 ............................****
1209 .............................***
1210 .............................***
1211 .............................***
1212 .............................***
1213 ..............................**
1214 ..............................**
1215 ...............................*
1216 ...............................*
1217 ................................
1218 ................................
1219 ................................
1220 ................................
1221 ................................
1222 ................................
1223 *...............................
1224 **..............................
1225 **..............................
1226 ***.............................
1227 ***.............................
1228 ****............................
1229 ****............................
1230 *****...........................
1231 *****...........................
1232 *****...........................
1233 *****...........................
1234 The following tags are set when reading an icon:
1236 ico_bits
1238 The number of bits per pixel used to store the image.
1239 For cursor files the following tags are set and read when reading and
1241 writing:
1242 cur_mask
1244 This is the same as the ico_mask above.
1245 cur_hotspotx
1247 cur_hotspoty
1248 The "hot" spot of the cursor image. This is the spot on the cursor
1249 that you click with. If you set these to out of range values they
1250 are clipped to the size of the image when written to the file.
1251 The following parameters can be supplied to read() or read_multi() to
1253 control reading of ICO/CUR files:
1254 • "ico_masked" - if true, the default, then the icon/cursors mask is
1256 applied as an alpha channel to the image, unless that image already
1257 has an alpha channel. This may result in a paletted image being
1258 returned as a direct color image. Default: 1
1259 # retrieve the image as stored, without using the mask as an alpha
1261 # channel
1262 $img->read(file => 'foo.ico', ico_masked => 0)
1263 or die $img->errstr;
1264 This was introduced in Imager 0.60. Previously reading ICO images
1266 acted as if "ico_masked => 0".
1267 • "ico_alpha_masked" - if true, then the icon/cursor mask is applied
1269 as an alpha channel to images that already have an alpha mask.
1270 Note that this will only make pixels transparent, not opaque.
1271 Default: 0.
1272 Note: If you get different results between "ico_alpha_masked" being
1274 set to 0 and 1, your mask may break when used with the Win32 API.
1275 "cur_bits" is set when reading a cursor.
1277 Examples:
1279 my $img = Imager->new(xsize => 32, ysize => 32, channels => 4);
1281 $im->box(color => 'FF0000');
1282 $im->write(file => 'box.ico');
1283 $im->settag(name => 'cur_hotspotx', value => 16);
1285 $im->settag(name => 'cur_hotspoty', value => 16);
1286 $im->write(file => 'box.cur');
1287 SGI (RGB, BW)
1289 SGI images, often called by the extensions, RGB or BW, can be stored
1290 either uncompressed or compressed using an RLE compression.
1291 By default, when saving to an extension of "rgb", "bw", "sgi", "rgba"
1293 the file will be saved in SGI format. The file extension is otherwise
1294 ignored, so saving a 3-channel image to a ".bw" file will result in a
1295 3-channel image on disk.
1296 The following tags are set when reading a SGI image:
1298 • i_comment - the "IMAGENAME" field from the image. Also written to
1300 the file when writing.
1301 • sgi_pixmin, sgi_pixmax - the "PIXMIN" and "PIXMAX" fields from the
1303 image. On reading image data is expanded from this range to the
1304 full range of samples in the image.
1305 • sgi_bpc - the number of bytes per sample for the image. Ignored
1307 when writing.
1308 • sgi_rle - whether or not the image is compressed. If this is non-
1310 zero when writing the image will be compressed.
1311
1313 To support a new format for reading, call the register_reader() class
1314 method:
1315 register_reader()
1317 Registers single or multiple image read functions.
1318 Parameters:
1320 • type - the identifier of the file format, if Imager's
1322 i_test_format_probe() can identify the format then this value
1323 should match i_test_format_probe()'s result.
1324 This parameter is required.
1326 • single - a code ref to read a single image from a file. This
1328 is supplied:
1329 • the object that read() was called on,
1331 • an Imager::IO object that should be used to read the file,
1333 and
1334 • all the parameters supplied to the read() method.
1336 The single parameter is required.
1338 • multiple - a code ref which is called to read multiple images
1340 from a file. This is supplied:
1341 • an Imager::IO object that should be used to read the file,
1343 and
1344 • all the parameters supplied to the read_multi() method.
1346 Example:
1348 # from Imager::File::ICO
1350 Imager->register_reader
1351 (
1352 type=>'ico',
1353 single =>
1354 sub {
1355 my ($im, $io, %hsh) = @_;
1356 $im->{IMG} = i_readico_single($io, $hsh{page} || 0);
1357 unless ($im->{IMG}) {
1359 $im->_set_error(Imager->_error_as_msg);
1360 return;
1361 }
1362 return $im;
1363 },
1364 multiple =>
1365 sub {
1366 my ($io, %hsh) = @_;
1367 my @imgs = i_readico_multi($io);
1369 unless (@imgs) {
1370 Imager->_set_error(Imager->_error_as_msg);
1371 return;
1372 }
1373 return map {
1374 bless { IMG => $_, DEBUG => $Imager::DEBUG, ERRSTR => undef }, 'Imager'
1375 } @imgs;
1376 },
1377 );
1378 register_writer()
1380 Registers single or multiple image write functions.
1381 Parameters:
1383 • type - the identifier of the file format. This is typically
1385 the extension in lowercase.
1386 This parameter is required.
1388 • single - a code ref to write a single image to a file. This is
1390 supplied:
1391 • the object that write() was called on,
1393 • an Imager::IO object that should be used to write the file,
1395 and
1396 • all the parameters supplied to the write() method.
1398 The single parameter is required.
1400 • multiple - a code ref which is called to write multiple images
1402 to a file. This is supplied:
1403 • the class name write_multi() was called on, this is
1405 typically "Imager".
1406 • an Imager::IO object that should be used to write the file,
1408 and
1409 • all the parameters supplied to the read_multi() method.
1411 add_type_extensions($type, $ext, ...)
1413 This class method can be used to add extensions to the map used by
1414 "def_guess_type" when working out the file type a filename
1415 extension.
1416 Imager->add_type_extension(mytype => "mytype", "mytypish");
1418 ...
1419 $im->write(file => "foo.mytypish") # use the mytype handler
1420 If you name the reader module "Imager::File::"your-format-name where
1422 your-format-name is a fully upper case version of the type value you
1423 would pass to read(), read_multi(), write() or write_multi() then
1424 Imager will attempt to load that module if it has no other way to read
1425 or write that format.
1426 For example, if you create a module Imager::File::GIF and the user has
1428 built Imager without it's normal GIF support then an attempt to read a
1429 GIF image will attempt to load Imager::File::GIF.
1430 If your module can only handle reading then you can name your module
1432 "Imager::File::"your-format-name"Reader" and Imager will attempt to
1433 autoload it.
1434 If your module can only handle writing then you can name your module
1436 "Imager::File::"your-format-name"Writer" and Imager will attempt to
1437 autoload it.
1438
1440 preload()
1441 This preloads the file support modules included with or that have
1442 been included with Imager in the past. This is intended for use in
1443 forking servers such as mod_perl.
1444 If the module is not available no error occurs.
1446 Preserves $@.
1448 use Imager;
1450 Imager->preload;
1451
1453 Producing an image from a CGI script
1454 Once you have an image the basic mechanism is:
1455 1. set STDOUT to autoflush
1457 2. output a content-type header, and optionally a content-length
1459 header
1460 3. put STDOUT into binmode
1462 4. call write() with the "fd" or "fh" parameter. You will need to
1464 provide the "type" parameter since Imager can't use the extension
1465 to guess the file format you want.
1466 # write an image from a CGI script
1468 # using CGI.pm
1469 use CGI qw(:standard);
1470 $| = 1;
1471 binmode STDOUT;
1472 print header(-type=>'image/gif');
1473 $img->write(type=>'gif', fd=>fileno(STDOUT))
1474 or die $img->errstr;
1475 If you want to send a content length you can send the output to a
1477 scalar to get the length:
1478 my $data;
1480 $img->write(type=>'gif', data=>\$data)
1481 or die $img->errstr;
1482 binmode STDOUT;
1483 print header(-type=>'image/gif', -content_length=>length($data));
1484 print $data;
1485 Writing an animated GIF
1487 The basic idea is simple, just use write_multi():
1488 my @imgs = ...;
1490 Imager->write_multi({ file=>$filename, type=>'gif' }, @imgs);
1491 If your images are RGB images the default quantization mechanism will
1493 produce a very good result, but can take a long time to execute. You
1494 could either use the standard web color map:
1495 Imager->write_multi({ file=>$filename,
1497 type=>'gif',
1498 make_colors=>'webmap' },
1499 @imgs);
1500 or use a median cut algorithm to built a fairly optimal color map:
1502 Imager->write_multi({ file=>$filename,
1504 type=>'gif',
1505 make_colors=>'mediancut' },
1506 @imgs);
1507 By default all of the images will use the same global color map, which
1509 will produce a smaller image. If your images have significant color
1510 differences, you may want to generate a new palette for each image:
1511 Imager->write_multi({ file=>$filename,
1513 type=>'gif',
1514 make_colors=>'mediancut',
1515 gif_local_map => 1 },
1516 @imgs);
1517 which will set the "gif_local_map" tag in each image to 1.
1519 Alternatively, if you know only some images have different colors, you
1520 can set the tag just for those images:
1521 $imgs[2]->settag(name=>'gif_local_map', value=>1);
1523 $imgs[4]->settag(name=>'gif_local_map', value=>1);
1524 and call write_multi() without a "gif_local_map" parameter, or supply
1526 an arrayref of values for the tag:
1527 Imager->write_multi({ file=>$filename,
1529 type=>'gif',
1530 make_colors=>'mediancut',
1531 gif_local_map => [ 0, 0, 1, 0, 1 ] },
1532 @imgs);
1533 Other useful parameters include "gif_delay" to control the delay
1535 between frames and "transp" to control transparency.
1536 Reading tags after reading an image
1538 This is pretty simple:
1539 # print the author of a TIFF, if any
1541 my $img = Imager->new;
1542 $img->read(file=>$filename, type='tiff') or die $img->errstr;
1543 my $author = $img->tags(name=>'tiff_author');
1544 if (defined $author) {
1545 print "Author: $author\n";
1546 }
1547
1549 When saving GIF images the program does NOT try to shave off extra
1550 colors if it is possible. If you specify 128 colors and there are only
1551 2 colors used - it will have a 128 color table anyway.
1552
1554 Imager(3)
1555
1557 Tony Cook <tonyc@cpan.org>, Arnar M. Hrafnkelsson
1558perl v5.32.1 2021-01-27 Imager::Files(3)