DESCRIPTION

The methods described in Imager::Transformations fall into two categories. Either they take an existing image and modify it in place, or they return a modified copy.

Functions that modify inplace are flip(), paste(), rubthrough() and compose(). If the original is to be left intact it's possible to make a copy and alter the copy:

$flipped = $img->copy()->flip(dir=>'h');

Image copying/resizing/cropping/rotating

A list of the transformations that do not alter the source image follows:

copy()

To create a copy of an image use the copy() method. This is useful if you want to keep an original after doing something that changes the image.

$newimg = $orig->copy();

scale()

To scale an image so proportions are maintained use the $img->scale() method. if you give either a xpixels or ypixels parameter they will determine the width or height respectively. If both are given the one resulting in a larger image is used, unless you set the type parameter to 'min'. example: $img is 700 pixels wide and 500 pixels tall.

If you want to create low quality previews of images you can pass qtype=>'preview' to scale and it will use nearest neighbor sampling instead of filtering. It is much faster but also generates worse looking images - especially if the original has a lot of sharp variations and the scaled image is by more than 3-5 times smaller than the original.

xpixels, ypixels - desired size of the scaled image. The type parameter controls whether the larger or smaller of the two possible sizes is chosen, or if the image is scaled non-proportionally.

constrain - an Image::Math::Constrain object defining the way in which the image size should be constrained.

scalefactor - if none of xpixels, ypixels, xscalefactor, yscalefactor or constrain is supplied then this is used as the ratio to scale by. Default: 0.5.

xscalefactor, yscalefactor - if both are supplied then the image is scaled as per these parameters, whether this is proportionally or not. New in Imager 0.54.

type - controls whether the larger or smaller of the two possible sizes is chosen, possible values are:

min - the smaller of the 2 sizes are chosen.

max - the larger of the 2 sizes. This is the default.

nonprop - non-proportional scaling. New in Imager 0.54.

scale() will fail if type is set to some other value.

For example, if the original image is 400 pixels wide by 200 pixels high and xpixels is set to 300, and ypixels is set to 160. When type is 'min' the resulting image is 300 x 150, when type is 'max' the resulting image is 320 x 160.

preview - lower quality. When scaling down this will skip input pixels, eg. scaling by 0.5 will skip every other pixel. When scaling up this will duplicate pixels.

mixing - implements the mixing algorithm implemented by pnmscale. This retains more detail when scaling down than normal. When scaling down this proportionally accumulates sample data from the pixels, resulting in a proportional mix of all of the pixels. When scaling up this will mix pixels when the sampling grid crosses a pixel boundary but will otherwise copy pixel values.

scale() will fail if qtype is set to some other value.

preview is faster than mixing which is much faster than normal.

To scale an image on a given axis without maintaining proportions, it is best to call the scaleX() and scaleY() methods with the required dimensions. eg.

my $scaled = $img->scaleX(pixels=>400)->scaleY(pixels=>200);

From Imager 0.54 you can scale without maintaining proportions either by supplying both the xscalefactor and yscalefactor arguments:

scalefactor - the amount to scale the Y axis. Ignored if pixels is provided. Default: 0.5.

pixels - the new height of the image.

Returns a new scaled image on success. The source image is not modified.

Returns false on failure, check the errstr() method for the reason for failure.

A mandatory warning is produced if scaleY() is called in void context.

scale_calculate()

Performs the same calculations that the scale() method does to calculate the scaling factors from the parameters you pass.

scale_calculate() can be called as an object method, or as a class method.

Takes the following parameters over scale():

width, height - the image width and height to base the scaling on. Required if scale_calculate() is called as a class method. If called as an object method these default to the image width and height respectively.

You might use scale_calculate() as a class method when generating an HTML IMG tag, for example.

Another way to resize an image is to crop it. The parameters to crop are the edges of the area that you want in the returned image, where the right and bottom edges are non-inclusive. If a parameter is omitted a default is used instead.

crop() returns the cropped image and does not modify the source image.

The possible parameters are:

left - the left edge of the area to be cropped. Default: 0

top - the top edge of the area to be cropped. Default: 0

right - the right edge of the area to be cropped. Default: right edge of image.

bottom - the bottom edge of the area to be cropped. Default: bottom edge of image.

width - width of the crop area. Ignored if both left and right are supplied. Centered on the image if neither left nor right are supplied.

height - height of the crop area. Ignored if both top and bottom are supplied. Centered on the image if neither top nor bottom are supplied.

