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