2. VisionPro工程环境与项目组织

在复杂定位与测量系统中，工程能否稳定交付，往往不取决于单个工具的参数调得多好，而取决于项目组织是否清晰。VisionPro 提供两条主要开发路径：QuickBuild 面向快速搭建与现场调试，VisionPro SDK 面向代码化集成与批量部署。理解两者的工程结构差异，是后续做多相机、多工位、多产品型号管理的基础。

QuickBuild 的工程结构：Job、ToolGroup 与 Tool

QuickBuild 的工程文件通常保存为 .vpp，其内部是三层结构：Job（作业）→ ToolGroup（工具组）→ Tool（工具）。Job 是最外层容器，对应一次完整的检测任务，例如“上料定位+字符识别”；ToolGroup 是逻辑分组，通常按工位、相机或功能划分，例如“Cam1_定位”“Cam2_测量”；Tool 是实际执行图像处理的最小单元，如 CogPMAlignTool、CogFindLineTool、CogCaliperTool。

关键点在于：图像源、标定、通信、脚本都挂在 Job 或 ToolGroup 层级。一个 Job 可以绑定多个相机，但每个 ToolGroup 只能有一个输入图像源。若同一工位需要切换不同相机，应通过 Job 的 Image Source 切换或使用多个 ToolGroup 分别绑定。工具之间的数据传递通过 Inputs 与 Outputs 终端连接，例如将 PMAlign 的 Found 结果作为 Caliper 的 SearchRegion 输入，形成数据流依赖。

VisionPro SDK 的工程结构：引用、命名空间与对象模型

SDK 开发通常基于 .NET，在 Visual Studio 中新建 C# 项目后，需要引用 Cognex.VisionPro.dll、Cognex.VisionPro.Core.dll、Cognex.VisionPro.Blob.dll 等程序集。核心命名空间为 Cognex.VisionPro，工具类位于 Cognex.VisionPro.PMAlign、Cognex.VisionPro.Caliper 等子命名空间。

SDK 的对象模型与 QuickBuild 一一对应：CogJob 对应 Job，CogToolGroup 对应 ToolGroup，CogPMAlignTool 对应 PMAlign 工具。加载已有 vpp 的标准写法是：

using Cognex.VisionPro;
using Cognex.VisionPro.PMAlign;

CogJob job = (CogJob)CogSerializer.LoadObjectFromFile(@"D:\Projects\A100_Station1_Align.vpp");
CogToolGroup tg = job.ToolGroups["Cam1_PMA"] as CogToolGroup;
CogPMAlignTool pma = tg.Tools["PMA_01"] as CogPMAlignTool;

pma.InputImage = cogImage;
pma.Run();
double score = pma.Results[0].Score;
double angle = pma.Results[0].Rotation;

这里有一个容易踩坑的点：vpp 中的工具类型必须与 SDK 中强转的类型一致。若 vpp 里 PMA_01 实际是 CogPMAlignTool，而代码写成 as CogCaliperTool，结果会是 null，运行时报 NullReferenceException。建议在加载后先做类型检查，或统一用 CogToolBase 遍历。

脚本与外部程序集管理

QuickBuild 支持在 Job 或 ToolGroup 中嵌入 Advanced Script（C# 或 VB.NET），用于在工具运行前后做数据预处理、结果判定、通信触发。脚本编辑器会引用当前 vpp 已加载的程序集，但不会自动引用外部 DLL。若脚本中需要调用自定义算法库或第三方通信库，必须在脚本编辑器的 References 中手动添加，或把 DLL 放到 VisionPro 的安装目录下。

SDK 项目则通过 <Reference> 节点管理程序集。推荐做法是：把 Cognex 程序集的 Copy Local 设为 False，避免部署时把大量 DLL 复制到输出目录；把自定义算法库设为 True，并统一放在 libs 子目录。若使用 NuGet 管理，注意 VisionPro 的版本号与 NuGet 包版本必须匹配，否则会出现 Could not load file or assembly 错误。

作业配置与参数持久化

QuickBuild 中每个工具的参数（如 PMAlign 的 Angle 范围、AcceptThreshold、NumberToFind）都保存在 vpp 内。SDK 中若直接修改工具参数并调用 Run()，修改只存在于内存；要持久化必须调用 CogSerializer.SaveObjectToFile(job, path)。实际项目中常见做法是：vpp 作为“模板”只读加载，运行参数从数据库或 JSON 配置文件读取，运行时覆盖到工具对象上，这样换型时无需重新保存 vpp，也避免多线程写文件冲突。

下面这张图展示了 QuickBuild 与 SDK 两条路径在工程结构、脚本引用和外部程序集管理上的对应关系与数据流。

工程组织建议与常见问题

实际项目中，建议把“定位”和“测量”拆成不同 ToolGroup，而不是全部塞进一个组。原因是定位工具（PMAlign）通常需要全图搜索，测量工具（Caliper）只需要局部 ROI，拆开后可以分别设置图像源和运行条件，也便于单独调试。若一个 Job 内工具超过 20 个，建议按功能拆成多个 vpp，由 SDK 主程序依次加载，避免单个文件过大导致 QuickBuild 打开缓慢。

外部程序集管理还有一个高频问题：32 位与 64 位不匹配。VisionPro 9.x 之后以 64 位为主，若自定义 DLL 编译为 x86，加载时会报 BadImageFormatException。解决方法是把自定义库的目标平台改为 x64，或在 SDK 项目属性中确认 Platform target 与 VisionPro 安装版本一致。

最后，脚本与 SDK 代码不要重复实现同一逻辑。推荐把判定规则、通信协议、数据记录统一放在外部程序集或 SDK 层，QuickBuild 脚本只做轻量的参数覆盖和结果转发。这样换型时只需改配置，不必逐个打开 vpp 修改脚本，工程可维护性会明显提升。