imager::largesamples(3pm) [debian man page]
Imager::LargeSamples(3pm) User Contributed Perl Documentation Imager::LargeSamples(3pm) NAME
Imager::LargeSamples - track/document large sample support SYNOPSIS
# make a large sample image my $im = Imager->new(..., bits => 16); # call some method my $result = $im->$method(...); # was the image modified at its full sample size DESCRIPTION
Imager has had in-memory support for large samples for years now, but many methods still don't work at the higher sample size when supplied with a large sample image. This document will track which methods support large samples and which don't, for future improvements. Support by method Method Support Notes ------ ------- ----- arc Partial [1] box Partial [2] circle Partial [1] convert Full copy Full crop Full difference Full filter Partial Depends on the filter. flip Full flood_fill Partial [1] getpixel Full getsamples Full getscanline Full map None masked Full matrix_transform Full paste Full polygon Partial [1] polyline None read Partial See L<File format large sample support> read_multi Partial See L<File format large sample support> rotate Full rubthrough Full scale Partial Some qtypes support large samples scaleX None scaleY None setpixel Full setscanline Full string Full Preserves large samples, but most font drivers generate 8 or fewer bits of levels of coverage. transform None transform2 None write Partial See L<File format large sample support> write_multi Partial See L<File format large sample support> [1] filling an area using the fill parameter works at the full depth of the image, using filled => 1 and color works at 8-bits/sample [2] box() will fill the area at the supplied color, but outline at 8-bits/sample. File format large sample support Format Format samples Imager support ------ -------------- -------------- BMP 8 8 GIF 8 8 ICO 8 8 JPEG 8, 12 8 PBM 1 1 PGM/PPM 1-16 read any, writes 8, 16 PNG 1, 2, 4, 8, 16 8 RAW 8 SGI 8, 16 8, 16 TGA 8 8 TIFF (many) read/write 8, 16, 32 contig rgb/grey images read/write bi-level read/write 4/8 paletted images Filter larger sample support Filter Large sample support ------ -------------------- autolevels No bumpmap No bumpmap_complex No contrast No conv Yes fountain Yes gaussian Yes gradgen No hardinvert Yes mosaic No postlevels No radnoise No turbnoise No unsharpmask Yes watermark No AUTHOR
Tony Cook <tonyc@cpan.org> perl v5.14.2 2011-06-06 Imager::LargeSamples(3pm)
Check Out this Related Man Page
Imager::Cookbook(3pm) User Contributed Perl Documentation Imager::Cookbook(3pm) NAME
Imager::Cookbook - recipes working with Imager DESCRIPTION
Various simple and not so simple ways to do things with Imager. FILES
This is described in detail in Imager::Files. Reading an image from a file my $image = Imager->new; $image->read(file=>$filename) or die $image->errstr; See Imager::Files. Writing an image to a file $image->write(file=>$filename) or die $image->errstr; Write an animated GIF # build an array of images to use in the gif my @images; # synthesize the images or read them from files, it doesn't matter ... # write the gif Imager->write_multi({ file=>$filename, type=>'gif' }, @images) or die Imager->errstr; See "Writing an animated GIF" in Imager::Files for a more detailed example. Reading multiple images from one file Some formats, like GIF and TIFF support multiple images per file. Use the read_multi() method to read them: my @images = Imager->read_multi(file=>$filename) or die Imager->errstr; Converting from one file format to another This is as simple as reading the original file and writing the new file, for single images: my $image = Imager->new; # Imager auto-detects the input file type $image->read(file => $input_filename) or die $image->errstr; # Imager derives the output file format from the filename $image->write(file => $output_filename) or die $image->errstr; # or you can supply a type parameter: $image->write(file => $output_filename, type => 'gif') or die $image->errstr; The main issue that can occur with this is if the input file has transparency and the output file format doesn't support that. This can be a problem when converting from GIF files to JPEG files for example. By default, if the output format doesn't support transparency, Imager will compose the image onto a black background. You can override that by supplying an "i_background" option to "write()" or "write_multi()": $image->write(file => "foo.jpg", i_background => "#808080") or die $image->errstr; Some formats support multiple files, so if you want to convert from say TIFF to JPEG, you'll need multiple output files: my @images = Imager->read_multi(file => 'input.tif') or die Imager->errstr; my $index = 1; for my $image (@images) { $image->write(file => sprintf('output%02d.jpg', $index++)) or die $image->errstr; } Transparent PNG To save to a transparent PNG (or GIF or TIFF) you need to start with an image with transparency. To make a transparent image, create an image object with 2 or 4 channels: # RGB with alpha channel my $rgba = Imager->new(xsize => $width, ysize => $height, channels => 4); # Gray with alpha channel my $graya = Imager->new(xsize => $width, ysize => $height, channels => 2); By default, the created image will be transparent. Otherwise, if you have an existing image file with transparency, simply read it, and the transparency will be preserved. IMAGE SYNTHESIS
Creating an image To create a simple RGB image, supply the image width and height to the new() method: my $rgb = Imager->new(xsize=>$width, ysize=>$height); If you also want an alpha channel: my $rgb_alpha = Imager->new(xsize=>$width, ysize=>$height, channels=>4); To make a gray-scale image: my $gray = Imager->new(xsize=>$width, ysize=>$height, channels=>1); and a gray-scale image with an alpha channel: my $gray_alpha = Imager->new(xsize=>$width, ysize=>$height, channels=>2); When a new image is created this way all samples are set to zero - black for 1 or 3 channel images, transparent black for 2 or 4 channel images. You can also create paletted images and images with more than 8-bits per channel, see Imager::ImageTypes for more details. Setting the background of a new image To set the background of a new image to a solid color, use the box() method with no limits, and "filled=>1": $image->box(filled=>1, color=>$color); As always, a color can be specified as an Imager::Color object: my $white = Imager::Color->new(255, 255, 255); $image->box(filled=>1, color=>$white); or you supply any single scalar that Imager::Color's new() method accepts as a color description: $image->box(filled=>1, color=>'white'); $image->box(filled=>1, color=>'#FF0000'); $image->box(filled=>1, color=>[ 255, 255, 255 ]); You can also fill the image with a fill object: use Imager::Fill; # create the fill object my $fill = Imager::Fill->new(hatch=>'check1x1') $image->box(fill=>$fill); # let Imager create one automatically $image->box(fill=>{ hatch=>'check1x1' }); See Imager::Fill for information on Imager's fill objects. WORLD WIDE WEB
As with any CGI script it's up to you to validate data and set limits on any parameters supplied to Imager. For example, if you allow the caller to set the size of an output image you should limit the size to prevent the client from specifying an image size that will consume all available memory. This is beside any any other controls you need over access to data. See CGI for a module useful for processing CGI submitted data. Returning an image from a CGI script This is similar to writing to a file, but you also need to supply the information needed by the web browser to identify the file format: my $img = ....; # create the image and generate the contents ++$|; # make sure the content type isn't buffered print "Content-Type: image/png "; binmode STDOUT; $img->write(fd=>fileno(STDOUT), type=>'png') or die $img->errstr; You need to set the Content-Type header depending on the file format you send to the web browser. If you want to supply a content-length header, write the image to a scalar as a buffer: my $img = ....; # create the image and generate the contents my $data; $img->write(type=>'png', data=>$data) or die $img->errstr; print "Content-Type: image/png "; print "Content-Length: ",length($data)," "; binmode STDOUT; print $data; See "samples/samp-scale.cgi" and "samples/samp-image.cgi" for a couple of simple examples of producing an image from CGI. Inserting a CGI image in a page There's occasionally confusion on how to display an image generated by Imager in a page generated by a CGI. Your web browser handles this process as two requests, one for the HTML page, and another for the image itself. Each request needs to perform validation since an attacker can control the values supplied to both requests. How you make the data available to the image generation code depends on your application. See "samples/samp-form.cgi" and "samples/samp-image.cgi" in the Imager distribution for one approach. The POD in "samp-form.cgi" also discusses some of the issues involved. Parsing an image posted via CGI "WARNING": file format attacks have become a common attack vector, make sure you have up to date image file format libraries, otherwise trying to parse uploaded files, whether with Imager or some other tool, may result in a remote attacker being able to run their own code on your system. If your HTML form uses the correct magic, it can upload files to your CGI script, in particular, you need to use " method="post" " and "enctype="multipart/form-data"" in the "form" tag, and use "type="file"" in the "input", for example: <form action="/cgi-bin/yourprogram" method="post" enctype="multipart/form-data"> <input type="file" name="myimage" /> <input type="submit value="Upload Image" /> </form> To process the form: 1. first check that the user supplied a file 2. get the file handle 3. have Imager read the image # returns the client's name for the file, don't open this locally my $cgi = CGI->new; # 1. check the user supplied a file my $filename = $cgi->param('myimage'); if ($filename) { # 2. get the file handle my $fh = $cgi->upload('myimage'); if ($fh) { binmode $fh; # 3. have Imager read the image my $img = Imager->new; if ($img->read(fh=>$fh)) { # we can now process the image } } # else, you probably have an incorrect form or input tag } # else, the user didn't select a file See "samples/samp-scale.cgi" and "samples/samp-tags.cgi" in the Imager distribution for example code. You may also want to set limits on the size of the image read, using Imager's "set_file_limits" method, documented in "set_file_limits()" in Imager::Files. For example: # limit to 10 million bytes of memory usage Imager->set_file_limits(bytes => 10_000_000); # limit to 1024 x 1024 Imager->set_file_limits(width => 1024, height => 1024); DRAWING
Adding a border to an image First make a new image with space for the border: my $border_width = ...; my $border_height = ...; my $out = Imager->new(xsize => $source->getwidth() + 2 * $border_width, ysize => $source->getheight() + 2 * $border_height, bits => $source->bits, channels => $source->getchannels); Then paste the source image into the new image: $out->paste(left => $border_width, top => $border_height, img => $source); Whether you draw the border before or after pasting the original image depends on whether you want the border to overlap the image, for example a semi-transparent border drawn after pasting the source image could overlap the edge without hiding it. If you want a solid border you could just fill the image before pasting the source for simplicity: $out->box(filled=>1, color=>'red'); $out->paste(left => $border_width, top => $border_height, img => $source); TEXT
Drawing text Aligning text Measuring text Word wrapping text Shearing (slanting) or Rotating text This requires that you have Imager installed with FreeType 2.x support installed, and that the font be created using the FreeType 2.x driver, for example: my $font = Imager::Font->new(file=>$fontfile, type=>'ft2'); First you need a transformation matrix, for shearing that could be: my $angle_in_radians = ...; my $tan_angle = sin($angle_rads) / cos($angle_rads); # shear horizontally, supply this as y instead to do it vertically my $matrix = Imager::Matrix2d->shear(x=>$tan_angle); For rotation that would be: my $matrix = Imager::Matrix2d->rotate(radians => $angle_in_radians); or: my $matrix = Imager::Matrix2d->rotate(degrees => $angle_in_degrees); Feed that to the font object: $font->transform(matrix => $matrix); and draw the text as normal: $image->string(string => $text, x => $where_x, y => $where_y, color => $color, font => $font); See samples/slant_text.pl for a comprehensive example, including calculating the transformed bounding box to create an image to fit the transformed text into. IMAGE TRANSFORMATION
Shearing an image Convert to gray-scale To convert an RGB image to a gray-scale image, use the convert method: my $grey = $image->convert(preset => 'gray'); convert() returns a new image. See: "Color transformations" in Imager::Transformations METADATA
Image format When Imager reads a file it does a magic number check to determine the file type, so "foo.png" could actually be a GIF image, and Imager will read it anyway. You can check the actual format of the image by looking at the "i_format" tag. my $format = $image->tags(name=>'i_format'); Image spatial resolution Most image file formats store information about the physical size of the pixels, though in some cases that information isn't useful. Imager stores this information in the tags "i_xres" and "i_yres", and this is always stored in dots per inch. Some formats, including TIFF and JPEG allow you to change the units spatial resolution information is stored in, if you set the tag that changes this the Imager will convert "i_xres" and "i_yres" to those units when it writes the file. For example to set the resolution to 300 dpi: $image->settag(name => 'i_xres', value => 300); $image->settag(name => 'i_yres', value => 300); If you want the file format to store the resolution in some other unit, for example you can write a TIFF file that stores the resolution in pixels per centimeter, you would do: # 150 pixels/cm $image->settag(name => 'i_xres', value => 150 * 2.54); $image->settag(name => 'i_yres', value => 150 * 2.54); $image->settag(name => 'tiff_resolutionunit', value => 3); Keywords: DPI AUTHOR
Tony Cook <tony@develop-help.com> SEE ALSO
Imager, Imager::Files, Imager::Draw. perl v5.14.2 2012-02-22 Imager::Cookbook(3pm)