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