3. 工具与工具组
在 VisionPro 中，单个工具（Tool）解决的是“一次具体检测”，而工具组（ToolGroup）解决的是“一类可重复使用的检测方案”。当你把一组工具按固定顺序连接、固定输入输出端子、固定运行模式封装成工具组后，它就可以像普通工具一样被反复调用、被嵌套、被参数化。理解工具组，本质上是理解 VisionPro 的复用边界在哪里。
工具组是什么：一个可参数化的检测子程序
工具组不是简单的“文件夹”。它拥有自己的输入端子（Inputs）、输出端子（Outputs）、内部工具链和运行模式。外部只能通过端子与它交互，内部工具的实现细节被封装起来。这与编程中的函数非常相似：端子是函数签名，内部工具链是函数体，运行模式决定它何时被调用。
一个典型的工具组结构如下：输入端子接收图像、区域（Region）、标定信息或阈值参数；内部依次执行定位、测量、判断工具；输出端子返回测量值、通过/失败标志、坐标结果。外部调用者不需要知道内部用了几个工具、如何连接，只需要知道端子含义。
创建工具组：从“选中一组工具”到“定义端子”
在 VisionPro QuickBuild 中创建工具组的典型操作路径是：先在 Job 中依次添加并连接好内部工具，确认单独运行时结果正确；然后框选这些工具，右键选择“Group”或使用工具栏的 Group 命令，VisionPro 会把它们收进一个 ToolGroup 节点。此时内部连接关系被保留，但外部看到的是一个整体。
接下来最关键的一步是定义端子。默认情况下，工具组会自动把内部工具中“未被内部连接消费”的输入暴露为输入端子，把“未被内部消费”的输出暴露为输出端子。但自动生成的端子往往命名混乱、粒度不合适，需要手动整理。例如内部有 CogPMAlignTool 的 InputImage，应将其重命名为 Image；内部 CogDistancePointLineTool 的 Distance 输出，应重命名为 MeasuredDistance，并明确单位是像素还是毫米。
MeasuredDistance 就知道含义，看到 CogDistancePointLineTool1.Output 则无法理解。输入输出端子的类型与映射
VisionPro 工具组的端子支持多种数据类型，常见的有：CogImage（图像）、CogRegion（区域）、double（数值）、bool（布尔）、CogTransform2DLinear（坐标变换）等。端子类型必须与内部工具对应参数的类型一致，否则无法建立映射。
端子映射的本质是“把外部端子绑定到内部某个工具的某个属性”。例如：
输入端子 Image → 内部 CogPMAlignTool1.InputImage
输入端子 SearchRegion → 内部 CogPMAlignTool1.SearchRegion
输入端子 Threshold → 内部 CogBlobTool1.Threshold
输出端子 Distance → 内部 CogDistancePointLineTool1.Distance
输出端子 Pass → 内部 CogBlobTool1.Results.Count > 0注意最后一行：输出端子不仅可以映射到某个工具的现成输出，还可以映射到一个由表达式计算出的结果。这使工具组能够对外提供“经过判断的结论”，而不仅是原始测量值。
运行模式：工具组何时被执行
工具组有三种常见运行模式，选择哪种取决于它在整个检测流程中的角色：
- 单次执行（Run Once）：工具组被调用一次就执行一次，适合离线分析或初始化阶段。
- 连续运行（Continuous）：只要上游有图像输入就持续执行，适合在线检测的主流程。
- 触发执行（Triggered）：由外部信号或上游工具的结果触发，适合与 PLC 或运动控制配合的场景。
运行模式影响的是工具组的调度行为，不影响内部工具链的连接关系。同一个工具组可以在不同 Job 中以不同模式被调用，这正是复用价值的体现。
嵌套规则：工具组里再放工具组
工具组可以嵌套工具组，形成层级结构。例如“定位工具组”负责输出坐标变换，“测量工具组”接收该变换后执行测量，“判断工具组”再接收测量结果输出 Pass/Fail。这种分层让复杂检测流程变得可管理。
但嵌套必须遵守几条规则：
- 禁止循环引用：A 组不能直接或间接包含 A 组自身，否则运行时会陷入死循环。
- 端子逐层映射：外层工具组的输入端子必须映射到内层工具组的输入端子，不能跳过层级直接映射到内层内部工具。
- 层级不宜过深：一般建议不超过 3 层。层级过深会导致端子映射链过长，调试时难以定位问题。
- 命名保持唯一：同一层级内工具组名称不能重复，否则端子引用会产生歧义。
一个可复用的工具组示例：引脚间距检测
假设需要检测连接器引脚间距，要求输出“间距值”和“是否合格”。可以这样组织工具组：
| 层级 | 对象 | 作用 |
|---|---|---|
| 输入端子 | Image | 接收待检测图像 |
| 输入端子 | PinRegion | 限定引脚搜索区域 |
| 输入端子 | MinGap / MaxGap | 合格间距上下限（示例：0.45mm / 0.55mm） |
| 内部工具 | CogFindLineTool ×2 | 分别找出相邻两引脚边缘 |
| 内部工具 | CogDistanceLineLineTool | 计算两边缘间距 |
| 内部工具 | CogBlobTool 或表达式 | 判断间距是否在 MinGap～MaxGap 之间 |
| 输出端子 | GapValue | 输出间距值（double） |
| 输出端子 | IsPass | 输出合格标志（bool） |
封装完成后，这个工具组可以在不同 Job 中反复使用。换一个产品型号时，只需要修改 MinGap 和 MaxGap 两个输入端子，内部工具链完全不用动。这就是工具组作为复用单元的核心价值：把“变化的部分”收敛到端子，把“不变的部分”封装在内部。
调试工具组的实用建议
工具组调试比单个工具麻烦，因为错误可能来自内部工具、端子映射或运行模式。建议按以下顺序排查：
- 先单独运行内部工具，确认每个工具自身结果正确。
- 再检查端子映射，确认外部输入确实传到了内部工具的对应属性。
- 然后检查运行模式，确认工具组被调用的时机和次数符合预期。
- 最后检查嵌套层级，确认没有循环引用或端子映射断链。
VisionPro 的 Job 编辑器支持在工具组内部设置断点并单步执行，这是定位嵌套问题最直接的手段。善用“逐层展开”的调试方式，可以避免在复杂嵌套中迷失方向。