- handle UTF8 strings passed to T1 low-level functions

[imager.git] / lib / Imager / Transformations.pod

=head1 NAME

Imager::Transformations - Simple transformations of one image into another.

=head1 SYNOPSIS

  use Imager;

  $newimg = $img->copy();

  $newimg = $img->scale(xpixels=>400);
  $newimg = $img->scale(xpixels=>400, ypixels=>400);
  $newimg = $img->scale(xpixels=>400, ypixels=>400, type=>'min');
  $newimg = $img->scale(scalefactor=>0.25);

  $newimg = $img->crop(left=>50, right=>100, top=>10, bottom=>100); 
  $newimg = $img->crop(left=>50, top=>10, width=>50, height=>90);

  $dest->paste(left=>40,top=>20,img=>$logo);

  $img->rubthrough(src=>$srcimage,tx=>30,ty=>50);


  $img->flip(dir=>"h");       # horizontal flip
  $img->flip(dir=>"vh");      # vertical and horizontal flip
  $newimg = $img->copy->flip(dir=>"v"); # make a copy and flip it vertically

  my $rot20 = $img->rotate(degrees=>20);
  my $rotpi4 = $img->rotate(radians=>3.14159265/4);


  # Convert image to gray
  $new = $img->convert(preset=>'grey');          

  # Swap red/green channel  
  $new = $img->convert(matrix=>[ [ 0, 1, 0 ],
                                 [ 1, 0, 0 ],
                                 [ 0, 0, 1 ] ]);

  # limit the range of red channel from 0..255 to 0..127
  @map = map { int( $_/2 } 0..255;
  $img->map( red=>\@map );

  # Apply a Gamma of 1.4
  my $gamma = 1.4;
  my @map = map { int( 0.5 + 255*($_/255)**$gamma ) } 0..255;
  $img->map(all=>\@map);  # inplace conversion

=head1 DESCRIPTION

The methods described in Imager::Transformations fall into two categories.
Either they take an existing image and modify it in place, or they 
return a modified copy.

Functions that modify inplace are C<flip()>, C<paste()> and
C<rubthrough()>.  If the original is to be left intact it's possible
to make a copy and alter the copy:

  $flipped = $img->copy()->flip(dir=>'h');

=head2 Image copying/resizing/cropping/rotating

A list of the transformations that do not alter the source image follows:

=over

=item copy

To create a copy of an image use the C<copy()> method.  This is usefull
if you want to keep an original after doing something that changes the image.

  $newimg = $orig->copy();

=item scale

To scale an image so porportions are maintained use the
C<$img-E<gt>scale()> method.  if you give either a xpixels or ypixels
parameter they will determine the width or height respectively.  If
both are given the one resulting in a larger image is used, unless you
set the C<type> parameter to C<'min'>.  example: C<$img> is 700 pixels
wide and 500 pixels tall.

  $newimg = $img->scale(xpixels=>400); # 400x285
  $newimg = $img->scale(ypixels=>400); # 560x400

  $newimg = $img->scale(xpixels=>400,ypixels=>400); # 560x400
  $newimg = $img->scale(xpixels=>400,ypixels=>400,type=>'min'); # 400x285

  $newimg = $img->scale(scalefactor=>0.25); 175x125 
  $newimg = $img->scale(); # 350x250

if you want to create low quality previews of images you can pass
C<qtype=E<gt>'preview'> to scale and it will use nearest neighbor
sampling instead of filtering. It is much faster but also generates
worse looking images - especially if the original has a lot of sharp
variations and the scaled image is by more than 3-5 times smaller than
the original.

If you need to scale images per axis it is best to do it simply by
calling scaleX and scaleY.  You can pass either 'scalefactor' or
'pixels' to both functions.

=item crop

Another way to resize an image is to crop it.  The parameters to
crop are the edges of the area that you want in the returned image,
where the right and bottom edges are non-inclusive.  If a parameter is
omitted a default is used instead.

  # the first two produce the same image
  $newimg = $img->crop(left=>50, right=>100, top=>10, bottom=>100); 
  $newimg = $img->crop(left=>50, top=>10, width=>50, height=>90);
  $newimg = $img->crop(left=>50, right=>100); # top 

You can also specify width and height parameters which will produce a
new image cropped from the center of the input image, with the given
width and height.

  $newimg = $img->crop(width=>50, height=>50);

The width and height parameters take precedence over the left/right
and top/bottom parameters respectively.

=item rotate

Use the rotate() method to rotate an image.  This method will return a
new, rotated image.

To rotate by an exact amount in degrees or radians, use the 'degrees'
or 'radians' parameter:

  my $rot20 = $img->rotate(degrees=>20);
  my $rotpi4 = $img->rotate(radians=>3.14159265/4);

Exact image rotation uses the same underlying transformation engine as
the matrix_transform() method.

To rotate in steps of 90 degrees, use the 'right' parameter:

  my $rotated = $img->rotate(right=>270);

Rotations are clockwise for positive values.

=back


=head2 Image pasting/flipping/

A list of the transformations that alter the source image follows:

=over

=item paste


To copy an image to onto another image use the C<paste()> method.

  $dest->paste(left=>40,top=>20,img=>$logo);

That copies the entire C<$logo> image onto the C<$dest> image so that the
upper left corner of the C<$logo> image is at (40,20).


=item rubthrough

A more complicated way of blending images is where one image is
put 'over' the other with a certain amount of opaqueness.  The
method that does this is rubthrough.

  $img->rubthrough(src=>$srcimage,tx=>30,ty=>50);

That will take the image C<$srcimage> and overlay it with the upper
left corner at (30,50).  You can rub 2 or 4 channel images onto a 3
channel image, or a 2 channel image onto a 1 channel image.  The last
channel is used as an alpha channel.


=item flip

An inplace horizontal or vertical flip is possible by calling the
C<flip()> method.  If the original is to be preserved it's possible to
make a copy first.  The only parameter it takes is the C<dir>
parameter which can take the values C<h>, C<v>, C<vh> and C<hv>.

  $img->flip(dir=>"h");       # horizontal flip
  $img->flip(dir=>"vh");      # vertical and horizontal flip
  $nimg = $img->copy->flip(dir=>"v"); # make a copy and flip it vertically

=back




=head2 Color transformations

You can use the convert method to transform the color space of an
image using a matrix.  For ease of use some presets are provided.

The convert method can be used to:

=over

=item *

convert an RGB or RGBA image to grayscale.

=item *

convert a grayscale image to RGB.

=item *

extract a single channel from an image.

=item *

set a given channel to a particular value (or from another channel)

=back

The currently defined presets are:

=over

=item gray

=item grey

converts an RGBA image into a grayscale image with alpha channel, or
an RGB image into a grayscale image without an alpha channel.

This weights the RGB channels at 22.2%, 70.7% and 7.1% respectively.

=item noalpha

removes the alpha channel from a 2 or 4 channel image.  An identity
for other images.

=item red

=item channel0

extracts the first channel of the image into a single channel image

=item green

=item channel1

extracts the second channel of the image into a single channel image

=item blue

=item channel2

extracts the third channel of the image into a single channel image

=item alpha

extracts the alpha channel of the image into a single channel image.

If the image has 1 or 3 channels (assumed to be grayscale of RGB) then
the resulting image will be all white.

=item rgb

converts a grayscale image to RGB, preserving the alpha channel if any

=item addalpha

adds an alpha channel to a grayscale or RGB image.  Preserves an
existing alpha channel for a 2 or 4 channel image.

=back

For example, to convert an RGB image into a greyscale image:

  $new = $img->convert(preset=>'grey'); # or gray

or to convert a grayscale image to an RGB image:

  $new = $img->convert(preset=>'rgb');

The presets aren't necessary simple constants in the code, some are
generated based on the number of channels in the input image.

If you want to perform some other colour transformation, you can use
the 'matrix' parameter.

For each output pixel the following matrix multiplication is done:

  | channel[0] |   | $c00, ...,  $c0k |   | inchannel[0] |
  |    ...     | = |       ...        | x |     ...      |
  | channel[k] |   | $ck0, ...,  $ckk |   | inchannel[k] |
                                                          1
Where C<k = $img-E<gt>getchannels()-1>.

So if you want to swap the red and green channels on a 3 channel image:

  $new = $img->convert(matrix=>[ [ 0, 1, 0 ],
                                 [ 1, 0, 0 ],
                                 [ 0, 0, 1 ] ]);

or to convert a 3 channel image to greyscale using equal weightings:

  $new = $img->convert(matrix=>[ [ 0.333, 0.333, 0.334 ] ])


=head2 Color Mappings

You can use the map method to map the values of each channel of an
image independently using a list of lookup tables.  It's important to
realize that the modification is made inplace.  The function simply
returns the input image again or undef on failure.

Each channel is mapped independently through a lookup table with 256
entries.  The elements in the table should not be less than 0 and not
greater than 255.  If they are out of the 0..255 range they are
clamped to the range.  If a table does not contain 256 entries it is
silently ignored.

Single channels can mapped by specifying their name and the mapping
table.  The channel names are C<red>, C<green>, C<blue>, C<alpha>.

  @map = map { int( $_/2 } 0..255;
  $img->map( red=>\@map );

It is also possible to specify a single map that is applied to all
channels, alpha channel included.  For example this applies a gamma
correction with a gamma of 1.4 to the input image.

  $gamma = 1.4;
  @map = map { int( 0.5 + 255*($_/255)**$gamma ) } 0..255;
  $img->map(all=> \@map);

The C<all> map is used as a default channel, if no other map is
specified for a channel then the C<all> map is used instead.  If we
had not wanted to apply gamma to the alpha channel we would have used:

  $img->map(all=> \@map, alpha=>[]);

Since C<[]> contains fewer than 256 element the gamma channel is
unaffected.

It is also possible to simply specify an array of maps that are
applied to the images in the rgba order.  For example to apply
maps to the C<red> and C<blue> channels one would use:

  $img->map(maps=>[\@redmap, [], \@bluemap]);