1 /* 2 By downloading, copying, installing or using the software you agree to this 3 license. If you do not agree to this license, do not download, install, 4 copy or use the software. 5 6 License Agreement 7 For Open Source Computer Vision Library 8 (3-clause BSD License) 9 10 Copyright (C) 2013, OpenCV Foundation, all rights reserved. 11 Third party copyrights are property of their respective owners. 12 13 Redistribution and use in source and binary forms, with or without modification, 14 are permitted provided that the following conditions are met: 15 16 * Redistributions of source code must retain the above copyright notice, 17 this list of conditions and the following disclaimer. 18 19 * Redistributions in binary form must reproduce the above copyright notice, 20 this list of conditions and the following disclaimer in the documentation 21 and/or other materials provided with the distribution. 22 23 * Neither the names of the copyright holders nor the names of the contributors 24 may be used to endorse or promote products derived from this software 25 without specific prior written permission. 26 27 This software is provided by the copyright holders and contributors "as is" and 28 any express or implied warranties, including, but not limited to, the implied 29 warranties of merchantability and fitness for a particular purpose are 30 disclaimed. In no event shall copyright holders or contributors be liable for 31 any direct, indirect, incidental, special, exemplary, or consequential damages 32 (including, but not limited to, procurement of substitute goods or services; 33 loss of use, data, or profits; or business interruption) however caused 34 and on any theory of liability, whether in contract, strict liability, 35 or tort (including negligence or otherwise) arising in any way out of 36 the use of this software, even if advised of the possibility of such damage. 37 */ 38 39 #ifndef __OPENCV_XFEATURES2D_HPP__ 40 #define __OPENCV_XFEATURES2D_HPP__ 41 42 #include "opencv2/features2d.hpp" 43 #include "opencv2/xfeatures2d/nonfree.hpp" 44 45 /** @defgroup xfeatures2d Extra 2D Features Framework 46 @{ 47 @defgroup xfeatures2d_experiment Experimental 2D Features Algorithms 48 49 This section describes experimental algorithms for 2d feature detection. 50 51 @defgroup xfeatures2d_nonfree Non-free 2D Features Algorithms 52 53 This section describes two popular algorithms for 2d feature detection, SIFT and SURF, that are 54 known to be patented. You need to set the OPENCV_ENABLE_NONFREE option in cmake to use those. Use them at your own risk. 55 56 @defgroup xfeatures2d_match Experimental 2D Features Matching Algorithm 57 58 This section describes the following matching strategies: 59 - GMS: Grid-based Motion Statistics, @cite Bian2017gms 60 - LOGOS: Local geometric support for high-outlier spatial verification, @cite Lowry2018LOGOSLG 61 62 @} 63 */ 64 65 namespace cv 66 { 67 namespace xfeatures2d 68 { 69 70 //! @addtogroup xfeatures2d_experiment 71 //! @{ 72 73 /** @brief Class implementing the FREAK (*Fast Retina Keypoint*) keypoint descriptor, described in @cite AOV12 . 74 75 The algorithm propose a novel keypoint descriptor inspired by the human visual system and more 76 precisely the retina, coined Fast Retina Key- point (FREAK). A cascade of binary strings is 77 computed by efficiently comparing image intensities over a retinal sampling pattern. FREAKs are in 78 general faster to compute with lower memory load and also more robust than SIFT, SURF or BRISK. 79 They are competitive alternatives to existing keypoints in particular for embedded applications. 80 81 @note 82 - An example on how to use the FREAK descriptor can be found at 83 opencv_source_code/samples/cpp/freak_demo.cpp 84 */ 85 class CV_EXPORTS_W FREAK : public Feature2D 86 { 87 public: 88 89 static const int NB_SCALES = 64; 90 static const int NB_PAIRS = 512; 91 static const int NB_ORIENPAIRS = 45; 92 93 /** 94 @param orientationNormalized Enable orientation normalization. 95 @param scaleNormalized Enable scale normalization. 96 @param patternScale Scaling of the description pattern. 97 @param nOctaves Number of octaves covered by the detected keypoints. 98 @param selectedPairs (Optional) user defined selected pairs indexes, 99 */ 100 CV_WRAP static Ptr<FREAK> create(bool orientationNormalized = true, 101 bool scaleNormalized = true, 102 float patternScale = 22.0f, 103 int nOctaves = 4, 104 const std::vector<int>& selectedPairs = std::vector<int>()); 105 }; 106 107 108 /** @brief The class implements the keypoint detector introduced by @cite Agrawal08, synonym of StarDetector. : 109 */ 110 class CV_EXPORTS_W StarDetector : public Feature2D 111 { 112 public: 113 //! the full constructor 114 CV_WRAP static Ptr<StarDetector> create(int maxSize=45, int responseThreshold=30, 115 int lineThresholdProjected=10, 116 int lineThresholdBinarized=8, 117 int suppressNonmaxSize=5); 118 }; 119 120 /* 121 * BRIEF Descriptor 122 */ 123 124 /** @brief Class for computing BRIEF descriptors described in @cite calon2010 . 125 126 @param bytes legth of the descriptor in bytes, valid values are: 16, 32 (default) or 64 . 127 @param use_orientation sample patterns using keypoints orientation, disabled by default. 128 129 */ 130 class CV_EXPORTS_W BriefDescriptorExtractor : public Feature2D 131 { 132 public: 133 CV_WRAP static Ptr<BriefDescriptorExtractor> create( int bytes = 32, bool use_orientation = false ); 134 }; 135 136 /** @brief Class implementing the locally uniform comparison image descriptor, described in @cite LUCID 137 138 An image descriptor that can be computed very fast, while being 139 about as robust as, for example, SURF or BRIEF. 140 141 @note It requires a color image as input. 142 */ 143 class CV_EXPORTS_W LUCID : public Feature2D 144 { 145 public: 146 /** 147 * @param lucid_kernel kernel for descriptor construction, where 1=3x3, 2=5x5, 3=7x7 and so forth 148 * @param blur_kernel kernel for blurring image prior to descriptor construction, where 1=3x3, 2=5x5, 3=7x7 and so forth 149 */ 150 CV_WRAP static Ptr<LUCID> create(const int lucid_kernel = 1, const int blur_kernel = 2); 151 }; 152 153 154 /* 155 * LATCH Descriptor 156 */ 157 158 /** latch Class for computing the LATCH descriptor. 159 If you find this code useful, please add a reference to the following paper in your work: 160 Gil Levi and Tal Hassner, "LATCH: Learned Arrangements of Three Patch Codes", arXiv preprint arXiv:1501.03719, 15 Jan. 2015 161 162 LATCH is a binary descriptor based on learned comparisons of triplets of image patches. 163 164 * bytes is the size of the descriptor - can be 64, 32, 16, 8, 4, 2 or 1 165 * rotationInvariance - whether or not the descriptor should compansate for orientation changes. 166 * half_ssd_size - the size of half of the mini-patches size. For example, if we would like to compare triplets of patches of size 7x7x 167 then the half_ssd_size should be (7-1)/2 = 3. 168 * sigma - sigma value for GaussianBlur smoothing of the source image. Source image will be used without smoothing in case sigma value is 0. 169 170 Note: the descriptor can be coupled with any keypoint extractor. The only demand is that if you use set rotationInvariance = True then 171 you will have to use an extractor which estimates the patch orientation (in degrees). Examples for such extractors are ORB and SIFT. 172 173 Note: a complete example can be found under /samples/cpp/tutorial_code/xfeatures2D/latch_match.cpp 174 175 */ 176 class CV_EXPORTS_W LATCH : public Feature2D 177 { 178 public: 179 CV_WRAP static Ptr<LATCH> create(int bytes = 32, bool rotationInvariance = true, int half_ssd_size = 3, double sigma = 2.0); 180 }; 181 182 /** @brief Class implementing BEBLID (Boosted Efficient Binary Local Image Descriptor), 183 * described in @cite Suarez2020BEBLID . 184 185 BEBLID \cite Suarez2020BEBLID is a efficient binary descriptor learned with boosting. 186 It is able to describe keypoints from any detector just by changing the scale_factor parameter. 187 In several benchmarks it has proved to largely improve other binary descriptors like ORB or 188 BRISK with the same efficiency. BEBLID describes using the difference of mean gray values in 189 different regions of the image around the KeyPoint, the descriptor is specifically optimized for 190 image matching and patch retrieval addressing the asymmetries of these problems. 191 192 If you find this code useful, please add a reference to the following paper: 193 <BLOCKQUOTE> Iago Suárez, Ghesn Sfeir, José M. Buenaposada, and Luis Baumela. 194 BEBLID: Boosted efficient binary local image descriptor. 195 Pattern Recognition Letters, 133:366–372, 2020. </BLOCKQUOTE> 196 197 The descriptor was trained using 1 million of randomly sampled pairs of patches 198 (20% positives and 80% negatives) from the Liberty split of the UBC datasets 199 \cite winder2007learning as described in the paper @cite Suarez2020BEBLID. 200 You can check in the [AKAZE example](https://raw.githubusercontent.com/opencv/opencv/master/samples/cpp/tutorial_code/features2D/AKAZE_match.cpp) 201 how well BEBLID works. Detecting 10000 keypoints with ORB and describing with BEBLID obtains 202 561 inliers (75%) whereas describing with ORB obtains only 493 inliers (63%). 203 */ 204 class CV_EXPORTS_W BEBLID : public Feature2D 205 { 206 public: 207 /** 208 * @brief Descriptor number of bits, each bit is a boosting weak-learner. 209 * The user can choose between 512 or 256 bits. 210 */ 211 enum BeblidSize 212 { 213 SIZE_512_BITS = 100, SIZE_256_BITS = 101, 214 }; 215 /** @brief Creates the BEBLID descriptor. 216 @param scale_factor Adjust the sampling window around detected keypoints: 217 - <b> 1.00f </b> should be the scale for ORB keypoints 218 - <b> 6.75f </b> should be the scale for SIFT detected keypoints 219 - <b> 6.25f </b> is default and fits for KAZE, SURF detected keypoints 220 - <b> 5.00f </b> should be the scale for AKAZE, MSD, AGAST, FAST, BRISK keypoints 221 @param n_bits Determine the number of bits in the descriptor. Should be either 222 BEBLID::SIZE_512_BITS or BEBLID::SIZE_256_BITS. 223 */ 224 CV_WRAP static Ptr<BEBLID> create(float scale_factor, int n_bits = BEBLID::SIZE_512_BITS); 225 }; 226 227 /** @brief Class implementing DAISY descriptor, described in @cite Tola10 228 229 @param radius radius of the descriptor at the initial scale 230 @param q_radius amount of radial range division quantity 231 @param q_theta amount of angular range division quantity 232 @param q_hist amount of gradient orientations range division quantity 233 @param norm choose descriptors normalization type, where 234 DAISY::NRM_NONE will not do any normalization (default), 235 DAISY::NRM_PARTIAL mean that histograms are normalized independently for L2 norm equal to 1.0, 236 DAISY::NRM_FULL mean that descriptors are normalized for L2 norm equal to 1.0, 237 DAISY::NRM_SIFT mean that descriptors are normalized for L2 norm equal to 1.0 but no individual one is bigger than 0.154 as in SIFT 238 @param H optional 3x3 homography matrix used to warp the grid of daisy but sampling keypoints remains unwarped on image 239 @param interpolation switch to disable interpolation for speed improvement at minor quality loss 240 @param use_orientation sample patterns using keypoints orientation, disabled by default. 241 242 */ 243 class CV_EXPORTS_W DAISY : public Feature2D 244 { 245 public: 246 enum NormalizationType 247 { 248 NRM_NONE = 100, NRM_PARTIAL = 101, NRM_FULL = 102, NRM_SIFT = 103, 249 }; 250 CV_WRAP static Ptr<DAISY> create( float radius = 15, int q_radius = 3, int q_theta = 8, 251 int q_hist = 8, DAISY::NormalizationType norm = DAISY::NRM_NONE, InputArray H = noArray(), 252 bool interpolation = true, bool use_orientation = false ); 253 254 /** @overload 255 * @param image image to extract descriptors 256 * @param keypoints of interest within image 257 * @param descriptors resulted descriptors array 258 */ 259 virtual void compute( InputArray image, std::vector<KeyPoint>& keypoints, OutputArray descriptors ) CV_OVERRIDE = 0; 260 261 virtual void compute( InputArrayOfArrays images, 262 std::vector<std::vector<KeyPoint> >& keypoints, 263 OutputArrayOfArrays descriptors ) CV_OVERRIDE; 264 265 /** @overload 266 * @param image image to extract descriptors 267 * @param roi region of interest within image 268 * @param descriptors resulted descriptors array for roi image pixels 269 */ 270 virtual void compute( InputArray image, Rect roi, OutputArray descriptors ) = 0; 271 272 /**@overload 273 * @param image image to extract descriptors 274 * @param descriptors resulted descriptors array for all image pixels 275 */ 276 virtual void compute( InputArray image, OutputArray descriptors ) = 0; 277 278 /** 279 * @param y position y on image 280 * @param x position x on image 281 * @param orientation orientation on image (0->360) 282 * @param descriptor supplied array for descriptor storage 283 */ 284 virtual void GetDescriptor( double y, double x, int orientation, float* descriptor ) const = 0; 285 286 /** 287 * @param y position y on image 288 * @param x position x on image 289 * @param orientation orientation on image (0->360) 290 * @param descriptor supplied array for descriptor storage 291 * @param H homography matrix for warped grid 292 */ 293 virtual bool GetDescriptor( double y, double x, int orientation, float* descriptor, double* H ) const = 0; 294 295 /** 296 * @param y position y on image 297 * @param x position x on image 298 * @param orientation orientation on image (0->360) 299 * @param descriptor supplied array for descriptor storage 300 */ 301 virtual void GetUnnormalizedDescriptor( double y, double x, int orientation, float* descriptor ) const = 0; 302 303 /** 304 * @param y position y on image 305 * @param x position x on image 306 * @param orientation orientation on image (0->360) 307 * @param descriptor supplied array for descriptor storage 308 * @param H homography matrix for warped grid 309 */ 310 virtual bool GetUnnormalizedDescriptor( double y, double x, int orientation, float* descriptor , double *H ) const = 0; 311 312 }; 313 314 /** @brief Class implementing the MSD (*Maximal Self-Dissimilarity*) keypoint detector, described in @cite Tombari14. 315 316 The algorithm implements a novel interest point detector stemming from the intuition that image patches 317 which are highly dissimilar over a relatively large extent of their surroundings hold the property of 318 being repeatable and distinctive. This concept of "contextual self-dissimilarity" reverses the key 319 paradigm of recent successful techniques such as the Local Self-Similarity descriptor and the Non-Local 320 Means filter, which build upon the presence of similar - rather than dissimilar - patches. Moreover, 321 it extends to contextual information the local self-dissimilarity notion embedded in established 322 detectors of corner-like interest points, thereby achieving enhanced repeatability, distinctiveness and 323 localization accuracy. 324 325 */ 326 327 class CV_EXPORTS_W MSDDetector : public Feature2D { 328 329 public: 330 331 static Ptr<MSDDetector> create(int m_patch_radius = 3, int m_search_area_radius = 5, 332 int m_nms_radius = 5, int m_nms_scale_radius = 0, float m_th_saliency = 250.0f, int m_kNN = 4, 333 float m_scale_factor = 1.25f, int m_n_scales = -1, bool m_compute_orientation = false); 334 }; 335 336 /** @brief Class implementing VGG (Oxford Visual Geometry Group) descriptor trained end to end 337 using "Descriptor Learning Using Convex Optimisation" (DLCO) aparatus described in @cite Simonyan14. 338 339 @param desc type of descriptor to use, VGG::VGG_120 is default (120 dimensions float) 340 Available types are VGG::VGG_120, VGG::VGG_80, VGG::VGG_64, VGG::VGG_48 341 @param isigma gaussian kernel value for image blur (default is 1.4f) 342 @param img_normalize use image sample intensity normalization (enabled by default) 343 @param use_orientation sample patterns using keypoints orientation, enabled by default 344 @param scale_factor adjust the sampling window of detected keypoints to 64.0f (VGG sampling window) 345 6.25f is default and fits for KAZE, SURF detected keypoints window ratio 346 6.75f should be the scale for SIFT detected keypoints window ratio 347 5.00f should be the scale for AKAZE, MSD, AGAST, FAST, BRISK keypoints window ratio 348 0.75f should be the scale for ORB keypoints ratio 349 350 @param dsc_normalize clamp descriptors to 255 and convert to uchar CV_8UC1 (disabled by default) 351 352 */ 353 class CV_EXPORTS_W VGG : public Feature2D 354 { 355 public: 356 357 CV_WRAP enum 358 { 359 VGG_120 = 100, VGG_80 = 101, VGG_64 = 102, VGG_48 = 103, 360 }; 361 362 CV_WRAP static Ptr<VGG> create( int desc = VGG::VGG_120, float isigma = 1.4f, 363 bool img_normalize = true, bool use_scale_orientation = true, 364 float scale_factor = 6.25f, bool dsc_normalize = false ); 365 366 CV_WRAP virtual void setSigma(const float isigma) = 0; 367 CV_WRAP virtual float getSigma() const = 0; 368 369 CV_WRAP virtual void setUseNormalizeImage(const bool img_normalize) = 0; 370 CV_WRAP virtual bool getUseNormalizeImage() const = 0; 371 372 CV_WRAP virtual void setUseScaleOrientation(const bool use_scale_orientation) = 0; 373 CV_WRAP virtual bool getUseScaleOrientation() const = 0; 374 375 CV_WRAP virtual void setScaleFactor(const float scale_factor) = 0; 376 CV_WRAP virtual float getScaleFactor() const = 0; 377 378 CV_WRAP virtual void setUseNormalizeDescriptor(const bool dsc_normalize) = 0; 379 CV_WRAP virtual bool getUseNormalizeDescriptor() const = 0; 380 }; 381 382 /** @brief Class implementing BoostDesc (Learning Image Descriptors with Boosting), described in 383 @cite Trzcinski13a and @cite Trzcinski13b. 384 385 @param desc type of descriptor to use, BoostDesc::BINBOOST_256 is default (256 bit long dimension) 386 Available types are: BoostDesc::BGM, BoostDesc::BGM_HARD, BoostDesc::BGM_BILINEAR, BoostDesc::LBGM, 387 BoostDesc::BINBOOST_64, BoostDesc::BINBOOST_128, BoostDesc::BINBOOST_256 388 @param use_orientation sample patterns using keypoints orientation, enabled by default 389 @param scale_factor adjust the sampling window of detected keypoints 390 6.25f is default and fits for KAZE, SURF detected keypoints window ratio 391 6.75f should be the scale for SIFT detected keypoints window ratio 392 5.00f should be the scale for AKAZE, MSD, AGAST, FAST, BRISK keypoints window ratio 393 0.75f should be the scale for ORB keypoints ratio 394 1.50f was the default in original implementation 395 396 @note BGM is the base descriptor where each binary dimension is computed as the output of a single weak learner. 397 BGM_HARD and BGM_BILINEAR refers to same BGM but use different type of gradient binning. In the BGM_HARD that 398 use ASSIGN_HARD binning type the gradient is assigned to the nearest orientation bin. In the BGM_BILINEAR that use 399 ASSIGN_BILINEAR binning type the gradient is assigned to the two neighbouring bins. In the BGM and all other modes that use 400 ASSIGN_SOFT binning type the gradient is assigned to 8 nearest bins according to the cosine value between the gradient 401 angle and the bin center. LBGM (alias FP-Boost) is the floating point extension where each dimension is computed 402 as a linear combination of the weak learner responses. BINBOOST and subvariants are the binary extensions of LBGM 403 where each bit is computed as a thresholded linear combination of a set of weak learners. 404 BoostDesc header files (boostdesc_*.i) was exported from original binaries with export-boostdesc.py script from 405 samples subfolder. 406 407 */ 408 409 class CV_EXPORTS_W BoostDesc : public Feature2D 410 { 411 public: 412 413 CV_WRAP enum 414 { 415 BGM = 100, BGM_HARD = 101, BGM_BILINEAR = 102, LBGM = 200, 416 BINBOOST_64 = 300, BINBOOST_128 = 301, BINBOOST_256 = 302 417 }; 418 419 CV_WRAP static Ptr<BoostDesc> create( int desc = BoostDesc::BINBOOST_256, 420 bool use_scale_orientation = true, float scale_factor = 6.25f ); 421 422 CV_WRAP virtual void setUseScaleOrientation(const bool use_scale_orientation) = 0; 423 CV_WRAP virtual bool getUseScaleOrientation() const = 0; 424 425 CV_WRAP virtual void setScaleFactor(const float scale_factor) = 0; 426 CV_WRAP virtual float getScaleFactor() const = 0; 427 }; 428 429 430 /* 431 * Position-Color-Texture signatures 432 */ 433 434 /** 435 * @brief Class implementing PCT (position-color-texture) signature extraction 436 * as described in @cite KrulisLS16. 437 * The algorithm is divided to a feature sampler and a clusterizer. 438 * Feature sampler produces samples at given set of coordinates. 439 * Clusterizer then produces clusters of these samples using k-means algorithm. 440 * Resulting set of clusters is the signature of the input image. 441 * 442 * A signature is an array of SIGNATURE_DIMENSION-dimensional points. 443 * Used dimensions are: 444 * weight, x, y position; lab color, contrast, entropy. 445 * @cite KrulisLS16 446 * @cite BeecksUS10 447 */ 448 class CV_EXPORTS_W PCTSignatures : public Algorithm 449 { 450 public: 451 /** 452 * @brief Lp distance function selector. 453 */ 454 enum DistanceFunction 455 { 456 L0_25, L0_5, L1, L2, L2SQUARED, L5, L_INFINITY 457 }; 458 459 /** 460 * @brief Point distributions supported by random point generator. 461 */ 462 enum PointDistribution 463 { 464 UNIFORM, //!< Generate numbers uniformly. 465 REGULAR, //!< Generate points in a regular grid. 466 NORMAL //!< Generate points with normal (gaussian) distribution. 467 }; 468 469 /** 470 * @brief Similarity function selector. 471 * @see 472 * Christian Beecks, Merih Seran Uysal, Thomas Seidl. 473 * Signature quadratic form distance. 474 * In Proceedings of the ACM International Conference on Image and Video Retrieval, pages 438-445. 475 * ACM, 2010. 476 * @cite BeecksUS10 477 * @note For selected distance function: \f[ d(c_i, c_j) \f] and parameter: \f[ \alpha \f] 478 */ 479 enum SimilarityFunction 480 { 481 MINUS, //!< \f[ -d(c_i, c_j) \f] 482 GAUSSIAN, //!< \f[ e^{ -\alpha * d^2(c_i, c_j)} \f] 483 HEURISTIC //!< \f[ \frac{1}{\alpha + d(c_i, c_j)} \f] 484 }; 485 486 487 /** 488 * @brief Creates PCTSignatures algorithm using sample and seed count. 489 * It generates its own sets of sampling points and clusterization seed indexes. 490 * @param initSampleCount Number of points used for image sampling. 491 * @param initSeedCount Number of initial clusterization seeds. 492 * Must be lower or equal to initSampleCount 493 * @param pointDistribution Distribution of generated points. Default: UNIFORM. 494 * Available: UNIFORM, REGULAR, NORMAL. 495 * @return Created algorithm. 496 */ 497 CV_WRAP static Ptr<PCTSignatures> create( 498 const int initSampleCount = 2000, 499 const int initSeedCount = 400, 500 const int pointDistribution = 0); 501 502 /** 503 * @brief Creates PCTSignatures algorithm using pre-generated sampling points 504 * and number of clusterization seeds. It uses the provided 505 * sampling points and generates its own clusterization seed indexes. 506 * @param initSamplingPoints Sampling points used in image sampling. 507 * @param initSeedCount Number of initial clusterization seeds. 508 * Must be lower or equal to initSamplingPoints.size(). 509 * @return Created algorithm. 510 */ 511 CV_WRAP static Ptr<PCTSignatures> create( 512 const std::vector<Point2f>& initSamplingPoints, 513 const int initSeedCount); 514 515 /** 516 * @brief Creates PCTSignatures algorithm using pre-generated sampling points 517 * and clusterization seeds indexes. 518 * @param initSamplingPoints Sampling points used in image sampling. 519 * @param initClusterSeedIndexes Indexes of initial clusterization seeds. 520 * Its size must be lower or equal to initSamplingPoints.size(). 521 * @return Created algorithm. 522 */ 523 CV_WRAP static Ptr<PCTSignatures> create( 524 const std::vector<Point2f>& initSamplingPoints, 525 const std::vector<int>& initClusterSeedIndexes); 526 527 528 529 /** 530 * @brief Computes signature of given image. 531 * @param image Input image of CV_8U type. 532 * @param signature Output computed signature. 533 */ 534 CV_WRAP virtual void computeSignature( 535 InputArray image, 536 OutputArray signature) const = 0; 537 538 /** 539 * @brief Computes signatures for multiple images in parallel. 540 * @param images Vector of input images of CV_8U type. 541 * @param signatures Vector of computed signatures. 542 */ 543 CV_WRAP virtual void computeSignatures( 544 const std::vector<Mat>& images, 545 std::vector<Mat>& signatures) const = 0; 546 547 /** 548 * @brief Draws signature in the source image and outputs the result. 549 * Signatures are visualized as a circle 550 * with radius based on signature weight 551 * and color based on signature color. 552 * Contrast and entropy are not visualized. 553 * @param source Source image. 554 * @param signature Image signature. 555 * @param result Output result. 556 * @param radiusToShorterSideRatio Determines maximal radius of signature in the output image. 557 * @param borderThickness Border thickness of the visualized signature. 558 */ 559 CV_WRAP static void drawSignature( 560 InputArray source, 561 InputArray signature, 562 OutputArray result, 563 float radiusToShorterSideRatio = 1.0 / 8, 564 int borderThickness = 1); 565 566 /** 567 * @brief Generates initial sampling points according to selected point distribution. 568 * @param initPoints Output vector where the generated points will be saved. 569 * @param count Number of points to generate. 570 * @param pointDistribution Point distribution selector. 571 * Available: UNIFORM, REGULAR, NORMAL. 572 * @note Generated coordinates are in range [0..1) 573 */ 574 CV_WRAP static void generateInitPoints( 575 std::vector<Point2f>& initPoints, 576 const int count, 577 int pointDistribution); 578 579 580 /**** sampler ****/ 581 582 /** 583 * @brief Number of initial samples taken from the image. 584 */ 585 CV_WRAP virtual int getSampleCount() const = 0; 586 587 /** 588 * @brief Color resolution of the greyscale bitmap represented in allocated bits 589 * (i.e., value 4 means that 16 shades of grey are used). 590 * The greyscale bitmap is used for computing contrast and entropy values. 591 */ 592 CV_WRAP virtual int getGrayscaleBits() const = 0; 593 /** 594 * @brief Color resolution of the greyscale bitmap represented in allocated bits 595 * (i.e., value 4 means that 16 shades of grey are used). 596 * The greyscale bitmap is used for computing contrast and entropy values. 597 */ 598 CV_WRAP virtual void setGrayscaleBits(int grayscaleBits) = 0; 599 600 /** 601 * @brief Size of the texture sampling window used to compute contrast and entropy 602 * (center of the window is always in the pixel selected by x,y coordinates 603 * of the corresponding feature sample). 604 */ 605 CV_WRAP virtual int getWindowRadius() const = 0; 606 /** 607 * @brief Size of the texture sampling window used to compute contrast and entropy 608 * (center of the window is always in the pixel selected by x,y coordinates 609 * of the corresponding feature sample). 610 */ 611 CV_WRAP virtual void setWindowRadius(int radius) = 0; 612 613 614 /** 615 * @brief Weights (multiplicative constants) that linearly stretch individual axes of the feature space 616 * (x,y = position; L,a,b = color in CIE Lab space; c = contrast. e = entropy) 617 */ 618 CV_WRAP virtual float getWeightX() const = 0; 619 /** 620 * @brief Weights (multiplicative constants) that linearly stretch individual axes of the feature space 621 * (x,y = position; L,a,b = color in CIE Lab space; c = contrast. e = entropy) 622 */ 623 CV_WRAP virtual void setWeightX(float weight) = 0; 624 625 /** 626 * @brief Weights (multiplicative constants) that linearly stretch individual axes of the feature space 627 * (x,y = position; L,a,b = color in CIE Lab space; c = contrast. e = entropy) 628 */ 629 CV_WRAP virtual float getWeightY() const = 0; 630 /** 631 * @brief Weights (multiplicative constants) that linearly stretch individual axes of the feature space 632 * (x,y = position; L,a,b = color in CIE Lab space; c = contrast. e = entropy) 633 */ 634 CV_WRAP virtual void setWeightY(float weight) = 0; 635 636 /** 637 * @brief Weights (multiplicative constants) that linearly stretch individual axes of the feature space 638 * (x,y = position; L,a,b = color in CIE Lab space; c = contrast. e = entropy) 639 */ 640 CV_WRAP virtual float getWeightL() const = 0; 641 /** 642 * @brief Weights (multiplicative constants) that linearly stretch individual axes of the feature space 643 * (x,y = position; L,a,b = color in CIE Lab space; c = contrast. e = entropy) 644 */ 645 CV_WRAP virtual void setWeightL(float weight) = 0; 646 647 /** 648 * @brief Weights (multiplicative constants) that linearly stretch individual axes of the feature space 649 * (x,y = position; L,a,b = color in CIE Lab space; c = contrast. e = entropy) 650 */ 651 CV_WRAP virtual float getWeightA() const = 0; 652 /** 653 * @brief Weights (multiplicative constants) that linearly stretch individual axes of the feature space 654 * (x,y = position; L,a,b = color in CIE Lab space; c = contrast. e = entropy) 655 */ 656 CV_WRAP virtual void setWeightA(float weight) = 0; 657 658 /** 659 * @brief Weights (multiplicative constants) that linearly stretch individual axes of the feature space 660 * (x,y = position; L,a,b = color in CIE Lab space; c = contrast. e = entropy) 661 */ 662 CV_WRAP virtual float getWeightB() const = 0; 663 /** 664 * @brief Weights (multiplicative constants) that linearly stretch individual axes of the feature space 665 * (x,y = position; L,a,b = color in CIE Lab space; c = contrast. e = entropy) 666 */ 667 CV_WRAP virtual void setWeightB(float weight) = 0; 668 669 /** 670 * @brief Weights (multiplicative constants) that linearly stretch individual axes of the feature space 671 * (x,y = position; L,a,b = color in CIE Lab space; c = contrast. e = entropy) 672 */ 673 CV_WRAP virtual float getWeightContrast() const = 0; 674 /** 675 * @brief Weights (multiplicative constants) that linearly stretch individual axes of the feature space 676 * (x,y = position; L,a,b = color in CIE Lab space; c = contrast. e = entropy) 677 */ 678 CV_WRAP virtual void setWeightContrast(float weight) = 0; 679 680 /** 681 * @brief Weights (multiplicative constants) that linearly stretch individual axes of the feature space 682 * (x,y = position; L,a,b = color in CIE Lab space; c = contrast. e = entropy) 683 */ 684 CV_WRAP virtual float getWeightEntropy() const = 0; 685 /** 686 * @brief Weights (multiplicative constants) that linearly stretch individual axes of the feature space 687 * (x,y = position; L,a,b = color in CIE Lab space; c = contrast. e = entropy) 688 */ 689 CV_WRAP virtual void setWeightEntropy(float weight) = 0; 690 691 /** 692 * @brief Initial samples taken from the image. 693 * These sampled features become the input for clustering. 694 */ 695 CV_WRAP virtual std::vector<Point2f> getSamplingPoints() const = 0; 696 697 698 699 /** 700 * @brief Weights (multiplicative constants) that linearly stretch individual axes of the feature space. 701 * @param idx ID of the weight 702 * @param value Value of the weight 703 * @note 704 * WEIGHT_IDX = 0; 705 * X_IDX = 1; 706 * Y_IDX = 2; 707 * L_IDX = 3; 708 * A_IDX = 4; 709 * B_IDX = 5; 710 * CONTRAST_IDX = 6; 711 * ENTROPY_IDX = 7; 712 */ 713 CV_WRAP virtual void setWeight(int idx, float value) = 0; 714 /** 715 * @brief Weights (multiplicative constants) that linearly stretch individual axes of the feature space. 716 * @param weights Values of all weights. 717 * @note 718 * WEIGHT_IDX = 0; 719 * X_IDX = 1; 720 * Y_IDX = 2; 721 * L_IDX = 3; 722 * A_IDX = 4; 723 * B_IDX = 5; 724 * CONTRAST_IDX = 6; 725 * ENTROPY_IDX = 7; 726 */ 727 CV_WRAP virtual void setWeights(const std::vector<float>& weights) = 0; 728 729 /** 730 * @brief Translations of the individual axes of the feature space. 731 * @param idx ID of the translation 732 * @param value Value of the translation 733 * @note 734 * WEIGHT_IDX = 0; 735 * X_IDX = 1; 736 * Y_IDX = 2; 737 * L_IDX = 3; 738 * A_IDX = 4; 739 * B_IDX = 5; 740 * CONTRAST_IDX = 6; 741 * ENTROPY_IDX = 7; 742 */ 743 CV_WRAP virtual void setTranslation(int idx, float value) = 0; 744 /** 745 * @brief Translations of the individual axes of the feature space. 746 * @param translations Values of all translations. 747 * @note 748 * WEIGHT_IDX = 0; 749 * X_IDX = 1; 750 * Y_IDX = 2; 751 * L_IDX = 3; 752 * A_IDX = 4; 753 * B_IDX = 5; 754 * CONTRAST_IDX = 6; 755 * ENTROPY_IDX = 7; 756 */ 757 CV_WRAP virtual void setTranslations(const std::vector<float>& translations) = 0; 758 759 /** 760 * @brief Sets sampling points used to sample the input image. 761 * @param samplingPoints Vector of sampling points in range [0..1) 762 * @note Number of sampling points must be greater or equal to clusterization seed count. 763 */ 764 CV_WRAP virtual void setSamplingPoints(std::vector<Point2f> samplingPoints) = 0; 765 766 767 768 /**** clusterizer ****/ 769 /** 770 * @brief Initial seeds (initial number of clusters) for the k-means algorithm. 771 */ 772 CV_WRAP virtual std::vector<int> getInitSeedIndexes() const = 0; 773 /** 774 * @brief Initial seed indexes for the k-means algorithm. 775 */ 776 CV_WRAP virtual void setInitSeedIndexes(std::vector<int> initSeedIndexes) = 0; 777 /** 778 * @brief Number of initial seeds (initial number of clusters) for the k-means algorithm. 779 */ 780 CV_WRAP virtual int getInitSeedCount() const = 0; 781 782 /** 783 * @brief Number of iterations of the k-means clustering. 784 * We use fixed number of iterations, since the modified clustering is pruning clusters 785 * (not iteratively refining k clusters). 786 */ 787 CV_WRAP virtual int getIterationCount() const = 0; 788 /** 789 * @brief Number of iterations of the k-means clustering. 790 * We use fixed number of iterations, since the modified clustering is pruning clusters 791 * (not iteratively refining k clusters). 792 */ 793 CV_WRAP virtual void setIterationCount(int iterationCount) = 0; 794 795 /** 796 * @brief Maximal number of generated clusters. If the number is exceeded, 797 * the clusters are sorted by their weights and the smallest clusters are cropped. 798 */ 799 CV_WRAP virtual int getMaxClustersCount() const = 0; 800 /** 801 * @brief Maximal number of generated clusters. If the number is exceeded, 802 * the clusters are sorted by their weights and the smallest clusters are cropped. 803 */ 804 CV_WRAP virtual void setMaxClustersCount(int maxClustersCount) = 0; 805 806 /** 807 * @brief This parameter multiplied by the index of iteration gives lower limit for cluster size. 808 * Clusters containing fewer points than specified by the limit have their centroid dismissed 809 * and points are reassigned. 810 */ 811 CV_WRAP virtual int getClusterMinSize() const = 0; 812 /** 813 * @brief This parameter multiplied by the index of iteration gives lower limit for cluster size. 814 * Clusters containing fewer points than specified by the limit have their centroid dismissed 815 * and points are reassigned. 816 */ 817 CV_WRAP virtual void setClusterMinSize(int clusterMinSize) = 0; 818 819 /** 820 * @brief Threshold euclidean distance between two centroids. 821 * If two cluster centers are closer than this distance, 822 * one of the centroid is dismissed and points are reassigned. 823 */ 824 CV_WRAP virtual float getJoiningDistance() const = 0; 825 /** 826 * @brief Threshold euclidean distance between two centroids. 827 * If two cluster centers are closer than this distance, 828 * one of the centroid is dismissed and points are reassigned. 829 */ 830 CV_WRAP virtual void setJoiningDistance(float joiningDistance) = 0; 831 832 /** 833 * @brief Remove centroids in k-means whose weight is lesser or equal to given threshold. 834 */ 835 CV_WRAP virtual float getDropThreshold() const = 0; 836 /** 837 * @brief Remove centroids in k-means whose weight is lesser or equal to given threshold. 838 */ 839 CV_WRAP virtual void setDropThreshold(float dropThreshold) = 0; 840 841 /** 842 * @brief Distance function selector used for measuring distance between two points in k-means. 843 */ 844 CV_WRAP virtual int getDistanceFunction() const = 0; 845 /** 846 * @brief Distance function selector used for measuring distance between two points in k-means. 847 * Available: L0_25, L0_5, L1, L2, L2SQUARED, L5, L_INFINITY. 848 */ 849 CV_WRAP virtual void setDistanceFunction(int distanceFunction) = 0; 850 851 }; 852 853 /** 854 * @brief Class implementing Signature Quadratic Form Distance (SQFD). 855 * @see Christian Beecks, Merih Seran Uysal, Thomas Seidl. 856 * Signature quadratic form distance. 857 * In Proceedings of the ACM International Conference on Image and Video Retrieval, pages 438-445. 858 * ACM, 2010. 859 * @cite BeecksUS10 860 */ 861 class CV_EXPORTS_W PCTSignaturesSQFD : public Algorithm 862 { 863 public: 864 865 /** 866 * @brief Creates the algorithm instance using selected distance function, 867 * similarity function and similarity function parameter. 868 * @param distanceFunction Distance function selector. Default: L2 869 * Available: L0_25, L0_5, L1, L2, L2SQUARED, L5, L_INFINITY 870 * @param similarityFunction Similarity function selector. Default: HEURISTIC 871 * Available: MINUS, GAUSSIAN, HEURISTIC 872 * @param similarityParameter Parameter of the similarity function. 873 */ 874 CV_WRAP static Ptr<PCTSignaturesSQFD> create( 875 const int distanceFunction = 3, 876 const int similarityFunction = 2, 877 const float similarityParameter = 1.0f); 878 879 /** 880 * @brief Computes Signature Quadratic Form Distance of two signatures. 881 * @param _signature0 The first signature. 882 * @param _signature1 The second signature. 883 */ 884 CV_WRAP virtual float computeQuadraticFormDistance( 885 InputArray _signature0, 886 InputArray _signature1) const = 0; 887 888 /** 889 * @brief Computes Signature Quadratic Form Distance between the reference signature 890 * and each of the other image signatures. 891 * @param sourceSignature The signature to measure distance of other signatures from. 892 * @param imageSignatures Vector of signatures to measure distance from the source signature. 893 * @param distances Output vector of measured distances. 894 */ 895 CV_WRAP virtual void computeQuadraticFormDistances( 896 const Mat& sourceSignature, 897 const std::vector<Mat>& imageSignatures, 898 std::vector<float>& distances) const = 0; 899 900 }; 901 902 /** 903 * @brief Elliptic region around an interest point. 904 */ 905 class CV_EXPORTS Elliptic_KeyPoint : public KeyPoint 906 { 907 public: 908 Size_<float> axes; //!< the lengths of the major and minor ellipse axes 909 float si; //!< the integration scale at which the parameters were estimated 910 Matx23f transf; //!< the transformation between image space and local patch space 911 Elliptic_KeyPoint(); 912 Elliptic_KeyPoint(Point2f pt, float angle, Size axes, float size, float si); 913 virtual ~Elliptic_KeyPoint(); 914 }; 915 916 /** 917 * @brief Class implementing the Harris-Laplace feature detector as described in @cite Mikolajczyk2004. 918 */ 919 class CV_EXPORTS_W HarrisLaplaceFeatureDetector : public Feature2D 920 { 921 public: 922 /** 923 * @brief Creates a new implementation instance. 924 * 925 * @param numOctaves the number of octaves in the scale-space pyramid 926 * @param corn_thresh the threshold for the Harris cornerness measure 927 * @param DOG_thresh the threshold for the Difference-of-Gaussians scale selection 928 * @param maxCorners the maximum number of corners to consider 929 * @param num_layers the number of intermediate scales per octave 930 */ 931 CV_WRAP static Ptr<HarrisLaplaceFeatureDetector> create( 932 int numOctaves=6, 933 float corn_thresh=0.01f, 934 float DOG_thresh=0.01f, 935 int maxCorners=5000, 936 int num_layers=4); 937 }; 938 939 /** 940 * @brief Class implementing affine adaptation for key points. 941 * 942 * A @ref FeatureDetector and a @ref DescriptorExtractor are wrapped to augment the 943 * detected points with their affine invariant elliptic region and to compute 944 * the feature descriptors on the regions after warping them into circles. 945 * 946 * The interface is equivalent to @ref Feature2D, adding operations for 947 * @ref Elliptic_KeyPoint "Elliptic_KeyPoints" instead of @ref KeyPoint "KeyPoints". 948 */ 949 class CV_EXPORTS_W AffineFeature2D : public Feature2D 950 { 951 public: 952 /** 953 * @brief Creates an instance wrapping the given keypoint detector and 954 * descriptor extractor. 955 */ 956 static Ptr<AffineFeature2D> create( 957 Ptr<FeatureDetector> keypoint_detector, 958 Ptr<DescriptorExtractor> descriptor_extractor); 959 960 /** 961 * @brief Creates an instance where keypoint detector and descriptor 962 * extractor are identical. 963 */ create(Ptr<FeatureDetector> keypoint_detector)964 static Ptr<AffineFeature2D> create( 965 Ptr<FeatureDetector> keypoint_detector) 966 { 967 return create(keypoint_detector, keypoint_detector); 968 } 969 970 using Feature2D::detect; // overload, don't hide 971 /** 972 * @brief Detects keypoints in the image using the wrapped detector and 973 * performs affine adaptation to augment them with their elliptic regions. 974 */ 975 virtual void detect( 976 InputArray image, 977 CV_OUT std::vector<Elliptic_KeyPoint>& keypoints, 978 InputArray mask=noArray() ) = 0; 979 980 using Feature2D::detectAndCompute; // overload, don't hide 981 /** 982 * @brief Detects keypoints and computes descriptors for their surrounding 983 * regions, after warping them into circles. 984 */ 985 virtual void detectAndCompute( 986 InputArray image, 987 InputArray mask, 988 CV_OUT std::vector<Elliptic_KeyPoint>& keypoints, 989 OutputArray descriptors, 990 bool useProvidedKeypoints=false ) = 0; 991 }; 992 993 /** 994 @brief Class implementing the Tree Based Morse Regions (TBMR) as described in 995 @cite Najman2014 extended with scaled extraction ability. 996 997 @param min_area prune areas smaller than minArea 998 @param max_area_relative prune areas bigger than maxArea = max_area_relative * 999 input_image_size 1000 @param scale_factor scale factor for scaled extraction. 1001 @param n_scales number of applications of the scale factor (octaves). 1002 1003 @note This algorithm is based on Component Tree (Min/Max) as well as MSER but 1004 uses a Morse-theory approach to extract features. 1005 1006 Features are ellipses (similar to MSER, however a MSER feature can never be a 1007 TBMR feature and vice versa). 1008 1009 */ 1010 class CV_EXPORTS_W TBMR : public AffineFeature2D 1011 { 1012 public: 1013 CV_WRAP static Ptr<TBMR> create(int min_area = 60, 1014 float max_area_relative = 0.01f, 1015 float scale_factor = 1.25f, 1016 int n_scales = -1); 1017 1018 CV_WRAP virtual void setMinArea(int minArea) = 0; 1019 CV_WRAP virtual int getMinArea() const = 0; 1020 CV_WRAP virtual void setMaxAreaRelative(float maxArea) = 0; 1021 CV_WRAP virtual float getMaxAreaRelative() const = 0; 1022 CV_WRAP virtual void setScaleFactor(float scale_factor) = 0; 1023 CV_WRAP virtual float getScaleFactor() const = 0; 1024 CV_WRAP virtual void setNScales(int n_scales) = 0; 1025 CV_WRAP virtual int getNScales() const = 0; 1026 }; 1027 1028 /** @brief Estimates cornerness for prespecified KeyPoints using the FAST algorithm 1029 1030 @param image grayscale image where keypoints (corners) are detected. 1031 @param keypoints keypoints which should be tested to fit the FAST criteria. Keypoints not being 1032 detected as corners are removed. 1033 @param threshold threshold on difference between intensity of the central pixel and pixels of a 1034 circle around this pixel. 1035 @param nonmaxSuppression if true, non-maximum suppression is applied to detected corners 1036 (keypoints). 1037 @param type one of the three neighborhoods as defined in the paper: 1038 FastFeatureDetector::TYPE_9_16, FastFeatureDetector::TYPE_7_12, 1039 FastFeatureDetector::TYPE_5_8 1040 1041 Detects corners using the FAST algorithm by @cite Rosten06 . 1042 */ 1043 CV_EXPORTS void FASTForPointSet( InputArray image, CV_IN_OUT std::vector<KeyPoint>& keypoints, 1044 int threshold, bool nonmaxSuppression=true, cv::FastFeatureDetector::DetectorType type=FastFeatureDetector::TYPE_9_16); 1045 1046 1047 //! @} 1048 1049 1050 //! @addtogroup xfeatures2d_match 1051 //! @{ 1052 1053 /** @brief GMS (Grid-based Motion Statistics) feature matching strategy described in @cite Bian2017gms . 1054 @param size1 Input size of image1. 1055 @param size2 Input size of image2. 1056 @param keypoints1 Input keypoints of image1. 1057 @param keypoints2 Input keypoints of image2. 1058 @param matches1to2 Input 1-nearest neighbor matches. 1059 @param matchesGMS Matches returned by the GMS matching strategy. 1060 @param withRotation Take rotation transformation into account. 1061 @param withScale Take scale transformation into account. 1062 @param thresholdFactor The higher, the less matches. 1063 @note 1064 Since GMS works well when the number of features is large, we recommend to use the ORB feature and set FastThreshold to 0 to get as many as possible features quickly. 1065 If matching results are not satisfying, please add more features. (We use 10000 for images with 640 X 480). 1066 If your images have big rotation and scale changes, please set withRotation or withScale to true. 1067 */ 1068 CV_EXPORTS_W void matchGMS(const Size& size1, const Size& size2, const std::vector<KeyPoint>& keypoints1, const std::vector<KeyPoint>& keypoints2, 1069 const std::vector<DMatch>& matches1to2, CV_OUT std::vector<DMatch>& matchesGMS, const bool withRotation = false, 1070 const bool withScale = false, const double thresholdFactor = 6.0); 1071 1072 /** @brief LOGOS (Local geometric support for high-outlier spatial verification) feature matching strategy described in @cite Lowry2018LOGOSLG . 1073 @param keypoints1 Input keypoints of image1. 1074 @param keypoints2 Input keypoints of image2. 1075 @param nn1 Index to the closest BoW centroid for each descriptors of image1. 1076 @param nn2 Index to the closest BoW centroid for each descriptors of image2. 1077 @param matches1to2 Matches returned by the LOGOS matching strategy. 1078 @note 1079 This matching strategy is suitable for features matching against large scale database. 1080 First step consists in constructing the bag-of-words (BoW) from a representative image database. 1081 Image descriptors are then represented by their closest codevector (nearest BoW centroid). 1082 */ 1083 CV_EXPORTS_W void matchLOGOS(const std::vector<KeyPoint>& keypoints1, const std::vector<KeyPoint>& keypoints2, 1084 const std::vector<int>& nn1, const std::vector<int>& nn2, 1085 std::vector<DMatch>& matches1to2); 1086 1087 //! @} 1088 1089 } 1090 } 1091 1092 #endif 1093