diff options
Diffstat (limited to 'Master/tlpkg/tlperl/lib/Imager/Files.pod')
| -rwxr-xr-x | Master/tlpkg/tlperl/lib/Imager/Files.pod | 1608 |
1 files changed, 1608 insertions, 0 deletions
diff --git a/Master/tlpkg/tlperl/lib/Imager/Files.pod b/Master/tlpkg/tlperl/lib/Imager/Files.pod new file mode 100755 index 00000000000..b7d612bf4d4 --- /dev/null +++ b/Master/tlpkg/tlperl/lib/Imager/Files.pod @@ -0,0 +1,1608 @@ +=head1 NAME + +Imager::Files - working with image files + +=head1 SYNOPSIS + + use Imager; + my $img = ...; + $img->write(file=>$filename, type=>$type) + or die "Cannot write: ",$img->errstr; + + # type is optional if we can guess the format from the filename + $img->write(file => "foo.png") + or die "Cannot write: ",$img->errstr; + + $img = Imager->new; + $img->read(file=>$filename, type=>$type) + or die "Cannot read: ", $img->errstr; + + # type is optional if we can guess the type from the file data + # and we normally can guess + $img->read(file => $filename) + or die "Cannot read: ", $img->errstr; + + Imager->write_multi({ file=> $filename, ... }, @images) + or die "Cannot write: ", Imager->errstr; + + my @imgs = Imager->read_multi(file=>$filename) + or die "Cannot read: ", Imager->errstr; + + Imager->set_file_limits(width=>$max_width, height=>$max_height) + + my @read_types = Imager->read_types; + my @write_types = Imager->write_types; + + # we can write/write_multi to things other than filenames + my $data; + $img->write(data => \$data, type => $type) or die; + + my $fh = ... ; # eg. IO::File + $img->write(fh => $fh, type => $type) or die; + + $img->write(fd => fileno($fh), type => $type) or die; + + # some file types need seek callbacks too + $img->write(callback => \&write_callback, type => $type) or die; + + # and similarly for read/read_multi + $img->read(data => $data) or die; + $img->read(fh => $fh) or die; + $img->read(fd => fileno($fh)) or die; + $img->read(callback => \&read_callback) or die; + + use Imager 0.68; + my $img = Imager->new(file => $filename) + or die Imager->errstr; + +=head1 DESCRIPTION + +You can read and write a variety of images formats, assuming you have +the appropriate libraries, and images can be read or written to/from +files, file handles, file descriptors, scalars, or through callbacks. + +To see which image formats Imager is compiled to support the following +code snippet is sufficient: + + use Imager; + print join " ", keys %Imager::formats; + +This will include some other information identifying libraries rather +than file formats. For new code you might find the L</read_types> or +L</write_types> methods useful. + +=over + +=item read + +Reading writing to and from files is simple, use the C<read()> +method to read an image: + + my $img = Imager->new; + $img->read(file=>$filename, type=>$type) + or die "Cannot read $filename: ", $img->errstr; + +In most cases Imager can auto-detect the file type, so you can just +supply the filename: + + $img->read(file => $filename) + or die "Cannot read $filename: ", $img->errstr; + +The read() method accepts the C<allow_partial> parameter. If this is +non-zero then read() can return true on an incomplete image and set +the C<i_incomplete> tag. + +From Imager 0.68 you can supply most read() parameters to the new() +method to read the image file on creation. If the read fails, check +Imager->errstr() for the cause: + + use Imager 0.68; + my $img = Imager->new(file => $filename) + or die "Cannot read $filename: ", Imager->errstr; + +=item write + +and the C<write()> method to write an image: + + $img->write(file=>$filename, type=>$type) + or die "Cannot write $filename: ", $img->errstr; + +=item read_multi + +If you're reading from a format that supports multiple images per +file, use the C<read_multi()> method: + + my @imgs = Imager->read_multi(file=>$filename, type=>$type) + or die "Cannot read $filename: ", Imager->errstr; + +As with the read() method, Imager will normally detect the C<type> +automatically. + +=item write_multi + +and if you want to write multiple images to a single file use the +C<write_multi()> method: + + Imager->write_multi({ file=> $filename, type=>$type }, @images) + or die "Cannot write $filename: ", Imager->errstr; + +=item read_types + +This is a class method that returns a list of the image file types +that Imager can read. + + my @types = Imager->read_types; + +These types are the possible values for the C<type> parameter, not +necessarily the extension of the files you're reading. + +It is possible for extra file read handlers to be loaded when +attempting to read a file, which may modify the list of available read +types. + +=item write_types + +This is a class method that returns a list of the image file types +that Imager can write. + + my @types = Imager->write_types; + +Note that these are the possible values for the C<type> parameter, not +necessarily the extension of the files you're writing. + +It is possible for extra file write handlers to be loaded when +attempting to write a file, which may modify the list of available +write types. + +=back + +When writing, if the I<filename> includes an extension that Imager +recognizes, then you don't need the I<type>, but you may want to +provide one anyway. See L</Guessing types> for information on +controlling this recognition. + +The C<type> parameter is a lowercase representation of the file type, +and can be any of the following: + + bmp Windows BitMaP (BMP) + gif Graphics Interchange Format (GIF) + jpeg JPEG/JFIF + png Portable Network Graphics (PNG) + pnm Portable aNyMap (PNM) + raw Raw + sgi SGI .rgb files + tga TARGA + tiff Tagged Image File Format (TIFF) + +When you read an image, Imager may set some tags, possibly including +information about the spatial resolution, textual information, and +animation information. See L<Imager::ImageTypes/Tags> for specifics. + +The open() method is a historical alias for the read() method. + +=head2 Input and output + +When reading or writing you can specify one of a variety of sources or +targets: + +=over + +=item * + +file - The C<file> parameter is the name of the image file to be +written to or read from. If Imager recognizes the extension of the +file you do not need to supply a C<type>. + + # write in tiff format + $image->write(file => "example.tif") + or die $image->errstr; + + $image->write(file => 'foo.tmp', type => 'tiff') + or die $image->errstr; + + my $image = Imager->new; + $image->read(file => 'example.tif') + or die $image->errstr; + +=item * + +fh - C<fh> is a file handle, typically either returned from +C<<IO::File->new()>>, or a glob from an C<open> call. You should call +C<binmode> on the handle before passing it to Imager. + +Imager will set the handle to autoflush to make sure any buffered data +is flushed , since Imager will write to the file descriptor (from +fileno()) rather than writing at the perl level. + + $image->write(fh => \*STDOUT, type => 'gif') + or die $image->errstr; + + # for example, a file uploaded via CGI.pm + $image->read(fd => $cgi->param('file')) + or die $image->errstr; + +=item * + +fd - C<fd> is a file descriptor. You can get this by calling the +C<fileno()> function on a file handle, or by using one of the standard +file descriptor numbers. + +If you get this from a perl file handle, you may need to flush any +buffered output, otherwise it may appear in the output stream after +the image. + + $image->write(fd => file(STDOUT), type => 'gif') + or die $image->errstr; + +=item * + +data - When reading data, C<data> is a scalar containing the image +file data, when writing, C<data> is a reference to the scalar to save +the image file data too. For GIF images you will need giflib 4 or +higher, and you may need to patch giflib to use this option for +writing. + + my $data; + $image->write(data => \$data, type => 'tiff') + or die $image->errstr; + + my $data = $row->{someblob}; # eg. from a database + my @images = Imager->read_multi(data => $data) + or die Imager->errstr; + +=item * + +callback - Imager will make calls back to your supplied coderefs to +read, write and seek from/to/through the image file. + +When reading from a file you can use either C<callback> or C<readcb> +to supply the read callback, and when writing C<callback> or +C<writecb> to supply the write callback. + +When writing you can also supply the C<maxbuffer> option to set the +maximum amount of data that will be buffered before your write +callback is called. Note: the amount of data supplied to your +callback can be smaller or larger than this size. + +The read callback is called with 2 parameters, the minimum amount of +data required, and the maximum amount that Imager will store in it's C +level buffer. You may want to return the minimum if you have a slow +data source, or the maximum if you have a fast source and want to +prevent many calls to your perl callback. The read data should be +returned as a scalar. + +Your write callback takes exactly one parameter, a scalar containing +the data to be written. Return true for success. + +The seek callback takes 2 parameters, a I<POSITION>, and a I<WHENCE>, +defined in the same way as perl's seek function. + +You can also supply a C<closecb> which is called with no parameters +when there is no more data to be written. This could be used to flush +buffered data. + + # contrived + my $data; + sub mywrite { + $data .= unpack("H*", shift); + 1; + } + Imager->write_multi({ callback => \&mywrite, type => 'gif'}, @images) + or die Imager->errstr; + +Note that for reading you'll almost always need to provide a +C<seekcb>. + +=back + +=head2 Guessing types + +When writing to a file, if you don't supply a C<type> parameter Imager +will attempt to guess it from the filename. This is done by calling +the code reference stored in C<$Imager::FORMATGUESS>. This is only +done when write() or write_multi() is called with a C<file> parameter. + +The default function value of C<$Imager::FORMATGUESS> is +C<\&Imager::def_guess_type>. + +=over + +=item def_guess_type + +This is the default function Imager uses to derive a file type from a +file name. This is a function, not a method. + +Accepts a single parameter, the filename and returns the type or +undef. + +=back + +You can replace function with your own implementation if you have some +specialized need. The function takes a single parameter, the name of +the file, and should return either a file type or under. + + # I'm writing jpegs to weird filenames + local $Imager::FORMATGUESS = sub { 'jpeg' }; + +When reading a file Imager examines beginning of the file for +identifying information. The current implementation attempts to +detect the following image types beyond those supported by Imager: + +=over + +xpm, mng, jng, SGI RGB, ilbm, pcx, fits, psd (Photoshop), eps, Utah +RLE + +=back + +=head2 Limiting the sizes of images you read + +=over + +=item set_file_limits + +In some cases you will be receiving images from an untested source, +such as submissions via CGI. To prevent such images from consuming +large amounts of memory, you can set limits on the dimensions of +images you read from files: + +=over + +=item * + +width - limit the width in pixels of the image + +=item * + +height - limit the height in pixels of the image + +=item * + +bytes - limits the amount of storage used by the image. This depends +on the width, height, channels and sample size of the image. For +paletted images this is calculated as if the image was expanded to a +direct color image. + +=back + +To set the limits, call the class method set_file_limits: + + Imager->set_file_limits(width=>$max_width, height=>$max_height); + +You can pass any or all of the limits above, any limits you do not +pass are left as they were. + +Any limit of zero is treated as unlimited. + +By default, all of the limits are zero, or unlimited. + +You can reset all of the limited to their defaults by passing in the +reset parameter as a true value: + + # no limits + Imager->set_file_limits(reset=>1); + +This can be used with the other limits to reset all but the limit you +pass: + + # only width is limited + Imager->set_file_limits(reset=>1, width=>100); + + # only bytes is limited + Imager->set_file_limits(reset=>1, bytes=>10_000_000); + +=item get_file_limits + +You can get the current limits with the get_file_limits() method: + + my ($max_width, $max_height, $max_bytes) = + Imager->get_file_limits(); + +=back + +=head1 TYPE SPECIFIC INFORMATION + +The different image formats can write different image type, and some have +different options to control how the images are written. + +When you call C<write()> or C<write_multi()> with an option that has +the same name as a tag for the image format you're writing, then the +value supplied to that option will be used to set the corresponding +tag in the image. Depending on the image format, these values will be +used when writing the image. + +This replaces the previous options that were used when writing GIF +images. Currently if you use an obsolete option, it will be converted +to the equivalent tag and Imager will produced a warning. You can +suppress these warnings by calling the C<Imager::init()> function with +the C<warn_obsolete> option set to false: + + Imager::init(warn_obsolete=>0); + +At some point in the future these obsolete options will no longer be +supported. + +=head2 PNM (Portable aNy Map) + +Imager can write PGM (Portable Gray Map) and PPM (Portable PixMaps) +files, depending on the number of channels in the image. Currently +the images are written in binary formats. Only 1 and 3 channel images +can be written, including 1 and 3 channel paletted images. + + $img->write(file=>'foo.ppm') or die $img->errstr; + +Imager can read both the ASCII and binary versions of each of the PBM +(Portable BitMap), PGM and PPM formats. + + $img->read(file=>'foo.ppm') or die $img->errstr; + +PNM does not support the spatial resolution tags. + +The following tags are set when reading a PNM file: + +=over + +=item * + +X<pnm_maxval>pnm_maxval - the maxvals number from the PGM/PPM header. +Always set to 2 for a PBM file. + +=item * + +X<pnm_type>pnm_type - the type number from the PNM header, 1 for ASCII +PBM files, 2 for ASCII PGM files, 3 for ASCII PPM files, 4 for binary +PBM files, 5 for binary PGM files, 6 for binary PPM files. + +=back + +The following tag is checked when writing an image with more than +8-bits/sample: + +=over + +=item * + +X<pnm_write_wide_data>pnm_write_wide_data - if this is non-zero then +write() can write PGM/PPM files with 16-bits/sample. Some +applications, for example GIMP 2.2, and tools can only read +8-bit/sample binary PNM files, so Imager will only write a 16-bit +image when this tag is non-zero. + +=back + +=head2 JPEG + +You can supply a C<jpegquality> parameter (0-100) when writing a JPEG +file, which defaults to 75%. If you write an image with an alpha +channel to a jpeg file then it will be composited against the +background set by the C<i_background> parameter (or tag). + + $img->write(file=>'foo.jpg', jpegquality=>90) or die $img->errstr; + +Imager will read a grayscale JPEG as a 1 channel image and a color +JPEG as a 3 channel image. + + $img->read(file=>'foo.jpg') or die $img->errstr; + +The following tags are set in a JPEG image when read, and can be set +to control output: + +=over + +=item jpeg_density_unit + +The value of the density unit field in the JFIF header. This is +ignored on writing if the C<i_aspect_only> tag is non-zero. + +The C<i_xres> and C<i_yres> tags are expressed in pixels per inch no +matter the value of this tag, they will be converted to/from the value +stored in the JPEG file. + +=item jpeg_density_unit_name + +This is set when reading a JPEG file to the name of the unit given by +C<jpeg_density_unit>. Possible results include C<inch>, +C<centimeter>, C<none> (the C<i_aspect_only> tag is also set reading +these files). If the value of jpeg_density_unit is unknown then this +tag isn't set. + +=item jpeg_comment + +Text comment. + +=back + +JPEG supports the spatial resolution tags C<i_xres>, C<i_yres> and +C<i_aspect_only>. + +If an APP1 block containing EXIF information is found, then any of the +following tags can be set: + +=over + +exif_aperture exif_artist exif_brightness exif_color_space +exif_contrast exif_copyright exif_custom_rendered exif_date_time +exif_date_time_digitized exif_date_time_original +exif_digital_zoom_ratio exif_exposure_bias exif_exposure_index +exif_exposure_mode exif_exposure_program exif_exposure_time +exif_f_number exif_flash exif_flash_energy exif_flashpix_version +exif_focal_length exif_focal_length_in_35mm_film +exif_focal_plane_resolution_unit exif_focal_plane_x_resolution +exif_focal_plane_y_resolution exif_gain_control exif_image_description +exif_image_unique_id exif_iso_speed_rating exif_make exif_max_aperture +exif_metering_mode exif_model exif_orientation exif_related_sound_file +exif_resolution_unit exif_saturation exif_scene_capture_type +exif_sensing_method exif_sharpness exif_shutter_speed exif_software +exif_spectral_sensitivity exif_sub_sec_time +exif_sub_sec_time_digitized exif_sub_sec_time_original +exif_subject_distance exif_subject_distance_range +exif_subject_location exif_tag_light_source exif_user_comment +exif_version exif_white_balance exif_x_resolution exif_y_resolution + +=back + +The following derived tags can also be set: + +=over + +exif_color_space_name exif_contrast_name exif_custom_rendered_name +exif_exposure_mode_name exif_exposure_program_name exif_flash_name +exif_focal_plane_resolution_unit_name exif_gain_control_name +exif_light_source_name exif_metering_mode_name +exif_resolution_unit_name exif_saturation_name +exif_scene_capture_type_name exif_sensing_method_name +exif_sharpness_name exif_subject_distance_range_name +exif_white_balance_name + +=back + +The derived tags are for enumerated fields, when the value for the +base field is valid then the text that appears in the EXIF +specification for that value appears in the derived field. So for +example if C<exf_metering_mode> is C<5> then +C<exif_metering_mode_name> is set to C<Pattern>. + +eg. + + my $image = Imager->new; + $image->read(file => 'exiftest.jpg') + or die "Cannot load image: ", $image->errstr; + print $image->tags(name => "exif_image_description"), "\n"; + print $image->tags(name => "exif_exposure_mode"), "\n"; + print $image->tags(name => "exif_exposure_mode_name"), "\n"; + + # for the exiftest.jpg in the Imager distribution the output would be: + Imager Development Notes + 0 + Auto exposure + +=over + +=item parseiptc + +Historically, Imager saves IPTC data when reading a JPEG image, the +parseiptc() method returns a list of key/value pairs resulting from a +simple decoding of that data. + +Any future IPTC data decoding is likely to go into tags. + +=back + +=head2 GIF (Graphics Interchange Format) + +When writing one of more GIF images you can use the same +L<Quantization Options|Imager::ImageTypes> as you can when converting +an RGB image into a paletted image. + +When reading a GIF all of the sub-images are combined using the screen +size and image positions into one big image, producing an RGB image. +This may change in the future to produce a paletted image where possible. + +When you read a single GIF with C<$img-E<gt>read()> you can supply a +reference to a scalar in the C<colors> parameter, if the image is read +the scalar will be filled with a reference to an anonymous array of +L<Imager::Color> objects, representing the palette of the image. This +will be the first palette found in the image. If you want the +palettes for each of the images in the file, use C<read_multi()> and +use the C<getcolors()> method on each image. + +GIF does not support the spatial resolution tags. + +Imager will set the following tags in each image when reading, and can +use most of them when writing to GIF: + +=over + +=item * + +gif_left - the offset of the image from the left of the "screen" +("Image Left Position") + +=item * + +gif_top - the offset of the image from the top of the "screen" ("Image +Top Position") + +=item * + +gif_interlace - non-zero if the image was interlaced ("Interlace +Flag") + +=item * + +gif_screen_width, gif_screen_height - the size of the logical +screen. When writing this is used as the minimum. If any image being +written would extend beyond this then the screen size is extended. +("Logical Screen Width", "Logical Screen Height"). + +=item * + +gif_local_map - Non-zero if this image had a local color map. If set +for an image when writing the image is quantized separately from the +other images in the file. + +=item * + +gif_background - The index in the global colormap of the logical +screen's background color. This is only set if the current image uses +the global colormap. You can set this on write too, but for it to +choose the color you want, you will need to supply only paletted +images and set the C<gif_eliminate_unused> tag to 0. + +=item * + +gif_trans_index - The index of the color in the colormap used for +transparency. If the image has a transparency then it is returned as +a 4 channel image with the alpha set to zero in this palette entry. +This value is not used when writing. ("Transparent Color Index") + +=item * + +gif_trans_color - A reference to an Imager::Color object, which is the +colour to use for the palette entry used to represent transparency in +the palette. You need to set the transp option (see L<Quantization +options>) for this value to be used. + +=item * + +gif_delay - The delay until the next frame is displayed, in 1/100 of a +second. ("Delay Time"). + +=item * + +gif_user_input - whether or not a user input is expected before +continuing (view dependent) ("User Input Flag"). + +=item * + +gif_disposal - how the next frame is displayed ("Disposal Method") + +=item * + +gif_loop - the number of loops from the Netscape Loop extension. This +may be zero to loop forever. + +=item * + +gif_comment - the first block of the first gif comment before each +image. + +=item * + +gif_eliminate_unused - If this is true, when you write a paletted +image any unused colors will be eliminated from its palette. This is +set by default. + +=item * + +gif_colormap_size - the original size of the color map for the image. +The color map of the image may have been expanded to include out of +range color indexes. + +=back + +Where applicable, the ("name") is the name of that field from the GIF89 +standard. + +The following gif writing options are obsolete, you should set the +corresponding tag in the image, either by using the tags functions, or +by supplying the tag and value as options. + +=over + +=item * + +gif_each_palette - Each image in the gif file has it's own palette if +this is non-zero. All but the first image has a local colour table +(the first uses the global colour table. + +Use C<gif_local_map> in new code. + +=item * + +interlace - The images are written interlaced if this is non-zero. + +Use C<gif_interlace> in new code. + +=item * + +gif_delays - A reference to an array containing the delays between +images, in 1/100 seconds. + +Use C<gif_delay> in new code. + +=item * + +gif_positions - A reference to an array of references to arrays which +represent screen positions for each image. + +New code should use the C<gif_left> and C<gif_top> tags. + +=item * + +gif_loop_count - If this is non-zero the Netscape loop extension block +is generated, which makes the animation of the images repeat. + +This is currently unimplemented due to some limitations in giflib. + +=back + +You can supply a C<page> parameter to the C<read()> method to read +some page other than the first. The page is 0 based: + + # read the second image in the file + $image->read(file=>"example.gif", page=>1) + or die "Cannot read second page: ",$image->errstr,"\n"; + +Before release 0.46, Imager would read multi-image GIF image files +into a single image, overlaying each of the images onto the virtual +GIF screen. + +As of 0.46 the default is to read the first image from the file, as if +called with C<< page => 0 >>. + +You can return to the previous behaviour by calling read with the +C<gif_consolidate> parameter set to a true value: + + $img->read(file=>$some_gif_file, gif_consolidate=>1); + +As with the to_paletted() method, if you supply a colors parameter as +a reference to an array, this will be filled with Imager::Color +objects of the color table generated for the image file. + +=head2 TIFF (Tagged Image File Format) + +Imager can write images to either paletted or RGB TIFF images, +depending on the type of the source image. Currently if you write a +16-bit/sample or double/sample image it will be written as an +8-bit/sample image. Only 1 or 3 channel images can be written. + +If you are creating images for faxing you can set the I<class> +parameter set to C<fax>. By default the image is written in fine +mode, but this can be overridden by setting the I<fax_fine> parameter +to zero. Since a fax image is bi-level, Imager uses a threshold to +decide if a given pixel is black or white, based on a single channel. +For greyscale images channel 0 is used, for color images channel 1 +(green) is used. If you want more control over the conversion you can +use $img->to_paletted() to product a bi-level image. This way you can +use dithering: + + my $bilevel = $img->to_paletted(make_colors => 'mono', + translate => 'errdiff', + errdiff => 'stucki'); + +=over + +=item class + +If set to 'fax' the image will be written as a bi-level fax image. + +=item fax_fine + +By default when I<class> is set to 'fax' the image is written in fine +mode, you can select normal mode by setting I<fax_fine> to 0. + +=back + +Imager should be able to read any TIFF image you supply. Paletted +TIFF images are read as paletted Imager images, since paletted TIFF +images have 16-bits/sample (48-bits/color) this means the bottom +8-bits are lost, but this shouldn't be a big deal. Currently all +direct color images are read at 8-bits/sample. + +TIFF supports the spatial resolution tags. See the +C<tiff_resolutionunit> tag for some extra options. + +As of Imager 0.62 Imager reads: + +=over + +=item * + +16-bit grey, RGB, or CMYK image, including a possible alpha channel as +a 16-bit/sample image. + +=item * + +32-bit grey, RGB image, including a possible alpha channel as a +double/sample image. + +=item * + +bi-level images as paletted images containing only black and white, +which other formats will also write as bi-level. + +=item * + +tiled paletted images are now handled correctly + +=back + +The following tags are set in a TIFF image when read, and can be set +to control output: + +=over + +=item tiff_compression + +When reading an image this is set to the numeric value of the TIFF +compression tag. + +On writing you can set this to either a numeric compression tag value, +or one of the following values: + + Ident Number Description + none 1 No compression + packbits 32773 Macintosh RLE + ccittrle 2 CCITT RLE + fax3 3 CCITT Group 3 fax encoding (T.4) + t4 3 As above + fax4 4 CCITT Group 4 fax encoding (T.6) + t6 4 As above + lzw 5 LZW + jpeg 7 JPEG + zip 8 Deflate (GZIP) Non-standard + deflate 8 As above. + oldzip 32946 Deflate with an older code. + ccittrlew 32771 Word aligned CCITT RLE + +In general a compression setting will be ignored where it doesn't make +sense, eg. C<jpeg> will be ignored for compression if the image is +being written as bilevel. + +Imager attempts to check that your build of libtiff supports the given +compression, and will fallback to C<packbits> if it isn't enabled. +eg. older distributions didn't include LZW compression, and JPEG +compression is only available if libtiff is configured with libjpeg's +location. + + $im->write(file => 'foo.tif', tiff_compression => 'lzw') + or die $im->errstr; + +=item tiff_jpegquality + +If I<tiff_compression> if C<jpeg> then this can be a number from 1 to +100 giving the JPEG compression quality. High values are better +quality and larger files. + +=item tiff_resolutionunit + +The value of the ResolutionUnit tag. This is ignored on writing if +the i_aspect_only tag is non-zero. + +The C<i_xres> and C<i_yres> tags are expressed in pixels per inch no +matter the value of this tag, they will be converted to/from the value +stored in the TIFF file. + +=item tiff_resolutionunit_name + +This is set when reading a TIFF file to the name of the unit given by +C<tiff_resolutionunit>. Possible results include C<inch>, +C<centimeter>, C<none> (the C<i_aspect_only> tag is also set reading +these files) or C<unknown>. + +=item tiff_bitspersample + +Bits per sample from the image. This value is not used when writing +an image, it is only set on a read image. + +=item tiff_photometric + +Value of the PhotometricInterpretation tag from the image. This value +is not used when writing an image, it is only set on a read image. + +=item tiff_documentname + +=item tiff_imagedescription + +=item tiff_make + +=item tiff_model + +=item tiff_pagename + +=item tiff_software + +=item tiff_datetime + +=item tiff_artist + +=item tiff_hostcomputer + +Various strings describing the image. tiff_datetime must be formatted +as "YYYY:MM:DD HH:MM:SS". These correspond directly to the mixed case +names in the TIFF specification. These are set in images read from a +TIFF and saved when writing a TIFF image. + +=back + +You can supply a C<page> parameter to the C<read()> method to read +some page other than the first. The page is 0 based: + + # read the second image in the file + $image->read(file=>"example.tif", page=>1) + or die "Cannot read second page: ",$image->errstr,"\n"; + +Note: Imager uses the TIFF*RGBA* family of libtiff functions, +unfortunately these don't support alpha channels on CMYK images. This +will result in a full coverage alpha channel on CMYK images with an +alpha channel, until this is implemented in libtiff (or Imager's TIFF +implementation changes.) + +If you read an image with multiple alpha channels, then only the first +alpha channel will be read. + +Currently Imager's TIFF support reads all direct color images as 8-bit +RGB images, this may change in the future to reading 16-bit/sample +images. + +Currently tags that control the output color type and compression are +ignored when writing, this may change in the future. If you have +processes that rely upon Imager always producing packbits compressed +RGB images, you should strip any tags before writing. + +=head2 BMP (BitMaP) + +Imager can write 24-bit RGB, and 8, 4 and 1-bit per pixel paletted +Windows BMP files. Currently you cannot write compressed BMP files +with Imager. + +Imager can read 24-bit RGB, and 8, 4 and 1-bit perl pixel paletted +Windows BMP files. There is some support for reading 16-bit per pixel +images, but I haven't found any for testing. + +BMP has no support for multi-image files. + +BMP files support the spatial resolution tags, but since BMP has no +support for storing only an aspect ratio, if C<i_aspect_only> is set +when you write the C<i_xres> and C<i_yres> values are scaled so the +smaller is 72 DPI. + +The following tags are set when you read an image from a BMP file: + +=over + +=item bmp_compression + +The type of compression, if any. This can be any of the following +values: + +=over + +=item BI_RGB (0) + +Uncompressed. + +=item BI_RLE8 (1) + +8-bits/pixel paletted value RLE compression. + +=item BI_RLE4 (2) + +4-bits/pixel paletted value RLE compression. + +=item BI_BITFIELDS (3) + +Packed RGB values. + +=back + +=item bmp_compression_name + +The bmp_compression value as a BI_* string + +=item bmp_important_colors + +The number of important colors as defined by the writer of the image. + +=item bmp_used_colors + +Number of color used from the BMP header + +=item bmp_filesize + +The file size from the BMP header + +=item bmp_bit_count + +Number of bits stored per pixel. (24, 8, 4 or 1) + +=back + +=head2 TGA (TarGA) + +When storing targa images rle compression can be activated with the +'compress' parameter, the 'idstring' parameter can be used to set the +targa comment field and the 'wierdpack' option can be used to use the +15 and 16 bit targa formats for rgb and rgba data. The 15 bit format +has 5 of each red, green and blue. The 16 bit format in addition +allows 1 bit of alpha. The most significant bits are used for each +channel. + + +Tags: + +=over + +=item tga_idstring + +=item tga_bitspp + +=item compressed + +=back + +=head2 RAW + +When reading raw images you need to supply the width and height of the +image in the xsize and ysize options: + + $img->read(file=>'foo.raw', xsize=>100, ysize=>100) + or die "Cannot read raw image\n"; + +If your input file has more channels than you want, or (as is common), +junk in the fourth channel, you can use the datachannels and +storechannels options to control the number of channels in your input +file and the resulting channels in your image. For example, if your +input image uses 32-bits per pixel with red, green, blue and junk +values for each pixel you could do: + + $img->read(file=>'foo.raw', xsize=>100, ysize=>100, datachannels=>4, + storechannels=>3) + or die "Cannot read raw image\n"; + +Read parameters: + +=over + +=item * + +raw_interleave - controls the ordering of samples within the image. +Default: 1. Alternatively and historically spelled C<interleave>. +Possible values: + +=over + +=item * + +0 - samples are pixel by pixel, so all samples for the first pixel, +then all samples for the second pixel and so on. eg. for a four pixel +scanline the channels would be laid out as: + + 012012012012 + +=item * + +1 - samples are line by line, so channel 0 for the entire scanline is +followed by channel 1 for the entire scanline and so on. eg. for a +four pixel scanline the channels would be laid out as: + + 000011112222 + +This is the default. + +=back + +Unfortunately, historically, the default C<raw_interleave> for read +has been 1, while writing only supports the C<raw_interleave> = 0 +format. + +For future compatibility, you should always supply the +C<raw_interleave> (or C<interleave>) parameter. As of 0.68, Imager +will warn if you attempt to read a raw image without a +C<raw_interleave> parameter. + +=item * + +raw_storechannels - the number of channels to store in the image. +Range: 1 to 4. Default: 3. Alternatively and historically spelled +C<storechannels>. + +=item * + +raw_datachannels - the number of channels to read from the file. +Range: 1 or more. Default: 3. Alternatively and historically spelled +C<datachannels>. + +=back + + $img->read(file=>'foo.raw', xsize=100, ysize=>100, raw_interleave=>1) + or die "Cannot read raw image\n"; + +=head2 PNG + +There are no PNG specific tags. + +=head2 ICO (Microsoft Windows Icon) and CUR (Microsoft Windows Cursor) + +Icon and Cursor files are very similar, the only differences being a +number in the header and the storage of the cursor hotspot. I've +treated them separately so that you're not messing with tags to +distinguish between them. + +The following tags are set when reading an icon image and are used +when writing it: + +=over + +=item ico_mask + +This is the AND mask of the icon. When used as an icon in Windows 1 +bits in the mask correspond to pixels that are modified by the source +image rather than simply replaced by the source image. + +Rather than requiring a binary bitmap this is accepted in a specific format: + +=over + +=item * + +first line consisting of the 0 placeholder, the 1 placeholder and a +newline. + +=item * + +following lines which contain 0 and 1 placeholders for each scanline +of the image, starting from the top of the image. + +=back + +When reading an image, '.' is used as the 0 placeholder and '*' as the +1 placeholder. An example: + + .* + ..........................****** + ..........................****** + ..........................****** + ..........................****** + ...........................***** + ............................**** + ............................**** + .............................*** + .............................*** + .............................*** + .............................*** + ..............................** + ..............................** + ...............................* + ...............................* + ................................ + ................................ + ................................ + ................................ + ................................ + ................................ + *............................... + **.............................. + **.............................. + ***............................. + ***............................. + ****............................ + ****............................ + *****........................... + *****........................... + *****........................... + *****........................... + +=back + +The following tags are set when reading an icon: + +=over + +=item ico_bits + +The number of bits per pixel used to store the image. + +=back + +For cursor files the following tags are set and read when reading and +writing: + +=over + +=item cur_mask + +This is the same as the ico_mask above. + +=item cur_hotspotx + +=item cur_hotspoty + +The "hot" spot of the cursor image. This is the spot on the cursor +that you click with. If you set these to out of range values they are +clipped to the size of the image when written to the file. + +=back + +The following parameters can be supplied to read() or read_multi() to +control reading of ICO/CUR files: + +=over + +=item * + +ico_masked - if true, the default, then the icon/cursors mask is +applied as an alpha channel to the image. This may result in a +paletted image being returned as a direct color image. Default: 1 + + # retrieve the image as stored, without using the mask as an alpha + # channel + $img->read(file => 'foo.ico', ico_masked => 0) + or die $img->errstr; + +This was introduced in Imager 0.60. Previously reading ICO images +acted as if C<ico_masked =E<gt> 0>. + +=back + +C<cur_bits> is set when reading a cursor. + +Examples: + + my $img = Imager->new(xsize => 32, ysize => 32, channels => 4); + $im->box(color => 'FF0000'); + $im->write(file => 'box.ico'); + + $im->settag(name => 'cur_hotspotx', value => 16); + $im->settag(name => 'cur_hotspoty', value => 16); + $im->write(file => 'box.cur'); + +=head2 SGI (RGB, BW) + +SGI images, often called by the extensions, RGB or BW, can be stored +either uncompressed or compressed using an RLE compression. + +By default, when saving to an extension of C<rgb>, C<bw>, C<sgi>, +C<rgba> the file will be saved in SGI format. The file extension is +otherwise ignored, so saving a 3-channel image to a C<.bw> file will +result in a 3-channel image on disk. + +The following tags are set when reading a SGI image: + +=over + +=item * + +i_comment - the IMAGENAME field from the image. Also written to the +file when writing. + +=item * + +sgi_pixmin, sgi_pixmax - the PIXMIN and PIXMAX fields from the image. +On reading image data is expanded from this range to the full range of +samples in the image. + +=item * + +sgi_bpc - the number of bytes per sample for the image. Ignored when +writing. + +=item * + +sgi_rle - whether or not the image is compressed. If this is non-zero +when writing the image will be compressed. + +=back + +=head1 ADDING NEW FORMATS + +To support a new format for reading, call the register_reader() class +method: + +=over + +=item register_reader + +Registers single or multiple image read functions. + +Parameters: + +=over + +=item * + +type - the identifier of the file format, if Imager's +i_test_format_probe() can identify the format then this value should +match i_test_format_probe()'s result. + +This parameter is required. + +=item * + +single - a code ref to read a single image from a file. This is +supplied: + +=over + +=item * + +the object that read() was called on, + +=item * + +an Imager::IO object that should be used to read the file, and + +=item * + +all the parameters supplied to the read() method. + +=back + +The single parameter is required. + +=item * + +multiple - a code ref which is called to read multiple images from a +file. This is supplied: + +=over + +=item * + +an Imager::IO object that should be used to read the file, and + +=item * + +all the parameters supplied to the read_multi() method. + +=back + +=back + +Example: + + # from Imager::File::ICO + Imager->register_reader + ( + type=>'ico', + single => + sub { + my ($im, $io, %hsh) = @_; + $im->{IMG} = i_readico_single($io, $hsh{page} || 0); + + unless ($im->{IMG}) { + $im->_set_error(Imager->_error_as_msg); + return; + } + return $im; + }, + multiple => + sub { + my ($io, %hsh) = @_; + + my @imgs = i_readico_multi($io); + unless (@imgs) { + Imager->_set_error(Imager->_error_as_msg); + return; + } + return map { + bless { IMG => $_, DEBUG => $Imager::DEBUG, ERRSTR => undef }, 'Imager' + } @imgs; + }, + ); + +=item register_writer + +Registers single or multiple image write functions. + +Parameters: + +=over + +=item * + +type - the identifier of the file format. This is typically the +extension in lowercase. + +This parameter is required. + +=item * + +single - a code ref to write a single image to a file. This is +supplied: + +=over + +=item * + +the object that write() was called on, + +=item * + +an Imager::IO object that should be used to write the file, and + +=item * + +all the parameters supplied to the write() method. + +=back + +The single parameter is required. + +=item * + +multiple - a code ref which is called to write multiple images to a +file. This is supplied: + +=over + +=item * + +the class name write_multi() was called on, this is typically +C<Imager>. + +=item * + +an Imager::IO object that should be used to write the file, and + +=item * + +all the parameters supplied to the read_multi() method. + +=back + +=back + +=back + +If you name the reader module C<Imager::File::>I<your-format-name> +where I<your-format-name> is a fully upper case version of the type +value you would pass to read(), read_multi(), write() or write_multi() +then Imager will attempt to load that module if it has no other way to +read or write that format. + +For example, if you create a module Imager::File::GIF and the user has +built Imager without it's normal GIF support then an attempt to read a +GIF image will attempt to load Imager::File::GIF. + +If your module can only handle reading then you can name your module +C<Imager::File::>I<your-format-name>C<Reader> and Imager will attempt +to autoload it. + +If your module can only handle writing then you can name your module +C<Imager::File::>I<your-format-name>C<Writer> and Imager will attempt +to autoload it. + +=head1 EXAMPLES + +=head2 Producing an image from a CGI script + +Once you have an image the basic mechanism is: + +=over + +=item 1. + +set STDOUT to autoflush + +=item 2. + +output a content-type header, and optionally a content-length header + +=item 3. + +put STDOUT into binmode + +=item 4. + +call write() with the C<fd> or C<fh> parameter. You will need to +provide the C<type> parameter since Imager can't use the extension to +guess the file format you want. + +=back + + # write an image from a CGI script + # using CGI.pm + use CGI qw(:standard); + $| = 1; + binmode STDOUT; + print header(-type=>'image/gif'); + $img->write(type=>'gif', fd=>fileno(STDOUT)) + or die $img->errstr; + +If you want to send a content length you can send the output to a +scalar to get the length: + + my $data; + $img->write(type=>'gif', data=>\$data) + or die $img->errstr; + binmode STDOUT; + print header(-type=>'image/gif', -content_length=>length($data)); + print $data; + +=head2 Writing an animated GIF + +The basic idea is simple, just use write_multi(): + + my @imgs = ...; + Imager->write_multi({ file=>$filename, type=>'gif' }, @imgs); + +If your images are RGB images the default quantization mechanism will +produce a very good result, but can take a long time to execute. You +could either use the standard webmap: + + Imager->write_multi({ file=>$filename, + type=>'gif', + make_colors=>'webmap' }, + @imgs); + +or use a median cut algorithm to built a fairly optimal color map: + + Imager->write_multi({ file=>$filename, + type=>'gif', + make_colors=>'mediancut' }, + @imgs); + +By default all of the images will use the same global colormap, which +will produce a smaller image. If your images have significant color +differences, you may want to generate a new palette for each image: + + Imager->write_multi({ file=>$filename, + type=>'gif', + make_colors=>'mediancut', + gif_local_map => 1 }, + @imgs); + +which will set the C<gif_local_map> tag in each image to 1. +Alternatively, if you know only some images have different colors, you +can set the tag just for those images: + + $imgs[2]->settag(name=>'gif_local_map', value=>1); + $imgs[4]->settag(name=>'gif_local_map', value=>1); + +and call write_multi() without a C<gif_local_map> parameter, or supply +an arrayref of values for the tag: + + Imager->write_multi({ file=>$filename, + type=>'gif', + make_colors=>'mediancut', + gif_local_map => [ 0, 0, 1, 0, 1 ] }, + @imgs); + +Other useful parameters include C<gif_delay> to control the delay +between frames and C<transp> to control transparency. + +=head2 Reading tags after reading an image + +This is pretty simple: + + # print the author of a TIFF, if any + my $img = Imager->new; + $img->read(file=>$filename, type='tiff') or die $img->errstr; + my $author = $img->tags(name=>'tiff_author'); + if (defined $author) { + print "Author: $author\n"; + } + +=head1 BUGS + +When saving Gif images the program does NOT try to shave of extra +colors if it is possible. If you specify 128 colors and there are +only 2 colors used - it will have a 128 colortable anyway. + +=head1 SEE ALSO + +Imager(3) + +=cut |