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