WoodAlgo/Algo/DetectHole/examples

孔洞检测示例程序

这个目录包含使用 HoleDetectionLib 库的示例程序。

目录结构

• hole_detection_demo/ - 基础孔洞检测示例
  • sample_hole_detection.cpp - 主示例程序
  • CMakeLists.txt - CMake 配置文件
• visualization_demo/ - 可视化演示程序
  • VisualizationDemo.cpp - 可视化示例程序
  • CMakeLists.txt - CMake 配置文件
• CMakeLists.txt - 主CMake配置文件
• build.sh - 编译脚本
• README.md - 本文件

快速开始

1. 确保主库已编译

在运行示例之前，需要先编译主库：

cd ..
make          # 或 make debug

2. 编译示例程序

cd examples
./build.sh          # Release 模式
# 或
./build.sh debug    # Debug 模式

3. 运行示例

cd build

# 运行基础孔洞检测示例
# 使用默认数据文件（data/single_hole.xyz）
./hole_detection_demo/sample_hole_detection

# 指定数据文件
./hole_detection_demo/sample_hole_detection ../../data/single_hole.xyz
./hole_detection_demo/sample_hole_detection ../../data/multiple_holes.xyz
./hole_detection_demo/sample_hole_detection ../../data/large_deep_hole.xyz

# 运行可视化演示程序
./visualization_demo/visualization_demo ../../data/single_hole.xyz --interactive
./visualization_demo/visualization_demo ../../data/multiple_holes.xyz --batch --output-dir ./results

示例程序功能

1. 基础孔洞检测示例 (hole_detection_demo)

sample_hole_detection.cpp 演示了以下功能：

1. 加载点云数据 - 从 .xyz 文件加载点云
2. 配置参数 - 设置检测和过滤参数
3. 执行检测 - 调用 DetectMultipleHoles() API
4. 显示结果 - 打印检测到的孔洞信息
5. 内存管理 - 正确释放结果内存

2. 可视化演示程序 (visualization_demo)

VisualizationDemo.cpp 提供了完整的可视化功能：

1. 交互式可视化 - 实时查看检测过程和结果
2. 批处理模式 - 自动保存可视化截图
3. 批量处理 - 处理目录中的所有点云文件
4. 调试回调 - 可视化每个检测步骤
5. 多格式支持 - 支持 .xyz, .txt, .ply, .pcd 格式

数据文件格式

示例程序支持以下格式的 .xyz 文件：

LineNum:50
DataType: 0
Line_0_1000_50
{ x, y, z }-{ 0.0, 0.0 }-{ 0.0, 0.0 }
{ x, y, z }-{ 0.0, 0.0 }-{ 0.0, 0.0 }
...

其中：

• 第一行：LineNum:行数
• 第二行：DataType: 0
• 第三行：Line_起始_结束_列数
• 后续行：点云数据，格式为 { x, y, z }-{ 0.0, 0.0 }-{ 0.0, 0.0 }

可用的测试数据

../data/ 目录包含以下测试数据：

• single_hole.xyz - 单个孔洞（152KB）
• multiple_holes.xyz - 多个孔洞（388KB）
• large_deep_hole.xyz - 大型深孔（606KB）
• small_hole.xyz - 小孔洞（55KB）
• 2026-02-04-*.txt - 激光扫描数据（多个文件）

输出示例

========================================
孔洞检测示例程序
========================================

数据文件: data/single_hole.xyz

点云尺寸: 50 x 1000 = 50000 点
成功加载 50000 个点

检测参数:
  半径范围: 5 - 50 mm
  最小深度: 1 mm
  聚类距离: 5 mm

开始检测...
检测完成！

========================================
检测结果
========================================
检测到的孔洞数量: 1
候选孔洞总数: 1
过滤掉的孔洞: 0

孔洞 #1:
  中心点: (500.5, 25.3, -10.2)
  法向量: (0.0, 0.0, 1.0)
  半径: 15.5 mm
  深度: 10.2 mm
  离心率: 0.15
  半径方差: 0.8 mm
  角度跨度: 355.2 度
  质量分数: 0.85

========================================
程序结束
========================================

自定义参数

你可以修改 sample_hole_detection.cpp 中的参数来调整检测行为：

检测参数（SHoleDetectionParams）

detectionParams.minRadius = 5.0f;          // 最小半径
detectionParams.maxRadius = 50.0f;         // 最大半径
detectionParams.minPitDepth = 1.0f;        // 最小深度
detectionParams.clusterEps = 5.0f;         // 聚类距离
detectionParams.clusterMinPoints = 5;      // 最小聚类点数

过滤参数（SHoleFilterParams）

filterParams.minHoleRadius = 3.0f;         // 最小孔洞半径
filterParams.maxHoleRadius = 100.0f;       // 最大孔洞半径
filterParams.maxEccentricity = 0.9f;       // 最大离心率
filterParams.minQualityScore = 0.3f;       // 最小质量分数

手动编译

如果不想使用 build.sh，可以手动编译：

使用 CMake

mkdir -p build
cd build
cmake .. -DCMAKE_BUILD_TYPE=Release
cmake --build .

使用 g++ 直接编译

# Release 模式
g++ -I../Export/include \
    sample_hole_detection.cpp \
    -L../Export/arm/release \
    -lHoleDetectionLib \
    -Wl,-rpath,../Export/arm/release \
    -o sample_hole_detection

# Debug 模式
g++ -g \
    -I../Export/include \
    sample_hole_detection.cpp \
    -L../Export/arm/debug \
    -lHoleDetectionLib \
    -Wl,-rpath,../Export/arm/debug \
    -o sample_hole_detection

故障排除

找不到库文件

如果运行时提示找不到 libHoleDetectionLib.so，设置 LD_LIBRARY_PATH：

# Release 模式
export LD_LIBRARY_PATH=../Export/arm/release:$LD_LIBRARY_PATH

# Debug 模式
export LD_LIBRARY_PATH=../Export/arm/debug:$LD_LIBRARY_PATH

编译错误

确保主库已经编译：

cd ..
make
cd examples
./build.sh

数据文件错误

确保数据文件路径正确：

ls -lh ../data/single_hole.xyz

更多示例

查看源代码 sample_hole_detection.cpp 了解：

• 如何加载不同格式的点云数据
• 如何使用调试回调函数
• 如何处理检测结果
• 如何进行错误处理

相关文档

• BUILD.md - 编译主库
• USAGE.md - 库使用指南
• API 文档 - API 参考