updated doc on features2d

doc/features2d_object_categorization.tex

@@ -0,0 +1,200 @@
+\ifCpp
+\section{Object Categorization}
+Some approaches based on local 2D features and used to object categorization 
+are described in this section.
+
+\cvclass{BOWTrainer}
+Abstract base class for training ''bag of visual words'' vocabulary from a set of descriptors. 
+See e.g. ''Visual Categorization with Bags of Keypoints'' of Gabriella Csurka, Christopher R. Dance, 
+Lixin Fan, Jutta Willamowski, Cedric Bray, 2004.
+
+\begin{lstlisting}
+class BOWTrainer
+{
+public:
+    BOWTrainer(){}
+    virtual ~BOWTrainer(){}
+
+    void add( const Mat& descriptors );
+    const vector<Mat>& getDescriptors() const;
+    int descripotorsCount() const;
+
+    virtual void clear();
+
+    virtual Mat cluster() const = 0;
+    virtual Mat cluster( const Mat& descriptors ) const = 0;
+
+protected:
+    ...
+};
+\end{lstlisting}
+
+\cvCppFunc{BOWTrainer::add}
+Add descriptors to training set. The training set will be clustered using \texttt{cluster} 
+method to construct vocabulary.
+
+\cvdefCpp{
+void BOWTrainer::add( const Mat\& descriptors );
+}
+
+\begin{description}
+\cvarg{descriptors}{Descriptors to add to training set. Each row of \texttt{descriptors}
+					matrix is a one descriptor.}
+\end{description}
+
+\cvCppFunc{BOWTrainer::getDescriptors}
+Returns training set of descriptors.
+
+\cvdefCpp{
+const vector<Mat>\& BOWTrainer::getDescriptors() const;
+}
+
+\cvCppFunc{BOWTrainer::descripotorsCount}
+Returns count of all descriptors stored in the training set.
+
+\cvdefCpp{
+const vector<Mat>\& BOWTrainer::descripotorsCount() const;
+}
+
+\cvCppFunc{BOWTrainer::cluster}
+Cluster train descriptors. Vocabulary consists from cluster centers. So this method 
+returns vocabulary. In first method variant the stored in object train descriptors will be 
+clustered, in second variant -- input descriptors will be clustered.
+
+\cvdefCpp{
+Mat BOWTrainer::cluster() const;
+}
+
+\cvdefCpp{
+Mat BOWTrainer::cluster( const Mat\& descriptors ) const;
+}
+
+\begin{description}
+\cvarg{descriptors}{Descriptors to cluster. Each row of \texttt{descriptors}
+					matrix is a one descriptor. Descriptors will not be added 
+					to the inner train descriptor set.}
+\end{description}
+
+\cvclass{BOWKMeansTrainer}
+\cvCppCross{kmeans} based class to train visual vocabulary using the ''bag of visual words'' approach.
+
+\begin{lstlisting}
+class BOWKMeansTrainer : public BOWTrainer
+{
+public:
+    BOWKMeansTrainer( int clusterCount, const TermCriteria& termcrit=TermCriteria(),
+                      int attempts=3, int flags=KMEANS_PP_CENTERS );
+    virtual ~BOWKMeansTrainer(){}
+
+    // Returns trained vocabulary (i.e. cluster centers).
+    virtual Mat cluster() const;
+    virtual Mat cluster( const Mat& descriptors ) const;
+
+protected:
+    ...
+};
+\end{lstlisting}
+To gain an understanding of constructor parameters see \cvCppCross{kmeans} function 
+arguments.
+
+
+\cvclass{BOWImgDescriptorExtractor}
+ Class to compute image descriptor using ''bad of visual words''. In few, 
+ such computing consists from the following steps: 
+ 1. Compute descriptors for given image and it's keypoints set, \\
+ 2. Find nearest visual words from vocabulary for each keypoint descriptor, \\
+ 3. Image descriptor is a normalized histogram of vocabulary words encountered in the image. I.e. 
+ \texttt{i}-bin of the histogram is a frequency of \texttt{i}-word of vocabulary in the given image.
+
+\begin{lstlisting}
+class BOWImgDescriptorExtractor
+{
+public:
+    BOWImgDescriptorExtractor( const Ptr<DescriptorExtractor>& dextractor,
+                               const Ptr<DescriptorMatcher>& dmatcher );
+    virtual ~BOWImgDescriptorExtractor(){}
+
+    void setVocabulary( const Mat& vocabulary );
+    const Mat& getVocabulary() const;
+    void compute( const Mat& image, vector<KeyPoint>& keypoints, 
+                  Mat& imgDescriptor, 
+                  vector<vector<int> >* pointIdxsOfClusters=0, 
+                  Mat* descriptors=0 );
+    int descriptorSize() const;
+    int descriptorType() const;
+
+protected:
+    ...
+};
+\end{lstlisting}
+
+\cvCppFunc{BOWImgDescriptorExtractor::BOWImgDescriptorExtractor}
+Constructor.
+
+\cvdefCpp{
+BOWImgDescriptorExtractor::BOWImgDescriptorExtractor( 
+	\par const Ptr<DescriptorExtractor>\& dextractor,
+	\par const Ptr<DescriptorMatcher>\& dmatcher );
+}
+
+\begin{description}
+\cvarg{dextractor}{Descriptor extractor that will be used to compute descriptors 
+				   for input image and it's keypoints.}
+\cvarg{dmatcher}{Descriptor matcher that will be used to find nearest word of trained vocabulary to
+				 each keupoints descriptor of the image.}
+\end{description}
+
+\cvCppFunc{BOWImgDescriptorExtractor::setVocabulary}
+Method to set visual vocabulary.
+
+\cvdefCpp{
+void BOWImgDescriptorExtractor::setVocabulary( const Mat\& vocabulary );
+}
+
+\begin{description}
+\cvarg{vocabulary}{Vocabulary (can be trained using inheritor of \cvCppCross{BOWTrainer}). 
+				   Each row of vocabulary is a one visual word (cluster center).}
+\end{description}
+
+\cvCppFunc{BOWImgDescriptorExtractor::getVocabulary}
+Returns set vocabulary.
+
+\cvdefCpp{
+const Mat\& BOWImgDescriptorExtractor::getVocabulary() const;
+}
+
+\cvCppFunc{BOWImgDescriptorExtractor::compute}
+Compute image descriptor using set visual vocabulary.
+
+\cvdefCpp{    
+void BOWImgDescriptorExtractor::compute( const Mat\& image, 
+	\par vector<KeyPoint>\& keypoints, Mat\& imgDescriptor, 
+	\par vector<vector<int> >* pointIdxsOfClusters=0, 
+	\par Mat* descriptors=0 );
+}
+
+\begin{description}
+\cvarg{image}{The image. Image descriptor will be computed for this.}
+\cvarg{keypoints}{Keypoints detected in the input image.}
+\cvarg{imgDescriptor}{This is output, i.e. computed image descriptor.}
+\cvarg{pointIdxsOfClusters}{Indices of keypoints which belong to the cluster, i.e. 
+			\texttt{pointIdxsOfClusters[i]} is keypoint indices which belong 
+			to the \texttt{i-}cluster (word of vocabulary) (returned if it is not 0.)}
+\cvarg{descriptors}{Descriptors of the image keypoints (returned if it is not 0.)}
+\end{description}
+
+\cvCppFunc{BOWImgDescriptorExtractor::descriptorSize}
+Returns image discriptor size, if vocabulary was set, and 0 otherwise.
+
+\cvdefCpp{
+int BOWImgDescriptorExtractor::descriptorSize() const;
+}
+
+\cvCppFunc{BOWImgDescriptorExtractor::descriptorType}
+ Returns image descriptor type.
+ 
+\cvdefCpp{
+int BOWImgDescriptorExtractor::descriptorType() const;
+}
+
+\fi