Adding a .tex document for the dynamic feature detectors

doc/features2d_common_detection_description.tex

@@ -299,46 +299,8 @@ protected:
 };
 \end{lstlisting}
 
-
-\cvclass{DynamicDetectorAdaptor}
-An adaptively adjusting detector that iteratively detects until the desired number
-of features are found.
-
-Adapters can easily be implemented for any detector through the creation of an Adjuster
-object.
-
-Beware that this is not thread safe - as the adjustment of parameters breaks the const
-of the detection routine...
-
-\begin{lstlisting}
-template<typename Adjuster>
-class DynamicDetectorAdaptor: public FeatureDetector {
-public:
-	DynamicDetectorAdaptor(int min_features, int max_features, int max_iters, 
-						   const Adjuster& a = Adjuster());
-    ...
-};
-
-//expected Adjuster interface
-class MyAdjuster {
-public:
-	//this should call a FeatureDetector and populate keypoints
-	//e.g. FASTFeatureDetector(thresh).detect(img,mask,keypoints)
-	void detect(const Mat& img, const Mat& mask, std::vector<KeyPoint>& keypoints) const;
-
-	//called if there are too few features detected, should adjust feature detector params
-	//accordingly
-	void tooFew(int min, int n_detected);
-	
-	//called if there are too many features detected, should adjust feature detector params
-	//accordingly
-	void tooMany(int max, int n_detected);
-
-	//return whether or not the threshhold is beyond
-	//a useful point
-	bool good() const;
-\end{lstlisting}
-
+%dynamic detectors doc
+\input{features2d_dynamic_detectors}
 
 \cvCppFunc{createFeatureDetector}
 Feature detector factory that creates \cvCppCross{FeatureDetector} of given type with 

doc/features2d_dynamic_detectors.tex

+\cvclass{DynamicDetector}
+An adaptively adjusting detector that iteratively detects until the desired number
+of features are found.
+
+Adapters can easily be implemented for any detector through the creation of an Adjuster
+object.
+
+Beware that this is not thread safe - as the adjustment of parameters breaks the const
+of the detection routine...
+
+\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<FeatureDetector> detector(new DynamicDetector (100, 110, 10,new FastAdjuster(20,true)));
+ 
+class CV_EXPORTS DynamicDetector: public FeatureDetector {
+public:
+
+	/**min_features the minimum desired features
+	 * max_features the maximum desired number of features
+	 * max_iters the maximum number of times to try to adjust the feature detector params
+	 * 			for the FastAdjuster this can be high, but with Star or Surf this can get time consuming
+	 * a an AdjusterAdapter that will do the detection and parameter adjustment
+	 */
+	DynamicDetector(int min_features, int max_features, int max_iters,
+			const Ptr<AdjusterAdapter>& a);
+ 	...
+};
+ \end{lstlisting}
+\cvclass{AdjusterAdapter}
+A feature detector parameter adjuster interface, this is used by the \cvCppCross{DynamicDetector}
+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 {
+public:
+	/** pure virtual interface
+	 */
+	virtual ~AdjusterAdapter() {
+	}
+	/** too few features were detected so, adjust the detector params accordingly
+	 * \param min the minimum number of desired features
+	 * \param n_detected the number previously detected
+	 */
+	virtual void tooFew(int min, int n_detected) = 0;
+	/** too many features were detected so, adjust the detector params accordingly
+	 * \param max the maximum number of desired features
+	 * \param n_detected the number previously detected
+	 */
+	virtual void tooMany(int max, int n_detected) = 0;
+	/** are params maxed out or still valid?
+	 * \return false if the parameters can't be adjusted any more
+	 */
+	virtual bool good() const = 0;
+};
+\end{lstlisting}
+ 
+\cvclass{FastAdjuster}
+An \cvCppCross{AdjusterAdapter} for the \cvCppCross{FastFeatureDetector}. This will basically decrement or increment the
+threshhold by 1
+
+\begin{lstlisting}
+class FastAdjuster FastAdjuster: public AdjusterAdapter {
+public:
+	/**\param init_thresh the initial threshhold to start with, default = 20
+	 * \param nonmax whether to use non max or not for fast feature detection
+	 */
+	FastAdjuster(int init_thresh = 20, bool nonmax = true);
+	...
+};
+\end{lstlisting}
+
+\cvclass{StarAdjuster}
+An \cvCppCross{AdjusterAdapter} for the \cvCppCross{StarFeatureDetector}.  This adjusts the responseThreshhold of 
+StarFeatureDetector.
+\begin{lstlisting}
+class StarAdjuster: public AdjusterAdapter {
+	StarAdjuster(double initial_thresh = 30.0);
+	...
+};
+\end{lstlisting}
+
+
+\cvclass{SurfAdjuster}
+An \cvCppCross{AdjusterAdapter} for the \cvCppCross{SurfFeatureDetector}.  This adjusts the responseThreshhold of 
+SurfFeatureDetector.
+\begin{lstlisting}
+class SurfAdjuster: public SurfAdjuster {
+	SurfAdjuster();
+	...
+};
+\end{lstlisting}