- added comment support the postfix transform2() expression
[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
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 =item *
95
96 channels - the number of channels in the output image.  If this isn't
97 supplied a 3 channel image will be created.
98
99 =back
100
101 The tranformation function is specified using either the expr or
102 rpnexpr member of the options.
103
104 =over
105
106 =item Infix expressions
107
108 You can supply infix expressions to transform 2 with the expr keyword.
109
110 $opts{expr} = 'return getp1(w-x, h-y)'
111
112 The 'expression' supplied follows this general grammar:
113
114    ( identifier '=' expr ';' )* 'return' expr
115
116 This allows you to simplify your expressions using variables.
117
118 A more complex example might be:
119
120 $opts{expr} = 'pix = getp1(x,y); return if(value(pix)>0.8,pix*0.8,pix)'
121
122 Currently to use infix expressions you must have the Parse::RecDescent
123 module installed (available from CPAN).  There is also what might be a
124 significant delay the first time you run the infix expression parser
125 due to the compilation of the expression grammar.
126
127 =item Postfix expressions
128
129 You can supply postfix or reverse-polish notation expressions to
130 transform2() through the rpnexpr keyword.
131
132 The parser for rpnexpr emulates a stack machine, so operators will
133 expect to see their parameters on top of the stack.  A stack machine
134 isn't actually used during the image transformation itself.
135
136 You can store the value at the top of the stack in a variable called
137 foo using !foo and retrieve that value again using @foo.  The !foo
138 notation will pop the value from the stack.
139
140 An example equivalent to the infix expression above:
141
142  $opts{rpnexpr} = 'x y getp1 !pix @pix value 0.8 gt @pix 0.8 * @pix ifp'
143
144 =back
145
146 transform2() has a fairly rich range of operators.
147
148 =over
149
150 =item +, *, -, /, %, **
151
152 multiplication, addition, subtraction, division, remainder and
153 exponentiation.  Multiplication, addition and subtraction can be used
154 on colour values too - though you need to be careful - adding 2 white
155 values together and multiplying by 0.5 will give you grey, not white.
156
157 Division by zero (or a small number) just results in a large number.
158 Modulo zero (or a small number) results in zero.  % is implemented
159 using fmod() so you can use this to take a value mod a floating point
160 value.
161
162 =item sin(N), cos(N), atan2(y,x)
163
164 Some basic trig functions.  They work in radians, so you can't just
165 use the hue values.
166
167 =item distance(x1, y1, x2, y2)
168
169 Find the distance between two points.  This is handy (along with
170 atan2()) for producing circular effects.
171
172 =item sqrt(n)
173
174 Find the square root.  I haven't had much use for this since adding
175 the distance() function.
176
177 =item abs(n)
178
179 Find the absolute value.
180
181 =item getp1(x,y), getp2(x,y), getp3(x, y)
182
183 Get the pixel at position (x,y) from the first, second or third image
184 respectively.  I may add a getpn() function at some point, but this
185 prevents static checking of the instructions against the number of
186 images actually passed in.
187
188 =item value(c), hue(c), sat(c), hsv(h,s,v), hsva(h,s,v,alpha)
189
190 Separates a colour value into it's value (brightness), hue (colour)
191 and saturation elements.  Use hsv() to put them back together (after
192 suitable manipulation), or hsva() to include a tranparency value.
193
194 =item red(c), green(c), blue(c), rgb(r,g,b)
195
196 Separates a colour value into it's red, green and blue colours.  Use
197 rgb(r,g,b) to put it back together, or rgba() to include a
198 transparency value.
199
200 =item alpha(c)
201
202 Retrieve the alpha value from a colour.
203
204 =item int(n)
205
206 Convert a value to an integer.  Uses a C int cast, so it may break on
207 large values.
208
209 =item if(cond,ntrue,nfalse), if(cond,ctrue,cfalse)
210
211 A simple (and inefficient) if function.
212
213 =item <=,<,==,>=,>,!=
214
215 Relational operators (typically used with if()).  Since we're working
216 with floating point values the equalities are 'near equalities' - an
217 epsilon value is used.
218
219 =item &&, ||, not(n)
220
221 Basic logical operators.
222
223 =back
224
225 A few examples:
226
227 =over
228
229 =item rpnexpr=>'x 25 % 15 * y 35 % 10 * getp1 !pat x y getp1 !pix @pix sat 0.7 gt @pat @pix ifp'
230
231 tiles a smaller version of the input image over itself where the
232 colour has a saturation over 0.7.
233
234 =item rpnexpr=>'x 25 % 15 * y 35 % 10 * getp1 !pat y 360 / !rat x y getp1 1 @rat - pmult @pat @rat pmult padd'
235
236 tiles the input image over itself so that at the top of the image the
237 full-size image is at full strength and at the bottom the tiling is
238 most visible.
239
240 =item rpnexpr=>'x y getp1 !pix @pix value 0.96 gt @pix sat 0.1 lt and 128 128 255 rgb @pix ifp'
241
242 replace pixels that are white or almost white with a palish blue
243
244 =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'
245
246 Tiles the input image overitself where the image isn't white or almost
247 white.
248
249 =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'
250
251 Produces a spiral.
252
253 =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'
254
255 A spiral built on top of a colour wheel.
256
257 =back
258
259 For details on expression parsing see L<Imager::Expr>.  For details on
260 the virtual machine used to transform the images, see
261 L<Imager::regmach.pod>.
262
263   # generate a colorful spiral
264   # requires that Parse::RecDescent be installed
265   my $newimg = Imager::transform2({
266                                    width => 160, height=>160,
267                                    expr => <<EOS
268   dist = distance(x, y, w/2, h/2);
269   angle = atan2(y-h/2, x-w/2);
270   angle2 = (dist / 10 + angle) % ( 2 * pi );
271   return hsv(angle*180/pi, 1, (sin(angle2)+1)/2);
272   EOS
273                                   });
274
275   # replace green portions of an image with another image
276   my $newimg = Imager::transform2({
277                                    rpnexpr => <<EOS
278   x y getp2 !pat # used to replace green portions
279   x y getp1 !pix # source with "green screen"
280   @pix red 10 lt @pix blue 10 lt && # low blue and red
281   @pix green 254 gt && # and high green
282   @pat @pix ifp
283   EOS
284                                   }, $source, $background);
285
286 =head2 Matrix Transformations
287
288 Rather than having to write code in a little language, you can use a
289 matrix to perform affine transformations, using the matrix_transform()
290 method:
291
292   my $newimg = $img->matrix_transform(matrix=>[ -1, 0, $img->getwidth-1,
293                                             0,  1, 0,
294                                             0,  0, 1 ]);
295
296 By default the output image will be the same size as the input image,
297 but you can supply the xsize and ysize parameters to change the size.
298
299 Rather than building matrices by hand you can use the Imager::Matrix2d
300 module to build the matrices.  This class has methods to allow you to
301 scale, shear, rotate, translate and reflect, and you can combine these
302 with an overloaded multiplication operator.
303
304 WARNING: the matrix you provide in the matrix operator transforms the
305 co-ordinates within the B<destination> image to the co-ordinates
306 within the I<source> image.  This can be confusing.
307
308 Since Imager has 3 different fairly general ways of transforming an
309 image spatially, this method also has a yatf() alias.  Yet Another
310 Transformation Function.
311
312 =cut