- added log() and exp() functions to transform2()
[imager.git] / lib / Imager / Transformations.pod
CommitLineData
8435f780
AMH
1=head1 NAME
2
3Imager::Transformations - Simple transformations of one image into another.
4
5=head1 SYNOPSIS
6
7 use Imager;
8
9 $newimg = $img->copy();
10
11 $newimg = $img->scale(xpixels=>400);
12 $newimg = $img->scale(xpixels=>400, ypixels=>400);
6d0ed98a 13 $newimg = $img->scale(xpixels=>400, ypixels=>400, type=>'min');
8435f780
AMH
14 $newimg = $img->scale(scalefactor=>0.25);
15
16 $newimg = $img->crop(left=>50, right=>100, top=>10, bottom=>100);
17 $newimg = $img->crop(left=>50, top=>10, width=>50, height=>90);
18
19 $dest->paste(left=>40,top=>20,img=>$logo);
20
71dc4a83
AMH
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);
8435f780
AMH
25
26
27 $img->flip(dir=>"h"); # horizontal flip
28 $img->flip(dir=>"vh"); # vertical and horizontal flip
3e1be2c1 29 $newimg = $img->copy->flip(dir=>"v"); # make a copy and flip it vertically
8435f780
AMH
30
31 my $rot20 = $img->rotate(degrees=>20);
32 my $rotpi4 = $img->rotate(radians=>3.14159265/4);
33
3e1be2c1
AMH
34
35 # Convert image to gray
36 $new = $img->convert(preset=>'grey');
37
38 # Swap red/green channel
39 $new = $img->convert(matrix=>[ [ 0, 1, 0 ],
40 [ 1, 0, 0 ],
41 [ 0, 0, 1 ] ]);
42
aed9d070
TC
43 # image composition
44 $img->compose(img=>$source, mask=>$mask, left=>100, top=>50)
45 or die $img->errstr;
46
3e1be2c1
AMH
47 # limit the range of red channel from 0..255 to 0..127
48 @map = map { int( $_/2 } 0..255;
49 $img->map( red=>\@map );
50
51 # Apply a Gamma of 1.4
52 my $gamma = 1.4;
53 my @map = map { int( 0.5 + 255*($_/255)**$gamma ) } 0..255;
54 $img->map(all=>\@map); # inplace conversion
55
8435f780
AMH
56=head1 DESCRIPTION
57
58The methods described in Imager::Transformations fall into two categories.
59Either they take an existing image and modify it in place, or they
60return a modified copy.
61
62Functions that modify inplace are C<flip()>, C<paste()> and
63C<rubthrough()>. If the original is to be left intact it's possible
64to make a copy and alter the copy:
65
66 $flipped = $img->copy()->flip(dir=>'h');
67
68=head2 Image copying/resizing/cropping/rotating
69
70A list of the transformations that do not alter the source image follows:
71
72=over
73
74=item copy
75
76To create a copy of an image use the C<copy()> method. This is usefull
77if you want to keep an original after doing something that changes the image.
78
79 $newimg = $orig->copy();
80
81=item scale
82
83To scale an image so porportions are maintained use the
84C<$img-E<gt>scale()> method. if you give either a xpixels or ypixels
85parameter they will determine the width or height respectively. If
6d0ed98a
TC
86both are given the one resulting in a larger image is used, unless you
87set the C<type> parameter to C<'min'>. example: C<$img> is 700 pixels
88wide and 500 pixels tall.
8435f780
AMH
89
90 $newimg = $img->scale(xpixels=>400); # 400x285
91 $newimg = $img->scale(ypixels=>400); # 560x400
92
93 $newimg = $img->scale(xpixels=>400,ypixels=>400); # 560x400
6d0ed98a 94 $newimg = $img->scale(xpixels=>400,ypixels=>400,type=>'min'); # 400x285
8435f780
AMH
95
96 $newimg = $img->scale(scalefactor=>0.25); 175x125
97 $newimg = $img->scale(); # 350x250
98
99if you want to create low quality previews of images you can pass
100C<qtype=E<gt>'preview'> to scale and it will use nearest neighbor
101sampling instead of filtering. It is much faster but also generates
102worse looking images - especially if the original has a lot of sharp
103variations and the scaled image is by more than 3-5 times smaller than
104the original.
105
106If you need to scale images per axis it is best to do it simply by
107calling scaleX and scaleY. You can pass either 'scalefactor' or
108'pixels' to both functions.
109
110=item crop
111
fb19e83e
TC
112Another way to resize an image is to crop it. The parameters to
113crop are the edges of the area that you want in the returned image,
114where the right and bottom edges are non-inclusive. If a parameter is
115omitted a default is used instead.
8435f780 116
fb19e83e 117 # the first two produce the same image
8435f780
AMH
118 $newimg = $img->crop(left=>50, right=>100, top=>10, bottom=>100);
119 $newimg = $img->crop(left=>50, top=>10, width=>50, height=>90);
120 $newimg = $img->crop(left=>50, right=>100); # top
121
122You can also specify width and height parameters which will produce a
123new image cropped from the center of the input image, with the given
124width and height.
125
126 $newimg = $img->crop(width=>50, height=>50);
127
128The width and height parameters take precedence over the left/right
129and top/bottom parameters respectively.
130
131=item rotate
132
8435f780
AMH
133Use the rotate() method to rotate an image. This method will return a
134new, rotated image.
135
136To rotate by an exact amount in degrees or radians, use the 'degrees'
137or 'radians' parameter:
138
139 my $rot20 = $img->rotate(degrees=>20);
140 my $rotpi4 = $img->rotate(radians=>3.14159265/4);
141
142Exact image rotation uses the same underlying transformation engine as
143the matrix_transform() method.
144
145To rotate in steps of 90 degrees, use the 'right' parameter:
146
147 my $rotated = $img->rotate(right=>270);
148
149Rotations are clockwise for positive values.
150
151=back
152
153
154=head2 Image pasting/flipping/
155
156A list of the transformations that alter the source image follows:
157
158=over
159
160=item paste
161
162
163To copy an image to onto another image use the C<paste()> method.
164
165 $dest->paste(left=>40,top=>20,img=>$logo);
166
167That copies the entire C<$logo> image onto the C<$dest> image so that the
168upper left corner of the C<$logo> image is at (40,20).
169
170
171=item rubthrough
172
173A more complicated way of blending images is where one image is
174put 'over' the other with a certain amount of opaqueness. The
175method that does this is rubthrough.
176
71dc4a83
AMH
177 $img->rubthrough(src=>$overlay,
178 tx=>30, ty=>50,
179 src_minx=>20, src_miny=>30,
180 src_maxx=>20, src_maxy=>30);
181
182That will take the sub image defined by I<$overlay> and
183I<[src_minx,src_maxx)[src_miny,src_maxy)> and overlay it on top of
184I<$img> with the upper left corner at (30,50). You can rub 2 or 4
185channel images onto a 3 channel image, or a 2 channel image onto a 1
186channel image. The last channel is used as an alpha channel. To add
187an alpha channel to an image see I<convert()>.
8435f780
AMH
188
189
190=item flip
191
192An inplace horizontal or vertical flip is possible by calling the
193C<flip()> method. If the original is to be preserved it's possible to
194make a copy first. The only parameter it takes is the C<dir>
195parameter which can take the values C<h>, C<v>, C<vh> and C<hv>.
196
197 $img->flip(dir=>"h"); # horizontal flip
198 $img->flip(dir=>"vh"); # vertical and horizontal flip
199 $nimg = $img->copy->flip(dir=>"v"); # make a copy and flip it vertically
200
201=back
202
203
204
205
3e1be2c1
AMH
206=head2 Color transformations
207
208You can use the convert method to transform the color space of an
209image using a matrix. For ease of use some presets are provided.
210
211The convert method can be used to:
212
213=over
214
215=item *
216
217convert an RGB or RGBA image to grayscale.
218
219=item *
220
221convert a grayscale image to RGB.
222
223=item *
224
225extract a single channel from an image.
226
227=item *
228
229set a given channel to a particular value (or from another channel)
230
231=back
232
233The currently defined presets are:
234
235=over
236
237=item gray
238
239=item grey
240
241converts an RGBA image into a grayscale image with alpha channel, or
242an RGB image into a grayscale image without an alpha channel.
243
244This weights the RGB channels at 22.2%, 70.7% and 7.1% respectively.
245
246=item noalpha
247
248removes the alpha channel from a 2 or 4 channel image. An identity
249for other images.
250
251=item red
252
253=item channel0
254
255extracts the first channel of the image into a single channel image
256
257=item green
258
259=item channel1
260
261extracts the second channel of the image into a single channel image
262
263=item blue
264
265=item channel2
266
267extracts the third channel of the image into a single channel image
268
269=item alpha
270
271extracts the alpha channel of the image into a single channel image.
272
273If the image has 1 or 3 channels (assumed to be grayscale of RGB) then
274the resulting image will be all white.
275
276=item rgb
277
278converts a grayscale image to RGB, preserving the alpha channel if any
279
280=item addalpha
281
282adds an alpha channel to a grayscale or RGB image. Preserves an
283existing alpha channel for a 2 or 4 channel image.
284
285=back
286
287For example, to convert an RGB image into a greyscale image:
288
289 $new = $img->convert(preset=>'grey'); # or gray
290
291or to convert a grayscale image to an RGB image:
292
293 $new = $img->convert(preset=>'rgb');
294
295The presets aren't necessary simple constants in the code, some are
296generated based on the number of channels in the input image.
297
298If you want to perform some other colour transformation, you can use
299the 'matrix' parameter.
300
301For each output pixel the following matrix multiplication is done:
302
303 | channel[0] | | $c00, ..., $c0k | | inchannel[0] |
304 | ... | = | ... | x | ... |
305 | channel[k] | | $ck0, ..., $ckk | | inchannel[k] |
306 1
55b287f5 307Where C<k = $img-E<gt>getchannels()-1>.
3e1be2c1
AMH
308
309So if you want to swap the red and green channels on a 3 channel image:
310
311 $new = $img->convert(matrix=>[ [ 0, 1, 0 ],
312 [ 1, 0, 0 ],
313 [ 0, 0, 1 ] ]);
314
315or to convert a 3 channel image to greyscale using equal weightings:
316
317 $new = $img->convert(matrix=>[ [ 0.333, 0.333, 0.334 ] ])
318
319
320=head2 Color Mappings
321
322You can use the map method to map the values of each channel of an
323image independently using a list of lookup tables. It's important to
324realize that the modification is made inplace. The function simply
325returns the input image again or undef on failure.
326
327Each channel is mapped independently through a lookup table with 256
328entries. The elements in the table should not be less than 0 and not
329greater than 255. If they are out of the 0..255 range they are
330clamped to the range. If a table does not contain 256 entries it is
331silently ignored.
332
333Single channels can mapped by specifying their name and the mapping
334table. The channel names are C<red>, C<green>, C<blue>, C<alpha>.
335
336 @map = map { int( $_/2 } 0..255;
337 $img->map( red=>\@map );
338
339It is also possible to specify a single map that is applied to all
340channels, alpha channel included. For example this applies a gamma
341correction with a gamma of 1.4 to the input image.
342
343 $gamma = 1.4;
344 @map = map { int( 0.5 + 255*($_/255)**$gamma ) } 0..255;
345 $img->map(all=> \@map);
346
347The C<all> map is used as a default channel, if no other map is
348specified for a channel then the C<all> map is used instead. If we
349had not wanted to apply gamma to the alpha channel we would have used:
350
351 $img->map(all=> \@map, alpha=>[]);
352
353Since C<[]> contains fewer than 256 element the gamma channel is
354unaffected.
355
356It is also possible to simply specify an array of maps that are
357applied to the images in the rgba order. For example to apply
358maps to the C<red> and C<blue> channels one would use:
8435f780 359
3e1be2c1 360 $img->map(maps=>[\@redmap, [], \@bluemap]);
8435f780
AMH
361
362
363
364
365