From af6072814c35820ccc8fe2007fa243f33db36000 Mon Sep 17 00:00:00 2001 From: Elena Fedotova Date: Tue, 3 May 2011 20:41:11 +0000 Subject: [PATCH] Purpose: updated the feature2d chapter --- .../doc/feature_detection_and_description.rst | 141 +++++++++--------- 1 file changed, 70 insertions(+), 71 deletions(-) diff --git a/modules/features2d/doc/feature_detection_and_description.rst b/modules/features2d/doc/feature_detection_and_description.rst index 66775ff193..35a651d3c5 100644 --- a/modules/features2d/doc/feature_detection_and_description.rst +++ b/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& 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 - pixels on circle around this pixel. See description of the algorithm. + :param threshold: Threshold on difference between intensity of the central pixel and pixels on a circle around this pixel. See the algorithm description below. - :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 >& msers, const Mat& mask ) const; }; -The class encapsulates all the parameters of MSER (see -http://en.wikipedia.org/wiki/Maximally_stable_extremal_regions) extraction algorithm. +The class encapsulates all the parameters of the MSER extraction algorithm (see +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& keypoints) const; }; -The class implements a modified version of CenSurE keypoint detector described in -Agrawal08 +The class implements a modified version of the CenSurE keypoint detector described in +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& 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. -There is fast multi-scale Hessian keypoint detector that can be used to find the 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 class implements the Speeded Up Robust Features descriptor Bay06. +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. +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 nodes_; - float **posteriors_; // 16-bytes aligned posteriors - uchar **posteriors2_; // 16-bytes aligned posteriors + float **posteriors_; // 16-byte aligned posteriors + uchar **posteriors2_; // 16-byte aligned posteriors std::vector leaf_counts_; void createNodes(int num_nodes, RNG &rng); @@ -298,17 +297,17 @@ RandomizedTree::train ------------------------- .. c:function:: void train(std::vector 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 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} - {Random numbers generator is used for training} - {Patch generator is used for training} - {Maximum tree depth} + {Vector of ``BaseKeypoint`` type. Contains keypoints from the image that are used for training}?? + {Random numbers generator is used for training}?? + {Patch generator is used for training}?? + {Maximum tree depth}?? - {Number of dimensions are used in compressed signature} - {Number of bits are used for quantization} + {Number of dimensions are used in compressed signature}?? + {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 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 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} - {Random numbers generator is used for training} - {Patch generator is used for training} - {Number of randomized trees used in RTreeClassificator} - {Maximum tree depth} + {Vector of ``BaseKeypoint`` type. Contains image keypoints used for training}?? + {Random-number generator is used for training}?? + {Patch generator is used for training}?? + {Number of randomized trees used in RTreeClassificator}?? + {Maximum tree depth}?? - {Number of dimensions are used in compressed signature} - {Number of bits are used for quantization} - {Print current status of training on the console} + {Number of dimensions are used in compressed signature}?? + {Number of bits are used for quantization}?? + {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} - {Output signature (array dimension is ``reduced_num_dim)``} - {The threshold that is used for compressing the signature} + {Image patch to calculate signature for}?? + {Output signature (array dimension is ``reduced_num_dim)``}?? + {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;