return the projective transform in extract_image_4points (#2395)

dlib/image_transforms/interpolation.h

@@ -2118,7 +2118,7 @@ namespace dlib
     template <
         typename image_type
         >
-    void extract_image_4points (
+    point_transform_projective extract_image_4points (
         const image_type& img_,
         image_type& out_,
         const std::array<dpoint,4>& pts
@@ -2127,7 +2127,7 @@ namespace dlib
         const_image_view<image_type> img(img_);
         image_view<image_type> out(out_);
         if (out.size() == 0)
-            return;
+            return point_transform_projective();
 
         drectangle bounding_box;
         for (auto& p : pts)
@@ -2160,18 +2160,19 @@ namespace dlib
 
         auto tform = find_projective_transform(from_points, to_points);
         transform_image(img_, out_, interpolate_bilinear(), tform);
+        return inv(tform);
     }
 
     template <
         typename image_type
         >
-    void extract_image_4points (
+    point_transform_projective extract_image_4points (
         const image_type& img,
         image_type& out,
         const std::array<line,4>& lines 
     )
     {
-        extract_image_4points(img, out, find_convex_quadrilateral(lines));
+        return extract_image_4points(img, out, find_convex_quadrilateral(lines));
     }
 
 // ----------------------------------------------------------------------------------------

dlib/image_transforms/interpolation_abstract.h

@@ -1542,7 +1542,7 @@ namespace dlib
     template <
         typename image_type
         >
-    void extract_image_4points (
+    point_transform_projective extract_image_4points (
         const image_type& img,
         image_type& out,
         const std::array<dpoint,4>& pts
@@ -1564,12 +1564,14 @@ namespace dlib
               left corner, upper right corner to upper right corner, etc.).
             - #out.nr() == out.nr() && #out.nc() == out.nc().  
               I.e. out should already be sized to whatever size you want it to be.
+            - Returns a transformation object that maps points in img into their
+              corresponding location in #out.
     !*/
 
     template <
         typename image_type
         >
-    void extract_image_4points (
+    point_transform_projective extract_image_4points (
         const image_type& img,
         image_type& out,
         const std::array<line,4>& lines 
@@ -1584,6 +1586,8 @@ namespace dlib
               convex quadrilateral and uses them in a call to the version of
               extract_image_4points() defined above.  i.e. extract_image_4points(img, out,
               intersections_between_lines)
+            - Returns a transformation object that maps points in img into their
+              corresponding location in #out.
         throws 
             - no_convex_quadrilateral: this is thrown if you can't make a convex
               quadrilateral out of the given lines.