Added some functions which define the coordinate transforms

between different layers in an image pyramid.

--HG--
extra : convert_revision : svn%3Afdd8eb12-d10e-0410-9acb-85c331704f74/trunk%404239

dlib/image_transforms/image_pyramid.h

@@ -14,6 +14,85 @@ namespace dlib
     {
     public:
 
+        template <typename T>
+        vector<double,2> point_down (
+            const vector<T,2>& p
+        ) const
+        {
+            //do return (p - vector<T,2>(2,2))/2.0;
+            return p/2.0 - vector<double,2>(1,1);
+        }
+
+        template <typename T>
+        vector<double,2> point_up (
+            const vector<T,2>& p
+        ) const
+        {
+            return p*2 + vector<T,2>(2,2);
+        }
+
+    // -----------------------------
+
+        template <typename T>
+        vector<double,2> point_down (
+            const vector<T,2>& p,
+            unsigned int levels
+        ) const
+        {
+            vector<double,2> temp = p;
+            for (unsigned int i = 0; i < levels; ++i)
+                temp = point_down(temp);
+            return temp;
+        }
+
+        template <typename T>
+        vector<double,2> point_up (
+            const vector<T,2>& p,
+            unsigned int levels
+        ) const
+        {
+            vector<double,2> temp = p;
+            for (unsigned int i = 0; i < levels; ++i)
+                temp = point_up(temp);
+            return temp;
+        }
+
+    // -----------------------------
+
+        rectangle rect_up (
+            const rectangle& rect
+        ) const
+        {
+            return rectangle(point_up(rect.tl_corner()), point_up(rect.br_corner()));
+        }
+
+        rectangle rect_up (
+            const rectangle& rect,
+            unsigned int levels
+        ) const
+        {
+            return rectangle(point_up(rect.tl_corner(),levels), point_up(rect.br_corner(),levels));
+        }
+
+    // -----------------------------
+
+        rectangle rect_down (
+            const rectangle& rect
+        ) const
+        {
+            return rectangle(point_down(rect.tl_corner()), point_down(rect.br_corner()));
+        }
+
+        rectangle rect_down (
+            const rectangle& rect,
+            unsigned int levels
+        ) const
+        {
+            return rectangle(point_down(rect.tl_corner(),levels), point_down(rect.br_corner(),levels));
+        }
+
+    // -----------------------------
+
         template <
             typename in_image_type,
             typename out_image_type

dlib/image_transforms/image_pyramid_abstract.h

@@ -14,6 +14,15 @@ namespace dlib
         /*!
             WHAT THIS OBJECT REPRESENTS
                 This is a simple functor to help create image pyramids.
+
+
+                WARNING, when mapping rectangles from one layer of a pyramid
+                to another you might end up with rectangles which extend slightly 
+                outside your images.  This is because points on the border of an 
+                image at a higher pyramid layer might correspond to points outside 
+                images at lower layers.  So just keep this in mind.  Note also
+                that it's easy to deal with.  Just say something like this:
+                    rect = rect.intersect(get_rect(my_image)); // keep rect inside my_image 
         !*/
     public:
 
@@ -40,7 +49,105 @@ namespace dlib
                     - 1. Applies a 5x5 Gaussian filter to the original image to smooth it a little.
                     - 2. Every other row and column is discarded to create an image half the size
                          of the original.  This smaller image is stored in #down.
+                - The location of a point P in original image will show up at point point_down(P)
+                  in the #down image.  
+                - Note that some points on the border of the original image will correspond to 
+                  points outside the #down image.  This is because the 5x5 filter is not applied 
+                  at the borders.
+        !*/
+
+    // -------------------------------
+
+        template <typename T>
+        vector<double,2> point_down (
+            const vector<T,2>& p
+        ) const;
+        /*!
+            ensures
+                - interprets p as a point in a parent image and returns the
+                  point in a downsampled image which corresponds to p.
+                - This function is the inverse of point_up().  I.e. for an point P:
+                  point_down(point_up(P)) == P
+        !*/
+
+        template <typename T>
+        vector<double,2> point_up (
+            const vector<T,2>& p
+        ) const;
+        /*!
+            ensures
+                - interprets p as a point in a downsampled image and returns the
+                  point in a parent image which corresponds to p.
+                - This function is the inverse of point_down().  I.e. for an point P:
+                  point_up(point_down(P)) == P
+        !*/
+
+        rectangle rect_down (
+            const rectangle& rect
+        ) const;
+        /*!
+            ensures
+                - returns rectangle(point_down(rect.tl_corner()), point_down(rect.br_corner()));
+                  (i.e. maps rect into a downsampled)
+        !*/
+
+        rectangle rect_up (
+            const rectangle& rect
+        ) const;
+        /*!
+            ensures
+                - returns rectangle(point_up(rect.tl_corner()), point_up(rect.br_corner()));
+                  (i.e. maps rect into a parent image)
         !*/
+
+    // -------------------------------
+
+        template <typename T>
+        vector<double,2> point_down (
+            const vector<T,2>& p,
+            unsigned int levels
+        ) const;
+        /*!
+            ensures
+                - applies point_down() to p levels times and returns the result.
+                  (i.e. point_down(p,2) == point_down(point_down(p)),
+                        point_down(p,1) == point_down(p),
+                        point_down(p,0) == p,  etc. )
+        !*/
+
+        template <typename T>
+        vector<double,2> point_up (
+            const vector<T,2>& p,
+            unsigned int levels
+        ) const;
+        /*!
+            ensures
+                - applies point_up() to p levels times and returns the result.
+                  (i.e. point_up(p,2) == point_up(point_up(p)),
+                        point_up(p,1) == point_up(p),
+                        point_up(p,0) == p,  etc. )
+        !*/
+
+        rectangle rect_down (
+            const rectangle& rect,
+            unsigned int levels
+        ) const;
+        /*!
+            ensures
+                - returns rectangle(point_down(rect.tl_corner(),levels), point_down(rect.br_corner(),levels));
+                  (i.e. Basically applies rect_down() to rect levels times and returns the result.)
+        !*/
+
+        rectangle rect_up (
+            const rectangle& rect,
+            unsigned int levels
+        ) const;
+        /*!
+            ensures
+                - returns rectangle(point_up(rect.tl_corner(),levels), point_up(rect.br_corner(),levels));
+                  (i.e. Basically applies rect_up() to rect levels times and returns the result.)
+        !*/
+
     };
 
 }