feat: add 3DSC descriptor support to correspondence benchmarks

nerdneilsfield · claude · nerdneilsfield · commit de49cf8bd3e8 · 2025-06-02T08:22:35.000-04:00
- Fix 3DSC signature interface compatibility with KNN algorithms - Add data(), size(), value_type, data_type members for KNN interface - Add DSC3DMetric class for proper distance calculations - Add comprehensive 3DSC descriptor benchmarks: - Type comparison (KNN vs brute-force methods) - Quantity scaling tests (50-2000 descriptors) - Dimension impact analysis (1980D comparison) - Add create_test_3dsc_descriptors() helper function - Add bilingual documentation with usage examples - Performance results: ~40ms for 300 descriptors vs ~7ms for SHOT 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>
diff --git a/benchmark/pcl/correspondence_benc.cpp b/benchmark/pcl/correspondence_benc.cpp
@@ -8,6 +8,7 @@
 #include <cpp-toolbox/pcl/descriptors/fpfh_extractor.hpp>
 #include <cpp-toolbox/pcl/descriptors/pfh_extractor.hpp>
 #include <cpp-toolbox/pcl/descriptors/shot_extractor.hpp>
+#include <cpp-toolbox/pcl/descriptors/3dsc_extractor.hpp>
 #include <cpp-toolbox/pcl/knn/bfknn.hpp>
 #include <cpp-toolbox/pcl/knn/kdtree.hpp>
 #include <cpp-toolbox/types/point.hpp>
@@ -72,6 +73,25 @@ struct SHOTMetric
   }
 };
 
+template<typename T>
+struct DSC3DMetric
+{
+  using value_type = T;
+  using result_type = T;
+
+  T operator()(const toolbox::pcl::dsc3d_signature_t<T>& a,
+               const toolbox::pcl::dsc3d_signature_t<T>& b) const
+  {
+    return a.distance(b);
+  }
+
+  T distance(const toolbox::pcl::dsc3d_signature_t<T>& a,
+             const toolbox::pcl::dsc3d_signature_t<T>& b) const
+  {
+    return a.distance(b);
+  }
+};
+
 }  // namespace toolbox::metrics
 
 using namespace toolbox::pcl;
@@ -188,6 +208,42 @@ create_test_shot_descriptors(size_t num_descriptors, std::mt19937& rng)
   return {descriptors, indices};
 }
 
+// 创建测试3DSC描述子 / Create test 3DSC descriptors
+template<typename T>
+std::pair<std::shared_ptr<std::vector<dsc3d_signature_t<T>>>,
+          std::shared_ptr<std::vector<std::size_t>>>
+create_test_3dsc_descriptors(size_t num_descriptors, std::mt19937& rng)
+{
+  auto descriptors = std::make_shared<std::vector<dsc3d_signature_t<T>>>();
+  auto indices = std::make_shared<std::vector<std::size_t>>();
+
+  std::uniform_real_distribution<T> dist(0.0, 1.0);
+
+  for (size_t i = 0; i < num_descriptors; ++i) {
+    dsc3d_signature_t<T> desc;
+
+    // 创建随机描述子 / Create random descriptor (1980 dimensions)
+    for (int j = 0; j < 1980; ++j) {
+      desc.histogram[j] = dist(rng);
+    }
+
+    // 归一化 / Normalize
+    T sum = 0;
+    for (int j = 0; j < 1980; ++j) {
+      sum += desc.histogram[j];
+    }
+    if (sum > 0) {
+      for (int j = 0; j < 1980; ++j) {
+        desc.histogram[j] /= sum;
+      }
+    }
+
+    descriptors->push_back(desc);
+    indices->push_back(i * 10);
+  }
+
+  return {descriptors, indices};
+}
 
 TEST_CASE("对应点生成性能比较 / Correspondence Generation Performance Comparison",
           "[pcl][correspondence][benchmark]")
@@ -375,6 +431,57 @@ TEST_CASE("对应点生成性能比较 / Correspondence Generation Performance C
       };
     }
 
