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