lib/Imager/Engines.pod

   1 =head1 NAME
   2
   3 Imager::Engines - Programmable transformation operations
   4
   5 =head1 SYNOPSIS
   6
   7   use Imager;
   8
   9   my %opts;
  10   my @imgs;
  11   my $img;
  12   ...
  13
  14   my $newimg = $img->transform(
  15       xexpr=>'x',
  16       yexpr=>'y+10*sin((x+y)/10)')
  17     or die $img->errstr;
  18
  19   my $newimg = Imager::transform2(\%opts, @imgs)
  20     or die "transform2 failed: $Imager::ERRSTR";
  21
  22   my $newimg = $img->matrix_transform(
  23      matrix=>[ -1, 0, $img->getwidth-1,
  24                 0,  1, 0,
  25                 0,  0, 1 ]);
  26
  27
  28 =head1 DESCRIPTION
  29
  30 =head2 transform
  31
  32 The C<transform()> function can be used to generate spatial warps and
  33 rotations and such effects.  It only operates on a single image and
  34 its only function is to displace pixels.
  35
  36 It can be given the operations in postfix notation or the module
  37 Affix::Infix2Postfix can be used to generate postfix code from infix
  38 code.  Look in the test case t/t55trans.t for an example.
  39
  40 C<transform()> needs expressions (or opcodes) that determine the
  41 source pixel for each target pixel.  Source expressions are infix
  42 expressions using any of the +, -, *, / or ** binary operators, the -
  43 unary operator, ( and ) for grouping and the sin() and cos()
  44 functions.  The target pixel is input as the variables x and y.
  45
  46 You specify the x and y expressions as xexpr and yexpr respectively.
  47 You can also specify opcodes directly, but that's magic deep enough
  48 that you can look at the source code.
  49
  50 Note: You can still use the transform() function, but the transform2()
  51 function is just as fast and is more likely to be enhanced and
  52 maintained.
  53
  54
  55
  56 =head2 transform2
  57
  58 Imager also supports a C<transform2()> class method which allows you
  59 perform a more general set of operations, rather than just specifying
  60 a spatial transformation as with the transform() method, you can also
  61 perform colour transformations, image synthesis and image
  62 combinations from multiple source images.
  63
  64 C<transform2()> takes an reference to an options hash, and a list of
  65 images to operate one (this list may be empty):
  66
  67   my %opts;
  68   my @imgs;
  69   ...
  70   my $img = Imager::transform2(\%opts, @imgs)
  71       or die "transform2 failed: $Imager::ERRSTR";
  72
  73 The options hash may define a transformation function, and optionally:
  74
  75 =over
  76
  77 =item *
  78
  79 width - the width of the image in pixels.  If this isn't supplied the
  80 width of the first input image is used.  If there are no input images
  81 an error occurs.
  82
  83 =item *
  84
  85 height - the height of the image in pixels.  If this isn't supplied
  86 the height of the first input image is used.  If there are no input
  87 images an error occurs.
  88
  89 =item *
  90
  91 constants - a reference to hash of constants to define for the
  92 expression engine.  Some extra constants are defined by Imager
  93
  94 =back
  95
  96 The tranformation function is specified using either the expr or
  97 rpnexpr member of the options.
  98
  99 =over
 100
 101 =item Infix expressions
 102
 103 You can supply infix expressions to transform 2 with the expr keyword.
 104
 105 $opts{expr} = 'return getp1(w-x, h-y)'
 106
 107 The 'expression' supplied follows this general grammar:
 108
 109    ( identifier '=' expr ';' )* 'return' expr
 110
 111 This allows you to simplify your expressions using variables.
 112
 113 A more complex example might be:
 114
 115 $opts{expr} = 'pix = getp1(x,y); return if(value(pix)>0.8,pix*0.8,pix)'
 116
 117 Currently to use infix expressions you must have the Parse::RecDescent
 118 module installed (available from CPAN).  There is also what might be a
 119 significant delay the first time you run the infix expression parser
 120 due to the compilation of the expression grammar.
 121
 122 =item Postfix expressions
 123
 124 You can supply postfix or reverse-polish notation expressions to
 125 transform2() through the rpnexpr keyword.
 126
 127 The parser for rpnexpr emulates a stack machine, so operators will
 128 expect to see their parameters on top of the stack.  A stack machine
 129 isn't actually used during the image transformation itself.
 130
 131 You can store the value at the top of the stack in a variable called
 132 foo using !foo and retrieve that value again using @foo.  The !foo
 133 notation will pop the value from the stack.
 134
 135 An example equivalent to the infix expression above:
 136
 137  $opts{rpnexpr} = 'x y getp1 !pix @pix value 0.8 gt @pix 0.8 * @pix ifp'
 138
 139 =back
 140
 141 transform2() has a fairly rich range of operators.
 142
 143 =over
 144
 145 =item +, *, -, /, %, **
 146
 147 multiplication, addition, subtraction, division, remainder and
 148 exponentiation.  Multiplication, addition and subtraction can be used
 149 on colour values too - though you need to be careful - adding 2 white
 150 values together and multiplying by 0.5 will give you grey, not white.
 151
 152 Division by zero (or a small number) just results in a large number.
 153 Modulo zero (or a small number) results in zero.
 154
 155 =item sin(N), cos(N), atan2(y,x)
 156
 157 Some basic trig functions.  They work in radians, so you can't just
 158 use the hue values.
 159
 160 =item distance(x1, y1, x2, y2)
 161
 162 Find the distance between two points.  This is handy (along with
 163 atan2()) for producing circular effects.
 164
 165 =item sqrt(n)
 166
 167 Find the square root.  I haven't had much use for this since adding
 168 the distance() function.
 169
 170 =item abs(n)
 171
 172 Find the absolute value.
 173
 174 =item getp1(x,y), getp2(x,y), getp3(x, y)
 175
 176 Get the pixel at position (x,y) from the first, second or third image
 177 respectively.  I may add a getpn() function at some point, but this
 178 prevents static checking of the instructions against the number of
 179 images actually passed in.
 180
 181 =item value(c), hue(c), sat(c), hsv(h,s,v)
 182
 183 Separates a colour value into it's value (brightness), hue (colour)
 184 and saturation elements.  Use hsv() to put them back together (after
 185 suitable manipulation).
 186
 187 =item red(c), green(c), blue(c), rgb(r,g,b)
 188
 189 Separates a colour value into it's red, green and blue colours.  Use
 190 rgb(r,g,b) to put it back together.
 191
 192 =item int(n)
 193
 194 Convert a value to an integer.  Uses a C int cast, so it may break on
 195 large values.
 196
 197 =item if(cond,ntrue,nfalse), if(cond,ctrue,cfalse)
 198
 199 A simple (and inefficient) if function.
 200
 201 =item <=,<,==,>=,>,!=
 202
 203 Relational operators (typically used with if()).  Since we're working
 204 with floating point values the equalities are 'near equalities' - an
 205 epsilon value is used.
 206
 207 =item &&, ||, not(n)
 208
 209 Basic logical operators.
 210
 211 =back
 212
 213 A few examples:
 214
 215 =over
 216
 217 =item rpnexpr=>'x 25 % 15 * y 35 % 10 * getp1 !pat x y getp1 !pix @pix sat 0.7 gt @pat @pix ifp'
 218
 219 tiles a smaller version of the input image over itself where the
 220 colour has a saturation over 0.7.
 221
 222 =item rpnexpr=>'x 25 % 15 * y 35 % 10 * getp1 !pat y 360 / !rat x y getp1 1 @rat - pmult @pat @rat pmult padd'
 223
 224 tiles the input image over itself so that at the top of the image the
 225 full-size image is at full strength and at the bottom the tiling is
 226 most visible.
 227
 228 =item rpnexpr=>'x y getp1 !pix @pix value 0.96 gt @pix sat 0.1 lt and 128 128 255 rgb @pix ifp'
 229
 230 replace pixels that are white or almost white with a palish blue
 231
 232 =item 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'
 233
 234 Tiles the input image overitself where the image isn't white or almost
 235 white.
 236
 237 =item 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'
 238
 239 Produces a spiral.
 240
 241 =item 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'
 242
 243 A spiral built on top of a colour wheel.
 244
 245 =back
 246
 247 For details on expression parsing see L<Imager::Expr>.  For details on
 248 the virtual machine used to transform the images, see
 249 L<Imager::regmach.pod>.
 250
 251
 252 =head2 Matrix Transformations
 253
 254 Rather than having to write code in a little language, you can use a
 255 matrix to perform affine transformations, using the matrix_transform()
 256 method:
 257
 258   my $newimg = $img->matrix_transform(matrix=>[ -1, 0, $img->getwidth-1,
 259                                             0,  1, 0,
 260                                             0,  0, 1 ]);
 261
 262 By default the output image will be the same size as the input image,
 263 but you can supply the xsize and ysize parameters to change the size.
 264
 265 Rather than building matrices by hand you can use the Imager::Matrix2d
 266 module to build the matrices.  This class has methods to allow you to
 267 scale, shear, rotate, translate and reflect, and you can combine these
 268 with an overloaded multiplication operator.
 269
 270 WARNING: the matrix you provide in the matrix operator transforms the
 271 co-ordinates within the B<destination> image to the co-ordinates
 272 within the I<source> image.  This can be confusing.
 273
 274 Since Imager has 3 different fairly general ways of transforming an
 275 image spatially, this method also has a yatf() alias.  Yet Another
 276 Transformation Function.
 277
 278 =cut