Imager::Engines - Programmable transformation operations
use Imager;
my %opts; my @imgs; my $img; ...
my $newimg = $img->transform(
xexpr=>'x',
yexpr=>'y+10*sin((x+y)/10)')
or die $img->errstr;
my $newimg = Imager::transform2(\%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 ]);
The transform() 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.
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.
transform() 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 sin() and cos()
functions. The target pixel is input as the variables x and y.
You specify the x and y expressions as xexpr and yexpr respectively. You can also specify opcodes directly, but that's magic deep enough that you can look at the source code.
Note: You can still use the transform() function, but the transform2() function is just as fast and is more likely to be enhanced and maintained.
Imager also supports a transform2() class method which allows you
perform a more general set of operations, rather than just specifying
a spatial transformation as with the transform() method, you can also
perform colour transformations, image synthesis and image
combinations from multiple source images.
transform2() takes an reference to an options hash, and a list of
images to operate one (this list may be empty):
my %opts;
my @imgs;
...
my $img = Imager::transform2(\%opts, @imgs)
or die "transform2 failed: $Imager::ERRSTR";
The options hash may define a transformation function, and optionally:
The tranformation function is specified using either the expr or rpnexpr member of the options.
You can supply infix expressions to transform 2 with the expr keyword.
$opts{expr} = 'return getp1(w-x, h-y)'
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.
You can supply postfix or reverse-polish 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'
transform2() has a fairly rich range of operators.
multiplication, addition, subtraction, division, remainder and exponentiation. Multiplication, addition and subtraction can be used on colour values too - though you need to be careful - adding 2 white values together and multiplying by 0.5 will give you grey, not white.
Division by zero (or a small number) just results in a large number. Modulo zero (or a small number) results in zero.
A few examples:
For details on expression parsing see Imager::Expr. For details on the virtual machine used to transform the images, see Imager::regmach.pod.
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->getwidth-1,
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 co-ordinates within the destination image to the co-ordinates within the source image. This can be confusing.
Since Imager has 3 different fairly general ways of transforming an image spatially, this method also has a yatf() alias. Yet Another Transformation Function.