Adding new BAD descriptor to xfeatures2d module

Author: iago-suarez

modules/xfeatures2d/README.md

@@ -5,4 +5,4 @@ Extra 2D Features Framework
 2. Non-free 2D feature algorithms
 
 Extra 2D Features Framework containing experimental and non-free 2D feature detector/descriptor algorithms:
- SURF, BRIEF, Censure, Freak, LUCID, Daisy, BEBLID, Self-similar.
+ SURF, BRIEF, Censure, Freak, LUCID, Daisy, BEBLID, BAD, Self-similar.

modules/xfeatures2d/doc/xfeatures2d.bib

@@ -154,6 +154,18 @@ @article{Suarez2020BEBLID
   author = {Iago Su\'arez and Ghesn Sfeir and Jos\'e M. Buenaposada and Luis Baumela},
 }
 
+@article{Suarez2021BAD,
+  title = {Revisiting Binary Local Image Description for Resource Limited Devices},
+  journal = {IEEE Robotics and Automation Letters},
+  volume = {6},
+  pages = {8317--8324},
+  year = {2021},
+  number = {4},
+  doi = {https://doi.org/10.1109/LRA.2021.3107024},
+  url = {https://arxiv.org/pdf/2108.08380.pdf},
+  author = {Iago Su\'arez and Jos\'e M. Buenaposada and Luis Baumela},
+}
+
 @inproceedings{winder2007learning,
   title= {Learning Local Image Descriptors},
   author= {Winder, Simon AJ and Brown, Matthew},

modules/xfeatures2d/include/opencv2/xfeatures2d.hpp

@@ -224,6 +224,48 @@ class CV_EXPORTS_W BEBLID : public Feature2D
     CV_WRAP static Ptr<BEBLID> create(float scale_factor, int n_bits = BEBLID::SIZE_512_BITS);
 };
 
+/** @brief Class implementing BAD (Box Average Difference Descriptor),
+ * described in @cite Suarez2021BAD .
+
+BAD \cite Suarez2021BAD is an improvement over BEBLID \cite Suarez2020BEBLID, that uses triplet loss,
+hard negative mining, and anchor swap to improve the image matching results.
+It is able to describe keypoints from any detector just by changing the scale_factor parameter.
+BAD is as efficient as ORB, BEBLID or BRISK, but the triplet-based training objective selected more
+discriminative features that explain the accuracy gain. It is also more compact than BEBLID,
+when running the [AKAZE example](https://raw.githubusercontent.com/opencv/opencv/master/samples/cpp/tutorial_code/features2D/AKAZE_match.cpp)
+with 10000 keypoints detected by ORB, BEBLID obtains 561 inliers (75%) with 512 bits, whereas
+BAD obtains 621 (75.2%) with 256 bits. ORB obtains only 493 inliers (63%).
+
+If you find this code useful, please add a reference to the following paper:
+<BLOCKQUOTE> Iago Suárez, José M. Buenaposada, and Luis Baumela.
+Revisiting Binary Local Image Description for Resource Limited Devices.
+IEEE Robotics and Automation Letters, vol. 6, no. 4, pp. 8317-8324, Oct. 2021. </BLOCKQUOTE>
+
+The descriptor was trained in Liberty split of the UBC datasets \cite winder2007learning .
+*/
+class CV_EXPORTS_W BAD : public Feature2D
+{
+public:
+    /**
+     * @brief  Descriptor number of bits, each bit is a box average difference.
+     * The user can choose between 256 or 512 bits.
+     */
+    enum BadSize
+    {
+        SIZE_256_BITS = 102, SIZE_512_BITS = 103,
+    };
+    /** @brief Creates the BAD descriptor.
+    @param scale_factor Adjust the sampling window around detected keypoints:
+    - <b> 1.00f </b> should be the scale for ORB keypoints
+    - <b> 6.75f </b> should be the scale for SIFT detected keypoints
+    - <b> 6.25f </b> is default and fits for KAZE, SURF detected keypoints
+    - <b> 5.00f </b> should be the scale for AKAZE, MSD, AGAST, FAST, BRISK keypoints
+    @param n_bits Determine the number of bits in the descriptor. Should be either
+     BAD::SIZE_256_BITS or BAD::SIZE_512_BITS.
+    */
+    CV_WRAP static Ptr<BAD> create(float scale_factor, int n_bits = BAD::SIZE_256_BITS);
+};
+
 /** @brief Class implementing DAISY descriptor, described in @cite Tola10
 
 @param radius radius of the descriptor at the initial scale

modules/xfeatures2d/perf/perf_bad.cpp

@@ -0,0 +1,36 @@
+// This file is part of OpenCV project.
+// It is subject to the license terms in the LICENSE file found in the top-level directory
+// of this distribution and at http://opencv.org/license.html.
+#include "perf_precomp.hpp"
+
+namespace opencv_test { namespace {
+
+typedef perf::TestBaseWithParam<std::string> bad;
+
+#define BAD_IMAGES \
+    "cv/detectors_descriptors_evaluation/images_datasets/leuven/img1.png",\
+    "stitching/a3.png"
+
+#ifdef OPENCV_ENABLE_NONFREE
+PERF_TEST_P(bad, extract, testing::Values(BAD_IMAGES))
+{
+    string filename = getDataPath(GetParam());
+    Mat frame = imread(filename, IMREAD_GRAYSCALE);
+    ASSERT_FALSE(frame.empty()) << "Unable to load source image " << filename;
+
+    Mat mask;
+    declare.in(frame).time(90);
+
+    Ptr<SURF> detector = SURF::create();
+    vector<KeyPoint> points;
+    detector->detect(frame, points, mask);
+
+    Ptr<BAD> descriptor = BAD::create(6.25f);
+    cv::Mat descriptors;
+    TEST_CYCLE() descriptor->compute(frame, points, descriptors);
+
+    SANITY_CHECK_NOTHING();
+}
+#endif // NONFREE
+
+}} // namespace

modules/xfeatures2d/src/bad.p256.hpp

@@ -0,0 +1,102 @@
+// This file is part of OpenCV project.
+// It is subject to the license terms in the LICENSE file found in the top-level directory
+// of this distribution and at http://opencv.org/license.html.
+// Author: Iago Suarez <[email protected]>
+
+// Implementation of the article:
+//     Iago Suarez, Jose M. Buenaposada, and Luis Baumela.
+//     Revisiting Binary Local Image Description for Resource Limited Devices.
+//     IEEE Robotics and Automation Letters, vol. 6, no. 4, pp. 8317-8324, Oct. 2021.
+
+// ABWLParams: x1, y1, x2, y2, boxRadius, th
+
+// Pre-trained parameters of BAD-256 trained in Liberty data set. 10K triplets are sampled per iteration. Each triplet
+// contains an anchor patch, a positive and a negative, selected as the hardest among 256 random negatives.
+static const ABWLParams bad_params_256[] = {
+    {25, 14, 13, 15, 6, 21.65}, {16, 15, 14, 11, 1, 5.65}, {14, 14, 7, 8, 6, 4.95},
+    {10, 9, 6, 20, 6, 2.45}, {13, 26, 13, 19, 5, 2.25}, {19, 14, 19, 5, 4, 0.85},
+    {16, 19, 15, 13, 2, 3.35}, {26, 26, 21, 12, 5, 1.75}, {18, 23, 15, 20, 2, 4.55},
+    {12, 15, 10, 20, 1, -1.55}, {26, 4, 18, 8, 3, 4.55}, {8, 21, 2, 29, 2, -5.05},
+    {19, 16, 17, 19, 1, 3.15}, {10, 3, 5, 13, 3, 4.85}, {16, 10, 10, 14, 1, 9.95},
+    {19, 12, 18, 17, 1, 1.35}, {21, 26, 21, 19, 5, -2.05}, {6, 7, 5, 5, 5, -0.15},
+    {22, 12, 20, 14, 2, 1.55}, {14, 12, 13, 17, 1, 3.35}, {11, 16, 10, 13, 2, 0.25},
+    {7, 23, 7, 17, 3, 0.35}, {27, 13, 25, 8, 4, 2.45}, {20, 19, 16, 14, 1, 2.75},
+    {27, 10, 24, 16, 2, -1.65}, {13, 12, 13, 6, 2, -0.05}, {14, 18, 13, 23, 1, -0.75},
+    {14, 8, 11, 1, 1, 0.85}, {14, 23, 12, 9, 2, 2.95}, {6, 19, 2, 13, 2, -1.65},
+    {8, 19, 6, 19, 3, -0.05}, {18, 28, 17, 25, 3, -0.25}, {29, 28, 25, 22, 2, -3.85},
+    {15, 19, 15, 17, 3, -0.05}, {23, 21, 19, 19, 1, 3.35}, {20, 20, 20, 16, 3, 0.05},
+    {29, 4, 25, 8, 2, -3.55}, {17, 6, 16, 25, 2, 2.65}, {12, 21, 8, 29, 1, 1.95},
+    {14, 15, 9, 17, 2, 6.35}, {18, 5, 17, 3, 3, 0.85}, {21, 12, 18, 10, 1, 2.65},
+    {17, 14, 14, 14, 2, 12.45}, {5, 26, 3, 6, 3, 0.05}, {16, 13, 15, 14, 1, 3.35},
+    {28, 21, 24, 22, 3, 1.75}, {13, 12, 13, 10, 1, -1.05}, {22, 3, 21, 11, 3, -1.05},
+    {27, 27, 4, 16, 4, 28.25}, {12, 13, 7, 10, 1, 0.35}, {15, 25, 15, 22, 2, -0.15},
+    {19, 10, 18, 12, 1, 2.05}, {17, 16, 17, 9, 2, 2.55}, {21, 17, 21, 14, 2, 0.85},
+    {13, 19, 12, 16, 1, 1.35}, {11, 11, 9, 15, 1, 1.15}, {15, 26, 14, 28, 3, 1.25},
+    {17, 22, 17, 20, 1, 1.35}, {10, 26, 2, 27, 2, 1.85}, {28, 12, 26, 23, 3, 3.95},
+    {4, 5, 3, 14, 3, 0.75}, {17, 7, 17, 4, 3, 1.65}, {19, 15, 17, 15, 1, -3.15},
+    {7, 8, 2, 5, 2, -6.35}, {22, 15, 19, 14, 2, 2.05}, {15, 16, 12, 20, 1, -5.15},
+    {13, 19, 12, 20, 1, 1.75}, {17, 10, 17, 8, 2, -0.65}, {26, 16, 19, 15, 4, -0.65},
+    {9, 14, 8, 20, 2, 1.05}, {27, 14, 27, 4, 4, -0.85}, {17, 14, 15, 9, 1, 0.85},
+    {5, 4, 5, 3, 3, -0.35}, {15, 30, 9, 5, 1, 9.05}, {7, 25, 7, 23, 6, 0.75},
+    {12, 24, 11, 16, 1, -1.75}, {20, 29, 20, 20, 2, 0.75}, {19, 18, 15, 19, 1, 16.05},
+    {9, 11, 7, 11, 7, 0.35}, {27, 26, 26, 15, 4, 0.75}, {10, 28, 10, 27, 3, 0.05},
+    {8, 12, 8, 6, 3, 0.05}, {21, 23, 16, 22, 1, 3.75}, {22, 7, 4, 25, 4, 14.15},
+    {17, 19, 16, 15, 1, -8.95}, {28, 21, 11, 15, 3, 67.25}, {15, 3, 15, 2, 2, -0.45},
+    {16, 16, 14, 17, 3, 1.65}, {10, 17, 7, 18, 3, -1.95}, {12, 18, 12, 15, 1, 1.15},
+    {18, 16, 16, 13, 1, 1.85}, {20, 16, 19, 15, 1, 3.95}, {16, 15, 11, 11, 1, -1.75},
+    {4, 14, 2, 13, 2, 0.45}, {29, 18, 27, 17, 2, -1.55}, {16, 18, 14, 16, 1, 1.05},
+    {23, 29, 22, 27, 2, -0.25}, {18, 13, 18, 11, 1, -1.05}, {26, 23, 21, 27, 4, 3.05},
+    {18, 22, 17, 18, 1, -1.05}, {3, 11, 2, 21, 2, 1.95}, {13, 18, 13, 9, 3, -0.05},
+    {15, 14, 14, 5, 2, 0.85}, {1, 14, 1, 1, 1, 3.05}, {29, 2, 5, 9, 2, 34.85},
+    {12, 17, 11, 17, 1, -0.15}, {13, 10, 12, 25, 4, 4.35}, {5, 13, 1, 25, 1, -10.65},
+    {13, 16, 13, 12, 1, 2.35}, {16, 23, 16, 12, 1, -1.35}, {27, 14, 22, 14, 2, 0.05},
+    {29, 29, 27, 27, 2, 1.05}, {23, 6, 22, 4, 4, 1.05}, {22, 16, 22, 8, 3, -0.15},
+    {14, 1, 11, 9, 1, 0.45}, {12, 11, 10, 8, 2, -0.55}, {24, 19, 7, 16, 7, 10.45},
+    {5, 29, 2, 20, 2, 1.35}, {19, 15, 19, 13, 1, -0.95}, {15, 18, 8, 24, 2, 0.45},
+    {4, 24, 1, 30, 1, -0.85}, {17, 30, 17, 26, 1, 1.45}, {9, 8, 7, 5, 2, -1.85},
+    {15, 20, 15, 18, 1, 1.65}, {27, 5, 14, 26, 4, 2.75}, {18, 19, 18, 15, 1, 1.05},
+    {24, 14, 9, 12, 1, 81.45}, {20, 6, 18, 10, 1, 3.35}, {21, 23, 21, 21, 1, 0.85},
+    {19, 17, 6, 6, 6, 2.65}, {10, 13, 6, 12, 3, 9.35}, {30, 10, 27, 14, 1, 1.15},
+    {9, 5, 6, 3, 3, 1.35}, {26, 21, 18, 19, 2, -1.55}, {23, 5, 23, 4, 4, 0.85},
+    {14, 11, 11, 12, 1, 20.65}, {18, 13, 16, 13, 1, 2.05}, {7, 8, 3, 16, 3, 12.85},
+    {16, 15, 16, 12, 2, 7.95}, {25, 20, 24, 25, 3, 2.25}, {20, 14, 19, 14, 1, 0.05},
+    {12, 29, 12, 5, 1, 0.85}, {23, 17, 13, 13, 5, 8.75}, {27, 27, 23, 22, 4, -8.25},
+    {11, 4, 11, 3, 3, -0.35}, {9, 18, 7, 15, 1, 1.65}, {18, 17, 18, 14, 1, -3.95},
+    {28, 2, 6, 17, 2, 92.55}, {5, 20, 3, 22, 3, 0.55}, {30, 30, 30, 2, 1, 0.35},
+    {16, 8, 15, 13, 1, -0.75}, {15, 16, 14, 13, 1, -12.25}, {28, 5, 27, 5, 3, 0.55},
+    {13, 13, 12, 12, 1, 1.05}, {7, 8, 6, 7, 6, 0.95}, {10, 21, 10, 17, 1, 1.15},
+    {11, 17, 3, 30, 1, -43.25}, {16, 17, 9, 14, 7, 3.05}, {17, 16, 9, 14, 1, 4.35},
+    {14, 29, 13, 27, 2, 7.15}, {19, 5, 19, 3, 2, 0.15}, {18, 16, 14, 14, 1, 57.95},
+    {10, 23, 8, 25, 2, 4.35}, {17, 17, 15, 18, 1, 0.75}, {16, 22, 16, 16, 6, 0.05},
+    {29, 11, 27, 11, 2, 0.05}, {13, 9, 7, 11, 1, 5.45}, {18, 23, 17, 19, 4, 0.55},
+    {12, 14, 11, 17, 1, 0.95}, {13, 23, 11, 18, 2, 20.55}, {27, 8, 23, 20, 4, -4.45},
+    {18, 18, 18, 11, 4, 0.75}, {8, 21, 5, 8, 5, 4.55}, {23, 5, 21, 10, 1, -0.15},
+    {16, 16, 16, 12, 1, 8.65}, {18, 17, 14, 19, 1, 42.65}, {16, 27, 16, 24, 2, -0.45},
+    {21, 17, 15, 15, 1, -1.25}, {16, 5, 15, 9, 2, -1.75}, {24, 16, 1, 30, 1, 11.25},
+    {15, 14, 14, 19, 1, -8.15}, {19, 12, 12, 14, 2, 2.85}, {5, 5, 3, 4, 3, -2.85},
+    {16, 11, 16, 9, 1, -5.05}, {16, 9, 6, 18, 6, 44.65}, {25, 24, 23, 14, 1, 1.45},
+    {5, 26, 5, 17, 5, -0.75}, {9, 16, 6, 18, 1, 11.85}, {29, 25, 9, 24, 2, 2.05},
+    {25, 22, 24, 30, 1, 1.25}, {22, 2, 20, 5, 2, 4.45}, {27, 1, 25, 11, 1, -1.35},
+    {15, 12, 14, 10, 1, 5.95}, {17, 6, 16, 8, 1, 1.35}, {28, 8, 23, 7, 3, -2.55},
+    {24, 24, 23, 22, 7, 5.05}, {7, 18, 5, 20, 3, -2.85}, {22, 15, 20, 20, 1, 7.35},
+    {30, 21, 28, 20, 1, -1.35}, {3, 18, 2, 18, 2, -0.45}, {6, 14, 5, 15, 1, 0.45},
+    {15, 18, 15, 16, 1, -11.85}, {7, 11, 5, 2, 1, -39.65}, {17, 17, 13, 15, 3, 1.65},
+    {12, 15, 7, 15, 5, -0.05}, {16, 12, 15, 18, 1, 3.65}, {14, 26, 14, 25, 5, -0.35},
+    {11, 17, 8, 18, 1, 0.05}, {23, 13, 15, 21, 7, 1.85}, {10, 9, 10, 2, 2, -0.45},
+    {17, 13, 12, 19, 1, -1.75}, {20, 25, 19, 22, 1, 3.95}, {9, 26, 8, 21, 1, 5.25},
+    {19, 22, 19, 18, 1, -1.05}, {8, 15, 3, 12, 1, -11.95}, {26, 13, 16, 19, 5, 37.05},
+    {24, 12, 21, 13, 1, -1.15}, {12, 14, 12, 9, 1, 1.25}, {3, 7, 1, 1, 1, 0.75},
+    {16, 9, 15, 3, 3, -6.05}, {23, 20, 23, 8, 7, -1.55}, {24, 16, 22, 15, 1, -1.65},
+    {20, 19, 20, 14, 1, 0.85}, {30, 27, 29, 22, 1, 0.35}, {27, 17, 4, 16, 4, 101.55},
+    {8, 13, 5, 13, 5, -5.05}, {19, 8, 10, 16, 3, 3.65}, {30, 11, 30, 4, 1, -2.35},
+    {14, 21, 14, 20, 1, -0.35}, {14, 11, 13, 13, 1, -1.65}, {30, 2, 28, 5, 1, 0.65},
+    {17, 29, 12, 24, 2, 6.35}, {15, 25, 6, 30, 1, 2.85}, {4, 1, 1, 1, 1, 5.25},
+    {12, 16, 5, 20, 5, 24.05}, {16, 20, 14, 15, 1, 38.15}, {6, 17, 6, 9, 3, -1.05},
+    {20, 17, 12, 20, 4, 3.05}, {15, 15, 12, 4, 4, 0.35}, {28, 20, 22, 21, 3, -16.05},
+    {14, 18, 9, 18, 5, -1.25}, {26, 1, 23, 5, 1, 0.25}, {21, 24, 11, 10, 7, 1.95},
+    {15, 19, 14, 12, 1, -0.85}, {27, 29, 11, 16, 1, 107.65}, {23, 19, 22, 29, 1, -1.55},
+    {2, 30, 2, 29, 1, -0.25}, {14, 16, 6, 5, 3, 26.95}, {17, 13, 14, 16, 1, 35.95},
+    {19, 14, 15, 16, 1, -4.85}, {20, 25, 13, 15, 6, 1.55}, {19, 18, 11, 12, 5, 10.85},
+    {30, 30, 30, 13, 1, -7.15}, {3, 14, 1, 9, 1, -4.25}, {20, 17, 1, 18, 1, -25.15},
+    {16, 20, 12, 19, 1, 2.75}
+};