1 /*M/////////////////////////////////////////////////////////////////////////////////////// 2 // 3 // IMPORTANT: READ BEFORE DOWNLOADING, COPYING, INSTALLING OR USING. 4 // 5 // By downloading, copying, installing or using the software you agree to this license. 6 // If you do not agree to this license, do not download, install, 7 // copy or use the software. 8 // 9 // 10 // License Agreement 11 // For Open Source Computer Vision Library 12 // 13 // Copyright (C) 2000-2008, Intel Corporation, all rights reserved. 14 // Copyright (C) 2009, Willow Garage Inc., all rights reserved. 15 // Third party copyrights are property of their respective owners. 16 // 17 // Redistribution and use in source and binary forms, with or without modification, 18 // are permitted provided that the following conditions are met: 19 // 20 // * Redistribution's of source code must retain the above copyright notice, 21 // this list of conditions and the following disclaimer. 22 // 23 // * Redistribution's in binary form must reproduce the above copyright notice, 24 // this list of conditions and the following disclaimer in the documentation 25 // and/or other materials provided with the distribution. 26 // 27 // * The name of the copyright holders may not be used to endorse or promote products 28 // derived from this software without specific prior written permission. 29 // 30 // This software is provided by the copyright holders and contributors "as is" and 31 // any express or implied warranties, including, but not limited to, the implied 32 // warranties of merchantability and fitness for a particular purpose are disclaimed. 33 // In no event shall the Intel Corporation or contributors be liable for any direct, 34 // indirect, incidental, special, exemplary, or consequential damages 35 // (including, but not limited to, procurement of substitute goods or services; 36 // loss of use, data, or profits; or business interruption) however caused 37 // and on any theory of liability, whether in contract, strict liability, 38 // or tort (including negligence or otherwise) arising in any way out of 39 // the use of this software, even if advised of the possibility of such damage. 40 // 41 //M*/ 42 43 #ifndef __OPENCV_STITCHING_MATCHERS_HPP__ 44 #define __OPENCV_STITCHING_MATCHERS_HPP__ 45 46 #include "opencv2/core.hpp" 47 #include "opencv2/features2d.hpp" 48 49 #include "opencv2/opencv_modules.hpp" 50 51 #ifdef HAVE_OPENCV_XFEATURES2D 52 # include "opencv2/xfeatures2d/cuda.hpp" 53 #endif 54 55 namespace cv { 56 namespace detail { 57 58 //! @addtogroup stitching_match 59 //! @{ 60 61 /** @brief Structure containing image keypoints and descriptors. */ 62 struct CV_EXPORTS ImageFeatures 63 { 64 int img_idx; 65 Size img_size; 66 std::vector<KeyPoint> keypoints; 67 UMat descriptors; 68 }; 69 70 /** @brief Feature finders base class */ 71 class CV_EXPORTS FeaturesFinder 72 { 73 public: 74 virtual ~FeaturesFinder() {} 75 /** @overload */ 76 void operator ()(InputArray image, ImageFeatures &features); 77 /** @brief Finds features in the given image. 78 79 @param image Source image 80 @param features Found features 81 @param rois Regions of interest 82 83 @sa detail::ImageFeatures, Rect_ 84 */ 85 void operator ()(InputArray image, ImageFeatures &features, const std::vector<cv::Rect> &rois); 86 /** @brief Frees unused memory allocated before if there is any. */ 87 virtual void collectGarbage() {} 88 89 protected: 90 /** @brief This method must implement features finding logic in order to make the wrappers 91 detail::FeaturesFinder::operator()_ work. 92 93 @param image Source image 94 @param features Found features 95 96 @sa detail::ImageFeatures */ 97 virtual void find(InputArray image, ImageFeatures &features) = 0; 98 }; 99 100 /** @brief SURF features finder. 101 102 @sa detail::FeaturesFinder, SURF 103 */ 104 class CV_EXPORTS SurfFeaturesFinder : public FeaturesFinder 105 { 106 public: 107 SurfFeaturesFinder(double hess_thresh = 300., int num_octaves = 3, int num_layers = 4, 108 int num_octaves_descr = /*4*/3, int num_layers_descr = /*2*/4); 109 110 private: 111 void find(InputArray image, ImageFeatures &features); 112 113 Ptr<FeatureDetector> detector_; 114 Ptr<DescriptorExtractor> extractor_; 115 Ptr<Feature2D> surf; 116 }; 117 118 /** @brief ORB features finder. : 119 120 @sa detail::FeaturesFinder, ORB 121 */ 122 class CV_EXPORTS OrbFeaturesFinder : public FeaturesFinder 123 { 124 public: 125 OrbFeaturesFinder(Size _grid_size = Size(3,1), int nfeatures=1500, float scaleFactor=1.3f, int nlevels=5); 126 127 private: 128 void find(InputArray image, ImageFeatures &features); 129 130 Ptr<ORB> orb; 131 Size grid_size; 132 }; 133 134 135 #ifdef HAVE_OPENCV_XFEATURES2D 136 class CV_EXPORTS SurfFeaturesFinderGpu : public FeaturesFinder 137 { 138 public: 139 SurfFeaturesFinderGpu(double hess_thresh = 300., int num_octaves = 3, int num_layers = 4, 140 int num_octaves_descr = 4, int num_layers_descr = 2); 141 142 void collectGarbage(); 143 144 private: 145 void find(InputArray image, ImageFeatures &features); 146 147 cuda::GpuMat image_; 148 cuda::GpuMat gray_image_; 149 cuda::SURF_CUDA surf_; 150 cuda::GpuMat keypoints_; 151 cuda::GpuMat descriptors_; 152 int num_octaves_, num_layers_; 153 int num_octaves_descr_, num_layers_descr_; 154 }; 155 #endif 156 157 /** @brief Structure containing information about matches between two images. 158 159 It's assumed that there is a homography between those images. 160 */ 161 struct CV_EXPORTS MatchesInfo 162 { 163 MatchesInfo(); 164 MatchesInfo(const MatchesInfo &other); 165 const MatchesInfo& operator =(const MatchesInfo &other); 166 167 int src_img_idx, dst_img_idx; //!< Images indices (optional) 168 std::vector<DMatch> matches; 169 std::vector<uchar> inliers_mask; //!< Geometrically consistent matches mask 170 int num_inliers; //!< Number of geometrically consistent matches 171 Mat H; //!< Estimated homography 172 double confidence; //!< Confidence two images are from the same panorama 173 }; 174 175 /** @brief Feature matchers base class. */ 176 class CV_EXPORTS FeaturesMatcher 177 { 178 public: 179 virtual ~FeaturesMatcher() {} 180 181 /** @overload 182 @param features1 First image features 183 @param features2 Second image features 184 @param matches_info Found matches 185 */ 186 void operator ()(const ImageFeatures &features1, const ImageFeatures &features2, 187 MatchesInfo& matches_info) { match(features1, features2, matches_info); } 188 189 /** @brief Performs images matching. 190 191 @param features Features of the source images 192 @param pairwise_matches Found pairwise matches 193 @param mask Mask indicating which image pairs must be matched 194 195 The function is parallelized with the TBB library. 196 197 @sa detail::MatchesInfo 198 */ 199 void operator ()(const std::vector<ImageFeatures> &features, std::vector<MatchesInfo> &pairwise_matches, 200 const cv::UMat &mask = cv::UMat()); 201 202 /** @return True, if it's possible to use the same matcher instance in parallel, false otherwise 203 */ 204 bool isThreadSafe() const { return is_thread_safe_; } 205 206 /** @brief Frees unused memory allocated before if there is any. 207 */ 208 virtual void collectGarbage() {} 209 210 protected: 211 FeaturesMatcher(bool is_thread_safe = false) : is_thread_safe_(is_thread_safe) {} 212 213 /** @brief This method must implement matching logic in order to make the wrappers 214 detail::FeaturesMatcher::operator()_ work. 215 216 @param features1 first image features 217 @param features2 second image features 218 @param matches_info found matches 219 */ 220 virtual void match(const ImageFeatures &features1, const ImageFeatures &features2, 221 MatchesInfo& matches_info) = 0; 222 223 bool is_thread_safe_; 224 }; 225 226 /** @brief Features matcher which finds two best matches for each feature and leaves the best one only if the 227 ratio between descriptor distances is greater than the threshold match_conf 228 229 @sa detail::FeaturesMatcher 230 */ 231 class CV_EXPORTS BestOf2NearestMatcher : public FeaturesMatcher 232 { 233 public: 234 /** @brief Constructs a "best of 2 nearest" matcher. 235 236 @param try_use_gpu Should try to use GPU or not 237 @param match_conf Match distances ration threshold 238 @param num_matches_thresh1 Minimum number of matches required for the 2D projective transform 239 estimation used in the inliers classification step 240 @param num_matches_thresh2 Minimum number of matches required for the 2D projective transform 241 re-estimation on inliers 242 */ 243 BestOf2NearestMatcher(bool try_use_gpu = false, float match_conf = 0.3f, int num_matches_thresh1 = 6, 244 int num_matches_thresh2 = 6); 245 246 void collectGarbage(); 247 248 protected: 249 void match(const ImageFeatures &features1, const ImageFeatures &features2, MatchesInfo &matches_info); 250 251 int num_matches_thresh1_; 252 int num_matches_thresh2_; 253 Ptr<FeaturesMatcher> impl_; 254 }; 255 256 class CV_EXPORTS BestOf2NearestRangeMatcher : public BestOf2NearestMatcher 257 { 258 public: 259 BestOf2NearestRangeMatcher(int range_width = 5, bool try_use_gpu = false, float match_conf = 0.3f, 260 int num_matches_thresh1 = 6, int num_matches_thresh2 = 6); 261 262 void operator ()(const std::vector<ImageFeatures> &features, std::vector<MatchesInfo> &pairwise_matches, 263 const cv::UMat &mask = cv::UMat()); 264 265 266 protected: 267 int range_width_; 268 }; 269 270 //! @} stitching_match 271 272 } // namespace detail 273 } // namespace cv 274 275 #endif // __OPENCV_STITCHING_MATCHERS_HPP__ 276
