3 Imager::Transformations - Simple transformations of one image into another.
9 $newimg = $img->copy();
11 $newimg = $img->scale(xpixels=>400);
12 $newimg = $img->scale(xpixels=>400, ypixels=>400);
13 $newimg = $img->scale(xpixels=>400, ypixels=>400, type=>'min');
14 $newimg = $img->scale(scalefactor=>0.25);
16 $newimg = $img->crop(left=>50, right=>100, top=>10, bottom=>100);
17 $newimg = $img->crop(left=>50, top=>10, width=>50, height=>90);
19 $dest->paste(left=>40,top=>20,img=>$logo);
21 $img->rubthrough(src=>$srcimage,tx=>30, ty=>50);
22 $img->rubthrough(src=>$srcimage,tx=>30, ty=>50,
23 src_minx=>20, src_miny=>30,
24 src_maxx=>20, src_maxy=>30);
27 $img->flip(dir=>"h"); # horizontal flip
28 $img->flip(dir=>"vh"); # vertical and horizontal flip
29 $newimg = $img->copy->flip(dir=>"v"); # make a copy and flip it vertically
31 my $rot20 = $img->rotate(degrees=>20);
32 my $rotpi4 = $img->rotate(radians=>3.14159265/4);
35 # Convert image to gray
36 $new = $img->convert(preset=>'grey');
38 # Swap red/green channel
39 $new = $img->convert(matrix=>[ [ 0, 1, 0 ],
43 # limit the range of red channel from 0..255 to 0..127
44 @map = map { int( $_/2 } 0..255;
45 $img->map( red=>\@map );
47 # Apply a Gamma of 1.4
49 my @map = map { int( 0.5 + 255*($_/255)**$gamma ) } 0..255;
50 $img->map(all=>\@map); # inplace conversion
54 The methods described in Imager::Transformations fall into two categories.
55 Either they take an existing image and modify it in place, or they
56 return a modified copy.
58 Functions that modify inplace are C<flip()>, C<paste()> and
59 C<rubthrough()>. If the original is to be left intact it's possible
60 to make a copy and alter the copy:
62 $flipped = $img->copy()->flip(dir=>'h');
64 =head2 Image copying/resizing/cropping/rotating
66 A list of the transformations that do not alter the source image follows:
72 To create a copy of an image use the C<copy()> method. This is usefull
73 if you want to keep an original after doing something that changes the image.
75 $newimg = $orig->copy();
79 To scale an image so porportions are maintained use the
80 C<$img-E<gt>scale()> method. if you give either a xpixels or ypixels
81 parameter they will determine the width or height respectively. If
82 both are given the one resulting in a larger image is used, unless you
83 set the C<type> parameter to C<'min'>. example: C<$img> is 700 pixels
84 wide and 500 pixels tall.
86 $newimg = $img->scale(xpixels=>400); # 400x285
87 $newimg = $img->scale(ypixels=>400); # 560x400
89 $newimg = $img->scale(xpixels=>400,ypixels=>400); # 560x400
90 $newimg = $img->scale(xpixels=>400,ypixels=>400,type=>'min'); # 400x285
92 $newimg = $img->scale(scalefactor=>0.25); 175x125
93 $newimg = $img->scale(); # 350x250
95 if you want to create low quality previews of images you can pass
96 C<qtype=E<gt>'preview'> to scale and it will use nearest neighbor
97 sampling instead of filtering. It is much faster but also generates
98 worse looking images - especially if the original has a lot of sharp
99 variations and the scaled image is by more than 3-5 times smaller than
102 If you need to scale images per axis it is best to do it simply by
103 calling scaleX and scaleY. You can pass either 'scalefactor' or
104 'pixels' to both functions.
108 Another way to resize an image is to crop it. The parameters to
109 crop are the edges of the area that you want in the returned image,
110 where the right and bottom edges are non-inclusive. If a parameter is
111 omitted a default is used instead.
113 # these produce the same image
114 $newimg = $img->crop(left=>50, right=>100, top=>10, bottom=>100);
115 $newimg = $img->crop(left=>50, top=>10, width=>50, height=>90);
116 $newimg = $img->crop(right=>100, bottom=>100, width=>50, height=>90);
118 # and the following produce the same image
119 $newimg = $img->crop(left=>50, right=>100);
120 $newimg = $img->crop(left=>50, right=>100, top=>0,
121 bottom=>$img->getheight);
123 # grab the top left corner of the image
124 $newimg = $img->crop(right=>50, bottom=>50);
126 You can also specify width and height parameters which will produce a
127 new image cropped from the center of the input image, with the given
130 $newimg = $img->crop(width=>50, height=>50);
132 If you supply C<left>, C<width> and C<right> values, the C<right>
133 value will be ignored. If you supply C<top>, C<height> and C<bottom>
134 values, the C<bottom> value will be ignored.
136 The edges of the cropped area default to the edges of the source
139 # a vertical bar from the middle from top to bottom
140 $newimg = $img->crop(width=>50);
143 $newimg = $img->crop(left=>$img->getwidth() / 2);
145 If the resulting image would have zero width or height then crop()
146 returns false and $img->errstr is an appropriate error message.
150 Use the rotate() method to rotate an image. This method will return a
153 To rotate by an exact amount in degrees or radians, use the 'degrees'
154 or 'radians' parameter:
156 my $rot20 = $img->rotate(degrees=>20);
157 my $rotpi4 = $img->rotate(radians=>3.14159265/4);
159 Exact image rotation uses the same underlying transformation engine as
160 the matrix_transform() method (see Imager::Engines).
162 You can also supply a C<back> argument which acts as a background
163 color for the areas of the image with no samples available (outside
164 the rectangle of the source image.) This can be either an
165 Imager::Color or Imager::Color::Float object. This is B<not> mixed
166 transparent pixels in the middle of the source image, it is B<only>
167 used for pixels where there is no corresponding pixel in the source
170 To rotate in steps of 90 degrees, use the 'right' parameter:
172 my $rotated = $img->rotate(right=>270);
174 Rotations are clockwise for positive values.
180 =head2 Image pasting/flipping/
182 A list of the transformations that alter the source image follows:
189 To copy an image to onto another image use the C<paste()> method.
191 $dest->paste(left=>40,top=>20,img=>$logo);
193 That copies the entire C<$logo> image onto the C<$dest> image so that the
194 upper left corner of the C<$logo> image is at (40,20).
199 A more complicated way of blending images is where one image is
200 put 'over' the other with a certain amount of opaqueness. The
201 method that does this is rubthrough.
203 $img->rubthrough(src=>$overlay,
205 src_minx=>20, src_miny=>30,
206 src_maxx=>20, src_maxy=>30);
208 That will take the sub image defined by I<$overlay> and
209 I<[src_minx,src_maxx)[src_miny,src_maxy)> and overlay it on top of
210 I<$img> with the upper left corner at (30,50). You can rub 2 or 4
211 channel images onto a 3 channel image, or a 2 channel image onto a 1
212 channel image. The last channel is used as an alpha channel. To add
213 an alpha channel to an image see I<convert()>.
218 An inplace horizontal or vertical flip is possible by calling the
219 C<flip()> method. If the original is to be preserved it's possible to
220 make a copy first. The only parameter it takes is the C<dir>
221 parameter which can take the values C<h>, C<v>, C<vh> and C<hv>.
223 $img->flip(dir=>"h"); # horizontal flip
224 $img->flip(dir=>"vh"); # vertical and horizontal flip
225 $nimg = $img->copy->flip(dir=>"v"); # make a copy and flip it vertically
232 =head2 Color transformations
234 You can use the convert method to transform the color space of an
235 image using a matrix. For ease of use some presets are provided.
237 The convert method can be used to:
243 convert an RGB or RGBA image to grayscale.
247 convert a grayscale image to RGB.
251 extract a single channel from an image.
255 set a given channel to a particular value (or from another channel)
259 The currently defined presets are:
267 converts an RGBA image into a grayscale image with alpha channel, or
268 an RGB image into a grayscale image without an alpha channel.
270 This weights the RGB channels at 22.2%, 70.7% and 7.1% respectively.
274 removes the alpha channel from a 2 or 4 channel image. An identity
281 extracts the first channel of the image into a single channel image
287 extracts the second channel of the image into a single channel image
293 extracts the third channel of the image into a single channel image
297 extracts the alpha channel of the image into a single channel image.
299 If the image has 1 or 3 channels (assumed to be grayscale of RGB) then
300 the resulting image will be all white.
304 converts a grayscale image to RGB, preserving the alpha channel if any
308 adds an alpha channel to a grayscale or RGB image. Preserves an
309 existing alpha channel for a 2 or 4 channel image.
313 For example, to convert an RGB image into a greyscale image:
315 $new = $img->convert(preset=>'grey'); # or gray
317 or to convert a grayscale image to an RGB image:
319 $new = $img->convert(preset=>'rgb');
321 The presets aren't necessary simple constants in the code, some are
322 generated based on the number of channels in the input image.
324 If you want to perform some other colour transformation, you can use
325 the 'matrix' parameter.
327 For each output pixel the following matrix multiplication is done:
329 | channel[0] | | $c00, ..., $c0k | | inchannel[0] |
330 | ... | = | ... | x | ... |
331 | channel[k] | | $ck0, ..., $ckk | | inchannel[k] |
333 Where C<k = $img-E<gt>getchannels()-1>.
335 So if you want to swap the red and green channels on a 3 channel image:
337 $new = $img->convert(matrix=>[ [ 0, 1, 0 ],
341 or to convert a 3 channel image to greyscale using equal weightings:
343 $new = $img->convert(matrix=>[ [ 0.333, 0.333, 0.334 ] ])
346 =head2 Color Mappings
348 You can use the map method to map the values of each channel of an
349 image independently using a list of lookup tables. It's important to
350 realize that the modification is made inplace. The function simply
351 returns the input image again or undef on failure.
353 Each channel is mapped independently through a lookup table with 256
354 entries. The elements in the table should not be less than 0 and not
355 greater than 255. If they are out of the 0..255 range they are
356 clamped to the range. If a table does not contain 256 entries it is
359 Single channels can mapped by specifying their name and the mapping
360 table. The channel names are C<red>, C<green>, C<blue>, C<alpha>.
362 @map = map { int( $_/2 } 0..255;
363 $img->map( red=>\@map );
365 It is also possible to specify a single map that is applied to all
366 channels, alpha channel included. For example this applies a gamma
367 correction with a gamma of 1.4 to the input image.
370 @map = map { int( 0.5 + 255*($_/255)**$gamma ) } 0..255;
371 $img->map(all=> \@map);
373 The C<all> map is used as a default channel, if no other map is
374 specified for a channel then the C<all> map is used instead. If we
375 had not wanted to apply gamma to the alpha channel we would have used:
377 $img->map(all=> \@map, alpha=>[]);
379 Since C<[]> contains fewer than 256 element the gamma channel is
382 It is also possible to simply specify an array of maps that are
383 applied to the images in the rgba order. For example to apply
384 maps to the C<red> and C<blue> channels one would use:
386 $img->map(maps=>[\@redmap, [], \@bluemap]);