Halcon例程detect_3d_defects_on_battery_surface.hdev解析

该例程是Halcon 官方经典的 3D 点云缺陷检测例程，专门检测圆柱电池展开表面的凹坑、凸起、破损等 3D 缺陷，完全适配深度图 / 点云凹坑检测。

一、工作原理

工作原理的核心思想：平滑对比法（最通用的 3D 凹坑检测算法），其工作步骤如下：

1）输入：电池 3D 点云（由深度图转换而来）

2）对正常表面做大面积平滑 → 得到 "理想基准面"

3）计算原始点云 vs 平滑点云的距离

4）距离超过阈值 = 缺陷（凹坑 / 凸起）

5）聚类 + 过滤噪点 → 输出最终缺陷

二、代码解析

头部注释 + 初始化

功能注释：：检测圆柱电池展开表面的3D缺陷（凹坑、凸起、破损）

* 步骤1：传感器XYZ映射平滑3D点云

* 步骤2：缺陷 = 平滑点云与原始点云距离过大的连通区域

dev_update_off () //关闭实时刷新，加速运行

参数设置

说明：凹坑检测：距离为负；凸起检测：距离为正。

DefectNumPointsMin := 150 //最小缺陷点数：缺陷必须 ≥150 个点，过滤小噪点

SmoothingMaskSize := 50 //平滑模板大小：50x50（越大，表面越平滑，越能突出缺陷）

MaxDistanceSmoothedToOriginal := 2.5e-05 //平滑与原始点云最大允许距离：2.5e-5 米 = 0.025 mm ＞这个值判定为缺陷

MaxDistanceConnection := 2e-04 //3D点聚类最大距离：0.2 mm,小于此距离的点 → 归为同一个缺陷

窗口初始化 + 3D 视角设置

代码如下，比较简单，不做说明。

bash 复制代码

dev_close_window ()
dev_open_window (0, 0, 1024, 768, 'black', WindowHandle)
set_display_font (WindowHandle, 16, 'mono', 'true', 'false')

* 3D操作提示
Instructions[0] := 'Rotate: Left button'
Instructions[1] := 'Zoom:   Shift + left button'
Instructions[2] := 'Move:   Ctrl  + left button'

* 初始3D姿态
create_pose (0.0, 0.0, 1.5, 0.0, -5.0, 0.0, 'Rp+T', 'gba', 'point', PoseOutInit)

循环处理 4 组电池数据

for Index := 0 to 3 by 1 //读取3D点云模型

read_object_model_3d ( 'battery_surface/battery_surface_' + Index$'02d', 'm', \[\], \[\], ObjectModel3D, Status )

显示原始点云（按 Z 值着色）

visualize_object_model_3d ( WindowHandle, ObjectModel3D, \[\], PoseOutInit, $'color_attrib', 'color'$ , $'coord_z', 'yellow'$ , Title, \[\], Instructions, PoseOut )

3D 点云平滑（生成基准面）

工作原理：

平滑 = 模拟理想无缺陷表面

缺陷区域因为凹凸不平，平滑后会被 "拉平"

原始 vs 平滑 → 差值就是缺陷高度

bash 复制代码

smooth_object_model_3d ( ObjectModel3D, // 输入原始点云 
'xyz_mapping', //平滑方法：相机像素网格平滑（最适合深度图） 
['mask_width','mask_height'], [SmoothingMaskSize,SmoothingMaskSize], //50x50平滑窗口 ObjectModel3DSmoothed //输出平滑后的点云 )

7.计算点到点距离

distance_object_model_3d ( ObjectModel3D, // 原始点云

ObjectModel3DSmoothed, //平滑点云

\[\], 0, 'distance_to', 'points' )

该函数功能是计算每个 3D 点到平滑表面的距离，并把距离值存在点云属性&distance中。

阈值筛选缺陷点

select_points_object_model_3d ( ObjectModel3D, '&distance', // 使用距离属性 MaxDistanceSmoothedToOriginal, 'max',//大于阈值 = 缺陷

ObjectModel3DThresholded )

说明：如果只检测凹坑，参数可修改如下：

select_points_object_model_3d ( ObjectModel3D,

'&distance',

-MaxDistanceSmoothedToOriginal, //负值 = 凹坑

'min', // 小于负阈值 = 深凹坑

ObjectModel3DThresholded )

9.聚类缺陷 + 过滤噪点

* 3D点聚类：距离近的点合成一个缺陷

connection_object_model_3d ( ObjectModel3DThresholded, 'distance_3d', MaxDistanceConnection, ObjectModel3DConnected )

* 过滤：只保留点数足够多的真实缺陷（去掉噪点）

select_object_model_3d ( ObjectModel3DConnected, 'num_points', 'and', DefectNumPointsMin, 'max', ObjectModel3DDefect )

结果显示 OK / NOK

cpp 复制代码

if (|ObjectModel3DDefect| > 0)
    Title[0] := 'Status = NOK'
    Title[1] := '发现缺陷'
else
    Title[0] := 'Status = OK'
    Title[1] := '无缺陷'
endif

* 3D显示缺陷（红色）+ 原始表面（黄色）
visualize_object_model_3d (
    WindowHandle,
    [ObjectModel3DDefect, ObjectModel3D],
    [], PoseOut,
    VisParamNames, VisParamValues,
    Title, Labels, Instructions, PoseOut
)

三、凹坑检测算子和参数总结

1)算子

算子	功能	凹坑检测用途
`smooth_object_model_3d`	点云平滑，生成基准面	模拟无缺陷表面
`distance_object_model_3d`	计算点云距离	得到凹凸高度差
`select_points_object_model_3d`	按距离筛选缺陷点	提取凹坑点
`connection_object_model_3d`	3D 点聚类	把零散点合成缺陷
`select_object_model_3d`	过滤缺陷大小	去噪，保留真实缺陷

2)参数

参数	凹坑推荐值	说明
SmoothingMaskSize	30~80	越大越能检测小凹坑
MaxDistance	0.01~0.1 mm	凹坑深度阈值
DefectNumPointsMin	50~300	过滤噪点
MaxDistanceConnection	0.1~0.5 mm	缺陷聚类距离