2. VisionPro开发环境与快速上手

VisionPro 的工程落地通常有两条并行路径：一条是面向快速验证与现场调试的图形化环境 QuickBuild，另一条是面向产线软件集成的 VisionPro SDK（.NET 程序集）。理解这两者的分工，是后续所有读码与追溯功能开发的前提。QuickBuild 负责“把作业跑通、把参数调对”，SDK 负责“把跑通的作业嵌入到上位机、PLC 交互与 MES 上报流程中”。本节围绕安装配置、界面组成、工具链组织，以及第一个读码作业的创建与运行展开。

一、安装与授权配置

VisionPro 的安装包通常包含运行时（VisionPro Runtime）、QuickBuild、SDK 程序集以及相机驱动组件。安装时需要注意三点：第一，安装路径不要包含中文与空格，否则部分工具在加载自定义脚本或引用外部 DLL 时容易报路径异常；第二，安装完成后需通过 Cognex 授权工具（如 VisionPro License Manager）导入授权文件，未授权状态下 QuickBuild 可以打开但部分工具会以演示模式运行，读码结果可能被限制；第三，若使用 GigE 相机，需确认网卡已启用巨帧（Jumbo Frame，一般设为 9014 字节）并关闭网卡的节能与中断节流，否则会出现丢帧或连接超时。

SDK 侧需要在 Visual Studio 中引用 Cognex.VisionPro 相关程序集，典型包括 Cognex.VisionPro.dll、Cognex.VisionPro.Core.dll、Cognex.VisionPro.ID.dll（读码工具所在程序集）以及 Cognex.VisionPro.Blob、Cognex.VisionPro.Caliper 等按需引用。目标框架建议与安装版本匹配，例如 VisionPro 9.x 常用 .NET Framework 4.7.2 及以上。引用后需将平台目标设为 x64，因为 VisionPro 运行时为 64 位，AnyCPU 在部分机器上会触发 BadImageFormatException。

二、QuickBuild 界面组成

QuickBuild 的主界面可以理解为四个功能区：左侧的 Job 树（作业结构树，显示工具、输入图像、结果输出与脚本节点）；中部的 图像显示窗口（显示当前工具处理的图像、ROI 区域与图形标注）；右侧的 工具属性面板（编辑选中工具的参数，如码制、极性、超时、搜索区域）；底部的 结果与终端窗口（显示工具运行状态、读码字符串、评分、耗时与错误信息）。作业（Job）是 QuickBuild 的最小可运行单元，一个 Job 内可以串联多个工具，工具之间通过输入输出端子连接。

三、工具链组织方式

VisionPro 的工具链不是简单的线性列表，而是以“数据端子”连接的有向结构。每个工具都有输入端子（如图像输入、区域输入）和输出端子（如图像输出、结果输出）。读码作业的典型组织是：图像采集工具（CogAcqFifoTool 或 CogImageFileTool）输出图像 → 图像预处理工具（如 CogIPOneImageTool 做灰度拉伸）→ 定位工具（CogPMAlignTool 或 CogFindLineTool）输出位姿 → 读码工具（CogIDTool）在定位结果上建立搜索区域 → 结果输出与脚本节点。定位工具的作用是把读码区域“跟随”到产品实际位置，避免产品偏移导致读码失败。

四、创建并运行第一个读码作业

下面以“读取产品上的 DataMatrix 码并输出字符串”为例，说明从零创建作业的关键操作。示例参数均为教学示例，实际值需根据现场相机、镜头与码质量调整。

1. 新建 Job 并添加图像源。在 QuickBuild 中新建 Job，从工具箱拖入 CogAcqFifoTool（若用相机）或 CogImageFileTool（若用离线图片）。若用相机，在属性面板中选择相机、设置曝光时间（示例 8000 μs）与增益（示例 1.0），点击“实时采集”确认图像清晰、码区域对比度足够。
2. 添加预处理。拖入 CogIPOneImageTool，将输入图像连接到采集工具输出。选择灰度拉伸（Gain/Offset 或 Histogram Equalize），使码的黑白模块边界更锐利。示例：将灰度范围从 40–180 拉伸到 0–255。
3. 添加定位工具。拖入 CogPMAlignTool，训练一个包含码区域附近特征的模板（如产品边缘或定位标记）。运行后查看位姿输出（X、Y、角度），确认定位稳定。定位的作用是让读码区域随产品位置变化，而不是固定在图像坐标上。
4. 添加读码工具。拖入 CogIDTool，将图像输入连接到预处理输出。在属性面板中选择码制为 DataMatrix，设置极性为“黑底白码”（示例），并将搜索区域设置为由 CogPMAlignTool 的位姿动态建立。设置超时 200 ms、评分阈值 0.6（示例）。
5. 连接结果输出。将 CogIDTool 的结果端子连接到 Job 的结果输出节点，或添加脚本节点读取 CogIDTool.Results(0).DecodedString。运行 Job，在底部结果窗口查看读码字符串、评分与耗时。

运行后如何判断作业是否可用？主要看三个指标：一是读码字符串是否与预期一致；二是评分（Score）是否稳定高于阈值，若长期在阈值附近波动，说明图像质量或码质量不足，需要调整曝光、光源或预处理；三是单次耗时是否满足产线节拍，例如节拍要求 300 ms，则读码加定位的总耗时需留出余量。若出现读码失败，优先检查搜索区域是否覆盖码、极性设置是否正确、码制是否选对，再检查图像是否过曝或欠曝。

五、从 QuickBuild 过渡到 SDK

当作业在 QuickBuild 中稳定运行后，SDK 集成的基本流程是：加载 .vpp 作业文件 → 传入图像（来自相机或文件）→ 运行作业 → 读取结果。下面是一段最小示例代码，用于说明调用关系：

using Cognex.VisionPro;
using Cognex.VisionPro.ID;

// 1. 加载 QuickBuild 保存的作业
CogJob job = CogSerializer.LoadObjectFromFile(@"D:\Jobs\ReadDM.vpp") as CogJob;

// 2. 获取读码工具（按工具名或索引）
CogIDTool idTool = job.VisionTool as CogIDTool;

// 3. 传入图像并运行
idTool.InputImage = cogImage;   // cogImage 来自相机或文件
idTool.Run();

// 4. 读取结果
if (idTool.Results != null && idTool.Results.Count > 0)
{
    string code = idTool.Results[0].DecodedString;
    double score = idTool.Results[0].Score;
    // 将 code 与 score 上报给上位机或 MES
}

这段代码的关键点在于：作业文件承载了工具链与参数，SDK 只负责驱动与取结果。实际集成时还需处理异常（如未找到码时 Results 为空）、超时控制以及多相机多工位的作业管理。建议在 SDK 侧对读码结果做二次校验，例如字符串长度、前缀规则或校验位，再决定是否上报，避免把误读结果送入追溯系统。

完成本节后，应能够独立完成 VisionPro 的安装授权、在 QuickBuild 中搭建一条“采集—预处理—定位—读码—输出”的工具链，并理解 SDK 加载作业、传入图像、读取结果的基本调用方式。这是后续多码读取、追溯数据上报与产线集成的起点。