Imager::Transformations - Simple transformations of one image into another.

  use Imager;

  $newimg = $img->copy();

  $newimg = $img->scale(xpixels=>400);
  $newimg = $img->scale(xpixels=>400, ypixels=>400);
  $newimg = $img->scale(xpixels=>400, ypixels=>400, type=>'min');
  $newimg = $img->scale(scalefactor=>0.25);

  $newimg = $img->scaleX(pixels=>400);
  $newimg = $img->scaleX(scalefactor=>0.25);
  $newimg = $img->scaleY(pixels=>400);
  $newimg = $img->scaleY(scalefactor=>0.25);

  $newimg = $img->crop(left=>50, right=>100, top=>10, bottom=>100); 
  $newimg = $img->crop(left=>50, top=>10, width=>50, height=>90);

  $dest->paste(left=>40,top=>20,img=>$logo);

  $img->rubthrough(src=>$srcimage,tx=>30, ty=>50);
  $img->rubthrough(src=>$srcimage,tx=>30, ty=>50,
                   src_minx=>20, src_miny=>30,
                   src_maxx=>20, src_maxy=>30);

  $img->flip(dir=>"h");       # horizontal flip
  $img->flip(dir=>"vh");      # vertical and horizontal flip
  $newimg = $img->copy->flip(dir=>"v"); # make a copy and flip it vertically

  my $rot20 = $img->rotate(degrees=>20);
  my $rotpi4 = $img->rotate(radians=>3.14159265/4);

  # Convert image to gray
  $new = $img->convert(preset=>'grey');

  # Swap red/green channel  
  $new = $img->convert(matrix=>[ [ 0, 1, 0 ],
                                 [ 1, 0, 0 ],
                                 [ 0, 0, 1 ] ]);

  # limit the range of red channel from 0..255 to 0..127
  @map = map { int( $_/2 } 0..255;
  $img->map( red=>\@map );

  # Apply a Gamma of 1.4
  my $gamma = 1.4;
  my @map = map { int( 0.5 + 255*($_/255)**$gamma ) } 0..255;
  $img->map(all=>\@map);  # inplace conversion

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 CWflip(), CWpaste() and CWrubthrough(). 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');

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

copy

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

  $newimg = $orig->copy();

scale

To scale an image so porportions are maintained use the CW$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 CWtype parameter to CW'min'. example: CW$img is 700 pixels wide and 500 pixels tall.

  $newimg = $img->scale(xpixels=>400); # 400x285
  $newimg = $img->scale(ypixels=>400); # 560x400

  $newimg = $img->scale(xpixels=>400,ypixels=>400); # 560x400
  $newimg = $img->scale(xpixels=>400,ypixels=>400,type=>'min'); # 400x285

  $newimg = $img->scale(scalefactor=>0.25); 175x125 
  $newimg = $img->scale(); # 350x250

if you want to create low quality previews of images you can pass CWqtype=>'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 resulting image is always scaled proportionally. The CWtype parameter controls whether the larger or smaller of the two possible sizes is chosen.

*

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

*

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

*

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. scale() will fail if CWtype is set to some other value. For example, if the original image is 400 pixels wide by 200 pixels high and CWxpixels is set to 300, and CWypixels is set to 160. When CWtype is CW'min' the resulting image is 300 x 150, when CWtype is CW'max' the resulting image is 320 x 150. CWtype is only used if both CWxpixels and CWypixels are supplied.

*

qtype - defines the quality of scaling performed. Possible values are:

*

normal - high quality scaling. This is the default.

*

preview - lower quality. scale() will fail if CWqtype is set to some other value. 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);

Returns the scaled image on success. Returns false on failure, check the errstr() method for the reason for failure. A mandatory warning is produced if scale() is called in void context.

  # setup
  my $image = Imager->new;
  $image->read(file => 'somefile.jpg')
    or die $image->errstr;

  # all full quality unless indicated otherwise
  # half the size:
  my $half = $image->scale;

  # double the size
  my $double = $image->scale(scalefactor => 2.0);

  # so a 400 x 400 box fits in the resulting image:
  my $fit400x400inside = $image->scale(xpixels => 400, ypixels => 400);
  my $fit400x400inside2 = $image->scale(xpixels => 400, ypixels => 400,
                                        type=>'max');

  # fit inside a 400 x 400 box
  my $inside400x400 = $image->scale(xpixels => 400, ypixels => 400,
                              type=>'min');

  # make it 400 pixels wide or high
  my $width400 = $image->scale(xpixels => 400);
  my $height400 = $image->scale(ypixels => 400);

  # low quality scales:
  # to half size
  my $low = $image->scale(qtype => 'preview');

  # using an Image::Math::Constrain object
  use Image::Math::Constrain;
  my $constrain = Image::Math::Constrain->new(800, 600);
  my $scaled = $image->scale(constrain => $constrain);

  # same as Image::Math::Constrain version
  my $scaled2 = $image->scale(xpixels => 800, ypixels => 600, type => 'min');

