Purpose: updated the feature2d chapter

modules/features2d/doc/feature_detection_and_description.rst

@@ -1,4 +1,4 @@
-Feature detection and description
+Feature Detection and Description
 =================================
 
 .. highlight:: cpp
@@ -9,16 +9,15 @@ FAST
 --------
 .. c:function:: void FAST( const Mat& image, vector<KeyPoint>& keypoints,            int threshold, bool nonmaxSupression=true )
 
-    Detects corners using FAST algorithm by E. Rosten (''Machine learning for high-speed corner detection'', 2006).
+    Detects corners using the FAST algorithm by E. Rosten (*Machine learning for high-speed corner detection*, 2006).
 
-    :param image: The image. Keypoints (corners) will be detected on this.
+    :param image: Image where keypoints (corners) are detected.
 
     :param keypoints: Keypoints detected on the image.
 
-    :param threshold: Threshold on difference between intensity of center pixel and
+    :param threshold: Threshold on difference between intensity of the central pixel and pixels on a circle around this pixel. See the algorithm description below.
-                pixels on circle around this pixel. See description of the algorithm.
 
-    :param nonmaxSupression: If it is true then non-maximum supression will be applied to detected corners (keypoints).
+    :param nonmaxSupression: If it is true, non-maximum supression is applied to detected corners (keypoints).
 
 .. index:: MSER
 
@@ -28,7 +27,7 @@ MSER
 ----
 .. c:type:: MSER
 
-Maximally-Stable Extremal Region Extractor ::
+Maximally (or Most??) stable extremal region extractor ::
 
     class MSER : public CvMSERParams
     {
@@ -46,8 +45,8 @@ Maximally-Stable Extremal Region Extractor ::
         void operator()( const Mat& image, vector<vector<Point> >& msers, const Mat& mask ) const;
     };
 
