Added missing comments and asserts.

--HG--
extra : convert_revision : svn%3Afdd8eb12-d10e-0410-9acb-85c331704f74/trunk%403049

dlib/image_keypoint/hessian_pyramid.h

@@ -109,7 +109,6 @@ namespace dlib
                                          img.get_sum_of_area(centered_rect(p+tl, lobe_size, lobe_size)) -
                                          img.get_sum_of_area(centered_rect(p+br, lobe_size, lobe_size));
 
-                            //std::cout << "(((((: " << Dxx << "  " << Dyy << "  " << Dxy << std::endl;
                             // now we normalize the filter responses
                             Dxx *= area_inv;
                             Dyy *= area_inv;
@@ -127,7 +126,6 @@ namespace dlib
                             if (determinant < 0)
                                 determinant = 0;
 
-                            //std::cout << "****: " << Dxx << "  " << Dyy << "  " << Dxy << std::endl;
                             // Save the determinant of the Hessian into our image pyramid.  Also
                             // pack the laplacian sign into the value so we can get it out later.
                             pyramid[o*num_intervals + i][r/step_size][c/step_size] = sign_of_laplacian*determinant;
@@ -413,6 +411,11 @@ namespace dlib
         std::vector<interest_point,Alloc>& result_points
     )
     {
+        DLIB_ASSERT(threshold > 0,
+            "\tvoid get_interest_points()"
+            << "\n\t Invalid arguments to this function"
+            << "\n\t threshold: " << threshold 
+        );
         using namespace std;
         using namespace hessian_pyramid_helpers;
 

dlib/image_keypoint/hessian_pyramid_abstract.h

@@ -173,6 +173,8 @@ namespace dlib
                 hessian_pyramid object.  Its fields have the following
                 meanings:
                     - center == the x/y location of the center of the interest point
+                      (in image space coordinates.  y gives the row and x gives the
+                      column in the image)
                     - scale == the scale at which the point was detected
                     - score == the determinant of the Hessian for the interest point
                     - laplacian == the sign of the laplacian for the interest point

dlib/image_keypoint/surf.h

@@ -17,16 +17,17 @@ namespace dlib
         interest_point p;
         matrix<double,64,1> des;
         double angle;
-
-        double match_score;
-
-        bool operator < (const surf_point& p) const { return match_score < p.match_score; }
     };
 
 // ----------------------------------------------------------------------------------------
 
     inline double gaussian (double x, double y, double sig)
     {
+        DLIB_ASSERT(sig > 0,
+            "\tdouble gaussian()"
+            << "\n\t sig must be bigger than 0"
+            << "\n\t sig: " << sig 
+        );
         const double pi = 3.1415926535898;
         return 1.0/(sig*std::sqrt(2*pi)) * std::exp( -(x*x + y*y)/(2*sig*sig));
     }
@@ -40,7 +41,8 @@ namespace dlib
         const double& scale
     )
     {
-        DLIB_ASSERT(get_rect(img).contains(centered_rect(center, 17*scale,17*scale)) == true,
+        DLIB_ASSERT(get_rect(img).contains(centered_rect(center, 17*scale,17*scale)) == true &&
+                    scale > 0,
             "\tdouble compute_dominant_angle(img, center, scale)"
             << "\n\tAll arguments to this function must be > 0"
             << "\n\t get_rect(img): " << get_rect(img) 
@@ -71,7 +73,6 @@ namespace dlib
             }
         }
 
-        //cout << "ang size: " << ang.size() << endl;
 
         // now find the dominant direction
         double max_length = 0;
@@ -94,15 +95,12 @@ namespace dlib
                 if (ang1 <= ang[i] && ang[i] <= ang2)
                 {
                     vect += samples[i];
-                    //cout << ".";
                 }
                 else if (ang2 > pi && (ang[i] >= ang1 || ang[i] <= (-2*pi+ang2)))
                 {
                     vect += samples[i];
-                    //cout << ".";
                 }
             }
-            //cout << "$";
 
 
             // record the angle of the best vectors
