Made the spatial filtering routines return a rectangle which tells you what

part of the image wasn't just zero padding along the border.

dlib/image_transforms/spatial_filtering.h

@@ -22,7 +22,7 @@ namespace dlib
         typename EXP,
         typename T
         >
-    void spatially_filter_image (
+    rectangle spatially_filter_image (
         const in_image_type& in_img,
         out_image_type& out_img,
         const matrix_exp<EXP>& filter,
@@ -54,7 +54,7 @@ namespace dlib
         if (in_img.size() == 0)
         {
             out_img.clear();
-            return;
+            return rectangle();
         }
 
         out_img.set_size(in_img.nr(),in_img.nc());
@@ -67,6 +67,8 @@ namespace dlib
         const long last_row = in_img.nr() - filter.nr()/2;
         const long last_col = in_img.nc() - filter.nc()/2;
 
+        const rectangle non_border = rectangle(first_col, first_row, last_col-1, last_row-1);
+
         // apply the filter to the image
         for (long r = first_row; r < last_row; ++r)
         {
@@ -104,6 +106,8 @@ namespace dlib
                 }
             }
         }
+
+        return non_border;
     }
 
     template <
@@ -111,13 +115,13 @@ namespace dlib
         typename out_image_type,
         typename EXP
         >
-    void spatially_filter_image (
+    rectangle spatially_filter_image (
         const in_image_type& in_img,
         out_image_type& out_img,
         const matrix_exp<EXP>& filter
     )
     {
-        spatially_filter_image(in_img,out_img,filter,1);
+        return spatially_filter_image(in_img,out_img,filter,1);
     }
 
 // ----------------------------------------------------------------------------------------
@@ -129,7 +133,7 @@ namespace dlib
         typename EXP2,
         typename T
         >
-    void spatially_filter_image_separable (
+    rectangle spatially_filter_image_separable (
         const in_image_type& in_img,
         out_image_type& out_img,
         const matrix_exp<EXP1>& row_filter,
@@ -166,7 +170,7 @@ namespace dlib
         if (in_img.size() == 0)
         {
             out_img.clear();
-            return;
+            return rectangle();
         }
 
         out_img.set_size(in_img.nr(),in_img.nc());
@@ -179,6 +183,7 @@ namespace dlib
         const long last_row = in_img.nr() - col_filter.size()/2;
         const long last_col = in_img.nc() - row_filter.size()/2;
 
+        const rectangle non_border = rectangle(first_col, first_row, last_col-1, last_row-1);
 
         typedef typename out_image_type::mem_manager_type mem_manager_type;
         typedef typename EXP1::type ptype;
@@ -233,6 +238,7 @@ namespace dlib
                 }
             }
         }
+        return non_border;
     }
 
     template <
@@ -241,14 +247,14 @@ namespace dlib
         typename EXP1,
         typename EXP2
         >
