17914006868d605a24053e4acfe691ccb0467399
[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 =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.  % is implemented
154 using fmod() so you can use this to take a value mod a floating point
155 value.
156
157 =item sin(N), cos(N), atan2(y,x)
158
159 Some basic trig functions.  They work in radians, so you can't just
160 use the hue values.
161
162 =item distance(x1, y1, x2, y2)
163
164 Find the distance between two points.  This is handy (along with
165 atan2()) for producing circular effects.
166
167 =item sqrt(n)
168
169 Find the square root.  I haven't had much use for this since adding
170 the distance() function.
171
172 =item abs(n)
173
174 Find the absolute value.
175
176 =item getp1(x,y), getp2(x,y), getp3(x, y)
177
178 Get the pixel at position (x,y) from the first, second or third image
179 respectively.  I may add a getpn() function at some point, but this
180 prevents static checking of the instructions against the number of
181 images actually passed in.
182
183 =item value(c), hue(c), sat(c), hsv(h,s,v)
184
185 Separates a colour value into it's value (brightness), hue (colour)
186 and saturation elements.  Use hsv() to put them back together (after
187 suitable manipulation).
188
189 =item red(c), green(c), blue(c), rgb(r,g,b)
190
191 Separates a colour value into it's red, green and blue colours.  Use
192 rgb(r,g,b) to put it back together.
193
194 =item int(n)
195
196 Convert a value to an integer.  Uses a C int cast, so it may break on
197 large values.
198
199 =item if(cond,ntrue,nfalse), if(cond,ctrue,cfalse)
200
201 A simple (and inefficient) if function.
202
203 =item <=,<,==,>=,>,!=
204
205 Relational operators (typically used with if()).  Since we're working
206 with floating point values the equalities are 'near equalities' - an
207 epsilon value is used.
208
209 =item &&, ||, not(n)
210
211 Basic logical operators.
212
213 =back
214
215 A few examples:
216
217 =over
218
219 =item rpnexpr=>'x 25 % 15 * y 35 % 10 * getp1 !pat x y getp1 !pix @pix sat 0.7 gt @pat @pix ifp'
220
221 tiles a smaller version of the input image over itself where the
222 colour has a saturation over 0.7.
223
224 =item rpnexpr=>'x 25 % 15 * y 35 % 10 * getp1 !pat y 360 / !rat x y getp1 1 @rat - pmult @pat @rat pmult padd'
225
226 tiles the input image over itself so that at the top of the image the
227 full-size image is at full strength and at the bottom the tiling is
228 most visible.
229
230 =item rpnexpr=>'x y getp1 !pix @pix value 0.96 gt @pix sat 0.1 lt and 128 128 255 rgb @pix ifp'
231
232 replace pixels that are white or almost white with a palish blue
233
234 =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'
235
236 Tiles the input image overitself where the image isn't white or almost
237 white.
238
239 =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'
240
241 Produces a spiral.
242
243 =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'
244
245 A spiral built on top of a colour wheel.
246
247 =back
248
249 For details on expression parsing see L<Imager::Expr>.  For details on
250 the virtual machine used to transform the images, see
251 L<Imager::regmach.pod>.
252
253   # generate a colorful spiral
254   # requires that Parse::RecDescent be installed
255   my $newimg = Imager::transform2({
256                                    width => 160, height=>160,
257                                    expr => <<EOS
258   dist = distance(x, y, w/2, h/2);
259   angle = atan2(y-h/2, x-w/2);
260   angle2 = (dist / 10 + angle) % ( 2 * pi );
261   return hsv(angle*180/pi, 1, (sin(angle2)+1)/2);
262   EOS
263                                   });
264
265 =head2 Matrix Transformations
266
267 Rather than having to write code in a little language, you can use a
268 matrix to perform affine transformations, using the matrix_transform()
269 method:
270
271   my $newimg = $img->matrix_transform(matrix=>[ -1, 0, $img->getwidth-1,
272                                             0,  1, 0,
273                                             0,  0, 1 ]);
274
275 By default the output image will be the same size as the input image,
276 but you can supply the xsize and ysize parameters to change the size.
277
278 Rather than building matrices by hand you can use the Imager::Matrix2d
279 module to build the matrices.  This class has methods to allow you to
280 scale, shear, rotate, translate and reflect, and you can combine these
281 with an overloaded multiplication operator.
282
283 WARNING: the matrix you provide in the matrix operator transforms the
284 co-ordinates within the B<destination> image to the co-ordinates
285 within the I<source> image.  This can be confusing.
286
287 Since Imager has 3 different fairly general ways of transforming an
288 image spatially, this method also has a yatf() alias.  Yet Another
289 Transformation Function.
290
291 =cut