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() and
74       compose().  If the original is to be left intact it's possible to make
75       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 useful
85           if you want to keep an original after doing something that changes
86           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       trim()
438           Returns a cropped version of the original image cropped of border
439           pixels based on either transparent pixels, or pixels that match any
440           of a set of provided colors.
441
442           If you just want the number of pixels to be cropped on each side
443           you can use the "trim_rect()" method.
444
445           If the supplied parameters would result in the entire image is
446           cropped, then a single pixel image is returned from the top left of
447           the source image.
448
449           To trim just on fully transparent pixels:
450
451              my $trimmed = $img->trim();
452
453           To trim pixels with less than 1% coverage:
454
455              my $trimmed = $img->trim(alpha => 0.01);
456
457           To trim based on automatically determined colors and fully
458           transparent pixels:
459
460              my $trimmed = $img->trim(auto => 1);
461
462           To trim a black border:
463
464             my $trimmed = $img->trim(colors => [ "#000" ]);
465
466           Parameters:
467
468           •   "alpha" - any pixels with less than or equal coverage to this
469               value will be treated as part of the border to be cropped.
470               This is always expressed as a fraction, so "alpha =" 1.0> will
471               treat all pixels as part of the border.  Default: 0 (fully
472               transparent pixels are part of the border).
473
474           •   "auto" - automatically select colors to crop on.  Possible
475               values:
476
477               •   1 - a "best" mechanism is selected, this is currently the
478                   "center" method, but it subject to change.
479
480               •   "center", "centre" - the pixels at the center of each side
481                   of the image are used.
482
483           •   "tolerance" - used by the "auto" mechanism to control the range
484               of pixel colors to be accepted as part of the border.  Default:
485               0.01.
486
487           •   "colors" - either a Imager::TrimColorList object or a reference
488               to an array of color entries to be considered part of the
489               border.  Code like:
490
491                   my $trimmed = $img->trim(colors => [ LIST ]);
492
493               results in a temporary Imager::TrimColorList being produced
494               like:
495
496                   my $trimmed = $img->trim(colors => Imager::TrimColorList->new( LIST ));
497
498           "colors" and "auto" exclude each other, only one or the other can
499           be supplied.
500
501       trim_rect()
502           Returns a list of the number of columns and rows of that would be
503           removed from each side if trim() was called.
504
505              my ($left, $top, $right, $bottom) = $img->trim_rect();
506
507           If the entire image matches the trim parameters then $left will be
508           the width of the image and $top will be the height of the image.
509
510           Accepts the same parameters as "trim()".
511
512   Image pasting/flipping
513       A list of the transformations that alter the source image follows:
514
515       paste()
516           To copy an image to onto another image use the paste() method.
517
518             $dest->paste(left=>40, top=>20, src=>$logo);
519
520           That copies the entire $logo image onto the $dest image so that the
521           upper left corner of the $logo image is at (40,20).
522
523           Parameters:
524
525           •   "src", "img" - the source image.  "src" added for compatibility
526               with rubthrough().
527
528           •   "left", "top" - position in output of the top left of the
529               pasted image.  Default: (0,0)
530
531           •   "src_minx", "src_miny" - the top left corner in the source
532               image to start the paste from.  Default: (0, 0)
533
534           •   "src_maxx", "src_maxy" - the bottom right in the source image
535               of the sub image to paste.  This position is non inclusive.
536               Default: bottom right corner of the source image.
537
538           •   "width", "height" - if the corresponding src_maxx or src_maxy
539               is not defined then width or height is used for the width or
540               height of the sub image to be pasted.
541
542             # copy the 20x20 pixel image from (20,20) in $src_image to (10,10) in $img
543             $img->paste(src=>$src_image,
544                         left => 10, top => 10,
545                         src_minx => 20, src_miny => 20,
546                         src_maxx => 40, src_maxx => 40);
547
548           If the source image has an alpha channel and the target doesn't,
549           then the source is treated as if composed onto a black background.
550
551           If the source image is color and the target is gray scale, the
552           source is treated as if run through convert(preset=>'gray').
553
554       rubthrough()
555           A more complicated way of blending images is where one image is put
556           'over' the other with a certain amount of opaqueness.  The method
557           that does this is rubthrough().
558
559             $img->rubthrough(src=>$overlay,
560                              tx=>30,       ty=>50,
561                              src_minx=>20, src_miny=>30,
562                              src_maxx=>20, src_maxy=>30);
563
564           That will take the sub image defined by $overlay and
565           [src_minx,src_maxx)[src_miny,src_maxy) and overlay it on top of
566           $img with the upper left corner at (30,50).  You can rub 2 or 4
567           channel images onto a 3 channel image, or a 2 channel image onto a
568           1 channel image.  The last channel is used as an alpha channel.  To
569           add an alpha channel to an image see convert().
570
571           Parameters:
572
573           •   "tx", "ty" - location in the target image ($self) to render the
574               top left corner of the source.
575
576           •   "src_minx", "src_miny" - the top left corner in the source to
577               transfer to the target image.  Default: (0, 0).
578
579           •   "src_maxx", "src_maxy" - the bottom right in the source image
580               of the sub image to overlay.  This position is non inclusive.
581               Default: bottom right corner of the source image.
582
583             # overlay all of $source onto $targ
584             $targ->rubthrough(tx => 20, ty => 25, src => $source);
585
586             # overlay the top left corner of $source onto $targ
587             $targ->rubthrough(tx => 20, ty => 25, src => $source,
588                               src_maxx => 20, src_maxy => 20);
589
590             # overlay the bottom right corner of $source onto $targ
591             $targ->rubthrough(tx => 20, ty => 30, src => $src,
592                               src_minx => $src->getwidth() - 20,
593                               src_miny => $src->getheight() - 20);
594
595           rubthrough() returns true on success.  On failure check
596           "$target->errstr" for the reason for failure.
597
598       compose()
599           Draws the source image over the target image, with the source alpha
600           channel modified by the optional mask and the opacity.
601
602             $img->compose(src=>$overlay,
603                           tx=>30,       ty=>50,
604                           src_minx=>20, src_miny=>30,
605                           src_maxx=>20, src_maxy=>30,
606                           mask => $mask, opacity => 0.5);
607
608           That will take the sub image defined by $overlay and
609           [src_minx,src_maxx)[src_miny,src_maxy) and overlay it on top of
610           $img with the upper left corner at (30,50).  You can rub 2 or 4
611           channel images onto a 3 channel image, or a 2 channel image onto a
612           1 channel image.
613
614           Parameters:
615
616           •   "src" - the source image to draw onto the target.  Required.
617
618           •   "tx", "ty" - location in the target image ($self) to render the
619               top left corner of the source.  These can also be supplied as
620               "left" and "right".  Default: (0, 0).
621
622           •   "src_minx", "src_miny" - the top left corner in the source to
623               transfer to the target image.  Default: (0, 0).
624
625           •   "src_maxx", "src_maxy" - the bottom right in the source image
626               of the sub image to overlay.  This position is non inclusive.
627               Default: bottom right corner of the source image.
628
629           •   "mask" - a mask image.  The first channel of this image is used
630               to modify the alpha channel of the source image.  This can be
631               used to mask out portions of the source image.  Where the first
632               channel is zero none of the source image will be used, where
633               the first channel is maximum the full alpha of the source image
634               will be used, as further modified by the opacity.
635
636           •   opacity - further modifies the alpha channel of the source
637               image, in the range 0.0 to 1.0.  Default: 1.0.
638
639           •   combine - the method to combine the source pixels with the
640               target.  See the combine option documentation in Imager::Fill.
641               Default: normal.
642
643           Calling compose() with no mask, combine set to "normal", opacity
644           set to 1.0 is equivalent to calling rubthrough().
645
646           compose() is intended to be produce similar effects to layers in
647           interactive paint software.
648
649             # overlay all of $source onto $targ
650             $targ->compose(tx => 20, ty => 25, src => $source);
651
652             # overlay the top left corner of $source onto $targ
653             $targ->compose(tx => 20, ty => 25, src => $source,
654                               src_maxx => 20, src_maxy => 20);
655
656             # overlay the bottom right corner of $source onto $targ
657             $targ->compose(tx => 20, ty => 30, src => $src,
658                               src_minx => $src->getwidth() - 20,
659                               src_miny => $src->getheight() - 20);
660
661           compose() returns true on success.  On failure check
662           $target->errstr for the reason for failure.
663
664       flip()
665           An inplace horizontal or vertical flip is possible by calling the
666           flip() method.  If the original is to be preserved it's possible to
667           make a copy first.  The only parameter it takes is the "dir"
668           parameter which can take the values "h", "v", "vh" and "hv".
669
670             $img->flip(dir=>"h");       # horizontal flip
671             $img->flip(dir=>"vh");      # vertical and horizontal flip
672             $nimg = $img->copy->flip(dir=>"v"); # make a copy and flip it vertically
673
674           flip() returns true on success.  On failure check $img->errstr for
675           the reason for failure.
676
677   Color transformations
678       convert()
679           You can use the convert method to transform the color space of an
680           image using a matrix.  For ease of use some presets are provided.
681
682           The convert method can be used to:
683
684           •   convert an RGB or RGBA image to gray scale.
685
686           •   convert a gray scale image to RGB.
687
688           •   extract a single channel from an image.
689
690           •   set a given channel to a particular value (or from another
691               channel)
692
693           The currently defined presets are:
694
695           •   "gray", "grey" - converts an RGBA image into a gray scale image
696               with alpha channel, or an RGB image into a gray scale image
697               without an alpha channel.
698
699               This weights the RGB channels at 22.2%, 70.7% and 7.1%
700               respectively.
701
702           •   "noalpha" - removes the alpha channel from a 2 or 4 channel
703               image.  An identity for other images.  Warning: this removes
704               the alpha channel without applying it.
705
706           •   "red", "channel0" - extracts the first channel of the image
707               into a single channel image
708
709           •   "green", "channel1" - extracts the second channel of the image
710               into a single channel image
711
712           •   "blue", "channel2" - extracts the third channel of the image
713               into a single channel image
714
715           •   "alpha" - extracts the alpha channel of the image into a single
716               channel image.
717
718               If the image has 1 or 3 channels (assumed to be gray scale or
719               RGB) then the resulting image will be all white.
720
721           •   "rgb"
722
723               converts a gray scale image to RGB, preserving the alpha
724               channel if any
725
726           •   "addalpha" - adds an alpha channel to a gray scale or RGB
727               image.  Preserves an existing alpha channel for a 2 or 4
728               channel image.
729
730           For example, to convert an RGB image into a gray scale image:
731
732             $new = $img->convert(preset=>'grey'); # or gray
733
734           or to convert a gray scale image to an RGB image:
735
736             $new = $img->convert(preset=>'rgb');
737
738           The presets aren't necessary simple constants in the code, some are
739           generated based on the number of channels in the input image.
740
741           If you want to perform some other color transformation, you can use
742           the 'matrix' parameter.
743
744           For each output pixel the following matrix multiplication is done:
745
746             | channel[0] |   | $c00, ...,  $c0k |   | inchannel[0] |
747             |    ...     | = |       ...        | x |     ...      |
748             | channel[k] |   | $ck0, ...,  $ckk |   | inchannel[k] |
749                                                                     1
750           Where C<k = $img-E<gt>getchannels()-1>.
751
752           So if you want to swap the red and green channels on a 3 channel
753           image:
754
755             $new = $img->convert(matrix=>[ [ 0, 1, 0 ],
756                                            [ 1, 0, 0 ],
757                                            [ 0, 0, 1 ] ]);
758
759           or to convert a 3 channel image to gray scale using equal
760           weightings:
761
762             $new = $img->convert(matrix=>[ [ 0.333, 0.333, 0.334 ] ])
763
764           Convert a 2 channel image (gray scale with alpha) to an RGBA image
765           with the gray converted to the specified RGB color:
766
767             # set (RGB) scaled on the grey scale portion and copy the alpha
768             # channel as is
769             my $colored = $gray->convert(matrix=>[ [ ($red/255),   0 ],
770                                                    [ ($green/255), 0 ],
771                                                    [ ($blue/255),  0 ],
772                                                    [ 0,            1 ],
773                                                  ]);
774
775           To convert a 3 channel image to a 4 channel image with a 50 percent
776           alpha channel:
777
778             my $withalpha = $rgb->convert(matrix =>[ [ 1, 0, 0, 0 ],
779                                                      [ 0, 1, 0, 0 ],
780                                                      [ 0, 0, 1, 0 ],
781                                                      [ 0, 0, 0, 0.5 ],
782                                                    ]);
783
784       combine()
785           Combine channels from one or more input images into a new image.
786
787           Parameters:
788
789           •   "src" - a reference to an array of input images.  There must be
790               at least one input image.  A given image may appear more than
791               once in "src".
792
793           •   "channels" - a reference to an array of channels corresponding
794               to the source images.  If "channels" is not supplied then the
795               first channel from each input image is used.  If the array
796               referenced by "channels" is shorter than that referenced by
797               "src" then the first channel is used from the extra images.
798
799             # make an rgb image from red, green, and blue images
800             my $rgb = Imager->combine(src => [ $red, $green, $blue ]);
801
802             # convert a BGR image into RGB
803             my $rgb = Imager->combine(src => [ $bgr, $bgr, $bgr ],
804                                       channels => [ 2, 1, 0 ]);
805
806             # add an alpha channel from another image
807             my $rgba = Imager->combine(src => [ $rgb, $rgb, $rgb, $alpha ],
808                                channels => [ 0, 1, 2, 0 ]);
809
810   Color Mappings
811       map()
812           You can use the map method to map the values of each channel of an
813           image independently using a list of look-up tables.  It's important
814           to realize that the modification is made inplace.  The function
815           simply returns the input image again or undef on failure.
816
817           Each channel is mapped independently through a look-up table with
818           256 entries.  The elements in the table should not be less than 0
819           and not greater than 255.  If they are out of the 0..255 range they
820           are clamped to the range.  If a table does not contain 256 entries
821           it is silently ignored.
822
823           Single channels can mapped by specifying their name and the mapping
824           table.  The channel names are "red", "green", "blue", "alpha".
825
826             @map = map { int( $_/2 } 0..255;
827             $img->map( red=>\@map );
828
829           It is also possible to specify a single map that is applied to all
830           channels, alpha channel included.  For example this applies a gamma
831           correction with a gamma of 1.4 to the input image.
832
833             $gamma = 1.4;
834             @map = map { int( 0.5 + 255*($_/255)**$gamma ) } 0..255;
835             $img->map(all=> \@map);
836
837           The "all" map is used as a default channel, if no other map is
838           specified for a channel then the "all" map is used instead.  If we
839           had not wanted to apply gamma to the alpha channel we would have
840           used:
841
842             $img->map(all=> \@map, alpha=>[]);
843
844           Since "[]" contains fewer than 256 element the gamma channel is
845           unaffected.
846
847           It is also possible to simply specify an array of maps that are
848           applied to the images in the RGBA order.  For example to apply maps
849           to the "red" and "blue" channels one would use:
850
851             $img->map(maps=>[\@redmap, [], \@bluemap]);
852

SEE ALSO

854       Imager, Imager::Engines
855

AUTHOR

857       Tony Cook <tonyc@cpan.org>, Arnar M. Hrafnkelsson
858

REVISION

860       $Revision$
861
862
863
864perl v5.38.0                      2023-07-20        Imager::Transformations(3)
Impressum