-    void spatially_filter_image_separable (
+    rectangle spatially_filter_image_separable (
         const in_image_type& in_img,
         out_image_type& out_img,
         const matrix_exp<EXP1>& row_filter,
         const matrix_exp<EXP2>& col_filter
     )
     {
-        spatially_filter_image_separable(in_img,out_img,row_filter,col_filter,1);
+        return spatially_filter_image_separable(in_img,out_img,row_filter,col_filter,1);
     }
 
 // ----------------------------------------------------------------------------------------
@@ -260,7 +266,7 @@ namespace dlib
         typename EXP2,
         typename T
         >
-    void spatially_filter_image_separable_down (
+    rectangle spatially_filter_image_separable_down (
         const unsigned long downsample,
         const in_image_type& in_img,
         out_image_type& out_img,
@@ -300,7 +306,7 @@ namespace dlib
         if (in_img.size() == 0)
         {
             out_img.clear();
-            return;
+            return rectangle();
         }
 
         out_img.set_size((long)(std::ceil((double)in_img.nr()/downsample)),
@@ -312,11 +318,12 @@ namespace dlib
         // figure out the range that we should apply the filter to
         const long first_row = (long)std::ceil(col_border/downsample);
         const long first_col = (long)std::ceil(row_border/downsample);
-        const long last_row  = (long)std::ceil((in_img.nr() - col_border)/downsample);
-        const long last_col  = (long)std::ceil((in_img.nc() - row_border)/downsample);
+        const long last_row  = (long)std::ceil((in_img.nr() - col_border)/downsample) - 1;
+        const long last_col  = (long)std::ceil((in_img.nc() - row_border)/downsample) - 1;
 
         // zero border pixels
-        border_enumerator be(get_rect(out_img), rectangle(first_col, first_row, last_col-1, last_row-1));
+        const rectangle non_border = rectangle(first_col, first_row, last_col, last_row);
+        border_enumerator be(get_rect(out_img), non_border );
         while (be.move_next())
         {
             out_img[be.element().y()][be.element().x()] = 0;
@@ -331,7 +338,7 @@ namespace dlib
         // apply the row filter
         for (long r = 0; r < temp_img.nr(); ++r)
         {
-            for (long c = first_col; c < last_col; ++c)
+            for (long c = non_border.left(); c <= non_border.right(); ++c)
             {
                 ptype p;
                 ptype temp = 0;
@@ -346,9 +353,9 @@ namespace dlib
         }
 
         // apply the column filter 
-        for (long r = first_row; r < last_row; ++r)
+        for (long r = non_border.top(); r <= non_border.bottom(); ++r)
         {
-            for (long c = first_col; c < last_col; ++c)
+            for (long c = non_border.left(); c <= non_border.right(); ++c)
             {
                 ptype temp = 0;
                 for (long m = 0; m < col_filter.size(); ++m)
@@ -375,6 +382,8 @@ namespace dlib
                 }
             }
         }
+
+        return non_border;
     }
 
     template <
@@ -383,7 +392,7 @@ namespace dlib
         typename EXP1,
         typename EXP2
         >
-    void spatially_filter_image_separable_down (
+    rectangle spatially_filter_image_separable_down (
         const unsigned long downsample,
         const in_image_type& in_img,
         out_image_type& out_img,
@@ -391,7 +400,7 @@ namespace dlib
         const matrix_exp<EXP2>& col_filter
     )
     {
-        spatially_filter_image_separable_down(downsample,in_img,out_img,row_filter,col_filter,1);
+        return spatially_filter_image_separable_down(downsample,in_img,out_img,row_filter,col_filter,1);
     }
 
 // ----------------------------------------------------------------------------------------

dlib/image_transforms/spatial_filtering_abstract.h

@@ -17,7 +17,7 @@ namespace dlib
         typename EXP,
         typename T
         >
-    void spatially_filter_image (
+    rectangle spatially_filter_image (
         const in_image_type& in_img,
         out_image_type& out_img,
         const matrix_exp<EXP>& filter,
@@ -54,6 +54,8 @@ namespace dlib
               inside the image are always set to zero.
             - #out_img.nc() == in_img.nc()
             - #out_img.nr() == in_img.nr()
+            - returns a rectangle which indicates what pixels in #out_img are considered 
+              non-border pixels and therefore contain output from the filter.
     !*/
 
 // ----------------------------------------------------------------------------------------
@@ -65,7 +67,7 @@ namespace dlib
         typename EXP2,
         typename T
         >
-    void spatially_filter_image_separable (
+    rectangle spatially_filter_image_separable (
         const in_image_type& in_img,
         out_image_type& out_img,
         const matrix_exp<EXP1>& row_filter,
@@ -108,6 +110,8 @@ namespace dlib
               inside the image are always set to zero.
             - #out_img.nc() == in_img.nc()
             - #out_img.nr() == in_img.nr()
+            - returns a rectangle which indicates what pixels in #out_img are considered 
+              non-border pixels and therefore contain output from the filter.
     !*/
 
 // ----------------------------------------------------------------------------------------
@@ -119,7 +123,7 @@ namespace dlib
         typename EXP2,
         typename T
         >
-    void spatially_filter_image_separable_down (
+    rectangle spatially_filter_image_separable_down (
         const unsigned long downsample,
         const in_image_type& in_img,
         out_image_type& out_img,
@@ -151,6 +155,8 @@ namespace dlib
                 - #out_img.nr() == ceil((double)in_img.nr()/downsample)
                 - #out_img.nc() == ceil((double)in_img.nc()/downsample)
                 - #out_img[r][c] == filtered pixel corresponding to in_img[r*downsample][c*downsample]
+            - returns a rectangle which indicates what pixels in #out_img are considered 
+              non-border pixels and therefore contain output from the filter.
     !*/
 
 // ----------------------------------------------------------------------------------------

dlib/test/image.cpp

@@ -778,7 +778,8 @@ namespace
                   1,1,1,1,1;
 
         assign_all_pixels(img2,3);
-        spatially_filter_image(img, img2, filter2);
+        rectangle brect = spatially_filter_image(img, img2, filter2);
+        DLIB_TEST(brect == shrink_rect(get_rect(img), filter2.nc()/2, filter2.nr()/2));
 
         const rectangle rect(2,1,img.nc()-3,img.nr()-2);
 
@@ -800,7 +801,8 @@ namespace
 
         assign_all_pixels(img2,3);
         assign_all_pixels(img3,3);
-        spatially_filter_image(img, img2, filter2);
+        brect = spatially_filter_image(img, img2, filter2);
+        DLIB_TEST(brect == shrink_rect(get_rect(img), filter2.nc()/2, filter2.nr()/2));
 
         matrix<int,1,5> row_filter;
         matrix<int,1,3> col_filter;
@@ -839,9 +841,13 @@ namespace
             assign_all_pixels(img2,3);
             assign_all_pixels(img3,3);
             // Just make sure both filtering methods give the same results.
-            spatially_filter_image(img, img2, filter, scale, use_abs);
-            spatially_filter_image_separable(img, img3, row_filter, col_filter, scale, use_abs);
+            rectangle brect1, brect2;
+            brect1 = spatially_filter_image(img, img2, filter, scale, use_abs);
+            brect2 = spatially_filter_image_separable(img, img3, row_filter, col_filter, scale, use_abs);
             DLIB_TEST(array_to_matrix(img2) == array_to_matrix(img3));
+
+            DLIB_TEST(brect1 == shrink_rect(get_rect(img), filter.nc()/2, filter.nr()/2));
+            DLIB_TEST(brect1 == brect2);
         }
 
         {