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 that can not be represented as vectors in a multidimensional space. GenericDescriptorMatcher is a more generic interface for descriptors. It does not make any assumptions about descriptor representation. Every descriptor with DescriptorExtractor() interface has a wrapper with GenericDescriptorMatcher interface (see VectorDescriptorMatcher() ). There are descriptors such as One way descriptor and Ferns that have GenericDescriptorMatcher interface implemented, but do not support DescriptorExtractor() .

GenericDescriptorMatcher

Comments from the Wiki

GenericDescriptorMatcher

Abstract interface for a keypoint descriptor extracting and matching. There is DescriptorExtractor() and DescriptorMatcher() for these purposes too, but their interfaces are intended for descriptors represented as vectors in a multidimensional space. GenericDescriptorMatcher is a more generic interface for descriptors. As DescriptorMatcher() , GenericDescriptorMatcher has two groups of match methods: for matching keypoints of one image with other image or with image set.

class GenericDescriptorMatcher
{
public:
    GenericDescriptorMatcher();
    virtual ~GenericDescriptorMatcher();

    virtual void add( const vector<Mat>& images,
                      vector<vector<KeyPoint> >& keypoints );

    const vector<Mat>& getTrainImages() const;
    const vector<vector<KeyPoint> >& getTrainKeypoints() const;
    virtual void clear();

    virtual void train() = 0;

    virtual bool isMaskSupported() = 0;

    void classify( const Mat& queryImage,
                   vector<KeyPoint>& queryKeypoints,
                   const Mat& trainImage,
                   vector<KeyPoint>& trainKeypoints ) const;
    void classify( const Mat& queryImage,
                   vector<KeyPoint>& queryKeypoints );

    /*
     * Group of methods to match keypoints from image pair.
     */
    void match( const Mat& queryImage, vector<KeyPoint>& queryKeypoints,
                const Mat& trainImage, vector<KeyPoint>& trainKeypoints,
                vector<DMatch>& matches, const Mat& mask=Mat() ) const;
    void knnMatch( const Mat& queryImage, vector<KeyPoint>& queryKeypoints,
                   const Mat& trainImage, vector<KeyPoint>& trainKeypoints,
                   vector<vector<DMatch> >& matches, int k,
                   const Mat& mask=Mat(), bool compactResult=false ) const;
    void radiusMatch( const Mat& queryImage, vector<KeyPoint>& queryKeypoints,
                      const Mat& trainImage, vector<KeyPoint>& trainKeypoints,
                      vector<vector<DMatch> >& matches, float maxDistance,
                      const Mat& mask=Mat(), bool compactResult=false ) const;
    /*
     * Group of methods to match keypoints from one image to image set.
     */
    void match( const Mat& queryImage, vector<KeyPoint>& queryKeypoints,
                vector<DMatch>& matches, const vector<Mat>& masks=vector<Mat>() );
    void knnMatch( const Mat& queryImage, vector<KeyPoint>& queryKeypoints,
                   vector<vector<DMatch> >& matches, int k,
                   const vector<Mat>& masks=vector<Mat>(), bool compactResult=false );
    void radiusMatch( const Mat& queryImage, vector<KeyPoint>& queryKeypoints,
                      vector<vector<DMatch> >& matches, float maxDistance,
                      const vector<Mat>& masks=vector<Mat>(), bool compactResult=false );

    virtual void read( const FileNode& );
    virtual void write( FileStorage& ) const;

    virtual Ptr<GenericDescriptorMatcher> clone( bool emptyTrainData=false ) const = 0;

protected:
    ...
};

cv::GenericDescriptorMatcher::add

Comments from the Wiki

void GenericDescriptorMatcher::add(const vector<Mat>& images, vector<vector<KeyPoint> >& keypoints)

Adds images and keypoints from them to the train collection (descriptors are supposed to be calculated here).

If train collection is not empty new image and keypoints from them will be added to existing data.

param images:Image collection. param keypoints:  Point collection. Assumes that keypoints[i] are keypoints detected in an image images[i] .

cv::GenericDescriptorMatcher::getTrainImages

Comments from the Wiki

..

cv::

Comments from the Wiki

..

cv::

Comments from the Wiki

..

cv::

Comments from the Wiki

..

cv::

Comments from the Wiki

..

cv::

Comments from the Wiki

GenericDescriptorMatcher::add()

