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
32 rotations and such effects. It only operates on a single image and its
33 only function is to displace pixels.
34 It can be given the operations in postfix notation or the module
36 Affix::Infix2Postfix can be used to generate postfix code from infix
37 code. Look in the test case t/t55trans.t for an example.
38 transform() needs expressions (or opcodes) that determine the source
40 pixel for each target pixel. Source expressions are infix expressions
41 using any of the +, -, *, / or ** binary operators, the - unary
42 operator, ( and ) for grouping and the sin() and cos() functions. The
43 target pixel is input as the variables x and y.
44 You specify the x and y expressions as "xexpr" and "yexpr"
46 respectively. You can also specify opcodes directly, but that's magic
47 deep enough that you can look at the source code.
48 Note: You can still use the transform() function, but the transform2()
50 function is just as fast and is more likely to be enhanced and
51 maintained.
52 $new_img=$img->transform(xexpr=>'x',yexpr=>'y+10*sin((x+y)/10)')
54 $new_img=$img->transform(xexpr=>'x+0.1*y+5*sin(y/10.0+1.57)',
56 yexpr=>'y+10*sin((x+y-0.785)/10)')
57 transform2()
59 Imager also supports a transform2() class method which allows you
60 perform a more general set of operations, rather than just specifying a
61 spatial transformation as with the transform() method, you can also
62 perform color transformations, image synthesis and image combinations
63 from multiple source images.
64 transform2() takes an reference to an options hash, and a list of
66 images to operate one (this list may be empty):
67 my %opts;
69 my @imgs;
70 ...
71 my $img = Imager::transform2(\%opts, @imgs)
72 or die "transform2 failed: $Imager::ERRSTR";
73 The options hash may define a transformation function, and optionally:
75 • width - the width of the image in pixels. If this isn't supplied
77 the width of the first input image is used. If there are no input
78 images an error occurs.
79 • height - the height of the image in pixels. If this isn't supplied
81 the height of the first input image is used. If there are no input
82 images an error occurs.
83 • constants - a reference to hash of constants to define for the
85 expression engine. Some extra constants are defined by Imager
86 • channels - the number of channels in the output image. If this
88 isn't supplied a 3 channel image will be created.
89 The transformation function is specified using either the "expr" or
91 "rpnexpr" member of the options.
92 Infix expressions
94 You can supply infix expressions to transform 2 with the "expr"
96 keyword.
97 $opts{expr} = 'return getp1(w-x, h-y)'
99 The 'expression' supplied follows this general grammar:
101 ( identifier '=' expr ';' )* 'return' expr
103 This allows you to simplify your expressions using variables.
105 A more complex example might be:
107 $opts{expr} = 'pix = getp1(x,y); return if(value(pix)>0.8,pix*0.8,pix)'
109 Currently to use infix expressions you must have the Parse::RecDescent
111 module installed (available from CPAN). There is also what might be a
112 significant delay the first time you run the infix expression parser
113 due to the compilation of the expression grammar.
114 Postfix expressions
116 You can supply postfix or reverse-polish notation expressions to
118 transform2() through the "rpnexpr" keyword.
119 The parser for "rpnexpr" emulates a stack machine, so operators will
121 expect to see their parameters on top of the stack. A stack machine
122 isn't actually used during the image transformation itself.
123 You can store the value at the top of the stack in a variable called
125 "foo" using "!foo" and retrieve that value again using @foo. The !foo
126 notation will pop the value from the stack.
127 An example equivalent to the infix expression above:
129 $opts{rpnexpr} = 'x y getp1 !pix @pix value 0.8 gt @pix 0.8 * @pix ifp'
131 At the end of the expression there should be a single pixel value left
133 on the stack, which is used as the output pixel.
134 Operators
136 transform2() has a fairly rich range of operators.
138 Each entry below includes the usage with "rpnexpr", formatted as:
140 operand operand ... operator -- result
142 If the operand or result begins with "N" it is a numeric value, if it
144 begins with "C" it is a color or pixel value.
145 +, *, -, /, %, **
147 multiplication, addition, subtraction, division, remainder and
148 exponentiation. Multiplication, addition and subtraction can be
149 used on color values too - though you need to be careful - adding 2
150 white values together and multiplying by 0.5 will give you gray,
151 not white.
152 Division by zero (or a small number) just results in a large
154 number. Modulo zero (or a small number) results in zero. % is
155 implemented using fmod() so you can use this to take a value mod a
156 floating point value.
157 "rpnexpr" usage:
159 N1 N2 + -- N
161 N1 N2 * -- N
163 N1 N2 - -- N
165 N1 N2 / -- N
167 N1 N2 ** -- N
169 N1 uminus -- N
171 sin(N), cos(N), atan2(y,x)
173 Some basic trig functions. They work in radians, so you can't just
174 use the hue values.
175 "rpnexpr" usage:
177 N sin -- N
179 N cos -- N
181 Ny Nx atan2 -- N
183 distance(x1, y1, x2, y2)
185 Find the distance between two points. This is handy (along with
186 atan2()) for producing circular effects.
187 "rpnexpr" usage:
189 Nx1 Ny1 Nx2 Ny2 distance -- N
191 sqrt(n)
193 Find the square root. I haven't had much use for this since adding
194 the distance() function.
195 "rpnexpr" usage:
197 N sqrt -- N
199 abs(n)
201 Find the absolute value.
202 "rpnexpr" usage:
204 N abs -- N
206 getp1(x,y), getp2(x,y), getp3(x, y)
208 Get the pixel at position (x,y) from the first, second or third
209 image respectively. I may add a getpn() function at some point,
210 but this prevents static checking of the instructions against the
211 number of images actually passed in.
212 "rpnexpr" usage:
214 Nx Ny getp1 -- C
216 Nx Ny getp2 -- C
218 Nx Ny getp3 -- C
220 value(c), hue(c), sat(c), hsv(h,s,v), hsva(h,s,v,alpha)
222 Separates a color value into it's value (brightness), hue (color)
223 and saturation elements. Use hsv() to put them back together
224 (after suitable manipulation), or hsva() to include a transparency
225 value.
226 "rpnexpr" usage:
228 C value -- N
230 C hue -- N
232 C sat -- N
234 Nh Ns Nv hsv -- C
236 Nh Ns Nv Na hsva -- C
238 red(c), green(c), blue(c), rgb(r,g,b), rgba(r,g,b,a)
240 Separates a color value into it's red, green and blue colors. Use
241 rgb(r,g,b) to put it back together, or rgba() to include a
242 transparency value.
243 "rpnexpr" usage:
245 C red -- N
247 C green -- N
249 C blue -- N
251 Nr Ng Nb rgb -- C
253 Nr Ng Nb Na rgba -- C
255 alpha(c)
257 Retrieve the alpha value from a color.
258 "rpnexpr" usage:
260 C alpha -- N
262 int(n)
264 Convert a value to an integer. Uses a C int cast, so it may break
265 on large values.
266 "rpnexpr" usage:
268 N int -- N
270 if(cond,ntrue,nfalse), if(cond,ctrue,cfalse)
272 A simple (and inefficient) if function.
273 "rpnexpr" usage:
275 Ncond N-true-result N-false-result if -- N
277 Ncond C-true-result C-false-result if -- C
279 Ncond C-true-result C-false-result ifp -- C
281 <=,<,==,>=,>,!=
283 Relational operators (typically used with if()). Since we're
284 working with floating point values the equalities are 'near
285 equalities' - an epsilon value is used.
286 N1 N2 <= -- N
288 N1 N2 < -- N
290 N1 N2 >= -- N
292 N1 N2 > -- N
294 N1 N2 == -- N
296 N1 N2 != -- N
298 &&, ||, not(n)
300 Basic logical operators.
301 "rpnexpr" usage:
303 N1 N2 and -- N
305 N1 N2 or -- N
307 N not -- N
309 log(n), exp(n)
311 Natural logarithm and exponential.
312 "rpnexpr" usage:
314 N log -- N
316 N exp -- N
318 det(a, b, c, d)
320 Calculate the determinant of the 2 x 2 matrix;
321 a b
323 c d
324 "rpnexpr" usage:
326 Na Nb Nc Nd det -- N
328 Constants
330 transform2() defines the following constants:
332 "pi"
334 The classical constant.
335 "w"
337 "h" The width and height of the output image.
338 "cx"
340 "cy"
341 The center of the output image.
342 "w"image number
344 "h"image number
345 The width and height of each of the input images, "w1" is the width
346 of the first input image and so on.
347 "cx"image number
349 "cy"image number
350 The center of each of the input images, ("cx1", "cy1") is the
351 center of the first input image and so on.
352 A few examples:
354 rpnexpr=>'x 25 % 15 * y 35 % 10 * getp1 !pat x y getp1 !pix @pix sat 0.7 gt @pat @pix ifp'
356 tiles a smaller version of the input image over itself where the
358 color has a saturation over 0.7.
359 rpnexpr=>'x 25 % 15 * y 35 % 10 * getp1 !pat y 360 / !rat x y getp1 1 @rat - pmult @pat @rat pmult padd'
361 tiles the input image over itself so that at the top of the image
363 the full-size image is at full strength and at the bottom the
364 tiling is most visible.
365 rpnexpr=>'x y getp1 !pix @pix value 0.96 gt @pix sat 0.1 lt and 128 128 255 rgb @pix ifp'
367 replace pixels that are white or almost white with a palish blue
369 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'
371 Tiles the input image over it self where the image isn't white or
373 almost white.
374 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'
376 Produces a spiral.
378 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'
380 A spiral built on top of a color wheel.
382 For details on expression parsing see Imager::Expr. For details on the
384 virtual machine used to transform the images, see Imager::regmach.
385 # generate a colorful spiral
387 # requires that Parse::RecDescent be installed
388 my $newimg = Imager::transform2({
389 width => 160, height=>160,
390 expr => <<EOS
391 dist = distance(x, y, w/2, h/2);
392 angle = atan2(y-h/2, x-w/2);
393 angle2 = (dist / 10 + angle) % ( 2 * pi );
394 return hsv(angle*180/pi, 1, (sin(angle2)+1)/2);
395 EOS
396 });
397 # replace green portions of an image with another image
399 my $newimg = Imager::transform2({
400 rpnexpr => <<EOS
401 x y getp2 !pat # used to replace green portions
402 x y getp1 !pix # source with "green screen"
403 @pix red 10 lt @pix blue 10 lt && # low blue and red
404 @pix green 254 gt && # and high green
405 @pat @pix ifp
406 EOS
407 }, $source, $background);
408 Matrix Transformations
410 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
413 matrix_transform() 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
421 change 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
427 multiplication 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.
440
442 Tony Cook <tonyc@cpan.org>, Arnar M. Hrafnkelsson
443perl v5.38.0 2023-07-20 Imager::Engines(3)