From 362df22fac1e3b30f6559391da83c6d6a64970f0 Mon Sep 17 00:00:00 2001 From: Maria Dimashova Date: Thu, 25 Nov 2010 17:44:16 +0000 Subject: [PATCH] update features2d documentation after changes create functions and DynamicAdaptedFeatureDetector --- ...eatures2d_common_detection_description.tex | 112 +++++++++++------- doc/features2d_dynamic_detectors.tex | 58 +++++---- 2 files changed, 100 insertions(+), 70 deletions(-) diff --git a/doc/features2d_common_detection_description.tex b/doc/features2d_common_detection_description.tex index 170958b819..d7c100f013 100644 --- a/doc/features2d_common_detection_description.tex +++ b/doc/features2d_common_detection_description.tex @@ -75,6 +75,8 @@ public: virtual void read(const FileNode&); virtual void write(FileStorage&) const; + + static Ptr create( const string& detectorType ); protected: ... @@ -132,6 +134,31 @@ void FeatureDetector::write( FileStorage\& fs ) const; \cvarg{fs}{File storage in which detector will be written.} \end{description} +\cvCppFunc{FeatureDetector::create} +Feature detector factory that creates \cvCppCross{FeatureDetector} of given type with +default parameters (rather using default constructor). + +\begin{lstlisting} +Ptr FeatureDetector::create( const string& detectorType ); +\end{lstlisting} + +\begin{description} +\cvarg{detectorType}{Feature detector type.} +\end{description} + +Now the following detector types are supported:\\ +\texttt{"FAST"} -- \cvCppCross{FastFeatureDetector},\\ +\texttt{"STAR"} -- \cvCppCross{StarFeatureDetector},\\ +\texttt{"SIFT"} -- \cvCppCross{SiftFeatureDetector}, \\ +\texttt{"SURF"} -- \cvCppCross{SurfFeatureDetector}, \\ +\texttt{"MSER"} -- \cvCppCross{MserFeatureDetector}, \\ +\texttt{"GFTT"} -- \cvCppCross{GfttFeatureDetector}, \\ +\texttt{"HARRIS"} -- \cvCppCross{HarrisFeatureDetector}. \\ +Also combined format is supported: feature detector adapter name (\texttt{"Grid"} -- +\cvCppCross{GridAdaptedFeatureDetector}, \texttt{"Pyramid"} -- +\cvCppCross{PyramidAdaptedFeatureDetector}) + feature detector name (see above), +e.g. \texttt{"GridFAST"}, \texttt{"PyramidSTAR"}, etc. + \cvclass{FastFeatureDetector} Wrapping class for feature detection using \cvCppCross{FAST} method. @@ -302,21 +329,6 @@ protected: %dynamic detectors doc \input{features2d_dynamic_detectors} -\cvCppFunc{createFeatureDetector} -Feature detector factory that creates \cvCppCross{FeatureDetector} of given type with -default parameters (rather using default constructor). - -\begin{lstlisting} -Ptr createFeatureDetector( const string& detectorType ); -\end{lstlisting} - -\begin{description} -\cvarg{detectorType}{Feature detector type.} -\end{description} - -Now the following detector types are supported ''FAST'', ''STAR'', ''SIFT'', -''SURF'', ''MSER'', ''GFTT'', ''HARRIS''. - \section{Common Interfaces of Descriptor Extractors} Extractors of keypoint descriptors in OpenCV have wrappers with common interface that enables to switch easily between different algorithms solving the same problem. This section is devoted to computing descriptors @@ -342,6 +354,8 @@ public: virtual int descriptorSize() const = 0; virtual int descriptorType() const = 0; + + static Ptr create( const string& descriptorExtractorType ); protected: ... @@ -407,6 +421,27 @@ void DescriptorExtractor::write( FileStorage\& fs ) const; \cvarg{fs}{File storage in which detector will be written.} \end{description} +\cvCppFunc{DescriptorExtractor::create} +Descriptor extractor factory that creates \cvCppCross{DescriptorExtractor} of given type with +default parameters (rather using default constructor). + +\begin{lstlisting} +Ptr +DescriptorExtractor::create( const string& descriptorExtractorType ); +\end{lstlisting} + +\begin{description} +\cvarg{descriptorExtractorType}{Descriptor extractor type.} +\end{description} + +Now the following descriptor extractor types are supported:\\ +\texttt{"SIFT"} -- \cvCppCross{SiftFeatureDetector},\\ +\texttt{"SURF"} -- \cvCppCross{SurfFeatureDetector},\\ +\texttt{"BRIEF"} -- \cvCppCross{BriefFeatureDetector}.\\ +Also combined format is supported: descriptor extractor adapter name (\texttt{"Opponent"} -- +\cvCppCross{OpponentColorDescriptorExtractor}) + descriptor extractor name (see above), +e.g. \texttt{"OpponentSIFT"}, etc. + \cvclass{SiftDescriptorExtractor} Wrapping class for descriptors computing using \cvCppCross{SIFT} class. @@ -516,22 +551,6 @@ protected: }; \end{lstlisting} -\cvCppFunc{createDescriptorExtractor} -Descriptor extractor factory that creates \cvCppCross{DescriptorExtractor} of given type with -default parameters (rather using default constructor). - -\begin{lstlisting} -Ptr -createDescriptorExtractor( const string& descriptorExtractorType ); -\end{lstlisting} - -\begin{description} -\cvarg{descriptorExtractorType}{Descriptor extractor type.} -\end{description} - -Now the following descriptor extractor types are supported ''SIFT'', ''SURF'', -''OpponentSIFT'', ''OpponentSURF'', ''BRIEF''. - \section{Common Interfaces of Descriptor Matchers} Matchers of keypoint descriptors in OpenCV have wrappers with common interface that enables to switch easily between different algorithms solving the same problem. This section is devoted to matching descriptors @@ -612,6 +631,8 @@ public: virtual void write( FileStorage& ) const; virtual Ptr clone( bool emptyTrainData=false ) const = 0; + + static Ptr create( const string& descriptorMatcherType ); protected: vector trainDescCollection; @@ -769,6 +790,21 @@ DescriptorMatcher::clone( bool emptyTrainData ) const; but with empty train data..} \end{description} +\cvCppFunc{DescriptorMatcher::create} +Descriptor matcher factory that creates \cvCppCross{DescriptorMatcher} of +given type with default parameters (rather using default constructor). + +\begin{lstlisting} +Ptr +DescriptorMatcher::create( const string& descriptorMatcherType ); +\end{lstlisting} + +\begin{description} +\cvarg{descriptorMatcherType}{Descriptor matcher type.} +\end{description} +Now the following matcher types are supported: \texttt{"BruteForce"} (it uses \texttt{L2}), \texttt{"BruteForce-L1"}, +\texttt{"BruteForce-Hamming"}, \texttt{"BruteForce-HammingLUT"}, \texttt{"FlannBased"}. + \cvclass{BruteForceMatcher} Brute-force descriptor matcher. For each descriptor in the first set, this matcher finds the closest descriptor in the second set by trying each one. This descriptor matcher supports masking @@ -881,20 +917,6 @@ protected: }; \end{lstlisting} -\cvCppFunc{createDescriptorMatcher} -Descriptor matcher factory that creates \cvCppCross{DescriptorMatcher} of -given type with default parameters (rather using default constructor). - -\begin{lstlisting} -Ptr createDescriptorMatcher( const string& descriptorMatcherType ); -\end{lstlisting} - -\begin{description} -\cvarg{descriptorMatcherType}{Descriptor matcher type.} -\end{description} -Now the following matcher types are supported: ''BruteForce'' (it uses L2), ''BruteForce-L1'', -''BruteForce-Hamming'', ''BruteForce-HammingLUT''. - \section{Common Interfaces of Generic Descriptor Matchers} Matchers of keypoint descriptors in OpenCV have wrappers with common interface that enables to switch easily between different algorithms solving the same problem. This section is devoted to matching descriptors diff --git a/doc/features2d_dynamic_detectors.tex b/doc/features2d_dynamic_detectors.tex index f2c5a032a8..144f21a788 100644 --- a/doc/features2d_dynamic_detectors.tex +++ b/doc/features2d_dynamic_detectors.tex @@ -1,4 +1,4 @@ -\cvclass{DynamicDetector} +\cvclass{DynamicAdaptedFeatureDetector} An adaptively adjusting detector that iteratively detects until the desired number of features are found. @@ -7,7 +7,7 @@ used on the last detection. In this way, the detector may be used for consistent of keypoints in a sets of images that are temporally related such as video streams or panorama series. -The DynamicDetector uses another detector such as FAST or SURF to do the dirty work, +The DynamicAdaptedFeatureDetector uses another detector such as FAST or SURF to do the dirty work, with the help of an AdjusterAdapter. After a detection, and an unsatisfactory number of features are detected, the AdjusterAdapter will adjust the detection parameters so that the next detection will @@ -20,52 +20,54 @@ AdjusterAdapter interface. Beware that this is not thread safe - as the adjustment of parameters breaks the const of the detection routine... -Here is a sample of how to create a DynamicDetector. +Here is a sample of how to create a DynamicAdaptedFeatureDetector. \begin{lstlisting} //sample usage: //will create a detector that attempts to find //100 - 110 FAST Keypoints, and will at most run //FAST feature detection 10 times until that //number of keypoints are found -Ptr detector(new DynamicDetector (100, 110, 10, +Ptr detector(new DynamicAdaptedFeatureDetector (100, 110, 10, new FastAdjuster(20,true))); \end{lstlisting} \begin{lstlisting} -class DynamicDetector: public FeatureDetector { +class DynamicAdaptedFeatureDetector: public FeatureDetector +{ public: - DynamicDetector(int min_features, int max_features, int max_iters, - const Ptr& a); - ... + DynamicAdaptedFeatureDetector( const Ptr& adjaster, + int min_features=400, int max_features=500, int max_iters=5 ); + ... }; \end{lstlisting} -\cvCppFunc{DynamicDetector::DynamicDetector} -DynamicDetector constructor. +\cvCppFunc{DynamicAdaptedFeatureDetector::DynamicAdaptedFeatureDetector} +DynamicAdaptedFeatureDetector constructor. \cvdefCpp{ -DynamicDetector::DynamicDetector( \par int min\_features, \par int max\_features, \par int max\_iters, - \par const Ptr\& a); +DynamicAdaptedFeatureDetector::DynamicAdaptedFeatureDetector( + \par const Ptr\& adjaster, + \par int min\_features, \par int max\_features, \par int max\_iters ); } \begin{description} +\cvarg{adjaster}{ An \cvCppCross{AdjusterAdapter} that will do the detection and parameter + adjustment} \cvarg{min\_features}{This minimum desired number features.} \cvarg{max\_features}{The maximum desired number of features.} \cvarg{max\_iters}{The maximum number of times to try to adjust the feature detector parameters. For the \cvCppCross{FastAdjuster} this number can be high, but with Star or Surf, many iterations can get time consuming. At each iteration the detector is rerun, so keep this in mind when choosing this value.} -\cvarg{a}{ An \cvCppCross{AdjusterAdapter} that will do the detection and parameter - adjustment} \end{description} \cvclass{AdjusterAdapter} -A feature detector parameter adjuster interface, this is used by the \cvCppCross{DynamicDetector} +A feature detector parameter adjuster interface, this is used by the \cvCppCross{DynamicAdaptedFeatureDetector} and is a wrapper for \cvCppCross{FeatureDetecto}r that allow them to be adjusted after a detection. See \cvCppCross{FastAdjuster}, \cvCppCross{StarAdjuster}, \cvCppCross{SurfAdjuster} for concrete implementations. \begin{lstlisting} -class AdjusterAdapter: public FeatureDetector { +class AdjusterAdapter: public FeatureDetector +{ public: - virtual ~AdjusterAdapter() { - } + virtual ~AdjusterAdapter() {} virtual void tooFew(int min, int n_detected) = 0; virtual void tooMany(int max, int n_detected) = 0; virtual bool good() const = 0; @@ -73,7 +75,7 @@ public: \end{lstlisting} \cvCppFunc{AdjusterAdapter::tooFew} \cvdefCpp{ -virtual void tooFew(\par int min, int n\_detected) = 0; +virtual void tooFew(int min, int n\_detected) = 0; } Too few features were detected so, adjust the detector parameters accordingly - so that the next detection detects more features. @@ -83,7 +85,8 @@ detection detects more features. \end{description} An example implementation of this is \begin{lstlisting} -void FastAdjuster::tooFew(int min, int n_detected) { +void FastAdjuster::tooFew(int min, int n_detected) +{ thresh_--; } \end{lstlisting} @@ -100,7 +103,8 @@ virtual void tooMany(int max, int n\_detected) = 0; \end{description} An example implementation of this is \begin{lstlisting} -void FastAdjuster::tooMany(int min, int n_detected) { +void FastAdjuster::tooMany(int min, int n_detected) +{ thresh_++; } \end{lstlisting} @@ -112,7 +116,8 @@ virtual bool good() const = 0; } An example implementation of this is \begin{lstlisting} -bool FastAdjuster::good() const { +bool FastAdjuster::good() const +{ return (thresh_ > 1) && (thresh_ < 200); } \end{lstlisting} @@ -122,7 +127,8 @@ An \cvCppCross{AdjusterAdapter} for the \cvCppCross{FastFeatureDetector}. This w threshhold by 1 \begin{lstlisting} -class FastAdjuster FastAdjuster: public AdjusterAdapter { +class FastAdjuster FastAdjuster: public AdjusterAdapter +{ public: FastAdjuster(int init_thresh = 20, bool nonmax = true); ... @@ -133,7 +139,8 @@ public: An \cvCppCross{AdjusterAdapter} for the \cvCppCross{StarFeatureDetector}. This adjusts the responseThreshhold of StarFeatureDetector. \begin{lstlisting} -class StarAdjuster: public AdjusterAdapter { +class StarAdjuster: public AdjusterAdapter +{ StarAdjuster(double initial_thresh = 30.0); ... }; @@ -144,7 +151,8 @@ class StarAdjuster: public AdjusterAdapter { An \cvCppCross{AdjusterAdapter} for the \cvCppCross{SurfFeatureDetector}. This adjusts the hessianThreshold of SurfFeatureDetector. \begin{lstlisting} -class SurfAdjuster: public SurfAdjuster { +class SurfAdjuster: public SurfAdjuster +{ SurfAdjuster(); ... };