Doxygen documentation: calib3d and features2d modules

modules/calib3d/include/opencv2/calib3d/calib3d_c.h

@@ -50,6 +50,10 @@
 extern "C" {
 #endif
 
+/** @addtogroup calib3d_c
+  @{
+  */
+
 /****************************************************************************************\
 *                      Camera Calibration, Pose Estimation and Stereo                    *
 \****************************************************************************************/
@@ -371,6 +375,8 @@ CVAPI(void)  cvReprojectImageTo3D( const CvArr* disparityImage,
                                    CvArr* _3dImage, const CvMat* Q,
                                    int handleMissingValues CV_DEFAULT(0) );
 
+/** @} calib3d_c */
+
 #ifdef __cplusplus
 } // extern "C"
 

modules/features2d/include/opencv2/features2d.hpp

@@ -46,18 +46,54 @@
 #include "opencv2/core.hpp"
 #include "opencv2/flann/miniflann.hpp"
 
+/**
+  @defgroup features2d 2D Features Framework
+  @{
+    @defgroup features2d_main Feature Detection and Description
+    @defgroup features2d_match Descriptor Matchers
+
+Matchers of keypoint descriptors in OpenCV have wrappers with a common interface that enables you to
+easily switch between different algorithms solving the same problem. This section is devoted to
+matching descriptors that are represented as vectors in a multidimensional space. All objects that
+implement vector descriptor matchers inherit the DescriptorMatcher interface.
+
+@note
+   -   An example explaining keypoint matching can be found at
+        opencv\_source\_code/samples/cpp/descriptor\_extractor\_matcher.cpp
+    -   An example on descriptor matching evaluation can be found at
+        opencv\_source\_code/samples/cpp/detector\_descriptor\_matcher\_evaluation.cpp
+    -   An example on one to many image matching can be found at
+        opencv\_source\_code/samples/cpp/matching\_to\_many\_images.cpp
+
+    @defgroup features2d_draw Drawing Function of Keypoints and Matches
+    @defgroup features2d_category Object Categorization
+
+This section describes approaches based on local 2D features and used to categorize objects.
+
+@note
+   -   A complete Bag-Of-Words sample can be found at
+        opencv\_source\_code/samples/cpp/bagofwords\_classification.cpp
+    -   (Python) An example using the features2D framework to perform object categorization can be
+        found at opencv\_source\_code/samples/python2/find\_obj.py
+
+  @}
+ */
+
 namespace cv
 {
 
+//! @addtogroup features2d
+//! @{
+
 // //! writes vector of keypoints to the file storage
 // CV_EXPORTS void write(FileStorage& fs, const String& name, const std::vector<KeyPoint>& keypoints);
 // //! reads vector of keypoints from the specified file storage node
 // CV_EXPORTS void read(const FileNode& node, CV_OUT std::vector<KeyPoint>& keypoints);
 
-/*
+/** @brief A class filters a vector of keypoints.
- * A class filters a vector of keypoints.
+
- * Because now it is difficult to provide a convenient interface for all usage scenarios of the keypoints filter class,
+ Because now it is difficult to provide a convenient interface for all usage scenarios of the
- * it has only several needed by now static methods.
+ keypoints filter class, it has only several needed by now static methods.
  */
 class CV_EXPORTS KeyPointsFilter
 {
@@ -91,44 +127,66 @@ public:
 
 /************************************ Base Classes ************************************/
 
-/*
+/** @brief Abstract base class for 2D image feature detectors and descriptor extractors
- * Abstract base class for 2D image feature detectors and descriptor extractors
+*/
- */
 class CV_EXPORTS_W Feature2D : public virtual Algorithm
 {
 public:
     virtual ~Feature2D();
 
-    /*
+    /** @brief Detects keypoints in an image (first variant) or image set (second variant).
-     * Detect keypoints in an image.
+
-     * image        The image.
+    @param image Image.
-     * keypoints    The detected keypoints.
+    @param keypoints The detected keypoints. In the second variant of the method keypoints[i] is a set
-     * mask         Mask specifying where to look for keypoints (optional). Must be a char
+    of keypoints detected in images[i] .
-     *              matrix with non-zero values in the region of interest.
+    @param mask Mask specifying where to look for keypoints (optional). It must be a 8-bit integer
+    matrix with non-zero values in the region of interest.
      */
     CV_WRAP virtual void detect( InputArray image,
                                  CV_OUT std::vector<KeyPoint>& keypoints,
                                  InputArray mask=noArray() );
 
+    /** @overload
+    @param images Image set.
+    @param keypoints The detected keypoints. In the second variant of the method keypoints[i] is a set
+    of keypoints detected in images[i] .
+    @param masks Masks for each input image specifying where to look for keypoints (optional).
+    masks[i] is a mask for images[i].
+    */
     virtual void detect( InputArrayOfArrays images,
                          std::vector<std::vector<KeyPoint> >& keypoints,
                          InputArrayOfArrays masks=noArray() );
 
-    /*
+    /** @brief Computes the descriptors for a set of keypoints detected in an image (first variant) or image set
-     * Compute the descriptors for a set of keypoints in an image.
+    (second variant).
-     * image        The image.
+
-     * keypoints    The input keypoints. Keypoints for which a descriptor cannot be computed are removed.
+    @param image Image.
-     * descriptors  Copmputed descriptors. Row i is the descriptor for keypoint i.
+    @param keypoints Input collection of keypoints. Keypoints for which a descriptor cannot be
+    computed are removed. Sometimes new keypoints can be added, for example: SIFT duplicates keypoint
+    with several dominant orientations (for each orientation).
+    @param descriptors Computed descriptors. In the second variant of the method descriptors[i] are
+    descriptors computed for a keypoints[i]. Row j is the keypoints (or keypoints[i]) is the
+    descriptor for keypoint j-th keypoint.
      */
     CV_WRAP virtual void compute( InputArray image,
                                   CV_OUT CV_IN_OUT std::vector<KeyPoint>& keypoints,
                                   OutputArray descriptors );
 
+    /** @overload
+
+    @param images Image set.
+    @param keypoints Input collection of keypoints. Keypoints for which a descriptor cannot be
+    computed are removed. Sometimes new keypoints can be added, for example: SIFT duplicates keypoint
+    with several dominant orientations (for each orientation).
+    @param descriptors Computed descriptors. In the second variant of the method descriptors[i] are
+    descriptors computed for a keypoints[i]. Row j is the keypoints (or keypoints[i]) is the
+    descriptor for keypoint j-th keypoint.
+    */
     virtual void compute( InputArrayOfArrays images,
                           std::vector<std::vector<KeyPoint> >& keypoints,
                           OutputArrayOfArrays descriptors );
 
-    /* Detects keypoints and computes the descriptors */
+    /** Detects keypoints and computes the descriptors */
     CV_WRAP virtual void detectAndCompute( InputArray image, InputArray mask,
                                            CV_OUT std::vector<KeyPoint>& keypoints,
                                            OutputArray descriptors,
@@ -138,33 +196,96 @@ public:
     CV_WRAP virtual int descriptorType() const;
     CV_WRAP virtual int defaultNorm() const;
 
-    // Return true if detector object is empty
+    //! Return true if detector object is empty
     CV_WRAP virtual bool empty() const;
 };
 
+/** Feature detectors in OpenCV have wrappers with a common interface that enables you to easily switch
+between different algorithms solving the same problem. All objects that implement keypoint detectors
+inherit the FeatureDetector interface. */
 typedef Feature2D FeatureDetector;
+
+/** Extractors of keypoint descriptors in OpenCV have wrappers with a common interface that enables you
+to easily switch between different algorithms solving the same problem. This section is devoted to
+computing descriptors represented as vectors in a multidimensional space. All objects that implement
+the vector descriptor extractors inherit the DescriptorExtractor interface.
+ */
 typedef Feature2D DescriptorExtractor;
 
-/*!
+//! @addtogroup features2d_main
-  BRISK implementation
+//! @{
-*/
+
+/** @brief Class implementing the BRISK keypoint detector and descriptor extractor, described in @cite LCS11.
+ */
 class CV_EXPORTS_W BRISK : public Feature2D
 {
 public:
+    /** @brief The BRISK constructor
+
+    @param thresh FAST/AGAST detection threshold score.
+    @param octaves detection octaves. Use 0 to do single scale.
+    @param patternScale apply this scale to the pattern used for sampling the neighbourhood of a
+    keypoint.
+     */
     CV_WRAP static Ptr<BRISK> create(int thresh=30, int octaves=3, float patternScale=1.0f);
-    // custom setup
+
+    /** @brief The BRISK constructor for a custom pattern
+
+    @param radiusList defines the radii (in pixels) where the samples around a keypoint are taken (for
+    keypoint scale 1).
+    @param numberList defines the number of sampling points on the sampling circle. Must be the same
+    size as radiusList..
+    @param dMax threshold for the short pairings used for descriptor formation (in pixels for keypoint
+    scale 1).
+    @param dMin threshold for the long pairings used for orientation determination (in pixels for
+    keypoint scale 1).
+    @param indexChange index remapping of the bits. */
     CV_WRAP static Ptr<BRISK> create(const std::vector<float> &radiusList, const std::vector<int> &numberList,
         float dMax=5.85f, float dMin=8.2f, const std::vector<int>& indexChange=std::vector<int>());
 };
 
-/*!
+/** @brief Class implementing the ORB (*oriented BRIEF*) keypoint detector and descriptor extractor
- ORB implementation.
+
-*/
+described in @cite RRKB11. The algorithm uses FAST in pyramids to detect stable keypoints, selects
+the strongest features using FAST or Harris response, finds their orientation using first-order
+moments and computes the descriptors using BRIEF (where the coordinates of random point pairs (or
+k-tuples) are rotated according to the measured orientation).
+ */
 class CV_EXPORTS_W ORB : public Feature2D
 {
 public:
     enum { kBytes = 32, HARRIS_SCORE=0, FAST_SCORE=1 };
 
+    /** @brief The ORB constructor
+
+    @param nfeatures The maximum number of features to retain.
+    @param scaleFactor Pyramid decimation ratio, greater than 1. scaleFactor==2 means the classical
+    pyramid, where each next level has 4x less pixels than the previous, but such a big scale factor
+    will degrade feature matching scores dramatically. On the other hand, too close to 1 scale factor
+    will mean that to cover certain scale range you will need more pyramid levels and so the speed
+    will suffer.
+    @param nlevels The number of pyramid levels. The smallest level will have linear size equal to
+    input\_image\_linear\_size/pow(scaleFactor, nlevels).
+    @param edgeThreshold This is size of the border where the features are not detected. It should
+    roughly match the patchSize parameter.
+    @param firstLevel It should be 0 in the current implementation.
+    @param WTA\_K The number of points that produce each element of the oriented BRIEF descriptor. The
+    default value 2 means the BRIEF where we take a random point pair and compare their brightnesses,
+    so we get 0/1 response. Other possible values are 3 and 4. For example, 3 means that we take 3
+    random points (of course, those point coordinates are random, but they are generated from the
+    pre-defined seed, so each element of BRIEF descriptor is computed deterministically from the pixel
+    rectangle), find point of maximum brightness and output index of the winner (0, 1 or 2). Such
+    output will occupy 2 bits, and therefore it will need a special variant of Hamming distance,
+    denoted as NORM\_HAMMING2 (2 bits per bin). When WTA\_K=4, we take 4 random points to compute each
+    bin (that will also occupy 2 bits with possible values 0, 1, 2 or 3).
+    @param scoreType The default HARRIS\_SCORE means that Harris algorithm is used to rank features
+    (the score is written to KeyPoint::score and is used to retain best nfeatures features);
+    FAST\_SCORE is alternative value of the parameter that produces slightly less stable keypoints,
+    but it is a little faster to compute.
+    @param patchSize size of the patch used by the oriented BRIEF descriptor. Of course, on smaller
+    pyramid layers the perceived image area covered by a feature will be larger.
+    @param fastThreshold
+     */
     CV_WRAP static Ptr<ORB> create(int nfeatures=500, float scaleFactor=1.2f, int nlevels=8, int edgeThreshold=31,
         int firstLevel=0, int WTA_K=2, int scoreType=ORB::HARRIS_SCORE, int patchSize=31, int fastThreshold=20);
 
@@ -196,15 +317,16 @@ public:
     CV_WRAP virtual int getFastThreshold() const = 0;
 };
 
-/*!
+/** @brief Maximally stable extremal region extractor. :
- Maximal Stable Extremal Regions class.
 
- The class implements MSER algorithm introduced by J. Matas.
+The class encapsulates all the parameters of the MSER extraction algorithm (see
- Unlike SIFT, SURF and many other detectors in OpenCV, this is salient region detector,
+<http://en.wikipedia.org/wiki/Maximally_stable_extremal_regions>). Also see
- not the salient point detector.
+<http://code.opencv.org/projects/opencv/wiki/MSER> for useful comments and parameters description.
 
- It returns the regions, each of those is encoded as a contour.
+@note
-*/
+   -   (Python) A complete example showing the use of the MSER detector can be found at
+        opencv\_source\_code/samples/python2/mser.py
+ */
 class CV_EXPORTS_W MSER : public Feature2D
 {
 public:
@@ -231,13 +353,38 @@ public:
     CV_WRAP virtual bool getPass2Only() const = 0;
 };
 
-//! detects corners using FAST algorithm by E. Rosten
+/** @overload */
 CV_EXPORTS void FAST( InputArray image, CV_OUT std::vector<KeyPoint>& keypoints,
                       int threshold, bool nonmaxSuppression=true );
 
+/** @brief Detects corners using the FAST algorithm
+
+@param image grayscale image where keypoints (corners) are detected.
+@param keypoints keypoints detected on the image.
+@param threshold threshold on difference between intensity of the central pixel and pixels of a
+circle around this pixel.
+@param nonmaxSuppression if true, non-maximum suppression is applied to detected corners
+(keypoints).
+@param type one of the three neighborhoods as defined in the paper:
+FastFeatureDetector::TYPE\_9\_16, FastFeatureDetector::TYPE\_7\_12,
+FastFeatureDetector::TYPE\_5\_8
+
+Detects corners using the FAST algorithm by @cite Rosten06.
+
+@note In Python API, types are given as cv2.FAST\_FEATURE\_DETECTOR\_TYPE\_5\_8,
+cv2.FAST\_FEATURE\_DETECTOR\_TYPE\_7\_12 and cv2.FAST\_FEATURE\_DETECTOR\_TYPE\_9\_16. For corner
+detection, use cv2.FAST.detect() method.
+ */
 CV_EXPORTS void FAST( InputArray image, CV_OUT std::vector<KeyPoint>& keypoints,
                       int threshold, bool nonmaxSuppression, int type );
 
+//! @} features2d_main
+
+//! @addtogroup features2d_main
+//! @{
+
+/** @brief Wrapping class for feature detection using the FAST method. :
+ */
 class CV_EXPORTS_W FastFeatureDetector : public Feature2D
 {
 public:
@@ -261,7 +408,8 @@ public:
     CV_WRAP virtual int getType() const = 0;
 };
 
-
+/** @brief Wrapping class for feature detection using the goodFeaturesToTrack function. :
+ */
 class CV_EXPORTS_W GFTTDetector : public Feature2D
 {
 public:
@@ -286,7 +434,37 @@ public:
     CV_WRAP virtual double getK() const = 0;
 };
 
-
+/** @brief Class for extracting blobs from an image. :
+
+The class implements a simple algorithm for extracting blobs from an image:
+
+1.  Convert the source image to binary images by applying thresholding with several thresholds from
+    minThreshold (inclusive) to maxThreshold (exclusive) with distance thresholdStep between
+    neighboring thresholds.
+2.  Extract connected components from every binary image by findContours and calculate their
+    centers.
+3.  Group centers from several binary images by their coordinates. Close centers form one group that
+    corresponds to one blob, which is controlled by the minDistBetweenBlobs parameter.
+4.  From the groups, estimate final centers of blobs and their radiuses and return as locations and
+    sizes of keypoints.
+
+This class performs several filtrations of returned blobs. You should set filterBy\* to true/false
+to turn on/off corresponding filtration. Available filtrations:
+
+-   **By color**. This filter compares the intensity of a binary image at the center of a blob to
+blobColor. If they differ, the blob is filtered out. Use blobColor = 0 to extract dark blobs
+and blobColor = 255 to extract light blobs.
+-   **By area**. Extracted blobs have an area between minArea (inclusive) and maxArea (exclusive).
+-   **By circularity**. Extracted blobs have circularity
+(\f$\frac{4*\pi*Area}{perimeter * perimeter}\f$) between minCircularity (inclusive) and
+maxCircularity (exclusive).
+-   **By ratio of the minimum inertia to maximum inertia**. Extracted blobs have this ratio
+between minInertiaRatio (inclusive) and maxInertiaRatio (exclusive).
+-   **By convexity**. Extracted blobs have convexity (area / area of blob convex hull) between
+minConvexity (inclusive) and maxConvexity (exclusive).
+
+Default values of parameters are tuned to extract dark circular blobs.
+ */
 class CV_EXPORTS_W SimpleBlobDetector : public Feature2D
 {
 public:
@@ -322,9 +500,16 @@ public:
     create(const SimpleBlobDetector::Params &parameters = SimpleBlobDetector::Params());
 };
 
+//! @} features2d_main
+
+//! @addtogroup features2d_main
+//! @{
 
-/*!
+/** @brief Class implementing the KAZE keypoint detector and descriptor extractor, described in @cite ABD12.
-KAZE implementation
+
+@note AKAZE descriptor can only be used with KAZE or AKAZE keypoints .. [ABD12] KAZE Features. Pablo
+F. Alcantarilla, Adrien Bartoli and Andrew J. Davison. In European Conference on Computer Vision
+(ECCV), Fiorenze, Italy, October 2012.
 */
 class CV_EXPORTS_W KAZE : public Feature2D
 {
@@ -337,6 +522,16 @@ public:
         DIFF_CHARBONNIER = 3
     };
 
+    /** @brief The KAZE constructor
+
+    @param extended Set to enable extraction of extended (128-byte) descriptor.
+    @param upright Set to enable use of upright descriptors (non rotation-invariant).
+    @param threshold Detector response threshold to accept point
+    @param nOctaves Maximum octave evolution of the image
+    @param nOctaveLayers Default number of sublevels per scale level
+    @param diffusivity Diffusivity type. DIFF\_PM\_G1, DIFF\_PM\_G2, DIFF\_WEICKERT or
+    DIFF\_CHARBONNIER
+     */
     CV_WRAP static Ptr<KAZE> create(bool extended=false, bool upright=false,
                                     float threshold = 0.001f,
                                     int nOctaves = 4, int nOctaveLayers = 4,
@@ -361,9 +556,13 @@ public:
     CV_WRAP virtual int getDiffusivity() const = 0;
 };
 
-/*!
+/** @brief Class implementing the AKAZE keypoint detector and descriptor extractor, described in @cite ANB13. :
-AKAZE implementation
+
-*/
+@note AKAZE descriptors can only be used with KAZE or AKAZE keypoints. Try to avoid using *extract*
+and *detect* instead of *operator()* due to performance reasons. .. [ANB13] Fast Explicit Diffusion
+for Accelerated Features in Nonlinear Scale Spaces. Pablo F. Alcantarilla, Jesús Nuevo and Adrien
+Bartoli. In British Machine Vision Conference (BMVC), Bristol, UK, September 2013.
+ */
 class CV_EXPORTS_W AKAZE : public Feature2D
 {
 public:
@@ -376,6 +575,18 @@ public:
         DESCRIPTOR_MLDB = 5
     };
 
+    /** @brief The AKAZE constructor
+
+    @param descriptor\_type Type of the extracted descriptor: DESCRIPTOR\_KAZE,
+    DESCRIPTOR\_KAZE\_UPRIGHT, DESCRIPTOR\_MLDB or DESCRIPTOR\_MLDB\_UPRIGHT.
+    @param descriptor\_size Size of the descriptor in bits. 0 -\> Full size
+    @param descriptor\_channels Number of channels in the descriptor (1, 2, 3)
+    @param threshold Detector response threshold to accept point
+    @param nOctaves Maximum octave evolution of the image
+    @param nOctaveLayers Default number of sublevels per scale level
+    @param diffusivity Diffusivity type. DIFF\_PM\_G1, DIFF\_PM\_G2, DIFF\_WEICKERT or
+    DIFF\_CHARBONNIER
+     */
     CV_WRAP static Ptr<AKAZE> create(int descriptor_type=AKAZE::DESCRIPTOR_MLDB,
                                      int descriptor_size = 0, int descriptor_channels = 3,
                                      float threshold = 0.001f, int nOctaves = 4,
@@ -403,6 +614,8 @@ public:
     CV_WRAP virtual int getDiffusivity() const = 0;
 };
 
+//! @} features2d_main
+
 /****************************************************************************************\
 *                                      Distance                                          *
 \****************************************************************************************/
@@ -501,76 +714,153 @@ template<int cellsize> struct HammingMultilevel
 /****************************************************************************************\
 *                                  DescriptorMatcher                                     *
 \****************************************************************************************/
-/*
+
- * Abstract base class for matching two sets of descriptors.
+//! @addtogroup features2d_match
+//! @{
+
+/** @brief Abstract base class for matching keypoint descriptors.
+
+It has two groups of match methods: for matching descriptors of an image with another image or with
+an image set.
  */
 class CV_EXPORTS_W DescriptorMatcher : public Algorithm
 {
 public:
     virtual ~DescriptorMatcher();
 
-    /*
+    /** @brief Adds descriptors to train a CPU(trainDescCollectionis) or GPU(utrainDescCollectionis) descriptor
-     * Add descriptors to train descriptor collection.
+    collection.
-     * descriptors      Descriptors to add. Each descriptors[i] is a descriptors set from one image.
+
+    If the collection is not empty, the new descriptors are added to existing train descriptors.
+
+    @param descriptors Descriptors to add. Each descriptors[i] is a set of descriptors from the same
+    train image.
      */
     CV_WRAP virtual void add( InputArrayOfArrays descriptors );
-    /*
+
-     * Get train descriptors collection.
+    /** @brief Returns a constant link to the train descriptor collection trainDescCollection .
      */
     CV_WRAP const std::vector<Mat>& getTrainDescriptors() const;
-    /*
+
-     * Clear train descriptors collection.
+    /** @brief Clears the train descriptor collections.
      */
     CV_WRAP virtual void clear();
 
-    /*
+    /** @brief Returns true if there are no train descriptors in the both collections.
-     * Return true if there are not train descriptors in collection.
      */
     CV_WRAP virtual bool empty() const;
-    /*
+
-     * Return true if the matcher supports mask in match methods.
+    /** @brief Returns true if the descriptor matcher supports masking permissible matches.
      */
     CV_WRAP virtual bool isMaskSupported() const = 0;
 
-    /*
+    /** @brief Trains a descriptor matcher
-     * Train matcher (e.g. train flann index).
+
-     * In all methods to match the method train() is run every time before matching.
+    Trains a descriptor matcher (for example, the flann index). In all methods to match, the method
-     * Some descriptor matchers (e.g. BruteForceMatcher) have empty implementation
+    train() is run every time before matching. Some descriptor matchers (for example, BruteForceMatcher)
-     * of this method, other matchers really train their inner structures
+    have an empty implementation of this method. Other matchers really train their inner structures (for
-     * (e.g. FlannBasedMatcher trains flann::Index). So nonempty implementation
+    example, FlannBasedMatcher trains flann::Index ).
-     * of train() should check the class object state and do traing/retraining
-     * only if the state requires that (e.g. FlannBasedMatcher trains flann::Index
-     * if it has not trained yet or if new descriptors have been added to the train
-     * collection).
      */
     CV_WRAP virtual void train();
-    /*
+
-     * Group of methods to match descriptors from image pair.
+    /** @brief Finds the best match for each descriptor from a query set.
-     * Method train() is run in this methods.
+
+    @param queryDescriptors Query set of descriptors.
+    @param trainDescriptors Train set of descriptors. This set is not added to the train descriptors
+    collection stored in the class object.
+    @param matches Matches. If a query descriptor is masked out in mask , no match is added for this
+    descriptor. So, matches size may be smaller than the query descriptors count.
+    @param mask Mask specifying permissible matches between an input query and train matrices of
+    descriptors.
+
+    In the first variant of this method, the train descriptors are passed as an input argument. In the
+    second variant of the method, train descriptors collection that was set by DescriptorMatcher::add is
+    used. Optional mask (or masks) can be passed to specify which query and training descriptors can be
+    matched. Namely, queryDescriptors[i] can be matched with trainDescriptors[j] only if
+    mask.at\<uchar\>(i,j) is non-zero.
      */
-    // Find one best match for each query descriptor (if mask is empty).
     CV_WRAP void match( InputArray queryDescriptors, InputArray trainDescriptors,
                 CV_OUT std::vector<DMatch>& matches, InputArray mask=noArray() ) const;
-    // Find k best matches for each query descriptor (in increasing order of distances).
+
-    // compactResult is used when mask is not empty. If compactResult is false matches
+    /** @brief Finds the k best matches for each descriptor from a query set.
-    // vector will have the same size as queryDescriptors rows. If compactResult is true
+
-    // matches vector will not contain matches for fully masked out query descriptors.
+    @param queryDescriptors Query set of descriptors.
+    @param trainDescriptors Train set of descriptors. This set is not added to the train descriptors
+    collection stored in the class object.
+    @param mask Mask specifying permissible matches between an input query and train matrices of
+    descriptors.
+    @param matches Matches. Each matches[i] is k or less matches for the same query descriptor.
+    @param k Count of best matches found per each query descriptor or less if a query descriptor has
+    less than k possible matches in total.
+    @param compactResult Parameter used when the mask (or masks) is not empty. If compactResult is
+    false, the matches vector has the same size as queryDescriptors rows. If compactResult is true,
+    the matches vector does not contain matches for fully masked-out query descriptors.
+
+    These extended variants of DescriptorMatcher::match methods find several best matches for each query
+    descriptor. The matches are returned in the distance increasing order. See DescriptorMatcher::match
+    for the details about query and train descriptors.
+     */
     CV_WRAP void knnMatch( InputArray queryDescriptors, InputArray trainDescriptors,
                    CV_OUT std::vector<std::vector<DMatch> >& matches, int k,
                    InputArray mask=noArray(), bool compactResult=false ) const;
-    // Find best matches for each query descriptor which have distance less than
+
-    // maxDistance (in increasing order of distances).
+    /** @brief For each query descriptor, finds the training descriptors not farther than the specified distance.
+
+    @param queryDescriptors Query set of descriptors.
+    @param trainDescriptors Train set of descriptors. This set is not added to the train descriptors
+    collection stored in the class object.
+    @param matches Found matches.
+    @param compactResult Parameter used when the mask (or masks) is not empty. If compactResult is
+    false, the matches vector has the same size as queryDescriptors rows. If compactResult is true,
+    the matches vector does not contain matches for fully masked-out query descriptors.
+    @param maxDistance Threshold for the distance between matched descriptors. Distance means here
+    metric distance (e.g. Hamming distance), not the distance between coordinates (which is measured
+    in Pixels)!
+    @param mask Mask specifying permissible matches between an input query and train matrices of
+    descriptors.
+
+    For each query descriptor, the methods find such training descriptors that the distance between the
+    query descriptor and the training descriptor is equal or smaller than maxDistance. Found matches are
+    returned in the distance increasing order.
+     */
     void radiusMatch( InputArray queryDescriptors, InputArray trainDescriptors,
                       std::vector<std::vector<DMatch> >& matches, float maxDistance,
                       InputArray mask=noArray(), bool compactResult=false ) const;
-    /*
+
-     * Group of methods to match descriptors from one image to image set.
+    /** @overload
-     * See description of similar methods for matching image pair above.
+    @param queryDescriptors Query set of descriptors.
+    @param matches Matches. If a query descriptor is masked out in mask , no match is added for this
+    descriptor. So, matches size may be smaller than the query descriptors count.
+    @param masks Set of masks. Each masks[i] specifies permissible matches between the input query
+    descriptors and stored train descriptors from the i-th image trainDescCollection[i].
     */
     CV_WRAP void match( InputArray queryDescriptors, CV_OUT std::vector<DMatch>& matches,
                         InputArrayOfArrays masks=noArray() );
+    /** @overload
+    @param queryDescriptors Query set of descriptors.
+    @param matches Matches. Each matches[i] is k or less matches for the same query descriptor.
+    @param k Count of best matches found per each query descriptor or less if a query descriptor has
+    less than k possible matches in total.
+    @param masks Set of masks. Each masks[i] specifies permissible matches between the input query
+    descriptors and stored train descriptors from the i-th image trainDescCollection[i].
+    @param compactResult Parameter used when the mask (or masks) is not empty. If compactResult is
+    false, the matches vector has the same size as queryDescriptors rows. If compactResult is true,
+    the matches vector does not contain matches for fully masked-out query descriptors.
+    */
     CV_WRAP void knnMatch( InputArray queryDescriptors, CV_OUT std::vector<std::vector<DMatch> >& matches, int k,
                            InputArrayOfArrays masks=noArray(), bool compactResult=false );
+    /** @overload
+    @param queryDescriptors Query set of descriptors.
+    @param matches Found matches.
+    @param maxDistance Threshold for the distance between matched descriptors. Distance means here
+    metric distance (e.g. Hamming distance), not the distance between coordinates (which is measured
+    in Pixels)!
+    @param masks Set of masks. Each masks[i] specifies permissible matches between the input query
+    descriptors and stored train descriptors from the i-th image trainDescCollection[i].
+    @param compactResult Parameter used when the mask (or masks) is not empty. If compactResult is
+    false, the matches vector has the same size as queryDescriptors rows. If compactResult is true,
+    the matches vector does not contain matches for fully masked-out query descriptors.
+    */
     void radiusMatch( InputArray queryDescriptors, std::vector<std::vector<DMatch> >& matches, float maxDistance,
                       InputArrayOfArrays masks=noArray(), bool compactResult=false );
 
@@ -579,14 +869,28 @@ public:
     // Writes matcher object to a file storage
     virtual void write( FileStorage& ) const;
 
-    // Clone the matcher. If emptyTrainData is false the method create deep copy of the object, i.e. copies
+    /** @brief Clones the matcher.
-    // both parameters and train data. If emptyTrainData is true the method create object copy with current parameters
+
-    // but with empty train data.
+    @param emptyTrainData If emptyTrainData is false, the method creates a deep copy of the object,
+    that is, copies both parameters and train data. If emptyTrainData is true, the method creates an
+    object copy with the current parameters but with empty train data.
+     */
     virtual Ptr<DescriptorMatcher> clone( bool emptyTrainData=false ) const = 0;
 
+    /** @brief Creates a descriptor matcher of a given type with the default parameters (using default
+    constructor).
+
+    @param descriptorMatcherType Descriptor matcher type. Now the following matcher types are
+    supported:
+    -   `BruteForce` (it uses L2 )
+    -   `BruteForce-L1`
+    -   `BruteForce-Hamming`
+    -   `BruteForce-Hamming(2)`
+    -   `FlannBased`
+     */
     CV_WRAP static Ptr<DescriptorMatcher> create( const String& descriptorMatcherType );
 protected:
-    /*
+    /**
      * Class to work with descriptors from several images as with one merged matrix.
      * It is used e.g. in FlannBasedMatcher.
      */
@@ -613,9 +917,9 @@ protected:
         std::vector<int> startIdxs;
     };
 
-    // In fact the matching is implemented only by the following two methods. These methods suppose
+    //! In fact the matching is implemented only by the following two methods. These methods suppose
-    // that the class object has been trained already. Public match methods call these methods
+    //! that the class object has been trained already. Public match methods call these methods
-    // after calling train().
+    //! after calling train().
     virtual void knnMatchImpl( InputArray queryDescriptors, std::vector<std::vector<DMatch> >& matches, int k,
         InputArrayOfArrays masks=noArray(), bool compactResult=false ) = 0;
     virtual void radiusMatchImpl( InputArray queryDescriptors, std::vector<std::vector<DMatch> >& matches, float maxDistance,
@@ -627,23 +931,33 @@ protected:
     static Mat clone_op( Mat m ) { return m.clone(); }
     void checkMasks( InputArrayOfArrays masks, int queryDescriptorsCount ) const;
 
-    // Collection of descriptors from train images.
+    //! Collection of descriptors from train images.
     std::vector<Mat> trainDescCollection;
     std::vector<UMat> utrainDescCollection;
 };
 
-/*
+/** @brief Brute-force descriptor matcher.
- * Brute-force descriptor matcher.
+
- *
+For each descriptor in the first set, this matcher finds the closest descriptor in the second set
- * For each descriptor in the first set, this matcher finds the closest
+by trying each one. This descriptor matcher supports masking permissible matches of descriptor
- * descriptor in the second set by trying each one.
+sets.
- *
- * For efficiency, BruteForceMatcher is templated on the distance metric.
- * For float descriptors, a common choice would be cv::L2<float>.
  */
 class CV_EXPORTS_W BFMatcher : public DescriptorMatcher
 {
 public:
+    /** @brief Brute-force matcher constructor.
+
+    @param normType One of NORM\_L1, NORM\_L2, NORM\_HAMMING, NORM\_HAMMING2. L1 and L2 norms are
+    preferable choices for SIFT and SURF descriptors, NORM\_HAMMING should be used with ORB, BRISK and
+    BRIEF, NORM\_HAMMING2 should be used with ORB when WTA\_K==3 or 4 (see ORB::ORB constructor
+    description).
+    @param crossCheck If it is false, this is will be default BFMatcher behaviour when it finds the k
+    nearest neighbors for each query descriptor. If crossCheck==true, then the knnMatch() method with
+    k=1 will only return pairs (i,j) such that for i-th query descriptor the j-th descriptor in the
+    matcher's collection is the nearest and vice versa, i.e. the BFMatcher will only return consistent
+    pairs. Such technique usually produces best results with minimal number of outliers when there are
+    enough matches. This is alternative to the ratio test, used by D. Lowe in SIFT paper.
+     */
     CV_WRAP BFMatcher( int normType=NORM_L2, bool crossCheck=false );
     virtual ~BFMatcher() {}
 
@@ -661,8 +975,12 @@ protected:
 };
 
 
-/*
+/** @brief Flann-based descriptor matcher.
- * Flann based matcher
+
+This matcher trains flann::Index\_ on a train descriptor collection and calls its nearest search
+methods to find the best matches. So, this matcher may be faster when matching a large train
+collection than the brute force matcher. FlannBasedMatcher does not support masking permissible
+matches of descriptor sets because flann::Index does not support this. :
  */
 class CV_EXPORTS_W FlannBasedMatcher : public DescriptorMatcher
 {
@@ -700,42 +1018,85 @@ protected:
     int addedDescCount;
 };
 
+//! @} features2d_match
 
 /****************************************************************************************\
 *                                   Drawing functions                                    *
 \****************************************************************************************/
+
+//! @addtogroup features2d_draw
+//! @{
+
 struct CV_EXPORTS DrawMatchesFlags
 {
-    enum{ DEFAULT = 0, // Output image matrix will be created (Mat::create),
+    enum{ DEFAULT = 0, //!< Output image matrix will be created (Mat::create),
-                       // i.e. existing memory of output image may be reused.
+                       //!< i.e. existing memory of output image may be reused.
-                       // Two source image, matches and single keypoints will be drawn.
+                       //!< Two source image, matches and single keypoints will be drawn.
-                       // For each keypoint only the center point will be drawn (without
+                       //!< For each keypoint only the center point will be drawn (without
-                       // the circle around keypoint with keypoint size and orientation).
+                       //!< the circle around keypoint with keypoint size and orientation).
-          DRAW_OVER_OUTIMG = 1, // Output image matrix will not be created (Mat::create).
+          DRAW_OVER_OUTIMG = 1, //!< Output image matrix will not be created (Mat::create).
-                                // Matches will be drawn on existing content of output image.
+                                //!< Matches will be drawn on existing content of output image.
-          NOT_DRAW_SINGLE_POINTS = 2, // Single keypoints will not be drawn.
+          NOT_DRAW_SINGLE_POINTS = 2, //!< Single keypoints will not be drawn.
-          DRAW_RICH_KEYPOINTS = 4 // For each keypoint the circle around keypoint with keypoint size and
+          DRAW_RICH_KEYPOINTS = 4 //!< For each keypoint the circle around keypoint with keypoint size and
-                                  // orientation will be drawn.
+                                  //!< orientation will be drawn.
         };
 };
 
-// Draw keypoints.
+/** @brief Draws keypoints.
+
+@param image Source image.
+@param keypoints Keypoints from the source image.
+@param outImage Output image. Its content depends on the flags value defining what is drawn in the
+output image. See possible flags bit values below.
+@param color Color of keypoints.
+@param flags Flags setting drawing features. Possible flags bit values are defined by
+DrawMatchesFlags. See details above in drawMatches .
+
+@note
+For Python API, flags are modified as cv2.DRAW\_MATCHES\_FLAGS\_DEFAULT,
+cv2.DRAW\_MATCHES\_FLAGS\_DRAW\_RICH\_KEYPOINTS, cv2.DRAW\_MATCHES\_FLAGS\_DRAW\_OVER\_OUTIMG,
+cv2.DRAW\_MATCHES\_FLAGS\_NOT\_DRAW\_SINGLE\_POINTS
+ */
 CV_EXPORTS_W void drawKeypoints( InputArray image, const std::vector<KeyPoint>& keypoints, InputOutputArray outImage,
                                const Scalar& color=Scalar::all(-1), int flags=DrawMatchesFlags::DEFAULT );
 
-// Draws matches of keypints from two images on output image.
+/** @brief Draws the found matches of keypoints from two images.
+
+@param img1 First source image.
+@param keypoints1 Keypoints from the first source image.
+@param img2 Second source image.
+@param keypoints2 Keypoints from the second source image.
+@param matches1to2 Matches from the first image to the second one, which means that keypoints1[i]
+has a corresponding point in keypoints2[matches[i]] .
+@param outImg Output image. Its content depends on the flags value defining what is drawn in the
+output image. See possible flags bit values below.
+@param matchColor Color of matches (lines and connected keypoints). If matchColor==Scalar::all(-1)
+, the color is generated randomly.
+@param singlePointColor Color of single keypoints (circles), which means that keypoints do not
+have the matches. If singlePointColor==Scalar::all(-1) , the color is generated randomly.
+@param matchesMask Mask determining which matches are drawn. If the mask is empty, all matches are
+drawn.
+@param flags Flags setting drawing features. Possible flags bit values are defined by
+DrawMatchesFlags.
+
+This function draws matches of keypoints from two images in the output image. Match is a line
+connecting two keypoints (circles). See cv::DrawMatchesFlags.
+ */
 CV_EXPORTS_W void drawMatches( InputArray img1, const std::vector<KeyPoint>& keypoints1,
                              InputArray img2, const std::vector<KeyPoint>& keypoints2,
                              const std::vector<DMatch>& matches1to2, InputOutputArray outImg,
                              const Scalar& matchColor=Scalar::all(-1), const Scalar& singlePointColor=Scalar::all(-1),
                              const std::vector<char>& matchesMask=std::vector<char>(), int flags=DrawMatchesFlags::DEFAULT );
 
+/** @overload */
 CV_EXPORTS_AS(drawMatchesKnn) void drawMatches( InputArray img1, const std::vector<KeyPoint>& keypoints1,
                              InputArray img2, const std::vector<KeyPoint>& keypoints2,
                              const std::vector<std::vector<DMatch> >& matches1to2, InputOutputArray outImg,
                              const Scalar& matchColor=Scalar::all(-1), const Scalar& singlePointColor=Scalar::all(-1),
                              const std::vector<std::vector<char> >& matchesMask=std::vector<std::vector<char> >(), int flags=DrawMatchesFlags::DEFAULT );
 
+//! @} features2d_draw
+
 /****************************************************************************************\
 *   Functions to evaluate the feature detectors and [generic] descriptor extractors      *
 \****************************************************************************************/
@@ -755,8 +1116,14 @@ CV_EXPORTS int getNearestPoint( const std::vector<Point2f>& recallPrecisionCurve
 /****************************************************************************************\
 *                                     Bag of visual words                                *
 \****************************************************************************************/
-/*
+
- * Abstract base class for training of a 'bag of visual words' vocabulary from a set of descriptors
+//! @addtogroup features2d_category
+//! @{
+
+/** @brief Abstract base class for training the *bag of visual words* vocabulary from a set of descriptors.
+
+For details, see, for example, *Visual Categorization with Bags of Keypoints* by Gabriella Csurka,
+Christopher R. Dance, Lixin Fan, Jutta Willamowski, Cedric Bray, 2004. :
  */
 class CV_EXPORTS_W BOWTrainer
 {
@@ -764,20 +1131,37 @@ public:
     BOWTrainer();
     virtual ~BOWTrainer();
 
+    /** @brief Adds descriptors to a training set.
+
+    @param descriptors Descriptors to add to a training set. Each row of the descriptors matrix is a
+    descriptor.
+
+    The training set is clustered using clustermethod to construct the vocabulary.
+     */
     CV_WRAP void add( const Mat& descriptors );
+
+    /** @brief Returns a training set of descriptors.
+    */
     CV_WRAP const std::vector<Mat>& getDescriptors() const;
+
+    /** @brief Returns the count of all descriptors stored in the training set.
+    */
     CV_WRAP int descriptorsCount() const;
 
     CV_WRAP virtual void clear();
 
-    /*
+    /** @overload */
-     * Train visual words vocabulary, that is cluster training descriptors and
-     * compute cluster centers.
-     * Returns cluster centers.
-     *
-     * descriptors      Training descriptors computed on images keypoints.
-     */
     CV_WRAP virtual Mat cluster() const = 0;
+
+    /** @brief Clusters train descriptors.
+
+    @param descriptors Descriptors to cluster. Each row of the descriptors matrix is a descriptor.
+    Descriptors are not added to the inner train descriptor set.
+
+    The vocabulary consists of cluster centers. So, this method returns the vocabulary. In the first
+    variant of the method, train descriptors stored in the object are clustered. In the second variant,
+    input descriptors are clustered.
+     */
     CV_WRAP virtual Mat cluster( const Mat& descriptors ) const = 0;
 
 protected:
@@ -785,12 +1169,15 @@ protected:
     int size;
 };
 
-/*
+/** @brief kmeans -based class to train visual vocabulary using the *bag of visual words* approach. :
- * This is BOWTrainer using cv::kmeans to get vocabulary.
  */
 class CV_EXPORTS_W BOWKMeansTrainer : public BOWTrainer
 {
 public:
+    /** @brief The constructor.
+
+    @see cv::kmeans
+    */
     CV_WRAP BOWKMeansTrainer( int clusterCount, const TermCriteria& termcrit=TermCriteria(),
                       int attempts=3, int flags=KMEANS_PP_CENTERS );
     virtual ~BOWKMeansTrainer();
@@ -807,21 +1194,62 @@ protected:
     int flags;
 };
 
-/*
+/** @brief Class to compute an image descriptor using the *bag of visual words*.
- * Class to compute image descriptor using bag of visual words.
+
+Such a computation consists of the following steps:
+
+1.  Compute descriptors for a given image and its keypoints set.
+2.  Find the nearest visual words from the vocabulary for each keypoint descriptor.
+3.  Compute the bag-of-words image descriptor as is a normalized histogram of vocabulary words
+encountered in the image. The i-th bin of the histogram is a frequency of i-th word of the
+vocabulary in the given image.
  */
 class CV_EXPORTS_W BOWImgDescriptorExtractor
 {
 public:
+    /** @brief The constructor.
+
+    @param dextractor Descriptor extractor that is used to compute descriptors for an input image and
+    its keypoints.
+    @param dmatcher Descriptor matcher that is used to find the nearest word of the trained vocabulary
+    for each keypoint descriptor of the image.
+     */
     CV_WRAP BOWImgDescriptorExtractor( const Ptr<DescriptorExtractor>& dextractor,
                                const Ptr<DescriptorMatcher>& dmatcher );
+    /** @overload */
     BOWImgDescriptorExtractor( const Ptr<DescriptorMatcher>& dmatcher );
     virtual ~BOWImgDescriptorExtractor();
 
+    /** @brief Sets a visual vocabulary.
+
+    @param vocabulary Vocabulary (can be trained using the inheritor of BOWTrainer ). Each row of the
+    vocabulary is a visual word (cluster center).
+     */
     CV_WRAP void setVocabulary( const Mat& vocabulary );
+
+    /** @brief Returns the set vocabulary.
+    */
     CV_WRAP const Mat& getVocabulary() const;
+
+    /** @brief Computes an image descriptor using the set visual vocabulary.
+
+    @param image Image, for which the descriptor is computed.
+    @param keypoints Keypoints detected in the input image.
+    @param imgDescriptor Computed output image descriptor.
+    @param pointIdxsOfClusters Indices of keypoints that belong to the cluster. This means that
+    pointIdxsOfClusters[i] are keypoint indices that belong to the i -th cluster (word of vocabulary)
+    returned if it is non-zero.
+    @param descriptors Descriptors of the image keypoints that are returned if they are non-zero.
+     */
     void compute( InputArray image, std::vector<KeyPoint>& keypoints, OutputArray imgDescriptor,
                   std::vector<std::vector<int> >* pointIdxsOfClusters=0, Mat* descriptors=0 );
+    /** @overload
+    @param keypointDescriptors Computed descriptors to match with vocabulary.
+    @param imgDescriptor Computed output image descriptor.
+    @param pointIdxsOfClusters Indices of keypoints that belong to the cluster. This means that
+    pointIdxsOfClusters[i] are keypoint indices that belong to the i -th cluster (word of vocabulary)
+    returned if it is non-zero.
+    */
     void compute( InputArray keypointDescriptors, OutputArray imgDescriptor,
                   std::vector<std::vector<int> >* pointIdxsOfClusters=0 );
     // compute() is not constant because DescriptorMatcher::match is not constant
@@ -829,7 +1257,12 @@ public:
     CV_WRAP_AS(compute) void compute2( const Mat& image, std::vector<KeyPoint>& keypoints, CV_OUT Mat& imgDescriptor )
     { compute(image,keypoints,imgDescriptor); }
 
+    /** @brief Returns an image descriptor size if the vocabulary is set. Otherwise, it returns 0.
+    */
     CV_WRAP int descriptorSize() const;
+
+    /** @brief Returns an image descriptor type.
+     */
     CV_WRAP int descriptorType() const;
 
 protected:
@@ -838,6 +1271,10 @@ protected:
     Ptr<DescriptorMatcher> dmatcher;
 };
 
+//! @} features2d_category
+
+//! @} features2d
+
 } /* namespace cv */
 
 #endif