- start of external Imager API access:
[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->scaleX(pixels=>400);
17   $newimg = $img->scaleX(scalefactor=>0.25);
18   $newimg = $img->scaleY(pixels=>400);
19   $newimg = $img->scaleY(scalefactor=>0.25);
20
21   $newimg = $img->crop(left=>50, right=>100, top=>10, bottom=>100); 
22   $newimg = $img->crop(left=>50, top=>10, width=>50, height=>90);
23
24   $dest->paste(left=>40,top=>20,img=>$logo);
25
26   $img->rubthrough(src=>$srcimage,tx=>30, ty=>50);
27   $img->rubthrough(src=>$srcimage,tx=>30, ty=>50,
28                    src_minx=>20, src_miny=>30,
29                    src_maxx=>20, src_maxy=>30);
30
31
32   $img->flip(dir=>"h");       # horizontal flip
33   $img->flip(dir=>"vh");      # vertical and horizontal flip
34   $newimg = $img->copy->flip(dir=>"v"); # make a copy and flip it vertically
35
36   my $rot20 = $img->rotate(degrees=>20);
37   my $rotpi4 = $img->rotate(radians=>3.14159265/4);
38
39
40   # Convert image to gray
41   $new = $img->convert(preset=>'grey');          
42
43   # Swap red/green channel  
44   $new = $img->convert(matrix=>[ [ 0, 1, 0 ],
45                                  [ 1, 0, 0 ],
46                                  [ 0, 0, 1 ] ]);
47
48   # limit the range of red channel from 0..255 to 0..127
49   @map = map { int( $_/2 } 0..255;
50   $img->map( red=>\@map );
51
52   # Apply a Gamma of 1.4
53   my $gamma = 1.4;
54   my @map = map { int( 0.5 + 255*($_/255)**$gamma ) } 0..255;
55   $img->map(all=>\@map);  # inplace conversion
56
57 =head1 DESCRIPTION
58
59 The methods described in Imager::Transformations fall into two categories.
60 Either they take an existing image and modify it in place, or they 
61 return a modified copy.
62
63 Functions that modify inplace are C<flip()>, C<paste()> and
64 C<rubthrough()>.  If the original is to be left intact it's possible
65 to make a copy and alter the copy:
66
67   $flipped = $img->copy()->flip(dir=>'h');
68
69 =head2 Image copying/resizing/cropping/rotating
70
71 A list of the transformations that do not alter the source image follows:
72
73 =over
74
75 =item copy
76
77 To create a copy of an image use the C<copy()> method.  This is usefull
78 if you want to keep an original after doing something that changes the image.
79
80   $newimg = $orig->copy();
81
82 =item scale
83
84 To scale an image so porportions are maintained use the
85 C<$img-E<gt>scale()> method.  if you give either a xpixels or ypixels
86 parameter they will determine the width or height respectively.  If
87 both are given the one resulting in a larger image is used, unless you
88 set the C<type> parameter to C<'min'>.  example: C<$img> is 700 pixels
89 wide and 500 pixels tall.
90
91   $newimg = $img->scale(xpixels=>400); # 400x285
92   $newimg = $img->scale(ypixels=>400); # 560x400
93
94   $newimg = $img->scale(xpixels=>400,ypixels=>400); # 560x400
95   $newimg = $img->scale(xpixels=>400,ypixels=>400,type=>'min'); # 400x285
96
97   $newimg = $img->scale(scalefactor=>0.25); 175x125 
98   $newimg = $img->scale(); # 350x250
99
100 if you want to create low quality previews of images you can pass
101 C<qtype=E<gt>'preview'> to scale and it will use nearest neighbor
102 sampling instead of filtering. It is much faster but also generates
103 worse looking images - especially if the original has a lot of sharp
104 variations and the scaled image is by more than 3-5 times smaller than
105 the original.
106
107 =over
108
109 =item *
110
111 xpixels, ypixels - desired size of the scaled image.  The resulting
112 image is always scaled proportionally.  The C<type> parameter controls
113 whether the larger or smaller of the two possible sizes is chosen.
114
115 =item *
116
117 type - controls whether the larger or smaller of the two possible
118 sizes is chosen, possible values are:
119
120 =over
121
122 =item *
123
124 min - the smaller of the 2 sizes are chosen.
125
126 =item *
127
128 max - the larger of the 2 sizes.  This is the default.
129
130 =back
131
132 The behaviour when C<type> is set to some other value is undefined.
133
134 For example, if the original image is 400 pixels wide by 200 pixels
135 high and C<xpixels> is set to 300, and C<ypixels> is set to 160.  When
136 C<type> is C<'min'> the resulting image is 300 x 150, when C<type> is
137 C<'max'> the resulting image is 320 x 150.
138
139 C<type> is only used if both C<xpixels> and C<ypixels> are supplied.
140
141 =item *
142
143 qtype - defines the quality of scaling performed.  Possible values are:
144
145 =over
146
147 =item *
148
149 normal - high quality scaling.  This is the default.
150
151 =item *
152
153 preview - lower quality.
154
155 =back
156
157 =back
158
159 If you need to scale images per axis it is best to do it simply by
160 calling scaleX() or scaleY().  You can pass either 'scalefactor' or
161 'pixels' to both functions.
162
163 Returns the scaled image on success.
164
165 Returns false on failure, check the errstr() method for the reason for
166 failure.
167
168 =item scaleX
169
170 scaleX() will scale along the X dimension, changing the width of the
171 image:
172
173   $newimg = $img->scaleX(pixels=>400); # 400x500
174   $newimg = $img->scaleX(scalefactor=>0.25) # 175x500
175
176 =item scaleY
177
178 scaleY() will scale along the Y dimension, changing the height of the
179 image:
180
181   $newimg = $img->scaleY(pixels=>400); # 700x400
182   $newimg = $img->scaleY(scalefactor=>0.25) # 700x125
183
184 =item crop
185
186 Another way to resize an image is to crop it.  The parameters to
187 crop are the edges of the area that you want in the returned image,
188 where the right and bottom edges are non-inclusive.  If a parameter is
189 omitted a default is used instead.
190
191 The possible parameters are:
192
193 =over
194
195 =item *
196
197 C<left> - the left edge of the area to be cropped.  Default: 0
198
199 =item *
200
201 C<top> - the top edge of the area to be cropped.  Default: 0
202
203 =item *
204
205 C<right> - the right edge of the area to be cropped.  Default: right
206 edge of image.
207
208 =item *
209
210 C<bottom> - the bottom edge of the area to be cropped.  Default:
211 bottom edge of image.
212
213 =item *
214
215 C<width> - width of the crop area.  Ignored if both C<left> and C<right> are
216 supplied.  Centered on the image if neither C<left> nor C<right> are
217 supplied.
218
219 =item *
220
221 C<height> - height of the crop area.  Ignored if both C<top> and
222 C<bottom> are supplied.  Centered on the image if neither C<top> nor
223 C<bottom> are supplied.
224
225 =back
226
227 For example:
228
229   # these produce the same image
230   $newimg = $img->crop(left=>50, right=>100, top=>10, bottom=>100); 
231   $newimg = $img->crop(left=>50, top=>10, width=>50, height=>90);
232   $newimg = $img->crop(right=>100, bottom=>100, width=>50, height=>90);
233
234   # and the following produce the same image
235   $newimg = $img->crop(left=>50, right=>100);
236   $newimg = $img->crop(left=>50, right=>100, top=>0, 
237                        bottom=>$img->getheight);
238
239   # grab the top left corner of the image
240   $newimg = $img->crop(right=>50, bottom=>50);
241
242 You can also specify width and height parameters which will produce a
243 new image cropped from the center of the input image, with the given
244 width and height.
245
246   $newimg = $img->crop(width=>50, height=>50);
247
248 If you supply C<left>, C<width> and C<right> values, the C<right>
249 value will be ignored.  If you supply C<top>, C<height> and C<bottom>
250 values, the C<bottom> value will be ignored.
251
252 The edges of the cropped area default to the edges of the source
253 image, for example:
254
255   # a vertical bar from the middle from top to bottom
256   $newimg = $img->crop(width=>50);
257
258   # the right half
259   $newimg = $img->crop(left=>$img->getwidth() / 2);
260
261 If the resulting image would have zero width or height then crop()
262 returns false and $img->errstr is an appropriate error message.
263
264 =item rotate
265
266 Use the rotate() method to rotate an image.  This method will return a
267 new, rotated image.
268
269 To rotate by an exact amount in degrees or radians, use the 'degrees'
270 or 'radians' parameter:
271
272   my $rot20 = $img->rotate(degrees=>20);
273   my $rotpi4 = $img->rotate(radians=>3.14159265/4);
274
275 Exact image rotation uses the same underlying transformation engine as
276 the matrix_transform() method (see Imager::Engines).
277
278 You can also supply a C<back> argument which acts as a background
279 color for the areas of the image with no samples available (outside
280 the rectangle of the source image.)  This can be either an
281 Imager::Color or Imager::Color::Float object.  This is B<not> mixed
282 transparent pixels in the middle of the source image, it is B<only>
283 used for pixels where there is no corresponding pixel in the source
284 image.
285
286 To rotate in steps of 90 degrees, use the 'right' parameter:
287
288   my $rotated = $img->rotate(right=>270);
289
290 Rotations are clockwise for positive values.
291
292
293 =back
294
295
296 =head2 Image pasting/flipping/
297
298 A list of the transformations that alter the source image follows:
299
300 =over
301
302 =item paste
303
304 X<paste>To copy an image to onto another image use the C<paste()>
305 method.
306
307   $dest->paste(left=>40, top=>20, src=>$logo);
308
309 That copies the entire C<$logo> image onto the C<$dest> image so that the
310 upper left corner of the C<$logo> image is at (40,20).
311
312 Parameters:
313
314 =over
315
316 =item *
317
318 src, img - the source image.  I<src> added for compatibility with
319 rubthrough().
320
321 =item *
322
323 left, top - position in output of the top left of the pasted image.
324 Default: (0,0)
325
326 =item *
327
328 src_minx, src_miny - the top left corner in the source image to start
329 the paste from.  Default: (0, 0)
330
331 =item *
332
333 src_maxx, src_maxy - the bottom right in the source image of the sub
334 image to paste.  This position is B<non> inclusive.  Default: bottom
335 right corner of the source image.
336
337 =item *
338
339 width, height - if the corresponding src_maxx or src_maxy is not
340 defined then width or height is used for the width or height of the
341 sub image to be pasted.
342
343 =back
344
345   # copy the 20x20 pixel image from (20,20) in $src_image to (10,10) in $img
346   $img->paste(src=>$src_image,
347               left => 10, top => 10,
348               src_minx => 20, src_miny => 20,
349               src_maxx => 40, src_maxx => 40);
350               
351 =item rubthrough
352
353 A more complicated way of blending images is where one image is
354 put 'over' the other with a certain amount of opaqueness.  The
355 method that does this is rubthrough.
356
357   $img->rubthrough(src=>$overlay,
358                    tx=>30,       ty=>50,
359                    src_minx=>20, src_miny=>30,
360                    src_maxx=>20, src_maxy=>30);
361
362 That will take the sub image defined by I<$overlay> and
363 I<[src_minx,src_maxx)[src_miny,src_maxy)> and overlay it on top of
364 I<$img> with the upper left corner at (30,50).  You can rub 2 or 4
365 channel images onto a 3 channel image, or a 2 channel image onto a 1
366 channel image.  The last channel is used as an alpha channel.  To add
367 an alpha channel to an image see I<convert()>.
368
369
370 =item flip
371
372 An inplace horizontal or vertical flip is possible by calling the
373 C<flip()> method.  If the original is to be preserved it's possible to
374 make a copy first.  The only parameter it takes is the C<dir>
375 parameter which can take the values C<h>, C<v>, C<vh> and C<hv>.
376
377   $img->flip(dir=>"h");       # horizontal flip
378   $img->flip(dir=>"vh");      # vertical and horizontal flip
379   $nimg = $img->copy->flip(dir=>"v"); # make a copy and flip it vertically
380
381 =back
382
383
384
385
386 =head2 Color transformations
387
388 You can use the convert method to transform the color space of an
389 image using a matrix.  For ease of use some presets are provided.
390
391 The convert method can be used to:
392
393 =over
394
395 =item *
396
397 convert an RGB or RGBA image to grayscale.
398
399 =item *
400
401 convert a grayscale image to RGB.
402
403 =item *
404
405 extract a single channel from an image.
406
407 =item *
408
409 set a given channel to a particular value (or from another channel)
410
411 =back
412
413 The currently defined presets are:
414
415 =over
416
417 =item gray
418
419 =item grey
420
421 converts an RGBA image into a grayscale image with alpha channel, or
422 an RGB image into a grayscale image without an alpha channel.
423
424 This weights the RGB channels at 22.2%, 70.7% and 7.1% respectively.
425
426 =item noalpha
427
428 removes the alpha channel from a 2 or 4 channel image.  An identity
429 for other images.
430
431 =item red
432
433 =item channel0
434
435 extracts the first channel of the image into a single channel image
436
437 =item green
438
439 =item channel1
440
441 extracts the second channel of the image into a single channel image
442
443 =item blue
444
445 =item channel2
446
447 extracts the third channel of the image into a single channel image
448
449 =item alpha
450
451 extracts the alpha channel of the image into a single channel image.
452
453 If the image has 1 or 3 channels (assumed to be grayscale of RGB) then
454 the resulting image will be all white.
455
456 =item rgb
457
458 converts a grayscale image to RGB, preserving the alpha channel if any
459
460 =item addalpha
461
462 adds an alpha channel to a grayscale or RGB image.  Preserves an
463 existing alpha channel for a 2 or 4 channel image.
464
465 =back
466
467 For example, to convert an RGB image into a greyscale image:
468
469   $new = $img->convert(preset=>'grey'); # or gray
470
471 or to convert a grayscale image to an RGB image:
472
473   $new = $img->convert(preset=>'rgb');
474
475 The presets aren't necessary simple constants in the code, some are
476 generated based on the number of channels in the input image.
477
478 If you want to perform some other colour transformation, you can use
479 the 'matrix' parameter.
480
481 For each output pixel the following matrix multiplication is done:
482
483   | channel[0] |   | $c00, ...,  $c0k |   | inchannel[0] |
484   |    ...     | = |       ...        | x |     ...      |
485   | channel[k] |   | $ck0, ...,  $ckk |   | inchannel[k] |
486                                                           1
487 Where C<k = $img-E<gt>getchannels()-1>.
488
489 So if you want to swap the red and green channels on a 3 channel image:
490
491   $new = $img->convert(matrix=>[ [ 0, 1, 0 ],
492                                  [ 1, 0, 0 ],
493                                  [ 0, 0, 1 ] ]);
494
495 or to convert a 3 channel image to greyscale using equal weightings:
496
497   $new = $img->convert(matrix=>[ [ 0.333, 0.333, 0.334 ] ])
498
499 Convert a 2 channel image (grayscale with alpha) to an RGBA image with
500 the grey converted to the specified RGB color:
501
502   # set (RGB) scaled on the grey scale portion and copy the alpha
503   # channel as is
504   my $colored = $gray->convert(matrix=>[ [ ($red/255),   0 ], 
505                                          [ ($green/255), 0 ], 
506                                          [ ($blue/255),  0 ], 
507                                          [ 0,            1 ],
508                                        ]);
509
510 =head2 Color Mappings
511
512 You can use the map method to map the values of each channel of an
513 image independently using a list of lookup tables.  It's important to
514 realize that the modification is made inplace.  The function simply
515 returns the input image again or undef on failure.
516
517 Each channel is mapped independently through a lookup table with 256
518 entries.  The elements in the table should not be less than 0 and not
519 greater than 255.  If they are out of the 0..255 range they are
520 clamped to the range.  If a table does not contain 256 entries it is
521 silently ignored.
522
523 Single channels can mapped by specifying their name and the mapping
524 table.  The channel names are C<red>, C<green>, C<blue>, C<alpha>.
525
526   @map = map { int( $_/2 } 0..255;
527   $img->map( red=>\@map );
528
529 It is also possible to specify a single map that is applied to all
530 channels, alpha channel included.  For example this applies a gamma
531 correction with a gamma of 1.4 to the input image.
532
533   $gamma = 1.4;
534   @map = map { int( 0.5 + 255*($_/255)**$gamma ) } 0..255;
535   $img->map(all=> \@map);
536
537 The C<all> map is used as a default channel, if no other map is
538 specified for a channel then the C<all> map is used instead.  If we
539 had not wanted to apply gamma to the alpha channel we would have used:
540
541   $img->map(all=> \@map, alpha=>[]);
542
543 Since C<[]> contains fewer than 256 element the gamma channel is
544 unaffected.
545
546 It is also possible to simply specify an array of maps that are
547 applied to the images in the rgba order.  For example to apply
548 maps to the C<red> and C<blue> channels one would use:
549
550   $img->map(maps=>[\@redmap, [], \@bluemap]);
551
552 =cut