Added distance_to_line() and clip_line_to_rectangle()

dlib/geometry/rectangle.h

@@ -450,6 +450,86 @@ namespace dlib
         return temp;
     }
 
+// ----------------------------------------------------------------------------------------
+
+    template <typename T, typename U>
+    double distance_to_line (
+        const std::pair<vector<T,2>,vector<T,2> >& line,
+        const vector<U,2>& p
+    )
+    {
+        const vector<double,2> delta = p-line.second;
+        const double along_dist = (line.first-line.second).normalize().dot(delta);
+        return std::sqrt(std::max(0.0,delta.length_squared() - along_dist*along_dist));
+    }
+
+// ----------------------------------------------------------------------------------------
+
+    inline void clip_line_to_rectangle (
+        const rectangle& box,
+        point& p1,
+        point& p2
+    )
+    {
+        // Now clip the line segment so it is contained inside box.
+        if (p1.x() == p2.x())
+        {
+            if (!box.contains(p1))
+                p1.y() = box.top();
+            if (!box.contains(p2))
+                p2.y() = box.bottom();
+        }
+        else if (p1.y() == p2.y())
+        {
+            if (!box.contains(p1))
+                p1.x() = box.left();
+            if (!box.contains(p2))
+                p2.x() = box.right();
+        }
+        else
+        {
+            // We use these relations to find alpha values.  These values tell us
+            // how to generate points intersecting the rectangle boundaries.  We then
+            // test the resulting points for ones that are inside the rectangle and output
+            // those.
+            //box.left()  == alpha1*(p1.x()-p2.x()) + p2.x();
+            //box.right() == alpha2*(p1.x()-p2.x()) + p2.x();
+
+            const point d = p1-p2;
+            double alpha1 = (box.left()  -p2.x())/(double)d.x();
+            double alpha2 = (box.right() -p2.x())/(double)d.x();
+            double alpha3 = (box.top()   -p2.y())/(double)d.y();
+            double alpha4 = (box.bottom()-p2.y())/(double)d.y();
+
+            const point c1 = alpha1*d + p2;
+            const point c2 = alpha2*d + p2;
+            const point c3 = alpha3*d + p2;
+            const point c4 = alpha4*d + p2;
+
+            if (!box.contains(p1))
+                p1 = c1;
+            if (!box.contains(p2))
+                p2 = c2;
+            if (box.contains(c3))
+            {
+                if (!box.contains(p2))
+                    p2 = c3;
+                else if (!box.contains(p1))
+                    p1 = c3;
+            }
+            if (box.contains(c4))
+            {
+                if (!box.contains(p2))
+                    p2 = c4;
+                else if (!box.contains(p1))
+                    p1 = c4;
+            }
+        }
+
+        p1 = nearest_point(box, p1);
+        p2 = nearest_point(box, p2);
+    }
+
 // ----------------------------------------------------------------------------------------
 
     inline const rectangle centered_rect (

dlib/geometry/rectangle_abstract.h

@@ -705,6 +705,41 @@ namespace dlib
             - returns the Manhattan distance between the edge of rect and p.
     !*/
 
+// ----------------------------------------------------------------------------------------
+
+    template <typename T, typename U>
+    double distance_to_line (
+        const std::pair<vector<T,2>,vector<T,2> >& line,
+        const vector<U,2>& p
+    );
+    /*!
+        ensures
+            - returns the euclidean distance between the given line and the point p.  That
+              is, given a line that passes though the points line.first and line.second,
+              what is the distance between p and the nearest point on the line?  This
+              function returns that distance.
+    !*/
+
+// ----------------------------------------------------------------------------------------
+
+    void clip_line_to_rectangle (
+        const rectangle& box,
+        point& p1,
+        point& p2
+    );
+    /*!
+        ensures
+            - clips the line segment that goes from points p1 to p2 so that it is entirely
+              within the given box.  In particular, we will have:
+                - box.contains(#p1) == true
+                - box.contains(#p2) == true
+                - The line segment #p1 to #p2 is entirely contained within the line segment
+                  p1 to p2.  Moreover, #p1 to #p2 is the largest such line segment that
+                  fits within the given box.
+            - If the line segment does not intersect the box then the result is some
+              arbitrary line segment inside the box.
+    !*/
+
 // ----------------------------------------------------------------------------------------
 
     template <