1Imager::TransformationsU(s3e)r Contributed Perl DocumentaItmiaogner::Transformations(3)
2
3
4

NAME

6       Imager::Transformations - Simple transformations of one image into
7       another.
8

SYNOPSIS

10         use Imager;
11
12         $newimg = $img->copy();
13
14         $newimg = $img->scale(xpixels=>400, qtype => 'mixing');
15         $newimg = $img->scale(xpixels=>400, ypixels=>400);
16         $newimg = $img->scale(xpixels=>400, ypixels=>400, type=>'min');
17         $newimg = $img->scale(scalefactor=>0.25);
18
19         $newimg = $img->scaleX(pixels=>400);
20         $newimg = $img->scaleX(scalefactor=>0.25);
21         $newimg = $img->scaleY(pixels=>400);
22         $newimg = $img->scaleY(scalefactor=>0.25);
23
24         $newimg = $img->crop(left=>50, right=>100, top=>10, bottom=>100);
25         $newimg = $img->crop(left=>50, top=>10, width=>50, height=>90);
26
27         $dest->paste(left=>40,top=>20,img=>$logo);
28
29         $img->rubthrough(src=>$srcimage,tx=>30, ty=>50);
30         $img->rubthrough(src=>$srcimage,tx=>30, ty=>50,
31                          src_minx=>20, src_miny=>30,
32                          src_maxx=>20, src_maxy=>30);
33
34         $img->compose(src => $src, tx => 30, ty => 20, combine => 'color');
35         $img->compose(src => $src, tx => 30, ty => 20, combine => 'color');
36                       mask => $mask, opacity => 0.5);
37
38         $img->flip(dir=>"h");       # horizontal flip
39         $img->flip(dir=>"vh");      # vertical and horizontal flip
40         $newimg = $img->copy->flip(dir=>"v"); # make a copy and flip it vertically
41
42         my $rot20 = $img->rotate(degrees=>20);
43         my $rotpi4 = $img->rotate(radians=>3.14159265/4);
44
45
46         # Convert image to gray
47         $new = $img->convert(preset=>'grey');
48
49         # Swap red/green channel
50         $new = $img->convert(matrix=>[ [ 0, 1, 0 ],
51                                        [ 1, 0, 0 ],
52                                        [ 0, 0, 1 ] ]);
53
54         # build an image using channels from multiple input images
55         $new = $img->combine(src => [ $im1, $im2, $im3 ]);
56         $new = $img->combine(src => [ $im1, $im2, $im3 ],
57                              channels => [ 2, 1, 0 ]);
58
59         # limit the range of red channel from 0..255 to 0..127
60         @map = map { int( $_/2 } 0..255;
61         $img->map( red=>\@map );
62
63         # Apply a Gamma of 1.4
64         my $gamma = 1.4;
65         my @map = map { int( 0.5 + 255*($_/255)**$gamma ) } 0..255;
66         $img->map(all=>\@map);  # inplace conversion
67

DESCRIPTION

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

SEE ALSO

779       Imager, Imager::Engines
780

AUTHOR

782       Tony Cook <tonyc@cpan.org>, Arnar M. Hrafnkelsson
783

REVISION

785       $Revision$
786
787
788
789perl v5.32.0                      2020-07-28        Imager::Transformations(3)
Impressum