Merging upstream version 1.44.3.

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 163 insertions, 0 deletions

diff --git a/ml/dlib/dlib/image_keypoint/surf_abstract.h b/ml/dlib/dlib/image_keypoint/surf_abstract.h
new file mode 100644
index 000000000..e539f3e24
--- /dev/null
+++ b/ml/dlib/dlib/image_keypoint/surf_abstract.h
@@ -0,0 +1,163 @@
+// Copyright (C) 2009  Davis E. King (davis@dlib.net)
+// License: Boost Software License   See LICENSE.txt for the full license.
+#undef DLIB_SURf_ABSTRACT_H_
+#ifdef DLIB_SURf_ABSTRACT_H_
+
+#include "hessian_pyramid_abstract.h"
+#include "../geometry/vector_abstract.h"
+#include "../matrix/matrix_abstract.h"
+#include "../image_processing/generic_image.h"
+
+namespace dlib
+{
+    /*
+        The functions in this file implement the components of the SURF algorithm
+        for extracting scale invariant feature descriptors from images.
+
+        For the full story on what this algorithm does and how it works
+        you should refer to the following papers.
+
+        This is the original paper which introduced the algorithm:
+            SURF: Speeded Up Robust Features
+            By Herbert Bay, Tinne Tuytelaars, and Luc Van Gool
+
+        This paper provides a nice detailed overview of how the algorithm works:
+            Notes on the OpenSURF Library by Christopher Evans
+    */
+
+// ----------------------------------------------------------------------------------------
+    
+    double gaussian (
+        double x, 
+        double y,
+        double sig
+    );
+    /*!
+        requires
+            - sig > 0
+        ensures
+            - computes and returns the value of a 2D Gaussian function with mean 0 
+              and standard deviation sig at the given (x,y) point.
+    !*/
+
+// ----------------------------------------------------------------------------------------
+
+    template <typename integral_image_type, typename T>
+    double compute_dominant_angle (
+        const integral_image_type& img,
+        const dlib::vector<T,2>& center,
+        const double& scale
+    );
+    /*!
+        requires
+            - integral_image_type == an object such as dlib::integral_image or another
+              type that implements the interface defined in image_transforms/integral_image_abstract.h
+            - scale > 0
+            - get_rect(img).contains(centered_rect(center, 17*scale, 17*scale)) == true
+              (i.e. center can't be within 17*scale pixels of the edge of the image)
+        ensures
+            - computes and returns the dominant angle (i.e. the angle of the dominant gradient)
+              at the given center point and scale in img.  
+            - The returned angle is in radians.  Specifically, if the angle is described by
+              a vector vect then the angle is exactly the value of std::atan2(vect.y(), vect.x())
+    !*/
+
+// ----------------------------------------------------------------------------------------
+
+    template <typename integral_image_type, typename T, typename MM, typename L>
+    void compute_surf_descriptor (
+        const integral_image_type& img,
+        const dlib::vector<T,2>& center,
+        const double scale,
+        const double angle,
+        matrix<double,64,1,MM,L>& des
+    )
+    /*!
+        requires
+            - integral_image_type == an object such as dlib::integral_image or another
+              type that implements the interface defined in image_transforms/integral_image_abstract.h
+            - scale > 0
+            - get_rect(img).contains(centered_rect(center, 32*scale, 32*scale)) == true
+              (i.e. center can't be within 32*scale pixels of the edge of the image)
+        ensures
+            - computes the 64 dimensional SURF descriptor vector of a box centered
+              at the given center point, tilted at an angle determined by the given 
+              angle, and sized according to the given scale.  
+            - #des == the computed SURF descriptor vector extracted from the img object.
+            - The angle is measured in radians and measures the degree of counter-clockwise 
+              rotation around the center point.  This is the same kind of rotation as is 
+              performed by the dlib::rotate_point() function.
+    !*/
+
+// ----------------------------------------------------------------------------------------
+
+    struct surf_point
+    {
+        /*!
+            WHAT THIS OBJECT REPRESENTS
+                This object represents a detected SURF point.  The meanings of 
+                its fields are defined below in the get_surf_points() function.
+        !*/
+
+        interest_point p;
+        matrix<double,64,1> des;
+        double angle;
+    };
+
+// ----------------------------------------------------------------------------------------
+
+    void serialize (
+        const surf_point& item,
+        std::ostream& out
+    );
+    /*!
+        provides serialization support
+    !*/
+
+    void deserialize (
+        surf_point& item,
+        std::istream& in 
+    );
+    /*!
+        provides serialization support
+    !*/
+
+// ----------------------------------------------------------------------------------------
+
+    template <typename image_type>
+    const std::vector<surf_point> get_surf_points (
+        const image_type& img,
+        long max_points = 10000,
+        double detection_threshold = 30.0
+    );
+    /*!
+        requires
+            - max_points > 0
+            - detection_threshold >= 0
+            - image_type == an image object that implements the interface defined in
+              dlib/image_processing/generic_image.h 
+            - Let P denote the type of pixel in img, then we require:
+                - pixel_traits<P>::has_alpha == false 
+        ensures
+            - This function runs the complete SURF algorithm on the given input image and 
+              returns the points it found. 
+            - returns a vector V such that:
+                - V.size() <= max_points
+                - for all valid i:
+                    - V[i] == a SURF point found in the given input image img
+                    - V[i].p == the interest_point extracted from the hessian pyramid for this
+                      SURF point.
+                    - V[i].des == the SURF descriptor for this point (calculated using 
+                      compute_surf_descriptor())
+                    - V[i].angle == the angle of the SURF box at this point (calculated using 
+                      compute_dominant_angle())
+                    - V[i].p.score >= detection_threshold
+    !*/
+
+// ----------------------------------------------------------------------------------------
+
+}
+
+#endif // DLIB_SURf_ABSTRACT_H_
+
+