summaryrefslogtreecommitdiff
path: root/Master/tlpkg/tlperl.straw/lib/Imager/Engines.pod
blob: 42784712e67c60ff0796a9757fac0db09a02dd2b (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
=head1 NAME

Imager::Engines - Programmable transformation operations

=head1 SYNOPSIS

  use Imager;

  my %opts;
  my @imgs;
  my $img;
  ...

  my $newimg = $img->transform(
      xexpr=>'x',
      yexpr=>'y+10*sin((x+y)/10)')
    or die $img->errstr;

  my $newimg = Imager::transform2(\%opts, @imgs)
    or die "transform2 failed: $Imager::ERRSTR";

  my $newimg = $img->matrix_transform(
     matrix=>[ -1, 0, $img->getwidth-1,
                0,  1, 0,
                0,  0, 1 ]);


=head1 DESCRIPTION

=head2 transform

The C<transform()> function can be used to generate spatial warps and
rotations and such effects.  It only operates on a single image and
its only function is to displace pixels.

It can be given the operations in postfix notation or the module
Affix::Infix2Postfix can be used to generate postfix code from infix
code.  Look in the test case t/t55trans.t for an example.

C<transform()> needs expressions (or opcodes) that determine the
source pixel for each target pixel.  Source expressions are infix
expressions using any of the +, -, *, / or ** binary operators, the -
unary operator, ( and ) for grouping and the sin() and cos()
functions.  The target pixel is input as the variables x and y.

You specify the x and y expressions as xexpr and yexpr respectively.
You can also specify opcodes directly, but that's magic deep enough
that you can look at the source code.

Note: You can still use the transform() function, but the transform2()
function is just as fast and is more likely to be enhanced and
maintained.

  $new_img=$img->transform(xexpr=>'x',yexpr=>'y+10*sin((x+y)/10)')

  $new_img=$img->transform(xexpr=>'x+0.1*y+5*sin(y/10.0+1.57)',
                           yexpr=>'y+10*sin((x+y-0.785)/10)') 

=head2 transform2

Imager also supports a C<transform2()> class method which allows you
perform a more general set of operations, rather than just specifying
a spatial transformation as with the transform() method, you can also
perform colour transformations, image synthesis and image
combinations from multiple source images.

C<transform2()> takes an reference to an options hash, and a list of
images to operate one (this list may be empty):

  my %opts;
  my @imgs;
  ...
  my $img = Imager::transform2(\%opts, @imgs)
      or die "transform2 failed: $Imager::ERRSTR";

The options hash may define a transformation function, and optionally:

=over

=item *

width - the width of the image in pixels.  If this isn't supplied the
width of the first input image is used.  If there are no input images
an error occurs.

=item *

height - the height of the image in pixels.  If this isn't supplied
the height of the first input image is used.  If there are no input
images an error occurs.

=item *

constants - a reference to hash of constants to define for the
expression engine.  Some extra constants are defined by Imager

=item *

channels - the number of channels in the output image.  If this isn't
supplied a 3 channel image will be created.

=back

The tranformation function is specified using either the expr or
rpnexpr member of the options.

=head3 Infix expressions

You can supply infix expressions to transform 2 with the expr keyword.

  $opts{expr} = 'return getp1(w-x, h-y)'

The 'expression' supplied follows this general grammar:

   ( identifier '=' expr ';' )* 'return' expr

This allows you to simplify your expressions using variables.

A more complex example might be:

  $opts{expr} = 'pix = getp1(x,y); return if(value(pix)>0.8,pix*0.8,pix)'

Currently to use infix expressions you must have the L<Parse::RecDescent>
module installed (available from CPAN).  There is also what might be a
significant delay the first time you run the infix expression parser
due to the compilation of the expression grammar.

=head3 Postfix expressions

You can supply postfix or reverse-polish notation expressions to
transform2() through the rpnexpr keyword.

The parser for rpnexpr emulates a stack machine, so operators will
expect to see their parameters on top of the stack.  A stack machine
isn't actually used during the image transformation itself.

You can store the value at the top of the stack in a variable called
foo using !foo and retrieve that value again using @foo.  The !foo
notation will pop the value from the stack.

An example equivalent to the infix expression above:

 $opts{rpnexpr} = 'x y getp1 !pix @pix value 0.8 gt @pix 0.8 * @pix ifp'

At the end of the expression there should be a single pixel value left
on the stack, which is used as the output pixel.

=head3 Operators

transform2() has a fairly rich range of operators.

Each entry below includes the usage with rpnexpr, formatted as:

=over

I<operand> I<operand> ... B<I<operator>> -- I<result>

=back

If the operand or result begins with "N" it is a numeric value, if it
begins with "C" it is a color or pixel value.

=over

=item +, *, -, /, %, **

multiplication, addition, subtraction, division, remainder and
exponentiation.  Multiplication, addition and subtraction can be used
on colour values too - though you need to be careful - adding 2 white
values together and multiplying by 0.5 will give you grey, not white.

Division by zero (or a small number) just results in a large number.
Modulo zero (or a small number) results in zero.  % is implemented
using fmod() so you can use this to take a value mod a floating point
value.

rpnexpr usage:

=over

I<N1> I<N2> B<+> -- I<N>

I<N1> I<N2> B<*> -- I<N>

I<N1> I<N2> B<-> -- I<N>

I<N1> I<N2> B</> -- I<N>

I<N1> I<N2> B<**> -- I<N>

I<N1> B<uminus> -- I<N>

=back

=item sin(N), cos(N), atan2(y,x)

Some basic trig functions.  They work in radians, so you can't just
use the hue values.

rpnexpr usage:

=over

I<N> B<sin> -- I<N>

I<N> B<cos> -- I<N>

I<Ny> I<Nx> B<atan2> -- I<N>

=back

=item distance(x1, y1, x2, y2)

Find the distance between two points.  This is handy (along with
atan2()) for producing circular effects.

rpnexpr usage:

=over

I<Nx1> I<Ny1> I<Nx2> I<Ny2> B<distance> -- I<N>

=back

=item sqrt(n)

Find the square root.  I haven't had much use for this since adding
the distance() function.

rpnexpr usage:

=over

I<N> B<sqrt> -- I<N>

=back

=item abs(n)

Find the absolute value.

rpnexpr usage:

=over

I<N> B<abs> -- I<N>

=back

=item getp1(x,y), getp2(x,y), getp3(x, y)

Get the pixel at position (x,y) from the first, second or third image
respectively.  I may add a getpn() function at some point, but this
prevents static checking of the instructions against the number of
images actually passed in.

rpnexpr usage:

=over

I<Nx> I<Ny> B<getp1> -- I<C>

I<Nx> I<Ny> B<getp2> -- I<C>

I<Nx> I<Ny> B<getp3> -- I<C>

=back

=item value(c), hue(c), sat(c), hsv(h,s,v), hsva(h,s,v,alpha)

Separates a colour value into it's value (brightness), hue (colour)
and saturation elements.  Use hsv() to put them back together (after
suitable manipulation), or hsva() to include a tranparency value.

rpnexpr usage:

=over

I<C> B<value> -- I<N>

I<C> B<hue> -- I<N>

I<C> B<sat> -- I<N>

I<Nh> I<Ns> I<Nv> B<hsv> -- I<C>

I<Nh> I<Ns> I<Nv> I<Na> B<hsva> -- I<C>

=back

=item red(c), green(c), blue(c), rgb(r,g,b), rgba(r,g,b,a)

Separates a colour value into it's red, green and blue colours.  Use
rgb(r,g,b) to put it back together, or rgba() to include a
transparency value.

rpnexpr usage:

=over

I<C> B<red> -- I<N>

I<C> B<green> -- I<N>

I<C> B<blue> -- I<N>

I<Nr> I<Ng> I<Nb> B<rgb> -- I<C>

I<Nr> I<Ng> I<Nb> I<Na> B<rgba> -- I<C>

=back

=item alpha(c)

Retrieve the alpha value from a colour.

rpnexpr usage:

=over

I<C> B<alpha> -- I<N>

=back

=item int(n)

Convert a value to an integer.  Uses a C int cast, so it may break on
large values.

rpnexpr usage:

=over

I<N> B<int> -- I<N>

=back

=item if(cond,ntrue,nfalse), if(cond,ctrue,cfalse)

A simple (and inefficient) if function.

rpnexpr usage:

=over

I<Ncond> I<N-true-result> I<N-false-result> B<if> -- I<N>

I<Ncond> I<C-true-result> I<C-false-result> B<if> -- I<C>

I<Ncond> I<C-true-result> I<C-false-result> B<ifp> -- I<C>

=back

=item <=,<,==,>=,>,!=

Relational operators (typically used with if()).  Since we're working
with floating point values the equalities are 'near equalities' - an
epsilon value is used.

=over

I<N1> I<N2> B<< <= >> -- I<N>

I<N1> I<N2> B<< < >> -- I<N>

I<N1> I<N2> B<< >= >> -- I<N>

I<N1> I<N2> B<< > >> -- I<N>

I<N1> I<N2> B<< == >> -- I<N>

I<N1> I<N2> B<< != >> -- I<N>

=back

=item &&, ||, not(n)

Basic logical operators.

rpnexpr usage:

=over

I<N1> I<N2> B<and> -- I<N>

I<N1> I<N2> B<or> -- I<N>

I<N> B<not> -- I<N>

=back

=item log(n), exp(n)

Natural logarithm and exponential.

rpnexpr usage:

=over

I<N> B<log> -- I<N>

I<N> B<exp> -- I<N>

=back

=item det(a, b, c, d)

Calculate the determinant of the 2 x 2 matrix;

  a b
  c d

rpnexpr usage:

=over

I<Na> I<Nb> I<Nc> I<Nd> B<det> -- I<N>

=back

=back

=head3 Constants

transform2() defines the following constants:

=over

=item pi

The classical constant.

=item w

=item h

The width and height of the output image.

=item cx

=item cy

The center of the output image.

=item wI<image number>

=item hI<image number>

The width and height of each of the input images, C<w1> is the width
of the first input image and so on.

=item cxI<image number>

=item cyI<image number>

The center of each of the input images, (C<cx1>, C<cy1>) is the center
of the first input image and so on.

=back

A few examples:

=over

=item rpnexpr=>'x 25 % 15 * y 35 % 10 * getp1 !pat x y getp1 !pix @pix sat 0.7 gt @pat @pix ifp'

tiles a smaller version of the input image over itself where the
colour has a saturation over 0.7.

=item rpnexpr=>'x 25 % 15 * y 35 % 10 * getp1 !pat y 360 / !rat x y getp1 1 @rat - pmult @pat @rat pmult padd'

tiles the input image over itself so that at the top of the image the
full-size image is at full strength and at the bottom the tiling is
most visible.

=item rpnexpr=>'x y getp1 !pix @pix value 0.96 gt @pix sat 0.1 lt and 128 128 255 rgb @pix ifp'

replace pixels that are white or almost white with a palish blue

=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'

Tiles the input image overitself where the image isn't white or almost
white.

=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'

Produces a spiral.

=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'

A spiral built on top of a colour wheel.

=back

For details on expression parsing see L<Imager::Expr>.  For details on
the virtual machine used to transform the images, see
L<Imager::regmach.pod>.

  # generate a colorful spiral
  # requires that Parse::RecDescent be installed
  my $newimg = Imager::transform2({
                                   width => 160, height=>160,
                                   expr => <<EOS
  dist = distance(x, y, w/2, h/2);
  angle = atan2(y-h/2, x-w/2);
  angle2 = (dist / 10 + angle) % ( 2 * pi );
  return hsv(angle*180/pi, 1, (sin(angle2)+1)/2);
  EOS
                                  });

  # replace green portions of an image with another image
  my $newimg = Imager::transform2({
                                   rpnexpr => <<EOS
  x y getp2 !pat # used to replace green portions
  x y getp1 !pix # source with "green screen"
  @pix red 10 lt @pix blue 10 lt && # low blue and red
  @pix green 254 gt && # and high green
  @pat @pix ifp
  EOS
                                  }, $source, $background);

=head2 Matrix Transformations

=over

=item matrix_transform

Rather than having to write code in a little language, you can use a
matrix to perform affine transformations, using the matrix_transform()
method:

  my $newimg = $img->matrix_transform(matrix=>[ -1, 0, $img->getwidth-1,
                                            0,  1, 0,
                                            0,  0, 1 ]);

By default the output image will be the same size as the input image,
but you can supply the xsize and ysize parameters to change the size.

Rather than building matrices by hand you can use the Imager::Matrix2d
module to build the matrices.  This class has methods to allow you to
scale, shear, rotate, translate and reflect, and you can combine these
with an overloaded multiplication operator.

WARNING: the matrix you provide in the matrix operator transforms the
co-ordinates within the B<destination> image to the co-ordinates
within the I<source> image.  This can be confusing.

You can also supply a C<back> argument which acts as a background
color for the areas of the image with no samples available (outside
the rectangle of the source image.)  This can be either an
Imager::Color or Imager::Color::Float object.  This is B<not> mixed
transparent pixels in the middle of the source image, it is B<only>
used for pixels where there is no corresponding pixel in the source
image.

=back

=cut