- use Imager;
-
- $img = Imager->new();
- $img->open(file=>'image.ppm',type=>'pnm')
- || print "failed: ",$img->{ERRSTR},"\n";
- $scaled=$img->scale(xpixels=>400,ypixels=>400);
- $scaled->write(file=>'sc_image.ppm',type=>'pnm')
- || print "failed: ",$scaled->{ERRSTR},"\n";
-
-=head1 DESCRIPTION
-
-Imager is a module for creating and altering images - It is not meant
-as a replacement or a competitor to ImageMagick or GD. Both are
-excellent packages and well supported.
-
-=head2 Overview of documentation
-
-=over
-
-=item Imager
-
-This document - Table of Contents, Example and Overview
-
-=item Imager::ImageTypes
-
-Direct type/virtual images, RGB(A)/paletted images, 8/16/double
-bits/channel, image tags, and channel masks.
-
-=item Imager::Files
-
-IO interaction, reading/writing images, format specific tags.
-
-=item Imager::Draw
-
-Drawing Primitives, lines boxes, circles, flood fill.
-
-=item Imager::Color
-
-Color specification.
-
-=item Imager::Font
-
-General font rendering.
-
-=item Imager::Transformations
-
-Copying, scaling, cropping, flipping, blending, pasting, [convert and map.]
-
-=item Imager::Engines
-
-transform2 and matrix_transform.
-
-=item Imager::Filters
-
-Filters, sharpen, blur, noise, convolve etc. and plugins.
-
-=item Imager::Expr
-
-Expressions for evaluation engine used by transform2().
-
-=item Imager::Matrix2d
-
-Helper class for affine transformations.
-
-=item Imager::Fountain
-
-Helper for making gradient profiles.
-
-=back
-
-
-
-
-
-
-
-
-Almost all functions take the parameters in the hash fashion.
-Example:
-
- $img->open(file=>'lena.png',type=>'png');
-
-or just:
-
- $img->open(file=>'lena.png');
-
-=head2 Basic concept
-
-An Image object is created with C<$img = Imager-E<gt>new()> Should
-this fail for some reason an explanation can be found in
-C<$Imager::ERRSTR> usually error messages are stored in
-C<$img-E<gt>{ERRSTR}>, but since no object is created this is the only
-way to give back errors. C<$Imager::ERRSTR> is also used to report
-all errors not directly associated with an image object. Examples:
-
- $img=Imager->new(); # This is an empty image (size is 0 by 0)
- $img->open(file=>'lena.png',type=>'png'); # initializes from file
-
-or if you want to create an empty image:
-
- $img=Imager->new(xsize=>400,ysize=>300,channels=>4);
-
-This example creates a completely black image of width 400 and
-height 300 and 4 channels.
-
-If you have an existing image, use img_set() to change it's dimensions
-- this will destroy any existing image data:
-
- $img->img_set(xsize=>500, ysize=>500, channels=>4);
-
-To create paletted images, set the 'type' parameter to 'paletted':
-
- $img = Imager->new(xsize=>200, ysize=>200, channels=>3, type=>'paletted');
-
-which creates an image with a maxiumum of 256 colors, which you can
-change by supplying the C<maxcolors> parameter.
-
-You can create a new paletted image from an existing image using the
-to_paletted() method:
-
- $palimg = $img->to_paletted(\%opts)
-
-where %opts contains the options specified under L<Quantization options>.
-
-You can convert a paletted image (or any image) to an 8-bit/channel
-RGB image with:
-
- $rgbimg = $img->to_rgb8;
-
-Warning: if you draw on a paletted image with colors that aren't in
-the palette, the image will be internally converted to a normal image.
-
-For improved color precision you can use the bits parameter to specify
-16 bit per channel:
-
- $img = Imager->new(xsize=>200, ysize=>200, channels=>3, bits=>16);
-
-or for even more precision:
-
- $img = Imager->new(xsize=>200, ysize=>200, channels=>3, bits=>'double');
-
-to get an image that uses a double for each channel.
-
-Note that as of this writing all functions should work on images with
-more than 8-bits/channel, but many will only work at only
-8-bit/channel precision.
-
-Currently only 8-bit, 16-bit, and double per channel image types are
-available, this may change later.
-
-Color objects are created by calling the Imager::Color->new()
-method:
-
- $color = Imager::Color->new($red, $green, $blue);
- $color = Imager::Color->new($red, $green, $blue, $alpha);
- $color = Imager::Color->new("#C0C0FF"); # html color specification
-
-This object can then be passed to functions that require a color parameter.
-
-Coordinates in Imager have the origin in the upper left corner. The
-horizontal coordinate increases to the right and the vertical
-downwards.
-
-=head2 Reading and writing images
-
-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.
-
-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;
-
-and the C<write()> method to write an image:
-
- $img->write(file=>$filename, type=>$type)
- or die "Cannot write $filename: ", $img->errstr;
-
-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.
-Imager currently does not check the files magic to determine the
-format. It is possible to override the method for determining the
-filetype from the filename. If the data is given in another form than
-a file name a
-
-When you read an image, Imager may set some tags, possibly including
-information about the spatial resolution, textual information, and
-animation information. See L</Tags> for specifics.
-
-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>.
-
-=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.
-
-=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.
-
-=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.
-
-=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.
-
-=back
-
-C<$img-E<gt>read()> generally takes two parameters, 'file' and 'type'.
-If the type of the file can be determined from the suffix of the file
-it can be omitted. Format dependant parameters are: For images of
-type 'raw' two extra parameters are needed 'xsize' and 'ysize', if the
-'channel' parameter is omitted for type 'raw' it is assumed to be 3.
-gif and png images might have a palette are converted to truecolor bit
-when read. Alpha channel is preserved for png images irregardless of
-them being in RGB or gray colorspace. Similarly grayscale jpegs are
-one channel images after reading them. For jpeg images the iptc
-header information (stored in the APP13 header) is avaliable to some
-degree. You can get the raw header with C<$img-E<gt>{IPTCRAW}>, but
-you can also retrieve the most basic information with
-C<%hsh=$img-E<gt>parseiptc()> as always patches are welcome. pnm has no
-extra options. Examples:
-
- $img = Imager->new();
- $img->read(file=>"cover.jpg") or die $img->errstr; # gets type from name
-
- $img = Imager->new();
- { local(*FH,$/); open(FH,"file.gif") or die $!; $a=<FH>; }
- $img->read(data=>$a,type=>'gif') or die $img->errstr;
-
-The second example shows how to read an image from a scalar, this is
-usefull if your data originates from somewhere else than a filesystem
-such as a database over a DBI connection.
-
-When writing to a tiff image file you can also specify the 'class'
-parameter, which can currently take a single value, "fax". If class
-is set to fax then a tiff image which should be suitable for faxing
-will be written. For the best results start with a grayscale image.
-By default the image is written at fine resolution you can override
-this by setting the "fax_fine" parameter to 0.
-
-If you are reading from a gif image file, you can supply a 'colors'
-parameter which must be a reference to a scalar. The referenced
-scalar will receive an array reference which contains the colors, each
-represented as an Imager::Color object.
-
-If you already have an open file handle, for example a socket or a
-pipe, you can specify the 'fd' parameter instead of supplying a
-filename. Please be aware that you need to use fileno() to retrieve
-the file descriptor for the file:
-
- $img->read(fd=>fileno(FILE), type=>'gif') or die $img->errstr;
-
-For writing using the 'fd' option you will probably want to set $| for
-that descriptor, since the writes to the file descriptor bypass Perl's
-(or the C libraries) buffering. Setting $| should avoid out of order
-output. For example a common idiom when writing a CGI script is:
-
- # the $| _must_ come before you send the content-type
- $| = 1;
- print "Content-Type: image/jpeg\n\n";
- $img->write(fd=>fileno(STDOUT), type=>'jpeg') or die $img->errstr;
-
-*Note that load() is now an alias for read but will be removed later*
-
-C<$img-E<gt>write> has the same interface as C<read()>. The earlier
-comments on C<read()> for autodetecting filetypes apply. For jpegs
-quality can be adjusted via the 'jpegquality' parameter (0-100). The
-number of colorplanes in gifs are set with 'gifplanes' and should be
-between 1 (2 color) and 8 (256 colors). It is also possible to choose
-between two quantizing methods with the parameter 'gifquant'. If set
-to mc it uses the mediancut algorithm from either giflibrary. If set
-to lm it uses a local means algorithm. It is then possible to give
-some extra settings. lmdither is the dither deviation amount in pixels
-(manhattan distance). lmfixed can be an array ref who holds an array
-of Imager::Color objects. Note that the local means algorithm needs
-much more cpu time but also gives considerable better results than the
-median cut algorithm.
-
-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.
-
-Currently just for gif files, you can specify various options for the
-conversion from Imager's internal RGB format to the target's indexed
-file format. If you set the gifquant option to 'gen', you can use the
-options specified under L<Quantization options>.
-
-To see what Imager is compiled to support the following code snippet
-is sufficient:
projects / imager.git / blobdiff