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_CUDAFEATURES2D_HPP__ 44 #define __OPENCV_CUDAFEATURES2D_HPP__ 45 46 #ifndef __cplusplus 47 # error cudafeatures2d.hpp header must be compiled as C++ 48 #endif 49 50 #include "opencv2/core/cuda.hpp" 51 #include "opencv2/features2d.hpp" 52 #include "opencv2/cudafilters.hpp" 53 54 /** 55 @addtogroup cuda 56 @{ 57 @defgroup cudafeatures2d Feature Detection and Description 58 @} 59 */ 60 61 namespace cv { namespace cuda { 62 63 //! @addtogroup cudafeatures2d 64 //! @{ 65 66 // 67 // DescriptorMatcher 68 // 69 70 /** @brief Abstract base class for matching keypoint descriptors. 71 72 It has two groups of match methods: for matching descriptors of an image with another image or with 73 an image set. 74 */ 75 class CV_EXPORTS DescriptorMatcher : public cv::Algorithm 76 { 77 public: 78 // 79 // Factories 80 // 81 82 /** @brief Brute-force descriptor matcher. 83 84 For each descriptor in the first set, this matcher finds the closest descriptor in the second set 85 by trying each one. This descriptor matcher supports masking permissible matches of descriptor 86 sets. 87 88 @param normType One of NORM_L1, NORM_L2, NORM_HAMMING. L1 and L2 norms are 89 preferable choices for SIFT and SURF descriptors, NORM_HAMMING should be used with ORB, BRISK and 90 BRIEF). 91 */ 92 static Ptr<DescriptorMatcher> createBFMatcher(int normType = cv::NORM_L2); 93 94 // 95 // Utility 96 // 97 98 /** @brief Returns true if the descriptor matcher supports masking permissible matches. 99 */ 100 virtual bool isMaskSupported() const = 0; 101 102 // 103 // Descriptor collection 104 // 105 106 /** @brief Adds descriptors to train a descriptor collection. 107 108 If the collection is not empty, the new descriptors are added to existing train descriptors. 109 110 @param descriptors Descriptors to add. Each descriptors[i] is a set of descriptors from the same 111 train image. 112 */ 113 virtual void add(const std::vector<GpuMat>& descriptors) = 0; 114 115 /** @brief Returns a constant link to the train descriptor collection. 116 */ 117 virtual const std::vector<GpuMat>& getTrainDescriptors() const = 0; 118 119 /** @brief Clears the train descriptor collection. 120 */ 121 virtual void clear() = 0; 122 123 /** @brief Returns true if there are no train descriptors in the collection. 124 */ 125 virtual bool empty() const = 0; 126 127 /** @brief Trains a descriptor matcher. 128 129 Trains a descriptor matcher (for example, the flann index). In all methods to match, the method 130 train() is run every time before matching. 131 */ 132 virtual void train() = 0; 133 134 // 135 // 1 to 1 match 136 // 137 138 /** @brief Finds the best match for each descriptor from a query set (blocking version). 139 140 @param queryDescriptors Query set of descriptors. 141 @param trainDescriptors Train set of descriptors. This set is not added to the train descriptors 142 collection stored in the class object. 143 @param matches Matches. If a query descriptor is masked out in mask , no match is added for this 144 descriptor. So, matches size may be smaller than the query descriptors count. 145 @param mask Mask specifying permissible matches between an input query and train matrices of 146 descriptors. 147 148 In the first variant of this method, the train descriptors are passed as an input argument. In the 149 second variant of the method, train descriptors collection that was set by DescriptorMatcher::add is 150 used. Optional mask (or masks) can be passed to specify which query and training descriptors can be 151 matched. Namely, queryDescriptors[i] can be matched with trainDescriptors[j] only if 152 mask.at\<uchar\>(i,j) is non-zero. 153 */ 154 virtual void match(InputArray queryDescriptors, InputArray trainDescriptors, 155 std::vector<DMatch>& matches, 156 InputArray mask = noArray()) = 0; 157 158 /** @overload 159 */ 160 virtual void match(InputArray queryDescriptors, 161 std::vector<DMatch>& matches, 162 const std::vector<GpuMat>& masks = std::vector<GpuMat>()) = 0; 163 164 /** @brief Finds the best match for each descriptor from a query set (asynchronous version). 165 166 @param queryDescriptors Query set of descriptors. 167 @param trainDescriptors Train set of descriptors. This set is not added to the train descriptors 168 collection stored in the class object. 169 @param matches Matches array stored in GPU memory. Internal representation is not defined. 170 Use DescriptorMatcher::matchConvert method to retrieve results in standard representation. 171 @param mask Mask specifying permissible matches between an input query and train matrices of 172 descriptors. 173 @param stream CUDA stream. 174 175 In the first variant of this method, the train descriptors are passed as an input argument. In the 176 second variant of the method, train descriptors collection that was set by DescriptorMatcher::add is 177 used. Optional mask (or masks) can be passed to specify which query and training descriptors can be 178 matched. Namely, queryDescriptors[i] can be matched with trainDescriptors[j] only if 179 mask.at\<uchar\>(i,j) is non-zero. 180 */ 181 virtual void matchAsync(InputArray queryDescriptors, InputArray trainDescriptors, 182 OutputArray matches, 183 InputArray mask = noArray(), 184 Stream& stream = Stream::Null()) = 0; 185 186 /** @overload 187 */ 188 virtual void matchAsync(InputArray queryDescriptors, 189 OutputArray matches, 190 const std::vector<GpuMat>& masks = std::vector<GpuMat>(), 191 Stream& stream = Stream::Null()) = 0; 192 193 /** @brief Converts matches array from internal representation to standard matches vector. 194 195 The method is supposed to be used with DescriptorMatcher::matchAsync to get final result. 196 Call this method only after DescriptorMatcher::matchAsync is completed (ie. after synchronization). 197 198 @param gpu_matches Matches, returned from DescriptorMatcher::matchAsync. 199 @param matches Vector of DMatch objects. 200 */ 201 virtual void matchConvert(InputArray gpu_matches, 202 std::vector<DMatch>& matches) = 0; 203 204 // 205 // knn match 206 // 207 208 /** @brief Finds the k best matches for each descriptor from a query set (blocking version). 209 210 @param queryDescriptors Query set of descriptors. 211 @param trainDescriptors Train set of descriptors. This set is not added to the train descriptors 212 collection stored in the class object. 213 @param matches Matches. Each matches[i] is k or less matches for the same query descriptor. 214 @param k Count of best matches found per each query descriptor or less if a query descriptor has 215 less than k possible matches in total. 216 @param mask Mask specifying permissible matches between an input query and train matrices of 217 descriptors. 218 @param compactResult Parameter used when the mask (or masks) is not empty. If compactResult is 219 false, the matches vector has the same size as queryDescriptors rows. If compactResult is true, 220 the matches vector does not contain matches for fully masked-out query descriptors. 221 222 These extended variants of DescriptorMatcher::match methods find several best matches for each query 223 descriptor. The matches are returned in the distance increasing order. See DescriptorMatcher::match 224 for the details about query and train descriptors. 225 */ 226 virtual void knnMatch(InputArray queryDescriptors, InputArray trainDescriptors, 227 std::vector<std::vector<DMatch> >& matches, 228 int k, 229 InputArray mask = noArray(), 230 bool compactResult = false) = 0; 231 232 /** @overload 233 */ 234 virtual void knnMatch(InputArray queryDescriptors, 235 std::vector<std::vector<DMatch> >& matches, 236 int k, 237 const std::vector<GpuMat>& masks = std::vector<GpuMat>(), 238 bool compactResult = false) = 0; 239 240 /** @brief Finds the k best matches for each descriptor from a query set (asynchronous version). 241 242 @param queryDescriptors Query set of descriptors. 243 @param trainDescriptors Train set of descriptors. This set is not added to the train descriptors 244 collection stored in the class object. 245 @param matches Matches array stored in GPU memory. Internal representation is not defined. 246 Use DescriptorMatcher::knnMatchConvert method to retrieve results in standard representation. 247 @param k Count of best matches found per each query descriptor or less if a query descriptor has 248 less than k possible matches in total. 249 @param mask Mask specifying permissible matches between an input query and train matrices of 250 descriptors. 251 @param stream CUDA stream. 252 253 These extended variants of DescriptorMatcher::matchAsync methods find several best matches for each query 254 descriptor. The matches are returned in the distance increasing order. See DescriptorMatcher::matchAsync 255 for the details about query and train descriptors. 256 */ 257 virtual void knnMatchAsync(InputArray queryDescriptors, InputArray trainDescriptors, 258 OutputArray matches, 259 int k, 260 InputArray mask = noArray(), 261 Stream& stream = Stream::Null()) = 0; 262 263 /** @overload 264 */ 265 virtual void knnMatchAsync(InputArray queryDescriptors, 266 OutputArray matches, 267 int k, 268 const std::vector<GpuMat>& masks = std::vector<GpuMat>(), 269 Stream& stream = Stream::Null()) = 0; 270 271 /** @brief Converts matches array from internal representation to standard matches vector. 272 273 The method is supposed to be used with DescriptorMatcher::knnMatchAsync to get final result. 274 Call this method only after DescriptorMatcher::knnMatchAsync is completed (ie. after synchronization). 275 276 @param gpu_matches Matches, returned from DescriptorMatcher::knnMatchAsync. 277 @param matches Vector of DMatch objects. 278 @param compactResult Parameter used when the mask (or masks) is not empty. If compactResult is 279 false, the matches vector has the same size as queryDescriptors rows. If compactResult is true, 280 the matches vector does not contain matches for fully masked-out query descriptors. 281 */ 282 virtual void knnMatchConvert(InputArray gpu_matches, 283 std::vector< std::vector<DMatch> >& matches, 284 bool compactResult = false) = 0; 285 286 // 287 // radius match 288 // 289 290 /** @brief For each query descriptor, finds the training descriptors not farther than the specified distance (blocking version). 291 292 @param queryDescriptors Query set of descriptors. 293 @param trainDescriptors Train set of descriptors. This set is not added to the train descriptors 294 collection stored in the class object. 295 @param matches Found matches. 296 @param maxDistance Threshold for the distance between matched descriptors. Distance means here 297 metric distance (e.g. Hamming distance), not the distance between coordinates (which is measured 298 in Pixels)! 299 @param mask Mask specifying permissible matches between an input query and train matrices of 300 descriptors. 301 @param compactResult Parameter used when the mask (or masks) is not empty. If compactResult is 302 false, the matches vector has the same size as queryDescriptors rows. If compactResult is true, 303 the matches vector does not contain matches for fully masked-out query descriptors. 304 305 For each query descriptor, the methods find such training descriptors that the distance between the 306 query descriptor and the training descriptor is equal or smaller than maxDistance. Found matches are 307 returned in the distance increasing order. 308 */ 309 virtual void radiusMatch(InputArray queryDescriptors, InputArray trainDescriptors, 310 std::vector<std::vector<DMatch> >& matches, 311 float maxDistance, 312 InputArray mask = noArray(), 313 bool compactResult = false) = 0; 314 315 /** @overload 316 */ 317 virtual void radiusMatch(InputArray queryDescriptors, 318 std::vector<std::vector<DMatch> >& matches, 319 float maxDistance, 320 const std::vector<GpuMat>& masks = std::vector<GpuMat>(), 321 bool compactResult = false) = 0; 322 323 /** @brief For each query descriptor, finds the training descriptors not farther than the specified distance (asynchronous version). 324 325 @param queryDescriptors Query set of descriptors. 326 @param trainDescriptors Train set of descriptors. This set is not added to the train descriptors 327 collection stored in the class object. 328 @param matches Matches array stored in GPU memory. Internal representation is not defined. 329 Use DescriptorMatcher::radiusMatchConvert method to retrieve results in standard representation. 330 @param maxDistance Threshold for the distance between matched descriptors. Distance means here 331 metric distance (e.g. Hamming distance), not the distance between coordinates (which is measured 332 in Pixels)! 333 @param mask Mask specifying permissible matches between an input query and train matrices of 334 descriptors. 335 @param stream CUDA stream. 336 337 For each query descriptor, the methods find such training descriptors that the distance between the 338 query descriptor and the training descriptor is equal or smaller than maxDistance. Found matches are 339 returned in the distance increasing order. 340 */ 341 virtual void radiusMatchAsync(InputArray queryDescriptors, InputArray trainDescriptors, 342 OutputArray matches, 343 float maxDistance, 344 InputArray mask = noArray(), 345 Stream& stream = Stream::Null()) = 0; 346 347 /** @overload 348 */ 349 virtual void radiusMatchAsync(InputArray queryDescriptors, 350 OutputArray matches, 351 float maxDistance, 352 const std::vector<GpuMat>& masks = std::vector<GpuMat>(), 353 Stream& stream = Stream::Null()) = 0; 354 355 /** @brief Converts matches array from internal representation to standard matches vector. 356 357 The method is supposed to be used with DescriptorMatcher::radiusMatchAsync to get final result. 358 Call this method only after DescriptorMatcher::radiusMatchAsync is completed (ie. after synchronization). 359 360 @param gpu_matches Matches, returned from DescriptorMatcher::radiusMatchAsync. 361 @param matches Vector of DMatch objects. 362 @param compactResult Parameter used when the mask (or masks) is not empty. If compactResult is 363 false, the matches vector has the same size as queryDescriptors rows. If compactResult is true, 364 the matches vector does not contain matches for fully masked-out query descriptors. 365 */ 366 virtual void radiusMatchConvert(InputArray gpu_matches, 367 std::vector< std::vector<DMatch> >& matches, 368 bool compactResult = false) = 0; 369 }; 370 371 // 372 // Feature2DAsync 373 // 374 375 /** @brief Abstract base class for CUDA asynchronous 2D image feature detectors and descriptor extractors. 376 */ 377 class CV_EXPORTS Feature2DAsync 378 { 379 public: 380 virtual ~Feature2DAsync(); 381 382 /** @brief Detects keypoints in an image. 383 384 @param image Image. 385 @param keypoints The detected keypoints. 386 @param mask Mask specifying where to look for keypoints (optional). It must be a 8-bit integer 387 matrix with non-zero values in the region of interest. 388 @param stream CUDA stream. 389 */ 390 virtual void detectAsync(InputArray image, 391 OutputArray keypoints, 392 InputArray mask = noArray(), 393 Stream& stream = Stream::Null()); 394 395 /** @brief Computes the descriptors for a set of keypoints detected in an image. 396 397 @param image Image. 398 @param keypoints Input collection of keypoints. 399 @param descriptors Computed descriptors. Row j is the descriptor for j-th keypoint. 400 @param stream CUDA stream. 401 */ 402 virtual void computeAsync(InputArray image, 403 OutputArray keypoints, 404 OutputArray descriptors, 405 Stream& stream = Stream::Null()); 406 407 /** Detects keypoints and computes the descriptors. */ 408 virtual void detectAndComputeAsync(InputArray image, 409 InputArray mask, 410 OutputArray keypoints, 411 OutputArray descriptors, 412 bool useProvidedKeypoints = false, 413 Stream& stream = Stream::Null()); 414 415 /** Converts keypoints array from internal representation to standard vector. */ 416 virtual void convert(InputArray gpu_keypoints, 417 std::vector<KeyPoint>& keypoints) = 0; 418 }; 419 420 // 421 // FastFeatureDetector 422 // 423 424 /** @brief Wrapping class for feature detection using the FAST method. 425 */ 426 class CV_EXPORTS FastFeatureDetector : public cv::FastFeatureDetector, public Feature2DAsync 427 { 428 public: 429 enum 430 { 431 LOCATION_ROW = 0, 432 RESPONSE_ROW, 433 ROWS_COUNT, 434 435 FEATURE_SIZE = 7 436 }; 437 438 static Ptr<FastFeatureDetector> create(int threshold=10, 439 bool nonmaxSuppression=true, 440 int type=FastFeatureDetector::TYPE_9_16, 441 int max_npoints = 5000); 442 443 virtual void setMaxNumPoints(int max_npoints) = 0; 444 virtual int getMaxNumPoints() const = 0; 445 }; 446 447 // 448 // ORB 449 // 450 451 /** @brief Class implementing the ORB (*oriented BRIEF*) keypoint detector and descriptor extractor 452 * 453 * @sa cv::ORB 454 */ 455 class CV_EXPORTS ORB : public cv::ORB, public Feature2DAsync 456 { 457 public: 458 enum 459 { 460 X_ROW = 0, 461 Y_ROW, 462 RESPONSE_ROW, 463 ANGLE_ROW, 464 OCTAVE_ROW, 465 SIZE_ROW, 466 ROWS_COUNT 467 }; 468 469 static Ptr<ORB> create(int nfeatures=500, 470 float scaleFactor=1.2f, 471 int nlevels=8, 472 int edgeThreshold=31, 473 int firstLevel=0, 474 int WTA_K=2, 475 int scoreType=ORB::HARRIS_SCORE, 476 int patchSize=31, 477 int fastThreshold=20, 478 bool blurForDescriptor=false); 479 480 //! if true, image will be blurred before descriptors calculation 481 virtual void setBlurForDescriptor(bool blurForDescriptor) = 0; 482 virtual bool getBlurForDescriptor() const = 0; 483 }; 484 485 //! @} 486 487 }} // namespace cv { namespace cuda { 488 489 #endif /* __OPENCV_CUDAFEATURES2D_HPP__ */ 490