Changing BAD name by TEBLID and using int threshold again for BEBLID

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, BAD, Self-similar.
+ SURF, BRIEF, Censure, Freak, LUCID, Daisy, BEBLID, TEBLID, Self-similar.

modules/xfeatures2d/doc/xfeatures2d.bib

@@ -154,7 +154,7 @@ @article{Suarez2020BEBLID
   author = {Iago Su\'arez and Ghesn Sfeir and Jos\'e M. Buenaposada and Luis Baumela},
 }
 
-@article{Suarez2021BAD,
+@article{Suarez2021TEBLID,
   title = {Revisiting Binary Local Image Description for Resource Limited Devices},
   journal = {IEEE Robotics and Automation Letters},
   volume = {6},

modules/xfeatures2d/include/opencv2/xfeatures2d.hpp

@@ -224,17 +224,18 @@ 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 .
+/** @brief Class implementing TEBLID (Triplet-based Efficient Binary Local Image Descriptor),
+ * described in @cite Suarez2021TEBLID.
 
-BAD \cite Suarez2021BAD is an improvement over BEBLID \cite Suarez2020BEBLID, that uses triplet loss,
+TEBLID stands for Triplet-based Efficient Binary Local Image Descriptor, although originally it was called BAD
+\cite Suarez2021TEBLID. It 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
+TEBLID 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%).
+TEBLID 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.
@@ -243,27 +244,27 @@ IEEE Robotics and Automation Letters, vol. 6, no. 4, pp. 8317-8324, Oct. 2021. <
 
 The descriptor was trained in Liberty split of the UBC datasets \cite winder2007learning .
 */
-class CV_EXPORTS_W BAD : public Feature2D
+class CV_EXPORTS_W TEBLID : 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
+    enum TeblidSize
     {
         SIZE_256_BITS = 102, SIZE_512_BITS = 103,
     };
-    /** @brief Creates the BAD descriptor.
+    /** @brief Creates the TEBLID 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.
+     TEBLID::SIZE_256_BITS or TEBLID::SIZE_512_BITS.
     */
-    CV_WRAP static Ptr<BAD> create(float scale_factor, int n_bits = BAD::SIZE_256_BITS);
+    CV_WRAP static Ptr<TEBLID> create(float scale_factor, int n_bits = TEBLID::SIZE_256_BITS);
 };
 
 /** @brief Class implementing DAISY descriptor, described in @cite Tola10

modules/xfeatures2d/perf/perf_bad.cpp renamed to modules/xfeatures2d/perf/perf_teblid.cpp

@@ -5,14 +5,14 @@
 
 namespace opencv_test { namespace {
 
-typedef perf::TestBaseWithParam<std::string> bad;
+typedef perf::TestBaseWithParam<std::string> teblid;
 
-#define BAD_IMAGES \
+#define TEBLID_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))
+PERF_TEST_P(teblid, extract, testing::Values(TEBLID_IMAGES))
 {
     string filename = getDataPath(GetParam());
     Mat frame = imread(filename, IMREAD_GRAYSCALE);
@@ -25,7 +25,7 @@ PERF_TEST_P(bad, extract, testing::Values(BAD_IMAGES))
     vector<KeyPoint> points;
     detector->detect(frame, points, mask);
 
-    Ptr<BAD> descriptor = BAD::create(6.25f);
+    Ptr<TEBLID> descriptor = TEBLID::create(6.25f);
     cv::Mat descriptors;
     TEST_CYCLE() descriptor->compute(frame, points, descriptors);
 

modules/xfeatures2d/src/beblid.cpp

@@ -27,12 +27,18 @@ namespace xfeatures2d
 
 // Struct containing the 6 parameters that define an Average Box weak-learner
 struct ABWLParams
+{
+    int x1, y1, x2, y2, boxRadius, th;
+};
+// Same as previous with floating point threshold
+struct ABWLParamsFloatTh
 {
     int x1, y1, x2, y2, boxRadius;
     float th;
 };
 
 // BEBLID implementation
+template <class WeakLearnerT>
 class BEBLID_Impl CV_FINAL: public BEBLID
 {
 public:
@@ -56,26 +62,26 @@ class BEBLID_Impl CV_FINAL: public BEBLID
     void compute(InputArray image, vector<KeyPoint> &keypoints, OutputArray descriptors) CV_OVERRIDE;
 
 private:
-    std::vector<ABWLParams> wl_params_;
+    std::vector<WeakLearnerT> wl_params_;
     float scale_factor_;
     cv::Size patch_size_;
 
-    void computeBEBLID(const cv::Mat &integralImg,
-                       const std::vector<cv::KeyPoint> &keypoints,
-                       cv::Mat &descriptors);
+    void computeBoxDiffsDescriptor(const cv::Mat &integralImg,
+                                   const std::vector<cv::KeyPoint> &keypoints,
+                                   cv::Mat &descriptors);
 }; // END BEBLID_Impl CLASS
 
 
-// BAD implementation
-class BAD_Impl CV_FINAL: public BAD
+// TEBLID implementation
+class TEBLID_Impl CV_FINAL: public TEBLID
 {
 public:
 
     // constructor
-    explicit BAD_Impl(float scale_factor, int n_bits = BAD::SIZE_256_BITS) : impl(scale_factor, n_bits){}
+    explicit TEBLID_Impl(float scale_factor, int n_bits = TEBLID::SIZE_256_BITS) : impl(scale_factor, n_bits){}
 
     // destructor
-    ~BAD_Impl() CV_OVERRIDE = default;
+    ~TEBLID_Impl() CV_OVERRIDE = default;
 
     // returns the descriptor length in bytes
     int descriptorSize() const CV_OVERRIDE { return impl.descriptorSize(); }
@@ -93,12 +99,12 @@ class BAD_Impl CV_FINAL: public BAD
     }
 
 private:
-    BEBLID_Impl impl;
-}; // END BAD_Impl CLASS
+    BEBLID_Impl<ABWLParamsFloatTh> impl;
+}; // END TEBLID_Impl CLASS
 
-Ptr<BAD> BAD::create(float scale_factor, int n_bits)
+Ptr<TEBLID> TEBLID::create(float scale_factor, int n_bits)
 {
-    return makePtr<BAD_Impl>(scale_factor, n_bits);
+    return makePtr<TEBLID_Impl>(scale_factor, n_bits);
 }
 
 /**
@@ -137,8 +143,9 @@ static inline bool isKeypointInTheBorder(const cv::KeyPoint &kp,
  * @param scaleFactor A scale factor that magnifies the measurement functions w.r.t. the keypoint.
  * @param patchSize The size of the normalized patch where the measurement functions were learnt.
  */
-static inline void rectifyABWL(const std::vector<ABWLParams> &wlPatchParams,
-                               std::vector<ABWLParams> &wlImageParams,
+template< typename WeakLearnerT>
+static inline void rectifyABWL(const std::vector<WeakLearnerT> &wlPatchParams,
+                               std::vector<WeakLearnerT> &wlImageParams,
                                const cv::KeyPoint &kp,
                                float scaleFactor = 1,
                                const cv::Size &patchSize = cv::Size(32, 32))
@@ -188,7 +195,8 @@ static inline void rectifyABWL(const std::vector<ABWLParams> &wlPatchParams,
  * @param integralImage The integral image used to compute the average gray value in the square regions.
  * @return The difference of gray level in the two squares defined by wlImageParams
  */
-static inline float computeABWLResponse(const ABWLParams &wlImageParams,
+template <typename WeakLearnerT>
+static inline float computeABWLResponse(const WeakLearnerT &wlImageParams,
                                         const cv::Mat &integralImage)
 {
     CV_DbgAssert(!integralImage.empty());
@@ -276,7 +284,8 @@ static inline float computeABWLResponse(const ABWLParams &wlImageParams,
 }
 
 // descriptor computation using keypoints
-void BEBLID_Impl::compute(InputArray _image, vector<KeyPoint> &keypoints, OutputArray _descriptors)
+template <class WeakLearnerT>
+void BEBLID_Impl<WeakLearnerT>::compute(InputArray _image, vector<KeyPoint> &keypoints, OutputArray _descriptors)
 {
     Mat image = _image.getMat();
 
@@ -318,45 +327,54 @@ void BEBLID_Impl::compute(InputArray _image, vector<KeyPoint> &keypoints, Output
     CV_DbgAssert(descriptors.type() == CV_8UC1);
 
     // Compute the BEBLID descriptors
-    computeBEBLID(integralImg, keypoints, descriptors);
+    computeBoxDiffsDescriptor(integralImg, keypoints, descriptors);
 }
 
 // constructor
-BEBLID_Impl::BEBLID_Impl(float scale_factor, int n_bits)
+template <class WeakLearnerT>
+BEBLID_Impl<WeakLearnerT>::BEBLID_Impl(float scale_factor, int n_bits)
     : scale_factor_(scale_factor), patch_size_(32, 32)
 {
+    WeakLearnerT * begin_ptr, * end_ptr;
     if (n_bits == BEBLID::SIZE_512_BITS)
     {
         #include "beblid.p512.hpp"
-        wl_params_.assign(wl_params_512, wl_params_512 + sizeof(wl_params_512) / sizeof(wl_params_512[0]));
+        begin_ptr = (WeakLearnerT *) std::begin(beblid_wl_params_512);
+        end_ptr = (WeakLearnerT *) std::end(beblid_wl_params_512);
     }
     else if(n_bits == BEBLID::SIZE_256_BITS)
     {
         #include "beblid.p256.hpp"
-        wl_params_.assign(wl_params_256, wl_params_256 + sizeof(wl_params_256) / sizeof(wl_params_256[0]));
+        begin_ptr = (WeakLearnerT *) std::begin(beblid_wl_params_256);
+        end_ptr = (WeakLearnerT *) std::end(beblid_wl_params_256);
     }
-    else if (n_bits == BAD::SIZE_512_BITS)
+    else if (n_bits == TEBLID::SIZE_512_BITS)
     {
-        #include "bad.p512.hpp"
-        wl_params_.assign(bad_params_512, bad_params_512 + sizeof(bad_params_512) / sizeof(bad_params_512[0]));
+        #include "teblid.p512.hpp"
+
+        begin_ptr = (WeakLearnerT *) std::begin(teblid_wl_params_512);
+        end_ptr = (WeakLearnerT *) std::end(teblid_wl_params_512);
     }
-    else if(n_bits == BAD::SIZE_256_BITS)
+    else if(n_bits == TEBLID::SIZE_256_BITS)
     {
-        #include "bad.p256.hpp"
-        wl_params_.assign(bad_params_256, bad_params_256 + sizeof(bad_params_256) / sizeof(bad_params_256[0]));
+        #include "teblid.p256.hpp"
+
+        begin_ptr = (WeakLearnerT *) std::begin(teblid_wl_params_256);
+        end_ptr = (WeakLearnerT *) std::end(teblid_wl_params_256);
     }
     else
     {
-        CV_Error(Error::StsBadArg, "n_bits should be either BAD::SIZE_512_BITS, BAD::SIZE_256_BITS, "
+        CV_Error(Error::StsBadArg, "n_bits should be either TEBLID::SIZE_512_BITS, TEBLID::SIZE_256_BITS, "
                                    "BEBLID::SIZE_512_BITS or BEBLID::SIZE_256_BITS");
     }
-
+    wl_params_.assign(begin_ptr, end_ptr);
 }
 
 // Internal function that implements the core of BEBLID descriptor
-void BEBLID_Impl::computeBEBLID(const cv::Mat &integralImg,
-                                const std::vector<cv::KeyPoint> &keypoints,
-                                cv::Mat &descriptors)
+template<class WeakLearnerT>
+void BEBLID_Impl<WeakLearnerT>::computeBoxDiffsDescriptor(const cv::Mat &integralImg,
+                                                          const std::vector<cv::KeyPoint> &keypoints,
+                                                          cv::Mat &descriptors)
 {
     CV_DbgAssert(!integralImg.empty());
     CV_DbgAssert(size_t(descriptors.rows) == keypoints.size());
@@ -371,13 +389,13 @@ void BEBLID_Impl::computeBEBLID(const cv::Mat &integralImg,
 #endif
     {
         // Get a pointer to the first element in the range
-        ABWLParams *wl;
+        WeakLearnerT *wl;
         float responseFun;
         int areaResponseFun, kpIdx;
         size_t wlIdx;
         int box1x1, box1y1, box1x2, box1y2, box2x1, box2y1, box2x2, box2y2, bit_idx, side;
         uchar byte = 0;
-        std::vector<ABWLParams> imgWLParams(wl_params_.size());
+        std::vector<WeakLearnerT> imgWLParams(wl_params_.size());
         uchar *d = &descriptors.at<uchar>(range.start, 0);
 
         for (kpIdx = range.start; kpIdx < range.end; kpIdx++)
@@ -452,7 +470,7 @@ void BEBLID_Impl::computeBEBLID(const cv::Mat &integralImg,
 
 Ptr<BEBLID> BEBLID::create(float scale_factor, int n_bits)
 {
-    return makePtr<BEBLID_Impl>(scale_factor, n_bits);
+    return makePtr<BEBLID_Impl<ABWLParams>>(scale_factor, n_bits);
 }
 } // END NAMESPACE XFEATURES2D
 } // END NAMESPACE CV

modules/xfeatures2d/src/beblid.p256.hpp

@@ -12,7 +12,7 @@
 
 // Pre-trained parameters of BEBLID-256 trained in Liberty data set with
 // a million of patch pairs, 20% positives and 80% negatives
-static const ABWLParams wl_params_256[] = {
+static const ABWLParams beblid_wl_params_256[] = {
     {26, 20, 14, 16, 5, 16}, {17, 17, 15, 15, 2, 7}, {18, 16, 8, 13, 3, 18},
     {19, 15, 13, 14, 3, 17}, {16, 16, 5, 15, 4, 10}, {25, 10, 16, 16, 6, 11},
     {16, 15, 12, 15, 1, 12}, {18, 17, 14, 17, 1, 13}, {15, 14, 5, 21, 5, 6}, {14, 14, 11, 7, 4, 2},

modules/xfeatures2d/src/beblid.p512.hpp

@@ -12,7 +12,7 @@
 
 // Pre-trained parameters of BEBLID-512 trained in Liberty data set with
 // a million of patch pairs, 20% positives and 80% negatives
-static const ABWLParams wl_params_512[] = {
+static const ABWLParams beblid_wl_params_512[] = {
     {24, 18, 15, 17, 6, 13}, {19, 14, 13, 17, 2, 18}, {23, 19, 12, 15, 6, 19},
     {24, 14, 16, 16, 6, 11}, {16, 15, 12, 16, 1, 12}, {16, 15, 7, 10, 4, 10},
     {17, 12, 8, 17, 3, 16}, {24, 12, 11, 17, 7, 19}, {19, 17, 14, 11, 3, 13},

modules/xfeatures2d/src/bad.p256.hpp renamed to modules/xfeatures2d/src/teblid.p256.hpp

@@ -10,9 +10,9 @@
 
 // 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
+// Pre-trained parameters of TEBLID-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[] = {
+static const ABWLParamsFloatTh teblid_wl_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},

modules/xfeatures2d/src/bad.p512.hpp renamed to modules/xfeatures2d/src/teblid.p512.hpp

@@ -10,9 +10,9 @@
 
 // ABWLParams: x1, y1, x2, y2, boxRadius, th
 
-// Pre-trained parameters of BAD-512 trained in Liberty data set. 10K triplets are sampled per iteration. Each triplet
+// Pre-trained parameters of TEBLID-512 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_512[] = {
+static const ABWLParamsFloatTh teblid_wl_params_512[] = {
     {17, 18, 12, 15, 2, 14.45}, {13, 14, 5, 7, 5, 4.15}, {21, 16, 16, 14, 1, 7.75},
     {27, 11, 18, 20, 3, 9.65}, {17, 13, 16, 19, 2, 2.25}, {18, 24, 18, 16, 5, 0.15},
     {12, 11, 10, 25, 6, 0.45}, {14, 17, 14, 13, 1, -0.95}, {7, 4, 4, 15, 4, 3.65},

modules/xfeatures2d/test/test_features2d.cpp

@@ -192,10 +192,10 @@ TEST(Features2d_DescriptorExtractor_BEBLID, regression )
     test.safe_run();
 }
 
-TEST(Features2d_DescriptorExtractor_BAD, regression )
+TEST(Features2d_DescriptorExtractor_TEBLID, regression )
 {
-    CV_DescriptorExtractorTest<Hamming> test("descriptor-bad", 1,
-                                             BAD::create(6.75));
+    CV_DescriptorExtractorTest<Hamming> test("descriptor-teblid", 1,
+                                             TEBLID::create(6.75));
     test.safe_run();
 }