.\" Automatically generated by Pod::Man 4.11 (Pod::Simple 3.35)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Imager::Engines 3"
.TH Imager::Engines 3 "2014-01-10" "perl v5.26.3" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Imager::Engines \- Programmable transformation operations
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&  use Imager;
\&
\&  my %opts;
\&  my @imgs;
\&  my $img;
\&  ...
\&
\&  my $newimg = $img\->transform(
\&      xexpr=>\*(Aqx\*(Aq,
\&      yexpr=>\*(Aqy+10*sin((x+y)/10)\*(Aq)
\&    or die $img\->errstr;
\&
\&  my $newimg = Imager::transform2(\e%opts, @imgs)
\&    or die "transform2 failed: $Imager::ERRSTR";
\&
\&  my $newimg = $img\->matrix_transform(
\&     matrix=>[ \-1, 0, $img\->getwidth\-1,
\&                0,  1, 0,
\&                0,  0, 1 ]);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
.SS "\fBtransform()\fP"
.IX Subsection "transform()"
The \f(CW\*(C`transform()\*(C'\fR function can be used to generate spatial warps and
rotations and such effects.  It only operates on a single image and
its only function is to displace pixels.
.PP
It can be given the operations in postfix notation or the module
Affix::Infix2Postfix can be used to generate postfix code from infix
code.  Look in the test case t/t55trans.t for an example.
.PP
\&\f(CW\*(C`transform()\*(C'\fR needs expressions (or opcodes) that determine the
source pixel for each target pixel.  Source expressions are infix
expressions using any of the +, \-, *, / or ** binary operators, the \-
unary operator, ( and ) for grouping and the \f(CW\*(C`sin()\*(C'\fR and \f(CW\*(C`cos()\*(C'\fR
functions.  The target pixel is input as the variables x and y.
.PP
You specify the x and y expressions as \f(CW\*(C`xexpr\*(C'\fR and \f(CW\*(C`yexpr\*(C'\fR respectively.
You can also specify opcodes directly, but that's magic deep enough
that you can look at the source code.
.PP
Note: You can still use the \fBtransform()\fR function, but the \fBtransform2()\fR
function is just as fast and is more likely to be enhanced and
maintained.
.PP
.Vb 1
\&  $new_img=$img\->transform(xexpr=>\*(Aqx\*(Aq,yexpr=>\*(Aqy+10*sin((x+y)/10)\*(Aq)
\&
\&  $new_img=$img\->transform(xexpr=>\*(Aqx+0.1*y+5*sin(y/10.0+1.57)\*(Aq,
\&                           yexpr=>\*(Aqy+10*sin((x+y\-0.785)/10)\*(Aq)
.Ve
.SS "\fBtransform2()\fP"
.IX Subsection "transform2()"
Imager also supports a \f(CW\*(C`transform2()\*(C'\fR class method which allows you
perform a more general set of operations, rather than just specifying
a spatial transformation as with the \fBtransform()\fR method, you can also
perform color transformations, image synthesis and image
combinations from multiple source images.
.PP
\&\f(CW\*(C`transform2()\*(C'\fR takes an reference to an options hash, and a list of
images to operate one (this list may be empty):
.PP
.Vb 5
\&  my %opts;
\&  my @imgs;
\&  ...
\&  my $img = Imager::transform2(\e%opts, @imgs)
\&      or die "transform2 failed: $Imager::ERRSTR";
.Ve
.PP
The options hash may define a transformation function, and optionally:
.IP "\(bu" 4
width \- the width of the image in pixels.  If this isn't supplied the
width of the first input image is used.  If there are no input images
an error occurs.
.IP "\(bu" 4
height \- the height of the image in pixels.  If this isn't supplied
the height of the first input image is used.  If there are no input
images an error occurs.
.IP "\(bu" 4
constants \- a reference to hash of constants to define for the
expression engine.  Some extra constants are defined by Imager
.IP "\(bu" 4
channels \- the number of channels in the output image.  If this isn't
supplied a 3 channel image will be created.
.PP
The transformation function is specified using either the \f(CW\*(C`expr\*(C'\fR or
\&\f(CW\*(C`rpnexpr\*(C'\fR member of the options.
.PP
\fIInfix expressions\fR
.IX Subsection "Infix expressions"
.PP
You can supply infix expressions to transform 2 with the \f(CW\*(C`expr\*(C'\fR keyword.
.PP
.Vb 1
\&  $opts{expr} = \*(Aqreturn getp1(w\-x, h\-y)\*(Aq
.Ve
.PP
The 'expression' supplied follows this general grammar:
.PP
.Vb 1
\&   ( identifier \*(Aq=\*(Aq expr \*(Aq;\*(Aq )* \*(Aqreturn\*(Aq expr
.Ve
.PP
This allows you to simplify your expressions using variables.
.PP
A more complex example might be:
.PP
.Vb 1
\&  $opts{expr} = \*(Aqpix = getp1(x,y); return if(value(pix)>0.8,pix*0.8,pix)\*(Aq
.Ve
.PP
Currently to use infix expressions you must have the Parse::RecDescent
module installed (available from \s-1CPAN\s0).  There is also what might be a
significant delay the first time you run the infix expression parser
due to the compilation of the expression grammar.
.PP
\fIPostfix expressions\fR
.IX Subsection "Postfix expressions"
.PP
You can supply postfix or reverse-polish notation expressions to
\&\fBtransform2()\fR through the \f(CW\*(C`rpnexpr\*(C'\fR keyword.
.PP
The parser for \f(CW\*(C`rpnexpr\*(C'\fR emulates a stack machine, so operators will
expect to see their parameters on top of the stack.  A stack machine
isn't actually used during the image transformation itself.
.PP
You can store the value at the top of the stack in a variable called
\&\f(CW\*(C`foo\*(C'\fR using \f(CW\*(C`!foo\*(C'\fR and retrieve that value again using \f(CW@foo\fR.  The !foo
notation will pop the value from the stack.
.PP
An example equivalent to the infix expression above:
.PP
.Vb 1
\& $opts{rpnexpr} = \*(Aqx y getp1 !pix @pix value 0.8 gt @pix 0.8 * @pix ifp\*(Aq
.Ve
.PP
At the end of the expression there should be a single pixel value left
on the stack, which is used as the output pixel.
.PP
\fIOperators\fR
.IX Subsection "Operators"
.PP
\&\fBtransform2()\fR has a fairly rich range of operators.
.PP
Each entry below includes the usage with \f(CW\*(C`rpnexpr\*(C'\fR, formatted as:
.Sp
.RS 4
\&\fIoperand\fR \fIoperand\fR ... \fB\f(BIoperator\fB\fR \*(-- \fIresult\fR
.RE
.PP
If the operand or result begins with \*(L"N\*(R" it is a numeric value, if it
begins with \*(L"C\*(R" it is a color or pixel value.
.IP "+, *, \-, /, %, **" 4
multiplication, addition, subtraction, division, remainder and
exponentiation.  Multiplication, addition and subtraction can be used
on color values too \- though you need to be careful \- adding 2 white
values together and multiplying by 0.5 will give you gray, not white.
.Sp
Division by zero (or a small number) just results in a large number.
Modulo zero (or a small number) results in zero.  % is implemented
using \fBfmod()\fR so you can use this to take a value mod a floating point
value.
.Sp
\&\f(CW\*(C`rpnexpr\*(C'\fR usage:
.RS 4
.Sp
.RS 4
\&\fIN1\fR \fIN2\fR \fB+\fR \*(-- \fIN\fR
.Sp
\&\fIN1\fR \fIN2\fR \fB*\fR \*(-- \fIN\fR
.Sp
\&\fIN1\fR \fIN2\fR \fB\-\fR \*(-- \fIN\fR
.Sp
\&\fIN1\fR \fIN2\fR \fB/\fR \*(-- \fIN\fR
.Sp
\&\fIN1\fR \fIN2\fR \fB**\fR \*(-- \fIN\fR
.Sp
\&\fIN1\fR \fBuminus\fR \*(-- \fIN\fR
.RE
.RE
.RS 4
.RE
.IP "sin(N), cos(N), atan2(y,x)" 4
.IX Item "sin(N), cos(N), atan2(y,x)"
Some basic trig functions.  They work in radians, so you can't just
use the hue values.
.Sp
\&\f(CW\*(C`rpnexpr\*(C'\fR usage:
.RS 4
.Sp
.RS 4
\&\fIN\fR \fBsin\fR \*(-- \fIN\fR
.Sp
\&\fIN\fR \fBcos\fR \*(-- \fIN\fR
.Sp
\&\fINy\fR \fINx\fR \fBatan2\fR \*(-- \fIN\fR
.RE
.RE
.RS 4
.RE
.IP "distance(x1, y1, x2, y2)" 4
.IX Item "distance(x1, y1, x2, y2)"
Find the distance between two points.  This is handy (along with
\&\fBatan2()\fR) for producing circular effects.
.Sp
\&\f(CW\*(C`rpnexpr\*(C'\fR usage:
.RS 4
.Sp
.RS 4
\&\fINx1\fR \fINy1\fR \fINx2\fR \fINy2\fR \fBdistance\fR \*(-- \fIN\fR
.RE
.RE
.RS 4
.RE
.IP "sqrt(n)" 4
.IX Item "sqrt(n)"
Find the square root.  I haven't had much use for this since adding
the \fBdistance()\fR function.
.Sp
\&\f(CW\*(C`rpnexpr\*(C'\fR usage:
.RS 4
.Sp
.RS 4
\&\fIN\fR \fBsqrt\fR \*(-- \fIN\fR
.RE
.RE
.RS 4
.RE
.IP "abs(n)" 4
.IX Item "abs(n)"
Find the absolute value.
.Sp
\&\f(CW\*(C`rpnexpr\*(C'\fR usage:
.RS 4
.Sp
.RS 4
\&\fIN\fR \fBabs\fR \*(-- \fIN\fR
.RE
.RE
.RS 4
.RE
.IP "getp1(x,y), getp2(x,y), getp3(x, y)" 4
.IX Item "getp1(x,y), getp2(x,y), getp3(x, y)"
Get the pixel at position (x,y) from the first, second or third image
respectively.  I may add a \fBgetpn()\fR function at some point, but this
prevents static checking of the instructions against the number of
images actually passed in.
.Sp
\&\f(CW\*(C`rpnexpr\*(C'\fR usage:
.RS 4
.Sp
.RS 4
\&\fINx\fR \fINy\fR \fBgetp1\fR \*(-- \fIC\fR
.Sp
\&\fINx\fR \fINy\fR \fBgetp2\fR \*(-- \fIC\fR
.Sp
\&\fINx\fR \fINy\fR \fBgetp3\fR \*(-- \fIC\fR
.RE
.RE
.RS 4
.RE
.IP "value(c), hue(c), sat(c), hsv(h,s,v), hsva(h,s,v,alpha)" 4
.IX Item "value(c), hue(c), sat(c), hsv(h,s,v), hsva(h,s,v,alpha)"
Separates a color value into it's value (brightness), hue (color)
and saturation elements.  Use \fBhsv()\fR to put them back together (after
suitable manipulation), or \fBhsva()\fR to include a transparency value.
.Sp
\&\f(CW\*(C`rpnexpr\*(C'\fR usage:
.RS 4
.Sp
.RS 4
\&\fIC\fR \fBvalue\fR \*(-- \fIN\fR
.Sp
\&\fIC\fR \fBhue\fR \*(-- \fIN\fR
.Sp
\&\fIC\fR \fBsat\fR \*(-- \fIN\fR
.Sp
\&\fINh\fR \fINs\fR \fINv\fR \fBhsv\fR \*(-- \fIC\fR
.Sp
\&\fINh\fR \fINs\fR \fINv\fR \fINa\fR \fBhsva\fR \*(-- \fIC\fR
.RE
.RE
.RS 4
.RE
.IP "red(c), green(c), blue(c), rgb(r,g,b), rgba(r,g,b,a)" 4
.IX Item "red(c), green(c), blue(c), rgb(r,g,b), rgba(r,g,b,a)"
Separates a color value into it's red, green and blue colors.  Use
rgb(r,g,b) to put it back together, or \fBrgba()\fR to include a
transparency value.
.Sp
\&\f(CW\*(C`rpnexpr\*(C'\fR usage:
.RS 4
.Sp
.RS 4
\&\fIC\fR \fBred\fR \*(-- \fIN\fR
.Sp
\&\fIC\fR \fBgreen\fR \*(-- \fIN\fR
.Sp
\&\fIC\fR \fBblue\fR \*(-- \fIN\fR
.Sp
\&\fINr\fR \fINg\fR \fINb\fR \fBrgb\fR \*(-- \fIC\fR
.Sp
\&\fINr\fR \fINg\fR \fINb\fR \fINa\fR \fBrgba\fR \*(-- \fIC\fR
.RE
.RE
.RS 4
.RE
.IP "alpha(c)" 4
.IX Item "alpha(c)"
Retrieve the alpha value from a color.
.Sp
\&\f(CW\*(C`rpnexpr\*(C'\fR usage:
.RS 4
.Sp
.RS 4
\&\fIC\fR \fBalpha\fR \*(-- \fIN\fR
.RE
.RE
.RS 4
.RE
.IP "int(n)" 4
.IX Item "int(n)"
Convert a value to an integer.  Uses a C int cast, so it may break on
large values.
.Sp
\&\f(CW\*(C`rpnexpr\*(C'\fR usage:
.RS 4
.Sp
.RS 4
\&\fIN\fR \fBint\fR \*(-- \fIN\fR
.RE
.RE
.RS 4
.RE
.IP "if(cond,ntrue,nfalse), if(cond,ctrue,cfalse)" 4
.IX Item "if(cond,ntrue,nfalse), if(cond,ctrue,cfalse)"
A simple (and inefficient) if function.
.Sp
\&\f(CW\*(C`rpnexpr\*(C'\fR usage:
.RS 4
.Sp
.RS 4
\&\fINcond\fR \fIN\-true-result\fR \fIN\-false-result\fR \fBif\fR \*(-- \fIN\fR
.Sp
\&\fINcond\fR \fIC\-true-result\fR \fIC\-false-result\fR \fBif\fR \*(-- \fIC\fR
.Sp
\&\fINcond\fR \fIC\-true-result\fR \fIC\-false-result\fR \fBifp\fR \*(-- \fIC\fR
.RE
.RE
.RS 4
.RE
.IP "<=,<,==,>=,>,!=" 4
Relational operators (typically used with \fBif()\fR).  Since we're working
with floating point values the equalities are 'near equalities' \- an
epsilon value is used.
.RS 4
.Sp
.RS 4
\&\fIN1\fR \fIN2\fR \fB<=\fR \*(-- \fIN\fR
.Sp
\&\fIN1\fR \fIN2\fR \fB<\fR \*(-- \fIN\fR
.Sp
\&\fIN1\fR \fIN2\fR \fB>=\fR \*(-- \fIN\fR
.Sp
\&\fIN1\fR \fIN2\fR \fB>\fR \*(-- \fIN\fR
.Sp
\&\fIN1\fR \fIN2\fR \fB==\fR \*(-- \fIN\fR
.Sp
\&\fIN1\fR \fIN2\fR \fB!=\fR \*(-- \fIN\fR
.RE
.RE
.RS 4
.RE
.IP "&&, ||, not(n)" 4
.IX Item "&&, ||, not(n)"
Basic logical operators.
.Sp
\&\f(CW\*(C`rpnexpr\*(C'\fR usage:
.RS 4
.Sp
.RS 4
\&\fIN1\fR \fIN2\fR \fBand\fR \*(-- \fIN\fR
.Sp
\&\fIN1\fR \fIN2\fR \fBor\fR \*(-- \fIN\fR
.Sp
\&\fIN\fR \fBnot\fR \*(-- \fIN\fR
.RE
.RE
.RS 4
.RE
.IP "log(n), exp(n)" 4
.IX Item "log(n), exp(n)"
Natural logarithm and exponential.
.Sp
\&\f(CW\*(C`rpnexpr\*(C'\fR usage:
.RS 4
.Sp
.RS 4
\&\fIN\fR \fBlog\fR \*(-- \fIN\fR
.Sp
\&\fIN\fR \fBexp\fR \*(-- \fIN\fR
.RE
.RE
.RS 4
.RE
.IP "det(a, b, c, d)" 4
.IX Item "det(a, b, c, d)"
Calculate the determinant of the 2 x 2 matrix;
.Sp
.Vb 2
\&  a b
\&  c d
.Ve
.Sp
\&\f(CW\*(C`rpnexpr\*(C'\fR usage:
.RS 4
.Sp
.RS 4
\&\fINa\fR \fINb\fR \fINc\fR \fINd\fR \fBdet\fR \*(-- \fIN\fR
.RE
.RE
.RS 4
.RE
.PP
\fIConstants\fR
.IX Subsection "Constants"
.PP
\&\fBtransform2()\fR defines the following constants:
.ie n .IP """pi""" 4
.el .IP "\f(CWpi\fR" 4
.IX Item "pi"
The classical constant.
.ie n .IP """w""" 4
.el .IP "\f(CWw\fR" 4
.IX Item "w"
.PD 0
.ie n .IP """h""" 4
.el .IP "\f(CWh\fR" 4
.IX Item "h"
.PD
The width and height of the output image.
.ie n .IP """cx""" 4
.el .IP "\f(CWcx\fR" 4
.IX Item "cx"
.PD 0
.ie n .IP """cy""" 4
.el .IP "\f(CWcy\fR" 4
.IX Item "cy"
.PD
The center of the output image.
.ie n .IP """w""\fIimage number\fR" 4
.el .IP "\f(CWw\fR\fIimage number\fR" 4
.IX Item "wimage number"
.PD 0
.ie n .IP """h""\fIimage number\fR" 4
.el .IP "\f(CWh\fR\fIimage number\fR" 4
.IX Item "himage number"
.PD
The width and height of each of the input images, \f(CW\*(C`w1\*(C'\fR is the width
of the first input image and so on.
.ie n .IP """cx""\fIimage number\fR" 4
.el .IP "\f(CWcx\fR\fIimage number\fR" 4
.IX Item "cximage number"
.PD 0
.ie n .IP """cy""\fIimage number\fR" 4
.el .IP "\f(CWcy\fR\fIimage number\fR" 4
.IX Item "cyimage number"
.PD
The center of each of the input images, (\f(CW\*(C`cx1\*(C'\fR, \f(CW\*(C`cy1\*(C'\fR) is the center
of the first input image and so on.
.PP
A few examples:
.Sp
.Vb 1
\&  rpnexpr=>\*(Aqx 25 % 15 * y 35 % 10 * getp1 !pat x y getp1 !pix @pix sat 0.7 gt @pat @pix ifp\*(Aq
.Ve
.Sp
.RS 4
tiles a smaller version of the input image over itself where the
color has a saturation over 0.7.
.Sp
.Vb 1
\&  rpnexpr=>\*(Aqx 25 % 15 * y 35 % 10 * getp1 !pat y 360 / !rat x y getp1 1 @rat \- pmult @pat @rat pmult padd\*(Aq
.Ve
.Sp
tiles the input image over itself so that at the top of the image the
full-size image is at full strength and at the bottom the tiling is
most visible.
.Sp
.Vb 1
\&  rpnexpr=>\*(Aqx y getp1 !pix @pix value 0.96 gt @pix sat 0.1 lt and 128 128 255 rgb @pix ifp\*(Aq
.Ve
.Sp
replace pixels that are white or almost white with a palish blue
.Sp
.Vb 1
\&  rpnexpr=>\*(Aqx 35 % 10 * y 45 % 8 * getp1 !pat x y getp1 !pix @pix sat 0.2 lt @pix value 0.9 gt and @pix @pat @pix value 2 / 0.5 + pmult ifp\*(Aq
.Ve
.Sp
Tiles the input image over it self where the image isn't white or almost
white.
.Sp
.Vb 1
\&  rpnexpr=>\*(Aqx y 160 180 distance !d y 180 \- x 160 \- atan2 !a @d 10 / @a + 3.1416 2 * % !a2 @a2 180 * 3.1416 / 1 @a2 sin 1 + 2 / hsv\*(Aq
.Ve
.Sp
Produces a spiral.
.Sp
.Vb 1
\&  rpnexpr=>\*(Aqx y 160 180 distance !d y 180 \- x 160 \- atan2 !a @d 10 / @a + 3.1416 2 * % !a2 @a 180 * 3.1416 / 1 @a2 sin 1 + 2 / hsv\*(Aq
.Ve
.Sp
A spiral built on top of a color wheel.
.RE
.PP
For details on expression parsing see Imager::Expr.  For details on
the virtual machine used to transform the images, see
Imager::regmach.
.PP
.Vb 11
\&  # generate a colorful spiral
\&  # requires that Parse::RecDescent be installed
\&  my $newimg = Imager::transform2({
\&                                   width => 160, height=>160,
\&                                   expr => <<EOS
\&  dist = distance(x, y, w/2, h/2);
\&  angle = atan2(y\-h/2, x\-w/2);
\&  angle2 = (dist / 10 + angle) % ( 2 * pi );
\&  return hsv(angle*180/pi, 1, (sin(angle2)+1)/2);
\&  EOS
\&                                  });
\&
\&  # replace green portions of an image with another image
\&  my $newimg = Imager::transform2({
\&                                   rpnexpr => <<EOS
\&  x y getp2 !pat # used to replace green portions
\&  x y getp1 !pix # source with "green screen"
\&  @pix red 10 lt @pix blue 10 lt && # low blue and red
\&  @pix green 254 gt && # and high green
\&  @pat @pix ifp
\&  EOS
\&                                  }, $source, $background);
.Ve
.SS "Matrix Transformations"
.IX Subsection "Matrix Transformations"
.IP "\fBmatrix_transform()\fR" 4
.IX Item "matrix_transform()"
Rather than having to write code in a little language, you can use a
matrix to perform affine transformations, using the \fBmatrix_transform()\fR
method:
.Sp
.Vb 3
\&  my $newimg = $img\->matrix_transform(matrix=>[ \-1, 0, $img\->getwidth\-1,
\&                                            0,  1, 0,
\&                                            0,  0, 1 ]);
.Ve
.Sp
By default the output image will be the same size as the input image,
but you can supply the \f(CW\*(C`xsize\*(C'\fR and \f(CW\*(C`ysize\*(C'\fR parameters to change the
size.
.Sp
Rather than building matrices by hand you can use the Imager::Matrix2d
module to build the matrices.  This class has methods to allow you to
scale, shear, rotate, translate and reflect, and you can combine these
with an overloaded multiplication operator.
.Sp
\&\s-1WARNING:\s0 the matrix you provide in the matrix operator transforms the
co-ordinates within the \fBdestination\fR image to the co-ordinates
within the \fIsource\fR image.  This can be confusing.
.Sp
You can also supply a \f(CW\*(C`back\*(C'\fR 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 \fBnot\fR mixed
transparent pixels in the middle of the source image, it is \fBonly\fR
used for pixels where there is no corresponding pixel in the source
image.
.SH "AUTHOR"
.IX Header "AUTHOR"
Tony Cook <tonyc@cpan.org>, Arnar M. Hrafnkelsson