Added the camera_transform object.

dlib/geometry/point_transforms.h

@@ -783,6 +783,98 @@ namespace dlib
         return point_transform_affine3d(identity_matrix<double>(3),delta);
     }
 
+// ----------------------------------------------------------------------------------------
+
+    class camera_transform
+    {
+
+    public:
+
+        camera_transform (
+            const vector<double>& camera_pos_,
+            const vector<double>& camera_looking_at_,
+            const vector<double>& camera_up_direction_,
+            const double camera_field_of_view_, 
+            const unsigned long num_pixels_
+        )
+        {
+            camera_pos = camera_pos_;
+            camera_looking_at = camera_looking_at_;
+            camera_up_direction = camera_up_direction_;
+            camera_field_of_view = camera_field_of_view_;
+            num_pixels = num_pixels_;
+
+            dlib::vector<double> X,Y,Z;
+            Z = (camera_looking_at - camera_pos).normalize();
+            Y = camera_up_direction - dot(camera_up_direction,Z)*Z; 
+            Y = Y.normalize();
+            X = Z.cross(Y);
+
+            set_rowm(proj,0) = trans(X);
+            // Minus because images have y axis going down but we want the 3d projection to appear using a normal coordinate system with y going up.
+            set_rowm(proj,1) = -trans(Y); 
+            set_rowm(proj,2) = trans(Z);
+
+            width = num_pixels/2.0;
+            dist_scale = width/std::tan(pi/180*camera_field_of_view/2);
+        }
+
+        vector<double> get_camera_pos()         const { return camera_pos; }
+        vector<double> get_camera_looking_at()  const { return camera_looking_at; }
+        vector<double> get_camera_up_direction()const { return camera_up_direction; }
+        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
+        ) 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;
+            temp.x() = temp.x()*scale + width;
+            temp.y() = temp.y()*scale + width;
+            return temp;
+        }
+
+        inline friend void serialize (const camera_transform& item, std::ostream& out)
+        {
+            serialize(item.camera_pos, out);
+            serialize(item.camera_looking_at, out);
+            serialize(item.camera_up_direction, out);
+            serialize(item.camera_field_of_view, out); 
+            serialize(item.num_pixels, out);
+            serialize(item.proj, out);
+            serialize(item.dist_scale, out);
+            serialize(item.width, out);
+        }
+
+        inline friend void deserialize (camera_transform& item, std::istream& in)
+        {
+            deserialize(item.camera_pos, in);
+            deserialize(item.camera_looking_at, in);
+            deserialize(item.camera_up_direction, in);
+            deserialize(item.camera_field_of_view, in); 
+            deserialize(item.num_pixels, in);
+            deserialize(item.proj, in);
+            deserialize(item.dist_scale, in);
+            deserialize(item.width, in);
+        }
+
+    private:
+
+        vector<double> camera_pos;
+        vector<double> camera_looking_at;
+        vector<double> camera_up_direction;
+        double camera_field_of_view; 
+        unsigned long num_pixels;
+        matrix<double,3,3> proj;
+        double dist_scale;
+        double width;
+
+    };
+
 // ----------------------------------------------------------------------------------------
 
 }

dlib/geometry/point_transforms_abstract.h

@@ -18,6 +18,10 @@ namespace dlib
             WHAT THIS OBJECT REPRESENTS
                 This is an object that takes 2D points or vectors and 
                 applies an affine transformation to them.
+
+            THREAD SAFETY
+                It is safe for multiple threads to make concurrent accesses to this object
+                without synchronization.
         !*/
     public:
 
@@ -150,6 +154,10 @@ namespace dlib
             WHAT THIS OBJECT REPRESENTS
                 This is an object that takes 2D points or vectors and 
                 applies a projective transformation to them.
+
+            THREAD SAFETY
+                It is safe for multiple threads to make concurrent accesses to this object
+                without synchronization.
         !*/
 
     public:
@@ -260,6 +268,10 @@ namespace dlib
                 This is an object that takes 2D points or vectors and 
                 rotates them around the origin by a given angle and then
                 translates them.
