简介本资源是HALCON官方深度学习工具包DeepLearningTool的完整集成环境面向工业机器视觉领域的算法工程师、自动化设备开发人员及高校研究者专为解决工业检测场景中深度学习模型开发周期长、部署门槛高、与传统视觉算法融合难等核心问题。资源共921个文件主体为416个QML界面组件支撑可视化标注与交互式训练、146个PNG/SVG图标与UI资源、84个DLL动态库含halcon.dll、halcondl.dll等核心运行时及72个HTML帮助文档整体包体达760.64MB结构完整覆盖开发、调试与部署全流程。已有955人学习下载适合需快速构建缺陷检测、字符识别、表面瑕疵分析等方案的实战团队。用户可直接调用预置模型开展PCB板检测、药瓶外观判别等典型任务复用bat注册脚本与多语言接口C/C#/Python并结合HALCON传统算子实现混合检测策略显著缩短从数据标注到产线集成的落地周期。1. HALCON-DeepLearningTool 是什么一个让工业视觉工程师跳过 PyTorch 底层、直接调参训模部署的闭环工具链你有没有遇到过这样的场景产线现场刚拍回一批金属件表面划痕样本客户催着三天内给出可运行的检测结果你打开 Jupyter从import torch开始写数据加载、自定义 Dataset、改 backbone、调 learning rate、写 inference pipeline……结果第 2 天发现标注不一致导致 mAP 卡在 0.62重标又得两天——而隔壁用 HALCON 的同事用 DeepLearningTool 导入图像标注文件夹点三下鼠标、选两个参数、点“训练”4 小时后模型已导出为.dl3文件拖进 HALCON Live Image Acquisition 窗口就实时跑起来了。这不是演示视频是某汽车零部件厂真实产线落地节奏。HALCON-DeepLearningTool 不是“另一个深度学习框架”它是 MVTec 官方把工业视觉场景里最痛的环节——数据准备、模型选择、训练收敛、部署集成——全封装进 GUI 脚本双模式的专用工具链。它不替代 PyTorch/TensorFlow但让你不必再为 OpenCV 读图路径报错、labelImg 标注格式错位、ONNX 转换 shape mismatch 或 HALCON HDevEngine 加载失败反复调试。适合两类人一是熟悉传统机器视觉Blob 分析、模板匹配但不想啃 DL 框架源码的工程师二是已会写 PyTorch 但被产线交付周期压得喘不过气、需要“确定性交付”的项目负责人。它解决的不是“能不能做”而是“能不能在客户验收前 48 小时稳定跑通”。2. 从零启动用 DeepLearningTool 在本地跑通第一个缺陷检测模型2.1 准备最小可运行数据集按 HALCON 要求组织图像与标注HALCON-DeepLearningTool 对数据结构有强约定不接受任意目录格式。必须严格按以下结构组织以表面划痕检测为例scratch/ ├── dataset/ │ ├── train/ │ │ ├── images/ # 所有训练图像.png/.jpg │ │ └── annotations/ # 对应标注文件.jsonHALCON 标注工具或转换脚本生成 │ ├── validation/ │ │ ├── images/ │ │ └── annotations/ │ └── test/ # 可选用于最终评估 │ ├── images/ │ └── annotations/注意annotations/下的.json文件不是 COCO 格式而是 HALCON 自定义的detection类型 JSON。每个文件名需与对应图像同名如img_001.png→img_001.json内容结构如下{ objects: [ { class: scratch, region: {type: rectangle1, row1: 120, column1: 85, row2: 150, column2: 210} } ] }region支持rectangle1轴对齐矩形、rectangle2旋转矩形、polygon三种类型class名必须全小写且无空格。常见翻车点用 labelImg 导出的 Pascal VOC XML 直接丢进去会报错——必须用 HALCON 自带的convert_annotation_format.hdev脚本转换或用 Python 脚本批量处理见 2.2。2.2 用 Python 脚本将 labelImg 标注转为 HALCON 兼容 JSON如果你已有 labelImg 生成的*.xml别手动改——写个 20 行脚本保命# xml_to_halcon_json.py import os import xml.etree.ElementTree as ET import json def xml_to_halcon_json(xml_path, output_dir): tree ET.parse(xml_path) root tree.getroot() img_name root.find(filename).text base_name os.path.splitext(img_name)[0] json_path os.path.join(output_dir, f{base_name}.json) objects [] for obj in root.findall(object): cls obj.find(name).text.lower().strip() bndbox obj.find(bndbox) x1 int(bndbox.find(xmin).text) y1 int(bndbox.find(ymin).text) x2 int(bndbox.find(xmax).text) y2 int(bndbox.find(ymax).text) objects.append({ class: cls, region: { type: rectangle1, row1: y1, column1: x1, row2: y2, column2: x2 } }) with open(json_path, w) as f: json.dump({objects: objects}, f, indent2) # 批量转换 xml_dir ./labelimg_xml json_dir ./dataset/train/annotations os.makedirs(json_dir, exist_okTrue) for xml_file in os.listdir(xml_dir): if xml_file.endswith(.xml): xml_to_halcon_json(os.path.join(xml_dir, xml_file), json_dir)逻辑说明脚本读取xmin/ymin/xmax/ymax直接映射为 HALCON 的row1/column1/row2/column2注意HALCON 坐标系 row行ycolumn列x与 OpenCV 一致。关键参数os.makedirs(..., exist_okTrue)防止目录不存在报错indent2保证 JSON 可读避免因格式问题被 DeepLearningTool 拒绝加载。2.3 启动 DeepLearningTool GUI三步完成训练配置启动工具Windows 下双击DeepLearningTool.exe默认安装路径C:\Program Files\MVTec\HALCON-23.11\tools\DeepLearningTool首次运行会提示选择 HALCON 安装路径指向你的 HALCON 主目录即可。新建项目点击File → New Project在弹窗中Project name: 输入scratch_detectionDataset path: 选择你准备好的scratch/dataset/目录Task type: 选择Object Detection非分类或分割Model architecture: 初始选YOLOv5s轻量、收敛快适合起步提示YOLOv5s是 HALCON 封装的预编译模型非原始 PyTorch 版本其 backbone 和 head 已针对 HALCON 运行时优化无需 GPU 驱动兼容性调试。配置训练参数关键点击Training标签页重点调整三项Batch size: 本地 CPU 训练设4有 NVIDIA GPU≥8GB 显存设16Number of epochs: 新项目建议50足够观察 loss 曲线是否收敛Learning rate: 默认0.001可用若 loss 下降慢可试0.002若震荡剧烈则降为0.0005点击Start Training工具自动执行数据增强默认启用 mosaic、HSV 调整、模型初始化、训练循环并实时绘制 loss 曲线。典型耗时CPU 模式约 3 小时50 epoch200 张图GPU 模式约 25 分钟。3. 模型导出与 HALCON 集成把.dl3文件变成产线可用的检测节点3.1 导出为 HALCON 原生模型格式.dl3训练完成后GUI 自动跳转到Export标签页。此处不做任何修改直接点击Export Model保存路径选scratch/model/scratch_detection.dl3。该文件是 HALCON 专有二进制格式包含模型权重已量化为 FP16适配 HALCON HDevEngine 推理引擎输入预处理参数归一化均值/标准差、resize 尺寸输出后处理逻辑NMS 阈值、置信度过滤类别映射表class: scratch→ ID0注意.dl3文件不可用 Python 直接加载也不兼容 ONNX Runtime。它的存在意义就是“开箱即用”于 HALCON 生态——这是设计哲学不是缺陷。3.2 在 HALCON HDevelop 中调用模型实现推理新建.hdev脚本粘贴以下代码逐行说明* 1. 加载模型 read_dl_model (scratch/model/scratch_detection.dl3, DLModelHandle) * 2. 读取待检测图像支持实时采集或文件 read_image (Image, scratch/test_images/img_001.png) * 3. 预处理自动匹配模型要求的尺寸与归一化 preprocess_dl_model (Image, ImageProcessed, DLModelHandle) * 4. 推理核心 apply_dl_model (ImageProcessed, DLResult, DLModelHandle) * 5. 解析结果获取检测框与置信度 get_dl_result_objects (DLResult, Objects, detection, [class_id,confidence], ResultValues) * 6. 可视化调试用 dev_display (Image) dev_set_color (red) dev_set_line_width (2) dev_display (Objects)逻辑说明read_dl_model加载.dl3返回句柄DLModelHandle后续所有操作基于此句柄preprocess_dl_model是关键黑匣子它自动读取模型内嵌的预处理参数如input_size[640,640]、mean[0.485,0.456,0.406]对输入Image执行 resize 归一化输出ImageProcessed你不需要手动写scale_image或rgb1_to_grayapply_dl_model执行推理输出DLResult非图像是 HALCON 内部结果结构体get_dl_result_objects解包结果detection指定任务类型[class_id,confidence]指定要提取的字段ResultValues返回二维数组每行对应一个检测框[class_id, confidence, row1, column1, row2, column2]最后三行是调试可视化产线部署时可删除。3.3 封装为可复用函数detect_scratch.hdev为便于产线调用将上述逻辑封装为函数HALCON 支持.hdev函数* detect_scratch.hdev * param: ImageIn (input) - 输入图像 * param: ObjectsOut (output) - 检测到的划痕区域 * param: ConfidenceOut (output) - 对应置信度数组 * param: ModelPath (input) - .dl3 模型路径 read_dl_model (ModelPath, DLModelHandle) preprocess_dl_model (ImageIn, ImageProcessed, DLModelHandle) apply_dl_model (ImageProcessed, DLResult, DLModelHandle) get_dl_result_objects (DLResult, ObjectsOut, detection, [class_id,confidence], ResultValues) * 提取置信度ResultValues 第二列 ConfidenceOut : ResultValues[*,1] * 清理句柄重要防内存泄漏 clear_dl_model (DLModelHandle)调用方式read_image (Image, path/to/camera/frame.png) run (detect_scratch.hdev, [Image, scratch/model/scratch_detection.dl3], [Objects, Confidence]) * 后续可对 Objects 做面积过滤、位置判断等传统视觉操作4. 避坑指南五个让新手卡住超过 2 小时的真实问题4.1 现象DeepLearningTool 启动时报错 “Failed to initialize CUDA context”原因工具检测到 NVIDIA GPU 但驱动版本过低 v515或 HALCON 安装时未勾选 CUDA 支持组件。解决方案 A推荐关闭 GPU 加速。在 DeepLearningTool GUI 的Settings → Hardware Acceleration中取消勾选Use GPU强制 CPU 模式方案 B升级显卡驱动至 v515并重新运行 HALCON 安装程序勾选CUDA Support组件需对应 CUDA Toolkit 版本HALCON-23.11 要求 CUDA 11.8。4.2 现象训练时 loss 曲线剧烈震荡50 epoch 后仍不收敛原因数据集中存在大量低对比度图像如反光金属表面或标注框严重偏离目标如框住背景而非划痕。解决用 HALCONinspect_dataset.hdev脚本检查数据质量它会自动计算每张图的灰度方差标记方差 10 的“低信息量图像”人工复查annotations/中置信度最低的 10 个样本的 JSON 文件确认row1/column1是否为负数labelImg 导出 bug 常见在 DeepLearningTool 的Data Augmentation设置中关闭Mosaic易导致小目标丢失开启CLAHE提升低对比度区域。4.3 现象导出.dl3后在 HDevelop 中apply_dl_model报错 “Invalid model handle”原因.dl3文件被 Windows 杀毒软件如 Defender误判为风险文件并静默隔离或文件权限被限制。解决检查scratch/model/目录下.dl3文件大小正常应 15MBYOLOv5s若仅几 KB 说明导出失败临时关闭 Defender 实时防护重新导出右键.dl3文件 →Properties→ 底部勾选Unblock若存在。4.4 现象推理结果Objects为空但图像明显有划痕原因模型输出的置信度过滤阈值过高默认 0.5或get_dl_result_objects未正确指定class_id。解决在get_dl_result_objects后添加调试语句get_dl_result_values (DLResult, num_detections, NumDetections) dev_disp_text (Num detections: NumDetections, window, 12, 12, black, [], [])若NumDetections 0但Objects为空说明后处理过滤了所有框降低置信度过滤在get_dl_result_objects前插入set_dl_model_param (DLModelHandle, detection_confidence_threshold, 0.3)4.5 现象部署到产线工控机后apply_dl_model执行极慢5s/帧原因工控机 CPU 无 AVX2 指令集支持如老款 Intel Celeron而 HALCON-23.11 默认编译为 AVX2 优化。解决在工控机上运行halconcpp_info.exe位于 HALCON 安装目录bin/x64查看CPU Features是否含AVX2若无需降级 HALCON 版本至 22.11支持 AVX或联系 MVTec 获取非 AVX2 编译版临时方案在 HDevelop 中启用多线程预处理set_system (thread_num, 4) * 启用 4 线程 preprocess_dl_model (Image, ImageProcessed, DLModelHandle)5. 进阶技巧用 HALCON 脚本动态控制模型行为绕过 GUI 限制DeepLearningTool GUI 固然方便但产线常需动态调整参数如不同批次产品切换检测灵敏度。此时需脱离 GUI用 HALCON 脚本直接操控模型句柄。核心是理解.dl3模型的可调参数体系——它比 PyTorch 的model.eval()更细粒度。5.1 动态修改 NMS 与置信度过滤阈值GUI 中设置的NMS IoU threshold默认 0.45和Detection confidence threshold默认 0.5并非固化在.dl3中而是运行时参数。通过set_dl_model_param可实时覆盖read_dl_model (scratch/model/scratch_detection.dl3, DLModelHandle) * 动态降低灵敏度减少误报 set_dl_model_param (DLModelHandle, nms_iou_threshold, 0.6) set_dl_model_param (DLModelHandle, detection_confidence_threshold, 0.7) * 动态提高灵敏度增加漏检但抓小缺陷 * set_dl_model_param (DLModelHandle, nms_iou_threshold, 0.3) * set_dl_model_param (DLModelHandle, detection_confidence_threshold, 0.4) preprocess_dl_model (Image, ImageProcessed, DLModelHandle) apply_dl_model (ImageProcessed, DLResult, DLModelHandle) get_dl_result_objects (DLResult, Objects, detection, [class_id,confidence], ResultValues)血泪经验nms_iou_threshold控制重叠框合并力度值越大越保守保留更多框detection_confidence_threshold是硬过滤低于此值的框直接丢弃。二者配合使用比单纯调模型学习率更有效。5.2 模型热切换同一程序中加载多个.dl3处理不同工位产线常有多个工位A 工位检划痕B 工位检凹坑无需重启程序用句柄管理实现秒切* 预加载两个模型 read_dl_model (model/scratch.dl3, DLModelScratch) read_dl_model (model/dent.dl3, DLModelDent) * 根据工位 ID 切换模型句柄 if (StationID A) DLModelHandle : DLModelScratch else DLModelHandle : DLModelDent endif preprocess_dl_model (Image, ImageProcessed, DLModelHandle) apply_dl_model (ImageProcessed, DLResult, DLModelHandle) * ... 后续解析关键点read_dl_model返回的句柄可长期持有apply_dl_model调用不改变句柄状态因此可安全复用。内存占用实测两个 YOLOv5s 模型共约 1.2GB RAM远低于 PyTorch 加载两个模型的 3.5GB。5.3 用 HALCON 内置评估脚本量化模型效果DeepLearningTool GUI 的评估仅显示 mAP0.5但产线需知道“在 0.8 置信度下召回率多少”。用 HALCON 自带evaluate_detection_model.hdev* 准备测试集images annotations TestImagesDir : scratch/dataset/test/images/ TestAnnoDir : scratch/dataset/test/annotations/ * 加载模型与测试数据 read_dl_model (scratch/model/scratch_detection.dl3, DLModelHandle) list_files (TestImagesDir, [files,follow_links], ImageFiles) tuple_regexp_select (ImageFiles, \\.(png|jpg|jpeg)$, ImageFiles) * 执行评估自动遍历所有图像对比预测与真值 evaluate_detection_model (ImageFiles, TestAnnoDir, DLModelHandle, \ EvaluationResult, [conf_threshold,iou_threshold], [0.5,0.5]) * 提取关键指标 get_dict_tuple (EvaluationResult, mAP, mAP) get_dict_tuple (EvaluationResult, precision, Precision) get_dict_tuple (EvaluationResult, recall, Recall) get_dict_tuple (EvaluationResult, f1_score, F1Score) dev_disp_text (mAP: mAP$.3f , Recall: Recall$.3f, window, 12, 12, black, [], [])参数说明[conf_threshold,iou_threshold]设为[0.5,0.5]即标准 COCO 评估协议若想看高置信度表现改为[0.7,0.5]。输出EvaluationResult是字典含per_class子项可查单类别指标。我习惯在每次模型迭代后用此脚本生成eval_report.csv用 Excel 画趋势图——比盯着 GUI 的单次 mAP 数字靠谱得多。它让我在第三次迭代时发现把mosaic关掉后小划痕召回率从 0.68 升到 0.89而 mAP 只降了 0.01果断放弃 GUI 默认增强。希望帮到你。本文还有配套的精品资源点击获取