void GenericDescriptorMatcher::classify(const Mat& queryImage, vector<KeyPoint>& queryKeypoints, const Mat& trainImage, vector<KeyPoint>& trainKeypoints) const

Classifies query keypoints under keypoints of one train image qiven as input argument

(first version of the method) or train image collection that set using (second version).

void GenericDescriptorMatcher::classify(const Mat& queryImage, vector<KeyPoint>& queryKeypoints)

Parameters:

• queryImage – The query image.
• queryKeypoints – Keypoints from the query image.
• trainImage – The train image.
• trainKeypoints – Keypoints from the train image.

cv::GenericDescriptorMatcher::match

Comments from the Wiki

GenericDescriptorMatcher::add() DescriptorMatcher::match()

void GenericDescriptorMatcher::match(const Mat& queryImage, vector<KeyPoint>& queryKeypoints, const Mat& trainImage, vector<KeyPoint>& trainKeypoints, vector<DMatch>& matches, const Mat& mask=Mat()) const

Find best match for query keypoints to the training set. In first version of method

one train image and keypoints detected on it - are input arguments. In second version query keypoints are matched to training collectin that set using . As in the mask can be set.

void GenericDescriptorMatcher::match(const Mat& queryImage, vector<KeyPoint>& queryKeypoints, vector<DMatch>& matches, const vector<Mat>& masks=vector<Mat>())

Parameters:

• queryImage – Query image.
• queryKeypoints – Keypoints detected in queryImage .
• trainImage – Train image. This will not be added to train image collection stored in class object.
• trainKeypoints – Keypoints detected in trainImage . They will not be added to train points collection stored in class object.
• matches –

  Matches. If some query descriptor (keypoint) masked out in mask no match will be added for this descriptor.

  So matches size may be less query keypoints count.

• mask – Mask specifying permissible matches between input query and train keypoints.
• masks – The set of masks. Each masks[i] specifies permissible matches between input query keypoints and stored train keypointss from i-th image.

cv::GenericDescriptorMatcher::knnMatch

Comments from the Wiki

GenericDescriptorMatcher::match() DescriptorMatcher::knnMatch()

void GenericDescriptorMatcher::knnMatch(const Mat& queryImage, vector<KeyPoint>& queryKeypoints, const Mat& trainImage, vector<KeyPoint>& trainKeypoints, vector<vector<DMatch> >& matches, int k, const Mat& mask=Mat(), bool compactResult=false) const

Find the knn best matches for each keypoint from a query set with train keypoints.

Found knn (or less if not possible) matches are returned in distance increasing order. Details see in and .

void GenericDescriptorMatcher::knnMatch(const Mat& queryImage, vector<KeyPoint>& queryKeypoints, vector<vector<DMatch> >& matches, int k, const vector<Mat>& masks=vector<Mat>(), bool compactResult=false)

cv::GenericDescriptorMatcher::radiusMatch

Comments from the Wiki

GenericDescriptorMatcher::match() DescriptorMatcher::radiusMatch()

void GenericDescriptorMatcher::radiusMatch(const Mat& queryImage, vector<KeyPoint>& queryKeypoints, const Mat& trainImage, vector<KeyPoint>& trainKeypoints, vector<vector<DMatch> >& matches, float maxDistance, const Mat& mask=Mat(), bool compactResult=false) const

Find the best matches for each query keypoint which have distance less than given threshold.

Found matches are returned in distance increasing order. Details see in and .

void GenericDescriptorMatcher::radiusMatch(const Mat& queryImage, vector<KeyPoint>& queryKeypoints, vector<vector<DMatch> >& matches, float maxDistance, const vector<Mat>& masks=vector<Mat>(), bool compactResult=false)

cv::GenericDescriptorMatcher::read

Comments from the Wiki

void GenericDescriptorMatcher::read(const FileNode& fn)

Reads matcher object from a file node.

cv::GenericDescriptorMatcher::write

Comments from the Wiki

void GenericDescriptorMatcher::write(FileStorage& fs) const

Writes match object to a file storage

cv::GenericDescriptorMatcher::clone

Comments from the Wiki

Ptr<GenericDescriptorMatcher>\GenericDescriptorMatcher::clone(bool emptyTrainData) const

Clone the matcher.

Parameters:

• emptyTrainData – If emptyTrainData is false the method create deep copy of the object, i.e. copies both parameters and train data. If emptyTrainData is true the method create object copy with current parameters but with empty train data.

