=head1 DESCRIPTION
-=head2 transform
+=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
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()
+unary operator, ( and ) for grouping and the C<sin()> and C<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 specify the x and y expressions as C<xexpr> and C<yexpr> respectively.
You can also specify opcodes directly, but that's magic deep enough
that you can look at the source code.
$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
+=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
+perform color transformations, image synthesis and image
combinations from multiple source images.
C<transform2()> takes an reference to an options hash, and a list of
=back
-The tranformation function is specified using either the expr or
-rpnexpr member of the options.
+The transformation function is specified using either the C<expr> or
+C<rpnexpr> member of the options.
=head3 Infix expressions
-You can supply infix expressions to transform 2 with the expr keyword.
+You can supply infix expressions to transform 2 with the C<expr> keyword.
$opts{expr} = 'return getp1(w-x, h-y)'
=head3 Postfix expressions
You can supply postfix or reverse-polish notation expressions to
-transform2() through the rpnexpr keyword.
+transform2() through the C<rpnexpr> keyword.
-The parser for rpnexpr emulates a stack machine, so operators will
+The parser for C<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
+C<foo> using C<!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:
transform2() has a fairly rich range of operators.
-Each entry below includes the usage with rpnexpr, formatted as:
+Each entry below includes the usage with C<rpnexpr>, formatted as:
=over
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.
+on color values too - though you need to be careful - adding 2 white
+values together and multiplying by 0.5 will give you gray, 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:
+=for stopwords N1 N2 N uminus
+
+C<rpnexpr> usage:
=over
Some basic trig functions. They work in radians, so you can't just
use the hue values.
-rpnexpr usage:
+=for stopwords Ny Nx atan2
+
+C<rpnexpr> usage:
=over
Find the distance between two points. This is handy (along with
atan2()) for producing circular effects.
-rpnexpr usage:
+=for stopwords Nx1 Ny1 Nx2 Ny2
+
+C<rpnexpr> usage:
=over
Find the square root. I haven't had much use for this since adding
the distance() function.
-rpnexpr usage:
+C<rpnexpr> usage:
=over
Find the absolute value.
-rpnexpr usage:
+C<rpnexpr> usage:
=over
prevents static checking of the instructions against the number of
images actually passed in.
-rpnexpr usage:
+=for stopwords getp1 getp2 getp3
+
+C<rpnexpr> usage:
=over
=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)
+Separates a color value into it's value (brightness), hue (color)
and saturation elements. Use hsv() to put them back together (after
-suitable manipulation), or hsva() to include a tranparency value.
+suitable manipulation), or hsva() to include a transparency value.
+
+=for stopwords Nh Ns Nv hsv hsva Nr Ng Nb rgb rgba
-rpnexpr usage:
+C<rpnexpr> usage:
=over
=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
+Separates a color value into it's red, green and blue colors. Use
rgb(r,g,b) to put it back together, or rgba() to include a
transparency value.
-rpnexpr usage:
+C<rpnexpr> usage:
=over
=item alpha(c)
-Retrieve the alpha value from a colour.
+Retrieve the alpha value from a color.
-rpnexpr usage:
+C<rpnexpr> usage:
=over
Convert a value to an integer. Uses a C int cast, so it may break on
large values.
-rpnexpr usage:
+C<rpnexpr> usage:
=over
A simple (and inefficient) if function.
-rpnexpr usage:
+=for stopwords Ncond ifp
+
+C<rpnexpr> usage:
=over
Basic logical operators.
-rpnexpr usage:
+C<rpnexpr> usage:
=over
Natural logarithm and exponential.
-rpnexpr usage:
+C<rpnexpr> usage:
=over
a b
c d
-rpnexpr usage:
+=for stopwords Na Nv Nc Nd det
+
+C<rpnexpr> usage:
=over
=over
-=item pi
+=item C<pi>
The classical constant.
-=item w
+=item C<w>
-=item h
+=item C<h>
The width and height of the output image.
-=item cx
+=item C<cx>
-=item cy
+=item C<cy>
The center of the output image.
-=item wI<image number>
+=item C<w>I<image number>
-=item hI<image number>
+=item C<h>I<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 C<cx>I<image number>
-=item cyI<image number>
+=item C<cy>I<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.
=over
-=item rpnexpr=>'x 25 % 15 * y 35 % 10 * getp1 !pat x y getp1 !pix @pix sat 0.7 gt @pat @pix ifp'
+ 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.
+color 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'
+ 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'
+ 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'
+ 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
+Tiles the input image over it self 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'
+ 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'
+ 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.
+A spiral built on top of a color 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>.
+L<Imager::regmach>.
# generate a colorful spiral
# requires that Parse::RecDescent be installed
=over
-=item matrix_transform
+=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()
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.
+but you can supply the C<xsize> and C<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
=back
+=head1 AUTHOR
+
+Tony Cook <tonyc@cpan.org>, Arnar M. Hrafnkelsson
+
=cut
projects / imager.git / blobdiff