

o  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. 
o  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. 
o  constants  a reference to hash of constants to define for the expression engine. Some extra constants are defined by Imager 
o  channels  the number of channels in the output image. If this isn’t supplied a 3 channel image will be created. 
The transformation function is specified using either the expr or rpnexpr member of the options.  
Infix expressions  
You can supply infix expressions to transform 2 with the expr keyword.  
$opts{expr} = return getp1(wx, hy)  
The ’expression’ supplied follows this general grammar:  
( identifier = expr ; )* return expr  
This allows you to simplify your expressions using variables.  
A more complex example might be:  
$opts{expr} = pix = getp1(x,y); return if(value(pix)>0.8,pix*0.8,pix)  
Currently to use infix expressions you must have the Parse::RecDescent module installed (available from CPAN). 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.  
Postfix expressions  
You can supply postfix or reversepolish notation expressions to transform2() through the rpnexpr keyword.  
The parser for rpnexpr 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.  
You can store the value at the top of the stack in a variable called foo using !foo and retrieve that value again using @foo. The !foo notation will pop the value from the stack.  
An example equivalent to the infix expression above:  
$opts{rpnexpr} = x y getp1 !pix @pix value 0.8 gt @pix 0.8 * @pix ifp  
At the end of the expression there should be a single pixel value left on the stack, which is used as the output pixel.  
Operators  
transform2() has a fairly rich range of operators.  
Each entry below includes the usage with rpnexpr, formatted as:
 
operand operand ... <B>B>operator<B>B> — result  
+, *, , /, %, ** 
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.
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 fmod() so you can use this to take a value mod a floating point value. rpnexpr usage:
 
sin(N), cos(N), atan2(y,x) 
Some basic trig functions. They work in radians, so you can’t just
use the hue values.
rpnexpr usage:
 
distance(x1, y1, x2, y2) 
Find the distance between two points. This is handy (along with
atan2()) for producing circular effects.
rpnexpr usage:
 
sqrt(n) 
Find the square root. I haven’t had much use for this since adding
the distance() function.
rpnexpr usage:
 
abs(n) 
Find the absolute value.
rpnexpr usage:
 
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 getpn() function at some point, but this
prevents static checking of the instructions against the number of
images actually passed in.
rpnexpr usage:
 
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 hsv() to put them back together (after
suitable manipulation), or hsva() to include a transparency value.
rpnexpr usage:
 
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 rgba() to include a
transparency value.
rpnexpr usage:
 
alpha(c) 
Retrieve the alpha value from a color.
rpnexpr usage:
 
int(n) 
Convert a value to an integer. Uses a C int cast, so it may break on
large values.
rpnexpr usage:
 
if(cond,ntrue,nfalse), if(cond,ctrue,cfalse) 
A simple (and inefficient) if function.
rpnexpr usage:
 
<=,<,==,>=,>,!= 
Relational operators (typically used with if()). Since we’re working
with floating point values the equalities are ’near equalities’  an
epsilon value is used.
 
&&, , not(n) 
Basic logical operators.
rpnexpr usage:
 
log(n), exp(n) 
Natural logarithm and exponential.
rpnexpr usage:
 
det(a, b, c, d) 
Calculate the determinant of the 2 x 2 matrix;
a b c d rpnexpr usage:
 
Constants  
transform2() defines the following constants:  
pi  The classical constant.  
w  
h  The width and height of the output image.  
cx  
cy  The center of the output image.  
wimage number  
himage number  The width and height of each of the input images, w1 is the width of the first input image and so on.  
cximage number  
cyimage number  The center of each of the input images, (cx1, cy1) is the center of the first input image and so on.  
A few examples:
rpnexpr=>x 25 % 15 * y 35 % 10 * getp1 !pat x y getp1 !pix @pix sat 0.7 gt @pat @pix ifp
 
tiles a smaller version of the input image over itself where the
color has a saturation over 0.7.
rpnexpr=>x 25 % 15 * y 35 % 10 * getp1 !pat y 360 / !rat x y getp1 1 @rat  pmult @pat @rat pmult padd tiles the input image over itself so that at the top of the image the fullsize image is at full strength and at the bottom the tiling is most visible.
rpnexpr=>x y getp1 !pix @pix value 0.96 gt @pix sat 0.1 lt and 128 128 255 rgb @pix ifp replace pixels that are white or almost white with a palish blue
rpnexpr=>x 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 Tiles the input image over it self where the image isn’t white or almost white.
rpnexpr=>x 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 Produces a spiral.
rpnexpr=>x 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 A spiral built on top of a color wheel.  
# 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(yh/2, xw/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);
matrix_transform() Rather than having to write code in a little language, you can use a matrix to perform affine transformations, using the matrix_transform() method:
my $newimg = $img>matrix_transform(matrix=>[ 1, 0, $img>getwidth1, 0, 1, 0, 0, 0, 1 ]);By default the output image will be the same size as the input image, but you can supply the xsize and ysize parameters to change the size.
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.
WARNING: the matrix you provide in the matrix operator transforms the coordinates within the <B>destinationB> image to the coordinates within the source image. This can be confusing.
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 <B>notB> mixed transparent pixels in the middle of the source image, it is <B>onlyB> used for pixels where there is no corresponding pixel in the source image.
Tony Cook <tonyc@cpan.org>, Arnar M. Hrafnkelsson
perl v5.20.3  IMAGER::ENGINES (3)  20140110 
Visit the GSP FreeBSD Man Page Interface.
Output converted with manServer 1.07.