1Imager::TransformationsU(s3e)r Contributed Perl DocumentaItmiaogner::Transformations(3)
2
6 Imager::Transformations - Simple transformations of one image into
7 another.
8
10 use Imager;
11 $newimg = $img->copy();
13 $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 $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 $newimg = $img->crop(left=>50, right=>100, top=>10, bottom=>100);
25 $newimg = $img->crop(left=>50, top=>10, width=>50, height=>90);
26 $dest->paste(left=>40,top=>20,img=>$logo);
28 $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 $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 $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 my $rot20 = $img->rotate(degrees=>20);
43 my $rotpi4 = $img->rotate(radians=>3.14159265/4);
44 # Convert image to gray
47 $new = $img->convert(preset=>'grey');
48 # Swap red/green channel
50 $new = $img->convert(matrix=>[ [ 0, 1, 0 ],
51 [ 1, 0, 0 ],
52 [ 0, 0, 1 ] ]);
53 # 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 # 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 # 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
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 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 $flipped = $img->copy()->flip(dir=>'h');
78 Image copying/resizing/cropping/rotating
80 A list of the transformations that do not alter the source image
81 follows:
82 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 $newimg = $orig->copy();
89 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 $newimg = $img->scale(xpixels=>400); # 400x285
99 $newimg = $img->scale(ypixels=>400); # 560x400
100 $newimg = $img->scale(xpixels=>400,ypixels=>400); # 560x400
102 $newimg = $img->scale(xpixels=>400,ypixels=>400,type=>'min'); # 400x285
103 $newimg = $img->scale(xpixels=>400, ypixels=>400),type=>'nonprop'); # 400x400
105 $newimg = $img->scale(scalefactor=>0.25); 175x125
107 $newimg = $img->scale(); # 350x250
108 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 • "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 • "constrain" - an Image::Math::Constrain object defining the way
122 in which the image size should be constrained.
123 • "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 • "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 • "type" - controls whether the larger or smaller of the two
133 possible sizes is chosen, possible values are:
134 • "min" - the smaller of the 2 sizes are chosen.
136 • "max" - the larger of the 2 sizes. This is the default.
138 • "nonprop" - non-proportional scaling. New in Imager 0.54.
140 scale() will fail if "type" is set to some other value.
142 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 "type" is only used if both "xpixels" and "ypixels" are
149 supplied.
150 • "qtype" - defines the quality of scaling performed. Possible
152 values are:
153 • "normal" - high quality scaling. This is the default.
155 • "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 • "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 scale() will fail if "qtype" is set to some other value.
169 "preview" is faster than "mixing" which is much faster than
171 "normal".
172 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 my $scaled = $img->scaleX(pixels=>400)->scaleY(pixels=>200);
178 From Imager 0.54 you can scale without maintaining proportions
180 either by supplying both the "xscalefactor" and "yscalefactor"
181 arguments:
182 my $scaled = $img->scale(xscalefactor => 0.5, yscalefactor => 0.67);
184 or by supplying "xpixels" and "ypixels" and setting "type" to
186 <nonprop>:
187 my $scaled = $im->scale(xpixels => 200, ypixels => 200, type => 'nonprop');
189 Returns a new scaled image on success. The source image is not
191 modified.
192 Returns false on failure, check the errstr() method for the reason
194 for failure.
195 A mandatory warning is produced if scale() is called in void
197 context.
198 # setup
200 my $image = Imager->new;
201 $image->read(file => 'somefile.jpg')
202 or die $image->errstr;
203 # all full quality unless indicated otherwise
205 # half the size:
206 my $half = $image->scale;
207 # double the size
209 my $double = $image->scale(scalefactor => 2.0);
210 # 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 # fit inside a 400 x 400 box
217 my $inside400x400 = $image->scale(xpixels => 400, ypixels => 400,
218 type=>'min');
219 # make it 400 pixels wide or high
221 my $width400 = $image->scale(xpixels => 400);
222 my $height400 = $image->scale(ypixels => 400);
223 # low quality scales:
225 # to half size
226 my $low = $image->scale(qtype => 'preview');
227 # mixing method scale
229 my $mixed = $image->scale(qtype => 'mixing', scalefactor => 0.1);
230 # 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 # same as Image::Math::Constrain version
237 my $scaled2 = $image->scale(xpixels => 800, ypixels => 600, type => 'min');
238 scaleX()
240 scaleX() will scale along the X dimension, return a new image with
241 the new width:
242 my $newimg = $img->scaleX(pixels=>400); # 400x500
244 $newimg = $img->scaleX(scalefactor=>0.25) # 175x500
245 • "scalefactor" - the amount to scale the X axis. Ignored if
247 "pixels" is provided. Default: 0.5.
248 • "pixels" - the new width of the image.
250 Returns a new scaled image on success. The source image is not
252 modified.
253 Returns false on failure, check the errstr() method for the reason
255 for failure.
256 A mandatory warning is produced if scaleX() is called in void
258 context.
259 scaleY()
261 scaleY() will scale along the Y dimension, return a new image with
262 the new height:
263 $newimg = $img->scaleY(pixels=>400); # 700x400
265 $newimg = $img->scaleY(scalefactor=>0.25) # 700x125
266 • "scalefactor" - the amount to scale the Y axis. Ignored if
268 "pixels" is provided. Default: 0.5.
269 • "pixels" - the new height of the image.
271 Returns a new scaled image on success. The source image is not
273 modified.
274 Returns false on failure, check the errstr() method for the reason
276 for failure.
277 A mandatory warning is produced if scaleY() is called in void
279 context.
280 scale_calculate()
282 Performs the same calculations that the scale() method does to
283 calculate the scaling factors from the parameters you pass.
284 scale_calculate() can be called as an object method, or as a class
286 method.
287 Takes the following parameters over scale():
289 • "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 You might use scale_calculate() as a class method when generating
296 an HTML "IMG" tag, for example.
297 Returns an empty list on failure.
299 Returns a list containing horizontal scale factor, vertical scale
301 factor, new width, new height, on success.
302 my ($x_scale, $y_scale, $new_width, $new_height) =
304 Imager->scale_calculate(width => 1024, height => 768,
305 ypixels => 180, type => 'min');
306 my ($x_scale, $y_scale, $new_width, $new_height) =
308 $img->scale_calculate(xpixels => 200, type => 'min');
309 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 crop() returns the cropped image and does not modify the source
317 image.
318 The possible parameters are:
320 • "left" - the left edge of the area to be cropped. Default: 0
322 • "top" - the top edge of the area to be cropped. Default: 0
324 • "right" - the right edge of the area to be cropped. Default:
326 right edge of image.
327 • "bottom" - the bottom edge of the area to be cropped. Default:
329 bottom edge of image.
330 • "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 • "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 For example:
340 # 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 # 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 # grab the top left corner of the image
352 $newimg = $img->crop(right=>50, bottom=>50);
353 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 $newimg = $img->crop(width=>50, height=>50);
359 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 The edges of the cropped area default to the edges of the source
365 image, for example:
366 # a vertical bar from the middle from top to bottom
368 $newimg = $img->crop(width=>50);
369 # the right half
371 $newimg = $img->crop(left=>$img->getwidth() / 2);
372 If the resulting image would have zero width or height then crop()
374 returns false and $img->errstr is an appropriate error message.
375 A mandatory warning is produced if crop() is called in void
377 context.
378 rotate()
380 Use the rotate() method to rotate an image. This method will
381 return a new, rotated image.
382 To rotate by an exact amount in degrees or radians, use the
384 'degrees' or 'radians' parameter:
385 my $rot20 = $img->rotate(degrees=>20);
387 my $rotpi4 = $img->rotate(radians=>3.14159265/4);
388 Exact image rotation uses the same underlying transformation engine
390 as the matrix_transform() method (see Imager::Engines).
391 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 To rotate in steps of 90 degrees, use the 'right' parameter:
401 my $rotated = $img->rotate(right=>270);
403 Rotations are clockwise for positive values.
405 Parameters:
407 • "right" - rotate by an exact multiple of 90 degrees, specified
409 in degrees.
410 • "radians" - rotate by an angle specified in radians.
412 • "degrees" - rotate by an angle specified in degrees.
414 • "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 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 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 Default: transparent black.
429 # rotate 45 degrees clockwise,
431 my $rotated = $img->rotate(degrees => 45);
432 # 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 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 If you just want the number of pixels to be cropped on each side
443 you can use the "trim_rect()" method.
444 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 To trim just on fully transparent pixels:
450 my $trimmed = $img->trim();
452 To trim pixels with less than 1% coverage:
454 my $trimmed = $img->trim(alpha => 0.01);
456 To trim based on automatically determined colors and fully
458 transparent pixels:
459 my $trimmed = $img->trim(auto => 1);
461 To trim a black border:
463 my $trimmed = $img->trim(colors => [ "#000" ]);
465 Parameters:
467 • "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 • "auto" - automatically select colors to crop on. Possible
475 values:
476 • 1 - a "best" mechanism is selected, this is currently the
478 "center" method, but it subject to change.
479 • "center", "centre" - the pixels at the center of each side
481 of the image are used.
482 • "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 • "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 my $trimmed = $img->trim(colors => [ LIST ]);
492 results in a temporary Imager::TrimColorList being produced
494 like:
495 my $trimmed = $img->trim(colors => Imager::TrimColorList->new( LIST ));
497 "colors" and "auto" exclude each other, only one or the other can
499 be supplied.
500 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 my ($left, $top, $right, $bottom) = $img->trim_rect();
506 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 Accepts the same parameters as "trim()".
511 Image pasting/flipping
513 A list of the transformations that alter the source image follows:
514 paste()
516 To copy an image to onto another image use the "paste()" method.
517 $dest->paste(left=>40, top=>20, src=>$logo);
519 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 Parameters:
524 • "src", "img" - the source image. "src" added for compatibility
526 with rubthrough().
527 • "left", "top" - position in output of the top left of the
529 pasted image. Default: (0,0)
530 • "src_minx", "src_miny" - the top left corner in the source
532 image to start the paste from. Default: (0, 0)
533 • "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 • "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 # 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 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 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 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 $img->rubthrough(src=>$overlay,
560 tx=>30, ty=>50,
561 src_minx=>20, src_miny=>30,
562 src_maxx=>20, src_maxy=>30);
563 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 Parameters:
572 • "tx", "ty" - location in the target image ($self) to render the
574 top left corner of the source.
575 • "src_minx", "src_miny" - the top left corner in the source to
577 transfer to the target image. Default: (0, 0).
578 • "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 # overlay all of $source onto $targ
584 $targ->rubthrough(tx => 20, ty => 25, src => $source);
585 # 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 # 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 rubthrough() returns true on success. On failure check
596 "$target->errstr" for the reason for failure.
597 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 $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 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 Parameters:
615 • "src" - the source image to draw onto the target. Required.
617 • "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 • "src_minx", "src_miny" - the top left corner in the source to
623 transfer to the target image. Default: (0, 0).
624 • "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 • "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 • opacity - further modifies the alpha channel of the source
637 image, in the range 0.0 to 1.0. Default: 1.0.
638 • combine - the method to combine the source pixels with the
640 target. See the combine option documentation in Imager::Fill.
641 Default: normal.
642 Calling compose() with no mask, combine set to "normal", opacity
644 set to 1.0 is equivalent to calling rubthrough().
645 compose() is intended to be produce similar effects to layers in
647 interactive paint software.
648 # overlay all of $source onto $targ
650 $targ->compose(tx => 20, ty => 25, src => $source);
651 # 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 # 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 compose() returns true on success. On failure check
662 $target->errstr for the reason for failure.
663 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
667 to 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 $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 flip() returns true on success. On failure check $img->errstr for
675 the reason for failure.
676 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 The convert method can be used to:
683 • convert an RGB or RGBA image to gray scale.
685 • convert a gray scale image to RGB.
687 • extract a single channel from an image.
689 • set a given channel to a particular value (or from another
691 channel)
692 The currently defined presets are:
694 • "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 This weights the RGB channels at 22.2%, 70.7% and 7.1%
700 respectively.
701 • "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 • "red", "channel0" - extracts the first channel of the image
707 into a single channel image
708 • "green", "channel1" - extracts the second channel of the image
710 into a single channel image
711 • "blue", "channel2" - extracts the third channel of the image
713 into a single channel image
714 • "alpha" - extracts the alpha channel of the image into a single
716 channel image.
717 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 • "rgb"
722 converts a gray scale image to RGB, preserving the alpha
724 channel if any
725 • "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 For example, to convert an RGB image into a gray scale image:
731 $new = $img->convert(preset=>'grey'); # or gray
733 or to convert a gray scale image to an RGB image:
735 $new = $img->convert(preset=>'rgb');
737 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 If you want to perform some other color transformation, you can use
742 the 'matrix' parameter.
743 For each output pixel the following matrix multiplication is done:
745 | 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 So if you want to swap the red and green channels on a 3 channel
753 image:
754 $new = $img->convert(matrix=>[ [ 0, 1, 0 ],
756 [ 1, 0, 0 ],
757 [ 0, 0, 1 ] ]);
758 or to convert a 3 channel image to gray scale using equal
760 weightings:
761 $new = $img->convert(matrix=>[ [ 0.333, 0.333, 0.334 ] ])
763 Convert a 2 channel image (gray scale with alpha) to an RGBA image
765 with the gray converted to the specified RGB color:
766 # 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 To convert a 3 channel image to a 4 channel image with a 50 percent
776 alpha channel:
777 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 combine()
785 Combine channels from one or more input images into a new image.
786 Parameters:
788 • "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 • "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 # make an rgb image from red, green, and blue images
800 my $rgb = Imager->combine(src => [ $red, $green, $blue ]);
801 # convert a BGR image into RGB
803 my $rgb = Imager->combine(src => [ $bgr, $bgr, $bgr ],
804 channels => [ 2, 1, 0 ]);
805 # add an alpha channel from another image
807 my $rgba = Imager->combine(src => [ $rgb, $rgb, $rgb, $alpha ],
808 channels => [ 0, 1, 2, 0 ]);
809 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 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 Single channels can mapped by specifying their name and the mapping
824 table. The channel names are "red", "green", "blue", "alpha".
825 @map = map { int( $_/2 } 0..255;
827 $img->map( red=>\@map );
828 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 $gamma = 1.4;
834 @map = map { int( 0.5 + 255*($_/255)**$gamma ) } 0..255;
835 $img->map(all=> \@map);
836 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 $img->map(all=> \@map, alpha=>[]);
843 Since "[]" contains fewer than 256 element the gamma channel is
845 unaffected.
846 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 $img->map(maps=>[\@redmap, [], \@bluemap]);
852
854 Imager, Imager::Engines
855
857 Tony Cook <tonyc@cpan.org>, Arnar M. Hrafnkelsson
858
860 $Revision$
861perl v5.36.0 2022-07-22 Imager::Transformations(3)