Making hamming_distance more generalized; improving docs

skimage/feature/_brief.py

@@ -27,7 +27,11 @@ def brief(image, keypoints, descriptor_size=256, mode='normal', patch_size=49,
         Length of the two dimensional square patch sampling region around
         the keypoints. Default is 49.
     sample_seed : int
-        Seed for sampling the decision pixel-pairs. Default is 1.
+        Seed for sampling the decision pixel-pairs. From a square window with
+        length patch_size, pixel pairs are sampled using the `mode` parameter
+        to build the descriptors using intensity comparison. The value of
+        `sample_seed` should be the same for the images to be matched while
+        building the descriptors. Default is 1. 
     variance : float
         Variance of the Gaussian Low Pass filter applied on the image to
         alleviate noise sensitivity. Default is 2.
@@ -37,8 +41,8 @@ def brief(image, keypoints, descriptor_size=256, mode='normal', patch_size=49,
 
     Returns
     -------
-    descriptors : (Q, descriptor_size) ndarray of dtype bool
-        2D ndarray of binary descriptors of size descriptor_size about Q
+    descriptors : (Q, `descriptor_size`) ndarray of dtype bool
+        2D ndarray of binary descriptors of size `descriptor_size` about Q
         keypoints after filtering out border keypoints with value at an index
         (i, j) either being True or False representing the outcome
         of Intensity comparison about ith keypoint on jth decision pixel-pair.
@@ -136,14 +140,13 @@ def brief(image, keypoints, descriptor_size=256, mode='normal', patch_size=49,
 
     image = np.ascontiguousarray(image)
 
-    keypoints = np.array(keypoints + 0.5, dtype=np.intp, order='C')
+    keypoints = np.array(keypoints + 0.5, dtype=np.intp)
 
-    # Removing keypoints that are (patch_size / 2) distance from the image
-    # border
+    # Removing keypoints that are within (patch_size / 2) distance from the
+    # image border
     keypoints = _remove_border_keypoints(image, keypoints, patch_size / 2)
 
-    descriptors = np.zeros((keypoints.shape[0], descriptor_size),
-                           dtype=bool, order='C')
+    descriptors = np.zeros((keypoints.shape[0], descriptor_size), dtype=bool)
 
     # Sampling pairs of decision pixels in patch_size x patch_size window
     if mode == 'normal':

skimage/feature/util.py

@@ -15,35 +15,27 @@ def _remove_border_keypoints(image, keypoints, dist):
     return keypoints
 
 
-def hamming_distance(descriptors1, descriptors2):
+def hamming_distance(array1, array2):
     """A dissimilarity measure used for matching keypoints in different images
     using binary feature descriptors like BRIEF etc.
 
     Parameters
     ----------
-    descriptors1 : (P1, D) array of dtype bool
-        Binary feature descriptors for keypoints in the first image.
-        2D ndarray with a binary descriptors of size D about P1 keypoints
-        with value at an index (i, j) either being True or False representing
-        the outcome of Intensity comparison about ith keypoint on jth decision
-        pixel-pair.
-    descriptors2 : (P2, D) array of dtype bool
-        Binary feature descriptors for keypoints in the second image.
-        2D ndarray with a binary descriptors of size D about P2 keypoints
-        with value at an index (i, j) either being True or False representing
-        the outcome of Intensity comparison about ith keypoint on jth decision
-        pixel-pair.
+    array1 : (P1, D) array of dtype bool
+        P1 vectors of size D with boolean elements.
+    array2 : (P2, D) array of dtype bool
+        P2 vectors of size D with boolean elements.
 
     Returns
     -------
     distance : (P1, P2) array of dtype float
         2D ndarray with value at an index (i, j) in the range [0, 1]
-        representing the extent of dissimilarity between ith keypoint of in
-        first image and jth keypoint in second image.
+        representing the hamming distance between ith vector in
+        array1 and jth vector in array2.
 
     """
-    distance = np.zeros((descriptors1.shape[0], descriptors2.shape[0]), dtype=float)
-    for i in range(descriptors1.shape[0]):
-        for j in range(descriptors2.shape[0]):
-            distance[i, j] = hamming(descriptors1[i, :], descriptors2[j, :])
+    distance = np.zeros((array1.shape[0], array2.shape[0]), dtype=float)
+    for i in range(array1.shape[0]):
+        for j in range(array2.shape[0]):
+            distance[i, j] = hamming(array1[i, :], array2[j, :])
     return distance