- added the det() function to the transform2() engine.
[imager.git] / 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   $new_img=$img->transform(xexpr=>'x',yexpr=>'y+10*sin((x+y)/10)')
55
56   $new_img=$img->transform(xexpr=>'x+0.1*y+5*sin(y/10.0+1.57)',
57                            yexpr=>'y+10*sin((x+y-0.785)/10)') 
58
59 =head2 transform2
60
61 Imager also supports a C<transform2()> class method which allows you
62 perform a more general set of operations, rather than just specifying
63 a spatial transformation as with the transform() method, you can also
64 perform colour transformations, image synthesis and image
65 combinations from multiple source images.
66
67 C<transform2()> takes an reference to an options hash, and a list of
68 images to operate one (this list may be empty):
69
70   my %opts;
71   my @imgs;
72   ...
73   my $img = Imager::transform2(\%opts, @imgs)
74       or die "transform2 failed: $Imager::ERRSTR";
75
76 The options hash may define a transformation function, and optionally:
77
78 =over
79
80 =item *
81
82 width - the width of the image in pixels.  If this isn't supplied the
83 width of the first input image is used.  If there are no input images
84 an error occurs.
85
86 =item *
87
88 height - the height of the image in pixels.  If this isn't supplied
89 the height of the first input image is used.  If there are no input
90 images an error occurs.
91
92 =item *
93
94 constants - a reference to hash of constants to define for the
95 expression engine.  Some extra constants are defined by Imager
96
97 =item *
98
99 channels - the number of channels in the output image.  If this isn't
100 supplied a 3 channel image will be created.
101
102 =back
103
104 The tranformation function is specified using either the expr or
105 rpnexpr member of the options.
106
107 =head3 Infix expressions
108
109 You can supply infix expressions to transform 2 with the expr keyword.
110
111   $opts{expr} = 'return getp1(w-x, h-y)'
112
113 The 'expression' supplied follows this general grammar:
114
115    ( identifier '=' expr ';' )* 'return' expr
116
117 This allows you to simplify your expressions using variables.
118
119 A more complex example might be:
120
121   $opts{expr} = 'pix = getp1(x,y); return if(value(pix)>0.8,pix*0.8,pix)'
122
123 Currently to use infix expressions you must have the L<Parse::RecDescent>
124 module installed (available from CPAN).  There is also what might be a
125 significant delay the first time you run the infix expression parser
126 due to the compilation of the expression grammar.
127
128 =head3 Postfix expressions
129
130 You can supply postfix or reverse-polish notation expressions to
131 transform2() through the rpnexpr keyword.
132
133 The parser for rpnexpr emulates a stack machine, so operators will
134 expect to see their parameters on top of the stack.  A stack machine
135 isn't actually used during the image transformation itself.
136
137 You can store the value at the top of the stack in a variable called
138 foo using !foo and retrieve that value again using @foo.  The !foo
139 notation will pop the value from the stack.
140
141 An example equivalent to the infix expression above:
142
143  $opts{rpnexpr} = 'x y getp1 !pix @pix value 0.8 gt @pix 0.8 * @pix ifp'
144
145 At the end of the expression there should be a single pixel value left
146 on the stack, which is used as the output pixel.
147
148 =head3 Operators
149
150 transform2() has a fairly rich range of operators.
151
152 Each entry below includes the usage with rpnexpr, formatted as:
153
154 =over
155
156 I<operand> I<operand> ... B<I<operator>> -- I<result>
157
158 =back
159
160 If the operand or result begins with "N" it is a numeric value, if it
161 begins with "C" it is a color or pixel value.
162
163 =over
164
165 =item +, *, -, /, %, **
166
167 multiplication, addition, subtraction, division, remainder and
168 exponentiation.  Multiplication, addition and subtraction can be used
169 on colour values too - though you need to be careful - adding 2 white
170 values together and multiplying by 0.5 will give you grey, not white.
171
172 Division by zero (or a small number) just results in a large number.
173 Modulo zero (or a small number) results in zero.  % is implemented
174 using fmod() so you can use this to take a value mod a floating point
175 value.
176
177 rpnexpr usage:
178
179 =over
180
181 I<N1> I<N2> B<+> -- I<N>
182
183 I<N1> I<N2> B<*> -- I<N>
184
185 I<N1> I<N2> B<-> -- I<N>
186
187 I<N1> I<N2> B</> -- I<N>
188
189 I<N1> I<N2> B<**> -- I<N>
190
191 I<N1> B<uminus> -- I<N>
192
193 =back
194
195 =item sin(N), cos(N), atan2(y,x)
196
197 Some basic trig functions.  They work in radians, so you can't just
198 use the hue values.
199
200 rpnexpr usage:
201
202 =over
203
204 I<N> B<sin> -- I<N>
205
206 I<N> B<cos> -- I<N>
207
208 I<Ny> I<Nx> B<atan2> -- I<N>
209
210 =back
211
212 =item distance(x1, y1, x2, y2)
213
214 Find the distance between two points.  This is handy (along with
215 atan2()) for producing circular effects.
216
217 rpnexpr usage:
218
219 =over
220
221 I<Nx1> I<Ny1> I<Nx2> I<Ny2> B<distance> -- I<N>
222
223 =back
224
225 =item sqrt(n)
226
227 Find the square root.  I haven't had much use for this since adding
228 the distance() function.
229
230 rpnexpr usage:
231
232 =over
233
234 I<N> B<sqrt> -- I<N>
235
236 =back
237
238 =item abs(n)
239
240 Find the absolute value.
241
242 rpnexpr usage:
243
244 =over
245
246 I<N> B<abs> -- I<N>
247
248 =back
249
250 =item getp1(x,y), getp2(x,y), getp3(x, y)
251
252 Get the pixel at position (x,y) from the first, second or third image
253 respectively.  I may add a getpn() function at some point, but this
254 prevents static checking of the instructions against the number of
255 images actually passed in.
256
257 rpnexpr usage:
258
259 =over
260
261 I<Nx> I<Ny> B<getp1> -- I<C>
262
263 I<Nx> I<Ny> B<getp2> -- I<C>
264
265 I<Nx> I<Ny> B<getp3> -- I<C>
266
267 =back
268
269 =item value(c), hue(c), sat(c), hsv(h,s,v), hsva(h,s,v,alpha)
270
271 Separates a colour value into it's value (brightness), hue (colour)
272 and saturation elements.  Use hsv() to put them back together (after
273 suitable manipulation), or hsva() to include a tranparency value.
274
275 rpnexpr usage:
276
277 =over
278
279 I<C> B<value> -- I<N>
280
281 I<C> B<hue> -- I<N>
282
283 I<C> B<sat> -- I<N>
284
285 I<Nh> I<Ns> I<Nv> B<hsv> -- I<C>
286
287 I<Nh> I<Ns> I<Nv> I<Na> B<hsva> -- I<C>
288
289 =back
290
291 =item red(c), green(c), blue(c), rgb(r,g,b), rgba(r,g,b,a)
292
293 Separates a colour value into it's red, green and blue colours.  Use
294 rgb(r,g,b) to put it back together, or rgba() to include a
295 transparency value.
296
297 rpnexpr usage:
298
299 =over
300
301 I<C> B<red> -- I<N>
302
303 I<C> B<green> -- I<N>
304
305 I<C> B<blue> -- I<N>
306
307 I<Nr> I<Ng> I<Nb> B<rgb> -- I<C>
308
309 I<Nr> I<Ng> I<Nb> I<Na> B<rgba> -- I<C>
310
311 =back
312
313 =item alpha(c)
314
315 Retrieve the alpha value from a colour.
316
317 rpnexpr usage:
318
319 =over
320
321 I<C> B<alpha> -- I<N>
322
323 =back
324
325 =item int(n)
326
327 Convert a value to an integer.  Uses a C int cast, so it may break on
328 large values.
329
330 rpnexpr usage:
331
332 =over
333
334 I<N> B<int> -- I<N>
335
336 =back
337
338 =item if(cond,ntrue,nfalse), if(cond,ctrue,cfalse)
339
340 A simple (and inefficient) if function.
341
342 rpnexpr usage:
343
344 =over
345
346 I<Ncond> I<N-true-result> I<N-false-result> B<if> -- I<N>
347
348 I<Ncond> I<C-true-result> I<C-false-result> B<if> -- I<C>
349
350 I<Ncond> I<C-true-result> I<C-false-result> B<ifp> -- I<C>
351
352 =back
353
354 =item <=,<,==,>=,>,!=
355
356 Relational operators (typically used with if()).  Since we're working
357 with floating point values the equalities are 'near equalities' - an
358 epsilon value is used.
359
360 =over
361
362 I<N1> I<N2> B<< <= >> -- I<N>
363
364 I<N1> I<N2> B<< < >> -- I<N>
365
366 I<N1> I<N2> B<< >= >> -- I<N>
367
368 I<N1> I<N2> B<< > >> -- I<N>
369
370 I<N1> I<N2> B<< == >> -- I<N>
371
372 I<N1> I<N2> B<< != >> -- I<N>
373
374 =back
375
376 =item &&, ||, not(n)
377
378 Basic logical operators.
379
380 rpnexpr usage:
381
382 =over
383
384 I<N1> I<N2> B<and> -- I<N>
385
386 I<N1> I<N2> B<or> -- I<N>
387
388 I<N> B<not> -- I<N>
389
390 =back
391
392 =item log(n), exp(n)
393
394 Natural logarithm and exponential.
395
396 rpnexpr usage:
397
398 =over
399
400 I<N> B<log> -- I<N>
401
402 I<N> B<exp> -- I<N>
403
404 =back
405
406 =item det(a, b, c, d)
407
408 Calculate the determinant of the 2 x 2 matrix;
409
410   a b
411   c d
412
413 rpnexpr usage:
414
415 =over
416
417 I<Na> I<Nb> I<Nc> I<Nd> B<det> -- I<N>
418
419 =back
420
421 =back
422
423 =head3 Constants
424
425 transform2() defines the following constants:
426
427 =over
428
429 =item pi
430
431 The classical constant.
432
433 =item w
434
435 =item h
436
437 The width and height of the output image.
438
439 =item cx
440
441 =item cy
442
443 The center of the output image.
444
445 =item wI<image number>
446
447 =item hI<image number>
448
449 The width and height of each of the input images, C<w1> is the width
450 of the first input image and so on.
451
452 =item cxI<image number>
453
454 =item cyI<image number>
455
456 The center of each of the input images, (C<cx1>, C<cy1>) is the center
457 of the first input image and so on.
458
459 =back
460
461 A few examples:
462
463 =over
464
465 =item rpnexpr=>'x 25 % 15 * y 35 % 10 * getp1 !pat x y getp1 !pix @pix sat 0.7 gt @pat @pix ifp'
466
467 tiles a smaller version of the input image over itself where the
468 colour has a saturation over 0.7.
469
470 =item rpnexpr=>'x 25 % 15 * y 35 % 10 * getp1 !pat y 360 / !rat x y getp1 1 @rat - pmult @pat @rat pmult padd'
471
472 tiles the input image over itself so that at the top of the image the
473 full-size image is at full strength and at the bottom the tiling is
474 most visible.
475
476 =item rpnexpr=>'x y getp1 !pix @pix value 0.96 gt @pix sat 0.1 lt and 128 128 255 rgb @pix ifp'
477
478 replace pixels that are white or almost white with a palish blue
479
480 =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'
481
482 Tiles the input image overitself where the image isn't white or almost
483 white.
484
485 =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'
486
487 Produces a spiral.
488
489 =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'
490
491 A spiral built on top of a colour wheel.
492
493 =back
494
495 For details on expression parsing see L<Imager::Expr>.  For details on
496 the virtual machine used to transform the images, see
497 L<Imager::regmach.pod>.
498
499   # generate a colorful spiral
500   # requires that Parse::RecDescent be installed
501   my $newimg = Imager::transform2({
502                                    width => 160, height=>160,
503                                    expr => <<EOS
504   dist = distance(x, y, w/2, h/2);
505   angle = atan2(y-h/2, x-w/2);
506   angle2 = (dist / 10 + angle) % ( 2 * pi );
507   return hsv(angle*180/pi, 1, (sin(angle2)+1)/2);
508   EOS
509                                   });
510
511   # replace green portions of an image with another image
512   my $newimg = Imager::transform2({
513                                    rpnexpr => <<EOS
514   x y getp2 !pat # used to replace green portions
515   x y getp1 !pix # source with "green screen"
516   @pix red 10 lt @pix blue 10 lt && # low blue and red
517   @pix green 254 gt && # and high green
518   @pat @pix ifp
519   EOS
520                                   }, $source, $background);
521
522 =head2 Matrix Transformations
523
524 =over
525
526 =item matrix_transform
527
528 Rather than having to write code in a little language, you can use a
529 matrix to perform affine transformations, using the matrix_transform()
530 method:
531
532   my $newimg = $img->matrix_transform(matrix=>[ -1, 0, $img->getwidth-1,
533                                             0,  1, 0,
534                                             0,  0, 1 ]);
535
536 By default the output image will be the same size as the input image,
537 but you can supply the xsize and ysize parameters to change the size.
538
539 Rather than building matrices by hand you can use the Imager::Matrix2d
540 module to build the matrices.  This class has methods to allow you to
541 scale, shear, rotate, translate and reflect, and you can combine these
542 with an overloaded multiplication operator.
543
544 WARNING: the matrix you provide in the matrix operator transforms the
545 co-ordinates within the B<destination> image to the co-ordinates
546 within the I<source> image.  This can be confusing.
547
548 You can also supply a C<back> argument which acts as a background
549 color for the areas of the image with no samples available (outside
550 the rectangle of the source image.)  This can be either an
551 Imager::Color or Imager::Color::Float object.  This is B<not> mixed
552 transparent pixels in the middle of the source image, it is B<only>
553 used for pixels where there is no corresponding pixel in the source
554 image.
555
556 =back
557
558 =cut