$newimg = $img->copy();
- $newimg = $img->scale(xpixels=>400);
+ $newimg = $img->scale(xpixels=>400, qtype => 'mixing');
$newimg = $img->scale(xpixels=>400, ypixels=>400);
$newimg = $img->scale(xpixels=>400, ypixels=>400, type=>'min');
$newimg = $img->scale(scalefactor=>0.25);
src_minx=>20, src_miny=>30,
src_maxx=>20, src_maxy=>30);
+ $img->compose(src => $src, tx => 30, ty => 20, combine => 'color');
+ $img->compose(src => $src, tx => 30, ty => 20, combine => 'color');
+ mask => $mask, opacity => 0.5);
$img->flip(dir=>"h"); # horizontal flip
$img->flip(dir=>"vh"); # vertical and horizontal flip
[ 1, 0, 0 ],
[ 0, 0, 1 ] ]);
+ # build an image using channels from multiple input images
+ $new = $img->combine(src => [ $im1, $im2, $im3 ]);
+ $new = $img->combine(src => [ $im1, $im2, $im3 ],
+ channels => [ 2, 1, 0 ]);
+
# limit the range of red channel from 0..255 to 0..127
@map = map { int( $_/2 } 0..255;
$img->map( red=>\@map );
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:
+Functions that modify inplace are C<flip()>, C<paste()>,
+C<rubthrough()> and C<compose()>. 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');
=over
-=item copy
+=item copy()
-To create a copy of an image use the C<copy()> method. This is usefull
+To create a copy of an image use the C<copy()> method. This is useful
if you want to keep an original after doing something that changes the image.
$newimg = $orig->copy();
-=item scale
+=item scale()
-X<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.
+X<scale>To scale an image so proportions are maintained use the
+C<$img-E<gt>scale()> method. if you give either a C<xpixels> or
+C<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(scalefactor=>0.25); 175x125
$newimg = $img->scale(); # 350x250
-if you want to create low quality previews of images you can pass
+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
=item *
-xpixels, ypixels - desired size of the scaled image. The C<type>
-parameter controls whether the larger or smaller of the two possible
-sizes is chosen, or if the image is scaled non-proportionally.
+C<xpixels>, C<ypixels> - desired size of the scaled image. The
+C<type> parameter controls whether the larger or smaller of the two
+possible sizes is chosen, or if the image is scaled
+non-proportionally.
=item *
-constrain - an Image::Math::Constrain object defining the way in which
-the image size should be constrained.
+C<constrain> - an Image::Math::Constrain object defining the way in
+which the image size should be constrained.
=item *
-scalefactor - if none of xpixels, ypixels, xscalefactor, yscalefactor
-or constrain is supplied then this is used as the ratio to scale by.
-Default: 0.5.
+C<scalefactor> - if none of C<xpixels>, C<ypixels>, C<xscalefactor>,
+C<yscalefactor> or C<constrain> is supplied then this is used as the
+ratio to scale by. Default: 0.5.
=item *
-xscalefactor, yscalefactor - if both are supplied then the image is
+C<xscalefactor>, C<yscalefactor> - if both are supplied then the image is
scaled as per these parameters, whether this is proportionally or not.
New in Imager 0.54.
=item *
-type - controls whether the larger or smaller of the two possible
+C<type> - controls whether the larger or smaller of the two possible
sizes is chosen, possible values are:
=over
=item *
-min - the smaller of the 2 sizes are chosen.
+C<min> - the smaller of the 2 sizes are chosen.
=item *
-max - the larger of the 2 sizes. This is the default.
+C<max> - the larger of the 2 sizes. This is the default.
=item *
-nonprop - non-proportional scaling. New in Imager 0.54.
+C<nonprop> - non-proportional scaling. New in Imager 0.54.
=back
For example, if the original image is 400 pixels wide by 200 pixels
high and C<xpixels> is set to 300, and C<ypixels> is set to 160. When
C<type> is C<'min'> the resulting image is 300 x 150, when C<type> is
-C<'max'> the resulting image is 320 x 150.
+C<'max'> the resulting image is 320 x 160.
C<type> is only used if both C<xpixels> and C<ypixels> are supplied.
=item *
-qtype - defines the quality of scaling performed. Possible values are:
+C<qtype> - defines the quality of scaling performed. Possible values are:
=over
=item *
-C<mixing> - implements the mixing algorithm implemented by pnmscale.
-This retains more detail when scaling down than C<normal>. When
-scaling down this proportionally accumulates sample data from the
-pixels, resulting in a proportional mix of all of the pixels. When
-scaling up this will mix pixels when the sampling grid crosses a pixel
-boundary but will otherwise copy pixel values.
+C<mixing> - implements the mixing algorithm implemented by
+F<pnmscale>. This retains more detail when scaling down than
+C<normal>. When scaling down this proportionally accumulates sample
+data from the pixels, resulting in a proportional mix of all of the
+pixels. When scaling up this will mix pixels when the sampling grid
+crosses a pixel boundary but will otherwise copy pixel values.
=back
scale() will fail if C<qtype> is set to some other value.
+C<preview> is faster than C<mixing> which is much faster than C<normal>.
+
=back
To scale an image on a given axis without maintaining proportions, it
my $scaled = $img->scaleX(pixels=>400)->scaleY(pixels=>200);
From Imager 0.54 you can scale without maintaining proportions either
-by supplying both the xscalefactor and yscalefactor arguments:
+by supplying both the C<xscalefactor> and C<yscalefactor> arguments:
my $scaled = $img->scale(xscalefactor => 0.5, yscalefactor => 0.67);
or by supplying C<xpixels> and C<ypixels> and setting C<type> to
-"nonprop":
+<nonprop>:
my $scaled = $im->scale(xpixels => 200, ypixels => 200, type => 'nonprop');
-Returns the scaled image on success.
+Returns a new scaled image on success. The source image is not
+modified.
Returns false on failure, check the errstr() method for the reason for
failure.
# same as Image::Math::Constrain version
my $scaled2 = $image->scale(xpixels => 800, ypixels => 600, type => 'min');
-=item scaleX
+=item scaleX()
scaleX() will scale along the X dimension, return a new image with the
new width:
=item *
-
scalefactor - the amount to scale the X axis. Ignored if C<pixels> is
+
C<scalefactor> - the amount to scale the X axis. Ignored if C<pixels> is
provided. Default: 0.5.
=item *
-pixels - the new width of the image.
+C<pixels> - the new width of the image.
=back
-Returns the scaled image on success.
+Returns a new scaled image on success. The source image is not
+modified.
Returns false on failure, check the errstr() method for the reason for
failure.
A mandatory warning is produced if scaleX() is called in void context.
-=item scaleY
+=item scaleY()
scaleY() will scale along the Y dimension, return a new image with the
new height:
=item *
-
scalefactor - the amount to scale the Y axis. Ignored if C<pixels> is
+
C<scalefactor> - the amount to scale the Y axis. Ignored if C<pixels> is
provided. Default: 0.5.
=item *
-pixels - the new height of the image.
+C<pixels> - the new height of the image.
=back
-Returns the scaled image on success.
+Returns a new scaled image on success. The source image is not
+modified.
Returns false on failure, check the errstr() method for the reason for
failure.
A mandatory warning is produced if scaleY() is called in void context.
-=item crop
+=item scale_calculate()
+
+Performs the same calculations that the scale() method does to
+calculate the scaling factors from the parameters you pass.
+
+scale_calculate() can be called as an object method, or as a class
+method.
+
+Takes the following parameters over scale():
+
+=over
+
+=item *
+
+C<width>, C<height> - the image width and height to base the scaling on.
+Required if scale_calculate() is called as a class method. If called
+as an object method these default to the image width and height
+respectively.
+
+=back
+
+You might use scale_calculate() as a class method when generating an
+HTML C<IMG> tag, for example.
+
+Returns an empty list on failure.
+
+Returns a list containing horizontal scale factor, vertical scale
+factor, new width, new height, on success.
+
+ my ($x_scale, $y_scale, $new_width, $new_height) =
+ Imager->scale_calculate(width => 1024, height => 768,
+ ypixels => 180, type => 'min');
+
+ my ($x_scale, $y_scale, $new_width, $new_height) =
+ $img->scale_calculate(xpixels => 200, type => 'min');
+
+=item crop()
+
+=for stopwords resize
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,
A mandatory warning is produced if crop() is called in void context.
-=item rotate
+=item rotate()
Use the rotate() method to rotate an image. This method will return a
new, rotated image.
=item *
-right - rotate by an exact multiple of 90 degrees, specified in
-degreess.
+C<right> - rotate by an exact multiple of 90 degrees, specified in
+degrees.
=item *
-radians - rotate by an angle specified in radians.
+C<radians> - rotate by an angle specified in radians.
=item *
-degrees - rotate by an angle specified in degrees.
+C<degrees> - rotate by an angle specified in degrees.
=item *
-back - for C<radians> and C<degrees> this is the color used for the
+C<back> - for C<radians> and C<degrees> this is the color used for the
areas not covered by the original image. For example, the corners of
an image rotated by 45 degrees.
=over
-=item paste
+=item paste()
X<paste>To copy an image to onto another image use the C<paste()>
method.
=item *
-src, img - the source image. I<src> added for compatibility with
+C<src>, C<img> - the source image. C<src> added for compatibility with
rubthrough().
=item *
-left, top - position in output of the top left of the pasted image.
+C<left>, C<top> - position in output of the top left of the pasted image.
Default: (0,0)
=item *
-src_minx, src_miny - the top left corner in the source image to start
+C<src_minx>, C<src_miny> - the top left corner in the source image to start
the paste from. Default: (0, 0)
=item *
-src_maxx, src_maxy - the bottom right in the source image of the sub
+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 *
-width, height - if the corresponding src_maxx or src_maxy is not
+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.
left => 10, top => 10,
src_minx => 20, src_miny => 20,
src_maxx => 40, src_maxx => 40);
-
-=item rubthrough
+
+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.
+method that does this is rubthrough().
$img->rubthrough(src=>$overlay,
tx=>30, ty=>50,
=item *
-tx, ty - location in the the target image ($self) to render the top
-left corner of the source.
+C<tx>, C<ty> - location in the target image ($self) to render the
+top left corner of the source.
=item *
-src_minx, src_miny - the top left corner in the source to transfer to
+C<src_minx>, C<src_miny> - the top left corner in the source to transfer to
the target image. Default: (0, 0).
=item *
-src_maxx, src_maxy - the bottom right in the source image of the sub
+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.
src_miny => $src->getheight() - 20);
rubthrough() returns true on success. On failure check
-$target->errstr for the reason for failure.
+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 *
-=item flip
+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
=over
-=item convert
+=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.
=item *
-convert an RGB or RGBA image to grayscale.
+convert an RGB or RGBA image to gray scale.
=item *
-convert a grayscale image to RGB.
+convert a gray scale image to RGB.
=item *
=over
-=item gray
-
-=item grey
+=item *
-converts an RGBA image into a grayscale image with alpha channel, or
-an RGB image into a grayscale image without an alpha channel.
+C<gray>, C<grey> - converts an RGBA image into a gray scale image with
+alpha channel, or an RGB image into a gray scale 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
+=item *
-extracts the first channel of the image into a single channel image
+C<noalpha> - removes the alpha channel from a 2 or 4 channel image.
+An identity for other images.
-=item green
+=item *
-=item channel1
+C<red>, C<channel0> - extracts the first channel of the image into a
+single channel image
-extracts the second channel of the image into a single channel image
+=item *
-=item blue
+C<green>, C<channel1> - extracts the second channel of the image into
+a single channel image
-=item channel2
+=item *
-extracts the third channel of the image into a single channel image
+C<blue>, C<channel2> - extracts the third channel of the image into a
+single channel image
-=item alpha
+=item *
-extracts the alpha channel of the image into a single channel image.
+C<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
+If the image has 1 or 3 channels (assumed to be gray scale or RGB) then
the resulting image will be all white.
-=item rgb
+=item *
-converts a grayscale image to RGB, preserving the alpha channel if any
+C<rgb>
-=item addalpha
+converts a gray scale image to RGB, preserving the alpha channel if any
-adds an alpha channel to a grayscale or RGB image. Preserves an
-existing alpha channel for a 2 or 4 channel image.
+=item *
+
+C<addalpha> - adds an alpha channel to a gray scale 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:
+For example, to convert an RGB image into a gray scale image:
$new = $img->convert(preset=>'grey'); # or gray
-or to convert a grayscale image to an RGB image:
+or to convert a gray scale 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
+If you want to perform some other color transformation, you can use
the 'matrix' parameter.
For each output pixel the following matrix multiplication is done:
[ 1, 0, 0 ],
[ 0, 0, 1 ] ]);
-or to convert a 3 channel image to greyscale using equal weightings:
+or to convert a 3 channel image to gray scale using equal weightings:
$new = $img->convert(matrix=>[ [ 0.333, 0.333, 0.334 ] ])
-Convert a 2 channel image (grayscale with alpha) to an RGBA image with
-the grey converted to the specified RGB color:
+Convert a 2 channel image (gray scale with alpha) to an RGBA image with
+the gray converted to the specified RGB color:
# set (RGB) scaled on the grey scale portion and copy the alpha
# channel as is
[ 0, 0, 0, 0.5 ],
]);
+=item combine()
+X<combine>
+
+Combine channels from one or more input images into a new image.
+
+Parameters:
+
+=over
+
+=item *
+
+C<src> - a reference to an array of input images. There must be at least
+one input image. A given image may appear more than once in C<src>.
+
+=item *
+
+C<channels> - a reference to an array of channels corresponding to the
+source images. If C<channels> is not supplied then the first channel
+from each input image is used. If the array referenced by C<channels>
+is shorter than that referenced by C<src> then the first channel is
+used from the extra images.
+
+=back
+
+ # make an rgb image from red, green, and blue images
+ my $rgb = Imager->combine(src => [ $red, $green, $blue ]);
+
+ # convert a BGR image into RGB
+ my $rgb = Imager->combine(src => [ $bgr, $bgr, $bgr ],
+ channels => [ 2, 1, 0 ]);
+
+ # add an alpha channel from another image
+ my $rgba = Imager->combine(src => [ $rgb, $rgb, $rgb, $alpha ],
+ channels => [ 0, 1, 2, 0 ]);
+
=back
=head2 Color Mappings
=over
-=item map
+=item map()
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
+image independently using a list of look-up 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
+Each channel is mapped independently through a look-up 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
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
+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]);
=head1 AUTHOR
-Tony Cook <tony@imager.perl.org>, Arnar M. Hrafnkelsson
+Tony Cook <tonyc@cpan.org>, Arnar M. Hrafnkelsson
=head1 REVISION
projects / imager.git / blobdiff