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 Frees unused memory allocated before if there is any. */
00087     virtual void collectGarbage() {}
00088 
00089 protected:
00090     /** @brief This method must implement features finding logic in order to make the wrappers
00091     detail::FeaturesFinder::operator()_ work.
00092 
00093     @param image Source image
00094     @param features Found features
00095 
00096     @sa detail::ImageFeatures */
00097     virtual void find(InputArray image, ImageFeatures &features) = 0;
00098 };
00099 
00100 /** @brief SURF features finder.
00101 
00102 @sa detail::FeaturesFinder, SURF
00103 */
00104 class CV_EXPORTS SurfFeaturesFinder : public FeaturesFinder
00105 {
00106 public:
00107     SurfFeaturesFinder(double hess_thresh = 300., int num_octaves = 3, int num_layers = 4,
00108                        int num_octaves_descr = /*4*/3, int num_layers_descr = /*2*/4);
00109 
00110 private:
00111     void find(InputArray image, ImageFeatures &features);
00112 
00113     Ptr<FeatureDetector>  detector_;
00114     Ptr<DescriptorExtractor>  extractor_;
00115     Ptr<Feature2D>  surf;
00116 };
00117 
00118 /** @brief ORB features finder. :
00119 
00120 @sa detail::FeaturesFinder, ORB
00121 */
00122 class CV_EXPORTS OrbFeaturesFinder : public FeaturesFinder
00123 {
00124 public:
00125     OrbFeaturesFinder(Size _grid_size = Size(3,1), int nfeatures=1500, float scaleFactor=1.3f, int nlevels=5);
00126 
00127 private:
00128     void find(InputArray image, ImageFeatures &features);
00129 
00130     Ptr<ORB>  orb;
00131     Size grid_size;
00132 };
00133 
00134 
00135 #ifdef HAVE_OPENCV_XFEATURES2D
00136 class CV_EXPORTS SurfFeaturesFinderGpu : public FeaturesFinder
00137 {
00138 public:
00139     SurfFeaturesFinderGpu(double hess_thresh = 300., int num_octaves = 3, int num_layers = 4,
00140                           int num_octaves_descr = 4, int num_layers_descr = 2);
00141 
00142     void collectGarbage();
00143 
00144 private:
00145     void find(InputArray image, ImageFeatures &features);
00146 
00147     cuda::GpuMat image_;
00148     cuda::GpuMat gray_image_;
00149     cuda::SURF_CUDA surf_;
00150     cuda::GpuMat keypoints_;
00151     cuda::GpuMat descriptors_;
00152     int num_octaves_, num_layers_;
00153     int num_octaves_descr_, num_layers_descr_;
00154 };
00155 #endif
00156 
00157 /** @brief Structure containing information about matches between two images.
00158 
00159 It's assumed that there is a homography between those images.
00160 */
00161 struct CV_EXPORTS MatchesInfo
00162 {
00163     MatchesInfo();
00164     MatchesInfo(const MatchesInfo &other);
00165     const MatchesInfo& operator =(const MatchesInfo &other);
00166 
00167     int src_img_idx, dst_img_idx;       //!< Images indices (optional)
00168     std::vector<DMatch> matches;
00169     std::vector<uchar> inliers_mask;    //!< Geometrically consistent matches mask
00170     int num_inliers;                    //!< Number of geometrically consistent matches
00171     Mat H;                              //!< Estimated homography
00172     double confidence;                  //!< Confidence two images are from the same panorama
00173 };
00174 
00175 /** @brief Feature matchers base class. */
00176 class CV_EXPORTS FeaturesMatcher
00177 {
00178 public:
00179     virtual ~FeaturesMatcher() {}
00180 
00181     /** @overload
00182     @param features1 First image features
00183     @param features2 Second image features
00184     @param matches_info Found matches
00185     */
00186     void operator ()(const ImageFeatures &features1, const ImageFeatures &features2,
00187                      MatchesInfo& matches_info) { match(features1, features2, matches_info); }
00188 
00189     /** @brief Performs images matching.
00190 
00191     @param features Features of the source images
00192     @param pairwise_matches Found pairwise matches
00193     @param mask Mask indicating which image pairs must be matched
00194 
00195     The function is parallelized with the TBB library.
00196 
00197     @sa detail::MatchesInfo
00198     */
00199     void operator ()(const std::vector<ImageFeatures> &features, std::vector<MatchesInfo> &pairwise_matches,
00200                      const cv::UMat  &mask = cv::UMat ());
00201 
00202     /** @return True, if it's possible to use the same matcher instance in parallel, false otherwise
00203     */
00204     bool isThreadSafe () const { return is_thread_safe_; }
00205 
00206     /** @brief Frees unused memory allocated before if there is any.
00207     */
00208     virtual void collectGarbage() {}
00209 
00210 protected:
00211     FeaturesMatcher(bool is_thread_safe = false) : is_thread_safe_(is_thread_safe) {}
00212 
00213     /** @brief This method must implement matching logic in order to make the wrappers
00214     detail::FeaturesMatcher::operator()_ work.
00215 
00216     @param features1 first image features
00217     @param features2 second image features
00218     @param matches_info found matches
00219      */
00220     virtual void match(const ImageFeatures &features1, const ImageFeatures &features2,
00221                        MatchesInfo& matches_info) = 0;
00222 
00223     bool is_thread_safe_;
00224 };
00225 
00226 /** @brief Features matcher which finds two best matches for each feature and leaves the best one only if the
00227 ratio between descriptor distances is greater than the threshold match_conf
00228 
00229 @sa detail::FeaturesMatcher
00230  */
00231 class CV_EXPORTS BestOf2NearestMatcher : public FeaturesMatcher
00232 {
00233 public:
00234     /** @brief Constructs a "best of 2 nearest" matcher.
00235 
00236     @param try_use_gpu Should try to use GPU or not
00237     @param match_conf Match distances ration threshold
00238     @param num_matches_thresh1 Minimum number of matches required for the 2D projective transform
00239     estimation used in the inliers classification step
00240     @param num_matches_thresh2 Minimum number of matches required for the 2D projective transform
00241     re-estimation on inliers
00242      */
00243     BestOf2NearestMatcher(bool try_use_gpu = false, float match_conf = 0.3f, int num_matches_thresh1 = 6,
00244                           int num_matches_thresh2 = 6);
00245 
00246     void collectGarbage();
00247 
00248 protected:
00249     void match(const ImageFeatures &features1, const ImageFeatures &features2, MatchesInfo &matches_info);
00250 
00251     int num_matches_thresh1_;
00252     int num_matches_thresh2_;
00253     Ptr<FeaturesMatcher>  impl_;
00254 };
00255 
00256 class CV_EXPORTS BestOf2NearestRangeMatcher : public BestOf2NearestMatcher
00257 {
00258 public:
00259     BestOf2NearestRangeMatcher(int range_width = 5, bool try_use_gpu = false, float match_conf = 0.3f,
00260                             int num_matches_thresh1 = 6, int num_matches_thresh2 = 6);
00261 
00262     void operator ()(const std::vector<ImageFeatures> &features, std::vector<MatchesInfo> &pairwise_matches,
00263                      const cv::UMat  &mask = cv::UMat ());
00264 
00265 
00266 protected:
00267     int range_width_;
00268 };
00269 
00270 //! @} stitching_match
00271 
00272 } // namespace detail
00273 } // namespace cv
00274 
00275 #endif // __OPENCV_STITCHING_MATCHERS_HPP__
00276