[arrayfire] 39/408: Added documentation for nearest neighbour

[Ghislain Vaillant]

This is an automated email from the git hooks/post-receive script.

ghisvail-guest pushed a commit to branch debian/sid
in repository arrayfire.

commit f3d46605af7a9aa38ea70e6227ded6caff8aa484
Author: Shehzan Mohammed <shehzan at arrayfire.com>
Date:   Wed Jun 24 17:38:01 2015 -0400

    Added documentation for nearest neighbour
---
 docs/details/vision.dox | 20 +++++++++++++++++++
 include/af/vision.h     | 51 +++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 71 insertions(+)

diff --git a/docs/details/vision.dox b/docs/details/vision.dox
index 9d96cac..250c90e 100644
--- a/docs/details/vision.dox
+++ b/docs/details/vision.dox
@@ -48,6 +48,26 @@ equal to the number of features contained in the query array.
 
 =======================================================================
 
+\defgroup cv_func_nearest_neighbour nearestNeighbour
+\ingroup featmatcher_mat
+
+\brief Nearest Neighbour
+
+Calculates nearest distances between two 2-dimensional arrays containing
+features based on the type of distance computation chosen. Currently, \ref
+AF_SAD (sum of absolute differences), \ref AF_SSD (sum of squared differences)
+and \ref AF_SHD (hamming distance) are supported.
+One of the arrays containing the training data and the other the
+query data. One of the dimensions of the both arrays must be equal among them,
+identifying the length of each feature. The other dimension indicates the
+total number of features in each of the training and query arrays. Two
+1-dimensional arrays are created as results, one containg the smallest N
+distances of the query array and another containing the indices of these
+distances in the training array. The resulting 1-dimensional arrays have length
+equal to the number of features contained in the query array.
+
+=======================================================================
+
 \defgroup cv_func_match_template matchTemplate
 \ingroup match_mat
 
diff --git a/include/af/vision.h b/include/af/vision.h
index d40a150..9475014 100644
--- a/include/af/vision.h
+++ b/include/af/vision.h
@@ -84,12 +84,39 @@ AFAPI void orb(features& feat, array& desc, const array& image, const float fast
    \param[in]  n_dist is the number of smallest distances to return (currently, only 1
                is supported)
 
+   \note Note: This is a special case of the \ref nearestNeighbour function with AF_SHD
+    as dist_type
+
    \ingroup cv_func_hamming_matcher
  */
 AFAPI void hammingMatcher(array& idx, array& dist,
                           const array& query, const array& train,
                           const dim_t dist_dim=0, const unsigned n_dist=1);
 
+/**
+   C++ Interface wrapper for Nearest Neighbour
+
+   \param[out] idx is an array of MxN size, where M is equal to the number of query
+               features and N is equal to n_dist. The value at position IxJ indicates
+               the index of the Jth smallest distance to the Ith query value in the
+               train data array.
+               the index of the Ith smallest distance of the Mth query.
+   \param[out] dist is an array of MxN size, where M is equal to the number of query
+               features and N is equal to n_dist. The value at position IxJ indicates
+               the distance of the Jth smallest distance to the Ith query value in the
+               train data array based on the dist_type chosen.
+   \param[in]  query is the array containing the data to be queried
+   \param[in]  train is the array containing the data used as training data
+   \param[in]  dist_dim indicates the dimension to analyze for distance (the dimension
+               indicated here must be of equal length for both query and train arrays)
+   \param[in]  n_dist is the number of smallest distances to return (currently, only 1
+               is supported)
+   \param[in]  dist_type is the distance computation type. Currently \ref AF_SAD (sum
+               of absolute differences), \ref AF_SSD (sum of squared differences), and
+               \ref AF_SHD (hamming distances) are supported.
+
+   \ingroup cv_func_nearest_neighbour
+ */
 AFAPI void nearestNeighbour(array& idx, array& dist,
                             const array& query, const array& train,
                             const dim_t dist_dim=0, const unsigned n_dist=1,
@@ -195,6 +222,30 @@ extern "C" {
                                     const af_array query, const af_array train,
                                     const dim_t dist_dim, const unsigned n_dist);
 
+    /**
+        C Interface wrapper for Nearest Neighbour
+
+        \param[out] idx is an array of MxN size, where M is equal to the number of query
+                    features and N is equal to n_dist. The value at position IxJ indicates
+                    the index of the Jth smallest distance to the Ith query value in the
+                    train data array.
+                    the index of the Ith smallest distance of the Mth query.
+        \param[out] dist is an array of MxN size, where M is equal to the number of query
+                    features and N is equal to n_dist. The value at position IxJ indicates
+                    the distance of the Jth smallest distance to the Ith query value in the
+                    train data array based on the dist_type chosen.
+        \param[in]  query is the array containing the data to be queried
+        \param[in]  train is the array containing the data used as training data
+        \param[in]  dist_dim indicates the dimension to analyze for distance (the dimension
+                    indicated here must be of equal length for both query and train arrays)
+        \param[in]  n_dist is the number of smallest distances to return (currently, only 1
+                    is supported)
+        \param[in]  dist_type is the distance computation type. Currently \ref AF_SAD (sum
+                    of absolute differences), \ref AF_SSD (sum of squared differences), and
+                    \ref AF_SHD (hamming distances) are supported.
+
+        \ingroup cv_func_nearest_neighbour
+    */
     AFAPI af_err af_nearest_neighbour(af_array* idx, af_array* dist,
                                       const af_array query, const af_array train,
                                       const dim_t dist_dim, const unsigned n_dist,

-- 
Alioth's /usr/local/bin/git-commit-notice on /srv/git.debian.org/git/debian-science/packages/arrayfire.git