+    SECTION("3DSC描述子性能 / 3DSC descriptor performance")
+    {
+      auto src_data = create_test_3dsc_descriptors<T>(num_desc, rng);
+      auto dst_data = create_test_3dsc_descriptors<T>(num_desc, rng);
+      auto src_descriptors = src_data.first;
+      auto src_indices = src_data.second;
+      auto dst_descriptors = dst_data.first;
+      auto dst_indices = dst_data.second;
+
+      BENCHMARK("3DSC - KNN方法 / 3DSC - KNN method")
+      {
+        using CorrespondenceGen = knn_correspondence_generator_t<
+            T,
+            dsc3d_signature_t<T>,
+            bfknn_generic_t<dsc3d_signature_t<T>,
+                            toolbox::metrics::DSC3DMetric<T>>>;
+        CorrespondenceGen corr_gen;
+
+        auto knn = std::make_shared<
+            bfknn_generic_t<dsc3d_signature_t<T>,
+                            toolbox::metrics::DSC3DMetric<T>>>();
+        corr_gen.set_knn(knn);
+        corr_gen.set_source(src_cloud, src_descriptors, src_indices);
+        corr_gen.set_destination(dst_cloud, dst_descriptors, dst_indices);
+        corr_gen.set_ratio(0.8f);
+        corr_gen.set_mutual_verification(true);
+
+        std::vector<correspondence_t> correspondences;
+        corr_gen.compute(correspondences);
+
+        return correspondences.size();
+      };
+
+      BENCHMARK("3DSC - 暴力搜索（并行） / 3DSC - Brute-force (parallel)")
+      {
+        brute_force_correspondence_generator_t<T, dsc3d_signature_t<T>>
+            corr_gen;
+
+        corr_gen.enable_parallel(true);
+        corr_gen.set_source(src_cloud, src_descriptors, src_indices);
+        corr_gen.set_destination(dst_cloud, dst_descriptors, dst_indices);
+        corr_gen.set_ratio(0.8f);
+        corr_gen.set_mutual_verification(true);
+
+        std::vector<correspondence_t> correspondences;
+        corr_gen.compute(correspondences);
+
+        return correspondences.size();
+      };
+    }
+
   }
 
   SECTION("不同描述子数量的性能影响 / Performance impact of different descriptor counts")
@@ -509,6 +616,39 @@ TEST_CASE("对应点生成性能比较 / Correspondence Generation Performance C
           return correspondences.size();
         };
       }
+
+      DYNAMIC_SECTION("3DSC描述子数量 / 3DSC descriptor count: " << num_desc)
+      {
+        std::mt19937 rng(42);
+        auto src_data = create_test_3dsc_descriptors<T>(num_desc, rng);
+        auto dst_data = create_test_3dsc_descriptors<T>(num_desc, rng);
+        auto src_descriptors = src_data.first;
+        auto src_indices = src_data.second;
+        auto dst_descriptors = dst_data.first;
+        auto dst_indices = dst_data.second;
+
+        auto src_cloud = std::make_shared<point_cloud_t<T>>();
+        auto dst_cloud = std::make_shared<point_cloud_t<T>>();
+        src_cloud->points.resize(num_desc * 10);
+        dst_cloud->points.resize(num_desc * 10);
+
+        BENCHMARK("3DSC - 暴力搜索（并行） / 3DSC - Brute-force (parallel)")
+        {
+          brute_force_correspondence_generator_t<T, dsc3d_signature_t<T>>
+              corr_gen;
+
+          corr_gen.enable_parallel(true);
+          corr_gen.set_source(src_cloud, src_descriptors, src_indices);
+          corr_gen.set_destination(dst_cloud, dst_descriptors, dst_indices);
+          corr_gen.set_ratio(0.8f);
+          corr_gen.set_mutual_verification(true);
+
+          std::vector<correspondence_t> correspondences;
+          corr_gen.compute(correspondences);
+
+          return correspondences.size();
+        };
+      }
     }
   }
 
@@ -684,6 +824,26 @@ TEST_CASE("描述子维度对性能的影响 / Impact of descriptor dimensions o
       };
     }
 
