[ 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 );
=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
=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
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');
# 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
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
A mandatory warning is produced if scaleY() is called in void context.
-=item scale_calculate
+=item scale_calculate()
Performs the same calculations that the scale() method does to
calculate the scaling factors from the parameters you pass.
=item *
-width, height - the image width and height to base the scaling on.
+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
-IMG tag, for example.
+HTML C<IMG> tag, for example.
Returns an empty list on failure.
my ($x_scale, $y_scale, $new_width, $new_height) =
$img->scale_calculate(xpixels => 200, type => 'min');
-=item crop
+=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.
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 grayscale, the the
+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
+=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
+=item compose()
-Draws the source image over the target image, with the src alpha
+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,
=item *
-src - the source image to draw onto the target. Required.
+C<src> - the source image to draw onto the target. Required.
=item *
-tx, ty - location in the the target image ($self) to render the top
+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 *
-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.
=item *
-mask - a mask image. The first channel of this image is used to
-modify the alpha channel of the source image. This can me used to
+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
-max the full alpha of the source image will be used, as further
+maximum the full alpha of the source image will be used, as further
modified by the opacity.
=item *
compose() returns true on success. On failure check $target->errstr
for the reason for failure.
-=item flip
+=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 *
+
+C<rgb>
-converts a grayscale image to RGB, preserving the alpha channel if any
+converts a gray scale image to RGB, preserving the alpha channel if any
-=item addalpha
+=item *
-adds an alpha channel to a grayscale or RGB image. Preserves an
-existing alpha channel for a 2 or 4 channel image.
+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