Find Image（查找图像）
等待已保存的模板图像出现在屏幕上，然后按是否找到分支。
Find Image 是视觉自动化的主力。多数流程就是一串"找这个，然后对它动作"。
用途
在活屏幕上查找一个或多个截取的模板图像，并报告最佳匹配在哪。
用来等按钮或图标出现、确认界面已加载，或把匹配坐标喂给一个 Click。它不断重查新截图，直到匹配或超时——所以它兼任智能等待。
何时用
- 等按钮、图标或界面出现。
- 通过检测本应产生的界面来确认动作成功。
- 定位位置会移动的东西，好让 Click 点它。
- 用 branch-by-template 区分多个可能界面。
何时不用
- 读一个值——数字、计时、坐标。用 Read Text。
- 检测没有明显图标的状态——条清空、界面渐变。用 Check Region。
- 做固定延时。 只需暂停，Wait 更清楚。
前提
至少一个截取的模板素材。模板从 Live Preview 截取并随流程保存。
如何运行
即便超时很小，至少一次抓取与匹配总会运行。
超时未匹配时，节点路由 Failure，但 status 是 success。检测运行了；图像只是不在。
这意味着一次未找到永不触发重试策略、永不计入连续失败护栏。见status 与 route。
设置
| 设置 | 类型 | 范围 | 默认 | 作用 |
|---|---|---|---|---|
| Template(s) | 素材引用 | 1–16 | — | 要找的截取图像 |
| Template name | string | ≤ 120 字符 | — | 截图的友好标签 |
| Threshold | number | 0.5–0.99 | 流程默认（0.88） | 最低匹配置信度；越高越严 |
| Search region | 矩形 | 屏幕百分比 | 整屏 | 限定搜索——更快、避免误命中 |
| Timeout | integer | 1–120000 ms | 流程默认 | 找多久 |
| Poll interval | integer | 50–120000 ms | 流程默认（250） | 多久重抓一次 |
| Multi-template | boolean | — | false | 匹配一组模板；最高分胜 |
| Branch by template | boolean | — | false | 每模板一端口而非一个 Success |
| Colour mode | 选择 | color、grayscale | color | 按颜色或灰度匹配 |
| Scale mode | object | none 或 multiScale | none | 在一段尺度上匹配 |
| Ambiguity mode | 选择 | requireUnique、best、all | best | 多处匹配时怎么办 |
| Min best/second-best delta | number | ≥ 0 | — | 胜者需比亚军清晰多少，用于 requireUnique |
| Max matches | integer | 1–100 | — | all 模式的上限 |
| Save results to variables | 列表 | ≤ 16 | — | 把输出字段绑到变量名 |
Threshold
影响最大的设置。
- 0.88 是好的起点，也是产品默认。
- 0.95+ 常错过有效匹配——差一像素或轻微抗锯齿差异就掉分。
- 低于 0.75 开始匹配噪声。
靠测试而非猜来调：用 Test Node 看模板达到的真实置信度。
搜索区域
设搜索区域是现成最便宜的提速：匹配器在裁剪上工作而非整帧。它还防屏幕别处的误报。
大致知道东西在哪就限定它。
Multi-template 与 branch-by-template
两个可叠加的独立开关：
| 配置 | 行为 | 端口 |
|---|---|---|
| 单模板 | 匹配一张图 | success / failure |
| Multi-template 开 | 匹配一组，保留最高分 | success / failure |
| Multi-template + Branch by template | 匹配一组，按哪个匹配来分流 | 每模板一端口 + notFound |
Branch-by-template 是在一个节点里处理"此界面可能处于四种状态之一"的方式。模板 id 就是端口键，所以重命名模板保留分支；删除模板移除端口。
Save results to variables
把输出字段绑到后续节点可用的变量名：
centerX、centerY、confidence、matched、matchedTemplate、匹配的 x / y / width / height、scale
变量在成功匹配时自动声明。
要点击你找到的东西，根本不需要变量——把 Click 的 coordinate source 设为这个 Find Image 节点。要做算术或记日志才用变量。
歧义策略
| 模式 | 含义 |
|---|---|
best | 取最高分匹配（默认） |
requireUnique | 若亚军太近则失败——错选代价高时用 |
all | 报告阈值以上所有匹配，上限 maxMatches |
端口
| 端口 | 走它的时机 | 必接 |
|---|---|---|
| Success | 模板被找到 | 是（单/多模式） |
| Failure | 超时前未找到（status 仍 success），或可恢复的检测错误——匹配歧义、引擎故障、劣质模板 | 否 |
| Cancelled | 搜索中途运行被停 | 否——永不被走 |
| Fatal | 抓帧失败、断连，或参数无效 | 否——永不被走 |
| 按模板 | 分支模式：携带匹配模板 id 的端口 | 否 |
| notFound | 分支模式：无模板匹配 | 否 |
基础示例
等一个按钮再点：
- Template：Start 按钮，紧裁剪
- Threshold：
0.88 - Timeout：
5000ms
接 Success → Click（coordinate source = 此节点），Failure → Stop: failure。
实际示例——可选弹窗
奖励弹窗有天有有天没有。两种都正常：
短超时是关键：你问的是"它现在在吗"，不是等它到来。这里 30 秒超时会在每个无弹窗的运行浪费 30 秒。
高级示例——按模板分支
一个节点决定你在四个界面的哪一个：
用一个节点替换四个串行 Find Image，用一张截图而非四张。
最佳实践
- 只截目标的紧裁剪，不带背景。背景正是模板日后不匹配的原因。
- 阈值从 0.88 起步，用 Test Node 调。
- 总接 Failure。 空的 Failure 端口把"未找到"变成被终止的运行。
- 大致知道目标在哪时设搜索区域。
- 超时匹配问题。"它现在在吗？"= 短。"等它加载"= 长。
- 用节点作 Click 的 coordinate source，而非把坐标穿过变量。
- 识别 哪个界面在显示时，优先 branch-by-template 而非一串 Find Image。
性能笔记
- 每次轮询成本 ≈（区域面积）×（模板数）×（尺度数）。三者相乘。
- 搜索区域是最大杠杆。 裁到四分之一屏约减 4 倍匹配工作。
- 多尺度贵——每个尺度档是又一次完整扫描。只在目标真会变大小时开。
- 灰度比彩色便宜，对 UI 框架常同样可靠。
- 短轮询意味着每秒更多抓取。低于约 150 ms 通常抓取花的比响应得的多。
- 图像在场时长超时零成本——节点匹配即返回。长超时只在未找到情形花时间。
内存笔记
- 模板被加载并缓存。模板多而大 = 工作集大；紧裁剪在每个意义上都小。
- 每次轮询抓新帧。帧短暂，但很短的轮询增加抓取搅动。
all歧义模式带高maxMatches保留匹配列表；保持上限合理。
常见错误
| 错误 | 后果 | 修复 |
|---|---|---|
| 只接 Success | "未找到"终止运行 | 接 Failure |
| 模板杂乱 | 背景一变置信度掉 | 紧裁辨识部分 |
| Threshold 0.95+ | 错过有效匹配 | 从 0.88 起 |
| 对加载界面超时太短 | 动画中放弃 | 超时匹配所等之物 |
| 对可选元素长超时 | 每次运行浪费那么久 | "现在在吗"用短超时 |
| 加重试想"找得狠" | 不触发——未找到是 success 状态 | 加大超时 |
| 到处开多尺度 | 检测慢数倍 | 只在尺寸变的地方开 |
故障排查
明明在屏幕上却从不找到。 降阈值，用 Test Node 看真实置信度。远低于 0.88 → 模板带了变化的背景。
匹配错位置。
设搜索区域，或把歧义改 requireUnique 加 delta，让接近的情况失败而非猜。
改分辨率或缩放后就坏了。 模板匹配按像素。重截模板，或在流程功能开关里开多尺度。
节点慢。 查区域大小、模板数与尺度范围——三者相乘。先加搜索区域。
一个 branch-by-template 端口消失了。 它的模板被移出选择。编辑器剪掉孤儿连线。
FAQ
未找到对重试或健康上限算失败吗？
不。它的 status 是 success。
能只搜屏幕一部分吗？ 能——设搜索区域。更快更可靠。
一个节点装几个模板？ 最多 16。
该瞄准多少置信度？ 稳稳高于阈值。真实最佳 0.89 对阈值 0.88 是过薄的余地——改进模板。
Poll interval 是超时吗？ 不。轮询是重查频率；超时是尝试总时长。
相关节点
- Click——点击找到的东西
- Swipe——居中找到的东西
- Read Text——读值而非找图
- Check Region——无图标的状态
- If——之后在此节点结果上分支