-The class encapsulates all the parameters of MSER (see
+The class encapsulates all the parameters of the MSER extraction algorithm (see
-http://en.wikipedia.org/wiki/Maximally_stable_extremal_regions) extraction algorithm.
+http://en.wikipedia.org/wiki/Maximally_stable_extremal_regions).
 
 .. index:: StarDetector
 
@@ -57,14 +56,14 @@ StarDetector
 ------------
 .. c:type:: StarDetector
 
-Implements Star keypoint detector ::
+Class implementing the Star keypoint detector ::
 
     class StarDetector : CvStarDetectorParams
     {
     public:
         // default constructor
         StarDetector();
-        // the full constructor initialized all the algorithm parameters:
+        // the full constructor that initializes all the algorithm parameters:
         // maxSize - maximum size of the features. The following
         //      values of the parameter are supported:
         //      4, 6, 8, 11, 12, 16, 22, 23, 32, 45, 46, 64, 90, 128
@@ -75,7 +74,7 @@ Implements Star keypoint detector ::
         //      eliminate edges
         // lineThresholdBinarized - another threshold for the feature
         //      size to eliminate edges.
-        // The larger the 2 threshold, the more points you get.
+        // The larger the 2nd threshold, the more points you get.
         StarDetector(int maxSize, int responseThreshold,
                      int lineThresholdProjected,
                      int lineThresholdBinarized,
@@ -85,8 +84,8 @@ Implements Star keypoint detector ::
         void operator()(const Mat& image, vector<KeyPoint>& keypoints) const;
     };
 
-The class implements a modified version of CenSurE keypoint detector described in
+The class implements a modified version of the CenSurE keypoint detector described in
-Agrawal08
+Agrawal08??.
 
 .. index:: SIFT
 
@@ -96,7 +95,7 @@ SIFT
 ----
 .. c:type:: SIFT
 
-Class for extracting keypoints and computing descriptors using approach named Scale Invariant Feature Transform (SIFT). ::
+Class for extracting keypoints and computing descriptors using the Scale Invariant Feature Transform (SIFT) approach ::
 
     class CV_EXPORTS SIFT
     {
@@ -160,7 +159,7 @@ Class for extracting keypoints and computing descriptors using approach named Sc
 
         //! returns the descriptor size in floats (128)
         int descriptorSize() const { return DescriptorParams::DESCRIPTOR_SIZE; }
-        //! finds the keypoints using SIFT algorithm
+        //! finds the keypoints using the SIFT algorithm
         void operator()(const Mat& img, const Mat& mask,
                         vector<KeyPoint>& keypoints) const;
         //! finds the keypoints and computes descriptors for them using SIFT algorithm.
@@ -186,7 +185,7 @@ SURF
 ----
 .. c:type:: SURF
 
-Class for extracting Speeded Up Robust Features from an image. ::
+Class for extracting Speeded Up Robust Features from an image ::
 
     class SURF : public CvSURFParams
     {
@@ -211,10 +210,10 @@ Class for extracting Speeded Up Robust Features from an image. ::
                         bool useProvidedKeypoints=false) const;
     };
 
-The class ``SURF`` implements Speeded Up Robust Features descriptor Bay06.
+The class implements the Speeded Up Robust Features descriptor Bay06.
-There is fast multi-scale Hessian keypoint detector that can be used to find the keypoints
+There is a fast multi-scale Hessian keypoint detector that can be used to find keypoints
-(which is the default option), but the descriptors can be also computed for the user-specified keypoints.
+(which is the default option). But the descriptors can be also computed for the user-specified keypoints.
-The function can be used for object tracking and localization, image stitching etc. See the ``find_obj.cpp`` demo in OpenCV samples directory.
+The function?? can be used for object tracking and localization, image stitching, and so on. See the ``find_obj.cpp`` demo in OpenCV samples directory.
 
 .. index:: RandomizedTree
 
@@ -224,7 +223,7 @@ RandomizedTree
 --------------
 .. c:type:: RandomizedTree
 
-The class contains base structure for ``RTreeClassifier`` ::
+Class containing a base structure for ``RTreeClassifier`` ::
 
     class CV_EXPORTS RandomizedTree
     {
@@ -241,7 +240,7 @@ The class contains base structure for ``RTreeClassifier`` ::
                      RNG &rng, PatchGenerator &make_patch, int depth,
                      int views, size_t reduced_num_dim, int num_quant_bits);
 
-            // following two funcs are EXPERIMENTAL
+            // next two functions are EXPERIMENTAL
             //(do not use unless you know exactly what you do)
             static void quantizeVector(float *vec, int dim, int N, float bnds[2],
                      int clamp_mode=0);
@@ -271,8 +270,8 @@ The class contains base structure for ``RTreeClassifier`` ::
             int depth_;
             int num_leaves_;
             std::vector<RTreeNode> nodes_;
-            float **posteriors_;        // 16-bytes aligned posteriors
+            float **posteriors_;        // 16-byte aligned posteriors
-            uchar **posteriors2_;     // 16-bytes aligned posteriors
+            uchar **posteriors2_;     // 16-byte aligned posteriors
             std::vector<int> leaf_counts_;
 
             void createNodes(int num_nodes, RNG &rng);
@@ -298,17 +297,17 @@ RandomizedTree::train
 -------------------------
 .. c:function:: void train(std::vector<BaseKeypoint> const& base_set, RNG& rng, PatchGenerator& make_patch, int depth, int views, size_t reduced_num_dim, int num_quant_bits)
 
-    Trains a randomized tree using input set of keypoints
+    Trains a randomized tree using an input set of keypoints.
 
 .. c:function:: void train(std::vector<BaseKeypoint> const& base_set, RNG& rng, PatchGenerator& make_patch, int depth, int views, size_t reduced_num_dim, int num_quant_bits)
 
-    {Vector of ``BaseKeypoint`` type. Contains keypoints from the image are used for training}
+    {Vector of ``BaseKeypoint`` type. Contains keypoints from the image that are used for training}??
-    {Random numbers generator is used for training}
+    {Random numbers generator is used for training}??
-    {Patch generator is used for training}
+    {Patch generator is used for training}??
-    {Maximum tree depth}
+    {Maximum tree depth}??
 
-    {Number of dimensions are used in compressed signature}
+    {Number of dimensions are used in compressed signature}??
-    {Number of bits are used for quantization}
+    {Number of bits are used for quantization}??
 
 .. index:: RandomizedTree::read
 
@@ -316,15 +315,15 @@ RandomizedTree::read
 ------------------------
 .. c:function:: read(const char* file_name, int num_quant_bits)
 
-    Reads pre-saved randomized tree from file or stream
+    Reads a pre-saved randomized tree from a file or stream. ?? is it applied to the 1st func only?
 
 .. c:function:: read(std::istream \&is, int num_quant_bits)
 
-    :param file_name: Filename of file contains randomized tree data
+    :param file_name: Name of the file that contains randomized tree data.
 
-    :param is: Input stream associated with file contains randomized tree data
+    :param is: Input stream associated with the file that contains randomized tree data.
 
-    {Number of bits are used for quantization}
+    {Number of bits are used for quantization}??
 
 .. index:: RandomizedTree::write
 
@@ -332,13 +331,13 @@ RandomizedTree::write
 -------------------------
 .. c:function:: void write(const char* file_name) const
 
-    Writes current randomized tree to a file or stream
+    Writes the current randomized tree to a file or stream.
 
 .. c:function:: void write(std::ostream \&os) const
 
-    :param file_name: Filename of file where randomized tree data will be stored
+    :param file_name: Name of the file where randomized tree data is stored.
 
-    :param is: Output stream associated with file where randomized tree data will be stored
+    :param is: Output stream associated with the file where randomized tree data is stored.
 
 .. index:: RandomizedTree::applyQuantization
 
@@ -346,9 +345,9 @@ RandomizedTree::applyQuantization
 -------------------------------------
 .. c:function:: void applyQuantization(int num_quant_bits)
 
-    Applies quantization to the current randomized tree
+    Applies quantization to the current randomized tree.
 
-    {Number of bits are used for quantization}
+    {Number of bits are used for quantization}??
 
 .. index:: RTreeNode
 
@@ -358,7 +357,7 @@ RTreeNode
 ---------
 .. c:type:: RTreeNode
 
-The class contains base structure for ``RandomizedTree`` ::
+Class containing a base structure for ``RandomizedTree`` ::
 
     struct RTreeNode
     {
@@ -386,7 +385,7 @@ RTreeClassifier
 ---------------
 .. c:type:: RTreeClassifier
 
-The class contains ``RTreeClassifier`` . It represents calonder descriptor which was originally introduced by Michael Calonder ::
+Class containing ``RTreeClassifier`` . It represents the Calonder descriptor that was originally introduced by Michael Calonder ::
 
     class CV_EXPORTS RTreeClassifier
     {
@@ -456,19 +455,19 @@ RTreeClassifier::train
 --------------------------
 .. c:function:: void train(vector<BaseKeypoint> const& base_set, RNG& rng, int num_trees = RTreeClassifier::DEFAULT_TREES,                         int depth = DEFAULT_DEPTH, int views = DEFAULT_VIEWS, size_t reduced_num_dim = DEFAULT_REDUCED_NUM_DIM, int num_quant_bits = DEFAULT_NUM_QUANT_BITS, bool print_status = true)
 
-    Trains a randomized tree classificator using input set of keypoints
+    Trains a randomized tree classifier using an input set of keypoints.
 
 .. c:function:: void train(vector<BaseKeypoint> const& base_set, RNG& rng, PatchGenerator& make_patch, int num_trees = RTreeClassifier::DEFAULT_TREES, int depth = DEFAULT_DEPTH, int views = DEFAULT_VIEWS, size_t reduced_num_dim = DEFAULT_REDUCED_NUM_DIM,                         int num_quant_bits = DEFAULT_NUM_QUANT_BITS, bool print_status = true)
 
-    {Vector of ``BaseKeypoint``     type. Contains keypoints from the image are used for training}
+    {Vector of ``BaseKeypoint``     type. Contains image keypoints used for training}??
-    {Random numbers generator is used for training}
+    {Random-number generator is used for training}??
-    {Patch generator is used for training}
+    {Patch generator is used for training}??
-    {Number of randomized trees used in RTreeClassificator}
+    {Number of randomized trees used in RTreeClassificator}??
-    {Maximum tree depth}
+    {Maximum tree depth}??
 
-    {Number of dimensions are used in compressed signature}
+    {Number of dimensions are used in compressed signature}??
-    {Number of bits are used for quantization}
+    {Number of bits are used for quantization}??
-    {Print current status of training on the console}
+    {Print current status of training on the console}??
 
 .. index:: RTreeClassifier::getSignature
 
@@ -476,7 +475,7 @@ RTreeClassifier::getSignature
 ---------------------------------
 .. c:function:: void getSignature(IplImage *patch, uchar *sig)
 
-    Returns signature for image patch
+    Returns a signature for an image patch.
 
 .. c:function:: void getSignature(IplImage *patch, float *sig)
 
@@ -490,11 +489,11 @@ RTreeClassifier::getSparseSignature
 
 .. c:function:: void getSparseSignature(IplImage *patch, float *sig, float thresh)
 
-    The function is simular to getSignaturebut uses the threshold for removing all signature elements less than the threshold. So that the signature is compressed
+    Similarly to ``getSignaturebut`` , uses a threshold for removing all signature elements below the threshold so that the signature is compressed.??
 
-    {Image patch to calculate signature for}
+    {Image patch to calculate signature for}??
-    {Output signature (array dimension is ``reduced_num_dim)``}
+    {Output signature (array dimension is ``reduced_num_dim)``}??
-    {The threshold that is used for compressing the signature}
+    {The threshold that is used for compressing the signature}??
 
 .. index:: RTreeClassifier::countNonZeroElements
 
@@ -502,13 +501,13 @@ RTreeClassifier::countNonZeroElements
 -----------------------------------------
 .. c:function:: static int countNonZeroElements(float *vec, int n, double tol=1e-10)
 
-    The function returns the number of non-zero elements in the input array.
+    Returns the number of non-zero elements in an input array.
 
-    :param vec: Input vector contains float elements
+    :param vec: Input vector containing float elements.
 
-    :param n: Input vector size
+    :param n: Input vector size.
 
-    {The threshold used for elements counting. We take all elements are less than ``tol``     as zero elements}
+    {The threshold used for counting elements. We take all elements are less than ``tol``     as zero elements}??
 
 .. index:: RTreeClassifier::read
 
@@ -516,13 +515,13 @@ RTreeClassifier::read
 -------------------------
 .. c:function:: read(const char* file_name)
 
-    Reads pre-saved RTreeClassifier from file or stream
+    Reads a pre-saved ``RTreeClassifier`` from a file or stream.
 
 .. c:function:: read(std::istream& is)
 
-    :param file_name: Filename of file contains randomized tree data
+    :param file_name: Name of the file that contains randomized tree data.
 
-    :param is: Input stream associated with file contains randomized tree data
+    :param is: Input stream associated with the file that contains randomized tree data.
 
 .. index:: RTreeClassifier::write
 
@@ -530,13 +529,13 @@ RTreeClassifier::write
 --------------------------
 .. c:function:: void write(const char* file_name) const
 
-    Writes current RTreeClassifier to a file or stream
+    Writes the current RTreeClassifier to a file or stream.
 
 .. c:function:: void write(std::ostream \&os) const
 
-    :param file_name: Filename of file where randomized tree data will be stored
+    :param file_name: Name of the file where randomized tree data is stored.
 
-    :param is: Output stream associated with file where randomized tree data will be stored
+    :param is: Output stream associated with the file where randomized tree data is stored.
 
 .. index:: RTreeClassifier::setQuantization
 
@@ -544,13 +543,13 @@ RTreeClassifier::setQuantization
 ------------------------------------
 .. c:function:: void setQuantization(int num_quant_bits)
 
-    Applies quantization to the current randomized tree
+    Applies quantization to the current randomized tree.
 
-    {Number of bits are used for quantization}
+    {Number of bits are used for quantization}??
 
-Below there is an example of ``RTreeClassifier`` usage for feature matching. There are test and train images and we extract features from both with SURF. Output is
+The example below demonstrates the usage of ``RTreeClassifier`` for feature matching. There are test and train images and features are extracted from both with SURF. Output is
 :math:`best\_corr` and
-:math:`best\_corr\_idx` arrays which keep the best probabilities and corresponding features indexes for every train feature. ::
+:math:`best\_corr\_idx` arrays that keep the best probabilities and corresponding features indices for every train feature. ::
 
     CvMemStorage* storage = cvCreateMemStorage(0);
     CvSeq *objectKeypoints = 0, *objectDescriptors = 0;