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
61 You can read and write a variety of images formats, assuming you have
62 the appropriate libraries, and images can be read or written to/from
63 files, file handles, file descriptors, scalars, or through callbacks.
64 To see which image formats Imager is compiled to support the following
66 code snippet is sufficient:
67 use Imager;
69 print join " ", keys %Imager::formats;
70 This will include some other information identifying libraries rather
72 than file formats. For new code you might find the "read_types()" or
73 "write_types()" methods useful.
74 read
76 Reading writing to and from files is simple, use the "read()"
77 method to read an image:
78 my $img = Imager->new;
80 $img->read(file=>$filename, type=>$type)
81 or die "Cannot read $filename: ", $img->errstr;
82 In most cases Imager can auto-detect the file type, so you can just
84 supply the file name:
85 $img->read(file => $filename)
87 or die "Cannot read $filename: ", $img->errstr;
88 The read() method accepts the "allow_partial" parameter. If this
90 is non-zero then read() can return true on an incomplete image and
91 set the "i_incomplete" tag.
92 From Imager 0.68 you can supply most read() parameters to the new()
94 method to read the image file on creation. If the read fails,
95 check Imager->errstr() for the cause:
96 use Imager 0.68;
98 my $img = Imager->new(file => $filename)
99 or die "Cannot read $filename: ", Imager->errstr;
100 write
102 and the "write()" method to write an image:
103 $img->write(file=>$filename, type=>$type)
105 or die "Cannot write $filename: ", $img->errstr;
106 read_multi
108 If you're reading from a format that supports multiple images per
109 file, use the "read_multi()" method:
110 my @imgs = Imager->read_multi(file=>$filename, type=>$type)
112 or die "Cannot read $filename: ", Imager->errstr;
113 As with the read() method, Imager will normally detect the "type"
115 automatically.
116 write_multi
118 and if you want to write multiple images to a single file use the
119 "write_multi()" method:
120 Imager->write_multi({ file=> $filename, type=>$type }, @images)
122 or die "Cannot write $filename: ", Imager->errstr;
123 read_types()
125 This is a class method that returns a list of the image file types
126 that Imager can read.
127 my @types = Imager->read_types;
129 These types are the possible values for the "type" parameter, not
131 necessarily the extension of the files you're reading.
132 It is possible for extra file read handlers to be loaded when
134 attempting to read a file, which may modify the list of available
135 read types.
136 write_types()
138 This is a class method that returns a list of the image file types
139 that Imager can write.
140 my @types = Imager->write_types;
142 Note that these are the possible values for the "type" parameter,
144 not necessarily the extension of the files you're writing.
145 It is possible for extra file write handlers to be loaded when
147 attempting to write a file, which may modify the list of available
148 write types.
149 When writing, if the "filename" includes an extension that Imager
151 recognizes, then you don't need the "type", but you may want to provide
152 one anyway. See "Guessing types" for information on controlling this
153 recognition.
154 The "type" parameter is a lowercase representation of the file type,
156 and can be any of the following:
157 bmp Windows BitMaP (BMP)
159 gif Graphics Interchange Format (GIF)
160 jpeg JPEG/JFIF
161 png Portable Network Graphics (PNG)
162 pnm Portable aNyMap (PNM)
163 raw Raw
164 sgi SGI .rgb files
165 tga TARGA
166 tiff Tagged Image File Format (TIFF)
167 When you read an image, Imager may set some tags, possibly including
169 information about the spatial resolution, textual information, and
170 animation information. See "Tags" in Imager::ImageTypes for specifics.
171 The open() method is a historical alias for the read() method.
173 Input and output
175 When reading or writing you can specify one of a variety of sources or
176 targets:
177 · "file" - The "file" parameter is the name of the image file to be
179 written to or read from. If Imager recognizes the extension of the
180 file you do not need to supply a "type".
181 # write in tiff format
183 $image->write(file => "example.tif")
184 or die $image->errstr;
185 $image->write(file => 'foo.tmp', type => 'tiff')
187 or die $image->errstr;
188 my $image = Imager->new;
190 $image->read(file => 'example.tif')
191 or die $image->errstr;
192 · "fh" - "fh" is a file handle, typically either returned from
194 "<IO::File-"new()>>, or a glob from an "open" call. You should
195 call "binmode" on the handle before passing it to Imager.
196 Imager will set the handle to autoflush to make sure any buffered
198 data is flushed , since Imager will write to the file descriptor
199 (from fileno()) rather than writing at the perl level.
200 $image->write(fh => \*STDOUT, type => 'gif')
202 or die $image->errstr;
203 # for example, a file uploaded via CGI.pm
205 $image->read(fd => $cgi->param('file'))
206 or die $image->errstr;
207 · "fd" - "fd" is a file descriptor. You can get this by calling the
209 "fileno()" function on a file handle, or by using one of the
210 standard file descriptor numbers.
211 If you get this from a perl file handle, you may need to flush any
213 buffered output, otherwise it may appear in the output stream after
214 the image.
215 $image->write(fd => file(STDOUT), type => 'gif')
217 or die $image->errstr;
218 · "data" - When reading data, "data" is a scalar containing the image
220 file data, when writing, "data" is a reference to the scalar to
221 save the image file data too. For GIF images you will need
222 "giflib" 4 or higher, and you may need to patch "giflib" to use
223 this option for writing.
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 · "callback" - Imager will make calls back to your supplied coderefs
234 to read, write and seek from/to/through the image file.
235 When reading from a file you can use either "callback" or "readcb"
237 to supply the read callback, and when writing "callback" or
238 "writecb" to supply the write callback.
239 When writing you can also supply the "maxbuffer" option to set the
241 maximum amount of data that will be buffered before your write
242 callback is called. Note: the amount of data supplied to your
243 callback can be smaller or larger than this size.
244 The read callback is called with 2 parameters, the minimum amount
246 of data required, and the maximum amount that Imager will store in
247 it's C level buffer. You may want to return the minimum if you
248 have a slow data source, or the maximum if you have a fast source
249 and want to prevent many calls to your perl callback. The read
250 data should be returned as a scalar.
251 Your write callback takes exactly one parameter, a scalar
253 containing the data to be written. Return true for success.
254 The seek callback takes 2 parameters, a POSITION, and a WHENCE,
256 defined in the same way as perl's seek function.
257 You can also supply a "closecb" which is called with no parameters
259 when there is no more data to be written. This could be used to
260 flush buffered data.
261 # contrived
263 my $data;
264 sub mywrite {
265 $data .= unpack("H*", shift);
266 1;
267 }
268 Imager->write_multi({ callback => \&mywrite, type => 'gif'}, @images)
269 or die Imager->errstr;
270 Note that for reading you'll almost always need to provide a
272 "seekcb".
273 Guessing types
275 When writing to a file, if you don't supply a "type" parameter Imager
276 will attempt to guess it from the file name. This is done by calling
277 the code reference stored in $Imager::FORMATGUESS. This is only done
278 when write() or write_multi() is called with a "file" parameter.
279 The default function value of $Imager::FORMATGUESS is
281 "\&Imager::def_guess_type".
282 def_guess_type()
284 This is the default function Imager uses to derive a file type from
285 a file name. This is a function, not a method.
286 Accepts a single parameter, the file name and returns the type or
288 undef.
289 You can replace function with your own implementation if you have some
291 specialized need. The function takes a single parameter, the name of
292 the file, and should return either a file type or under.
293 # I'm writing jpegs to weird filenames
295 local $Imager::FORMATGUESS = sub { 'jpeg' };
296 When reading a file Imager examines beginning of the file for
298 identifying information. The current implementation attempts to detect
299 the following image types beyond those supported by Imager:
300 "xpm", "mng", "jng", "ilbm", "pcx", "fits", "psd" (Photoshop),
302 "eps", Utah "RLE".
303 Limiting the sizes of images you read
305 set_file_limits()
306 In some cases you will be receiving images from an untested source,
307 such as submissions via CGI. To prevent such images from consuming
308 large amounts of memory, you can set limits on the dimensions of
309 images you read from files:
310 · width - limit the width in pixels of the image
312 · height - limit the height in pixels of the image
314 · bytes - limits the amount of storage used by the image. This
316 depends on the width, height, channels and sample size of the
317 image. For paletted images this is calculated as if the image
318 was expanded to a direct color image.
319 To set the limits, call the class method set_file_limits:
321 Imager->set_file_limits(width=>$max_width, height=>$max_height);
323 You can pass any or all of the limits above, any limits you do not
325 pass are left as they were.
326 Any limit of zero is treated as unlimited.
328 By default, the width and height limits are zero, or unlimited.
330 The default memory size limit is one gigabyte.
331 You can reset all limits to unlimited with the reset parameter:
333 # no limits
335 Imager->set_file_limits(reset=>1);
336 This can be used with the other limits to reset all but the limit
338 you pass:
339 # only width is limited
341 Imager->set_file_limits(reset=>1, width=>100);
342 # only bytes is limited
344 Imager->set_file_limits(reset=>1, bytes=>10_000_000);
345 get_file_limits()
347 You can get the current limits with the get_file_limits() method:
348 my ($max_width, $max_height, $max_bytes) =
350 Imager->get_file_limits();
351
353 The different image formats can write different image type, and some
354 have different options to control how the images are written.
355 When you call "write()" or "write_multi()" with an option that has the
357 same name as a tag for the image format you're writing, then the value
358 supplied to that option will be used to set the corresponding tag in
359 the image. Depending on the image format, these values will be used
360 when writing the image.
361 This replaces the previous options that were used when writing GIF
363 images. Currently if you use an obsolete option, it will be converted
364 to the equivalent tag and Imager will produced a warning. You can
365 suppress these warnings by calling the "Imager::init()" function with
366 the "warn_obsolete" option set to false:
367 Imager::init(warn_obsolete=>0);
369 At some point in the future these obsolete options will no longer be
371 supported.
372 PNM (Portable aNy Map)
374 Imager can write "PGM" (Portable Gray Map) and "PPM" (Portable PixMaps)
375 files, depending on the number of channels in the image. Currently the
376 images are written in binary formats. Only 1 and 3 channel images can
377 be written, including 1 and 3 channel paletted images.
378 $img->write(file=>'foo.ppm') or die $img->errstr;
380 Imager can read both the ASCII and binary versions of each of the "PBM"
382 (Portable BitMap), "PGM" and "PPM" formats.
383 $img->read(file=>'foo.ppm') or die $img->errstr;
385 PNM does not support the spatial resolution tags.
387 The following tags are set when reading a PNM file:
389 · "pnm_maxval" - the "maxvals" number from the PGM/PPM header.
391 Always set to 2 for a "PBM" file.
392 · "pnm_type" - the type number from the "PNM" header, 1 for ASCII
394 "PBM" files, 2 for ASCII "PGM" files, 3 for ASCII c<PPM> files, 4
395 for binary "PBM" files, 5 for binary "PGM" files, 6 for binary
396 "PPM" files.
397 The following tag is checked when writing an image with more than
399 8-bits/sample:
400 · pnm_write_wide_data - if this is non-zero then write() can write
402 "PGM"/"PPM" files with 16-bits/sample. Some applications, for
403 example GIMP 2.2, and tools can only read 8-bit/sample binary PNM
404 files, so Imager will only write a 16-bit image when this tag is
405 non-zero.
406 JPEG
408 You can supply a "jpegquality" parameter (0-100) when writing a JPEG
409 file, which defaults to 75%. If you write an image with an alpha
410 channel to a JPEG file then it will be composited against the
411 background set by the "i_background" parameter (or tag).
412 $img->write(file=>'foo.jpg', jpegquality=>90) or die $img->errstr;
414 Imager will read a gray scale JPEG as a 1 channel image and a color
416 JPEG as a 3 channel image.
417 $img->read(file=>'foo.jpg') or die $img->errstr;
419 The following tags are set in a JPEG image when read, and can be set to
421 control output:
422 · "jpeg_density_unit" - The value of the density unit field in the
424 "JFIF" header. This is ignored on writing if the "i_aspect_only"
425 tag is non-zero.
426 The "i_xres" and "i_yres" tags are expressed in pixels per inch no
428 matter the value of this tag, they will be converted to/from the
429 value stored in the JPEG file.
430 · "jpeg_density_unit_name" - This is set when reading a JPEG file to
432 the name of the unit given by "jpeg_density_unit". Possible
433 results include "inch", "centimeter", "none" (the "i_aspect_only"
434 tag is also set reading these files). If the value of
435 "jpeg_density_unit" is unknown then this tag isn't set.
436 · "jpeg_comment" - Text comment.
438 · "jpeg_progressive" - Whether the JPEG file is a progressive file.
440 (Imager 0.84)
441 JPEG supports the spatial resolution tags "i_xres", "i_yres" and
443 "i_aspect_only".
444 If an "APP1" block containing EXIF information is found, then any of
446 the following tags can be set when reading a JPEG image:
447 exif_aperture exif_artist exif_brightness exif_color_space
449 exif_contrast exif_copyright exif_custom_rendered exif_date_time
450 exif_date_time_digitized exif_date_time_original
451 exif_digital_zoom_ratio exif_exposure_bias exif_exposure_index
452 exif_exposure_mode exif_exposure_program exif_exposure_time
453 exif_f_number exif_flash exif_flash_energy exif_flashpix_version
454 exif_focal_length exif_focal_length_in_35mm_film
455 exif_focal_plane_resolution_unit exif_focal_plane_x_resolution
456 exif_focal_plane_y_resolution exif_gain_control
457 exif_image_description exif_image_unique_id exif_iso_speed_rating
458 exif_make exif_max_aperture exif_metering_mode exif_model
459 exif_orientation exif_related_sound_file exif_resolution_unit
460 exif_saturation exif_scene_capture_type exif_sensing_method
461 exif_sharpness exif_shutter_speed exif_software
462 exif_spectral_sensitivity exif_sub_sec_time
463 exif_sub_sec_time_digitized exif_sub_sec_time_original
464 exif_subject_distance exif_subject_distance_range
465 exif_subject_location exif_tag_light_source exif_user_comment
466 exif_version exif_white_balance exif_x_resolution exif_y_resolution
467 The following derived tags can also be set when reading a JPEG image:
469 exif_color_space_name exif_contrast_name exif_custom_rendered_name
471 exif_exposure_mode_name exif_exposure_program_name exif_flash_name
472 exif_focal_plane_resolution_unit_name exif_gain_control_name
473 exif_light_source_name exif_metering_mode_name
474 exif_resolution_unit_name exif_saturation_name
475 exif_scene_capture_type_name exif_sensing_method_name
476 exif_sharpness_name exif_subject_distance_range_name
477 exif_white_balance_name
478 The derived tags are for enumerated fields, when the value for the base
480 field is valid then the text that appears in the EXIF specification for
481 that value appears in the derived field. So for example if
482 "exf_metering_mode" is 5 then "exif_metering_mode_name" is set to
483 "Pattern".
484 eg.
486 my $image = Imager->new;
488 $image->read(file => 'exiftest.jpg')
489 or die "Cannot load image: ", $image->errstr;
490 print $image->tags(name => "exif_image_description"), "\n";
491 print $image->tags(name => "exif_exposure_mode"), "\n";
492 print $image->tags(name => "exif_exposure_mode_name"), "\n";
493 # for the exiftest.jpg in the Imager distribution the output would be:
495 Imager Development Notes
496 0
497 Auto exposure
498 Imager will not write EXIF tags to any type of image, if you need more
500 advanced EXIF handling, consider Image::ExifTool.
501 parseiptc()
503 Historically, Imager saves IPTC data when reading a JPEG image, the
504 parseiptc() method returns a list of key/value pairs resulting from
505 a simple decoding of that data.
506 Any future IPTC data decoding is likely to go into tags.
508 GIF
510 When writing one of more GIF images you can use the same Quantization
511 Options as you can when converting an RGB image into a paletted image.
512 When reading a GIF all of the sub-images are combined using the screen
514 size and image positions into one big image, producing an RGB image.
515 This may change in the future to produce a paletted image where
516 possible.
517 When you read a single GIF with "$img->read()" you can supply a
519 reference to a scalar in the "colors" parameter, if the image is read
520 the scalar will be filled with a reference to an anonymous array of
521 Imager::Color objects, representing the palette of the image. This
522 will be the first palette found in the image. If you want the palettes
523 for each of the images in the file, use "read_multi()" and use the
524 "getcolors()" method on each image.
525 GIF does not support the spatial resolution tags.
527 Imager will set the following tags in each image when reading, and can
529 use most of them when writing to GIF:
530 · gif_left - the offset of the image from the left of the "screen"
532 ("Image Left Position")
533 · gif_top - the offset of the image from the top of the "screen"
535 ("Image Top Position")
536 · gif_interlace - non-zero if the image was interlaced ("Interlace
538 Flag")
539 · gif_screen_width, gif_screen_height - the size of the logical
541 screen. When writing this is used as the minimum. If any image
542 being written would extend beyond this then the screen size is
543 extended. ("Logical Screen Width", "Logical Screen Height").
544 · gif_local_map - Non-zero if this image had a local color map. If
546 set for an image when writing the image is quantized separately
547 from the other images in the file.
548 · gif_background - The index in the global color map of the logical
550 screen's background color. This is only set if the current image
551 uses the global color map. You can set this on write too, but for
552 it to choose the color you want, you will need to supply only
553 paletted images and set the "gif_eliminate_unused" tag to 0.
554 · gif_trans_index - The index of the color in the color map used for
556 transparency. If the image has a transparency then it is returned
557 as a 4 channel image with the alpha set to zero in this palette
558 entry. This value is not used when writing. ("Transparent Color
559 Index")
560 · gif_trans_color - A reference to an Imager::Color object, which is
562 the color to use for the palette entry used to represent
563 transparency in the palette. You need to set the "transp" option
564 (see "Quantization options" in Imager::ImageTypes) for this value
565 to be used.
566 · gif_delay - The delay until the next frame is displayed, in 1/100
568 of a second. ("Delay Time").
569 · gif_user_input - whether or not a user input is expected before
571 continuing (view dependent) ("User Input Flag").
572 · gif_disposal - how the next frame is displayed ("Disposal Method")
574 · gif_loop - the number of loops from the Netscape Loop extension.
576 This may be zero to loop forever.
577 · gif_comment - the first block of the first GIF comment before each
579 image.
580 · gif_eliminate_unused - If this is true, when you write a paletted
582 image any unused colors will be eliminated from its palette. This
583 is set by default.
584 · gif_colormap_size - the original size of the color map for the
586 image. The color map of the image may have been expanded to
587 include out of range color indexes.
588 Where applicable, the ("name") is the name of that field from the
590 "GIF89" standard.
591 The following GIF writing options are obsolete, you should set the
593 corresponding tag in the image, either by using the tags functions, or
594 by supplying the tag and value as options.
595 · gif_each_palette - Each image in the GIF file has it's own palette
597 if this is non-zero. All but the first image has a local color
598 table (the first uses the global color table.
599 Use "gif_local_map" in new code.
601 · interlace - The images are written interlaced if this is non-zero.
603 Use "gif_interlace" in new code.
605 · gif_delays - A reference to an array containing the delays between
607 images, in 1/100 seconds.
608 Use "gif_delay" in new code.
610 · gif_positions - A reference to an array of references to arrays
612 which represent screen positions for each image.
613 New code should use the "gif_left" and "gif_top" tags.
615 · gif_loop_count - If this is non-zero the Netscape loop extension
617 block is generated, which makes the animation of the images repeat.
618 This is currently unimplemented due to some limitations in
620 "giflib".
621 You can supply a "page" parameter to the "read()" method to read some
623 page other than the first. The page is 0 based:
624 # read the second image in the file
626 $image->read(file=>"example.gif", page=>1)
627 or die "Cannot read second page: ",$image->errstr,"\n";
628 Before release 0.46, Imager would read multiple image GIF image files
630 into a single image, overlaying each of the images onto the virtual GIF
631 screen.
632 As of 0.46 the default is to read the first image from the file, as if
634 called with "page => 0".
635 You can return to the previous behavior by calling read with the
637 "gif_consolidate" parameter set to a true value:
638 $img->read(file=>$some_gif_file, gif_consolidate=>1);
640 As with the to_paletted() method, if you supply a colors parameter as a
642 reference to an array, this will be filled with Imager::Color objects
643 of the color table generated for the image file.
644 TIFF (Tagged Image File Format)
646 Imager can write images to either paletted or RGB TIFF images,
647 depending on the type of the source image.
648 When writing direct color images to TIFF the sample size of the output
650 file depends on the input:
651 · double/sample - written as 32-bit/sample TIFF
653 · 16-bit/sample - written as 16-bit/sample TIFF
655 · 8-bit/sample - written as 8-bit/sample TIFF
657 For paletted images:
659 · "$img->is_bilevel" is true - the image is written as bi-level
661 · otherwise - image is written as paletted.
663 If you are creating images for faxing you can set the class parameter
665 set to "fax". By default the image is written in fine mode, but this
666 can be overridden by setting the fax_fine parameter to zero. Since a
667 fax image is bi-level, Imager uses a threshold to decide if a given
668 pixel is black or white, based on a single channel. For gray scale
669 images channel 0 is used, for color images channel 1 (green) is used.
670 If you want more control over the conversion you can use
671 $img->to_paletted() to product a bi-level image. This way you can use
672 dithering:
673 my $bilevel = $img->to_paletted(make_colors => 'mono',
675 translate => 'errdiff',
676 errdiff => 'stucki');
677 · "class" - If set to 'fax' the image will be written as a bi-level
679 fax image.
680 · "fax_fine" - By default when "class" is set to 'fax' the image is
682 written in fine mode, you can select normal mode by setting
683 "fax_fine" to 0.
684 Imager should be able to read any TIFF image you supply. Paletted TIFF
686 images are read as paletted Imager images, since paletted TIFF images
687 have 16-bits/sample (48-bits/color) this means the bottom 8-bits are
688 lost, but this shouldn't be a big deal.
689 TIFF supports the spatial resolution tags. See the
691 "tiff_resolutionunit" tag for some extra options.
692 As of Imager 0.62 Imager reads:
694 · 8-bit/sample gray, RGB or CMYK images, including a possible alpha
696 channel as an 8-bit/sample image.
697 · 16-bit gray, RGB, or CMYK image, including a possible alpha channel
699 as a 16-bit/sample image.
700 · 32-bit gray, RGB image, including a possible alpha channel as a
702 double/sample image.
703 · bi-level images as paletted images containing only black and white,
705 which other formats will also write as bi-level.
706 · tiled paletted images are now handled correctly
708 · other images are read using "tifflib"'s RGBA interface as
710 8-bit/sample images.
711 The following tags are set in a TIFF image when read, and can be set to
713 control output:
714 · "tiff_compression" - When reading an image this is set to the
716 numeric value of the TIFF compression tag.
717 On writing you can set this to either a numeric compression tag
719 value, or one of the following values:
720 Ident Number Description
722 none 1 No compression
723 packbits 32773 Macintosh RLE
724 ccittrle 2 CCITT RLE
725 fax3 3 CCITT Group 3 fax encoding (T.4)
726 t4 3 As above
727 fax4 4 CCITT Group 4 fax encoding (T.6)
728 t6 4 As above
729 lzw 5 LZW
730 jpeg 7 JPEG
731 zip 8 Deflate (GZIP) Non-standard
732 deflate 8 As above.
733 oldzip 32946 Deflate with an older code.
734 ccittrlew 32771 Word aligned CCITT RLE
735 In general a compression setting will be ignored where it doesn't
737 make sense, eg. "jpeg" will be ignored for compression if the image
738 is being written as bilevel.
739 Imager attempts to check that your build of "libtiff" supports the
741 given compression, and will fallback to "packbits" if it isn't
742 enabled. eg. older distributions didn't include LZW compression,
743 and JPEG compression is only available if "libtiff" is configured
744 with "libjpeg"'s location.
745 $im->write(file => 'foo.tif', tiff_compression => 'lzw')
747 or die $im->errstr;
748 · "tags, tiff_jpegquality""tiff_jpegquality" - If "tiff_compression"
750 is "jpeg" then this can be a number from 1 to 100 giving the JPEG
751 compression quality. High values are better quality and larger
752 files.
753 · "tiff_resolutionunit" - The value of the "ResolutionUnit" tag.
755 This is ignored on writing if the i_aspect_only tag is non-zero.
756 The "i_xres" and "i_yres" tags are expressed in pixels per inch no
758 matter the value of this tag, they will be converted to/from the
759 value stored in the TIFF file.
760 · "tiff_resolutionunit_name" - This is set when reading a TIFF file
762 to the name of the unit given by "tiff_resolutionunit". Possible
763 results include "inch", "centimeter", "none" (the "i_aspect_only"
764 tag is also set reading these files) or "unknown".
765 · "tiff_bitspersample" - Bits per sample from the image. This value
767 is not used when writing an image, it is only set on a read image.
768 · "tiff_photometric" - Value of the "PhotometricInterpretation" tag
770 from the image. This value is not used when writing an image, it
771 is only set on a read image.
772 · "tiff_documentname", "tiff_imagedescription", "tiff_make",
774 "tiff_model", "tiff_pagename", "tiff_software", "tiff_datetime",
775 "tiff_artist", "tiff_hostcomputer" - Various strings describing the
776 image. "tiff_datetime" must be formatted as "YYYY:MM:DD HH:MM:SS".
777 These correspond directly to the mixed case names in the TIFF
778 specification. These are set in images read from a TIFF and saved
779 when writing a TIFF image.
780 You can supply a "page" parameter to the "read()" method to read some
782 page other than the first. The page is 0 based:
783 # read the second image in the file
785 $image->read(file=>"example.tif", page=>1)
786 or die "Cannot read second page: ",$image->errstr,"\n";
787 If you read an image with multiple alpha channels, then only the first
789 alpha channel will be read.
790 BMP (Windows Bitmap)
792 Imager can write 24-bit RGB, and 8, 4 and 1-bit per pixel paletted
793 Windows BMP files. Currently you cannot write compressed BMP files
794 with Imager.
795 Imager can read 24-bit RGB, and 8, 4 and 1-bit perl pixel paletted
797 Windows BMP files. There is some support for reading 16-bit per pixel
798 images, but I haven't found any for testing.
799 BMP has no support for multiple image files.
801 BMP files support the spatial resolution tags, but since BMP has no
803 support for storing only an aspect ratio, if "i_aspect_only" is set
804 when you write the "i_xres" and "i_yres" values are scaled so the
805 smaller is 72 DPI.
806 The following tags are set when you read an image from a BMP file:
808 bmp_compression
810 The type of compression, if any. This can be any of the following
811 values:
812 BI_RGB (0)
814 Uncompressed.
815 BI_RLE8 (1)
817 8-bits/pixel paletted value RLE compression.
818 BI_RLE4 (2)
820 4-bits/pixel paletted value RLE compression.
821 BI_BITFIELDS (3)
823 Packed RGB values.
824 bmp_compression_name
826 The bmp_compression value as a BI_* string
827 bmp_important_colors
829 The number of important colors as defined by the writer of the
830 image.
831 bmp_used_colors
833 Number of color used from the BMP header
834 bmp_filesize
836 The file size from the BMP header
837 bmp_bit_count
839 Number of bits stored per pixel. (24, 8, 4 or 1)
840 TGA (Targa)
842 When storing Targa images RLE compression can be activated with the
843 "compress" parameter, the "idstring" parameter can be used to set the
844 Targa comment field and the "wierdpack" option can be used to use the
845 15 and 16 bit Targa formats for RGB and RGBA data. The 15 bit format
846 has 5 of each red, green and blue. The 16 bit format in addition
847 allows 1 bit of alpha. The most significant bits are used for each
848 channel.
849 Tags:
851 tga_idstring
853 tga_bitspp
854 compressed
855 RAW
857 When reading raw images you need to supply the width and height of the
858 image in the "xsize" and "ysize" options:
859 $img->read(file=>'foo.raw', xsize=>100, ysize=>100)
861 or die "Cannot read raw image\n";
862 If your input file has more channels than you want, or (as is common),
864 junk in the fourth channel, you can use the "datachannels" and
865 "storechannels" options to control the number of channels in your input
866 file and the resulting channels in your image. For example, if your
867 input image uses 32-bits per pixel with red, green, blue and junk
868 values for each pixel you could do:
869 $img->read(file=>'foo.raw', xsize=>100, ysize=>100, datachannels=>4,
871 storechannels=>3)
872 or die "Cannot read raw image\n";
873 Read parameters:
875 · raw_interleave - controls the ordering of samples within the image.
877 Default: 1. Alternatively and historically spelled "interleave".
878 Possible values:
879 · 0 - samples are pixel by pixel, so all samples for the first
881 pixel, then all samples for the second pixel and so on. eg.
882 for a four pixel scan line the channels would be laid out as:
883 012012012012
885 · 1 - samples are line by line, so channel 0 for the entire scan
887 line is followed by channel 1 for the entire scan line and so
888 on. eg. for a four pixel scan line the channels would be laid
889 out as:
890 000011112222
892 This is the default.
894 Unfortunately, historically, the default "raw_interleave" for read
896 has been 1, while writing only supports the "raw_interleave" = 0
897 format.
898 For future compatibility, you should always supply the
900 "raw_interleave" (or "interleave") parameter. As of 0.68, Imager
901 will warn if you attempt to read a raw image without a
902 "raw_interleave" parameter.
903 · raw_storechannels - the number of channels to store in the image.
905 Range: 1 to 4. Default: 3. Alternatively and historically spelled
906 "storechannels".
907 · raw_datachannels - the number of channels to read from the file.
909 Range: 1 or more. Default: 3. Alternatively and historically
910 spelled "datachannels".
911 $img->read(file=>'foo.raw', xsize=100, ysize=>100, raw_interleave=>1)
913 or die "Cannot read raw image\n";
914 PNG
916 There are no PNG specific tags.
917 ICO (Microsoft Windows Icon) and CUR (Microsoft Windows Cursor)
919 Icon and Cursor files are very similar, the only differences being a
920 number in the header and the storage of the cursor hot spot. I've
921 treated them separately so that you're not messing with tags to
922 distinguish between them.
923 The following tags are set when reading an icon image and are used when
925 writing it:
926 ico_mask
928 This is the AND mask of the icon. When used as an icon in Windows
929 1 bits in the mask correspond to pixels that are modified by the
930 source image rather than simply replaced by the source image.
931 Rather than requiring a binary bitmap this is accepted in a
933 specific format:
934 · first line consisting of the 0 placeholder, the 1 placeholder
936 and a newline.
937 · following lines which contain 0 and 1 placeholders for each
939 scan line of the image, starting from the top of the image.
940 When reading an image, '.' is used as the 0 placeholder and '*' as
942 the 1 placeholder. An example:
943 .*
945 ..........................******
946 ..........................******
947 ..........................******
948 ..........................******
949 ...........................*****
950 ............................****
951 ............................****
952 .............................***
953 .............................***
954 .............................***
955 .............................***
956 ..............................**
957 ..............................**
958 ...............................*
959 ...............................*
960 ................................
961 ................................
962 ................................
963 ................................
964 ................................
965 ................................
966 *...............................
967 **..............................
968 **..............................
969 ***.............................
970 ***.............................
971 ****............................
972 ****............................
973 *****...........................
974 *****...........................
975 *****...........................
976 *****...........................
977 The following tags are set when reading an icon:
979 ico_bits
981 The number of bits per pixel used to store the image.
982 For cursor files the following tags are set and read when reading and
984 writing:
985 cur_mask
987 This is the same as the ico_mask above.
988 cur_hotspotx
990 cur_hotspoty
991 The "hot" spot of the cursor image. This is the spot on the cursor
992 that you click with. If you set these to out of range values they
993 are clipped to the size of the image when written to the file.
994 The following parameters can be supplied to read() or read_multi() to
996 control reading of ICO/CUR files:
997 · ico_masked - if true, the default, then the icon/cursors mask is
999 applied as an alpha channel to the image. This may result in a
1000 paletted image being returned as a direct color image. Default: 1
1001 # retrieve the image as stored, without using the mask as an alpha
1003 # channel
1004 $img->read(file => 'foo.ico', ico_masked => 0)
1005 or die $img->errstr;
1006 This was introduced in Imager 0.60. Previously reading ICO images
1008 acted as if "ico_masked => 0".
1009 "cur_bits" is set when reading a cursor.
1011 Examples:
1013 my $img = Imager->new(xsize => 32, ysize => 32, channels => 4);
1015 $im->box(color => 'FF0000');
1016 $im->write(file => 'box.ico');
1017 $im->settag(name => 'cur_hotspotx', value => 16);
1019 $im->settag(name => 'cur_hotspoty', value => 16);
1020 $im->write(file => 'box.cur');
1021 SGI (RGB, BW)
1023 SGI images, often called by the extensions, RGB or BW, can be stored
1024 either uncompressed or compressed using an RLE compression.
1025 By default, when saving to an extension of "rgb", "bw", "sgi", "rgba"
1027 the file will be saved in SGI format. The file extension is otherwise
1028 ignored, so saving a 3-channel image to a ".bw" file will result in a
1029 3-channel image on disk.
1030 The following tags are set when reading a SGI image:
1032 · i_comment - the "IMAGENAME" field from the image. Also written to
1034 the file when writing.
1035 · sgi_pixmin, sgi_pixmax - the "PIXMIN" and "PIXMAX" fields from the
1037 image. On reading image data is expanded from this range to the
1038 full range of samples in the image.
1039 · sgi_bpc - the number of bytes per sample for the image. Ignored
1041 when writing.
1042 · sgi_rle - whether or not the image is compressed. If this is non-
1044 zero when writing the image will be compressed.
1045
1047 To support a new format for reading, call the register_reader() class
1048 method:
1049 register_reader()
1051 Registers single or multiple image read functions.
1052 Parameters:
1054 · type - the identifier of the file format, if Imager's
1056 i_test_format_probe() can identify the format then this value
1057 should match i_test_format_probe()'s result.
1058 This parameter is required.
1060 · single - a code ref to read a single image from a file. This
1062 is supplied:
1063 · the object that read() was called on,
1065 · an Imager::IO object that should be used to read the file,
1067 and
1068 · all the parameters supplied to the read() method.
1070 The single parameter is required.
1072 · multiple - a code ref which is called to read multiple images
1074 from a file. This is supplied:
1075 · an Imager::IO object that should be used to read the file,
1077 and
1078 · all the parameters supplied to the read_multi() method.
1080 Example:
1082 # from Imager::File::ICO
1084 Imager->register_reader
1085 (
1086 type=>'ico',
1087 single =>
1088 sub {
1089 my ($im, $io, %hsh) = @_;
1090 $im->{IMG} = i_readico_single($io, $hsh{page} || 0);
1091 unless ($im->{IMG}) {
1093 $im->_set_error(Imager->_error_as_msg);
1094 return;
1095 }
1096 return $im;
1097 },
1098 multiple =>
1099 sub {
1100 my ($io, %hsh) = @_;
1101 my @imgs = i_readico_multi($io);
1103 unless (@imgs) {
1104 Imager->_set_error(Imager->_error_as_msg);
1105 return;
1106 }
1107 return map {
1108 bless { IMG => $_, DEBUG => $Imager::DEBUG, ERRSTR => undef }, 'Imager'
1109 } @imgs;
1110 },
1111 );
1112 register_writer()
1114 Registers single or multiple image write functions.
1115 Parameters:
1117 · type - the identifier of the file format. This is typically
1119 the extension in lowercase.
1120 This parameter is required.
1122 · single - a code ref to write a single image to a file. This is
1124 supplied:
1125 · the object that write() was called on,
1127 · an Imager::IO object that should be used to write the file,
1129 and
1130 · all the parameters supplied to the write() method.
1132 The single parameter is required.
1134 · multiple - a code ref which is called to write multiple images
1136 to a file. This is supplied:
1137 · the class name write_multi() was called on, this is
1139 typically "Imager".
1140 · an Imager::IO object that should be used to write the file,
1142 and
1143 · all the parameters supplied to the read_multi() method.
1145 If you name the reader module "Imager::File::"your-format-name where
1147 your-format-name is a fully upper case version of the type value you
1148 would pass to read(), read_multi(), write() or write_multi() then
1149 Imager will attempt to load that module if it has no other way to read
1150 or write that format.
1151 For example, if you create a module Imager::File::GIF and the user has
1153 built Imager without it's normal GIF support then an attempt to read a
1154 GIF image will attempt to load Imager::File::GIF.
1155 If your module can only handle reading then you can name your module
1157 "Imager::File::"your-format-name"Reader" and Imager will attempt to
1158 autoload it.
1159 If your module can only handle writing then you can name your module
1161 "Imager::File::"your-format-name"Writer" and Imager will attempt to
1162 autoload it.
1163
1165 preload()
1166 This preloads the file support modules included with or that have
1167 been included with Imager in the past. This is intended for use in
1168 forking servers such as mod_perl.
1169 If the module is not available no error occurs.
1171 Preserves $@.
1173 use Imager;
1175 Imager->preload;
1176
1178 Producing an image from a CGI script
1179 Once you have an image the basic mechanism is:
1180 1. set STDOUT to autoflush
1182 2. output a content-type header, and optionally a content-length
1184 header
1185 3. put STDOUT into binmode
1187 4. call write() with the "fd" or "fh" parameter. You will need to
1189 provide the "type" parameter since Imager can't use the extension
1190 to guess the file format you want.
1191 # write an image from a CGI script
1193 # using CGI.pm
1194 use CGI qw(:standard);
1195 $| = 1;
1196 binmode STDOUT;
1197 print header(-type=>'image/gif');
1198 $img->write(type=>'gif', fd=>fileno(STDOUT))
1199 or die $img->errstr;
1200 If you want to send a content length you can send the output to a
1202 scalar to get the length:
1203 my $data;
1205 $img->write(type=>'gif', data=>\$data)
1206 or die $img->errstr;
1207 binmode STDOUT;
1208 print header(-type=>'image/gif', -content_length=>length($data));
1209 print $data;
1210 Writing an animated GIF
1212 The basic idea is simple, just use write_multi():
1213 my @imgs = ...;
1215 Imager->write_multi({ file=>$filename, type=>'gif' }, @imgs);
1216 If your images are RGB images the default quantization mechanism will
1218 produce a very good result, but can take a long time to execute. You
1219 could either use the standard web color map:
1220 Imager->write_multi({ file=>$filename,
1222 type=>'gif',
1223 make_colors=>'webmap' },
1224 @imgs);
1225 or use a median cut algorithm to built a fairly optimal color map:
1227 Imager->write_multi({ file=>$filename,
1229 type=>'gif',
1230 make_colors=>'mediancut' },
1231 @imgs);
1232 By default all of the images will use the same global color map, which
1234 will produce a smaller image. If your images have significant color
1235 differences, you may want to generate a new palette for each image:
1236 Imager->write_multi({ file=>$filename,
1238 type=>'gif',
1239 make_colors=>'mediancut',
1240 gif_local_map => 1 },
1241 @imgs);
1242 which will set the "gif_local_map" tag in each image to 1.
1244 Alternatively, if you know only some images have different colors, you
1245 can set the tag just for those images:
1246 $imgs[2]->settag(name=>'gif_local_map', value=>1);
1248 $imgs[4]->settag(name=>'gif_local_map', value=>1);
1249 and call write_multi() without a "gif_local_map" parameter, or supply
1251 an arrayref of values for the tag:
1252 Imager->write_multi({ file=>$filename,
1254 type=>'gif',
1255 make_colors=>'mediancut',
1256 gif_local_map => [ 0, 0, 1, 0, 1 ] },
1257 @imgs);
1258 Other useful parameters include "gif_delay" to control the delay
1260 between frames and "transp" to control transparency.
1261 Reading tags after reading an image
1263 This is pretty simple:
1264 # print the author of a TIFF, if any
1266 my $img = Imager->new;
1267 $img->read(file=>$filename, type='tiff') or die $img->errstr;
1268 my $author = $img->tags(name=>'tiff_author');
1269 if (defined $author) {
1270 print "Author: $author\n";
1271 }
1272
1274 When saving GIF images the program does NOT try to shave off extra
1275 colors if it is possible. If you specify 128 colors and there are only
1276 2 colors used - it will have a 128 color table anyway.
1277
1279 Imager(3)
1280perl v5.12.3 2011-08-28 Imager::Files(3)