Clarified some specs, added a missing requirement to sum_filter(),

and added overloaded versions of a few image processing functions
to make doing in-place operations slightly more convenient.

dlib/image_transforms/equalize_histogram.h

@@ -116,6 +116,16 @@ namespace dlib
 
     }
 
+    template <
+        typename image_type 
+        >
+    void equalize_histogram (
+        image_type& img
+    )
+    {
+        equalize_histogram(img,img);
+    }
+
 // ---------------------------------------------------------------------------------------
 
 }

dlib/image_transforms/equalize_histogram_abstract.h

@@ -34,6 +34,19 @@ namespace dlib
             - #out_img.nr() == in_img.nr()
     !*/
 
+    template <
+        typename image_type 
+        >
+    void equalize_histogram (
+        image_type& img
+    );
+    /*!
+        requires
+            - it is valid to call equalize_histogram(img,img)
+        ensures
+            - calls equalize_histogram(img,img);
+    !*/
+
 // ---------------------------------------------------------------------------------------
 
     template <

dlib/image_transforms/morphological_operations.h

@@ -86,7 +86,7 @@ namespace dlib
         using namespace morphological_operations_helpers;
         COMPILE_TIME_ASSERT(M%2 == 1);
         COMPILE_TIME_ASSERT(N%2 == 1);
-        DLIB_ASSERT((void*)&in_img != (void*)&out_img ,
+        DLIB_ASSERT(is_same_object(in_img,out_img) == false,
             "\tvoid binary_dilation()"
             << "\n\tYou must give two different image objects"
             );
@@ -158,7 +158,7 @@ namespace dlib
         using namespace morphological_operations_helpers;
         COMPILE_TIME_ASSERT(M%2 == 1);
         COMPILE_TIME_ASSERT(N%2 == 1);
-        DLIB_ASSERT((void*)&in_img != (void*)&out_img ,
+        DLIB_ASSERT(is_same_object(in_img,out_img) == false,
             "\tvoid binary_erosion()"
             << "\n\tYou must give two different image objects"
             );
@@ -235,7 +235,7 @@ namespace dlib
         using namespace morphological_operations_helpers;
         COMPILE_TIME_ASSERT(M%2 == 1);
         COMPILE_TIME_ASSERT(N%2 == 1);
-        DLIB_ASSERT((void*)&in_img != (void*)&out_img ,
+        DLIB_ASSERT(is_same_object(in_img,out_img) == false,
             "\tvoid binary_open()"
             << "\n\tYou must give two different image objects"
             );
@@ -314,7 +314,7 @@ namespace dlib
         using namespace morphological_operations_helpers;
         COMPILE_TIME_ASSERT(M%2 == 1);
         COMPILE_TIME_ASSERT(N%2 == 1);
-        DLIB_ASSERT((void*)&in_img != (void*)&out_img ,
+        DLIB_ASSERT(is_same_object(in_img,out_img) == false,
             "\tvoid binary_close()"
             << "\n\tYou must give two different image objects"
             );
@@ -607,6 +607,16 @@ namespace dlib
         }
     }
 
+    template <
+        typename image_type
+        >
+    void binary_complement (
+        image_type& img
+    )
+    {
+        binary_complement(img,img);
+    }
+
 // ----------------------------------------------------------------------------------------
 
 }

dlib/image_transforms/morphological_operations_abstract.h

@@ -29,7 +29,7 @@ namespace dlib
             - pixel_traits<typename in_image_type::type>::grayscale == true   
             - pixel_traits<typename in_image_type::type>::has_alpha == false
             - pixel_traits<typename out_image_type::type>::has_alpha == false 
-            - &in_img != &out_img
+            - is_same_object(in_img,out_img) == false
             - M % 2 == 1  (i.e. M must be odd)
             - N % 2 == 1  (i.e. N must be odd)
             - all pixels in in_img are set to either on_pixel or off_pixel
@@ -63,7 +63,7 @@ namespace dlib
             - pixel_traits<typename in_image_type::type>::grayscale == true   
             - pixel_traits<typename in_image_type::type>::has_alpha == false
             - pixel_traits<typename out_image_type::type>::has_alpha == false 
-            - &in_img != &out_img
+            - is_same_object(in_img,out_img) == false
             - M % 2 == 1  (i.e. M must be odd)
             - N % 2 == 1  (i.e. N must be odd)
             - all pixels in in_img are set to either on_pixel or off_pixel
@@ -98,7 +98,7 @@ namespace dlib
             - pixel_traits<typename in_image_type::type>::grayscale == true   
             - pixel_traits<typename in_image_type::type>::has_alpha == false
             - pixel_traits<typename out_image_type::type>::has_alpha == false 
-            - &in_img != &out_img
+            - is_same_object(in_img,out_img) == false
             - M % 2 == 1  (i.e. M must be odd)
             - N % 2 == 1  (i.e. N must be odd)
             - all pixels in in_img are set to either on_pixel or off_pixel
@@ -134,7 +134,7 @@ namespace dlib
             - pixel_traits<typename in_image_type::type>::grayscale == true   
             - pixel_traits<typename in_image_type::type>::has_alpha == false
             - pixel_traits<typename out_image_type::type>::has_alpha == false 
-            - &in_img != &out_img
+            - is_same_object(in_img,out_img) == false
             - M % 2 == 1  (i.e. M must be odd)
             - N % 2 == 1  (i.e. N must be odd)
             - all pixels in in_img are set to either on_pixel or off_pixel
@@ -278,6 +278,19 @@ namespace dlib
             - #out_img.nr() == in_img.nr()
     !*/
 
+    template <
+        typename image_type
+        >
+    void binary_complement (
+        image_type& img
+    );
+    /*!
+        requires
+            - it must be valid to call binary_complement(img,img);
+        ensures
+            - calls binary_complement(img,img);
+    !*/
+
 // ----------------------------------------------------------------------------------------
 
 }