scaleX

scaleX() will scale along the X dimension, return a new image with the new width:

  my $newimg = $img->scaleX(pixels=>400); # 400x500
  $newimg = $img->scaleX(scalefactor=>0.25) # 175x500

*

scalefactor - the amount to scale the X axis. Ignored if CWpixels is provided. Default: 0.5.

*

pixels - the new width of the image. Returns the scaled image on success. Returns false on failure, check the errstr() method for the reason for failure. A mandatory warning is produced if scaleX() is called in void context.

scaleY

scaleY() will scale along the Y dimension, return a new image with the new height:

  $newimg = $img->scaleY(pixels=>400); # 700x400
  $newimg = $img->scaleY(scalefactor=>0.25) # 700x125

*

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

*

pixels - the new height of the image. Returns the scaled image on success. 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.

crop

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:

*

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

*

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

*

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

*

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

*

CWwidth - width of the crop area. Ignored if both CWleft and CWright are supplied. Centered on the image if neither CWleft nor CWright are supplied.

*

CWheight - height of the crop area. Ignored if both CWtop and CWbottom are supplied. Centered on the image if neither CWtop nor CWbottom are supplied. For example:

  # these produce the same image
  $newimg = $img->crop(left=>50, right=>100, top=>10, bottom=>100); 
  $newimg = $img->crop(left=>50, top=>10, width=>50, height=>90);
  $newimg = $img->crop(right=>100, bottom=>100, width=>50, height=>90);

  # and the following produce the same image
  $newimg = $img->crop(left=>50, right=>100);
  $newimg = $img->crop(left=>50, right=>100, top=>0, 
                       bottom=>$img->getheight);

  # grab the top left corner of the image
  $newimg = $img->crop(right=>50, bottom=>50);

You can also specify width and height parameters which will produce a new image cropped from the center of the input image, with the given width and height.

  $newimg = $img->crop(width=>50, height=>50);

If you supply CWleft, CWwidth and CWright values, the CWright value will be ignored. If you supply CWtop, CWheight and CWbottom values, the CWbottom value will be ignored. The edges of the cropped area default to the edges of the source image, for example:

  # a vertical bar from the middle from top to bottom
  $newimg = $img->crop(width=>50);

  # the right half
  $newimg = $img->crop(left=>$img->getwidth() / 2);

If the resulting image would have zero width or height then crop() returns false and CW$img->errstr is an appropriate error message. A mandatory warning is produced if crop() is called in void context.

rotate

Use the rotate() method to rotate an image. This method will return a new, rotated image. To rotate by an exact amount in degrees or radians, use the 'degrees' or 'radians' parameter:

  my $rot20 = $img->rotate(degrees=>20);
  my $rotpi4 = $img->rotate(radians=>3.14159265/4);

Exact image rotation uses the same underlying transformation engine as the matrix_transform() method (see Imager::Engines). You can also supply a CWback 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 degreess.

*

radians - rotate by an angle specified in radians.

*

degrees - rotate by an angle specified in degrees.

*

back - for CWradians and CWdegrees 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. Default: transparent black.

  # rotate 45 degrees clockwise, 
  my $rotated = $img->rotate(degrees => 45);

  # rotate 10 degrees counter-clockwise
  # set pixels not sourced from the original to red
  my $rotated = $img->rotate(degrees => -10, back => 'red');

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

paste

To copy an image to onto another image use the CWpaste() method.

  $dest->paste(left=>40, top=>20, src=>$logo);

That copies the entire CW$logo image onto the CW$dest image so that the upper left corner of the CW$logo image is at (40,20). Parameters:

*

src, img - the source image. src added for compatibility with rubthrough().

*

left, top - position in output of the top left of the pasted image. Default: (0,0)

*

src_minx, src_miny - the top left corner in the source image to start the paste from. Default: (0, 0)

*

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

*

width, height - if the corresponding src_maxx or src_maxy is not defined then width or height is used for the width or height of the sub image to be pasted.

  # copy the 20x20 pixel image from (20,20) in $src_image to (10,10) in $img
  $img->paste(src=>$src_image,
              left => 10, top => 10,
              src_minx => 20, src_miny => 20,
              src_maxx => 40, src_maxx => 40);

rubthrough

A more complicated way of blending images is where one image is put 'over' the other with a certain amount of opaqueness. The method that does this is rubthrough.

  $img->rubthrough(src=>$overlay,
                   tx=>30,       ty=>50,
                   src_minx=>20, src_miny=>30,
                   src_maxx=>20, src_maxy=>30);

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 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.

  # overlay all of $source onto $targ
  $targ->rubthrough(tx => 20, ty => 25, src => $source);

  # overlay the top left corner of $source onto $targ
  $targ->rubthrough(tx => 20, ty => 25, src => $source,
                    src_maxx => 20, src_maxy => 20);

  # overlay the bottom right corner of $source onto $targ
  $targ->rubthrough(tx => 20, ty => 30, src => $src,
                    src_minx => $src->getwidth() - 20,
                    src_miny => $src->getheight() - 20);

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

