1Imager::Files(3) User Contributed Perl Documentation Imager::Files(3)
2
3
4
6 Imager::Files - working with image files
7
9 my $img = ...;
10 $img->write(file=>$filename, type=>$type)
11 or die "Cannot write: ",$img->errstr;
12
13 $img = Imager->new;
14 $img->read(file=>$filename, type=>$type)
15 or die "Cannot read: ", $img->errstr;
16
17 Imager->write_multi({ file=> $filename, ... }, @images)
18 or die "Cannot write: ", Imager->errstr;
19
20 my @imgs = Imager->read_multi(file=>$filename)
21 or die "Cannot read: ", Imager->errstr;
22
23 Imager->set_file_limits(width=>$max_width, height=>$max_height)
24
25 my @read_types = Imager->read_types;
26 my @write_types = Imager->write_types;
27
29 You can read and write a variety of images formats, assuming you have
30 the appropriate libraries, and images can be read or written to/from
31 files, file handles, file descriptors, scalars, or through callbacks.
32
33 To see which image formats Imager is compiled to support the following
34 code snippet is sufficient:
35
36 use Imager;
37 print join " ", keys %Imager::formats;
38
39 This will include some other information identifying libraries rather
40 than file formats. For new code you might find the "read_types" or
41 "write_types" methods useful.
42
43 read
44 Reading writing to and from files is simple, use the "read()"
45 method to read an image:
46
47 my $img = Imager->new;
48 $img->read(file=>$filename, type=>$type)
49 or die "Cannot read $filename: ", $img->errstr;
50
51 In most cases Imager can auto-detect the file type, so you can just
52 supply the filename:
53
54 $img->read(file => $filename)
55 or die "Cannot read $filename: ", $img->errstr;
56
57 The read() method accepts the "allow_partial" parameter. If this
58 is non-zero then read() can return true on an incomplete image and
59 set the "i_incomplete" tag.
60
61 write
62 and the "write()" method to write an image:
63
64 $img->write(file=>$filename, type=>$type)
65 or die "Cannot write $filename: ", $img->errstr;
66
67 read_multi
68 If you're reading from a format that supports multiple images per
69 file, use the "read_multi()" method:
70
71 my @imgs = Imager->read_multi(file=>$filename, type=>$type)
72 or die "Cannot read $filename: ", Imager->errstr;
73
74 As with the read() method, Imager will normally detect the "type"
75 automatically.
76
77 write_multi
78 and if you want to write multiple images to a single file use the
79 "write_multi()" method:
80
81 Imager->write_multi({ file=> $filename, type=>$type }, @images)
82 or die "Cannot write $filename: ", Imager->errstr;
83
84 read_types
85 This is a class method that returns a list of the image file types
86 that Imager can read.
87
88 my @types = Imager->read_types;
89
90 These types are the possible values for the "type" parameter, not
91 necessarily the extension of the files you're reading.
92
93 It is possible for extra file read handlers to be loaded when
94 attempting to read a file, which may modify the list of available
95 read types.
96
97 write_types
98 This is a class method that returns a list of the image file types
99 that Imager can write.
100
101 my @types = Imager->write_types;
102
103 Note that these are the possible values for the "type" parameter,
104 not necessarily the extension of the files you're writing.
105
106 It is possible for extra file write handlers to be loaded when
107 attempting to write a file, which may modify the list of available
108 write types.
109
110 When writing, if the filename includes an extension that Imager recog‐
111 nizes, then you don't need the type, but you may want to provide one
112 anyway. See "Guessing types" for information on controlling this
113 recognition.
114
115 The "type" parameter is a lowercase representation of the file type,
116 and can be any of the following:
117
118 bmp Windows BitMaP (BMP)
119 gif Graphics Interchange Format (GIF)
120 jpeg JPEG/JFIF
121 png Portable Network Graphics (PNG)
122 pnm Portable aNyMap (PNM)
123 raw Raw
124 sgi SGI .rgb files
125 tga TARGA
126 tiff Tagged Image File Format (TIFF)
127
128 When you read an image, Imager may set some tags, possibly including
129 information about the spatial resolution, textual information, and ani‐
130 mation information. See "Tags" in Imager::ImageTypes for specifics.
131
132 The open() method is a historical alias for the read() method.
133
134 Input and output
135
136 When reading or writing you can specify one of a variety of sources or
137 targets:
138
139 · file - The "file" parameter is the name of the image file to be
140 written to or read from. If Imager recognizes the extension of the
141 file you do not need to supply a "type".
142
143 # write in tiff format
144 $image->write(file => "example.tif")
145 or die $image->errstr;
146
147 $image->write(file => 'foo.tmp', type => 'tiff')
148 or die $image->errstr;
149
150 my $image = Imager->new;
151 $image->read(file => 'example.tif')
152 or die $image->errstr;
153
154 · fh - "fh" is a file handle, typically either returned from
155 "<IO::File-"new()>>, or a glob from an "open" call. You should
156 call "binmode" on the handle before passing it to Imager.
157
158 Imager will set the handle to autoflush to make sure any buffered
159 data is flushed , since Imager will write to the file descriptor
160 (from fileno()) rather than writing at the perl level.
161
162 $image->write(fh => \*STDOUT, type => 'gif')
163 or die $image->errstr;
164
165 # for example, a file uploaded via CGI.pm
166 $image->read(fd => $cgi->param('file'))
167 or die $image->errstr;
168
169 · fd - "fd" is a file descriptor. You can get this by calling the
170 "fileno()" function on a file handle, or by using one of the stan‐
171 dard file descriptor numbers.
172
173 If you get this from a perl file handle, you may need to flush any
174 buffered output, otherwise it may appear in the output stream after
175 the image.
176
177 $image->write(fd => file(STDOUT), type => 'gif')
178 or die $image->errstr;
179
180 · data - When reading data, "data" is a scalar containing the image
181 file data, when writing, "data" is a reference to the scalar to
182 save the image file data too. For GIF images you will need giflib
183 4 or higher, and you may need to patch giflib to use this option
184 for writing.
185
186 my $data;
187 $image->write(data => \$data, type => 'tiff')
188 or die $image->errstr;
189
190 my $data = $row->{someblob}; # eg. from a database
191 my @images = Imager->read_multi(data => $data)
192 or die Imager->errstr;
193
194 · callback - Imager will make calls back to your supplied coderefs to
195 read, write and seek from/to/through the image file.
196
197 When reading from a file you can use either "callback" or "readcb"
198 to supply the read callback, and when writing "callback" or
199 "writecb" to supply the write callback.
200
201 When writing you can also supply the "maxbuffer" option to set the
202 maximum amount of data that will be buffered before your write
203 callback is called. Note: the amount of data supplied to your
204 callback can be smaller or larger than this size.
205
206 The read callback is called with 2 parameters, the minimum amount
207 of data required, and the maximum amount that Imager will store in
208 it's C level buffer. You may want to return the minimum if you
209 have a slow data source, or the maximum if you have a fast source
210 and want to prevent many calls to your perl callback. The read
211 data should be returned as a scalar.
212
213 Your write callback takes exactly one parameter, a scalar contain‐
214 ing the data to be written. Return true for success.
215
216 The seek callback takes 2 parameters, a POSITION, and a WHENCE,
217 defined in the same way as perl's seek function.
218
219 You can also supply a "closecb" which is called with no parameters
220 when there is no more data to be written. This could be used to
221 flush buffered data.
222
223 # contrived
224 my $data;
225 sub mywrite {
226 $data .= unpack("H*", shift);
227 1;
228 }
229 Imager->write_multi({ callback => \&mywrite, type => 'gif'}, @images)
230 or die Imager->errstr;
231
232 Note that for reading you'll almost always need to provide a
233 "seekcb".
234
235 Guessing types
236
237 When writing to a file, if you don't supply a "type" parameter Imager
238 will attempt to guess it from the filename. This is done by calling
239 the code reference stored in $Imager::FORMATGUESS. This is only done
240 when write() or write_multi() is called with a "file" parameter.
241
242 The default function value of $Imager::FORMATGUESS is
243 "\&Imager::def_guess_type".
244
245 def_guess_type
246 This is the default function Imager uses to derive a file type from
247 a file name. This is a function, not a method.
248
249 Accepts a single parameter, the filename and returns the type or
250 undef.
251
252 You can replace function with your own implementation if you have some
253 specialized need. The function takes a single parameter, the name of
254 the file, and should return either a file type or under.
255
256 # I'm writing jpegs to weird filenames
257 local $Imager::FORMATGUESS = sub { 'jpeg' };
258
259 When reading a file Imager examines beginning of the file for identify‐
260 ing information. The current implementation attempts to detect the
261 following image types beyond those supported by Imager:
262
263 xpm, mng, jng, SGI RGB, ilbm, pcx, fits, psd (Photoshop), eps, Utah
264 RLE
265
266 Limiting the sizes of images you read
267
268 set_file_limits
269 In some cases you will be receiving images from an untested source,
270 such as submissions via CGI. To prevent such images from consuming
271 large amounts of memory, you can set limits on the dimensions of
272 images you read from files:
273
274 * width - limit the width in pixels of the image
275
276 * height - limit the height in pixels of the image
277
278 * bytes - limits the amount of storage used by the image. This
279 depends on the width, height, channels and sample size of the
280 image. For paletted images this is calculated as if the image
281 was expanded to a direct color image.
282
283 To set the limits, call the class method set_file_limits:
284
285 Imager->set_file_limits(width=>$max_width, height=>$max_height);
286
287 You can pass any or all of the limits above, any limits you do not
288 pass are left as they were.
289
290 Any limit of zero is treated as unlimited.
291
292 By default, all of the limits are zero, or unlimited.
293
294 You can reset all of the limited to their defaults by passing in
295 the reset parameter as a true value:
296
297 # no limits
298 Imager->set_file_limits(reset=>1);
299
300 This can be used with the other limits to reset all but the limit
301 you pass:
302
303 # only width is limited
304 Imager->set_file_limits(reset=>1, width=>100);
305
306 # only bytes is limited
307 Imager->set_file_limits(reset=>1, bytes=>10_000_000);
308
309 get_file_limits
310 You can get the current limits with the get_file_limits() method:
311
312 my ($max_width, $max_height, $max_bytes) =
313 Imager->get_file_limits();
314
316 The different image formats can write different image type, and some
317 have different options to control how the images are written.
318
319 When you call "write()" or "write_multi()" with an option that has the
320 same name as a tag for the image format you're writing, then the value
321 supplied to that option will be used to set the corresponding tag in
322 the image. Depending on the image format, these values will be used
323 when writing the image.
324
325 This replaces the previous options that were used when writing GIF
326 images. Currently if you use an obsolete option, it will be converted
327 to the equivalent tag and Imager will produced a warning. You can sup‐
328 press these warnings by calling the "Imager::init()" function with the
329 "warn_obsolete" option set to false:
330
331 Imager::init(warn_obsolete=>0);
332
333 At some point in the future these obsolete options will no longer be
334 supported.
335
336 PNM (Portable aNy Map)
337
338 Imager can write PGM (Portable Gray Map) and PPM (Portable PixMaps)
339 files, depending on the number of channels in the image. Currently the
340 images are written in binary formats. Only 1 and 3 channel images can
341 be written, including 1 and 3 channel paletted images.
342
343 $img->write(file=>'foo.ppm') or die $img->errstr;
344
345 Imager can read both the ASCII and binary versions of each of the PBM
346 (Portable BitMap), PGM and PPM formats.
347
348 $img->read(file=>'foo.ppm') or die $img->errstr;
349
350 PNM does not support the spatial resolution tags.
351
352 The following tags are set when reading a PNM file:
353
354 · pnm_maxval - the maxvals number from the PGM/PPM header. Always
355 set to 2 for a PBM file.
356
357 · pnm_type - the type number from the PNM header, 1 for ASCII PBM
358 files, 2 for ASCII PGM files, 3 for ASCII PPM files, 4 for binary
359 PBM files, 5 for binary PGM files, 6 for binary PPM files.
360
361 The following tag is checked when writing an image with more than
362 8-bits/sample:
363
364 · pnm_write_wide_data - if this is non-zero then write() can write
365 PGM/PPM files with 16-bits/sample. Some applications, for example
366 GIMP 2.2, and tools can only read 8-bit/sample binary PNM files, so
367 Imager will only write a 16-bit image when this tag is non-zero.
368
369 JPEG
370
371 You can supply a "jpegquality" parameter (0-100) when writing a JPEG
372 file, which defaults to 75%. If you write an image with an alpha chan‐
373 nel to a jpeg file then it will be composited against the background
374 set by the "i_background" parameter (or tag).
375
376 $img->write(file=>'foo.jpg', jpegquality=>90) or die $img->errstr;
377
378 Imager will read a grayscale JPEG as a 1 channel image and a color JPEG
379 as a 3 channel image.
380
381 $img->read(file=>'foo.jpg') or die $img->errstr;
382
383 The following tags are set in a JPEG image when read, and can be set to
384 control output:
385
386 jpeg_density_unit
387 The value of the density unit field in the JFIF header. This is
388 ignored on writing if the "i_aspect_only" tag is non-zero.
389
390 The "i_xres" and "i_yres" tags are expressed in pixels per inch no
391 matter the value of this tag, they will be converted to/from the
392 value stored in the JPEG file.
393
394 jpeg_density_unit_name
395 This is set when reading a JPEG file to the name of the unit given
396 by "jpeg_density_unit". Possible results include "inch", "centime‐
397 ter", "none" (the "i_aspect_only" tag is also set reading these
398 files). If the value of jpeg_density_unit is unknown then this tag
399 isn't set.
400
401 jpeg_comment
402 Text comment.
403
404 JPEG supports the spatial resolution tags "i_xres", "i_yres" and
405 "i_aspect_only".
406
407 If an APP1 block containing EXIF information is found, then any of the
408 following tags can be set:
409
410 exif_aperture exif_artist exif_brightness exif_color_space
411 exif_contrast exif_copyright exif_custom_rendered exif_date_time
412 exif_date_time_digitized exif_date_time_original exif_digi‐
413 tal_zoom_ratio exif_exposure_bias exif_exposure_index exif_expo‐
414 sure_mode exif_exposure_program exif_exposure_time exif_f_number
415 exif_flash exif_flash_energy exif_flashpix_version
416 exif_focal_length exif_focal_length_in_35mm_film
417 exif_focal_plane_resolution_unit exif_focal_plane_x_resolution
418 exif_focal_plane_y_resolution exif_gain_control exif_image_descrip‐
419 tion exif_image_unique_id exif_iso_speed_rating exif_make
420 exif_max_aperture exif_metering_mode exif_model exif_orientation
421 exif_related_sound_file exif_resolution_unit exif_saturation
422 exif_scene_capture_type exif_sensing_method exif_sharpness
423 exif_shutter_speed exif_software exif_spectral_sensitivity
424 exif_sub_sec_time exif_sub_sec_time_digitized
425 exif_sub_sec_time_original exif_subject_distance exif_subject_dis‐
426 tance_range exif_subject_location exif_tag_light_source
427 exif_user_comment exif_version exif_white_balance exif_x_resolution
428 exif_y_resolution
429
430 The following derived tags can also be set:
431
432 exif_color_space_name exif_contrast_name exif_custom_rendered_name
433 exif_exposure_mode_name exif_exposure_program_name exif_flash_name
434 exif_focal_plane_resolution_unit_name exif_gain_control_name
435 exif_light_source_name exif_metering_mode_name exif_resolu‐
436 tion_unit_name exif_saturation_name exif_scene_capture_type_name
437 exif_sensing_method_name exif_sharpness_name exif_subject_dis‐
438 tance_range_name exif_white_balance_name
439
440 The derived tags are for enumerated fields, when the value for the base
441 field is valid then the text that appears in the EXIF specification for
442 that value appears in the derived field. So for example if "exf_meter‐
443 ing_mode" is 5 then "exif_metering_mode_name" is set to "Pattern".
444
445 eg.
446
447 my $image = Imager->new;
448 $image->read(file => 'exiftest.jpg')
449 or die "Cannot load image: ", $image->errstr;
450 print $image->tags(name => "exif_image_description"), "\n";
451 print $image->tags(name => "exif_exposure_mode"), "\n";
452 print $image->tags(name => "exif_exposure_mode_name"), "\n";
453
454 # for the exiftest.jpg in the Imager distribution the output would be:
455 Imager Development Notes
456 0
457 Auto exposure
458
459 parseiptc
460 Historically, Imager saves IPTC data when reading a JPEG image, the
461 parseiptc() method returns a list of key/value pairs resulting from
462 a simple decoding of that data.
463
464 Any future IPTC data decoding is likely to go into tags.
465
466 GIF (Graphics Interchange Format)
467
468 When writing one of more GIF images you can use the same Quantization
469 Options as you can when converting an RGB image into a paletted image.
470
471 When reading a GIF all of the sub-images are combined using the screen
472 size and image positions into one big image, producing an RGB image.
473 This may change in the future to produce a paletted image where possi‐
474 ble.
475
476 When you read a single GIF with "$img->read()" you can supply a refer‐
477 ence to a scalar in the "colors" parameter, if the image is read the
478 scalar will be filled with a reference to an anonymous array of
479 Imager::Color objects, representing the palette of the image. This
480 will be the first palette found in the image. If you want the palettes
481 for each of the images in the file, use "read_multi()" and use the
482 "getcolors()" method on each image.
483
484 GIF does not support the spatial resolution tags.
485
486 Imager will set the following tags in each image when reading, and can
487 use most of them when writing to GIF:
488
489 · gif_left - the offset of the image from the left of the "screen"
490 ("Image Left Position")
491
492 · gif_top - the offset of the image from the top of the "screen"
493 ("Image Top Position")
494
495 · gif_interlace - non-zero if the image was interlaced ("Interlace
496 Flag")
497
498 · gif_screen_width, gif_screen_height - the size of the logical
499 screen. When writing this is used as the minimum. If any image
500 being written would extend beyond this then the screen size is
501 extended. ("Logical Screen Width", "Logical Screen Height").
502
503 · gif_local_map - Non-zero if this image had a local color map. If
504 set for an image when writing the image is quantized separately
505 from the other images in the file.
506
507 · gif_background - The index in the global colormap of the logical
508 screen's background color. This is only set if the current image
509 uses the global colormap. You can set this on write too, but for
510 it to choose the color you want, you will need to supply only
511 paletted images and set the "gif_eliminate_unused" tag to 0.
512
513 · gif_trans_index - The index of the color in the colormap used for
514 transparency. If the image has a transparency then it is returned
515 as a 4 channel image with the alpha set to zero in this palette
516 entry. This value is not used when writing. ("Transparent Color
517 Index")
518
519 · gif_trans_color - A reference to an Imager::Color object, which is
520 the colour to use for the palette entry used to represent trans‐
521 parency in the palette. You need to set the transp option (see
522 "Quantization options") for this value to be used.
523
524 · gif_delay - The delay until the next frame is displayed, in 1/100
525 of a second. ("Delay Time").
526
527 · gif_user_input - whether or not a user input is expected before
528 continuing (view dependent) ("User Input Flag").
529
530 · gif_disposal - how the next frame is displayed ("Disposal Method")
531
532 · gif_loop - the number of loops from the Netscape Loop extension.
533 This may be zero to loop forever.
534
535 · gif_comment - the first block of the first gif comment before each
536 image.
537
538 · gif_eliminate_unused - If this is true, when you write a paletted
539 image any unused colors will be eliminated from its palette. This
540 is set by default.
541
542 · gif_colormap_size - the original size of the color map for the
543 image. The color map of the image may have been expanded to
544 include out of range color indexes.
545
546 Where applicable, the ("name") is the name of that field from the GIF89
547 standard.
548
549 The following gif writing options are obsolete, you should set the cor‐
550 responding tag in the image, either by using the tags functions, or by
551 supplying the tag and value as options.
552
553 · gif_each_palette - Each image in the gif file has it's own palette
554 if this is non-zero. All but the first image has a local colour
555 table (the first uses the global colour table.
556
557 Use "gif_local_map" in new code.
558
559 · interlace - The images are written interlaced if this is non-zero.
560
561 Use "gif_interlace" in new code.
562
563 · gif_delays - A reference to an array containing the delays between
564 images, in 1/100 seconds.
565
566 Use "gif_delay" in new code.
567
568 · gif_positions - A reference to an array of references to arrays
569 which represent screen positions for each image.
570
571 New code should use the "gif_left" and "gif_top" tags.
572
573 · gif_loop_count - If this is non-zero the Netscape loop extension
574 block is generated, which makes the animation of the images repeat.
575
576 This is currently unimplemented due to some limitations in giflib.
577
578 You can supply a "page" parameter to the "read()" method to read some
579 page other than the first. The page is 0 based:
580
581 # read the second image in the file
582 $image->read(file=>"example.gif", page=>1)
583 or die "Cannot read second page: ",$image->errstr,"\n";
584
585 Before release 0.46, Imager would read multi-image GIF image files into
586 a single image, overlaying each of the images onto the virtual GIF
587 screen.
588
589 As of 0.46 the default is to read the first image from the file, as if
590 called with "page => 0".
591
592 You can return to the previous behaviour by calling read with the
593 "gif_consolidate" parameter set to a true value:
594
595 $img->read(file=>$some_gif_file, gif_consolidate=>1);
596
597 TIFF (Tagged Image File Format)
598
599 Imager can write images to either paletted or RGB TIFF images, depend‐
600 ing on the type of the source image. Currently if you write a
601 16-bit/sample or double/sample image it will be written as an
602 8-bit/sample image. Only 1 or 3 channel images can be written.
603
604 If you are creating images for faxing you can set the class parameter
605 set to "fax". By default the image is written in fine mode, but this
606 can be overridden by setting the fax_fine parameter to zero. Since a
607 fax image is bi-level, Imager uses a threshold to decide if a given
608 pixel is black or white, based on a single channel. For greyscale
609 images channel 0 is used, for color images channel 1 (green) is used.
610 If you want more control over the conversion you can use
611 $img->to_paletted() to product a bi-level image. This way you can use
612 dithering:
613
614 my $bilevel = $img->to_paletted(make_colors => 'mono',
615 translate => 'errdiff',
616 errdiff => 'stucki');
617
618 class
619 If set to 'fax' the image will be written as a bi-level fax image.
620
621 fax_fine
622 By default when class is set to 'fax' the image is written in fine
623 mode, you can select normal mode by setting fax_fine to 0.
624
625 Imager should be able to read any TIFF image you supply. Paletted TIFF
626 images are read as paletted Imager images, since paletted TIFF images
627 have 16-bits/sample (48-bits/color) this means the bottom 8-bits are
628 lost, but this shouldn't be a big deal. Currently all direct color
629 images are read at 8-bits/sample.
630
631 TIFF supports the spatial resolution tags. See the "tiff_resolutio‐
632 nunit" tag for some extra options.
633
634 As of Imager 0.62 Imager reads:
635
636 · 16-bit grey, RGB, or CMYK image, including a possible alpha channel
637 as a 16-bit/sample image.
638
639 · 32-bit grey, RGB image, including a possible alpha channel as a
640 double/sample image.
641
642 · bi-level images as paletted images containing only black and white,
643 which other formats will also write as bi-level.
644
645 · tiled paletted images are now handled correctly
646
647 The following tags are set in a TIFF image when read, and can be set to
648 control output:
649
650 tiff_compression
651 When reading an image this is set to the numeric value of the TIFF
652 compression tag.
653
654 On writing you can set this to either a numeric compression tag
655 value, or one of the following values:
656
657 Ident Number Description
658 none 1 No compression
659 packbits 32773 Macintosh RLE
660 ccittrle 2 CCITT RLE
661 fax3 3 CCITT Group 3 fax encoding (T.4)
662 t4 3 As above
663 fax4 4 CCITT Group 4 fax encoding (T.6)
664 t6 4 As above
665 lzw 5 LZW
666 jpeg 7 JPEG
667 zip 8 Deflate (GZIP) Non-standard
668 deflate 8 As above.
669 oldzip 32946 Deflate with an older code.
670 ccittrlew 32771 Word aligned CCITT RLE
671
672 In general a compression setting will be ignored where it doesn't
673 make sense, eg. "jpeg" will be ignored for compression if the image
674 is being written as bilevel.
675
676 Imager attempts to check that your build of libtiff supports the
677 given compression, and will fallback to "packbits" if it isn't
678 enabled. eg. older distributions didn't include LZW compression,
679 and JPEG compression is only available if libtiff is configured
680 with libjpeg's location.
681
682 $im->write(file => 'foo.tif', tiff_compression => 'lzw')
683 or die $im->errstr;
684
685 tiff_jpegquality
686 If tiff_compression if "jpeg" then this can be a number from 1 to
687 100 giving the JPEG compression quality. High values are better
688 quality and larger files.
689
690 tiff_resolutionunit
691 The value of the ResolutionUnit tag. This is ignored on writing if
692 the i_aspect_only tag is non-zero.
693
694 The "i_xres" and "i_yres" tags are expressed in pixels per inch no
695 matter the value of this tag, they will be converted to/from the
696 value stored in the TIFF file.
697
698 tiff_resolutionunit_name
699 This is set when reading a TIFF file to the name of the unit given
700 by "tiff_resolutionunit". Possible results include "inch", "cen‐
701 timeter", "none" (the "i_aspect_only" tag is also set reading these
702 files) or "unknown".
703
704 tiff_bitspersample
705 Bits per sample from the image. This value is not used when writ‐
706 ing an image, it is only set on a read image.
707
708 tiff_photometric
709 Value of the PhotometricInterpretation tag from the image. This
710 value is not used when writing an image, it is only set on a read
711 image.
712
713 tiff_documentname
714 tiff_imagedescription
715 tiff_make
716 tiff_model
717 tiff_pagename
718 tiff_software
719 tiff_datetime
720 tiff_artist
721 tiff_hostcomputer
722 Various strings describing the image. tiff_datetime must be for‐
723 matted as "YYYY:MM:DD HH:MM:SS". These correspond directly to the
724 mixed case names in the TIFF specification. These are set in
725 images read from a TIFF and saved when writing a TIFF image.
726
727 You can supply a "page" parameter to the "read()" method to read some
728 page other than the first. The page is 0 based:
729
730 # read the second image in the file
731 $image->read(file=>"example.tif", page=>1)
732 or die "Cannot read second page: ",$image->errstr,"\n";
733
734 Note: Imager uses the TIFF*RGBA* family of libtiff functions, unfortu‐
735 nately these don't support alpha channels on CMYK images. This will
736 result in a full coverage alpha channel on CMYK images with an alpha
737 channel, until this is implemented in libtiff (or Imager's TIFF imple‐
738 mentation changes.)
739
740 If you read an image with multiple alpha channels, then only the first
741 alpha channel will be read.
742
743 Currently Imager's TIFF support reads all direct color images as 8-bit
744 RGB images, this may change in the future to reading 16-bit/sample
745 images.
746
747 Currently tags that control the output color type and compression are
748 ignored when writing, this may change in the future. If you have pro‐
749 cesses that rely upon Imager always producing packbits compressed RGB
750 images, you should strip any tags before writing.
751
752 BMP (BitMaP)
753
754 Imager can write 24-bit RGB, and 8, 4 and 1-bit per pixel paletted Win‐
755 dows BMP files. Currently you cannot write compressed BMP files with
756 Imager.
757
758 Imager can read 24-bit RGB, and 8, 4 and 1-bit perl pixel paletted Win‐
759 dows BMP files. There is some support for reading 16-bit per pixel
760 images, but I haven't found any for testing.
761
762 BMP has no support for multi-image files.
763
764 BMP files support the spatial resolution tags, but since BMP has no
765 support for storing only an aspect ratio, if "i_aspect_only" is set
766 when you write the "i_xres" and "i_yres" values are scaled so the
767 smaller is 72 DPI.
768
769 The following tags are set when you read an image from a BMP file:
770
771 bmp_compression
772 The type of compression, if any. This can be any of the following
773 values:
774
775 BI_RGB (0)
776 Uncompressed.
777
778 BI_RLE8 (1)
779 8-bits/pixel paletted value RLE compression.
780
781 BI_RLE4 (2)
782 4-bits/pixel paletted value RLE compression.
783
784 BI_BITFIELDS (3)
785 Packed RGB values.
786
787 bmp_compression_name
788 The bmp_compression value as a BI_* string
789
790 bmp_important_colors
791 The number of important colors as defined by the writer of the
792 image.
793
794 bmp_used_colors
795 Number of color used from the BMP header
796
797 bmp_filesize
798 The file size from the BMP header
799
800 bmp_bit_count
801 Number of bits stored per pixel. (24, 8, 4 or 1)
802
803 TGA (TarGA)
804
805 When storing targa images rle compression can be activated with the
806 'compress' parameter, the 'idstring' parameter can be used to set the
807 targa comment field and the 'wierdpack' option can be used to use the
808 15 and 16 bit targa formats for rgb and rgba data. The 15 bit format
809 has 5 of each red, green and blue. The 16 bit format in addition
810 allows 1 bit of alpha. The most significant bits are used for each
811 channel.
812
813 Tags:
814
815 tga_idstring
816 tga_bitspp
817 compressed
818
819 RAW
820
821 When reading raw images you need to supply the width and height of the
822 image in the xsize and ysize options:
823
824 $img->read(file=>'foo.raw', xsize=>100, ysize=>100)
825 or die "Cannot read raw image\n";
826
827 If your input file has more channels than you want, or (as is common),
828 junk in the fourth channel, you can use the datachannels and storechan‐
829 nels options to control the number of channels in your input file and
830 the resulting channels in your image. For example, if your input image
831 uses 32-bits per pixel with red, green, blue and junk values for each
832 pixel you could do:
833
834 $img->read(file=>'foo.raw', xsize=>100, ysize=>100, datachannels=>4,
835 storechannels=>3)
836 or die "Cannot read raw image\n";
837
838 Normally the raw image is expected to have the value for channel 1
839 immediately following channel 0 and channel 2 immediately following
840 channel 1 for each pixel. If your input image has all the channel 0
841 values for the first line of the image, followed by all the channel 1
842 values for the first line and so on, you can use the interleave option:
843
844 $img->read(file=>'foo.raw', xsize=100, ysize=>100, interleave=>1)
845 or die "Cannot read raw image\n";
846
847 PNG
848
849 There are no PNG specific tags.
850
851 ICO (Microsoft Windows Icon) and CUR (Microsoft Windows Cursor)
852
853 Icon and Cursor files are very similar, the only differences being a
854 number in the header and the storage of the cursor hotspot. I've
855 treated them separately so that you're not messing with tags to distin‐
856 guish between them.
857
858 The following tags are set when reading an icon image and are used when
859 writing it:
860
861 ico_mask
862 This is the AND mask of the icon. When used as an icon in Windows
863 1 bits in the mask correspond to pixels that are modified by the
864 source image rather than simply replaced by the source image.
865
866 Rather than requiring a binary bitmap this is accepted in a spe‐
867 cific format:
868
869 * first line consisting of the 0 placeholder, the 1 placeholder
870 and a newline.
871
872 * following lines which contain 0 and 1 placeholders for each
873 scanline of the image, starting from the top of the image.
874
875 When reading an image, '.' is used as the 0 placeholder and '*' as
876 the 1 placeholder. An example:
877
878 .*
879 ..........................******
880 ..........................******
881 ..........................******
882 ..........................******
883 ...........................*****
884 ............................****
885 ............................****
886 .............................***
887 .............................***
888 .............................***
889 .............................***
890 ..............................**
891 ..............................**
892 ...............................*
893 ...............................*
894 ................................
895 ................................
896 ................................
897 ................................
898 ................................
899 ................................
900 *...............................
901 **..............................
902 **..............................
903 ***.............................
904 ***.............................
905 ****............................
906 ****............................
907 *****...........................
908 *****...........................
909 *****...........................
910 *****...........................
911
912 The following tags are set when reading an icon:
913
914 ico_bits
915 The number of bits per pixel used to store the image.
916
917 For cursor files the following tags are set and read when reading and
918 writing:
919
920 cur_mask
921 This is the same as the ico_mask above.
922
923 cur_hotspotx
924 cur_hotspoty
925 The "hot" spot of the cursor image. This is the spot on the cursor
926 that you click with. If you set these to out of range values they
927 are clipped to the size of the image when written to the file.
928
929 The following parameters can be supplied to read() or read_multi() to
930 control reading of ICO/CUR files:
931
932 · ico_masked - if true, the default, then the icon/cursors mask is
933 applied as an alpha channel to the image. This may result in a
934 paletted image being returned as a direct color image. Default: 1
935
936 # retrieve the image as stored, without using the mask as an alpha
937 # channel
938 $img->read(file => 'foo.ico', ico_masked => 0)
939 or die $img->errstr;
940
941 This was introduced in Imager 0.60. Previously reading ICO images
942 acted as if "<ico_masked =" 0>>.
943
944 "cur_bits" is set when reading a cursor.
945
946 Examples:
947
948 my $img = Imager->new(xsize => 32, ysize => 32, channels => 4);
949 $im->box(color => 'FF0000');
950 $im->write(file => 'box.ico');
951
952 $im->settag(name => 'cur_hotspotx', value => 16);
953 $im->settag(name => 'cur_hotspoty', value => 16);
954 $im->write(file => 'box.cur');
955
956 SGI (RGB, BW)
957
958 SGI images, often called by the extensions, RGB or BW, can be stored
959 either uncompressed or compressed using an RLE compression.
960
961 By default, when saving to an extension of "rgb", "bw", "sgi", "rgba"
962 the file will be saved in SGI format. The file extension is otherwise
963 ignored, so saving a 3-channel image to a ".bw" file will result in a
964 3-channel image on disk.
965
966 The following tags are set when reading a SGI image:
967
968 · i_comment - the IMAGENAME field from the image. Also written to
969 the file when writing.
970
971 · sgi_pixmin, sgi_pixmax - the PIXMIN and PIXMAX fields from the
972 image. On reading image data is expanded from this range to the
973 full range of samples in the image.
974
975 · sgi_bpc - the number of bytes per sample for the image. Ignored
976 when writing.
977
978 · sgi_rle - whether or not the image is compressed. If this is non-
979 zero when writing the image will be compressed.
980
982 To support a new format for reading, call the register_reader() class
983 method:
984
985 register_reader
986 Registers single or multiple image read functions.
987
988 Parameters:
989
990 * type - the identifier of the file format, if Imager's
991 i_test_format_probe() can identify the format then this value
992 should match i_test_format_probe()'s result.
993
994 This parameter is required.
995
996 * single - a code ref to read a single image from a file. This
997 is supplied:
998
999 * the object that read() was called on,
1000
1001 * an Imager::IO object that should be used to read the file,
1002 and
1003
1004 * all the parameters supplied to the read() method.
1005
1006 The single parameter is required.
1007
1008 * multiple - a code ref which is called to read multiple images
1009 from a file. This is supplied:
1010
1011 * an Imager::IO object that should be used to read the file,
1012 and
1013
1014 * all the parameters supplied to the read_multi() method.
1015
1016 Example:
1017
1018 # from Imager::File::ICO
1019 Imager->register_reader
1020 (
1021 type=>'ico',
1022 single =>
1023 sub {
1024 my ($im, $io, %hsh) = @_;
1025 $im->{IMG} = i_readico_single($io, $hsh{page} ⎪⎪ 0);
1026
1027 unless ($im->{IMG}) {
1028 $im->_set_error(Imager->_error_as_msg);
1029 return;
1030 }
1031 return $im;
1032 },
1033 multiple =>
1034 sub {
1035 my ($io, %hsh) = @_;
1036
1037 my @imgs = i_readico_multi($io);
1038 unless (@imgs) {
1039 Imager->_set_error(Imager->_error_as_msg);
1040 return;
1041 }
1042 return map {
1043 bless { IMG => $_, DEBUG => $Imager::DEBUG, ERRSTR => undef }, 'Imager'
1044 } @imgs;
1045 },
1046 );
1047
1048 register_writer
1049 Registers single or multiple image write functions.
1050
1051 Parameters:
1052
1053 * type - the identifier of the file format. This is typically
1054 the extension in lowercase.
1055
1056 This parameter is required.
1057
1058 * single - a code ref to write a single image to a file. This is
1059 supplied:
1060
1061 * the object that write() was called on,
1062
1063 * an Imager::IO object that should be used to write the file,
1064 and
1065
1066 * all the parameters supplied to the write() method.
1067
1068 The single parameter is required.
1069
1070 * multiple - a code ref which is called to write multiple images
1071 to a file. This is supplied:
1072
1073 * the class name write_multi() was called on, this is typi‐
1074 cally "Imager".
1075
1076 * an Imager::IO object that should be used to write the file,
1077 and
1078
1079 * all the parameters supplied to the read_multi() method.
1080
1081 If you name the reader module "Imager::File::"your-format-name where
1082 your-format-name is a fully upper case version of the type value you
1083 would pass to read(), read_multi(), write() or write_multi() then
1084 Imager will attempt to load that module if it has no other way to read
1085 or write that format.
1086
1087 For example, if you create a module Imager::File::GIF and the user has
1088 built Imager without it's normal GIF support then an attempt to read a
1089 GIF image will attempt to load Imager::File::GIF.
1090
1091 If your module can only handle reading then you can name your module
1092 "Imager::File::"your-format-name"Reader" and Imager will attempt to
1093 autoload it.
1094
1095 If your module can only handle writing then you can name your module
1096 "Imager::File::"your-format-name"Writer" and Imager will attempt to
1097 autoload it.
1098
1100 Producing an image from a CGI script
1101
1102 Once you have an image the basic mechanism is:
1103
1104 1. set STDOUT to autoflush
1105
1106 2. output a content-type header, and optionally a content-length
1107 header
1108
1109 3. put STDOUT into binmode
1110
1111 4. call write() with the "fd" or "fh" parameter. You will need to
1112 provide the "type" parameter since Imager can't use the extension
1113 to guess the file format you want.
1114
1115 # write an image from a CGI script
1116 # using CGI.pm
1117 use CGI qw(:standard);
1118 $⎪ = 1;
1119 binmode STDOUT;
1120 print header(-type=>'image/gif');
1121 $img->write(type=>'gif', fd=>fileno(STDOUT))
1122 or die $img->errstr;
1123
1124 If you want to send a content length you can send the output to a
1125 scalar to get the length:
1126
1127 my $data;
1128 $img->write(type=>'gif', data=>\$data)
1129 or die $img->errstr;
1130 binmode STDOUT;
1131 print header(-type=>'image/gif', -content_length=>length($data));
1132 print $data;
1133
1134 Writing an animated GIF
1135
1136 The basic idea is simple, just use write_multi():
1137
1138 my @imgs = ...;
1139 Imager->write_multi({ file=>$filename, type=>'gif' }, @imgs);
1140
1141 If your images are RGB images the default quantization mechanism will
1142 produce a very good result, but can take a long time to execute. You
1143 could either use the standard webmap:
1144
1145 Imager->write_multi({ file=>$filename,
1146 type=>'gif',
1147 make_colors=>'webmap' },
1148 @imgs);
1149
1150 or use a median cut algorithm to built a fairly optimal color map:
1151
1152 Imager->write_multi({ file=>$filename,
1153 type=>'gif',
1154 make_colors=>'mediancut' },
1155 @imgs);
1156
1157 By default all of the images will use the same global colormap, which
1158 will produce a smaller image. If your images have significant color
1159 differences, you may want to generate a new palette for each image:
1160
1161 Imager->write_multi({ file=>$filename,
1162 type=>'gif',
1163 make_colors=>'mediancut',
1164 gif_local_map => 1 },
1165 @imgs);
1166
1167 which will set the "gif_local_map" tag in each image to 1. Alterna‐
1168 tively, if you know only some images have different colors, you can set
1169 the tag just for those images:
1170
1171 $imgs[2]->settag(name=>'gif_local_map', value=>1);
1172 $imgs[4]->settag(name=>'gif_local_map', value=>1);
1173
1174 and call write_multi() without a "gif_local_map" parameter, or supply
1175 an arrayref of values for the tag:
1176
1177 Imager->write_multi({ file=>$filename,
1178 type=>'gif',
1179 make_colors=>'mediancut',
1180 gif_local_map => [ 0, 0, 1, 0, 1 ] },
1181 @imgs);
1182
1183 Other useful parameters include "gif_delay" to control the delay
1184 between frames and "transp" to control transparency.
1185
1186 Reading tags after reading an image
1187
1188 This is pretty simple:
1189
1190 # print the author of a TIFF, if any
1191 my $img = Imager->new;
1192 $img->read(file=>$filename, type='tiff') or die $img->errstr;
1193 my $author = $img->tags(name=>'tiff_author');
1194 if (defined $author) {
1195 print "Author: $author\n";
1196 }
1197
1199 When saving Gif images the program does NOT try to shave of extra col‐
1200 ors if it is possible. If you specify 128 colors and there are only 2
1201 colors used - it will have a 128 colortable anyway.
1202
1204 Imager(3)
1205
1206
1207
1208perl v5.8.8 2008-03-28 Imager::Files(3)