+
+            THREAD SAFETY
+                It is safe for multiple threads to make concurrent accesses to this object
+                without synchronization.
         !*/
     public:
 
@@ -325,6 +337,10 @@ namespace dlib
             WHAT THIS OBJECT REPRESENTS
                 This is an object that takes 2D points or vectors and 
                 rotates them around the origin by a given angle.
+
+            THREAD SAFETY
+                It is safe for multiple threads to make concurrent accesses to this object
+                without synchronization.
         !*/
     public:
 
@@ -416,6 +432,10 @@ namespace dlib
             WHAT THIS OBJECT REPRESENTS
                 This is an object that takes 3D points or vectors and 
                 applies an affine transformation to them.
+
+            THREAD SAFETY
+                It is safe for multiple threads to make concurrent accesses to this object
+                without synchronization.
         !*/
     public:
 
@@ -556,6 +576,106 @@ namespace dlib
                 point_transform_affine3d(identity_matrix<double>(3),delta);
     !*/
 
+// ----------------------------------------------------------------------------------------
+
+    class camera_transform
+    {
+        /*!
+            WHAT THIS OBJECT REPRESENTS
+                This object maps 3D points into the image plane of a camera.  Therefore,
+                you can use it to compute 2D representations of 3D data from the point of
+                view of some camera in 3D space.
+
+            THREAD SAFETY
+                It is safe for multiple threads to make concurrent accesses to this object
+                without synchronization.
+        !*/
+
+    public:
+
+        camera_transform (
+            const vector<double>& camera_pos,
+            const vector<double>& camera_looking_at,
+            const vector<double>& camera_up_direction,
+            const double camera_field_of_view, 
+            const unsigned long num_pixels
+        );
+        /*!
+            requires
+                - 0 < camera_field_of_view < 360
+            ensures
+                - #get_camera_pos() == camera_pos
+                - #get_camera_looking_at() == camera_looking_at
+                - #get_camera_up_direction() == camera_up_direction
+                - #get_camera_field_of_view() == camera_field_of_view
+                - #get_num_pixels() == num_pixels
+        !*/
+
+        dpoint operator() (
+            const vector<double>& p
+        ) 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.
+        !*/
+
+        vector<double> get_camera_pos(
+        ) const;
+        /*!
+            ensures
+                - returns the position, in 3D space, of the camera.  When operator() is
+                  invoked it maps 3D points into the image plane of this camera.
+        !*/
+
+        vector<double> get_camera_looking_at(
+        ) const;
+        /*!
+            ensures
+                - returns the point in 3D space the camera is pointed at.  
+        !*/
+
+        vector<double> get_camera_up_direction(
+        ) const;
+        /*!
+            ensures
+                - returns a vector that defines what direction is "up" for the camera.
+                  This means that as you travel from the bottom of the image plane to the
+                  top you will be traveling in the direction of this vector.  Note that
+                  get_camera_up_direction() doesn't need to be orthogonal to the camera's
+                  line of sight (i.e. get_camera_looking_at()-get_camera_pos()), it just
+                  needs to not be an exact multiple of the line of sight.  Any necessary
+                  orthogonalization will be taken care of internally.
+        !*/
+
+        double get_camera_field_of_view(
+        ) const;
+        /*!
+            ensures
+                - returns the field of view of the camera in degrees.
+        !*/
+
+        unsigned long get_num_pixels(
+        ) const;
+        /*!
+            ensures
+                - 3D points that fall within the field of view of the camera are mapped by
+                  operator() into the pixel coordinates of a get_num_pixels() by
+                  get_num_pixels() image.  Therefore, you can use the output of operator()
+                  to index into an image.  However, you still need to perform bounds
+                  checking as there might be 3D points outside the field of view of the
+                  camera and those will be mapped to 2D points outside the image.
+        !*/
+
+    };
+
+    void serialize   (const camera_transform& item, std::ostream& out);
+    void deserialize (camera_transform& item, std::istream& in);
+    /*!
+        provides serialization support
+    !*/
+
 // ----------------------------------------------------------------------------------------
 
 }