+    // 3DSC (1980维) / 3DSC (1980 dimensions)
+    {
+      auto src_data = create_test_3dsc_descriptors<T>(num_desc, rng);
+      auto dst_data = create_test_3dsc_descriptors<T>(num_desc, rng);
+
+      BENCHMARK("3DSC (1980维) - 暴力搜索 / 3DSC (1980D) - Brute-force")
+      {
+        brute_force_correspondence_generator_t<T, dsc3d_signature_t<T>> corr_gen;
+        corr_gen.enable_parallel(true);
+        corr_gen.set_source(src_cloud, src_data.first, src_data.second);
+        corr_gen.set_destination(dst_cloud, dst_data.first, dst_data.second);
+        corr_gen.set_ratio(0.8f);
+        corr_gen.set_mutual_verification(true);
+
+        std::vector<correspondence_t> correspondences;
+        corr_gen.compute(correspondences);
+        return correspondences.size();
+      };
+    }
+
   }
 }
 
diff --git a/src/include/cpp-toolbox/pcl/descriptors/3dsc_extractor.hpp b/src/include/cpp-toolbox/pcl/descriptors/3dsc_extractor.hpp
@@ -14,12 +14,53 @@
 namespace toolbox::pcl
 {
 
+/**
+ * @brief 3D形状上下文描述子签名 / 3D Shape Context descriptor signature
+ * 
+ * @tparam DataType 数据类型（float或double） / Data type (float or double)
+ * 
+ * @details 3DSC描述子使用1980维直方图（11径向×12方位×15仰角）来描述局部3D形状
+ * The 3DSC descriptor uses a 1980-bin histogram (11 radial × 12 azimuth × 15 elevation) to describe local 3D shape
+ * 
+ * @code
+ * // 基本使用 / Basic usage
+ * dsc3d_signature_t<float> desc1, desc2;
+ * 
+ * // 计算距离 / Compute distance
+ * float dist = desc1.distance(desc2);
+ * 
+ * // 用于KNN搜索 / For KNN search
+ * std::vector<dsc3d_signature_t<float>> descriptors = {...};
+ * bfknn_generic_t<dsc3d_signature_t<float>, DSC3DMetric<float>> knn;
+ * knn.set_input(descriptors);
+ * @endcode
+ */
 template<typename DataType>
 struct dsc3d_signature_t : public base_signature_t<DataType, dsc3d_signature_t<DataType>>
 {
-  static constexpr std::size_t HISTOGRAM_SIZE = 1980;  // 11 * 12 * 15
-  std::array<DataType, HISTOGRAM_SIZE> histogram {};
-
+  using value_type = DataType;  ///< 为了兼容KNN接口 / For KNN interface compatibility
+  using data_type = DataType;   ///< 为了兼容描述子匹配接口 / For descriptor matching interface compatibility
+  static constexpr std::size_t HISTOGRAM_SIZE = 1980;  ///< 直方图大小：11 × 12 × 15 / Histogram size: 11 × 12 × 15
+  std::array<DataType, HISTOGRAM_SIZE> histogram {};   ///< 直方图数据 / Histogram data
+
+  /**
+   * @brief 提供data()方法以兼容IMetric接口 / Provide data() method for IMetric interface compatibility
+   * @return 直方图数据指针 / Pointer to histogram data
+   */
+  const DataType* data() const { return histogram.data(); }
+  DataType* data() { return histogram.data(); }
+  
+  /**
+   * @brief 获取直方图大小 / Get histogram size
+   * @return 直方图维度 / Histogram dimensions
+   */
+  constexpr std::size_t size() const { return HISTOGRAM_SIZE; }
+
+  /**
+   * @brief 计算与另一个描述子的欧氏距离 / Compute Euclidean distance to another descriptor
+   * @param other 另一个描述子 / Another descriptor
+   * @return 欧氏距离 / Euclidean distance
+   */
   DataType distance_impl(const dsc3d_signature_t& other) const
   {
     DataType dist = 0;
