c7313aa9b6da4301364b902139cf442428ace305
[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, qtype => 'mixing');
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   $img->compose(src => $src, tx => 30, ty => 20, combine => 'color');
32   $img->compose(src => $src, tx => 30, ty => 20, combine => 'color');
33                 mask => $mask, opacity => 0.5);
34
35   $img->flip(dir=>"h");       # horizontal flip
36   $img->flip(dir=>"vh");      # vertical and horizontal flip
37   $newimg = $img->copy->flip(dir=>"v"); # make a copy and flip it vertically
38
39   my $rot20 = $img->rotate(degrees=>20);
40   my $rotpi4 = $img->rotate(radians=>3.14159265/4);
41
42
43   # Convert image to gray
44   $new = $img->convert(preset=>'grey');          
45
46   # Swap red/green channel  
47   $new = $img->convert(matrix=>[ [ 0, 1, 0 ],
48                                  [ 1, 0, 0 ],
49                                  [ 0, 0, 1 ] ]);
50
51   # limit the range of red channel from 0..255 to 0..127
52   @map = map { int( $_/2 } 0..255;
53   $img->map( red=>\@map );
54
55   # Apply a Gamma of 1.4
56   my $gamma = 1.4;
57   my @map = map { int( 0.5 + 255*($_/255)**$gamma ) } 0..255;
58   $img->map(all=>\@map);  # inplace conversion
59
60 =head1 DESCRIPTION
61
62 The methods described in Imager::Transformations fall into two categories.
63 Either they take an existing image and modify it in place, or they 
64 return a modified copy.
65
66 Functions that modify inplace are C<flip()>, C<paste()>,
67 C<rubthrough()> and C<compose()>.  If the original is to be left
68 intact it's possible to make a copy and alter the copy:
69
70   $flipped = $img->copy()->flip(dir=>'h');
71
72 =head2 Image copying/resizing/cropping/rotating
73
74 A list of the transformations that do not alter the source image follows:
75
76 =over
77
78 =item copy
79
80 To create a copy of an image use the C<copy()> method.  This is useful
81 if you want to keep an original after doing something that changes the image.
82
83   $newimg = $orig->copy();
84
85 =item scale
86
87 X<scale>To scale an image so porportions are maintained use the
88 C<$img-E<gt>scale()> method.  if you give either a xpixels or ypixels
89 parameter they will determine the width or height respectively.  If
90 both are given the one resulting in a larger image is used, unless you
91 set the C<type> parameter to C<'min'>.  example: C<$img> is 700 pixels
92 wide and 500 pixels tall.
93
94   $newimg = $img->scale(xpixels=>400); # 400x285
95   $newimg = $img->scale(ypixels=>400); # 560x400
96
97   $newimg = $img->scale(xpixels=>400,ypixels=>400); # 560x400
98   $newimg = $img->scale(xpixels=>400,ypixels=>400,type=>'min'); # 400x285
99
100   $newimg = $img->scale(xpixels=>400, ypixels=>400),type=>'nonprop'); # 400x400
101
102   $newimg = $img->scale(scalefactor=>0.25); 175x125 
103   $newimg = $img->scale(); # 350x250
104
105 If you want to create low quality previews of images you can pass
106 C<qtype=E<gt>'preview'> to scale and it will use nearest neighbor
107 sampling instead of filtering. It is much faster but also generates
108 worse looking images - especially if the original has a lot of sharp
109 variations and the scaled image is by more than 3-5 times smaller than
110 the original.
111
112 =over
113
114 =item *
115
116 xpixels, ypixels - desired size of the scaled image.  The C<type>
117 parameter controls whether the larger or smaller of the two possible
118 sizes is chosen, or if the image is scaled non-proportionally.
119
120 =item *
121
122 constrain - an Image::Math::Constrain object defining the way in which
123 the image size should be constrained.
124
125 =item *
126
127 scalefactor - if none of xpixels, ypixels, xscalefactor, yscalefactor
128 or constrain is supplied then this is used as the ratio to scale by.
129 Default: 0.5.
130
131 =item *
132
133 xscalefactor, yscalefactor - if both are supplied then the image is
134 scaled as per these parameters, whether this is proportionally or not.
135 New in Imager 0.54.
136
137 =item *
138
139 type - controls whether the larger or smaller of the two possible
140 sizes is chosen, possible values are:
141
142 =over
143
144 =item *
145
146 min - the smaller of the 2 sizes are chosen.
147
148 =item *
149
150 max - the larger of the 2 sizes.  This is the default.
151
152 =item *
153
154 nonprop - non-proportional scaling.  New in Imager 0.54.
155
156 =back
157
158 scale() will fail if C<type> is set to some other value.
159
160 For example, if the original image is 400 pixels wide by 200 pixels
161 high and C<xpixels> is set to 300, and C<ypixels> is set to 160.  When
162 C<type> is C<'min'> the resulting image is 300 x 150, when C<type> is
163 C<'max'> the resulting image is 320 x 150.
164
165 C<type> is only used if both C<xpixels> and C<ypixels> are supplied.
166
167 =item *
168
169 qtype - defines the quality of scaling performed.  Possible values are:
170
171 =over
172
173 =item *
174
175 C<normal> - high quality scaling.  This is the default.
176
177 =item *
178
179 C<preview> - lower quality.  When scaling down this will skip input
180 pixels, eg. scaling by 0.5 will skip every other pixel.  When scaling
181 up this will duplicate pixels.
182
183 =item *
184
185 C<mixing> - implements the mixing algorithm implemented by pnmscale.
186 This retains more detail when scaling down than C<normal>.  When
187 scaling down this proportionally accumulates sample data from the
188 pixels, resulting in a proportional mix of all of the pixels.  When
189 scaling up this will mix pixels when the sampling grid crosses a pixel
190 boundary but will otherwise copy pixel values.
191
192 =back
193
194 scale() will fail if C<qtype> is set to some other value.
195
196 C<preview> is faster than C<mixing> which is much faster than C<normal>.
197
198 =back
199
200 To scale an image on a given axis without maintaining proportions, it
201 is best to call the scaleX() and scaleY() methods with the required
202 dimensions. eg.
203
204   my $scaled = $img->scaleX(pixels=>400)->scaleY(pixels=>200);
205
206 From Imager 0.54 you can scale without maintaining proportions either
207 by supplying both the xscalefactor and yscalefactor arguments:
208
209   my $scaled = $img->scale(xscalefactor => 0.5, yscalefactor => 0.67);
210
211 or by supplying C<xpixels> and C<ypixels> and setting C<type> to
212 "nonprop":
213
214   my $scaled = $im->scale(xpixels => 200, ypixels => 200, type => 'nonprop');
215
216 Returns a new scaled image on success.  The source image is not
217 modified.
218
219 Returns false on failure, check the errstr() method for the reason for
220 failure.
221
222 A mandatory warning is produced if scale() is called in void context.
223
224   # setup
225   my $image = Imager->new;
226   $image->read(file => 'somefile.jpg')
227     or die $image->errstr;
228
229   # all full quality unless indicated otherwise
230   # half the size:
231   my $half = $image->scale;
232
233   # double the size
234   my $double = $image->scale(scalefactor => 2.0);
235
236   # so a 400 x 400 box fits in the resulting image:
237   my $fit400x400inside = $image->scale(xpixels => 400, ypixels => 400);
238   my $fit400x400inside2 = $image->scale(xpixels => 400, ypixels => 400,
239                                         type=>'max');
240
241   # fit inside a 400 x 400 box
242   my $inside400x400 = $image->scale(xpixels => 400, ypixels => 400,
243                               type=>'min');
244
245   # make it 400 pixels wide or high
246   my $width400 = $image->scale(xpixels => 400);
247   my $height400 = $image->scale(ypixels => 400);
248
249   # low quality scales:
250   # to half size
251   my $low = $image->scale(qtype => 'preview');
252
253   # mixing method scale
254   my $mixed = $image->scale(qtype => 'mixing', scalefactor => 0.1);
255
256   # using an Image::Math::Constrain object
257   use Image::Math::Constrain;
258   my $constrain = Image::Math::Constrain->new(800, 600);
259   my $scaled = $image->scale(constrain => $constrain);
260
261   # same as Image::Math::Constrain version
262   my $scaled2 = $image->scale(xpixels => 800, ypixels => 600, type => 'min');
263
264 =item scaleX
265
266 scaleX() will scale along the X dimension, return a new image with the
267 new width:
268
269   my $newimg = $img->scaleX(pixels=>400); # 400x500
270   $newimg = $img->scaleX(scalefactor=>0.25) # 175x500
271
272 =over
273
274 =item *
275
276 scalefactor - the amount to scale the X axis.  Ignored if C<pixels> is
277 provided.  Default: 0.5.
278
279 =item *
280
281 pixels - the new width of the image.
282
283 =back
284
285 Returns a new scaled image on success.  The source image is not
286 modified.
287
288 Returns false on failure, check the errstr() method for the reason for
289 failure.
290
291 A mandatory warning is produced if scaleX() is called in void context.
292
293 =item scaleY
294
295 scaleY() will scale along the Y dimension, return a new image with the
296 new height:
297
298   $newimg = $img->scaleY(pixels=>400); # 700x400
299   $newimg = $img->scaleY(scalefactor=>0.25) # 700x125
300
301 =over
302
303 =item *
304
305 scalefactor - the amount to scale the Y axis.  Ignored if C<pixels> is
306 provided.  Default: 0.5.
307
308 =item *
309
310 pixels - the new height of the image.
311
312 =back
313
314 Returns a new scaled image on success.  The source image is not
315 modified.
316
317 Returns false on failure, check the errstr() method for the reason for
318 failure.
319
320 A mandatory warning is produced if scaleY() is called in void context.
321
322 =item scale_calculate
323
324 Performs the same calculations that the scale() method does to
325 calculate the scaling factors from the parameters you pass.
326
327 scale_calculate() can be called as an object method, or as a class
328 method.
329
330 Takes the following parameters over scale():
331
332 =over
333
334 =item *
335
336 width, height - the image width and height to base the scaling on.
337 Required if scale_calculate() is called as a class method.  If called
338 as an object method these default to the image width and height
339 respectively.
340
341 =back
342
343 You might use scale_calculate() as a class method when generating an
344 IMG tag, for example.
345
346 Returns an empty list on failure.
347
348 Returns a list containing horizontal scale factor, vertical scale
349 factor, new width, new height, on success.
350
351   my ($x_scale, $y_scale, $new_width, $new_height) =
352         Imager->scale_calculate(width => 1024, height => 768,
353                                 ypixels => 180, type => 'min');
354
355   my ($x_scale, $y_scale, $new_width, $new_height) =
356         $img->scale_calculate(xpixels => 200, type => 'min');
357
358 =item crop
359
360 Another way to resize an image is to crop it.  The parameters to
361 crop are the edges of the area that you want in the returned image,
362 where the right and bottom edges are non-inclusive.  If a parameter is
363 omitted a default is used instead.
364
365 crop() returns the cropped image and does not modify the source image.
366
367 The possible parameters are:
368
369 =over
370
371 =item *
372
373 C<left> - the left edge of the area to be cropped.  Default: 0
374
375 =item *
376
377 C<top> - the top edge of the area to be cropped.  Default: 0
378
379 =item *
380
381 C<right> - the right edge of the area to be cropped.  Default: right
382 edge of image.
383
384 =item *
385
386 C<bottom> - the bottom edge of the area to be cropped.  Default:
387 bottom edge of image.
388
389 =item *
390
391 C<width> - width of the crop area.  Ignored if both C<left> and C<right> are
392 supplied.  Centered on the image if neither C<left> nor C<right> are
393 supplied.
394
395 =item *
396
397 C<height> - height of the crop area.  Ignored if both C<top> and
398 C<bottom> are supplied.  Centered on the image if neither C<top> nor
399 C<bottom> are supplied.
400
401 =back
402
403 For example:
404
405   # these produce the same image
406   $newimg = $img->crop(left=>50, right=>100, top=>10, bottom=>100); 
407   $newimg = $img->crop(left=>50, top=>10, width=>50, height=>90);
408   $newimg = $img->crop(right=>100, bottom=>100, width=>50, height=>90);
409
410   # and the following produce the same image
411   $newimg = $img->crop(left=>50, right=>100);
412   $newimg = $img->crop(left=>50, right=>100, top=>0, 
413                        bottom=>$img->getheight);
414
415   # grab the top left corner of the image
416   $newimg = $img->crop(right=>50, bottom=>50);
417
418 You can also specify width and height parameters which will produce a
419 new image cropped from the center of the input image, with the given
420 width and height.
421
422   $newimg = $img->crop(width=>50, height=>50);
423
424 If you supply C<left>, C<width> and C<right> values, the C<right>
425 value will be ignored.  If you supply C<top>, C<height> and C<bottom>
426 values, the C<bottom> value will be ignored.
427
428 The edges of the cropped area default to the edges of the source
429 image, for example:
430
431   # a vertical bar from the middle from top to bottom
432   $newimg = $img->crop(width=>50);
433
434   # the right half
435   $newimg = $img->crop(left=>$img->getwidth() / 2);
436
437 If the resulting image would have zero width or height then crop()
438 returns false and $img->errstr is an appropriate error message.
439
440 A mandatory warning is produced if crop() is called in void context.
441
442 =item rotate
443
444 Use the rotate() method to rotate an image.  This method will return a
445 new, rotated image.
446
447 To rotate by an exact amount in degrees or radians, use the 'degrees'
448 or 'radians' parameter:
449
450   my $rot20 = $img->rotate(degrees=>20);
451   my $rotpi4 = $img->rotate(radians=>3.14159265/4);
452
453 Exact image rotation uses the same underlying transformation engine as
454 the matrix_transform() method (see Imager::Engines).
455
456 You can also supply a C<back> argument which acts as a background
457 color for the areas of the image with no samples available (outside
458 the rectangle of the source image.)  This can be either an
459 Imager::Color or Imager::Color::Float object.  This is B<not> mixed
460 transparent pixels in the middle of the source image, it is B<only>
461 used for pixels where there is no corresponding pixel in the source
462 image.
463
464 To rotate in steps of 90 degrees, use the 'right' parameter:
465
466   my $rotated = $img->rotate(right=>270);
467
468 Rotations are clockwise for positive values.
469
470 Parameters:
471
472 =over
473
474 =item *
475
476 right - rotate by an exact multiple of 90 degrees, specified in
477 degreess.
478
479 =item *
480
481 radians - rotate by an angle specified in radians.
482
483 =item *
484
485 degrees - rotate by an angle specified in degrees.
486
487 =item *
488
489 back - for C<radians> and C<degrees> this is the color used for the
490 areas not covered by the original image.  For example, the corners of
491 an image rotated by 45 degrees.
492
493 This can be either an Imager::Color object, an Imager::Color::Float
494 object or any parameter that Imager can convert to a color object, see
495 L<Imager::Draw/Color Parameters> for details.
496
497 This is B<not> mixed transparent pixels in the middle of the source
498 image, it is B<only> used for pixels where there is no corresponding
499 pixel in the source image.
500
501 Default: transparent black.
502
503 =back
504
505   # rotate 45 degrees clockwise, 
506   my $rotated = $img->rotate(degrees => 45);
507
508   # rotate 10 degrees counter-clockwise
509   # set pixels not sourced from the original to red
510   my $rotated = $img->rotate(degrees => -10, back => 'red');
511
512 =back
513
514 =head2 Image pasting/flipping
515
516 A list of the transformations that alter the source image follows:
517
518 =over
519
520 =item paste
521
522 X<paste>To copy an image to onto another image use the C<paste()>
523 method.
524
525   $dest->paste(left=>40, top=>20, src=>$logo);
526
527 That copies the entire C<$logo> image onto the C<$dest> image so that the
528 upper left corner of the C<$logo> image is at (40,20).
529
530 Parameters:
531
532 =over
533
534 =item *
535
536 src, img - the source image.  I<src> added for compatibility with
537 rubthrough().
538
539 =item *
540
541 left, top - position in output of the top left of the pasted image.
542 Default: (0,0)
543
544 =item *
545
546 src_minx, src_miny - the top left corner in the source image to start
547 the paste from.  Default: (0, 0)
548
549 =item *
550
551 src_maxx, src_maxy - the bottom right in the source image of the sub
552 image to paste.  This position is B<non> inclusive.  Default: bottom
553 right corner of the source image.
554
555 =item *
556
557 width, height - if the corresponding src_maxx or src_maxy is not
558 defined then width or height is used for the width or height of the
559 sub image to be pasted.
560
561 =back
562
563   # copy the 20x20 pixel image from (20,20) in $src_image to (10,10) in $img
564   $img->paste(src=>$src_image,
565               left => 10, top => 10,
566               src_minx => 20, src_miny => 20,
567               src_maxx => 40, src_maxx => 40);
568
569 If the source image has an alpha channel and the target doesn't, then
570 the source is treated as if composed onto a black background.
571
572 If the source image is color and the target is grayscale, the the
573 source is treated as if run through C<< convert(preset=>'gray') >>.
574
575 =item rubthrough
576
577 A more complicated way of blending images is where one image is
578 put 'over' the other with a certain amount of opaqueness.  The
579 method that does this is rubthrough.
580
581   $img->rubthrough(src=>$overlay,
582                    tx=>30,       ty=>50,
583                    src_minx=>20, src_miny=>30,
584                    src_maxx=>20, src_maxy=>30);
585
586 That will take the sub image defined by I<$overlay> and
587 I<[src_minx,src_maxx)[src_miny,src_maxy)> and overlay it on top of
588 I<$img> with the upper left corner at (30,50).  You can rub 2 or 4
589 channel images onto a 3 channel image, or a 2 channel image onto a 1
590 channel image.  The last channel is used as an alpha channel.  To add
591 an alpha channel to an image see I<convert()>.
592
593 Parameters:
594
595 =over
596
597 =item *
598
599 tx, ty - location in the the target image ($self) to render the top
600 left corner of the source.
601
602 =item *
603
604 src_minx, src_miny - the top left corner in the source to transfer to
605 the target image.  Default: (0, 0).
606
607 =item *
608
609 src_maxx, src_maxy - the bottom right in the source image of the sub
610 image to overlay.  This position is B<non> inclusive.  Default: bottom
611 right corner of the source image.
612
613 =back
614
615   # overlay all of $source onto $targ
616   $targ->rubthrough(tx => 20, ty => 25, src => $source);
617
618   # overlay the top left corner of $source onto $targ
619   $targ->rubthrough(tx => 20, ty => 25, src => $source,
620                     src_maxx => 20, src_maxy => 20);
621
622   # overlay the bottom right corner of $source onto $targ
623   $targ->rubthrough(tx => 20, ty => 30, src => $src,
624                     src_minx => $src->getwidth() - 20,
625                     src_miny => $src->getheight() - 20);
626
627 rubthrough() returns true on success.  On failure check
628 $target->errstr for the reason for failure.
629
630 =item compose
631
632 Draws the source image over the target image, with the src alpha
633 channel modified by the optional mask and the opacity.
634
635   $img->compose(src=>$overlay,
636                 tx=>30,       ty=>50,
637                 src_minx=>20, src_miny=>30,
638                 src_maxx=>20, src_maxy=>30,
639                 mask => $mask, opacity => 0.5);
640
641 That will take the sub image defined by I<$overlay> and
642 I<[src_minx,src_maxx)[src_miny,src_maxy)> and overlay it on top of
643 I<$img> with the upper left corner at (30,50).  You can rub 2 or 4
644 channel images onto a 3 channel image, or a 2 channel image onto a 1
645 channel image.
646
647 Parameters:
648
649 =over
650
651 =item *
652
653 src - the source image to draw onto the target.  Required.
654
655 =item *
656
657 tx, ty - location in the the target image ($self) to render the top
658 left corner of the source.  These can also be supplied as C<left> and
659 C<right>.  Default: (0, 0).
660
661 =item *
662
663 src_minx, src_miny - the top left corner in the source to transfer to
664 the target image.  Default: (0, 0).
665
666 =item *
667
668 src_maxx, src_maxy - the bottom right in the source image of the sub
669 image to overlay.  This position is B<non> inclusive.  Default: bottom
670 right corner of the source image.
671
672 =item *
673
674 mask - a mask image.  The first channel of this image is used to
675 modify the alpha channel of the source image.  This can me used to
676 mask out portions of the source image.  Where the first channel is
677 zero none of the source image will be used, where the first channel is
678 max the full alpha of the source image will be used, as further
679 modified by the opacity.
680
681 =item *
682
683 opacity - further modifies the alpha channel of the source image, in
684 the range 0.0 to 1.0.  Default: 1.0.
685
686 =item *
687
688 combine - the method to combine the source pixels with the target.
689 See the combine option documentation in Imager::Fill.  Default:
690 normal.
691
692 =back
693
694 Calling compose() with no mask, combine set to C<normal>, opacity set
695 to C<1.0> is equivalent to calling rubthrough().
696
697 compose() is intended to be produce similar effects to layers in
698 interactive paint software.
699
700   # overlay all of $source onto $targ
701   $targ->compose(tx => 20, ty => 25, src => $source);
702
703   # overlay the top left corner of $source onto $targ
704   $targ->compose(tx => 20, ty => 25, src => $source,
705                     src_maxx => 20, src_maxy => 20);
706
707   # overlay the bottom right corner of $source onto $targ
708   $targ->compose(tx => 20, ty => 30, src => $src,
709                     src_minx => $src->getwidth() - 20,
710                     src_miny => $src->getheight() - 20);
711
712 compose() returns true on success.  On failure check $target->errstr
713 for the reason for failure.
714
715 =item flip
716
717 An inplace horizontal or vertical flip is possible by calling the
718 C<flip()> method.  If the original is to be preserved it's possible to
719 make a copy first.  The only parameter it takes is the C<dir>
720 parameter which can take the values C<h>, C<v>, C<vh> and C<hv>.
721
722   $img->flip(dir=>"h");       # horizontal flip
723   $img->flip(dir=>"vh");      # vertical and horizontal flip
724   $nimg = $img->copy->flip(dir=>"v"); # make a copy and flip it vertically
725
726 flip() returns true on success.  On failure check $img->errstr for the
727 reason for failure.
728
729 =back
730
731 =head2 Color transformations
732
733 =over
734
735 =item convert
736
737 You can use the convert method to transform the color space of an
738 image using a matrix.  For ease of use some presets are provided.
739
740 The convert method can be used to:
741
742 =over
743
744 =item *
745
746 convert an RGB or RGBA image to grayscale.
747
748 =item *
749
750 convert a grayscale image to RGB.
751
752 =item *
753
754 extract a single channel from an image.
755
756 =item *
757
758 set a given channel to a particular value (or from another channel)
759
760 =back
761
762 The currently defined presets are:
763
764 =over
765
766 =item gray
767
768 =item grey
769
770 converts an RGBA image into a grayscale image with alpha channel, or
771 an RGB image into a grayscale image without an alpha channel.
772
773 This weights the RGB channels at 22.2%, 70.7% and 7.1% respectively.
774
775 =item noalpha
776
777 removes the alpha channel from a 2 or 4 channel image.  An identity
778 for other images.
779
780 =item red
781
782 =item channel0
783
784 extracts the first channel of the image into a single channel image
785
786 =item green
787
788 =item channel1
789
790 extracts the second channel of the image into a single channel image
791
792 =item blue
793
794 =item channel2
795
796 extracts the third channel of the image into a single channel image
797
798 =item alpha
799
800 extracts the alpha channel of the image into a single channel image.
801
802 If the image has 1 or 3 channels (assumed to be grayscale of RGB) then
803 the resulting image will be all white.
804
805 =item rgb
806
807 converts a grayscale image to RGB, preserving the alpha channel if any
808
809 =item addalpha
810
811 adds an alpha channel to a grayscale or RGB image.  Preserves an
812 existing alpha channel for a 2 or 4 channel image.
813
814 =back
815
816 For example, to convert an RGB image into a greyscale image:
817
818   $new = $img->convert(preset=>'grey'); # or gray
819
820 or to convert a grayscale image to an RGB image:
821
822   $new = $img->convert(preset=>'rgb');
823
824 The presets aren't necessary simple constants in the code, some are
825 generated based on the number of channels in the input image.
826
827 If you want to perform some other colour transformation, you can use
828 the 'matrix' parameter.
829
830 For each output pixel the following matrix multiplication is done:
831
832   | channel[0] |   | $c00, ...,  $c0k |   | inchannel[0] |
833   |    ...     | = |       ...        | x |     ...      |
834   | channel[k] |   | $ck0, ...,  $ckk |   | inchannel[k] |
835                                                           1
836 Where C<k = $img-E<gt>getchannels()-1>.
837
838 So if you want to swap the red and green channels on a 3 channel image:
839
840   $new = $img->convert(matrix=>[ [ 0, 1, 0 ],
841                                  [ 1, 0, 0 ],
842                                  [ 0, 0, 1 ] ]);
843
844 or to convert a 3 channel image to greyscale using equal weightings:
845
846   $new = $img->convert(matrix=>[ [ 0.333, 0.333, 0.334 ] ])
847
848 Convert a 2 channel image (grayscale with alpha) to an RGBA image with
849 the grey converted to the specified RGB color:
850
851   # set (RGB) scaled on the grey scale portion and copy the alpha
852   # channel as is
853   my $colored = $gray->convert(matrix=>[ [ ($red/255),   0 ], 
854                                          [ ($green/255), 0 ], 
855                                          [ ($blue/255),  0 ], 
856                                          [ 0,            1 ],
857                                        ]);
858
859 To convert a 3 channel image to a 4 channel image with a 50 percent
860 alpha channel:
861
862   my $withalpha = $rgb->convert(matrix =>[ [ 1, 0, 0, 0 ],
863                                            [ 0, 1, 0, 0 ],
864                                            [ 0, 0, 1, 0 ],
865                                            [ 0, 0, 0, 0.5 ],
866                                          ]);
867
868 =back
869
870 =head2 Color Mappings
871
872 =over
873
874 =item map
875
876 You can use the map method to map the values of each channel of an
877 image independently using a list of lookup tables.  It's important to
878 realize that the modification is made inplace.  The function simply
879 returns the input image again or undef on failure.
880
881 Each channel is mapped independently through a lookup table with 256
882 entries.  The elements in the table should not be less than 0 and not
883 greater than 255.  If they are out of the 0..255 range they are
884 clamped to the range.  If a table does not contain 256 entries it is
885 silently ignored.
886
887 Single channels can mapped by specifying their name and the mapping
888 table.  The channel names are C<red>, C<green>, C<blue>, C<alpha>.
889
890   @map = map { int( $_/2 } 0..255;
891   $img->map( red=>\@map );
892
893 It is also possible to specify a single map that is applied to all
894 channels, alpha channel included.  For example this applies a gamma
895 correction with a gamma of 1.4 to the input image.
896
897   $gamma = 1.4;
898   @map = map { int( 0.5 + 255*($_/255)**$gamma ) } 0..255;
899   $img->map(all=> \@map);
900
901 The C<all> map is used as a default channel, if no other map is
902 specified for a channel then the C<all> map is used instead.  If we
903 had not wanted to apply gamma to the alpha channel we would have used:
904
905   $img->map(all=> \@map, alpha=>[]);
906
907 Since C<[]> contains fewer than 256 element the gamma channel is
908 unaffected.
909
910 It is also possible to simply specify an array of maps that are
911 applied to the images in the rgba order.  For example to apply
912 maps to the C<red> and C<blue> channels one would use:
913
914   $img->map(maps=>[\@redmap, [], \@bluemap]);
915
916 =back
917
918 =head1 SEE ALSO
919
920 L<Imager>, L<Imager::Engines>
921
922 =head1 AUTHOR
923
924 Tony Cook <tony@imager.perl.org>, Arnar M. Hrafnkelsson
925
926 =head1 REVISION
927
928 $Revision$
929
930 =cut