2. Halcon3D 开发环境搭建
环境搭建这事儿，说难不难，说简单也容易踩坑。我见过不少新手，装完 Halcon 兴冲冲开始写代码，结果一调用 3D 算子就报错——许可证不对。所以这一章，咱们把环境彻底捋清楚。
2.1 Halcon 版本选择与安装
Halcon 目前主流的版本是 22.05、23.05 和 24.05。我个人建议，新项目直接用 23.05 或 24.05。为什么？因为 3D 模块在 22.05 之后做了大量优化，尤其是点云滤波和深度图转点云的效率，提升很明显。
| 版本 | 3D 模块特点 | 适用场景 |
|---|---|---|
| 22.05 | 基础 3D 算子完备，性能稳定 | 旧项目维护、兼容老设备 |
| 23.05 | 新增深度图预处理算子，点云配准加速 | 新项目首选，性价比高 |
| 24.05 | 支持 GPU 加速点云分割，内存管理优化 | 高精度、大批量点云处理 |
安装过程很简单，双击 exe 一路 Next 就行。但有一点要注意——安装路径不要有中文。我之前有个同事，装在了“D:\程序\Halcon”下面，结果调用 3D 可视化窗口时一直报错，折腾了半天才发现是路径问题。
2.2 3D 模块许可配置
这是最容易出问题的一步。Halcon 的许可证分很多种，只有带 "3D" 字样的许可才能调用 3D 算子。你想想看，如果拿一个基础版的 license 去跑 xyz_to_object_model_3d，系统直接给你弹个 "License not found"。
HALCON 3D— 基础 3D 处理HALCON 3D Visualization— 3D 可视化HALCON 3D Matching— 3D 匹配（高级功能）
配置步骤很简单：
- 将 license 文件复制到
%HALCONROOT%\license目录下 - 打开 HDevelop，菜单栏选择 Help → License Information
- 确认 "3D" 相关的模块状态为 Available
如果显示 "Expired" 或 "Not Available"，别慌。先检查系统时间是否正确，再确认 license 文件是否过期。我遇到过最奇葩的一次，是客户服务器时间同步错了，导致 license 提前 "过期"。
2.3 开发环境配置（HDevelop 与 VS）
实际项目中，我通常用 HDevelop 做算法原型验证，用 Visual Studio 做最终集成。两个环境各有侧重，咱们分开说。
2.3.1 HDevelop 配置
HDevelop 装完就能用，但有几个设置我建议你改一下：
- 字体放大： 默认字体太小，看 3D 点云坐标时眼睛累。菜单 Preferences → Editor → Font Size，调到 12 或 14。
- 自动补全： 勾选 Enable Auto Completion，写算子名时省很多事。
- 3D 可视化窗口： 默认是 OpenGL 模式，如果你的显卡比较老，改成 Software Renderer，否则可能黑屏。
info_3d_sensor 并执行。如果返回了传感器信息列表，说明 3D 模块已经正常工作了。
2.3.2 Visual Studio 集成
VS 集成稍微麻烦一点，但配好之后一劳永逸。步骤如下：
- 打开项目属性 → VC++ 目录
- 在 包含目录 中添加：
%HALCONROOT%\include\halconcpp - 在 库目录 中添加：
%HALCONROOT%\lib\x64-win64 - 在 链接器 → 输入 → 附加依赖项 中添加：
halconcpp.lib
嗯，这里要注意：64 位项目必须用 x64-win64 的库，别选成 x86sse2-win32。我见过有人配了半天连不上，结果发现是平台选错了。
配好之后，写个简单的测试代码：
// 测试 Halcon 3D 模块是否正常
#include "HalconCpp.h"
using namespace HalconCpp;
int main()
{
// 创建 3D 对象模型
HTuple hv_AcqHandle;
HObject ho_ObjectModel3D;
// 尝试打开 3D 传感器（模拟）
Open3dSensorModel("structured_light", "default", HTuple(), HTuple(), &hv_AcqHandle);
// 如果没报错，说明环境配置成功
std::cout << "3D 环境配置成功！" << std::endl;
Close3dSensorModel(hv_AcqHandle);
return 0;
}2.4 常用 3D 算子库概览
Halcon 的 3D 算子大概有 200 多个，但实际项目里常用的也就二三十个。我把它们分成四类，方便你快速上手：
| 类别 | 核心算子 | 作用 |
|---|---|---|
| 数据读取 | read_object_model_3dxyz_to_object_model_3d |
从文件或深度图创建 3D 模型 |
| 预处理 | sample_object_model_3dsmooth_object_model_3d |
点云降采样、平滑去噪 |
| 测量 | distance_object_model_3dfit_primitives_object_model_3d |
距离测量、拟合平面/球/圆柱 |
| 可视化 | visualize_object_model_3ddisp_object_model_3d |
3D 显示、交互操作 |
read_object_model_3d、visualize_object_model_3d、fit_primitives_object_model_3d 这三个算子玩熟。它们能覆盖 80% 的日常需求。
下面这张图，是我自己整理的 3D 算子调用流程。说白了，所有 3D 项目都逃不出这个框架：
你看，整个流程是单向的，但实际项目中经常需要 迭代。比如拟合平面后发现噪声太大，就得跳回预处理重新滤波。所以我把 "迭代优化" 的反馈箭头也画出来了。