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