4. CogTool与ToolGroup基础
在VisionPro中，单个CogTool（视觉工具）通常只完成一件明确的事：找边、定位、测量、读码或判断有无。但真实项目很少只靠一个工具完成，往往需要把多个工具按数据依赖串起来，形成一条“工具链”。ToolGroup（工具组）就是承载这条链的容器，它负责调度工具的执行顺序、传递中间结果，并把最终结果统一暴露给上层程序。理解CogTool与ToolGroup的关系，是后续用CogJob、CogToolBlock乃至脚本扩展的基础。
一、CogTool：最小功能单元
每个CogTool都是一个独立对象，具有输入端子（Input）、输出端子（Output）和一组可调参数。以最常用的CogPMAlignTool（模板匹配）为例，它的输入通常包括：待处理图像（InputImage）、搜索区域（Region）、模板（Pattern）以及角度/尺度搜索范围；输出则包括匹配分数（Score）、找到的位置（X、Y）、角度（Angle）以及匹配到的姿态（Pose）。这些输出不是“日志”，而是可以被其它工具直接引用的结构化数据。
VisionPro中工具之间不靠“全局变量”通信，而是靠端子连接。一个工具的输出端子可以连到另一个工具的输入端子，数据沿连接方向流动。这种显式连接让工具链的依赖关系一目了然，也便于单独调试某个工具。
二、输入输出连接：数据如何流动
连接的本质是“把上游工具的输出赋给下游工具的输入”。例如用CogPMAlignTool定位一个工件后，希望用CogFindCircleTool在定位后的坐标系里找圆，就需要把PMAlign的Outputs.Item("Pose")连接到FindCircle的Inputs.Item("Region")所依赖的坐标系上。VisionPro中常见的连接方式有三类：
- 图像连接：上游工具输出的图像（如CogImageConvertTool处理后的灰度图）接到下游工具的InputImage。
- 区域/坐标连接：把定位工具输出的Pose或Region接到测量工具的搜索区域，实现“跟着工件走”的柔性定位。
- 数值/结果连接：把上游的Score、Angle等数值接到下游工具的参数输入，或接到判断工具做阈值比较。
连接时要注意数据类型匹配：图像端子只能接图像，区域端子只能接区域，数值端子只能接数值。若类型不符，VisionPro会在连接时报错或标记为无效连接。此外，连接是有向的，不能形成环，否则工具组无法确定执行顺序。
三、ToolGroup的运行机制
ToolGroup不是简单地把工具“放进去”，它内部维护一张依赖图。运行时，ToolGroup会先做拓扑排序：没有未满足输入的工具先执行，执行完把输出写入端子，再触发依赖它的工具。因此工具在组内的排列顺序不等于执行顺序，真正决定顺序的是连接关系。如果两个工具之间没有连接，它们的执行先后不影响结果，ToolGroup可能并行或按内部顺序执行。
ToolGroup本身也有输入输出端子。外部（如CogJob或上层C#程序）通过ToolGroup的输入端子传入图像或参数，通过输出端子读取最终结果。这样ToolGroup就成为一个可复用的“黑盒”：内部工具链怎么改，只要对外端子不变，上层代码就不用动。
四、结果查看与调试
在VisionPro的QuickBuild环境中，运行ToolGroup后可以逐工具查看结果。常用手段包括：
- 图形叠加：在图像上显示匹配框、找到的圆、Blob区域，直观确认定位和测量是否正确。
- 结果表格：查看每个工具的输出端子值，例如PMAlign的Score是否达到0.8以上，FindCircle的半径是否在公差内。
- 单步运行：只运行到某个工具，检查它的输入是否已经正确传入，避免“上游没跑下游就报错”。
- 端子监视：在ToolGroup的输入输出端子上直接观察数据，确认外部传入的图像和参数是否符合预期。
五、一个可参考的工具链配置示例
假设要检测一个金属零件上的圆孔是否存在且位置正确，可以这样组织ToolGroup：
| 步骤 | 工具 | 关键输入 | 关键输出 | 判断依据 |
|---|---|---|---|---|
| 1 | CogPMAlignTool | InputImage、模板、搜索区域 | Pose、Score | Score ≥ 0.75 |
| 2 | CogFindCircleTool | InputImage、由Pose转换的搜索区域 | 圆心X/Y、半径 | 半径在 4.8~5.2 mm |
| 3 | CogBlobTool | InputImage、圆心附近的检测区域 | Blob面积、数量 | 面积 ≥ 50 像素且数量=1 |
配置时，第2步的搜索区域不要直接画在图像固定位置，而应通过Pose动态生成，这样零件轻微平移或旋转时圆孔仍能被找到。第3步的检测区域可以以第2步输出的圆心为中心，半径略大于圆孔，用于确认孔内没有多余异物。运行后，如果第1步Score只有0.4，说明模板或光照有问题，应先解决定位再往下看；如果第1步正常但第2步找不到圆，则检查搜索区域是否覆盖了实际圆孔位置。
六、常见问题与排查思路
工具组运行失败时，按“输入→连接→参数→输出”的顺序排查：先看上游工具是否成功执行并产生有效输出；再看连接是否指向了正确的端子；然后检查下游工具的搜索区域、阈值等参数是否合理；最后看输出值是否落在预期范围。若某个工具被标记为“未运行”，通常是因为它的某个必需输入没有连接或上游工具失败。ToolGroup的结果查看面板会显示每个工具的状态，善用它可以快速定位断点。
掌握CogTool与ToolGroup的这套机制后，后续无论是用CogToolBlock封装更复杂的逻辑，还是用CogJob管理多工位流程，本质上都是在同一套“工具—端子—连接—执行”模型上扩展。把本节的数据流关系理解清楚，后面的脚本和作业配置就会顺畅很多。