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