📚 课程目录第3章 Halcon环境搭建与3D算子初探

3. Halcon环境搭建与3D算子初探

说实话，很多初学者一上来就急着调算子，结果连3D模型都打不开。我见过太多人卡在这一步——环境没配好，后面全是白费功夫。这一章，咱们就把地基打牢。

3.1 安装Halcon 3D扩展包

Halcon从13版本开始，就把3D功能做成了独立扩展包。你装完基础版，还得单独装3D包。嗯，这里要注意版本匹配。

Halcon版本	3D扩展包名称	安装方式
Halcon 13~18	halcon-3d-.exe	独立安装包
Halcon 19~21	集成在完整安装包中	安装时勾选3D组件
Halcon 22+	默认包含3D模块	无需额外安装

我的习惯：装完第一时间打开HDevelop，在算子窗口输入 read_object_model_3d，如果能自动补全，说明3D包装好了。别等到写代码才发现缺东西。

3.2 常用3D数据读取算子：read_object_model_3d

这个算子，可以说是3D测量的入口。你拿到一个点云文件，第一件事就是用把它读进来。

read_object_model_3d( : : FileName, Scale, GenParamName, GenParamValue : ObjectModel3D, Status)

参数看着多，其实常用的就几个：

FileName：文件路径。支持.ply、.om3、.stl、.dxf等格式
Scale：缩放系数。默认1.0，单位是米。如果你数据是毫米，就填0.001
GenParamName/GenParamValue：通用参数对。比如设置是否自动三角化
ObjectModel3D：输出句柄。后面所有操作都靠它
Status：返回状态。0表示成功

我曾经踩过的坑：有一次客户给的数据是毫米单位，我忘了设Scale=0.001，结果所有测量结果都大了1000倍。排查了整整一下午……从那以后，我每次读文件都会先看一眼数据单位。

3.3 数据可视化：visualize_object_model_3d

读进来的数据长什么样？别猜，直接看。这个算子就是你的3D眼睛。

visualize_object_model_3d( : : WindowHandle, ObjectModel3D, CamParam, Pose, GenParamName, GenParamValue : )

几个关键参数：

WindowHandle：显示窗口句柄。用 open_window 创建
CamParam/Pose：相机参数和位姿。不填的话用默认视角
GenParamName：常用 'lut'（颜色映射）、'disp_pose'（显示坐标系）

实操小技巧：可视化时按住鼠标左键旋转，滚轮缩放，右键平移。我习惯先转一圈看看点云有没有空洞或离群点——这些在数据预处理阶段就要处理掉。

3.4 本章知识体系

下面这张图，帮你理清环境搭建到数据可视化的完整链路：

3.5 完整示例：从读取到显示

光说不练假把式。咱们直接跑一个完整流程：

* 打开显示窗口
open_window(0, 0, 800, 600, 0, 'visible', '', WindowHandle)

* 读取3D模型（PLY格式，单位毫米）
read_object_model_3d('point_cloud.ply', 0.001, [], [], ObjectModel3D, Status)

* 检查是否读取成功
if (Status != 0)
    disp_message(WindowHandle, '读取失败，请检查文件路径', 'window', 12, 12, 'red', 'false')
    return()
endif

* 设置可视化参数：使用彩色映射，显示坐标系
visualize_object_model_3d(WindowHandle, ObjectModel3D, [], [], \
    ['lut', 'disp_pose'], ['color1', 'true'])

* 释放模型（用完记得清理）
clear_object_model_3d(ObjectModel3D)

我建议：把这段代码存成模板。以后每次拿到新数据，先跑一遍看看效果。我自己的项目文件夹里，永远有一个 test_3d_loader.hdev，专门干这个事。

3.6 常见问题与避坑

文件打不开？先检查路径有没有中文。Halcon对中文路径支持不太好，我吃过这个亏
显示出来是空的？大概率是Scale设错了。点云范围太小或太大，超出可视范围
颜色不对？检查点云文件本身有没有颜色属性。没有的话用 'lut' 参数指定伪彩色
窗口卡死？点云太大（超过500万个点），建议先下采样再显示

特别提醒：visualize_object_model_3d 是阻塞函数。也就是说，它会一直占用窗口直到你关闭它。如果你要在循环里连续显示多个模型，记得用 set_display_param 控制刷新方式。

好了，环境搭好了，数据也能读能看了。下一步，咱们就可以开始真正的3D测量了。你想想看，有了这些基础，后面学标定和测量是不是心里就有底了？