📚 课程目录第2章 HALCON深度学习环境搭建与工具链

2. HALCON深度学习环境搭建与工具链

HALCON 的深度学习能力并不是一个独立安装的软件包，而是集成在 HALCON 主安装目录中的一组算子、预训练模型与运行时依赖。要在一台开发机上跑通第一个深度学习推理程序，需要同时打通四条链路：HALCON 本体与授权、深度学习算子库、HDevelop/Python 调用接口、GPU 计算环境。这四条链路任何一条不通，程序都会在加载模型或执行推理时失败。本节按“先装、再验、后调”的顺序，把每条链路的实际对象、关键操作和判断依据讲清楚。

一、HALCON 安装与授权配置

HALCON 的安装包通常以版本号命名，例如 HALCON 22.11 Progress 或 HALCON 24.11 Steady。安装时需要注意三个目录：程序目录（默认 C:\Program Files\MVTec\HALCON-24.11-Progress）、示例目录（examples）和许可证目录。深度学习相关的预训练模型、算子库文件都位于程序目录下的 dl 子目录中，安装时不要为了节省空间而取消该组件。

授权方面，HALCON 使用授权文件（license file）或加密狗。深度学习功能对授权有额外要求：普通 HALCON 授权可能只包含基础算子，而 read_dl_model、apply_dl_model 等算子需要包含深度学习模块的授权。判断授权是否覆盖深度学习，最直接的方法是在 HDevelop 中执行：

get_system ('dl_module_available', DlAvailable)
* 若 DlAvailable 为 'true'，说明当前授权支持深度学习

如果返回 false，需要检查环境变量 HALCONLICENSEFILE 是否指向正确的授权文件，或联系 MVTec 更新授权。授权文件路径中不要包含中文或空格，否则在部分版本中会导致加载失败。

二、深度学习算子库与模型文件

HALCON 的深度学习算子按任务类型组织，常见的有：分类（classify 系列）、目标检测（detect 系列）、语义分割（segment 系列）和异常检测（anomaly 系列）。这些算子本身是 HALCON 动态库的一部分，不需要单独安装，但每个任务都需要对应的预训练模型文件（.hdl 格式）。模型文件默认位于 dl 目录下，例如：

pretrained_dl_classifier_compact.hdl：轻量分类模型，适合快速验证；
pretrained_dl_detection_medium.hdl：中等规模检测模型；
pretrained_dl_segmentation_compact.hdl：轻量分割模型。

实际项目中，通常先用预训练模型跑通流程，再用自己的数据做迁移学习。加载模型时用 read_dl_model，加载后可用 get_dl_model_param 查看模型输入尺寸、类别数等参数。例如：

read_dl_model ('pretrained_dl_classifier_compact.hdl', DLModelHandle)
get_dl_model_param (DLModelHandle, 'image_width', Width)
get_dl_model_param (DLModelHandle, 'image_height', Height)
get_dl_model_param (DLModelHandle, 'class_ids', ClassIDs)

如果模型文件缺失或路径错误，read_dl_model 会直接报错，此时应检查 HALCONROOT 环境变量是否指向安装目录。

三、HDevelop 与 Python 接口

HDevelop 是 HALCON 自带的集成开发环境，适合快速验证算子逻辑。在 HDevelop 中调用深度学习算子时，建议先通过“程序 > 导入深度学习模型”向导生成模板代码，再手动调整参数。HDevelop 的优势是变量可视化：加载模型后，可以在变量窗口直接查看 DLModelHandle 的属性，推理结果也可以直接叠加显示在图像窗口上。

Python 接口通过 halcon 或 mvtec-halcon 包提供。安装时需注意 Python 版本与 HALCON 版本的匹配关系，例如 HALCON 24.11 通常支持 Python 3.8～3.11。安装命令示例：

pip install mvtec-halcon==24110

安装后，Python 中调用方式与 HDevelop 基本一致，但需要显式导入：

import halcon as ha
model = ha.read_dl_model('pretrained_dl_classifier_compact.hdl')
width = ha.get_dl_model_param(model, 'image_width')

Python 接口的一个常见问题是找不到 HALCON 动态库。此时需要设置 HALCONROOT 和 PATH（Windows）或 LD_LIBRARY_PATH（Linux），确保 Python 能加载 halcon.dll 或 libhalcon.so。

四、GPU 环境准备与验证

HALCON 深度学习推理默认使用 CPU，但训练和批量推理强烈建议使用 NVIDIA GPU。GPU 环境需要三样东西：NVIDIA 显卡驱动、CUDA Toolkit、cuDNN。HALCON 对版本有明确要求，例如 HALCON 24.11 通常要求 CUDA 11.8 或 12.x，cuDNN 8.x。版本不匹配时，set_dl_model_param 设置 'device' 为 'gpu' 会失败。

验证 GPU 是否可用，可以在 HDevelop 中执行：

query_available_dl_devices ('runtime', 'gpu', DLDevices)
* 若 DLDevices 为空，说明 GPU 环境未就绪

更完整的验证流程是：加载模型 → 设置设备为 GPU → 执行一次推理 → 检查耗时。下面这张图展示了从安装到验证的完整链路，以及每个环节的关键检查点。

图中把四条链路分成“安装授权—算子模型—接口—GPU”四个横向模块，再统一汇入底部的验证区。实际排障时，如果 read_dl_model 成功但 query_available_dl_devices 返回空，问题一定在 GPU 环境而非 HALCON 本体；如果 get_system('dl_module_available') 返回 false，则优先检查授权文件而不是重装软件。这种分层判断可以避免盲目重装。

建议在环境搭建完成后，用一张固定图片跑一次完整的“加载模型 → 预处理 → 推理 → 后处理”流程，并记录 CPU 与 GPU 下的耗时。这个基线数据在后续调参和排障时非常有用。

五、常见问题与判断依据

环境搭建阶段最常见的问题有三类。第一类是授权不覆盖深度学习，表现为 read_dl_model 报“operator not available”；第二类是模型文件路径错误，表现为文件找不到；第三类是 GPU 版本不匹配，表现为设置 device='gpu' 时抛出 CUDA 相关异常。三类问题的判断依据不同，处理方式也不同，建议按“先授权、再模型、后 GPU”的顺序逐一排除。

完成本节的环境搭建后，读者应该能够独立完成 HALCON 安装、授权确认、模型加载、Python 接口调用和 GPU 可用性验证。下一阶段将进入具体任务的数据准备与模型训练，届时本节建立的验证链路会直接用于判断训练环境是否正常。