$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);
=item scale
-To scale an image so porportions are maintained use the
+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
$newimg = $img->scale(xpixels=>400,ypixels=>400); # 560x400
$newimg = $img->scale(xpixels=>400,ypixels=>400,type=>'min'); # 400x285
+ $newimg = $img->scale(xpixels=>400, ypixels=>400),type=>'nonprop'); # 400x400
+
$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 resulting
-image is always scaled proportionally. The C<type> parameter controls
-whether the larger or smaller of the two possible sizes is chosen.
+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.
+
+=item *
+
+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.
+
+=item *
+
+xscalefactor, 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 *
max - the larger of the 2 sizes. This is the default.
+=item *
+
+nonprop - non-proportional scaling. New in Imager 0.54.
+
=back
-The behaviour when C<type> is set to some other value is undefined.
+scale() will fail if C<type> is set to some other value.
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
=item *
-normal - high quality scaling. This is the default.
+C<normal> - high quality scaling. This is the default.
+
+=item *
+
+C<preview> - lower quality. When scaling down this will skip input
+pixels, eg. scaling by 0.5 will skip every other pixel. When scaling
+up this will duplicate pixels.
=item *
-preview - lower quality.
+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.
=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);
-Returns the scaled image on success.
+From Imager 0.54 you can scale without maintaining proportions either
+by supplying both the xscalefactor and 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":
+
+ my $scaled = $im->scale(xpixels => 200, ypixels => 200, type => 'nonprop');
+
+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 scale() is called in void context.
+
+ # setup
+ my $image = Imager->new;
+ $image->read(file => 'somefile.jpg')
+ or die $image->errstr;
+
+ # all full quality unless indicated otherwise
+ # half the size:
+ my $half = $image->scale;
+
+ # double the size
+ my $double = $image->scale(scalefactor => 2.0);
+
+ # so a 400 x 400 box fits in the resulting image:
+ my $fit400x400inside = $image->scale(xpixels => 400, ypixels => 400);
+ my $fit400x400inside2 = $image->scale(xpixels => 400, ypixels => 400,
+ type=>'max');
+
+ # fit inside a 400 x 400 box
+ my $inside400x400 = $image->scale(xpixels => 400, ypixels => 400,
+ type=>'min');
+
+ # make it 400 pixels wide or high
+ my $width400 = $image->scale(xpixels => 400);
+ my $height400 = $image->scale(ypixels => 400);
+
+ # low quality scales:
+ # to half size
+ my $low = $image->scale(qtype => 'preview');
+
+ # mixing method scale
+ my $mixed = $image->scale(qtype => 'mixing', scalefactor => 0.1);
+
+ # using an Image::Math::Constrain object
+ use Image::Math::Constrain;
+ my $constrain = Image::Math::Constrain->new(800, 600);
+ my $scaled = $image->scale(constrain => $constrain);
+
+ # same as Image::Math::Constrain version
+ my $scaled2 = $image->scale(xpixels => 800, ypixels => 600, type => 'min');
+
=item scaleX
-scaleX() will scale along the X dimension, changing the width of the
-image:
+scaleX() will scale along the X dimension, return a new image with the
+new width:
- $newimg = $img->scaleX(pixels=>400); # 400x500
+ my $newimg = $img->scaleX(pixels=>400); # 400x500
$newimg = $img->scaleX(scalefactor=>0.25) # 175x500
+=over
+
+=item *
+
+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.
+
+=back
+
+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
-scaleY() will scale along the Y dimension, changing the height of the
-image:
+scaleY() will scale along the Y dimension, return a new image with the
+new height:
$newimg = $img->scaleY(pixels=>400); # 700x400
$newimg = $img->scaleY(scalefactor=>0.25) # 700x125
+=over
+
+=item *
+
+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.
+
+=back
+
+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
Another way to resize an image is to crop it. The parameters to
where the right and bottom edges are non-inclusive. If a parameter is
omitted a default is used instead.
+crop() returns the cropped image and does not modify the source image.
+
The possible parameters are:
=over
If the resulting image would have zero width or height then crop()
returns false and $img->errstr is an appropriate error message.
+A mandatory warning is produced if crop() is called in void context.
+
=item rotate
Use the rotate() method to rotate an image. This method will return a
Rotations are clockwise for positive values.
+Parameters:
+
+=over
+
+=item *
+
+right - rotate by an exact multiple of 90 degrees, specified in
+degreess.
+
+=item *
+
+radians - rotate by an angle specified in radians.
+
+=item *
+
+degrees - rotate by an angle specified in degrees.
+
+=item *
+
+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.
+
+This can be either an Imager::Color object, an Imager::Color::Float
+object or any parameter that Imager can convert to a color object, see
+L<Imager::Draw/Color Parameters> for details.
+
+This is B<not> mixed transparent pixels in the middle of the source
+image, it is B<only> used for pixels where there is no corresponding
+pixel in the source image.
+
+Default: transparent black.
=back
+ # rotate 45 degrees clockwise,
+ my $rotated = $img->rotate(degrees => 45);
-=head2 Image pasting/flipping/
+ # rotate 10 degrees counter-clockwise
+ # set pixels not sourced from the original to red
+ my $rotated = $img->rotate(degrees => -10, back => 'red');
+
+=back
+
+=head2 Image pasting/flipping
A list of the transformations that alter the source image follows:
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 *
+
+tx, ty - location in the 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
+the target image. Default: (0, 0).
+
+=item *
+
+src_maxx, 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
+$target->errstr for the reason for failure.
=item flip
$img->flip(dir=>"vh"); # vertical and horizontal flip
$nimg = $img->copy->flip(dir=>"v"); # make a copy and flip it vertically
-=back
+flip() returns true on success. On failure check $img->errstr for the
+reason for failure.
+=back
+=head2 Color transformations
+=over
-=head2 Color transformations
+=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.
[ 0, 1 ],
]);
+To convert a 3 channel image to a 4 channel image with a 50 percent
+alpha channel:
+
+ my $withalpha = $rgb->convert(matrix =>[ [ 1, 0, 0, 0 ],
+ [ 0, 1, 0, 0 ],
+ [ 0, 0, 1, 0 ],
+ [ 0, 0, 0, 0.5 ],
+ ]);
+
+=back
+
=head2 Color Mappings
+=over
+
+=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
realize that the modification is made inplace. The function simply
$img->map(maps=>[\@redmap, [], \@bluemap]);
+=back
+
+=head1 SEE ALSO
+
+L<Imager>, L<Imager::Engines>
+
+=head1 AUTHOR
+
+Tony Cook <tony@imager.perl.org>, Arnar M. Hrafnkelsson
+
+=head1 REVISION
+
+$Revision$
+
=cut
projects / imager.git / blobdiff