filled out spec

dlib/image_transforms/interpolation.h

@@ -321,7 +321,7 @@ namespace dlib
         typename background_type
         >
     void transform_image (
-        const image_type& img,
+        const image_type& in_img,
         image_type& out_img,
         const interpolation_type& interp,
         const point_mapping_type& map_point,
@@ -332,14 +332,14 @@ namespace dlib
         requires
             - get_rect(out_img).contains(area) == true
         ensures
-            - map_point maps from out_img to img
+            - map_point maps from out_img to in_img
     !*/
     {
         for (long r = area.top(); r <= area.bottom(); ++r)
         {
             for (long c = area.left(); c <= area.right(); ++c)
             {
-                if (!interp(img, map_point(dlib::vector<double,2>(c,r)), out_img[r][c]))
+                if (!interp(in_img, map_point(dlib::vector<double,2>(c,r)), out_img[r][c]))
                     set_background(out_img[r][c]);
             }
         }
@@ -354,14 +354,14 @@ namespace dlib
         typename background_type
         >
     void transform_image (
-        const image_type& img,
+        const image_type& in_img,
         image_type& out_img,
         const interpolation_type& interp,
         const point_mapping_type& map_point,
         const background_type& set_background
     )
     {
-        transform_image(img, out_img, interp, map_point, set_background, get_rect(out_img));
+        transform_image(in_img, out_img, interp, map_point, set_background, get_rect(out_img));
     }
 
 // ----------------------------------------------------------------------------------------
@@ -372,13 +372,13 @@ namespace dlib
         typename point_mapping_type
         >
     void transform_image (
-        const image_type& img,
+        const image_type& in_img,
         image_type& out_img,
         const interpolation_type& interp,
         const point_mapping_type& map_point
     )
     {
-        transform_image(img, out_img, interp, map_point, black_background(), get_rect(out_img));
+        transform_image(in_img, out_img, interp, map_point, black_background(), get_rect(out_img));
     }
 
 // ----------------------------------------------------------------------------------------
@@ -388,13 +388,13 @@ namespace dlib
         typename interpolation_type
         >
     void rotate_image (
-        const image_type& img,
+        const image_type& in_img,
         image_type& out_img,
         double angle,
         const interpolation_type& interp
     )
     {
-        const rectangle rimg = get_rect(img);
+        const rectangle rimg = get_rect(in_img);
 
 
         // figure out bounding box for rotated rectangle
@@ -407,7 +407,7 @@ namespace dlib
 
         const matrix<double,2,2> R = rotation_matrix(angle);
 
-        transform_image(img, out_img, interp, 
+        transform_image(in_img, out_img, interp, 
                         point_transform_affine(R, -R*dcenter(get_rect(out_img)) + dcenter(rimg)));
     }
 
@@ -418,12 +418,12 @@ namespace dlib
         typename image_type
         >
     void rotate_image (
-        const image_type& img,
+        const image_type& in_img,
         image_type& out_img,
         double angle
     )
     {
-        rotate_image(img, out_img, angle, interpolate_quadratic());
+        rotate_image(in_img, out_img, angle, interpolate_quadratic());
     }
 
 // ----------------------------------------------------------------------------------------
@@ -432,11 +432,11 @@ namespace dlib
         typename image_type
         >
     void flip_image_left_right (
-        const image_type& img,
+        const image_type& in_img,
         image_type& out_img
     )
     {
-        assign_image(out_img, fliplr(array_to_matrix(img)));
+        assign_image(out_img, fliplr(array_to_matrix(in_img)));
     }
 
 // ----------------------------------------------------------------------------------------
@@ -445,11 +445,11 @@ namespace dlib
         typename image_type
         >
     void flip_image_up_down (
-        const image_type& img,
+        const image_type& in_img,
         image_type& out_img
     )
     {
-        assign_image(out_img, flipud(array_to_matrix(img)));
+        assign_image(out_img, flipud(array_to_matrix(in_img)));
     }
 
 // ----------------------------------------------------------------------------------------

dlib/image_transforms/interpolation_abstract.h

@@ -10,6 +10,352 @@ namespace dlib
 
 // ----------------------------------------------------------------------------------------
 
+    class interpolate_nearest_neighbor
+    {
+        /*!
+            WHAT THIS OBJECT REPRESENTS
+                This object is a tool for performing nearest neighbor interpolation
+                on an image.  
+        !*/
+
+    public:
+
+        template <typename image_type>
+        bool operator() (
+            const image_type& img,
+            const dlib::point& p,
+            typename image_type::type& result
+        ) const;
+        /*!
+            requires
+                - image_type == is an implementation of array2d/array2d_kernel_abstract.h
+            ensures
+                - if (p is located inside img) then
+                    - #result == img[p.y()][p.x()]
+                    - returns true
+                - else
+                    - returns false
+        !*/
+
+    };
+
+// ----------------------------------------------------------------------------------------
+
+    class interpolate_bilinear
+    {
+
+        /*!
+            WHAT THIS OBJECT REPRESENTS
+                This object is a tool for performing bilinear interpolation
+                on an image.  This is performed by looking at the 4 pixels
+                nearest to a point and deriving an interpolated value from them.
+        !*/
+
+    public:
+
+        template <
+            typename T, 
+            typename image_type
+            >
+        bool operator() (
+            const image_type& img,
+            const dlib::vector<T,2>& p,
+            typename image_type::type& result
+        ) const;
+        /*!
+            requires
+                - image_type == is an implementation of array2d/array2d_kernel_abstract.h
+                - pixel_traits<typename image_type::type>::has_alpha == false
+            ensures
+                - if (there is an interpolatable image location at point p in img) then
+                    - #result == the interpolated pixel value from img at point p.
+                    - returns true
+                    - if img contain RGB pixels then the interpolation will be in 
+                      color.  Otherwise, the interpolation will be performed in 
+                      a grayscale mode.
+                - else
+                    - returns false
+        !*/
+    };
+
+// ----------------------------------------------------------------------------------------
+
+    class interpolate_quadratic
+    {
+        /*!
+            WHAT THIS OBJECT REPRESENTS
+                This object is a tool for performing quadratic interpolation
+                on an image.  This is performed by looking at the 9 pixels
+                nearest to a point and deriving an interpolated value from them.
+        !*/
+
+    public:
+
+        template <
+            typename T, 
+            typename image_type
+            >
+        bool operator() (
+            const image_type& img,
+            const dlib::vector<T,2>& p,
+            typename image_type::type& result
+        ) const;
+        /*!
+            requires
+                - image_type == is an implementation of array2d/array2d_kernel_abstract.h
+                - pixel_traits<typename image_type::type>::has_alpha == false
+            ensures
+                - if (there is an interpolatable image location at point p in img) then
+                    - #result == the interpolated pixel value from img at point p
+                    - returns true
+                    - if img contain RGB pixels then the interpolation will be in 
+                      color.  Otherwise, the interpolation will be performed in 
+                      a grayscale mode.
+                - else
+                    - returns false
+        !*/
+    };
+
+// ----------------------------------------------------------------------------------------
+// ----------------------------------------------------------------------------------------
+// ----------------------------------------------------------------------------------------
+
+    class black_background
+    {
+        /*!
+            WHAT THIS OBJECT REPRESENTS
+                This is a function object which simply sets a pixel 
+                to have a black value.
+        !*/
+
+    public:
+        template <typename pixel_type>
+        void operator() ( pixel_type& p) const { assign_pixel(p, 0); }
+    };
+
+// ----------------------------------------------------------------------------------------
+
+    class white_background
+    {
+        /*!
+            WHAT THIS OBJECT REPRESENTS
+                This is a function object which simply sets a pixel 
+                to have a white value.
+        !*/
+
+    public:
+        template <typename pixel_type>
+        void operator() ( pixel_type& p) const { assign_pixel(p, 255); }
+    };
+
+// ----------------------------------------------------------------------------------------
+
+    class no_background
+    {
+        /*!
+            WHAT THIS OBJECT REPRESENTS
+                This is a function object which does nothing.  It is useful
+                when used with the transform_image() routine defined below
+                if no modification of uninterpolated output pixels is desired.
+        !*/
+    public:
+        template <typename pixel_type>
+        void operator() ( pixel_type& ) const { }
+    };
+
+// ----------------------------------------------------------------------------------------
+// ----------------------------------------------------------------------------------------
+
+    template <
+        typename image_type,
+        typename interpolation_type,
+        typename point_mapping_type,
+        typename background_type
+        >
+    void transform_image (
+        const image_type& in_img,
+        image_type& out_img,
+        const interpolation_type& interp,
+        const point_mapping_type& map_point,
+        const background_type& set_background,
+        const rectangle& area
+    );
+    /*!
+        requires
+            - image_type == is an implementation of array2d/array2d_kernel_abstract.h
+            - interpolation_type == interpolate_nearest_neighbor, interpolate_bilinear, 
+              interpolate_quadratic, or a type with a compatible interface.
+            - map_point should be a function which takes dlib::vector<T,2> objects and
+              returns dlib::vector<T,2> objects.  An example is point_transform_affine.
+            - set_background should be a function which can take a single argument of
+              type image_type::type.  Examples are black_background, white_background,
+              and no_background.
+            - get_rect(out_img).contains(area) == true
+            - is_same_object(in_img, out_img) == false
+        ensures
+            - The map_point function defines a mapping from pixels in out_img to pixels
+              in in_img.  transform_image() uses this mapping, along with the supplied
+              interpolation routine interp, to fill the region of out_img defined by
+              area with an interpolated copy of in_img.  
+            - This function does not change the size of out_img.
+            - Only pixels inside the region defined by area in out_img are modified.
+            - For all locations r and c such that area.contains(c,r) but have no corresponding 
+              locations in in_img:
+                - set_background(out_img[r][c]) is invoked
+                  (i.e. some parts of out_img might correspond to areas outside in_img and
+                  therefore can't supply interpolated values.  In these cases, these
+                  pixels can be assigned a value by the supplied set_background() routine)
+    !*/
+
+// ----------------------------------------------------------------------------------------
+
+    template <
+        typename image_type,
+        typename interpolation_type,
+        typename point_mapping_type,
+        typename background_type
+        >
+    void transform_image (
+        const image_type& in_img,
+        image_type& out_img,
+        const interpolation_type& interp,
+        const point_mapping_type& map_point,
+        const background_type& set_background
+    );
+    /*!
+        requires
+            - image_type == is an implementation of array2d/array2d_kernel_abstract.h
+            - interpolation_type == interpolate_nearest_neighbor, interpolate_bilinear, 
+              interpolate_quadratic, or a type with a compatible interface.
+            - map_point should be a function which takes dlib::vector<T,2> objects and
+              returns dlib::vector<T,2> objects.  An example is point_transform_affine.
+            - set_background should be a function which can take a single argument of
+              type image_type::type.  Examples are black_background, white_background,
+              and no_background.
+            - is_same_object(in_img, out_img) == false
+        ensures
+            - performs: 
+              transform_image(in_img, out_img, interp, map_point, set_background, get_rect(out_img));
+              (i.e. runs transform_image() on the entire out_img)
+    !*/
+
+// ----------------------------------------------------------------------------------------
+
+    template <
+        typename image_type,
+        typename interpolation_type,
+        typename point_mapping_type
+        >
+    void transform_image (
+        const image_type& in_img,
+        image_type& out_img,
+        const interpolation_type& interp,
+        const point_mapping_type& map_point
+    );
+    /*!
+        requires
+            - image_type == is an implementation of array2d/array2d_kernel_abstract.h
+            - interpolation_type == interpolate_nearest_neighbor, interpolate_bilinear, 
+              interpolate_quadratic, or a type with a compatible interface.
+            - map_point should be a function which takes dlib::vector<T,2> objects and
+              returns dlib::vector<T,2> objects.  An example is point_transform_affine.
+            - is_same_object(in_img, out_img) == false
+        ensures
+            - performs: 
+              transform_image(in_img, out_img, interp, map_point, black_background(), get_rect(out_img));
+              (i.e. runs transform_image() on the entire out_img and sets non-interpolated
+              pixels to black)
+    !*/
+
+// ----------------------------------------------------------------------------------------
+
+    template <
+        typename image_type,
+        typename interpolation_type
+        >
+    void rotate_image (
+        const image_type& in_img,
+        image_type& out_img,
+        double angle,
+        const interpolation_type& interp
+    );
+    /*!
+        requires
+            - image_type == is an implementation of array2d/array2d_kernel_abstract.h
+            - interpolation_type == interpolate_nearest_neighbor, interpolate_bilinear, 
+              interpolate_quadratic, or a type with a compatible interface.
+            - is_same_object(in_img, out_img) == false
+        ensures
+            - #out_img == a copy of in_img which has been rotated angle radians counter clockwise.
+              The rotation is performed with respect to the center of the image.  
+            - Parts of #out_img which have no corresponding locations in in_img are set to black.
+            - uses the supplied interpolation routine interp to perform the necessary
+              pixel interpolation.
+    !*/
+
+// ----------------------------------------------------------------------------------------
+
+
+    template <
+        typename image_type
+        >
+    void rotate_image (
+        const image_type& in_img,
+        image_type& out_img,
+        double angle
+    );
+    /*!
+        requires
+            - image_type == is an implementation of array2d/array2d_kernel_abstract.h
+            - pixel_traits<typename image_type::type>::has_alpha == false
+            - is_same_object(in_img, out_img) == false
+        ensures
+            - #out_img == a copy of in_img which has been rotated angle radians counter clockwise.
+              The rotation is performed with respect to the center of the image.  
+            - Parts of #out_img which have no corresponding locations in in_img are set to black.
+            - uses the interpolate_quadratic object to perform the necessary pixel interpolation.
+    !*/
+
+// ----------------------------------------------------------------------------------------
+
+    template <
+        typename image_type
+        >
+    void flip_image_left_right (
+        const image_type& in_img,
+        image_type& out_img
+    );
+    /*!
+        requires
+            - image_type == is an implementation of array2d/array2d_kernel_abstract.h
+            - pixel_traits<image_type::type> is defined
+            - is_same_object(in_img, out_img) == false
+        ensures
+            - #out_img.nr() == in_img.nr()
+            - #out_img.nc() == in_img.nc()
+            - #out_img == a copy of in_img which has been flipped from left to right.  
+    !*/
+
+// ----------------------------------------------------------------------------------------
+
+    template <
+        typename image_type
+        >
+    void flip_image_up_down (
+        const image_type& in_img,
+        image_type& out_img
+    );
+    /*!
+        requires
+            - image_type == is an implementation of array2d/array2d_kernel_abstract.h
+            - pixel_traits<image_type::type> is defined
+            - is_same_object(in_img, out_img) == false
+        ensures
+            - #out_img.nr() == in_img.nr()
+            - #out_img.nc() == in_img.nc()
+            - #out_img == a copy of in_img which has been flipped upside down.  
+    !*/
+
 // ----------------------------------------------------------------------------------------
 
 }