Merge pull request #25292 from kaingwade:features2d_parts_to_contrib

Features2d cleanup: Move several feature detectors and descriptors to opencv_contrib #25292

features2d cleanup: #24999

The PR moves KAZE, AKAZE, AgastFeatureDetector, BRISK and BOW to opencv_contrib/xfeatures2d.

Related PR: opencv/opencv_contrib#3709

doc/py_tutorials/py_feature2d/py_brief/py_brief.markdown

@@ -1,92 +0,0 @@
-BRIEF (Binary Robust Independent Elementary Features) {#tutorial_py_brief}
-=====================================================
-
-Goal
-----
-
-In this chapter
-    -   We will see the basics of BRIEF algorithm
-
-Theory
-------
-
-We know SIFT uses 128-dim vector for descriptors. Since it is using floating point numbers, it takes
-basically 512 bytes. Similarly SURF also takes minimum of 256 bytes (for 64-dim). Creating such a
-vector for thousands of features takes a lot of memory which are not feasible for resource-constraint
-applications especially for embedded systems. Larger the memory, longer the time it takes for
-matching.
-
-But all these dimensions may not be needed for actual matching. We can compress it using several
-methods like PCA, LDA etc. Even other methods like hashing using LSH (Locality Sensitive Hashing) is
-used to convert these SIFT descriptors in floating point numbers to binary strings. These binary
-strings are used to match features using Hamming distance. This provides better speed-up because
-finding hamming distance is just applying XOR and bit count, which are very fast in modern CPUs with
-SSE instructions. But here, we need to find the descriptors first, then only we can apply hashing,
-which doesn't solve our initial problem on memory.
-
-BRIEF comes into picture at this moment. It provides a shortcut to find the binary strings directly
-without finding descriptors. It takes smoothened image patch and selects a set of \f$n_d\f$ (x,y)
-location pairs in an unique way (explained in paper). Then some pixel intensity comparisons are done
-on these location pairs. For eg, let first location pairs be \f$p\f$ and \f$q\f$. If \f$I(p) < I(q)\f$, then its
-result is 1, else it is 0. This is applied for all the \f$n_d\f$ location pairs to get a
-\f$n_d\f$-dimensional bitstring.
-
-This \f$n_d\f$ can be 128, 256 or 512. OpenCV supports all of these, but by default, it would be 256
-(OpenCV represents it in bytes. So the values will be 16, 32 and 64). So once you get this, you can
-use Hamming Distance to match these descriptors.
-
-One important point is that BRIEF is a feature descriptor, it doesn't provide any method to find the
-features. So you will have to use any other feature detectors like SIFT, SURF etc. The paper
-recommends to use CenSurE which is a fast detector and BRIEF works even slightly better for CenSurE
-points than for SURF points.
-
-In short, BRIEF is a faster method feature descriptor calculation and matching. It also provides
-high recognition rate unless there is large in-plane rotation.
-
-STAR(CenSurE) in OpenCV
-------
-STAR is a feature detector derived from CenSurE.
-Unlike CenSurE however, which uses polygons like squares, hexagons and octagons to approach a circle,
-Star emulates a circle with 2 overlapping squares: 1 upright and 1 45-degree rotated. These polygons are bi-level.
-They can be seen as polygons with thick borders. The borders and the enclosed area have weights of opposing signs.
-This has better computational characteristics than other scale-space detectors and it is capable of real-time implementation.
-In contrast to SIFT and SURF, which find extrema at sub-sampled pixels that compromises accuracy at larger scales,
-CenSurE creates a feature vector using full spatial resolution at all scales in the pyramid.
-BRIEF in OpenCV
----------------
-
-Below code shows the computation of BRIEF descriptors with the help of CenSurE detector.
-
-note, that you need [opencv contrib](https://github.com/opencv/opencv_contrib)) to use this.
-@code{.py}
-import numpy as np
-import cv2 as cv
-from matplotlib import pyplot as plt
-
-img = cv.imread('simple.jpg', cv.IMREAD_GRAYSCALE)
-
-# Initiate FAST detector
-star = cv.xfeatures2d.StarDetector_create()
-
-# Initiate BRIEF extractor
-brief = cv.xfeatures2d.BriefDescriptorExtractor_create()
-
-# find the keypoints with STAR
-kp = star.detect(img,None)
-
-# compute the descriptors with BRIEF
-kp, des = brief.compute(img, kp)
-
-print( brief.descriptorSize() )
-print( des.shape )
-@endcode
-The function brief.getDescriptorSize() gives the \f$n_d\f$ size used in bytes. By default it is 32. Next one
-is matching, which will be done in another chapter.
-
-Additional Resources
---------------------
-
--#  Michael Calonder, Vincent Lepetit, Christoph Strecha, and Pascal Fua, "BRIEF: Binary Robust
-    Independent Elementary Features", 11th European Conference on Computer Vision (ECCV), Heraklion,
-    Crete. LNCS Springer, September 2010.
-2.  [LSH (Locality Sensitive Hashing)](https://en.wikipedia.org/wiki/Locality-sensitive_hashing) at wikipedia.

doc/py_tutorials/py_feature2d/py_surf_intro/py_surf_intro.markdown

@@ -1,157 +0,0 @@
-Introduction to SURF (Speeded-Up Robust Features) {#tutorial_py_surf_intro}
-=================================================
-
-Goal
-----
-
-In this chapter,
-    -   We will see the basics of SURF
-    -   We will see SURF functionalities in OpenCV
-
-Theory
-------
-
-In last chapter, we saw SIFT for keypoint detection and description. But it was comparatively slow
-and people needed more speeded-up version. In 2006, three people, Bay, H., Tuytelaars, T. and Van
-Gool, L, published another paper, "SURF: Speeded Up Robust Features" which introduced a new
-algorithm called SURF. As name suggests, it is a speeded-up version of SIFT.
-
-In SIFT, Lowe approximated Laplacian of Gaussian with Difference of Gaussian for finding
-scale-space. SURF goes a little further and approximates LoG with Box Filter. Below image shows a
-demonstration of such an approximation. One big advantage of this approximation is that, convolution
-with box filter can be easily calculated with the help of integral images. And it can be done in
-parallel for different scales. Also the SURF rely on determinant of Hessian matrix for both scale
-and location.
-
-![image](images/surf_boxfilter.jpg)
-
-For orientation assignment, SURF uses wavelet responses in horizontal and vertical direction for a
-neighbourhood of size 6s. Adequate gaussian weights are also applied to it. Then they are plotted in
-a space as given in below image. The dominant orientation is estimated by calculating the sum of all
-responses within a sliding orientation window of angle 60 degrees. Interesting thing is that,
-wavelet response can be found out using integral images very easily at any scale. For many
-applications, rotation invariance is not required, so no need of finding this orientation, which
-speeds up the process. SURF provides such a functionality called Upright-SURF or U-SURF. It improves
-speed and is robust upto \f$\pm 15^{\circ}\f$. OpenCV supports both, depending upon the flag,
-**upright**. If it is 0, orientation is calculated. If it is 1, orientation is not calculated and it
-is faster.
-
-![image](images/surf_orientation.jpg)
-
-For feature description, SURF uses Wavelet responses in horizontal and vertical direction (again,
-use of integral images makes things easier). A neighbourhood of size 20sX20s is taken around the
-keypoint where s is the size. It is divided into 4x4 subregions. For each subregion, horizontal and
-vertical wavelet responses are taken and a vector is formed like this,
-\f$v=( \sum{d_x}, \sum{d_y}, \sum{|d_x|}, \sum{|d_y|})\f$. This when represented as a vector gives SURF
-feature descriptor with total 64 dimensions. Lower the dimension, higher the speed of computation
-and matching, but provide better distinctiveness of features.
-
-For more distinctiveness, SURF feature descriptor has an extended 128 dimension version. The sums of
-\f$d_x\f$ and \f$|d_x|\f$ are computed separately for \f$d_y < 0\f$ and \f$d_y \geq 0\f$. Similarly, the sums of
-\f$d_y\f$ and \f$|d_y|\f$ are split up according to the sign of \f$d_x\f$ , thereby doubling the number of
-features. It doesn't add much computation complexity. OpenCV supports both by setting the value of
-flag **extended** with 0 and 1 for 64-dim and 128-dim respectively (default is 128-dim)
-
-Another important improvement is the use of sign of Laplacian (trace of Hessian Matrix) for
-underlying interest point. It adds no computation cost since it is already computed during
-detection. The sign of the Laplacian distinguishes bright blobs on dark backgrounds from the reverse
-situation. In the matching stage, we only compare features if they have the same type of contrast
-(as shown in image below). This minimal information allows for faster matching, without reducing the
-descriptor's performance.
-
-![image](images/surf_matching.jpg)
-
-In short, SURF adds a lot of features to improve the speed in every step. Analysis shows it is 3
-times faster than SIFT while performance is comparable to SIFT. SURF is good at handling images with
-blurring and rotation, but not good at handling viewpoint change and illumination change.
-
-SURF in OpenCV
---------------
-
-OpenCV provides SURF functionalities just like SIFT. You initiate a SURF object with some optional
-conditions like 64/128-dim descriptors, Upright/Normal SURF etc. All the details are well explained
-in docs. Then as we did in SIFT, we can use SURF.detect(), SURF.compute() etc for finding keypoints
-and descriptors.
-
-First we will see a simple demo on how to find SURF keypoints and descriptors and draw it. All
-examples are shown in Python terminal since it is just same as SIFT only.
-@code{.py}
->>> img = cv.imread('fly.png', cv.IMREAD_GRAYSCALE)
-
-# Create SURF object. You can specify params here or later.
-# Here I set Hessian Threshold to 400
->>> surf = cv.xfeatures2d.SURF_create(400)
-
-# Find keypoints and descriptors directly
->>> kp, des = surf.detectAndCompute(img,None)
-
->>> len(kp)
- 699
-@endcode
-1199 keypoints is too much to show in a picture. We reduce it to some 50 to draw it on an image.
-While matching, we may need all those features, but not now. So we increase the Hessian Threshold.
-@code{.py}
-# Check present Hessian threshold
->>> print( surf.getHessianThreshold() )
-400.0
-
-# We set it to some 50000. Remember, it is just for representing in picture.
-# In actual cases, it is better to have a value 300-500
->>> surf.setHessianThreshold(50000)
-
-# Again compute keypoints and check its number.
->>> kp, des = surf.detectAndCompute(img,None)
-
->>> print( len(kp) )
-47
-@endcode
-It is less than 50. Let's draw it on the image.
-@code{.py}
->>> img2 = cv.drawKeypoints(img,kp,None,(255,0,0),4)
-
->>> plt.imshow(img2),plt.show()
-@endcode
-See the result below. You can see that SURF is more like a blob detector. It detects the white blobs
-on wings of butterfly. You can test it with other images.
-
-![image](images/surf_kp1.jpg)
-
-Now I want to apply U-SURF, so that it won't find the orientation.
-@code{.py}
-# Check upright flag, if it False, set it to True
->>> print( surf.getUpright() )
-False
-
->>> surf.setUpright(True)
-
-# Recompute the feature points and draw it
->>> kp = surf.detect(img,None)
->>> img2 = cv.drawKeypoints(img,kp,None,(255,0,0),4)
-
->>> plt.imshow(img2),plt.show()
-@endcode
-See the results below. All the orientations are shown in same direction. It is faster than
-previous. If you are working on cases where orientation is not a problem (like panorama stitching)
-etc, this is better.
-
-![image](images/surf_kp2.jpg)
-
-Finally we check the descriptor size and change it to 128 if it is only 64-dim.
-@code{.py}
-# Find size of descriptor
->>> print( surf.descriptorSize() )
-64
-
-# That means flag, "extended" is False.
->>> surf.getExtended()
- False
-
-# So we make it to True to get 128-dim descriptors.
->>> surf.setExtended(True)
->>> kp, des = surf.detectAndCompute(img,None)
->>> print( surf.descriptorSize() )
-128
->>> print( des.shape )
-(47, 128)
-@endcode
-Remaining part is matching which we will do in another chapter.

doc/py_tutorials/py_feature2d/py_table_of_contents_feature2d.markdown

@@ -22,28 +22,15 @@ Feature Detection and Description {#tutorial_py_table_of_contents_feature2d}
     is not good enough when scale of image changes. Lowe developed a breakthrough method to find
     scale-invariant features and it is called SIFT
 
--   @subpage tutorial_py_surf_intro
-
-    SIFT is really good,
-    but not fast enough, so people came up with a speeded-up version called SURF.
-
 -   @subpage tutorial_py_fast
 
     All the above feature
     detection methods are good in some way. But they are not fast enough to work in real-time
     applications like SLAM. There comes the FAST algorithm, which is really "FAST".
 
--   @subpage tutorial_py_brief
-
-    SIFT uses a feature
-    descriptor with 128 floating point numbers. Consider thousands of such features. It takes lots of
-    memory and more time for matching. We can compress it to make it faster. But still we have to
-    calculate it first. There comes BRIEF which gives the shortcut to find binary descriptors with
-    less memory, faster matching, still higher recognition rate.
-
 -   @subpage tutorial_py_orb
 
-    SIFT and SURF are good in what they do, but what if you have to pay a few dollars every year to use them in your applications? Yeah, they are patented!!! To solve that problem, OpenCV devs came up with a new "FREE" alternative to SIFT & SURF, and that is ORB.
+    SURF is good in what it does, but what if you have to pay a few dollars every year to use it in your applications? Yeah, it is patented!!! To solve that problem, OpenCV devs came up with a new "FREE" alternative to SIFT & SURF, and that is ORB.
 
 -   @subpage tutorial_py_matcher