+++ /dev/null
-Common Interfaces of Generic Descriptor Matchers
-================================================
-
-.. highlight:: cpp
-
-Matchers of keypoint descriptors in OpenCV have wrappers with a common interface that enables you to easily switch
-between different algorithms solving the same problem. This section is devoted to matching descriptors
-that cannot 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 the
-:ocv:class:`DescriptorExtractor` interface has a wrapper with the ``GenericDescriptorMatcher`` interface (see
-:ocv:class:`VectorDescriptorMatcher` ).
-There are descriptors such as the One-way descriptor and Ferns that have the ``GenericDescriptorMatcher`` interface implemented but do not support ``DescriptorExtractor``.
-
-.. note::
-
- * An example explaining keypoint description can be found at opencv_source_code/samples/cpp/descriptor_extractor_matcher.cpp
- * An example on descriptor matching evaluation can be found at opencv_source_code/samples/cpp/detector_descriptor_matcher_evaluation.cpp
- * An example on one to many image matching can be found at opencv_source_code/samples/cpp/matching_to_many_images.cpp
-
-GenericDescriptorMatcher
-------------------------
-.. ocv:class:: GenericDescriptorMatcher
-
-Abstract interface for extracting and matching a keypoint descriptor. There are also :ocv:class:`DescriptorExtractor` and :ocv:class:`DescriptorMatcher` for these purposes but their interfaces are intended for descriptors represented as vectors in a multidimensional space. ``GenericDescriptorMatcher`` is a more generic interface for descriptors. ``DescriptorMatcher`` and ``GenericDescriptorMatcher`` have two groups of match methods: for matching keypoints of an image with another image or with an image set. ::
-
- class GenericDescriptorMatcher
- {
- public:
- GenericDescriptorMatcher();
- virtual ~GenericDescriptorMatcher();
-
- virtual void add( InputArrayOfArrays 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( InputArray queryImage,
- vector<KeyPoint>& queryKeypoints,
- InputArray trainImage,
- vector<KeyPoint>& trainKeypoints ) const;
- void classify( InputArray queryImage,
- vector<KeyPoint>& queryKeypoints );
-
- /*
- * Group of methods to match keypoints from an image pair.
- */
- void match( InputArray queryImage, vector<KeyPoint>& queryKeypoints,
- InputArray trainImage, vector<KeyPoint>& trainKeypoints,
- vector<DMatch>& matches, InputArray mask=noArray() ) const;
- void knnMatch( InputArray queryImage, vector<KeyPoint>& queryKeypoints,
- InputArray trainImage, vector<KeyPoint>& trainKeypoints,
- vector<vector<DMatch> >& matches, int k,
- InputArray mask=noArray(), bool compactResult=false ) const;
- void radiusMatch( InputArray queryImage, vector<KeyPoint>& queryKeypoints,
- InputArray trainImage, vector<KeyPoint>& trainKeypoints,
- vector<vector<DMatch> >& matches, float maxDistance,
- InputArray mask=noArray(), bool compactResult=false ) const;
- /*
- * Group of methods to match keypoints from one image to an image set.
- */
- void match( InputArray queryImage, vector<KeyPoint>& queryKeypoints,
- vector<DMatch>& matches, InputArrayOfArrays masks=noArray() );
- void knnMatch( InputArray queryImage, vector<KeyPoint>& queryKeypoints,
- vector<vector<DMatch> >& matches, int k,
- InputArrayOfArrays masks=noArray(), bool compactResult=false );
- void radiusMatch( InputArray queryImage, vector<KeyPoint>& queryKeypoints,
- vector<vector<DMatch> >& matches, float maxDistance,
- InputArrayOfArrays masks=noArray(), bool compactResult=false );
-
- virtual void read( const FileNode& );
- virtual void write( FileStorage& ) const;
-
- virtual Ptr<GenericDescriptorMatcher> clone( bool emptyTrainData=false ) const = 0;
-
- protected:
- ...
- };
-
-
-
-
-GenericDescriptorMatcher::add
----------------------------------
-Adds images and their keypoints to the training collection stored in the class instance.
-
-.. ocv:function:: void GenericDescriptorMatcher::add( InputArrayOfArrays images, vector<vector<KeyPoint> >& keypoints )
-
- :param images: Image collection.
-
- :param keypoints: Point collection. It is assumed that ``keypoints[i]`` are keypoints detected in the image ``images[i]`` .
-
-
-
-GenericDescriptorMatcher::getTrainImages
---------------------------------------------
-Returns a train image collection.
-
-.. ocv:function:: const vector<Mat>& GenericDescriptorMatcher::getTrainImages() const
-
-
-
-GenericDescriptorMatcher::getTrainKeypoints
------------------------------------------------
-Returns a train keypoints collection.
-
-.. ocv:function:: const vector<vector<KeyPoint> >& GenericDescriptorMatcher::getTrainKeypoints() const
-
-
-
-GenericDescriptorMatcher::clear
------------------------------------
-Clears a train collection (images and keypoints).
-
-.. ocv:function:: void GenericDescriptorMatcher::clear()
-
-
-
-GenericDescriptorMatcher::train
------------------------------------
-Trains descriptor matcher
-
-.. ocv:function:: void GenericDescriptorMatcher::train()
-
-Prepares descriptor matcher, for example, creates a tree-based structure, to extract descriptors or to optimize descriptors matching.
-
-
-GenericDescriptorMatcher::isMaskSupported
----------------------------------------------
-Returns ``true`` if a generic descriptor matcher supports masking permissible matches.
-
-.. ocv:function:: bool GenericDescriptorMatcher::isMaskSupported()
-
-
-
-GenericDescriptorMatcher::classify
---------------------------------------
-Classifies keypoints from a query set.
-
-.. ocv:function:: void GenericDescriptorMatcher::classify( InputArray queryImage, vector<KeyPoint>& queryKeypoints, InputArray trainImage, vector<KeyPoint>& trainKeypoints ) const
-
-.. ocv:function:: void GenericDescriptorMatcher::classify( InputArray queryImage, vector<KeyPoint>& queryKeypoints )
-
- :param queryImage: Query image.
-
- :param queryKeypoints: Keypoints from a query image.
-
- :param trainImage: Train image.
-
- :param trainKeypoints: Keypoints from a train image.
-
-The method classifies each keypoint from a query set. The first variant of the method takes a train image and its keypoints as an input argument. The second variant uses the internally stored training collection that can be built using the ``GenericDescriptorMatcher::add`` method.
-
-The methods do the following:
-
-#.
- Call the ``GenericDescriptorMatcher::match`` method to find correspondence between the query set and the training set.
-
-#.
- Set the ``class_id`` field of each keypoint from the query set to ``class_id`` of the corresponding keypoint from the training set.
-
-
-
-GenericDescriptorMatcher::match
------------------------------------
-Finds the best match in the training set for each keypoint from the query set.
-
-.. ocv:function:: void GenericDescriptorMatcher::match(InputArray queryImage, vector<KeyPoint>& queryKeypoints, InputArray trainImage, vector<KeyPoint>& trainKeypoints, vector<DMatch>& matches, InputArray mask=noArray() ) const
-
-.. ocv:function:: void GenericDescriptorMatcher::match( InputArray queryImage, vector<KeyPoint>& queryKeypoints, vector<DMatch>& matches, InputArrayOfArrays masks=noArray() )
-
- :param queryImage: Query image.
-
- :param queryKeypoints: Keypoints detected in ``queryImage`` .
-
- :param trainImage: Train image. It is not added to a train image collection stored in the class object.
-
- :param trainKeypoints: Keypoints detected in ``trainImage`` . They are not added to a train points collection stored in the class object.
-
- :param matches: Matches. If a query descriptor (keypoint) is masked out in ``mask`` , match is added for this descriptor. So, ``matches`` size may be smaller than the query keypoints count.
-
- :param mask: Mask specifying permissible matches between an input query and train keypoints.
-
- :param masks: Set of masks. Each ``masks[i]`` specifies permissible matches between input query keypoints and stored train keypoints from the i-th image.
-
-The methods find the best match for each query keypoint. In the first variant of the method, a train image and its keypoints are the input arguments. In the second variant, query keypoints are matched to the internally stored training collection that can be built using the ``GenericDescriptorMatcher::add`` method. Optional mask (or masks) can be passed to specify which query and training descriptors can be matched. Namely, ``queryKeypoints[i]`` can be matched with ``trainKeypoints[j]`` only if ``mask.at<uchar>(i,j)`` is non-zero.
-
-
-
-GenericDescriptorMatcher::knnMatch
---------------------------------------
-Finds the ``k`` best matches for each query keypoint.
-
-.. ocv:function:: void GenericDescriptorMatcher::knnMatch( InputArray queryImage, vector<KeyPoint>& queryKeypoints, InputArray trainImage, vector<KeyPoint>& trainKeypoints, vector<vector<DMatch> >& matches, int k, InputArray mask=noArray(), bool compactResult=false ) const
-
-.. ocv:function:: void GenericDescriptorMatcher::knnMatch( InputArray queryImage, vector<KeyPoint>& queryKeypoints, vector<vector<DMatch> >& matches, int k, InputArrayOfArrays masks=noArray(), bool compactResult=false )
-
-The methods are extended variants of ``GenericDescriptorMatch::match``. The parameters are similar, and the semantics is similar to ``DescriptorMatcher::knnMatch``. But this class does not require explicitly computed keypoint descriptors.
-
-
-
-GenericDescriptorMatcher::radiusMatch
------------------------------------------
-For each query keypoint, finds the training keypoints not farther than the specified distance.
-
-.. ocv:function:: void GenericDescriptorMatcher::radiusMatch( InputArray queryImage, vector<KeyPoint>& queryKeypoints, InputArray trainImage, vector<KeyPoint>& trainKeypoints, vector<vector<DMatch> >& matches, float maxDistance, InputArray mask=noArray(), bool compactResult=false ) const
-
-.. ocv:function:: void GenericDescriptorMatcher::radiusMatch( InputArray queryImage, vector<KeyPoint>& queryKeypoints, vector<vector<DMatch> >& matches, float maxDistance, InputArrayOfArrays masks=noArray(), bool compactResult=false )
-
-The methods are similar to ``DescriptorMatcher::radius``. But this class does not require explicitly computed keypoint descriptors.
-
-
-
-GenericDescriptorMatcher::read
-----------------------------------
-Reads a matcher object from a file node.
-
-.. ocv:function:: void GenericDescriptorMatcher::read( const FileNode& fn )
-
-
-
-GenericDescriptorMatcher::write
------------------------------------
-Writes a match object to a file storage.
-
-.. ocv:function:: void GenericDescriptorMatcher::write( FileStorage& fs ) const
-
-
-GenericDescriptorMatcher::clone
------------------------------------
-Clones the matcher.
-
-.. ocv:function:: Ptr<GenericDescriptorMatcher> GenericDescriptorMatcher::clone( bool emptyTrainData=false ) const
-
- :param emptyTrainData: If ``emptyTrainData`` is false, the method creates a deep copy of the object, that is, copies
- both parameters and train data. If ``emptyTrainData`` is true, the method creates an object copy with the current parameters
- but with empty train data.
-
-
-VectorDescriptorMatcher
------------------------
-.. ocv:class:: VectorDescriptorMatcher : public GenericDescriptorMatcher
-
-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( InputArrayOfArrays 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: ::
-
- VectorDescriptorMatcher matcher( new SurfDescriptorExtractor,
- new BruteForceMatcher<L2<float> > );