1Imager::Engines(3) User Contributed Perl Documentation Imager::Engines(3)
2
6 Imager::Engines - Programmable transformation operations
7
9 use Imager;
10 my %opts;
12 my @imgs;
13 my $img;
14 ...
15 my $newimg = $img->transform(
17 xexpr=>'x',
18 yexpr=>'y+10*sin((x+y)/10)')
19 or die $img->errstr;
20 my $newimg = Imager::transform2(\%opts, @imgs)
22 or die "transform2 failed: $Imager::ERRSTR";
23 my $newimg = $img->matrix_transform(
25 matrix=>[ -1, 0, $img->getwidth-1,
26 0, 1, 0,
27 0, 0, 1 ]);
28
30 transform
31 The "transform()" function can be used to generate spatial warps and
33 rotations and such effects. It only operates on a single image and its
34 only function is to displace pixels.
35 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 "transform()" needs expressions (or opcodes) that determine the source
41 pixel for each target pixel. Source expressions are infix expressions
42 using any of the +, -, *, / or ** binary operators, the - unary opera‐
43 tor, ( and ) for grouping and the sin() and cos() functions. The tar‐
44 get pixel is input as the variables x and y.
45 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 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 main‐
52 tained.
53 $new_img=$img->transform(xexpr=>'x',yexpr=>'y+10*sin((x+y)/10)')
55 $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 transform2
60 Imager also supports a "transform2()" class method which allows you
62 perform a more general set of operations, rather than just specifying a
63 spatial transformation as with the transform() method, you can also
64 perform colour transformations, image synthesis and image combinations
65 from multiple source images.
66 "transform2()" takes an reference to an options hash, and a list of
68 images to operate one (this list may be empty):
69 my %opts;
71 my @imgs;
72 ...
73 my $img = Imager::transform2(\%opts, @imgs)
74 or die "transform2 failed: $Imager::ERRSTR";
75 The options hash may define a transformation function, and optionally:
77 · width - the width of the image in pixels. If this isn't supplied
79 the width of the first input image is used. If there are no input
80 images an error occurs.
81 · height - the height of the image in pixels. If this isn't supplied
83 the height of the first input image is used. If there are no input
84 images an error occurs.
85 · constants - a reference to hash of constants to define for the
87 expression engine. Some extra constants are defined by Imager
88 · channels - the number of channels in the output image. If this
90 isn't supplied a 3 channel image will be created.
91 The tranformation function is specified using either the expr or rpn‐
93 expr member of the options.
94 Infix expressions
96 You can supply infix expressions to transform 2 with the expr keyword.
98 $opts{expr} = 'return getp1(w-x, h-y)'
100 The 'expression' supplied follows this general grammar:
102 ( identifier '=' expr ';' )* 'return' expr
104 This allows you to simplify your expressions using variables.
106 A more complex example might be:
108 $opts{expr} = 'pix = getp1(x,y); return if(value(pix)>0.8,pix*0.8,pix)'
110 Currently to use infix expressions you must have the Parse::RecDescent
112 module installed (available from CPAN). There is also what might be a
113 significant delay the first time you run the infix expression parser
114 due to the compilation of the expression grammar.
115 Postfix expressions
117 You can supply postfix or reverse-polish notation expressions to trans‐
119 form2() through the rpnexpr keyword.
120 The parser for rpnexpr emulates a stack machine, so operators will
122 expect to see their parameters on top of the stack. A stack machine
123 isn't actually used during the image transformation itself.
124 You can store the value at the top of the stack in a variable called
126 foo using !foo and retrieve that value again using @foo. The !foo
127 notation will pop the value from the stack.
128 An example equivalent to the infix expression above:
130 $opts{rpnexpr} = 'x y getp1 !pix @pix value 0.8 gt @pix 0.8 * @pix ifp'
132 At the end of the expression there should be a single pixel value left
134 on the stack, which is used as the output pixel.
135 Operators
137 transform2() has a fairly rich range of operators.
139 Each entry below includes the usage with rpnexpr, formatted as:
141 operand operand ... operator -- result
143 If the operand or result begins with "N" it is a numeric value, if it
145 begins with "C" it is a color or pixel value.
146 +, *, -, /, %, **
148 multiplication, addition, subtraction, division, remainder and
149 exponentiation. Multiplication, addition and subtraction can be
150 used on colour values too - though you need to be careful - adding
151 2 white values together and multiplying by 0.5 will give you grey,
152 not white.
153 Division by zero (or a small number) just results in a large num‐
155 ber. Modulo zero (or a small number) results in zero. % is imple‐
156 mented using fmod() so you can use this to take a value mod a
157 floating point value.
158 rpnexpr usage:
160 N1 N2 + -- N
162 N1 N2 * -- N
164 N1 N2 - -- N
166 N1 N2 / -- N
168 N1 N2 ** -- N
170 N1 uminus -- N
172 sin(N), cos(N), atan2(y,x)
174 Some basic trig functions. They work in radians, so you can't just
175 use the hue values.
176 rpnexpr usage:
178 N sin -- N
180 N cos -- N
182 Ny Nx atan2 -- N
184 distance(x1, y1, x2, y2)
186 Find the distance between two points. This is handy (along with
187 atan2()) for producing circular effects.
188 rpnexpr usage:
190 Nx1 Ny1 Nx2 Ny2 distance -- N
192 sqrt(n)
194 Find the square root. I haven't had much use for this since adding
195 the distance() function.
196 rpnexpr usage:
198 N sqrt -- N
200 abs(n)
202 Find the absolute value.
203 rpnexpr usage:
205 N abs -- N
207 getp1(x,y), getp2(x,y), getp3(x, y)
209 Get the pixel at position (x,y) from the first, second or third
210 image respectively. I may add a getpn() function at some point,
211 but this prevents static checking of the instructions against the
212 number of images actually passed in.
213 rpnexpr usage:
215 Nx Ny getp1 -- C
217 Nx Ny getp2 -- C
219 Nx Ny getp3 -- C
221 value(c), hue(c), sat(c), hsv(h,s,v), hsva(h,s,v,alpha)
223 Separates a colour value into it's value (brightness), hue (colour)
224 and saturation elements. Use hsv() to put them back together
225 (after suitable manipulation), or hsva() to include a tranparency
226 value.
227 rpnexpr usage:
229 C value -- N
231 C hue -- N
233 C sat -- N
235 Nh Ns Nv hsv -- C
237 Nh Ns Nv Na hsva -- C
239 red(c), green(c), blue(c), rgb(r,g,b), rgba(r,g,b,a)
241 Separates a colour value into it's red, green and blue colours.
242 Use rgb(r,g,b) to put it back together, or rgba() to include a
243 transparency value.
244 rpnexpr usage:
246 C red -- N
248 C green -- N
250 C blue -- N
252 Nr Ng Nb rgb -- C
254 Nr Ng Nb Na rgba -- C
256 alpha(c)
258 Retrieve the alpha value from a colour.
259 rpnexpr usage:
261 C alpha -- N
263 int(n)
265 Convert a value to an integer. Uses a C int cast, so it may break
266 on large values.
267 rpnexpr usage:
269 N int -- N
271 if(cond,ntrue,nfalse), if(cond,ctrue,cfalse)
273 A simple (and inefficient) if function.
274 rpnexpr usage:
276 Ncond N-true-result N-false-result if -- N
278 Ncond C-true-result C-false-result if -- C
280 Ncond C-true-result C-false-result ifp -- C
282 <=,<,==,>=,>,!=
284 Relational operators (typically used with if()). Since we're work‐
285 ing with floating point values the equalities are 'near equalities'
286 - an epsilon value is used.
287 N1 N2 <= -- N
289 N1 N2 < -- N
291 N1 N2 >= -- N
293 N1 N2 > -- N
295 N1 N2 == -- N
297 N1 N2 != -- N
299 &&, ⎪⎪, not(n)
301 Basic logical operators.
302 rpnexpr usage:
304 N1 N2 and -- N
306 N1 N2 or -- N
308 N not -- N
310 log(n), exp(n)
312 Natural logarithm and exponential.
313 rpnexpr usage:
315 N log -- N
317 N exp -- N
319 det(a, b, c, d)
321 Calculate the determinant of the 2 x 2 matrix;
322 a b
324 c d
325 rpnexpr usage:
327 Na Nb Nc Nd det -- N
329 Constants
331 transform2() defines the following constants:
333 pi The classical constant.
335 w
337 h The width and height of the output image.
338 cx
340 cy The center of the output image.
341 wimage number
343 himage number
344 The width and height of each of the input images, "w1" is the width
345 of the first input image and so on.
346 cximage number
348 cyimage number
349 The center of each of the input images, ("cx1", "cy1") is the cen‐
350 ter of the first input image and so on.
351 A few examples:
353 rpnexpr=>'x 25 % 15 * y 35 % 10 * getp1 !pat x y getp1 !pix @pix sat
355 0.7 gt @pat @pix ifp'
356 tiles a smaller version of the input image over itself where the
357 colour has a saturation over 0.7.
358 rpnexpr=>'x 25 % 15 * y 35 % 10 * getp1 !pat y 360 / !rat x y getp1 1
360 @rat - pmult @pat @rat pmult padd'
361 tiles the input image over itself so that at the top of the image
362 the full-size image is at full strength and at the bottom the
363 tiling is most visible.
364 rpnexpr=>'x y getp1 !pix @pix value 0.96 gt @pix sat 0.1 lt and 128 128
366 255 rgb @pix ifp'
367 replace pixels that are white or almost white with a palish blue
368 rpnexpr=>'x 35 % 10 * y 45 % 8 * getp1 !pat x y getp1 !pix @pix sat 0.2
370 lt @pix value 0.9 gt and @pix @pat @pix value 2 / 0.5 + pmult ifp'
371 Tiles the input image overitself where the image isn't white or
372 almost white.
373 rpnexpr=>'x y 160 180 distance !d y 180 - x 160 - atan2 !a @d 10 / @a +
375 3.1416 2 * % !a2 @a2 180 * 3.1416 / 1 @a2 sin 1 + 2 / hsv'
376 Produces a spiral.
377 rpnexpr=>'x y 160 180 distance !d y 180 - x 160 - atan2 !a @d 10 / @a +
379 3.1416 2 * % !a2 @a 180 * 3.1416 / 1 @a2 sin 1 + 2 / hsv'
380 A spiral built on top of a colour wheel.
381 For details on expression parsing see Imager::Expr. For details on the
383 virtual machine used to transform the images, see Imager::regmach.pod.
384 # generate a colorful spiral
386 # requires that Parse::RecDescent be installed
387 my $newimg = Imager::transform2({
388 width => 160, height=>160,
389 expr => <<EOS
390 dist = distance(x, y, w/2, h/2);
391 angle = atan2(y-h/2, x-w/2);
392 angle2 = (dist / 10 + angle) % ( 2 * pi );
393 return hsv(angle*180/pi, 1, (sin(angle2)+1)/2);
394 EOS
395 });
396 # replace green portions of an image with another image
398 my $newimg = Imager::transform2({
399 rpnexpr => <<EOS
400 x y getp2 !pat # used to replace green portions
401 x y getp1 !pix # source with "green screen"
402 @pix red 10 lt @pix blue 10 lt && # low blue and red
403 @pix green 254 gt && # and high green
404 @pat @pix ifp
405 EOS
406 }, $source, $background);
407 Matrix Transformations
409 matrix_transform
411 Rather than having to write code in a little language, you can use
412 a matrix to perform affine transformations, using the matrix_trans‐
413 form() method:
414 my $newimg = $img->matrix_transform(matrix=>[ -1, 0, $img->getwidth-1,
416 0, 1, 0,
417 0, 0, 1 ]);
418 By default the output image will be the same size as the input
420 image, but you can supply the xsize and ysize parameters to change
421 the size.
422 Rather than building matrices by hand you can use the
424 Imager::Matrix2d module to build the matrices. This class has
425 methods to allow you to scale, shear, rotate, translate and
426 reflect, and you can combine these with an overloaded multiplica‐
427 tion operator.
428 WARNING: the matrix you provide in the matrix operator transforms
430 the co-ordinates within the destination image to the co-ordinates
431 within the source image. This can be confusing.
432 You can also supply a "back" argument which acts as a background
434 color for the areas of the image with no samples available (outside
435 the rectangle of the source image.) This can be either an
436 Imager::Color or Imager::Color::Float object. This is not mixed
437 transparent pixels in the middle of the source image, it is only
438 used for pixels where there is no corresponding pixel in the source
439 image.
440perl v5.8.8 2008-03-28 Imager::Engines(3)