opencv/doc/features2d_object_categorization.tex

\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