flip

An inplace horizontal or vertical flip is possible by calling the CWflip() method. If the original is to be preserved it's possible to make a copy first. The only parameter it takes is the CWdir parameter which can take the values CWh, CWv, CWvh and CWhv.

  $img->flip(dir=>"h");       # horizontal flip
  $img->flip(dir=>"vh");      # vertical and horizontal flip
  $nimg = $img->copy->flip(dir=>"v"); # make a copy and flip it vertically

flip() returns true on success. On failure check CW$img->errstr for the reason for failure.

convert

You can use the convert method to transform the color space of an image using a matrix. For ease of use some presets are provided. The convert method can be used to:

*

convert an RGB or RGBA image to grayscale.

*

convert a grayscale image to RGB.

*

extract a single channel from an image.

*

set a given channel to a particular value (or from another channel) The currently defined presets are:

gray

grey

converts an RGBA image into a grayscale image with alpha channel, or an RGB image into a grayscale image without an alpha channel. This weights the RGB channels at 22.2%, 70.7% and 7.1% respectively.

noalpha

removes the alpha channel from a 2 or 4 channel image. An identity for other images.

red

channel0

extracts the first channel of the image into a single channel image

green

channel1

extracts the second channel of the image into a single channel image

blue

channel2

extracts the third channel of the image into a single channel image

alpha

extracts the alpha channel of the image into a single channel image. If the image has 1 or 3 channels (assumed to be grayscale of RGB) then the resulting image will be all white.

rgb

converts a grayscale image to RGB, preserving the alpha channel if any

addalpha

adds an alpha channel to a grayscale or RGB image. Preserves an existing alpha channel for a 2 or 4 channel image. For example, to convert an RGB image into a greyscale image:

  $new = $img->convert(preset=>'grey'); # or gray

or to convert a grayscale image to an RGB image:

  $new = $img->convert(preset=>'rgb');

The presets aren't necessary simple constants in the code, some are generated based on the number of channels in the input image. If you want to perform some other colour transformation, you can use the 'matrix' parameter. For each output pixel the following matrix multiplication is done:

  | channel[0] |   | $c00, ...,  $c0k |   | inchannel[0] |
  |    ...     | = |       ...        | x |     ...      |
  | channel[k] |   | $ck0, ...,  $ckk |   | inchannel[k] |
                                                          1
Where C<k = $img-E<gt>getchannels()-1>.

So if you want to swap the red and green channels on a 3 channel image:

  $new = $img->convert(matrix=>[ [ 0, 1, 0 ],
                                 [ 1, 0, 0 ],
                                 [ 0, 0, 1 ] ]);

or to convert a 3 channel image to greyscale using equal weightings:

  $new = $img->convert(matrix=>[ [ 0.333, 0.333, 0.334 ] ])

Convert a 2 channel image (grayscale with alpha) to an RGBA image with the grey converted to the specified RGB color:

  # set (RGB) scaled on the grey scale portion and copy the alpha
  # channel as is
  my $colored = $gray->convert(matrix=>[ [ ($red/255),   0 ], 
                                         [ ($green/255), 0 ], 
                                         [ ($blue/255),  0 ], 
                                         [ 0,            1 ],
                                       ]);

To convert a 3 channel image to a 4 channel image with a 50 percent alpha channel:

  my $withalpha = $rgb->convert(matrix =>[ [ 1, 0, 0, 0 ],
                                           [ 0, 1, 0, 0 ],
                                           [ 0, 0, 1, 0 ],
                                           [ 0, 0, 0, 0.5 ],
                                         ]);

map

You can use the map method to map the values of each channel of an image independently using a list of lookup 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 lookup 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 CWred, CWgreen, CWblue, CWalpha.

  @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.

  $gamma = 1.4;
  @map = map { int( 0.5 + 255*($_/255)**$gamma ) } 0..255;
  $img->map(all=> \@map);

The CWall map is used as a default channel, if no other map is specified for a channel then the CWall map is used instead. If we had not wanted to apply gamma to the alpha channel we would have used:

  $img->map(all=> \@map, alpha=>[]);

Since CW[] contains fewer than 256 element the gamma channel is unaffected. It is also possible to simply specify an array of maps that are applied to the images in the rgba order. For example to apply maps to the CWred and CWblue channels one would use:

  $img->map(maps=>[\@redmap, [], \@bluemap]);

Imager, Imager::Engines

Tony Cook <tony@imager.perl.org>, Arnar M. Hrafnkelsson

$Revision: 930 $