📚 课程目录第2章 HALCON 3D数据表示与核心算子

2. HALCON 3D数据表示与核心算子

在HALCON的3D视觉工程中，选择正确的数据表示形式往往比选择算法更早决定项目成败。同一份三维场景，可以用点云、深度图、三角网格或XLD 3D轮廓来表达，但它们的存储方式、内存开销、可执行算子集合以及适用任务完全不同。本节围绕这四类核心数据结构，说明它们各自“是什么、适合什么、如何读写与显示、有哪些基本操作算子”，并给出可直接参考的算子调用示例。

四类3D数据结构的本质区别

点云（Point Cloud）是最原始的三维表示，本质是一组无序的3D坐标点集合，HALCON中以 ObjectModel3D 句柄承载。它不包含点与点之间的连接关系，因此对遮挡、噪声敏感，但保留了最完整的原始测量信息，适合做配准、拟合、测量和特征提取。点云可以携带法向量、强度、颜色等附加属性。

深度图（Depth Map / Range Image）是规则网格化的三维数据，每个像素存储一个深度值（Z），行列索引隐含了X、Y方向的位置。它天然与2D图像算子兼容，适合做滤波、边缘检测、区域分割，是结构光、ToF、激光轮廓仪最常见的原始输出形式。深度图的关键参数是像素当量（mm/pixel）和无效值标记。

三角网格（Mesh）在点云基础上增加了顶点间的三角面片连接，形成连续表面。它适合做表面重建、法向计算、体积计算和可视化渲染，但构建过程本身会引入近似误差。HALCON中网格同样以 ObjectModel3D 表示，通过三角面属性区分。

XLD 3D轮廓是HALCON特有的亚像素精度轮廓表示，由3D空间中的有序点序列构成，强调“边缘”而非“表面”。它适合做3D边缘提取、轮廓匹配、尺寸测量，精度可达亚像素级，数据量远小于点云。

读写算子：从文件到内存对象

点云与网格的读写统一走 ObjectModel3D 接口。读取PLY、STL、OM3等格式使用 read_object_model_3d，写出使用 write_object_model_3d。例如读取一个结构光扫描得到的PLY点云：

read_object_model_3d ('scan_part.ply', 'm', [], [], ObjectModel3D, Status)
* 查看点云属性
get_object_model_3d_params (ObjectModel3D, 'num_points', NumPoints)
get_object_model_3d_params (ObjectModel3D, 'has_normals', HasNormals)

深度图通常以TIFF或PNG保存，用 read_image 读入后，通过 xyz_to_object_model_3d 将X、Y、Z三通道图像或“深度图+标定参数”转换为点云。反向转换用 xyz_to_depth 或 project_object_model_3d 把点云投影回深度图。XLD 3D轮廓的读写则使用 read_contour_xld_dxf 与 write_contour_xld_dxf，DXF是工程交换中最通用的轮廓格式。

显示算子：三维可视化与交互

HALCON 3D显示的核心算子是 visualize_object_model_3d，它同时支持点云、网格和XLD 3D轮廓，可指定相机位姿、颜色、点大小、是否显示坐标系。典型调用如下：

create_pose (0, 0, 0.5, 0, 0, 0, 'Rp+T', 'gba', 'point', Pose)
visualize_object_model_3d (WindowHandle, ObjectModel3D, [], Pose, \
    ['color_0','point_size_0'], ['blue',2], [], [], [], PoseOut)

对于深度图，可直接用 dev_display 显示灰度图，再用 disp_xld 叠加提取出的3D轮廓。需要注意：深度图的灰度值范围通常远大于255，显示前应先用 scale_image 或 convert_image_type 做归一化，否则会看到全黑或全白。

基本操作算子：从原始数据到可用模型

点云的基本操作包括：select_points_object_model_3d 按坐标范围或属性筛选点；connection_object_model_3d 按连通性分割点云；smooth_object_model_3d 做平滑去噪；triangulate_object_model_3d 将点云三角化为网格。深度图的基本操作则更多复用2D算子：threshold 分割有效区域、select_gray 按灰度筛选、edges_sub_pix 提取亚像素边缘后再转为3D轮廓。

XLD 3D轮廓的基本操作包括：gen_contours_object_model_3d 从点云或网格提取轮廓；fit_line_contour_xld_3d 对3D轮廓做直线拟合；fit_circle_contour_xld_3d 做圆拟合；distance_contours_xld_3d 计算两条3D轮廓间的距离。这些算子是3D尺寸测量的基础。

选型建议：如果任务是“测一个孔的位置和直径”，优先用XLD 3D轮廓，数据量小、精度高；如果任务是“重建整个零件表面”，用网格；如果任务是“配准两个视角的扫描数据”，用点云；如果任务是“在深度图上做区域分割”，直接用深度图。

一个完整的转换与操作示例

假设我们有一张已标定的深度图 DepthImage，想提取其中的平面区域并转为点云做拟合。典型流程如下：

* 1. 深度图转点云
xyz_to_object_model_3d (DepthImage, CamParam, ObjectModel3D)

* 2. 按Z范围筛选有效点
select_points_object_model_3d (ObjectModel3D, 'point_coord_z', 0.1, 0.8, ObjectModel3DSelected)

* 3. 三角化并平滑
triangulate_object_model_3d (ObjectModel3DSelected, 'greedy', [], [], Mesh, Status)
smooth_object_model_3d (Mesh, 'mls', 5, SmoothedMesh)

* 4. 提取3D轮廓
gen_contours_object_model_3d (SmoothedMesh, Contours3D)

* 5. 显示
visualize_object_model_3d (WindowHandle, SmoothedMesh, [], [], [], [], [], [], [], PoseOut)

这段代码覆盖了“深度图→点云→筛选→网格→轮廓→显示”的完整链路，是HALCON 3D工程中最常见的处理骨架。实际项目中，参数如Z范围、平滑窗口、三角化方法需要根据工件尺寸和噪声水平调整，不能直接照搬。

常见陷阱：深度图中的无效值（如0或NaN）如果直接参与 xyz_to_object_model_3d，会在原点附近产生大量虚假点。正确做法是先用 threshold 或 select_gray 生成有效区域掩膜，再只对掩膜内像素做转换。

数据结构选择速查

数据结构	典型来源	优势	局限	首选任务
点云	激光扫描、结构光	信息完整、无拓扑假设	无序、噪声敏感	配准、拟合、测量
深度图	ToF、结构光、轮廓仪	规则网格、2D算子兼容	受遮挡和无效值影响	滤波、分割、边缘检测
三角网格	点云三角化	连续表面、法向稳定	构建有近似误差	重建、体积、渲染
XLD 3D轮廓	边缘提取、CAD导入	亚像素精度、数据量小	只表达边缘不表达表面	尺寸测量、轮廓匹配

掌握这四类数据结构的读写、显示与基本操作算子，是后续标定、配准、测量和缺陷检测的基础。实际工程中，往往需要在同一任务中多次转换数据形式，例如“深度图→点云→网格→XLD轮廓”，每一步转换都会引入误差，因此应尽量在满足任务要求的前提下减少转换次数，并优先使用精度更高的表示形式完成关键测量。