object_categorization.rst 7.09 KB
Newer Older
wester committed
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206
Object Categorization
=====================

.. highlight:: cpp

This section describes approaches based on local 2D features and used to categorize objects.

.. note::

   * A complete Bag-Of-Words sample can be found at opencv_source_code/samples/cpp/bagofwords_classification.cpp

   * (Python) An example using the features2D framework to perform object categorization can be found at opencv_source_code/samples/python2/find_obj.py

BOWTrainer
----------
.. ocv:class:: BOWTrainer

Abstract base class for training the *bag of visual words* vocabulary from a set of descriptors.
For details, see, for example, *Visual Categorization with Bags of Keypoints* by Gabriella Csurka, Christopher R. Dance,
Lixin Fan, Jutta Willamowski, Cedric Bray, 2004. ::

    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:
        ...
    };

BOWTrainer::add
-------------------
Adds descriptors to a training set.

.. ocv:function:: void BOWTrainer::add( const Mat& descriptors )

    :param descriptors: Descriptors to add to a training set. Each row of  the ``descriptors``  matrix is a descriptor.

The training set is clustered using ``clustermethod`` to construct the vocabulary.

BOWTrainer::getDescriptors
------------------------------
Returns a training set of descriptors.

.. ocv:function:: const vector<Mat>& BOWTrainer::getDescriptors() const



BOWTrainer::descripotorsCount
---------------------------------
Returns the count of all descriptors stored in the training set.

.. ocv:function:: int BOWTrainer::descripotorsCount() const



BOWTrainer::cluster
-----------------------
Clusters train descriptors.

.. ocv:function:: Mat BOWTrainer::cluster() const

.. ocv:function:: Mat BOWTrainer::cluster( const Mat& descriptors ) const

    :param descriptors: Descriptors to cluster. Each row of  the ``descriptors``  matrix is a descriptor. Descriptors are not added to the inner train descriptor set.

The vocabulary consists of cluster centers. So, this method returns the vocabulary. In the first variant of the method, train descriptors stored in the object are clustered. In the second variant, input descriptors are clustered.

BOWKMeansTrainer
----------------
.. ocv:class:: BOWKMeansTrainer : public BOWTrainer

:ocv:func:`kmeans` -based class to train visual vocabulary using the *bag of visual words* approach.
::

    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:
        ...
    };

BOWKMeansTrainer::BOWKMeansTrainer
----------------------------------

The constructor.

.. ocv:function:: BOWKMeansTrainer::BOWKMeansTrainer( int clusterCount, const TermCriteria& termcrit=TermCriteria(), int attempts=3, int flags=KMEANS_PP_CENTERS )

    See :ocv:func:`kmeans` function parameters.

BOWImgDescriptorExtractor
-------------------------
.. ocv:class:: BOWImgDescriptorExtractor

Class to compute an image descriptor using the *bag of visual words*. Such a computation consists of the following steps:

    #. Compute descriptors for a given image and its keypoints set.
    #. Find the nearest visual words from the vocabulary for each keypoint descriptor.
    #. Compute the bag-of-words image descriptor as is a normalized histogram of vocabulary words encountered in the image. The ``i``-th bin of the histogram is a frequency of ``i``-th word of the vocabulary in the given image.

The class declaration is the following: ::

        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:
            ...
        };




BOWImgDescriptorExtractor::BOWImgDescriptorExtractor
--------------------------------------------------------
The constructor.

.. ocv:function:: BOWImgDescriptorExtractor::BOWImgDescriptorExtractor(           const Ptr<DescriptorExtractor>& dextractor,          const Ptr<DescriptorMatcher>& dmatcher )

    :param dextractor: Descriptor extractor that is used to compute descriptors for an input image and its keypoints.

    :param dmatcher: Descriptor matcher that is used to find the nearest word of the trained vocabulary for each keypoint descriptor of the image.



BOWImgDescriptorExtractor::setVocabulary
--------------------------------------------
Sets a visual vocabulary.

.. ocv:function:: void BOWImgDescriptorExtractor::setVocabulary( const Mat& vocabulary )

    :param vocabulary: Vocabulary (can be trained using the inheritor of  :ocv:class:`BOWTrainer` ). Each row of the vocabulary is a visual word (cluster center).



BOWImgDescriptorExtractor::getVocabulary
--------------------------------------------
Returns the set vocabulary.

.. ocv:function:: const Mat& BOWImgDescriptorExtractor::getVocabulary() const



BOWImgDescriptorExtractor::compute
--------------------------------------
Computes an image descriptor using the set visual vocabulary.

.. ocv:function:: void BOWImgDescriptorExtractor::compute( const Mat& image, vector<KeyPoint>& keypoints, Mat& imgDescriptor, vector<vector<int> >* pointIdxsOfClusters=0, Mat* descriptors=0 )

    :param image: Image, for which the descriptor is computed.

    :param keypoints: Keypoints detected in the input image.

    :param imgDescriptor: Computed output image descriptor.

    :param pointIdxsOfClusters: Indices of keypoints that belong to the cluster. This means that ``pointIdxsOfClusters[i]``  are keypoint indices that belong to the  ``i`` -th cluster (word of vocabulary) returned if it is non-zero.

    :param descriptors: Descriptors of the image keypoints  that are returned if they are non-zero.



BOWImgDescriptorExtractor::descriptorSize
---------------------------------------------
Returns an image descriptor size if the vocabulary is set. Otherwise, it returns 0.

.. ocv:function:: int BOWImgDescriptorExtractor::descriptorSize() const



BOWImgDescriptorExtractor::descriptorType
---------------------------------------------

Returns an image descriptor type.

.. ocv:function:: int BOWImgDescriptorExtractor::descriptorType() const