You can also supply a back argument which acts as a background color for the areas of the image with no samples available (outside the rectangle of the source image.) This can be either an Imager::Color or Imager::Color::Float object. This is not mixed transparent pixels in the middle of the source image, it is only used for pixels where there is no corresponding pixel in the source image.

To rotate in steps of 90 degrees, use the 'right' parameter:

my $rotated = $img->rotate(right=>270);

Rotations are clockwise for positive values.

Parameters:

right - rotate by an exact multiple of 90 degrees, specified in degrees.

radians - rotate by an angle specified in radians.

degrees - rotate by an angle specified in degrees.

back - for radians and degrees this is the color used for the areas not covered by the original image. For example, the corners of an image rotated by 45 degrees.

This can be either an Imager::Color object, an Imager::Color::Float object or any parameter that Imager can convert to a color object, see "Color Parameters" in Imager::Draw for details.

This is not mixed transparent pixels in the middle of the source image, it is only used for pixels where there is no corresponding pixel in the source image.

That will take the sub image defined by $overlay and [src_minx,src_maxx)[src_miny,src_maxy) and overlay it on top of $img with the upper left corner at (30,50). You can rub 2 or 4 channel images onto a 3 channel image, or a 2 channel image onto a 1 channel image. The last channel is used as an alpha channel. To add an alpha channel to an image see convert().

Parameters:

tx, ty - location in the target image ($self) to render the top left corner of the source.

src_minx, src_miny - the top left corner in the source to transfer to the target image. Default: (0, 0).

src_maxx, src_maxy - the bottom right in the source image of the sub image to overlay. This position is non inclusive. Default: bottom right corner of the source image.

That will take the sub image defined by $overlay and [src_minx,src_maxx)[src_miny,src_maxy) and overlay it on top of $img with the upper left corner at (30,50). You can rub 2 or 4 channel images onto a 3 channel image, or a 2 channel image onto a 1 channel image.

Parameters:

src - the source image to draw onto the target. Required.

tx, ty - location in the target image ($self) to render the top left corner of the source. These can also be supplied as left and right. Default: (0, 0).

src_minx, src_miny - the top left corner in the source to transfer to the target image. Default: (0, 0).

src_maxx, src_maxy - the bottom right in the source image of the sub image to overlay. This position is non inclusive. Default: bottom right corner of the source image.

mask - a mask image. The first channel of this image is used to modify the alpha channel of the source image. This can be used to mask out portions of the source image. Where the first channel is zero none of the source image will be used, where the first channel is maximum the full alpha of the source image will be used, as further modified by the opacity.

opacity - further modifies the alpha channel of the source image, in the range 0.0 to 1.0. Default: 1.0.

combine - the method to combine the source pixels with the target. See the combine option documentation in Imager::Fill. Default: normal.

Calling compose() with no mask, combine set to normal, opacity set to 1.0 is equivalent to calling rubthrough().

compose() is intended to be produce similar effects to layers in interactive paint software.

compose() returns true on success. On failure check $target->errstr for the reason for failure.

flip()

An inplace horizontal or vertical flip is possible by calling the flip() method. If the original is to be preserved it's possible to make a copy first. The only parameter it takes is the dir parameter which can take the values h, v, vh and hv.

src - a reference to an array of input images. There must be at least one input image. A given image may appear more than once in src.

channels - a reference to an array of channels corresponding to the source images. If channels is not supplied then the first channel from each input image is used. If the array referenced by channels is shorter than that referenced by src then the first channel is used from the extra images.

Color Mappings

map()

You can use the map method to map the values of each channel of an image independently using a list of look-up tables. It's important to realize that the modification is made inplace. The function simply returns the input image again or undef on failure.

Each channel is mapped independently through a look-up table with 256 entries. The elements in the table should not be less than 0 and not greater than 255. If they are out of the 0..255 range they are clamped to the range. If a table does not contain 256 entries it is silently ignored.

Single channels can mapped by specifying their name and the mapping table. The channel names are red, green, blue, alpha.

@map = map { int( $_/2 } 0..255;
$img->map( red=>\@map );

It is also possible to specify a single map that is applied to all channels, alpha channel included. For example this applies a gamma correction with a gamma of 1.4 to the input image.

As a valued partner and proud supporter of MetaCPAN, StickerYou is
happy to offer a 10% discount on all Custom Stickers,
Business Labels, Roll Labels,
Vinyl Lettering or Custom Decals. StickerYou.com
is your one-stop shop to make your business stick.
Use code METACPAN10 at checkout to apply your discount.