matchers.hpp

00001 /*M///////////////////////////////////////////////////////////////////////////////////////
00002 //
00003 //  IMPORTANT: READ BEFORE DOWNLOADING, COPYING, INSTALLING OR USING.
00004 //
00005 //  By downloading, copying, installing or using the software you agree to this license.
00006 //  If you do not agree to this license, do not download, install,
00007 //  copy or use the software.
00008 //
00009 //
00010 //                          License Agreement
00011 //                For Open Source Computer Vision Library
00012 //
00013 // Copyright (C) 2000-2008, Intel Corporation, all rights reserved.
00014 // Copyright (C) 2009, Willow Garage Inc., all rights reserved.
00015 // Third party copyrights are property of their respective owners.
00016 //
00017 // Redistribution and use in source and binary forms, with or without modification,
00018 // are permitted provided that the following conditions are met:
00019 //
00020 //   * Redistribution's of source code must retain the above copyright notice,
00021 //     this list of conditions and the following disclaimer.
00022 //
00023 //   * Redistribution's in binary form must reproduce the above copyright notice,
00024 //     this list of conditions and the following disclaimer in the documentation
00025 //     and/or other materials provided with the distribution.
00026 //
00027 //   * The name of the copyright holders may not be used to endorse or promote products
00028 //     derived from this software without specific prior written permission.
00029 //
00030 // This software is provided by the copyright holders and contributors "as is" and
00031 // any express or implied warranties, including, but not limited to, the implied
00032 // warranties of merchantability and fitness for a particular purpose are disclaimed.
00033 // In no event shall the Intel Corporation or contributors be liable for any direct,
00034 // indirect, incidental, special, exemplary, or consequential damages
00035 // (including, but not limited to, procurement of substitute goods or services;
00036 // loss of use, data, or profits; or business interruption) however caused
00037 // and on any theory of liability, whether in contract, strict liability,
00038 // or tort (including negligence or otherwise) arising in any way out of
00039 // the use of this software, even if advised of the possibility of such damage.
00040 //
00041 //M*/
00042 
00043 #ifndef OPENCV_STITCHING_MATCHERS_HPP
00044 #define OPENCV_STITCHING_MATCHERS_HPP
00045 
00046 #include "opencv2/core.hpp"
00047 #include "opencv2/features2d.hpp"
00048 
00049 #include "opencv2/opencv_modules.hpp"
00050 
00051 #ifdef HAVE_OPENCV_XFEATURES2D
00052 #  include "opencv2/xfeatures2d/cuda.hpp"
00053 #endif
00054 
00055 namespace cv {
00056 namespace detail {
00057 
00058 //! @addtogroup stitching_match
00059 //! @{
00060 
00061 /** @brief Structure containing image keypoints and descriptors. */
00062 struct CV_EXPORTS ImageFeatures
00063 {
00064     int img_idx;
00065     Size img_size;
00066     std::vector<KeyPoint> keypoints;
00067     UMat  descriptors;
00068 };
00069 
00070 /** @brief Feature finders base class */
00071 class CV_EXPORTS FeaturesFinder
00072 {
00073 public:
00074     virtual ~FeaturesFinder() {}
00075     /** @overload */
00076     void operator ()(InputArray image, ImageFeatures &features);
00077     /** @brief Finds features in the given image.
00078 
00079     @param image Source image
00080     @param features Found features
00081     @param rois Regions of interest
00082 
00083     @sa detail::ImageFeatures, Rect_
00084     */
00085     void operator ()(InputArray image, ImageFeatures &features, const std::vector<cv::Rect> &rois);
00086     /** @brief Finds features in the given images in parallel.
00087 
00088     @param images Source images
00089     @param features Found features for each image
00090     @param rois Regions of interest for each image
00091 
00092     @sa detail::ImageFeatures, Rect_
00093     */
00094     void operator ()(InputArrayOfArrays images, std::vector<ImageFeatures> &features,
00095                      const std::vector<std::vector<cv::Rect> > &rois);
00096     /** @overload */
00097     void operator ()(InputArrayOfArrays images, std::vector<ImageFeatures> &features);
00098     /** @brief Frees unused memory allocated before if there is any. */
00099     virtual void collectGarbage() {}
00100 
00101     /* TODO OpenCV ABI 4.x
00102     reimplement this as public method similar to FeaturesMatcher and remove private function hack
00103     @return True, if it's possible to use the same finder instance in parallel, false otherwise
00104     bool isThreadSafe() const { return is_thread_safe_; }
00105     */
00106 
00107 protected:
00108     /** @brief This method must implement features finding logic in order to make the wrappers
00109     detail::FeaturesFinder::operator()_ work.
00110 
00111     @param image Source image
00112     @param features Found features
00113 
00114     @sa detail::ImageFeatures */
00115     virtual void find(InputArray image, ImageFeatures &features) = 0;
00116     /** @brief uses dynamic_cast to determine thread-safety
00117     @return True, if it's possible to use the same finder instance in parallel, false otherwise
00118     */
00119     bool isThreadSafe() const;
00120 };
00121 
00122 /** @brief SURF features finder.
00123 
00124 @sa detail::FeaturesFinder, SURF
00125 */
00126 class CV_EXPORTS SurfFeaturesFinder : public FeaturesFinder
00127 {
00128 public:
00129     SurfFeaturesFinder(double hess_thresh = 300., int num_octaves = 3, int num_layers = 4,
00130                        int num_octaves_descr = /*4*/3, int num_layers_descr = /*2*/4);
00131 
00132 private:
00133     void find(InputArray image, ImageFeatures &features);
00134 
00135     Ptr<FeatureDetector>  detector_;
00136     Ptr<DescriptorExtractor>  extractor_;
00137     Ptr<Feature2D>  surf;
00138 };
00139 
00140 /** @brief ORB features finder. :
00141 
00142 @sa detail::FeaturesFinder, ORB
00143 */
00144 class CV_EXPORTS OrbFeaturesFinder : public FeaturesFinder
00145 {
00146 public:
00147     OrbFeaturesFinder(Size _grid_size = Size(3,1), int nfeatures=1500, float scaleFactor=1.3f, int nlevels=5);
00148 
00149 private:
00150     void find(InputArray image, ImageFeatures &features);
00151 
00152     Ptr<ORB>  orb;
00153     Size grid_size;
00154 };
00155 
00156 /** @brief AKAZE features finder. :
00157 
00158 @sa detail::FeaturesFinder, AKAZE
00159 */
00160 class CV_EXPORTS AKAZEFeaturesFinder : public detail::FeaturesFinder
00161 {
00162 public:
00163     AKAZEFeaturesFinder(int descriptor_type = AKAZE::DESCRIPTOR_MLDB,
00164                         int descriptor_size = 0,
00165                         int descriptor_channels = 3,
00166                         float threshold = 0.001f,
00167                         int nOctaves = 4,
00168                         int nOctaveLayers = 4,
00169                         int diffusivity = KAZE::DIFF_PM_G2);
00170 
00171 private:
00172     void find(InputArray image, detail::ImageFeatures &features);
00173 
00174     Ptr<AKAZE>  akaze;
00175 };
00176 
00177 #ifdef HAVE_OPENCV_XFEATURES2D
00178 class CV_EXPORTS SurfFeaturesFinderGpu : public FeaturesFinder
00179 {
00180 public:
00181     SurfFeaturesFinderGpu(double hess_thresh = 300., int num_octaves = 3, int num_layers = 4,
00182                           int num_octaves_descr = 4, int num_layers_descr = 2);
00183 
00184     void collectGarbage();
00185 
00186 private:
00187     void find(InputArray image, ImageFeatures &features);
00188 
00189     cuda::GpuMat image_;
00190     cuda::GpuMat gray_image_;
00191     cuda::SURF_CUDA surf_;
00192     cuda::GpuMat keypoints_;
00193     cuda::GpuMat descriptors_;
00194     int num_octaves_, num_layers_;
00195     int num_octaves_descr_, num_layers_descr_;
00196 };
00197 #endif
00198 
00199 /** @brief Structure containing information about matches between two images.
00200 
00201 It's assumed that there is a transformation between those images. Transformation may be
00202 homography or affine transformation based on selected matcher.
00203 
00204 @sa detail::FeaturesMatcher
00205 */
00206 struct CV_EXPORTS MatchesInfo
00207 {
00208     MatchesInfo();
00209     MatchesInfo(const MatchesInfo &other);
00210     const MatchesInfo& operator =(const MatchesInfo &other);
00211 
00212     int src_img_idx, dst_img_idx;       //!< Images indices (optional)
00213     std::vector<DMatch> matches;
00214     std::vector<uchar> inliers_mask;    //!< Geometrically consistent matches mask
00215     int num_inliers;                    //!< Number of geometrically consistent matches
00216     Mat H;                              //!< Estimated transformation
00217     double confidence;                  //!< Confidence two images are from the same panorama
00218 };
00219 
00220 /** @brief Feature matchers base class. */
00221 class CV_EXPORTS FeaturesMatcher
00222 {
00223 public:
00224     virtual ~FeaturesMatcher() {}
00225 
00226     /** @overload
00227     @param features1 First image features
00228     @param features2 Second image features
00229     @param matches_info Found matches
00230     */
00231     void operator ()(const ImageFeatures &features1, const ImageFeatures &features2,
00232                      MatchesInfo& matches_info) { match(features1, features2, matches_info); }
00233 
00234     /** @brief Performs images matching.
00235 
00236     @param features Features of the source images
00237     @param pairwise_matches Found pairwise matches
00238     @param mask Mask indicating which image pairs must be matched
00239 
00240     The function is parallelized with the TBB library.
00241 
00242     @sa detail::MatchesInfo
00243     */
00244     void operator ()(const std::vector<ImageFeatures> &features, std::vector<MatchesInfo> &pairwise_matches,
00245                      const cv::UMat  &mask = cv::UMat ());
00246 
00247     /** @return True, if it's possible to use the same matcher instance in parallel, false otherwise
00248     */
00249     bool isThreadSafe () const { return is_thread_safe_; }
00250 
00251     /** @brief Frees unused memory allocated before if there is any.
00252     */
00253     virtual void collectGarbage() {}
00254 
00255 protected:
00256     FeaturesMatcher(bool is_thread_safe = false) : is_thread_safe_(is_thread_safe) {}
00257 
00258     /** @brief This method must implement matching logic in order to make the wrappers
00259     detail::FeaturesMatcher::operator()_ work.
00260 
00261     @param features1 first image features
00262     @param features2 second image features
00263     @param matches_info found matches
00264      */
00265     virtual void match(const ImageFeatures &features1, const ImageFeatures &features2,
00266                        MatchesInfo& matches_info) = 0;
00267 
00268     bool is_thread_safe_;
00269 };
00270 
00271 /** @brief Features matcher which finds two best matches for each feature and leaves the best one only if the
00272 ratio between descriptor distances is greater than the threshold match_conf
00273 
00274 @sa detail::FeaturesMatcher
00275  */
00276 class CV_EXPORTS BestOf2NearestMatcher : public FeaturesMatcher
00277 {
00278 public:
00279     /** @brief Constructs a "best of 2 nearest" matcher.
00280 
00281     @param try_use_gpu Should try to use GPU or not
00282     @param match_conf Match distances ration threshold
00283     @param num_matches_thresh1 Minimum number of matches required for the 2D projective transform
00284     estimation used in the inliers classification step
00285     @param num_matches_thresh2 Minimum number of matches required for the 2D projective transform
00286     re-estimation on inliers
00287      */
00288     BestOf2NearestMatcher(bool try_use_gpu = false, float match_conf = 0.3f, int num_matches_thresh1 = 6,
00289                           int num_matches_thresh2 = 6);
00290 
00291     void collectGarbage();
00292 
00293 protected:
00294     void match(const ImageFeatures &features1, const ImageFeatures &features2, MatchesInfo &matches_info);
00295 
00296     int num_matches_thresh1_;
00297     int num_matches_thresh2_;
00298     Ptr<FeaturesMatcher>  impl_;
00299 };
00300 
00301 class CV_EXPORTS BestOf2NearestRangeMatcher : public BestOf2NearestMatcher
00302 {
00303 public:
00304     BestOf2NearestRangeMatcher(int range_width = 5, bool try_use_gpu = false, float match_conf = 0.3f,
00305                             int num_matches_thresh1 = 6, int num_matches_thresh2 = 6);
00306 
00307     void operator ()(const std::vector<ImageFeatures> &features, std::vector<MatchesInfo> &pairwise_matches,
00308                      const cv::UMat  &mask = cv::UMat ());
00309 
00310 
00311 protected:
00312     int range_width_;
00313 };
00314 
00315 /** @brief Features matcher similar to cv::detail::BestOf2NearestMatcher which
00316 finds two best matches for each feature and leaves the best one only if the
00317 ratio between descriptor distances is greater than the threshold match_conf.
00318 
00319 Unlike cv::detail::BestOf2NearestMatcher this matcher uses affine
00320 transformation (affine trasformation estimate will be placed in matches_info).
00321 
00322 @sa cv::detail::FeaturesMatcher cv::detail::BestOf2NearestMatcher
00323  */
00324 class CV_EXPORTS AffineBestOf2NearestMatcher : public BestOf2NearestMatcher
00325 {
00326 public:
00327     /** @brief Constructs a "best of 2 nearest" matcher that expects affine trasformation
00328     between images
00329 
00330     @param full_affine whether to use full affine transformation with 6 degress of freedom or reduced
00331     transformation with 4 degrees of freedom using only rotation, translation and uniform scaling
00332     @param try_use_gpu Should try to use GPU or not
00333     @param match_conf Match distances ration threshold
00334     @param num_matches_thresh1 Minimum number of matches required for the 2D affine transform
00335     estimation used in the inliers classification step
00336 
00337     @sa cv::estimateAffine2D cv::estimateAffinePartial2D
00338      */
00339     AffineBestOf2NearestMatcher(bool full_affine = false, bool try_use_gpu = false,
00340                                 float match_conf = 0.3f, int num_matches_thresh1 = 6) :
00341         BestOf2NearestMatcher(try_use_gpu, match_conf, num_matches_thresh1, num_matches_thresh1),
00342         full_affine_(full_affine) {}
00343 
00344 protected:
00345     void match(const ImageFeatures &features1, const ImageFeatures &features2, MatchesInfo &matches_info);
00346 
00347     bool full_affine_;
00348 };
00349 
00350 //! @} stitching_match
00351 
00352 } // namespace detail
00353 } // namespace cv
00354 
00355 #endif // OPENCV_STITCHING_MATCHERS_HPP