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 open my $fh, "+>:raw", ... ;
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 Support for other formats can be found on CPAN, including:
171 heif/heic Imager::File::HEIF
173 qoi Imager::File::QOI
174 webp Imager::File::WEBP
175 When you read an image, Imager may set some tags, possibly including
177 information about the spatial resolution, textual information, and
178 animation information. See "Tags" in Imager::ImageTypes for specifics.
179 The open() method is a historical alias for the read() method.
181 Input and output
183 When reading or writing you can specify one of a variety of sources or
184 targets:
185 • "file" - The "file" parameter is the name of the image file to be
187 written to or read from. If Imager recognizes the extension of the
188 file you do not need to supply a "type".
189 # write in tiff format
191 $image->write(file => "example.tif")
192 or die $image->errstr;
193 $image->write(file => 'foo.tmp', type => 'tiff')
195 or die $image->errstr;
196 my $image = Imager->new;
198 $image->read(file => 'example.tif')
199 or die $image->errstr;
200 • "fh" - "fh" is a file handle, typically returned from an "open"
202 call. You should call "binmode" on the handle before passing it to
203 Imager.
204 Imager will set the handle to autoflush to make sure any buffered
206 data is flushed , since Imager will write to the file descriptor
207 (from fileno()) rather than writing at the perl level.
208 $image->write(fh => \*STDOUT, type => 'gif')
210 or die $image->errstr;
211 # for example, a file uploaded via CGI.pm
213 $image->read(fd => $cgi->param('file'))
214 or die $image->errstr;
215 • "fd" - "fd" is a file descriptor. You can get this by calling the
217 "fileno()" function on a file handle, or by using one of the
218 standard file descriptor numbers.
219 If you get this from a perl file handle, you may need to flush any
221 buffered output, otherwise it may appear in the output stream after
222 the image.
223 $image->write(fd => file(STDOUT), type => 'gif')
225 or die $image->errstr;
226 • "data" - When reading data, "data" is a scalar containing the image
228 file data, or a reference to such a scalar. When writing, "data"
229 is a reference to the scalar to save the image file data to.
230 my $data;
232 $image->write(data => \$data, type => 'tiff')
233 or die $image->errstr;
234 my $data = $row->{someblob}; # eg. from a database
236 my @images = Imager->read_multi(data => $data)
237 or die Imager->errstr;
238 # from Imager 0.99
240 my @images = Imager->read_multi(data => \$data)
241 or die Imager->errstr;
242 • "callback", "readcb", "writecb", "seekcb", "closecb" - Imager will
244 make calls back to your supplied coderefs to read, write and seek
245 from/to/through the image file. See "I/O Callbacks" below for
246 details.
247 • "io" - an Imager::IO object.
249 By default Imager will use buffered I/O when reading or writing an
251 image. You can disabled buffering for output by supplying a "buffered
252 => 0" parameter to "write()" or "write_multi()".
253 I/O Callbacks
255 When reading from a file you can use either "callback" or "readcb" to
256 supply the read callback, and when writing "callback" or "writecb" to
257 supply the write callback.
258 Whether reading or writing a "TIFF" image, "seekcb" and "readcb" are
260 required.
261 If a file handler attempts to use "readcb", "writecb" or "seekcb" and
263 you haven't supplied one, the call will fail, failing the image read or
264 write, returning an error message indicating that the callback is
265 missing:
266 # attempting to read a TIFF image without a seekcb
268 open my $fh, "<", $filename or die;
269 my $rcb = sub {
270 my $val;
271 read($fh, $val, $_[0]) or return "";
272 return $val;
273 };
274 my $im = Imager->new(callback => $rcb)
275 or die Imager->errstr
276 # dies with (wrapped here):
277 # Error opening file: (Iolayer): Failed to read directory at offset 0:
278 # (Iolayer): Seek error accessing TIFF directory: seek callback called
279 # but no seekcb supplied
280 You can also provide a "closecb" parameter called when writing the file
282 is complete. If no "closecb" is supplied the default will succeed
283 silently.
284 # contrived
286 my $data;
287 sub mywrite {
288 $data .= unpack("H*", shift);
289 1;
290 }
291 Imager->write_multi({ callback => \&mywrite, type => 'gif'}, @images)
292 or die Imager->errstr;
293 "readcb"
295 The read callback is called with 2 parameters:
297 • "size" - the minimum amount of data required.
299 • "maxsize" - previously this was the maximum amount of data
301 returnable - currently it's always the same as "size"
302 Your read callback should return the data as a scalar:
304 • on success, a string containing the bytes read.
306 • on end of file, an empty string
308 • on error, "undef".
310 If your return value contains more data than "size" Imager will panic.
312 Your return value must not contain any characters over "\xFF" or Imager
314 will panic.
315 "writecb"
317 Your write callback takes exactly one parameter, a scalar containing
319 the data to be written.
320 Return true for success.
322 "seekcb"
324 The seek callback takes 2 parameters, a POSITION, and a WHENCE, defined
326 in the same way as perl's seek function.
327 Previously you always needed a "seekcb" callback if you called Imager's
329 "read()" or "read_multi()" without a "type" parameter, but this is no
330 longer necessary unless the file handler requires seeking, such as for
331 TIFF files.
332 Returns the new position in the file, or -1 on failure.
334 "closecb"
336 You can also supply a "closecb" which is called with no parameters when
338 there is no more data to be written. This could be used to flush
339 buffered data.
340 Return true on success.
342 Guessing types
344 When writing to a file, if you don't supply a "type" parameter Imager
345 will attempt to guess it from the file name. This is done by calling
346 the code reference stored in $Imager::FORMATGUESS. This is only done
347 when write() or write_multi() is called with a "file" parameter, or if
348 read() or read_multi() can't determine the type from the file's header.
349 The default function value of $Imager::FORMATGUESS is
351 "\&Imager::def_guess_type".
352 def_guess_type()
354 This is the default function Imager uses to derive a file type from
355 a file name. This is a function, not a method.
356 Accepts a single parameter, the file name and returns the type or
358 undef.
359 You can replace function with your own implementation if you have some
361 specialized need. The function takes a single parameter, the name of
362 the file, and should return either a file type or under.
363 # I'm writing jpegs to weird filenames
365 local $Imager::FORMATGUESS = sub { 'jpeg' };
366 When reading a file Imager examines beginning of the file for
368 identifying information. The current implementation attempts to detect
369 the following image types beyond those supported by Imager:
370 "xpm", "mng", "jng", "ilbm", "pcx", "fits", "psd" (Photoshop),
372 "eps", Utah "RLE".
373 You can now add to the magic database Imager uses for detecting file
375 types:
376 add_file_magic()
378 Imager->add_file_magic(name => $name, bits => $bits, mask => $mask)
379 Adds to list of magic, the parameters are all required. The
381 parameters are:
382 • "name" - the file type name to return on match.
384 • "bits" - a binary string to match.
386 • "mask" - a mask controlling which parts of bits are
388 significant.
389 While mask is mostly a bit mask, some byte values are translated,
391 the space character is treated as all zeros ("\x00"), and the "x"
392 character as all ones ("\xFF").
393 New magic entries take priority over old entries.
395 You can add more than one magic entry for a given name.
397 Imager->add_file_magic(name => "heif",
399 bits => " ftypheif"
400 mask => " xxxxxxxx");
401 Limiting the sizes of images you read
403 set_file_limits()
404 In some cases you will be receiving images from an untested source,
405 such as submissions via CGI. To prevent such images from consuming
406 large amounts of memory, you can set limits on the dimensions of
407 images you read from files:
408 • width - limit the width in pixels of the image
410 • height - limit the height in pixels of the image
412 • bytes - limits the amount of storage used by the image. This
414 depends on the width, height, channels and sample size of the
415 image. For paletted images this is calculated as if the image
416 was expanded to a direct color image.
417 To set the limits, call the class method set_file_limits:
419 Imager->set_file_limits(width=>$max_width, height=>$max_height);
421 You can pass any or all of the limits above, any limits you do not
423 pass are left as they were.
424 Any limit of zero for width or height is treated as unlimited.
426 A limit of zero for bytes is treated as one gigabyte, but higher
428 bytes limits can be set explicitly.
429 By default, the width and height limits are zero, or unlimited.
431 The default memory size limit is one gigabyte.
432 You can reset all limits to their defaults with the reset
434 parameter:
435 # no limits
437 Imager->set_file_limits(reset=>1);
438 This can be used with the other limits to reset all but the limit
440 you pass:
441 # only width is limited
443 Imager->set_file_limits(reset=>1, width=>100);
444 # only bytes is limited
446 Imager->set_file_limits(reset=>1, bytes=>10_000_000);
447 get_file_limits()
449 You can get the current limits with the get_file_limits() method:
450 my ($max_width, $max_height, $max_bytes) =
452 Imager->get_file_limits();
453 check_file_limits()
455 Intended for use by file handlers to check that the size of a file
456 is within the limits set by "set_file_limits()".
457 Parameters:
459 • "width", "height" - the width and height of the image in
461 pixels. Must be a positive integer. Required.
462 • "channels" - the number of channels in the image, including the
464 alpha channel if any. Must be a positive integer between 1 and
465 4 inclusive. Default: 3.
466 • "sample_size" - the number of bytes stored per sample. Must be
468 a positive integer or "float". Note that this should be the
469 sample size of the Imager image you will be creating, not the
470 sample size in the source, eg. if the source has 32-bit samples
471 this should be "float" since Imager doesn't have 32-bit/sample
472 images.
473
475 The different image formats can write different image type, and some
476 have different options to control how the images are written.
477 When you call "write()" or "write_multi()" with an option that has the
479 same name as a tag for the image format you're writing, then the value
480 supplied to that option will be used to set the corresponding tag in
481 the image. Depending on the image format, these values will be used
482 when writing the image.
483 This replaces the previous options that were used when writing GIF
485 images. Currently if you use an obsolete option, it will be converted
486 to the equivalent tag and Imager will produced a warning. You can
487 suppress these warnings by calling the "Imager::init()" function with
488 the "warn_obsolete" option set to false:
489 Imager::init(warn_obsolete=>0);
491 At some point in the future these obsolete options will no longer be
493 supported.
494 PNM (Portable aNy Map)
496 Imager can write "PGM" (Portable Gray Map) and "PPM" (Portable PixMaps)
497 files, depending on the number of channels in the image. Currently the
498 images are written in binary formats. Only 1 and 3 channel images can
499 be written, including 1 and 3 channel paletted images.
500 $img->write(file=>'foo.ppm') or die $img->errstr;
502 Imager can read both the ASCII and binary versions of each of the "PBM"
504 (Portable BitMap), "PGM" and "PPM" formats.
505 $img->read(file=>'foo.ppm') or die $img->errstr;
507 PNM does not support the spatial resolution tags.
509 The following tags are set when reading a PNM file:
511 • "pnm_maxval" - the "maxvals" number from the PGM/PPM header.
513 Always set to 2 for a "PBM" file.
514 • "pnm_type" - the type number from the "PNM" header, 1 for ASCII
516 "PBM" files, 2 for ASCII "PGM" files, 3 for ASCII c<PPM> files, 4
517 for binary "PBM" files, 5 for binary "PGM" files, 6 for binary
518 "PPM" files.
519 The following tag is checked when writing an image with more than
521 8-bits/sample:
522 • pnm_write_wide_data - if this is non-zero then write() can write
524 "PGM"/"PPM" files with 16-bits/sample. Some applications, for
525 example GIMP 2.2, and tools can only read 8-bit/sample binary PNM
526 files, so Imager will only write a 16-bit image when this tag is
527 non-zero.
528 JPEG
530 You can supply a "jpegquality" parameter ranging from 0 (worst quality)
531 to 100 (best quality) when writing a JPEG file, which defaults to 75.
532 $img->write(file=>'foo.jpg', jpegquality=>90) or die $img->errstr;
534 If you write an image with an alpha channel to a JPEG file then it will
536 be composed against the background set by the "i_background" parameter
537 (or tag), or black if not supplied.
538 Imager will read a gray scale JPEG as a 1 channel image and a color
540 JPEG as a 3 channel image.
541 $img->read(file=>'foo.jpg') or die $img->errstr;
543 The following tags are set in a JPEG image when read, and can be set to
545 control output:
546 • "jpeg_density_unit" - The value of the density unit field in the
548 "JFIF" header. This is ignored on writing if the "i_aspect_only"
549 tag is non-zero.
550 The "i_xres" and "i_yres" tags are expressed in pixels per inch no
552 matter the value of this tag, they will be converted to/from the
553 value stored in the JPEG file.
554 • "jpeg_density_unit_name" - This is set when reading a JPEG file to
556 the name of the unit given by "jpeg_density_unit". Possible
557 results include "inch", "centimeter", "none" (the "i_aspect_only"
558 tag is also set reading these files). If the value of
559 "jpeg_density_unit" is unknown then this tag isn't set.
560 • "jpeg_comment" - Text comment.
562 • "jpeg_progressive" - Whether the JPEG file is a progressive file.
564 (Imager 0.84)
565 JPEG supports the spatial resolution tags "i_xres", "i_yres" and
567 "i_aspect_only".
568 You can also set the following tags when writing to an image, they are
570 not set in the image when reading:
571 • "jpeg_optimize" - set to a non-zero integer to compute optimal
573 Huffman coding tables for the image. This will increase memory
574 usage and processing time (about 12% in my simple tests) but can
575 significantly reduce file size without a loss of quality.
576 • "jpeg_compress_profile" - set to either "fastest", the default, or
578 only with "MozJPEG", to "max". Setting this to any other value
579 will cause an error, failing the write() call. Setting this to
580 "max" without "MozJPEG" will cause an error.
581 use Imager::File::JPEG;
583 my $prof = Imager::File::JPEG->is_mozjpeg ? "max" : "fastest";
584 $im->write(file => "foo.jpeg", jpeg_compress_profile => $prof)
585 or die $im->errstr;
586 Note that unlike "MozJPEG", Imager always defaults to "fastest".
588 • "jpeg_tune" - corresponds to the "MozJPEG" "cjpeg" "-tune"
590 parameters, this can be any of:
591 • "psnr"
593 • "ssim"
595 • "ms-ssim"
597 • "hvs-psnr"
599 These set the same values as the "jpeg_base_quant_tbl_idx",
601 "jpeg_lambda_log_scale1", "jpeg_lambda_log_scale2" and
602 "jpeg_use_lambda_weight_tbl" tags, which can override the values
603 set by "jpeg_tune".
604 Unlike "cjpeg" "-tune", "jpeg_tune" doesn't force the quality to
606 75.
607 Requires that Imager::File::JPEG was built with "MozJPEG".
609 • "jpeg_arithmetic" - if set to non-zero, use arithmetic coding when
611 writing the image. This requires that the "libjpeg" variant that
612 Imager::File::JPEG was built with had encode support for arithmetic
613 coding enabled when it was built.
614 •
616 "jpeg_jfif" - if set to zero, disable writing the JFIF header even
619 if one is technically required, which it is for the color spaces
620 Imager works with. This saves 18 bytes in the output file and most
621 applications including web browsers will successfully read the
622 file, but your experience may differ.
623 This will prevent the "i_xres", "i_yres" and "jpeg_density_units"
625 tags from having an effect.
626 • "jpeg_smooth" - if set to a value from 1 to 100 apply smoothing to
628 the image to eliminate dithering noise (without modifying the
629 Imager image). Default: 0 (no smoothing).
630 •
632 "jpeg_restart" - if set to a plain integer "N", generate a JPEG
635 restart marker every "N" rows, if set to an integer followed by
636 "B", generate a JPEG restart marker every "N" MCUs, the 8x8 pixel
637 blocks that make up a JPEG image. Note that if this is specified
638 in rows it will be translated to MCUs by "libjpeg".
639 This allows a decoder to recover from corruption, but it makes the
641 file slightly larger.
642 Default: 0, no restart markers are produced.
644 •
646 "jpeg_sample" - control subsampling of the YCbCr components,
649 equivalent to the "-sample" parameter for "cjpeg".
650 Default: "2x2,1x1,1x1", default 4:2:0 JPEG subsampling.
652 The following options can be set on writing with "MozJPEG" and
654 correspond directly to the API options described in the "MozJPEG"
655 README-mozilla.txt. Attempting to set them when Imager::File::JPEG has
656 been built with another "libjpeg" will result in an error.
657 • "jpeg_optimize_scans", "jpeg_trellis_quant",
659 "jpeg_trellis_quant_dc", "jpeg_tresllis_eob_opt",
660 "jpeg_use_lambda_weight_tbl", "jpeg_use_scans_in_trellis",
661 "jpeg_overshoot_deringing" - boolean options, set to 0 or 1.
662 "jpeg_lambda_log_scale1", "jpeg_lambda_log_scale2",
664 "jpeg_trellis_delta_dc_weight" - integer options.
665 "jpeg_trellis_freq_split", "jpeg_trellis_num_loops",
667 "jpeg_base_quant_tbl_idx", "jpeg_dc_scan_opt_mode" - floating point
668 options.
669 When reading a JPEG image, the following tag will be set, and ignored
671 on writing:
672 • "jpeg_read_arithmetic" - the image had been written with arithmetic
674 coding. This uses a separate name from writing to avoid arithmetic
675 coding from being accidentally propagated to a file that might need
676 to be read by an implementation without arithmetic coding support.
677 If an "APP1" block containing EXIF information is found, then any of
679 the following tags can be set when reading a JPEG image:
680 exif_aperture exif_artist exif_brightness exif_color_space
682 exif_contrast exif_copyright exif_custom_rendered exif_date_time
683 exif_date_time_digitized exif_date_time_original
684 exif_digital_zoom_ratio exif_exposure_bias exif_exposure_index
685 exif_exposure_mode exif_exposure_program exif_exposure_time
686 exif_f_number exif_flash exif_flash_energy exif_flashpix_version
687 exif_focal_length exif_focal_length_in_35mm_film
688 exif_focal_plane_resolution_unit exif_focal_plane_x_resolution
689 exif_focal_plane_y_resolution exif_gain_control
690 exif_image_description exif_image_unique_id exif_iso_speed_rating
691 exif_make exif_max_aperture exif_metering_mode exif_model
692 exif_orientation exif_related_sound_file exif_resolution_unit
693 exif_saturation exif_scene_capture_type exif_sensing_method
694 exif_sharpness exif_shutter_speed exif_software
695 exif_spectral_sensitivity exif_sub_sec_time
696 exif_sub_sec_time_digitized exif_sub_sec_time_original
697 exif_subject_distance exif_subject_distance_range
698 exif_subject_location exif_tag_light_source exif_user_comment
699 exif_version exif_white_balance exif_x_resolution exif_y_resolution
700 The following derived tags can also be set when reading a JPEG image:
702 exif_color_space_name exif_contrast_name exif_custom_rendered_name
704 exif_exposure_mode_name exif_exposure_program_name exif_flash_name
705 exif_focal_plane_resolution_unit_name exif_gain_control_name
706 exif_light_source_name exif_metering_mode_name
707 exif_resolution_unit_name exif_saturation_name
708 exif_scene_capture_type_name exif_sensing_method_name
709 exif_sharpness_name exif_subject_distance_range_name
710 exif_white_balance_name
711 The derived tags are for enumerated fields, when the value for the base
713 field is valid then the text that appears in the EXIF specification for
714 that value appears in the derived field. So for example if
715 "exf_metering_mode" is 5 then "exif_metering_mode_name" is set to
716 "Pattern".
717 eg.
719 my $image = Imager->new;
721 $image->read(file => 'exiftest.jpg')
722 or die "Cannot load image: ", $image->errstr;
723 print $image->tags(name => "exif_image_description"), "\n";
724 print $image->tags(name => "exif_exposure_mode"), "\n";
725 print $image->tags(name => "exif_exposure_mode_name"), "\n";
726 # for the exiftest.jpg in the Imager distribution the output would be:
728 Imager Development Notes
729 0
730 Auto exposure
731 Imager will not write EXIF tags to any type of image, if you need more
733 advanced EXIF handling, consider Image::ExifTool.
734 parseiptc()
736 Historically, Imager saves IPTC data when reading a JPEG image, the
737 parseiptc() method returns a list of key/value pairs resulting from
738 a simple decoding of that data.
739 Any future IPTC data decoding is likely to go into tags.
741 GIF
743 When writing one of more GIF images you can use the same Quantization
744 Options as you can when converting an RGB image into a paletted image.
745 When reading a GIF all of the sub-images are combined using the screen
747 size and image positions into one big image, producing an RGB image.
748 This may change in the future to produce a paletted image where
749 possible.
750 When you read a single GIF with "$img->read()" you can supply a
752 reference to a scalar in the "colors" parameter, if the image is read
753 the scalar will be filled with a reference to an anonymous array of
754 Imager::Color objects, representing the palette of the image. This
755 will be the first palette found in the image. If you want the palettes
756 for each of the images in the file, use "read_multi()" and use the
757 "getcolors()" method on each image.
758 GIF does not support the spatial resolution tags.
760 Imager will set the following tags in each image when reading, and can
762 use most of them when writing to GIF:
763 • gif_left - the offset of the image from the left of the "screen"
765 ("Image Left Position")
766 • gif_top - the offset of the image from the top of the "screen"
768 ("Image Top Position")
769 • gif_interlace - non-zero if the image was interlaced ("Interlace
771 Flag")
772 • gif_screen_width, gif_screen_height - the size of the logical
774 screen. When writing this is used as the minimum. If any image
775 being written would extend beyond this then the screen size is
776 extended. ("Logical Screen Width", "Logical Screen Height").
777 • gif_local_map - Non-zero if this image had a local color map. If
779 set for an image when writing the image is quantized separately
780 from the other images in the file.
781 • gif_background - The index in the global color map of the logical
783 screen's background color. This is only set if the current image
784 uses the global color map. You can set this on write too, but for
785 it to choose the color you want, you will need to supply only
786 paletted images and set the "gif_eliminate_unused" tag to 0.
787 • gif_trans_index - The index of the color in the color map used for
789 transparency. If the image has a transparency then it is returned
790 as a 4 channel image with the alpha set to zero in this palette
791 entry. This value is not used when writing. ("Transparent Color
792 Index")
793 • gif_trans_color - A reference to an Imager::Color object, which is
795 the color to use for the palette entry used to represent
796 transparency in the palette. You need to set the "transp" option
797 (see "Quantization options" in Imager::ImageTypes) for this value
798 to be used.
799 • gif_delay - The delay until the next frame is displayed, in 1/100
801 of a second. ("Delay Time").
802 • gif_user_input - whether or not a user input is expected before
804 continuing (view dependent) ("User Input Flag").
805 • gif_disposal - how the next frame is displayed ("Disposal Method")
807 • gif_loop - the number of loops from the Netscape Loop extension.
809 This may be zero to loop forever.
810 • gif_comment - the first block of the first GIF comment before each
812 image.
813 • gif_eliminate_unused - If this is true, when you write a paletted
815 image any unused colors will be eliminated from its palette. This
816 is set by default.
817 • gif_colormap_size - the original size of the color map for the
819 image. The color map of the image may have been expanded to
820 include out of range color indexes.
821 Where applicable, the ("name") is the name of that field from the
823 "GIF89" standard.
824 The following GIF writing options are obsolete, you should set the
826 corresponding tag in the image, either by using the tags functions, or
827 by supplying the tag and value as options.
828 • gif_each_palette - Each image in the GIF file has it's own palette
830 if this is non-zero. All but the first image has a local color
831 table (the first uses the global color table.
832 Use "gif_local_map" in new code.
834 • interlace - The images are written interlaced if this is non-zero.
836 Use "gif_interlace" in new code.
838 • gif_delays - A reference to an array containing the delays between
840 images, in 1/100 seconds.
841 Use "gif_delay" in new code.
843 • gif_positions - A reference to an array of references to arrays
845 which represent screen positions for each image.
846 New code should use the "gif_left" and "gif_top" tags.
848 • gif_loop_count - If this is non-zero the Netscape loop extension
850 block is generated, which makes the animation of the images repeat.
851 This is currently unimplemented due to some limitations in
853 "giflib".
854 You can supply a "page" parameter to the "read()" method to read some
856 page other than the first. The page is 0 based:
857 # read the second image in the file
859 $image->read(file=>"example.gif", page=>1)
860 or die "Cannot read second page: ",$image->errstr,"\n";
861 Before release 0.46, Imager would read multiple image GIF image files
863 into a single image, overlaying each of the images onto the virtual GIF
864 screen.
865 As of 0.46 the default is to read the first image from the file, as if
867 called with "page => 0".
868 You can return to the previous behavior by calling read with the
870 "gif_consolidate" parameter set to a true value:
871 $img->read(file=>$some_gif_file, gif_consolidate=>1);
873 As with the to_paletted() method, if you supply a colors parameter as a
875 reference to an array, this will be filled with Imager::Color objects
876 of the color table generated for the image file.
877 TIFF (Tagged Image File Format)
879 Imager can write images to either paletted or RGB TIFF images,
880 depending on the type of the source image.
881 When writing direct color images to TIFF the sample size of the output
883 file depends on the input:
884 • double/sample - written as 32-bit/sample TIFF
886 • 16-bit/sample - written as 16-bit/sample TIFF
888 • 8-bit/sample - written as 8-bit/sample TIFF
890 For paletted images:
892 • "$img->is_bilevel" is true - the image is written as bi-level
894 • otherwise - image is written as paletted.
896 If you are creating images for faxing you can set the class parameter
898 set to "fax". By default the image is written in fine mode, but this
899 can be overridden by setting the fax_fine parameter to zero. Since a
900 fax image is bi-level, Imager uses a threshold to decide if a given
901 pixel is black or white, based on a single channel. For gray scale
902 images channel 0 is used, for color images channel 1 (green) is used.
903 If you want more control over the conversion you can use
904 $img->to_paletted() to product a bi-level image. This way you can use
905 dithering:
906 my $bilevel = $img->to_paletted(make_colors => 'mono',
908 translate => 'errdiff',
909 errdiff => 'stucki');
910 • "class" - If set to 'fax' the image will be written as a bi-level
912 fax image.
913 • "fax_fine" - By default when "class" is set to 'fax' the image is
915 written in fine mode, you can select normal mode by setting
916 "fax_fine" to 0.
917 Imager should be able to read any TIFF image you supply. Paletted TIFF
919 images are read as paletted Imager images, since paletted TIFF images
920 have 16-bits/sample (48-bits/color) this means the bottom 8-bits are
921 lost, but this shouldn't be a big deal.
922 TIFF supports the spatial resolution tags. See the
924 "tiff_resolutionunit" tag for some extra options.
925 As of Imager 0.62 Imager reads:
927 • 8-bit/sample gray, RGB or CMYK images, including a possible alpha
929 channel as an 8-bit/sample image.
930 • 16-bit gray, RGB, or CMYK image, including a possible alpha channel
932 as a 16-bit/sample image.
933 • 32-bit gray, RGB image, including a possible alpha channel as a
935 double/sample image.
936 • bi-level images as paletted images containing only black and white,
938 which other formats will also write as bi-level.
939 • tiled paletted images are now handled correctly
941 • other images are read using "tifflib"'s RGBA interface as
943 8-bit/sample images.
944 The following tags are set in a TIFF image when read, and can be set to
946 control output:
947 • "tiff_compression" - When reading an image this is set to the
949 numeric value of the TIFF compression tag.
950 On writing you can set this to either a numeric compression tag
952 value, or one of the following values:
953 Ident Number Description
955 none 1 No compression
956 packbits 32773 Macintosh RLE
957 ccittrle 2 CCITT RLE
958 fax3 3 CCITT Group 3 fax encoding (T.4)
959 t4 3 As above
960 fax4 4 CCITT Group 4 fax encoding (T.6)
961 t6 4 As above
962 lzw 5 LZW
963 jpeg 7 JPEG
964 zip 8 Deflate (GZIP) Non-standard
965 deflate 8 As above.
966 oldzip 32946 Deflate with an older code.
967 ccittrlew 32771 Word aligned CCITT RLE
968 In general a compression setting will be ignored where it doesn't
970 make sense, eg. "jpeg" will be ignored for compression if the image
971 is being written as bilevel.
972 Imager attempts to check that your build of "libtiff" supports the
974 given compression, and will fallback to "packbits" if it isn't
975 enabled. eg. older distributions didn't include LZW compression,
976 and JPEG compression is only available if "libtiff" is configured
977 with "libjpeg"'s location.
978 $im->write(file => 'foo.tif', tiff_compression => 'lzw')
980 or die $im->errstr;
981 • "tags, tiff_jpegquality""tiff_jpegquality" - If "tiff_compression"
983 is "jpeg" then this can be a number from 1 to 100 giving the JPEG
984 compression quality. High values are better quality and larger
985 files.
986 • "tiff_resolutionunit" - The value of the "ResolutionUnit" tag.
988 This is ignored on writing if the i_aspect_only tag is non-zero.
989 The "i_xres" and "i_yres" tags are expressed in pixels per inch no
991 matter the value of this tag, they will be converted to/from the
992 value stored in the TIFF file.
993 • "tiff_resolutionunit_name" - This is set when reading a TIFF file
995 to the name of the unit given by "tiff_resolutionunit". Possible
996 results include "inch", "centimeter", "none" (the "i_aspect_only"
997 tag is also set reading these files) or "unknown".
998 • "tiff_bitspersample" - Bits per sample from the image. This value
1000 is not used when writing an image, it is only set on a read image.
1001 • "tiff_photometric" - Value of the "PhotometricInterpretation" tag
1003 from the image. This value is not used when writing an image, it
1004 is only set on a read image.
1005 • "tiff_documentname", "tiff_imagedescription", "tiff_make",
1007 "tiff_model", "tiff_pagename", "tiff_software", "tiff_datetime",
1008 "tiff_artist", "tiff_hostcomputer" - Various strings describing the
1009 image. "tiff_datetime" must be formatted as "YYYY:MM:DD HH:MM:SS".
1010 These correspond directly to the mixed case names in the TIFF
1011 specification. These are set in images read from a TIFF and saved
1012 when writing a TIFF image.
1013 You can supply a "page" parameter to the "read()" method to read some
1015 page other than the first. The page is 0 based:
1016 # read the second image in the file
1018 $image->read(file=>"example.tif", page=>1)
1019 or die "Cannot read second page: ",$image->errstr,"\n";
1020 If you read an image with multiple alpha channels, then only the first
1022 alpha channel will be read.
1023 When reading a "TIFF" image with callbacks, the "seekcb" callback
1025 parameter is also required.
1026 When writing a "TIFF" image with callbacks, the "seekcb" and "readcb"
1028 parameters are also required.
1029 "TIFF" is a random access file format, it cannot be read from or
1031 written to unseekable streams such as pipes or sockets.
1032 BMP (Windows Bitmap)
1034 Imager can write 24-bit RGB, and 8, 4 and 1-bit per pixel paletted
1035 Windows BMP files. Currently you cannot write compressed BMP files
1036 with Imager.
1037 Imager can read 24-bit RGB, and 8, 4 and 1-bit perl pixel paletted
1039 Windows BMP files. There is some support for reading 16-bit per pixel
1040 images, but I haven't found any for testing.
1041 BMP has no support for multiple image files.
1043 BMP files support the spatial resolution tags, but since BMP has no
1045 support for storing only an aspect ratio, if "i_aspect_only" is set
1046 when you write the "i_xres" and "i_yres" values are scaled so the
1047 smaller is 72 DPI.
1048 The following tags are set when you read an image from a BMP file:
1050 bmp_compression
1052 The type of compression, if any. This can be any of the following
1053 values:
1054 BI_RGB (0)
1056 Uncompressed.
1057 BI_RLE8 (1)
1059 8-bits/pixel paletted value RLE compression.
1060 BI_RLE4 (2)
1062 4-bits/pixel paletted value RLE compression.
1063 BI_BITFIELDS (3)
1065 Packed RGB values.
1066 bmp_compression_name
1068 The bmp_compression value as a BI_* string
1069 bmp_important_colors
1071 The number of important colors as defined by the writer of the
1072 image.
1073 bmp_used_colors
1075 Number of color used from the BMP header
1076 bmp_filesize
1078 The file size from the BMP header
1079 bmp_bit_count
1081 Number of bits stored per pixel. (24, 8, 4 or 1)
1082 TGA (Targa)
1084 When storing Targa images RLE compression can be activated with the
1085 "compress" parameter, the "idstring" parameter can be used to set the
1086 Targa comment field and the "wierdpack" option can be used to use the
1087 15 and 16 bit Targa formats for RGB and RGBA data. The 15 bit format
1088 has 5 of each red, green and blue. The 16 bit format in addition
1089 allows 1 bit of alpha. The most significant bits are used for each
1090 channel.
1091 Tags:
1093 tga_idstring
1095 tga_bitspp
1096 compressed
1097 RAW
1099 When reading raw images you need to supply the width and height of the
1100 image in the "xsize" and "ysize" options:
1101 $img->read(file=>'foo.raw', xsize=>100, ysize=>100)
1103 or die "Cannot read raw image\n";
1104 If your input file has more channels than you want, or (as is common),
1106 junk in the fourth channel, you can use the "raw_datachannels" and
1107 "raw_storechannels" options to control the number of channels in your
1108 input file and the resulting channels in your image. For example, if
1109 your input image uses 32-bits per pixel with red, green, blue and junk
1110 values for each pixel you could do:
1111 $img->read(file=>'foo.raw', xsize => 100, ysize => 100,
1113 raw_datachannels => 4, raw_storechannels => 3,
1114 raw_interleave => 0)
1115 or die "Cannot read raw image\n";
1116 In general, if you supply "raw_storechannels" you should also supply
1118 "raw_datachannels"
1119 Read parameters:
1121 • "raw_interleave" - controls the ordering of samples within the
1123 image. Default: 1. Alternatively and historically spelled
1124 "interleave". Possible values:
1125 • 0 - samples are pixel by pixel, so all samples for the first
1127 pixel, then all samples for the second pixel and so on. eg.
1128 for a four pixel scan line the channels would be laid out as:
1129 012012012012
1131 • 1 - samples are line by line, so channel 0 for the entire scan
1133 line is followed by channel 1 for the entire scan line and so
1134 on. eg. for a four pixel scan line the channels would be laid
1135 out as:
1136 000011112222
1138 This is the default.
1140 Unfortunately, historically, the default "raw_interleave" for read
1142 has been 1, while writing only supports the "raw_interleave" = 0
1143 format.
1144 For future compatibility, you should always supply the
1146 "raw_interleave" (or "interleave") parameter. As of 0.68, Imager
1147 will warn if you attempt to read a raw image without a
1148 "raw_interleave" parameter.
1149 • "raw_storechannels" - the number of channels to store in the image.
1151 Range: 1 to 4. Default: 3. Alternatively and historically spelled
1152 "storechannels".
1153 • "raw_datachannels" - the number of channels to read from the file.
1155 Range: 1 or more. Default: 3. Alternatively and historically
1156 spelled "datachannels".
1157 $img->read(file=>'foo.raw', xsize=100, ysize=>100, raw_interleave=>1)
1159 or die "Cannot read raw image\n";
1160 PNG
1162 PNG Image modes
1163 PNG files can be read and written in the following modes:
1165 • bi-level - written as a 1-bit per sample gray scale image
1167 • paletted - Imager gray scale paletted images are written as RGB
1169 paletted images. PNG palettes can include alpha values for each
1170 entry and this is honored as an Imager four channel paletted image.
1171 • 8 and 16-bit per sample gray scale, optionally with an alpha
1173 channel.
1174 • 8 and 16-bit per sample RGB, optionally with an alpha channel.
1176 Unlike GIF, there is no automatic conversion to a paletted image, since
1178 PNG supports direct color.
1179 PNG Text tags
1181 Text tags are retrieved from and written to PNG "tEXT" or "zTXT"
1183 chunks. The following standard tags from the PNG specification are
1184 directly supported:
1185 • "i_comment" - keyword of "Comment".
1187 • "png_author" - keyword "Author".
1189 • "png_copyright" - keyword "Copyright".
1191 • "png_creation_time" - keyword "Creation Time".
1193 • "png_description" - keyword "Description".
1195 • "png_disclaimer" - keyword "Disclaimer".
1197 • "png_software" - keyword "Software".
1199 • "png_title" - keyword "Title".
1201 • "png_warning" - keyword "Warning".
1203 Each of these tags has a corresponding "base-tag-name_compressed" tag,
1205 eg. "png_comment_compressed". When reading, if the PNG chunk is
1206 compressed this tag will be set to 1, but is otherwise unset. When
1207 writing, Imager will honor the compression tag if set and non-zero,
1208 otherwise the chunk text will be compressed if the value is longer than
1209 1000 characters, as recommended by the "libpng" documentation.
1210 PNG "tEXT" or "zTXT" chunks outside of those above are read into or
1212 written from Imager tags named like:
1213 • "png_textN_key" - the key for the text chunk. This can be 1 to 79
1215 characters, may not contain any leading, trailing or consecutive
1216 spaces, and may contain only Latin-1 characters from 32-126,
1217 161-255.
1218 • "png_textN_text" - the text for the text chunk. This may not
1220 contain any "NUL" characters.
1221 • "png_textN_compressed" - whether or not the text chunk is
1223 compressed. This behaves similarly to the
1224 "base-tag-name_compressed" tags described above.
1225 Where N starts from 0. When writing both the "..._key" and "..._text"
1227 tags must be present or the write will fail. If the key or text do not
1228 satisfy the requirements above the write will fail.
1229 Other PNG metadata tags
1231 • "png_interlace", "png_interlace_name" - only set when reading,
1233 "png_interlace" is set to the type of interlacing used by the file,
1234 0 for one, 1 for Adam7. "png_interlace_name" is set to a keyword
1235 describing the interlacing, either "none" or "adam7".
1236 • "png_srgb_intent" - the sRGB rendering intent for the image. an
1238 integer from 0 to 3, per the PNG specification. If this chunk is
1239 found in the PNG file the "gAMA" and "cHRM" are ignored and the
1240 "png_gamma" and "png_chroma_..." tags are not set. Similarly when
1241 writing if "png_srgb_intent" is set the "gAMA" and "cHRM" chunks
1242 are not written.
1243 • "png_gamma" - the gamma of the image. This value is not currently
1245 used by Imager when processing the image, but this may change in
1246 the future.
1247 • "png_chroma_white_x", "png_chroma_white_y", "png_chroma_red_x",
1249 "png_chroma_red_y", "png_chroma_green_x", "png_chroma_green_y",
1250 "png_chroma_blue_x", "png_chroma_blue_y" - the primary
1251 chromaticities of the image, defining the color model. This is
1252 currently not used by Imager when processing the image, but this
1253 may change in the future.
1254 • "i_xres", "i_yres", "i_aspect_only" - processed per
1256 Imager::ImageTypes/CommonTags.
1257 • "png_bits" - the number of bits per sample in the representation.
1259 Ignored when writing.
1260 • "png_time" - the creation time of the file formatted as
1262 "year-month-dayThour:minute:second". This is stored as time data
1263 structure in the file, not a string. If you set "png_time" and it
1264 cannot be parsed as above, writing the PNG file will fail.
1265 • "i_background" - set from the "sBKG" when reading an image file.
1267 You can control the level of zlib compression used when writing with
1269 the "png_compression_level" parameter. This can be an integer between
1270 0 (uncompressed) and 9 (best compression).
1271 If you're using libpng 1.6 or later, or an earlier release configured
1273 with "PNG_BENIGN_ERRORS_SUPPORTED", you can choose to ignore file
1274 format errors the authors of libpng consider benign, this includes at
1275 least CRC errors and palette index overflows. Do this by supplying a
1276 true value for the "png_ignore_benign_errors" parameter to the read()
1277 method:
1278 $im->read(file => "foo.png", png_ignore_benign_errors => 1)
1280 or die $im->errstr;
1281 ICO (Microsoft Windows Icon) and CUR (Microsoft Windows Cursor)
1283 Icon and Cursor files are very similar, the only differences being a
1284 number in the header and the storage of the cursor hot spot. I've
1285 treated them separately so that you're not messing with tags to
1286 distinguish between them.
1287 The following tags are set when reading an icon image and are used when
1289 writing it:
1290 ico_mask
1292 This is the AND mask of the icon. When used as an icon in Windows
1293 1 bits in the mask correspond to pixels that are modified by the
1294 source image rather than simply replaced by the source image.
1295 Rather than requiring a binary bitmap this is accepted in a
1297 specific format:
1298 • first line consisting of the 0 placeholder, the 1 placeholder
1300 and a newline.
1301 • following lines which contain 0 and 1 placeholders for each
1303 scan line of the image, starting from the top of the image.
1304 When reading an image, '.' is used as the 0 placeholder and '*' as
1306 the 1 placeholder. An example:
1307 .*
1309 ..........................******
1310 ..........................******
1311 ..........................******
1312 ..........................******
1313 ...........................*****
1314 ............................****
1315 ............................****
1316 .............................***
1317 .............................***
1318 .............................***
1319 .............................***
1320 ..............................**
1321 ..............................**
1322 ...............................*
1323 ...............................*
1324 ................................
1325 ................................
1326 ................................
1327 ................................
1328 ................................
1329 ................................
1330 *...............................
1331 **..............................
1332 **..............................
1333 ***.............................
1334 ***.............................
1335 ****............................
1336 ****............................
1337 *****...........................
1338 *****...........................
1339 *****...........................
1340 *****...........................
1341 The following tags are set when reading an icon:
1343 ico_bits
1345 The number of bits per pixel used to store the image.
1346 For cursor files the following tags are set and read when reading and
1348 writing:
1349 cur_mask
1351 This is the same as the ico_mask above.
1352 cur_hotspotx
1354 cur_hotspoty
1355 The "hot" spot of the cursor image. This is the spot on the cursor
1356 that you click with. If you set these to out of range values they
1357 are clipped to the size of the image when written to the file.
1358 The following parameters can be supplied to read() or read_multi() to
1360 control reading of ICO/CUR files:
1361 • "ico_masked" - if true, the default, then the icon/cursors mask is
1363 applied as an alpha channel to the image, unless that image already
1364 has an alpha channel. This may result in a paletted image being
1365 returned as a direct color image. Default: 1
1366 # retrieve the image as stored, without using the mask as an alpha
1368 # channel
1369 $img->read(file => 'foo.ico', ico_masked => 0)
1370 or die $img->errstr;
1371 This was introduced in Imager 0.60. Previously reading ICO images
1373 acted as if "ico_masked => 0".
1374 • "ico_alpha_masked" - if true, then the icon/cursor mask is applied
1376 as an alpha channel to images that already have an alpha mask.
1377 Note that this will only make pixels transparent, not opaque.
1378 Default: 0.
1379 Note: If you get different results between "ico_alpha_masked" being
1381 set to 0 and 1, your mask may break when used with the Win32 API.
1382 "cur_bits" is set when reading a cursor.
1384 Examples:
1386 my $img = Imager->new(xsize => 32, ysize => 32, channels => 4);
1388 $im->box(color => 'FF0000');
1389 $im->write(file => 'box.ico');
1390 $im->settag(name => 'cur_hotspotx', value => 16);
1392 $im->settag(name => 'cur_hotspoty', value => 16);
1393 $im->write(file => 'box.cur');
1394 SGI (RGB, BW)
1396 SGI images, often called by the extensions, RGB or BW, can be stored
1397 either uncompressed or compressed using an RLE compression.
1398 By default, when saving to an extension of "rgb", "bw", "sgi", "rgba"
1400 the file will be saved in SGI format. The file extension is otherwise
1401 ignored, so saving a 3-channel image to a ".bw" file will result in a
1402 3-channel image on disk.
1403 The following tags are set when reading a SGI image:
1405 • i_comment - the "IMAGENAME" field from the image. Also written to
1407 the file when writing.
1408 • sgi_pixmin, sgi_pixmax - the "PIXMIN" and "PIXMAX" fields from the
1410 image. On reading image data is expanded from this range to the
1411 full range of samples in the image.
1412 • sgi_bpc - the number of bytes per sample for the image. Ignored
1414 when writing.
1415 • sgi_rle - whether or not the image is compressed. If this is non-
1417 zero when writing the image will be compressed.
1418
1420 To support a new format for reading, call the register_reader() class
1421 method:
1422 register_reader()
1424 Registers single or multiple image read functions.
1425 Parameters:
1427 • type - the identifier of the file format, if Imager's
1429 i_test_format_probe() can identify the format then this value
1430 should match i_test_format_probe()'s result.
1431 This parameter is required.
1433 • single - a code ref to read a single image from a file. This
1435 is supplied:
1436 • the object that read() was called on,
1438 • an Imager::IO object that should be used to read the file,
1440 and
1441 • all the parameters supplied to the read() method.
1443 The single parameter is required.
1445 • multiple - a code ref which is called to read multiple images
1447 from a file. This is supplied:
1448 • an Imager::IO object that should be used to read the file,
1450 and
1451 • all the parameters supplied to the read_multi() method.
1453 Example:
1455 # from Imager::File::ICO
1457 Imager->register_reader
1458 (
1459 type=>'ico',
1460 single =>
1461 sub {
1462 my ($im, $io, %hsh) = @_;
1463 $im->{IMG} = i_readico_single($io, $hsh{page} || 0);
1464 unless ($im->{IMG}) {
1466 $im->_set_error(Imager->_error_as_msg);
1467 return;
1468 }
1469 return $im;
1470 },
1471 multiple =>
1472 sub {
1473 my ($io, %hsh) = @_;
1474 my @imgs = i_readico_multi($io);
1476 unless (@imgs) {
1477 Imager->_set_error(Imager->_error_as_msg);
1478 return;
1479 }
1480 return map {
1481 bless { IMG => $_, DEBUG => $Imager::DEBUG, ERRSTR => undef }, 'Imager'
1482 } @imgs;
1483 },
1484 );
1485 register_writer()
1487 Registers single or multiple image write functions.
1488 Parameters:
1490 • type - the identifier of the file format. This is typically
1492 the extension in lowercase.
1493 This parameter is required.
1495 • single - a code ref to write a single image to a file. This is
1497 supplied:
1498 • the object that write() was called on,
1500 • an Imager::IO object that should be used to write the file,
1502 and
1503 • all the parameters supplied to the write() method.
1505 The single parameter is required.
1507 • multiple - a code ref which is called to write multiple images
1509 to a file. This is supplied:
1510 • the class name write_multi() was called on, this is
1512 typically "Imager".
1513 • an Imager::IO object that should be used to write the file,
1515 and
1516 • all the parameters supplied to the read_multi() method.
1518 add_type_extensions($type, $ext, ...)
1520 This class method can be used to add extensions to the map used by
1521 "def_guess_type" when working out the file type a filename
1522 extension.
1523 Imager->add_type_extension(mytype => "mytype", "mytypish");
1525 ...
1526 $im->write(file => "foo.mytypish") # use the mytype handler
1527 If you name the reader module "Imager::File::"your-format-name where
1529 your-format-name is a fully upper case version of the type value you
1530 would pass to read(), read_multi(), write() or write_multi() then
1531 Imager will attempt to load that module if it has no other way to read
1532 or write that format.
1533 For example, if you create a module Imager::File::GIF and the user has
1535 built Imager without it's normal GIF support then an attempt to read a
1536 GIF image will attempt to load Imager::File::GIF.
1537 If your module can only handle reading then you can name your module
1539 "Imager::File::"your-format-name"Reader" and Imager will attempt to
1540 autoload it.
1541 If your module can only handle writing then you can name your module
1543 "Imager::File::"your-format-name"Writer" and Imager will attempt to
1544 autoload it.
1545
1547 preload()
1548 "Imager-"preload> preloads the file support modules included with
1549 or that have been included with Imager in the past.
1550 It isn't typically needed, but some cases where you might want to
1552 use it:
1553 • For use in forking servers such as mod_perl to allow as many
1555 pages as possible to be shared between parent and child
1556 processes.
1557 • to avoid runtime loading of a module from delaying output in an
1559 animation.
1560 • if you're loading modules from a relative $ENV{PERL5LIB} and
1562 expect to change directories.
1563 You probably don't need it.
1565 If the module is not available no error occurs.
1567 Preserves $@.
1569 use Imager;
1571 Imager->preload;
1572
1574 Producing an image from a CGI script
1575 Once you have an image the basic mechanism is:
1576 1. set STDOUT to autoflush
1578 2. output a content-type header, and optionally a content-length
1580 header
1581 3. put STDOUT into binmode
1583 4. call write() with the "fd" or "fh" parameter. You will need to
1585 provide the "type" parameter since Imager can't use the extension
1586 to guess the file format you want.
1587 # write an image from a CGI script
1589 # using CGI.pm
1590 use CGI qw(:standard);
1591 $| = 1;
1592 binmode STDOUT;
1593 print header(-type=>'image/gif');
1594 $img->write(type=>'gif', fd=>fileno(STDOUT))
1595 or die $img->errstr;
1596 If you want to send a content length you can send the output to a
1598 scalar to get the length:
1599 my $data;
1601 $img->write(type=>'gif', data=>\$data)
1602 or die $img->errstr;
1603 binmode STDOUT;
1604 print header(-type=>'image/gif', -content_length=>length($data));
1605 print $data;
1606 Writing an animated GIF
1608 The basic idea is simple, just use write_multi():
1609 my @imgs = ...;
1611 Imager->write_multi({ file=>$filename, type=>'gif' }, @imgs);
1612 If your images are RGB images the default quantization mechanism will
1614 produce a very good result, but can take a long time to execute. You
1615 could either use the standard web color map:
1616 Imager->write_multi({ file=>$filename,
1618 type=>'gif',
1619 make_colors=>'webmap' },
1620 @imgs);
1621 or use a median cut algorithm to built a fairly optimal color map:
1623 Imager->write_multi({ file=>$filename,
1625 type=>'gif',
1626 make_colors=>'mediancut' },
1627 @imgs);
1628 By default all of the images will use the same global color map, which
1630 will produce a smaller image. If your images have significant color
1631 differences, you may want to generate a new palette for each image:
1632 Imager->write_multi({ file=>$filename,
1634 type=>'gif',
1635 make_colors=>'mediancut',
1636 gif_local_map => 1 },
1637 @imgs);
1638 which will set the "gif_local_map" tag in each image to 1.
1640 Alternatively, if you know only some images have different colors, you
1641 can set the tag just for those images:
1642 $imgs[2]->settag(name=>'gif_local_map', value=>1);
1644 $imgs[4]->settag(name=>'gif_local_map', value=>1);
1645 and call write_multi() without a "gif_local_map" parameter, or supply
1647 an arrayref of values for the tag:
1648 Imager->write_multi({ file=>$filename,
1650 type=>'gif',
1651 make_colors=>'mediancut',
1652 gif_local_map => [ 0, 0, 1, 0, 1 ] },
1653 @imgs);
1654 Other useful parameters include "gif_delay" to control the delay
1656 between frames and "transp" to control transparency.
1657 Reading tags after reading an image
1659 This is pretty simple:
1660 # print the author of a TIFF, if any
1662 my $img = Imager->new;
1663 $img->read(file=>$filename, type='tiff') or die $img->errstr;
1664 my $author = $img->tags(name=>'tiff_author');
1665 if (defined $author) {
1666 print "Author: $author\n";
1667 }
1668
1670 When saving GIF images the program does NOT try to shave off extra
1671 colors if it is possible. If you specify 128 colors and there are only
1672 2 colors used - it will have a 128 color table anyway.
1673
1675 Imager(3)
1676
1678 Tony Cook <tonyc@cpan.org>, Arnar M. Hrafnkelsson
1679perl v5.36.0 2022-07-22 Imager::Files(3)