OneWayDescriptorMatcher

Comments from the Wiki

OneWayDescriptorMatcher

Wrapping class for computing, matching and classification of descriptors using OneWayDescriptorBase() class.

class OneWayDescriptorMatcher : public GenericDescriptorMatcher
{
public:
    class Params
    {
    public:
        static const int POSE_COUNT = 500;
        static const int PATCH_WIDTH = 24;
        static const int PATCH_HEIGHT = 24;
        static float GET_MIN_SCALE() { return 0.7f; }
        static float GET_MAX_SCALE() { return 1.5f; }
        static float GET_STEP_SCALE() { return 1.2f; }

        Params( int poseCount = POSE_COUNT,
                Size patchSize = Size(PATCH_WIDTH, PATCH_HEIGHT),
                string pcaFilename = string(),
                string trainPath = string(), string trainImagesList = string(),
                float minScale = GET_MIN_SCALE(), float maxScale = GET_MAX_SCALE(),
                float stepScale = GET_STEP_SCALE() );

        int poseCount;
        Size patchSize;
        string pcaFilename;
        string trainPath;
        string trainImagesList;

        float minScale, maxScale, stepScale;
    };

    OneWayDescriptorMatcher( const Params& params=Params() );
    virtual ~OneWayDescriptorMatcher();

    void initialize( const Params& params, const Ptr<OneWayDescriptorBase>& base=Ptr<OneWayDescriptorBase>() );

    // Clears keypoints storing in collection and OneWayDescriptorBase
    virtual void clear();

    virtual void train();

    virtual bool isMaskSupported();

    virtual void read( const FileNode &fn );
    virtual void write( FileStorage& fs ) const;

    virtual Ptr<GenericDescriptorMatcher> clone( bool emptyTrainData=false ) const;
protected:
    ...
};

FernDescriptorMatcher

Comments from the Wiki

FernDescriptorMatcher

Wrapping class for computing, matching and classification of descriptors using FernClassifier() class.

class FernDescriptorMatcher : public GenericDescriptorMatcher
{
public:
    class Params
    {
    public:
        Params( int nclasses=0,
                int patchSize=FernClassifier::PATCH_SIZE,
                int signatureSize=FernClassifier::DEFAULT_SIGNATURE_SIZE,
                int nstructs=FernClassifier::DEFAULT_STRUCTS,
                int structSize=FernClassifier::DEFAULT_STRUCT_SIZE,
                int nviews=FernClassifier::DEFAULT_VIEWS,
                int compressionMethod=FernClassifier::COMPRESSION_NONE,
                const PatchGenerator& patchGenerator=PatchGenerator() );

        Params( const string& filename );

        int nclasses;
        int patchSize;
        int signatureSize;
        int nstructs;
        int structSize;
        int nviews;
        int compressionMethod;
        PatchGenerator patchGenerator;

        string filename;
    };

    FernDescriptorMatcher( const Params& params=Params() );
    virtual ~FernDescriptorMatcher();

    virtual void clear();

    virtual void train();

    virtual bool isMaskSupported();

    virtual void read( const FileNode &fn );
    virtual void write( FileStorage& fs ) const;

    virtual Ptr<GenericDescriptorMatcher> clone( bool emptyTrainData=false ) const;

protected:
        ...
};

VectorDescriptorMatcher

Comments from the Wiki

VectorDescriptorMatcher

Class used for matching descriptors that can be described as vectors in a finite-dimensional space.

class CV_EXPORTS VectorDescriptorMatcher : public GenericDescriptorMatcher
{
public:
    VectorDescriptorMatcher( const Ptr<DescriptorExtractor>& extractor, const Ptr<DescriptorMatcher>& matcher );
    virtual ~VectorDescriptorMatcher();

    virtual void add( const vector<Mat>& imgCollection,
                      vector<vector<KeyPoint> >& pointCollection );
    virtual void clear();
    virtual void train();
    virtual bool isMaskSupported();

    virtual void read( const FileNode& fn );
    virtual void write( FileStorage& fs ) const;

    virtual Ptr<GenericDescriptorMatcher> clone( bool emptyTrainData=false ) const;

protected:
    ...
};

Example of creating:

VectorDescriptorMatcher matcher( new SurfDescriptorExtractor,
                                 new BruteForceMatcher<L2<float> > );