@@ -127,7 +125,8 @@ namespace dlib
         matrix<double,64,1,MM,L>& des
     )
     {
-        DLIB_ASSERT(get_rect(img).contains(centered_rect(center, 31*scale,31*scale)) == true,
+        DLIB_ASSERT(get_rect(img).contains(centered_rect(center, 31*scale,31*scale)) == true &&
+                    scale > 0,
             "\tvoid compute_surf_descriptor(img, center, scale, angle)"
             << "\n\tAll arguments to this function must be > 0"
             << "\n\t get_rect(img): " << get_rect(img) 
@@ -186,12 +185,21 @@ namespace dlib
         long max_points
     )
     {
-        integral_image int_img;
+        DLIB_ASSERT(max_points > 0,
+            "\t std::vector<surf_point> get_surf_points()"
+            << "\n\t invalid arguments to this function"
+            << "\n\t max_points: " << max_points 
+        );
 
+        // make an integral image first
+        integral_image int_img;
         int_img.load(img);
+
+        // now make a hessian pyramid
         hessian_pyramid pyr;
         pyr.build_pyramid(int_img, 4, 6, 2);
 
+        // now get all the interest points from the hessian pyramid
         std::vector<interest_point> points; 
         get_interest_points(pyr, 0.10, points);
         std::vector<surf_point> spoints;
@@ -199,22 +207,19 @@ namespace dlib
         // sort all the points by how strong their detect is
         std::sort(points.rbegin(), points.rend());
 
-
         // now extract SURF descriptors for the points
+        surf_point sp;
         for (unsigned long i = 0; i < std::min((size_t)max_points,points.size()); ++i)
         {
             // ignore points that are close to the edge of the image
             const double border = 31;
-            //const double border = std::sqrt(22.0*22 + 22*22);
             if (get_rect(int_img).contains(centered_rect(points[i].center, border*points[i].scale, border*points[i].scale)))
             {
-                surf_point sp;
                 sp.angle = compute_dominant_angle(int_img, points[i].center, points[i].scale);
                 compute_surf_descriptor(int_img, points[i].center, points[i].scale, sp.angle, sp.des);
                 sp.p = points[i];
 
                 spoints.push_back(sp);
-
             }
         }
 

dlib/image_keypoint/surf_abstract.h

@@ -9,6 +9,20 @@
 
 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 Bay1 , Tinne Tuytelaars2 , and Luc Van Gool12
+
+        This paper provides a nice detailed overview of how the algorithm works:
+            Notes on the OpenSURF Library by Christopher Evans
+    */
 
 // ----------------------------------------------------------------------------------------
     
@@ -18,11 +32,12 @@ namespace dlib
         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.
     !*/
-    {
-        const double pi = 3.1415926535898;
-        return 1.0/(sig*std::sqrt(2*pi)) * std::exp( -(x*x + y*y)/(2*sig*sig));
-    }
 
 // ----------------------------------------------------------------------------------------
 
@@ -39,6 +54,11 @@ namespace dlib
             - 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())
     !*/
 
 // ----------------------------------------------------------------------------------------
@@ -58,6 +78,11 @@ namespace dlib
             - scale > 0
             - get_rect(img).contains(centered_rect(center, 31*scale, 31*scale)) == true
               (i.e. center can't be within 31*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.
     !*/
 
 // ----------------------------------------------------------------------------------------
@@ -66,16 +91,13 @@ namespace dlib
     {
         /*!
             WHAT THIS OBJECT REPRESENTS
-                This object represents a detected SURF point.
+                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;
-
-        double match_score;
-
-        bool operator < (const surf_point& p) const { return match_score < p.match_score; }
     };
 
 // ----------------------------------------------------------------------------------------
@@ -88,6 +110,21 @@ namespace dlib
     /*!
         requires
             - max_points > 0
+            - image_type == a type that implements the array2d/array2d_kernel_abstract.h interface
+            - pixel_traits<image_type::type> must be defined
+        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())
     !*/
 
 // ----------------------------------------------------------------------------------------