Added an optional scale output to the camera_transform.

dlib/geometry/point_transforms.h

@@ -842,19 +842,28 @@ namespace dlib
         double get_camera_field_of_view()       const { return camera_field_of_view; }
         unsigned long get_num_pixels()                   const { return num_pixels; }
 
-        dpoint operator() (
-            const vector<double>& p
+        inline dpoint operator() (
+            const vector<double>& p,
+            double& scale
         ) const
         {
             vector<double> temp = p-camera_pos;
             temp = proj*temp;
             const double distance = temp.z()>0 ? temp.z() : 1e-9;
-            const double scale = dist_scale/distance;
+            scale = dist_scale/distance;
             temp.x() = temp.x()*scale + width;
             temp.y() = temp.y()*scale + width;
             return temp;
         }
 
+        dpoint operator() (
+            const vector<double>& p
+        ) const
+        {
+            double scale;
+            return (*this)(p,scale);
+        }
+
         inline friend void serialize (const camera_transform& item, std::ostream& out)
         {
             serialize(item.camera_pos, out);

dlib/geometry/point_transforms_abstract.h

@@ -632,6 +632,20 @@ namespace dlib
                   plane is returned.
         !*/
 
+        dpoint operator() (
+            const vector<double>& p,
+            double& scale
+        ) const;
+        /*!
+            ensures
+                - Maps the given 3D point p into the 2D image plane defined by the camera
+                  parameters given to this object's constructor.  The 2D point in the image
+                  plane is returned.
+                - #scale == a number that tells you how large things are at the point p.
+                  Objects further from the camera appear smaller, in particular, they
+                  appear #scale times their normal size.
+        !*/
+
         vector<double> get_camera_pos(
         ) const;
         /*!