Added documentation to map method in Imager.pm and made some minor fixes

to map method.

diff --git a/Imager.pm b/Imager.pm
index aa10e655df334b76843ed5c85f9fe69710d7f0a5..5208382bfe58dc3b23c2fc0437a19025e6537c7b 100644 (file)
--- a/Imager.pm
+++ b/Imager.pm
@@ -1295,19 +1295,21 @@ sub convert {
 }
 
 
-
-
-
 # general function to map an image through lookup tables
+
 sub map {
   my ($self, %opts) = @_;
-  my @chlist = qw( r g b a );
+  my @chlist = qw( red green blue alpha );
 
   if (!exists($opts{'maps'})) {
     # make maps from channel maps
     my $chnum;
     for $chnum (0..$#chlist) {
-      $opts{'maps'}[$chnum] = $opts{$chlist[$chnum]} if exists $opts{$chlist[$chnum]};
+      if (exists $opts{$chlist[$chnum]}) {
+       $opts{'maps'}[$chnum] = $opts{$chlist[$chnum]};
+      } elsif (exists $opts{'all'}) {
+       $opts{'maps'}[$chnum] = $opts{'all'};
+      }
     }
   }
   if ($opts{'maps'} and $self->{IMG}) {
@@ -1322,22 +1324,6 @@ sub map {
 
 
 
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
 
 
 
@@ -2422,6 +2408,50 @@ or to convert a 3 channel image to greyscale using equal weightings:
 
   $new = $img->convert(matrix=>[ [ 0.333, 0.333, 0.334 ] ])
 
+=head2 Color Mappings
+
+You can use the map method to map the values of each channel of an
+image independently using a list of lookup tables.  It's important to
+realize that the modification is made inplace.  The function simply
+returns the input image again or undef on failure.
+
+Each channel is mapped independently through a lookup table with 256
+entries.  The elements in the table should not be less than 0 and not
+greater than 255.  If they are out of the 0..255 range they are
+clamped to the range.  If a table does not contain 256 entries it is
+silently ignored.
+
+Single channels can mapped by specifying their name and the mapping
+table.  The channel names are C<red>, C<green>, C<blue>, C<alpha>.
+
+  @map = map { int( $_/2 } 0..255;
+  $img->map( red=>\@map );
+
+It is also possible to specify a single map that is applied to all
+channels, alpha channel included.  For example this applies a gamma
+correction with a gamma of 1.4 to the input image.
+
+  $gamma = 1.4;
+  @map = map { int( 0.5 + 255*($_/255)**$gamma ) } 0..255;
+  $img->map(all=> \@map);
+
+The C<all> map is used as a default channel, if no other map is
+specified for a channel then the C<all> map is used instead.  If we
+had not wanted to apply gamma to the alpha channel we would have used:
+
+  $img->map(all=> \@map, alpha=>[]);
+
+Since C<[]> contains fewer than 256 element the gamma channel is
+unaffected.
+
+It is also possible to simply specify an array of maps that are
+applied to the images in the rgba order.  For example to apply
+maps to the C<red> and C<blue> channels one would use:
+
+  $img->map(maps=>[\@redmap, [], \@bluemap]);
+
+
+
 =head2 Transformations
 
 Another special image method is transform.  It can be used to generate
@@ -2604,7 +2634,8 @@ A few examples:
 
 =item rpnexpr=>'x 25 % 15 * y 35 % 10 * getp1 !pat x y getp1 !pix @pix sat 0.7 gt @pat @pix ifp'
 
-tiles a smaller version of the input image over itself where the colour has a saturation over 0.7.
+tiles a smaller version of the input image over itself where the
+colour has a saturation over 0.7.
 
 =item rpnexpr=>'x 25 % 15 * y 35 % 10 * getp1 !pat y 360 / !rat x y getp1 1 @rat - pmult @pat @rat pmult padd'
 
@@ -2678,13 +2709,12 @@ only 2 colors used - it will have a 128 colortable anyway.
 
 =head1 AUTHOR
 
-Arnar M. Hrafnkelsson, addi@umich.edu
-And a great deal of help from others - see the README for a complete
-list.
-=head1 SEE ALSO
+Arnar M. Hrafnkelsson, addi@umich.edu, and recently lots of assistance
+from Tony Cook.  See the README for a complete list.
 
-perl(1), Imager::Color(3), Affix::Infix2Postfix(3), Parse::RecDescent(3)
-http://www.eecs.umich.edu/~addi/perl/Imager/
+=head1 SEE ALSO
 
+perl(1), Imager::Color(3), Imager::Font, Affix::Infix2Postfix(3),
+Parse::RecDescent(3) http://www.eecs.umich.edu/~addi/perl/Imager/
 
 =cut

diff --git a/Imager.xs b/Imager.xs
index 181451a27e9950b02d62499cede5cb384e78081c..fffbbdf9cf92682bcde8fd51e8e6318f45ceff11 100644 (file)
--- a/Imager.xs
+++ b/Imager.xs
@@ -855,8 +855,12 @@ i_map(im, pmaps)
              if(av_len(avsub) != 255) continue;
              mask |= 1<<j;
               for (i=0; i<256 ; i++) {
+               int val;
                temp = av_fetch(avsub, i, 0);
-               maps[j][i] = temp ? SvIV(*temp) : 0;
+               val = temp ? SvIV(*temp) : 0;
+               if (val<0) val = 0;
+               if (val>255) val = 255;
+               maps[j][i] = val;
              }
             }
           }

diff --git a/t/t68map.t b/t/t68map.t
index 4b39a6a1306380a9f62cae073687073212d156de..2f1d0c8e417a284005fae4513ee2b2ae921fb05c 100644 (file)
--- a/t/t68map.t
+++ b/t/t68map.t
@@ -16,13 +16,13 @@ my $imbase = Imager::ImgRaw::new(200,300,3);
 $tst = 1;
 
 i_map($imbase, [ [],     [],     \@map1 ]);
-print $tst++." ok\n";
+print "ok ".$tst++."\n";
 i_map($imbase, [ \@map1, \@map1, \@map1 ]);
 
-print $tst++." ok\n";
+print "ok ".$tst++."\n";
 i_map($imbase, [ \@map1, \@map2, \@map3 ]);
 
-print $tst++." ok\n";
+print "ok ".$tst++."\n";
 i_map($imbase, [ \@maps, \@mapl, \@map3 ]);
 
 # test the highlevel interface
@@ -31,8 +31,8 @@ i_map($imbase, [ \@maps, \@mapl, \@map3 ]);
 
 my $im = Imager->new;
 if ($im->read(file=>'testimg/scale.ppm')) {
-  print $tst++.( $im->map(r=>\@map1, g=>\@map2, b=>\@map3) ? " ok\n" : " not ok\n");
-  print $tst++.( $im->map(maps=>[\@map1, [], \@map2]) ? " ok\n" : " not ok\n");
+  print( ( $im->map(red=>\@map1, green=>\@map2, blue=>\@map3) ? "ok " : "not ok ").$tst++."\n" );
+  print( ( $im->map(maps=>[\@map1, [], \@map2]) ? "ok " : "not ok "). $tst++."\n");
 }
 else {
   die "could not load testout/scale.ppm\n";