view release on metacpan or  search on metacpan

lib/Imager/Transformations.pod  view on Meta::CPAN

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

  $dest->paste(left=>40, top=>20, src=>$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).

Parameters:

=over

=item *

C<src>, C<img> - the source image.  C<src> added for compatibility with
rubthrough().

=item *

C<left>, C<top> - position in output of the top left of the pasted image.
Default: (0,0)

=item *

C<src_minx>, C<src_miny> - the top left corner in the source image to start
the paste from.  Default: (0, 0)

=item *

C<src_maxx>, C<src_maxy> - the bottom right in the source image of the sub
image to paste.  This position is B<non> inclusive.  Default: bottom
right corner of the source image.

=item *

C<width>, C<height> - if the corresponding src_maxx or src_maxy is not
defined then width or height is used for the width or height of the
sub image to be pasted.

=back

  # copy the 20x20 pixel image from (20,20) in $src_image to (10,10) in $img
  $img->paste(src=>$src_image,
              left => 10, top => 10,
              src_minx => 20, src_miny => 20,
              src_maxx => 40, src_maxx => 40);

If the source image has an alpha channel and the target doesn't, then
the source is treated as if composed onto a black background.

If the source image is color and the target is gray scale, the
source is treated as if run through C<< convert(preset=>'gray') >>.

=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=>$overlay,
                   tx=>30,       ty=>50,
                   src_minx=>20, src_miny=>30,
                   src_maxx=>20, src_maxy=>30);

That will take the sub image defined by I<$overlay> and
I<[src_minx,src_maxx)[src_miny,src_maxy)> and overlay it on top of
I<$img> 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.  To add
an alpha channel to an image see I<convert()>.

Parameters:

=over

=item *

C<tx>, C<ty> - location in the target image ($self) to render the
top left corner of the source.

=item *

C<src_minx>, C<src_miny> - the top left corner in the source to transfer to
the target image.  Default: (0, 0).

=item *

C<src_maxx>, C<src_maxy> - the bottom right in the source image of the sub
image to overlay.  This position is B<non> inclusive.  Default: bottom
right corner of the source image.

=back

  # overlay all of $source onto $targ
  $targ->rubthrough(tx => 20, ty => 25, src => $source);

  # overlay the top left corner of $source onto $targ
  $targ->rubthrough(tx => 20, ty => 25, src => $source,
                    src_maxx => 20, src_maxy => 20);

  # overlay the bottom right corner of $source onto $targ
  $targ->rubthrough(tx => 20, ty => 30, src => $src,
                    src_minx => $src->getwidth() - 20,
                    src_miny => $src->getheight() - 20);

rubthrough() returns true on success.  On failure check
C<< $target->errstr >> for the reason for failure.

=item compose()

Draws the source image over the target image, with the source alpha
channel modified by the optional mask and the opacity.

  $img->compose(src=>$overlay,
                tx=>30,       ty=>50,
                src_minx=>20, src_miny=>30,
                src_maxx=>20, src_maxy=>30,
                mask => $mask, opacity => 0.5);

That will take the sub image defined by I<$overlay> and
I<[src_minx,src_maxx)[src_miny,src_maxy)> and overlay it on top of
I<$img> 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.

Parameters:

=over

=item *

C<src> - the source image to draw onto the target.  Required.

=item *

C<tx>, C<ty> - location in the target image ($self) to render the top
left corner of the source.  These can also be supplied as C<left> and
C<right>.  Default: (0, 0).

=item *

C<src_minx>, C<src_miny> - the top left corner in the source to transfer to
the target image.  Default: (0, 0).

=item *

C<src_maxx>, C<src_maxy> - the bottom right in the source image of the sub
image to overlay.  This position is B<non> inclusive.  Default: bottom
right corner of the source image.

=item *

C<mask> - a mask image.  The first channel of this image is used to
modify the alpha channel of the source image.  This can be used to
mask out portions of the source image.  Where the first channel is
zero none of the source image will be used, where the first channel is
maximum the full alpha of the source image will be used, as further
modified by the opacity.

=item *

opacity - further modifies the alpha channel of the source image, in
the range 0.0 to 1.0.  Default: 1.0.

=item *

combine - the method to combine the source pixels with the target.
See the combine option documentation in Imager::Fill.  Default:
normal.

=back

Calling compose() with no mask, combine set to C<normal>, opacity set
to C<1.0> is equivalent to calling rubthrough().

compose() is intended to be produce similar effects to layers in
interactive paint software.

  # overlay all of $source onto $targ
  $targ->compose(tx => 20, ty => 25, src => $source);

  # overlay the top left corner of $source onto $targ
  $targ->compose(tx => 20, ty => 25, src => $source,
                    src_maxx => 20, src_maxy => 20);

  # overlay the bottom right corner of $source onto $targ
  $targ->compose(tx => 20, ty => 30, src => $src,
                    src_minx => $src->getwidth() - 20,
                    src_miny => $src->getheight() - 20);

compose() returns true on success.  On failure check $target->errstr
for the reason for failure.

=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

flip() returns true on success.  On failure check $img->errstr for the
reason for failure.

=back

=head2 Color transformations

=over

=item convert()

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 gray scale.

=item *

convert a gray scale 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 *