test, doc a perspective projection

Author: mohawk2

lib/PDL/Transform.pd

@@ -3888,9 +3888,17 @@ can continuously warp an image plane so that C<ncoords + 2> arbitrarily chosen
 points exactly map to the same number of other arbitrarily chosen points.  They
 have the property that straight lines remain straight after transformation.
 
+=for example
+
+  # perspective projection 3D -> 2D
+  $t_proj = t_projective(
+    src => pdl('1 1 1; -1 1 1; -1 -1 1; 1 -1 1; 2 2 2; -2 -2 2'),
+    dst => pdl('0 1000; 1000 1000; 1000 0; 0 0; 0 1000; 1000 0'),
+  );
+
 You can specify your projective transformation directly in homogeneous
 coordinates, or (as of 2.104, not just in 2 dimensions) as a set
-of C<ncoords + 2> unique points that
+of unique points that
 are mapped one to the other by the transformation.
 
 Projective transforms are quasi-linear because they are most easily
@@ -3936,8 +3944,7 @@ For example, specifying
 maps the origin and the point (0,1) to themselves, the point (5,9)
 to (5,8), and the point (9,4) to (9,3).
 
-Added in 2.104. Works on any number of dimensions, the same for
-C<src> and C<dst> (a homography).
+Added in 2.104. Works on any number of dimensions.
 
 =item p, point, points, Points
 

t/transform.t

@@ -58,9 +58,15 @@ use Test::Exception;
     0 0 0 1 1 1   -1.463864 -1.463864 -1.463864
   '), 'right design matrix';
   $t_proj = t_projective(
-    m => pdl('-500 0 500 0; 0 500 500 0; 0 0 1 0'),
+    m => my $perspective_matrix = pdl('-500 0 500 0; 0 500 500 0; 0 0 1 0'),
   );
-  is_pdl $t_proj->apply(my $in32 = pdl('0 -1 -1; 4 2 -10')), my $out32 = pdl('500 1000; 700 400'), 'project 3->2 with matrix';
+  is_pdl $t_proj->apply(my $in32 = pdl('0 -1 -1; 4 2 -10')), my $out32 = pdl('500 1000; 700 400'), 'project perspective 3->2 with matrix';
+  $t_proj = t_projective(
+    src => my $src32perspective = pdl('1 1 1; -1 1 1; -1 -1 1; 1 -1 1; 2 2 2; -2 -2 2'),
+    dst => my $dst32perspective = pdl('0 1000; 1000 1000; 1000 0; 0 0; 0 1000; 1000 0'),
+  );
+  is_pdl $t_proj->{params}{matrix}, $perspective_matrix, {test_name=>'perspective matrix from src/dst', atol=>1e-2};
+  is_pdl $t_proj->apply($in32), $out32, 'project perspective 3->2 with src/dst';
   $t_proj = t_projective(
     src => my $src3 = pdl('0 0 0; 1 0 0;  0 1 0; 1 1 0; 0 0 1'),
     dst => my $dst3 = pdl('1 0 0; 2 1 0; -1 3 0; 0 4 0; 1 0 1'),