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: ~FeaturesFinder()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 Finds features in the given images in parallel. 87 88 @param images Source images 89 @param features Found features for each image 90 @param rois Regions of interest for each image 91 92 @sa detail::ImageFeatures, Rect_ 93 */ 94 void operator ()(InputArrayOfArrays images, std::vector<ImageFeatures> &features, 95 const std::vector<std::vector<cv::Rect> > &rois); 96 /** @overload */ 97 void operator ()(InputArrayOfArrays images, std::vector<ImageFeatures> &features); 98 /** @brief Frees unused memory allocated before if there is any. */ collectGarbage()99 virtual void collectGarbage() {} 100 101 /* TODO OpenCV ABI 4.x 102 reimplement this as public method similar to FeaturesMatcher and remove private function hack 103 @return True, if it's possible to use the same finder instance in parallel, false otherwise 104 bool isThreadSafe() const { return is_thread_safe_; } 105 */ 106 107 protected: 108 /** @brief This method must implement features finding logic in order to make the wrappers 109 detail::FeaturesFinder::operator()_ work. 110 111 @param image Source image 112 @param features Found features 113 114 @sa detail::ImageFeatures */ 115 virtual void find(InputArray image, ImageFeatures &features) = 0; 116 /** @brief uses dynamic_cast to determine thread-safety 117 @return True, if it's possible to use the same finder instance in parallel, false otherwise 118 */ 119 bool isThreadSafe() const; 120 }; 121 122 /** @brief SURF features finder. 123 124 @sa detail::FeaturesFinder, SURF 125 */ 126 class CV_EXPORTS SurfFeaturesFinder : public FeaturesFinder 127 { 128 public: 129 SurfFeaturesFinder(double hess_thresh = 300., int num_octaves = 3, int num_layers = 4, 130 int num_octaves_descr = /*4*/3, int num_layers_descr = /*2*/4); 131 132 private: 133 void find(InputArray image, ImageFeatures &features) CV_OVERRIDE; 134 135 Ptr<FeatureDetector> detector_; 136 Ptr<DescriptorExtractor> extractor_; 137 Ptr<Feature2D> surf; 138 }; 139 140 /** @brief ORB features finder. : 141 142 @sa detail::FeaturesFinder, ORB 143 */ 144 class CV_EXPORTS OrbFeaturesFinder : public FeaturesFinder 145 { 146 public: 147 OrbFeaturesFinder(Size _grid_size = Size(3,1), int nfeatures=1500, float scaleFactor=1.3f, int nlevels=5); 148 149 private: 150 void find(InputArray image, ImageFeatures &features) CV_OVERRIDE; 151 152 Ptr<ORB> orb; 153 Size grid_size; 154 }; 155 156 /** @brief AKAZE features finder. : 157 158 @sa detail::FeaturesFinder, AKAZE 159 */ 160 class CV_EXPORTS AKAZEFeaturesFinder : public detail::FeaturesFinder 161 { 162 public: 163 AKAZEFeaturesFinder(int descriptor_type = AKAZE::DESCRIPTOR_MLDB, 164 int descriptor_size = 0, 165 int descriptor_channels = 3, 166 float threshold = 0.001f, 167 int nOctaves = 4, 168 int nOctaveLayers = 4, 169 int diffusivity = KAZE::DIFF_PM_G2); 170 171 private: 172 void find(InputArray image, ImageFeatures &features) CV_OVERRIDE; 173 174 Ptr<AKAZE> akaze; 175 }; 176 177 #ifdef HAVE_OPENCV_XFEATURES2D 178 class CV_EXPORTS SurfFeaturesFinderGpu : public FeaturesFinder 179 { 180 public: 181 SurfFeaturesFinderGpu(double hess_thresh = 300., int num_octaves = 3, int num_layers = 4, 182 int num_octaves_descr = 4, int num_layers_descr = 2); 183 184 void collectGarbage() CV_OVERRIDE; 185 186 private: 187 void find(InputArray image, ImageFeatures &features) CV_OVERRIDE; 188 189 cuda::GpuMat image_; 190 cuda::GpuMat gray_image_; 191 cuda::SURF_CUDA surf_; 192 cuda::GpuMat keypoints_; 193 cuda::GpuMat descriptors_; 194 int num_octaves_, num_layers_; 195 int num_octaves_descr_, num_layers_descr_; 196 }; 197 #endif 198 199 /** @brief Structure containing information about matches between two images. 200 201 It's assumed that there is a transformation between those images. Transformation may be 202 homography or affine transformation based on selected matcher. 203 204 @sa detail::FeaturesMatcher 205 */ 206 struct CV_EXPORTS MatchesInfo 207 { 208 MatchesInfo(); 209 MatchesInfo(const MatchesInfo &other); 210 MatchesInfo& operator =(const MatchesInfo &other); 211 212 int src_img_idx, dst_img_idx; //!< Images indices (optional) 213 std::vector<DMatch> matches; 214 std::vector<uchar> inliers_mask; //!< Geometrically consistent matches mask 215 int num_inliers; //!< Number of geometrically consistent matches 216 Mat H; //!< Estimated transformation 217 double confidence; //!< Confidence two images are from the same panorama 218 }; 219 220 /** @brief Feature matchers base class. */ 221 class CV_EXPORTS FeaturesMatcher 222 { 223 public: ~FeaturesMatcher()224 virtual ~FeaturesMatcher() {} 225 226 /** @overload 227 @param features1 First image features 228 @param features2 Second image features 229 @param matches_info Found matches 230 */ operator ()(const ImageFeatures & features1,const ImageFeatures & features2,MatchesInfo & matches_info)231 void operator ()(const ImageFeatures &features1, const ImageFeatures &features2, 232 MatchesInfo& matches_info) { match(features1, features2, matches_info); } 233 234 /** @brief Performs images matching. 235 236 @param features Features of the source images 237 @param pairwise_matches Found pairwise matches 238 @param mask Mask indicating which image pairs must be matched 239 240 The function is parallelized with the TBB library. 241 242 @sa detail::MatchesInfo 243 */ 244 void operator ()(const std::vector<ImageFeatures> &features, std::vector<MatchesInfo> &pairwise_matches, 245 const cv::UMat &mask = cv::UMat()); 246 247 /** @return True, if it's possible to use the same matcher instance in parallel, false otherwise 248 */ isThreadSafe() const249 bool isThreadSafe() const { return is_thread_safe_; } 250 251 /** @brief Frees unused memory allocated before if there is any. 252 */ collectGarbage()253 virtual void collectGarbage() {} 254 255 protected: FeaturesMatcher(bool is_thread_safe=false)256 FeaturesMatcher(bool is_thread_safe = false) : is_thread_safe_(is_thread_safe) {} 257 258 /** @brief This method must implement matching logic in order to make the wrappers 259 detail::FeaturesMatcher::operator()_ work. 260 261 @param features1 first image features 262 @param features2 second image features 263 @param matches_info found matches 264 */ 265 virtual void match(const ImageFeatures &features1, const ImageFeatures &features2, 266 MatchesInfo& matches_info) = 0; 267 268 bool is_thread_safe_; 269 }; 270 271 /** @brief Features matcher which finds two best matches for each feature and leaves the best one only if the 272 ratio between descriptor distances is greater than the threshold match_conf 273 274 @sa detail::FeaturesMatcher 275 */ 276 class CV_EXPORTS BestOf2NearestMatcher : public FeaturesMatcher 277 { 278 public: 279 /** @brief Constructs a "best of 2 nearest" matcher. 280 281 @param try_use_gpu Should try to use GPU or not 282 @param match_conf Match distances ration threshold 283 @param num_matches_thresh1 Minimum number of matches required for the 2D projective transform 284 estimation used in the inliers classification step 285 @param num_matches_thresh2 Minimum number of matches required for the 2D projective transform 286 re-estimation on inliers 287 */ 288 BestOf2NearestMatcher(bool try_use_gpu = false, float match_conf = 0.3f, int num_matches_thresh1 = 6, 289 int num_matches_thresh2 = 6); 290 291 void collectGarbage() CV_OVERRIDE; 292 293 protected: 294 void match(const ImageFeatures &features1, const ImageFeatures &features2, MatchesInfo &matches_info) CV_OVERRIDE; 295 296 int num_matches_thresh1_; 297 int num_matches_thresh2_; 298 Ptr<FeaturesMatcher> impl_; 299 }; 300 301 class CV_EXPORTS BestOf2NearestRangeMatcher : public BestOf2NearestMatcher 302 { 303 public: 304 BestOf2NearestRangeMatcher(int range_width = 5, bool try_use_gpu = false, float match_conf = 0.3f, 305 int num_matches_thresh1 = 6, int num_matches_thresh2 = 6); 306 307 void operator ()(const std::vector<ImageFeatures> &features, std::vector<MatchesInfo> &pairwise_matches, 308 const cv::UMat &mask = cv::UMat()); 309 310 311 protected: 312 int range_width_; 313 }; 314 315 /** @brief Features matcher similar to cv::detail::BestOf2NearestMatcher which 316 finds two best matches for each feature and leaves the best one only if the 317 ratio between descriptor distances is greater than the threshold match_conf. 318 319 Unlike cv::detail::BestOf2NearestMatcher this matcher uses affine 320 transformation (affine trasformation estimate will be placed in matches_info). 321 322 @sa cv::detail::FeaturesMatcher cv::detail::BestOf2NearestMatcher 323 */ 324 class CV_EXPORTS AffineBestOf2NearestMatcher : public BestOf2NearestMatcher 325 { 326 public: 327 /** @brief Constructs a "best of 2 nearest" matcher that expects affine trasformation 328 between images 329 330 @param full_affine whether to use full affine transformation with 6 degress of freedom or reduced 331 transformation with 4 degrees of freedom using only rotation, translation and uniform scaling 332 @param try_use_gpu Should try to use GPU or not 333 @param match_conf Match distances ration threshold 334 @param num_matches_thresh1 Minimum number of matches required for the 2D affine transform 335 estimation used in the inliers classification step 336 337 @sa cv::estimateAffine2D cv::estimateAffinePartial2D 338 */ AffineBestOf2NearestMatcher(bool full_affine=false,bool try_use_gpu=false,float match_conf=0.3f,int num_matches_thresh1=6)339 AffineBestOf2NearestMatcher(bool full_affine = false, bool try_use_gpu = false, 340 float match_conf = 0.3f, int num_matches_thresh1 = 6) : 341 BestOf2NearestMatcher(try_use_gpu, match_conf, num_matches_thresh1, num_matches_thresh1), 342 full_affine_(full_affine) {} 343 344 protected: 345 void match(const ImageFeatures &features1, const ImageFeatures &features2, MatchesInfo &matches_info) CV_OVERRIDE; 346 347 bool full_affine_; 348 }; 349 350 //! @} stitching_match 351 352 } // namespace detail 353 } // namespace cv 354 355 #endif // OPENCV_STITCHING_MATCHERS_HPP 356