dlib/image_transforms/spatial_filtering.h

@@ -632,13 +632,15 @@ namespace dlib
     )
     {
         DLIB_ASSERT(img.nr() == out.nr() &&
-                    img.nc() == out.nc(),
+                    img.nc() == out.nc() &&
+                    is_same_object(img,out) == false,
             "\t void sum_filter()"
             << "\n\t Invalid arguments given to this function."
             << "\n\t img.nr(): " << img.nr() 
             << "\n\t img.nc(): " << img.nc() 
             << "\n\t out.nr(): " << out.nr() 
             << "\n\t out.nc(): " << out.nc() 
+            << "\n\t is_same_object(img,out): " << is_same_object(img,out) 
         );
 
         typedef typename image_type1::type pixel_type;

dlib/image_transforms/spatial_filtering_abstract.h

@@ -330,9 +330,11 @@ namespace dlib
               and it must contain a scalar type
             - image_type2 == an implementation of array2d/array2d_kernel_abstract.h
               and it must contain a scalar type
+            - is_same_object(img,out) == false
         ensures
             - for all valid r and c:
-                - let SUM(r,c) == sum of pixels inside the rectangle translate_rect(rect, point(c,r))
+                - let SUM(r,c) == sum of pixels from img which are inside the rectangle 
+                  translate_rect(rect, point(c,r)).
                 - #out[r][c] == out[r][c] + SUM(r,c)
     !*/
 

dlib/image_transforms/thresholding.h

@@ -53,6 +53,19 @@ namespace dlib
         }
     }
 
+// ----------------------------------------------------------------------------------------
+
+    template <
+        typename image_type
+        >
+    void threshold_image (
+        image_type& img,
+        typename pixel_traits<typename image_type::type>::basic_pixel_type thresh
+    )
+    {
+        threshold_image(img,img,thresh);
+    }
+
 // ----------------------------------------------------------------------------------------
 
     template <
@@ -161,6 +174,16 @@ namespace dlib
         threshold_image(in_img,out_img,thresh);
     }
 
+    template <
+        typename image_type
+        >
+    void auto_threshold_image (
+        image_type& img
+    )
+    {
+        auto_threshold_image(img,img);
+    }
+
 // ----------------------------------------------------------------------------------------
 
     template <

dlib/image_transforms/thresholding_abstract.h

@@ -39,6 +39,20 @@ namespace dlib
             - #out_img.nr() == in_img.nr()
     !*/
 
+    template <
+        typename image_type
+        >
+    void threshold_image (
+        image_type& img,
+        typename pixel_traits<typename image_type::type>::basic_pixel_type thresh
+    );
+    /*!
+        requires
+            - it is valid to call threshold_image(img,img,thresh);
+        ensures
+            - calls threshold_image(img,img,thresh);
+    !*/
+
 // ----------------------------------------------------------------------------------------
 
     template <
@@ -69,6 +83,19 @@ namespace dlib
             - #out_img.nr() == in_img.nr()
     !*/
 
+    template <
+        typename image_type
+        >
+    void auto_threshold_image (
+        image_type& img
+    );
+    /*!
+        requires
+            - it is valid to call auto_threshold_image(img,img);
+        ensures
+            - calls auto_threshold_image(img,img);
+    !*/
+
 // ----------------------------------------------------------------------------------------
 
     template <