Added subm_clipped()

dlib/matrix/matrix_subexp.h

@@ -121,6 +121,25 @@ namespace dlib
         return matrix_op<op>(op(m.ref(),r,c,nr,nc));
     }
 
+// ----------------------------------------------------------------------------------------
+
+    template <
+        typename EXP
+        >
+    const matrix_op<op_subm<EXP> > subm_clipped (
+        const matrix_exp<EXP>& m,
+        long r, 
+        long c,
+        long nr,
+        long nc
+    )
+    {
+        rectangle box(c,r,c+nc-1,r+nr-1);
+        box = box.intersect(get_rect(m));
+        typedef op_subm<EXP> op;
+        return matrix_op<op>(op(m.ref(),box.top(),box.left(),box.height(),box.width()));
+    }
+
 // ----------------------------------------------------------------------------------------
 
     template <
@@ -146,6 +165,22 @@ namespace dlib
         return matrix_op<op>(op(m.ref(),rect.top(),rect.left(),rect.height(),rect.width()));
     }
 
+// ----------------------------------------------------------------------------------------
+
+    template <
+        typename EXP
+        >
+    const matrix_op<op_subm<EXP> > subm_clipped (
+        const matrix_exp<EXP>& m,
+        rectangle rect
+    )
+    {
+        rect = rect.intersect(get_rect(m));
+
+        typedef op_subm<EXP> op;
+        return matrix_op<op>(op(m.ref(),rect.top(),rect.left(),rect.height(),rect.width()));
+    }
+
 // ----------------------------------------------------------------------------------------
 
     template <typename M1, typename M2, typename M3>

dlib/matrix/matrix_subexp_abstract.h

@@ -105,6 +105,30 @@ namespace dlib
                   R(r, c) == m(r+row,c+col)
     !*/
 
+// ----------------------------------------------------------------------------------------
+
+    const matrix_exp subm_clipped (
+        const matrix_exp& m,
+        long row,
+        long col,
+        long nr,
+        long nc
+    );
+    /*!
+        ensures
+            - This function is just like subm() except that it will automatically clip the
+              indicated sub matrix window so that it does not extend outside m.
+              In particular:
+                - Let box = rectangle(col,row,col+nc-1,row+nr-1)
+                  (i.e. the box that contains the indicated sub matrix)
+                - Let box_clipped = box.intersect(get_rect(m))
+                - Then this function returns a matrix R such that:
+                    - R.nr() == box_clipped.height()
+                    - R.nc() == box_clipped.width()
+                    - for all valid r and c:
+                      R(r, c) == m(r+box_clipped.top(),c+box_clipped.left())
+    !*/
+
 // ----------------------------------------------------------------------------------------
 
     const matrix_exp subm (
@@ -123,6 +147,22 @@ namespace dlib
                   R(r, c) == m(r+rect.top(), c+rect.left())
     !*/
 
+// ----------------------------------------------------------------------------------------
+
+    const matrix_exp subm_clipped (
+        const matrix_exp& m,
+        const rectangle& rect
+    );
+    /*!
+        ensures
+            - Let box_clipped == rect.intersect(get_rect(m))
+            - returns a matrix R such that:
+                - R.nr() == box_clipped.height()  
+                - R.nc() == box_clipped.width()
+                - for all valid r and c:
+                  R(r, c) == m(r+box_clipped.top(), c+box_clipped.left())
+    !*/
+
 // ----------------------------------------------------------------------------------------
 
     const matrix_exp rowm (

dlib/test/matrix.cpp

@@ -433,6 +433,8 @@ namespace
                 {
                     DLIB_TEST(subm(a,1,2,2,3)(r,c) == (r+1)*a.nc() + c+2);
                     DLIB_TEST(subm(a,1,2,2,3) == subm(a,rect));
+                    DLIB_TEST(subm_clipped(a,1,2,2,3) == subm(a,rect));
+                    DLIB_TEST(subm_clipped(a,1,2,2,3) == subm_clipped(a,rect));
                 }
             }