查找图像（多模板）

使用 OpenCV 模板匹配技术，在设备截图中同时查找多张模板图片。相比 findImage，该接口使用 sprites 数组输入，并在返回结果中提供命中的模板 index（对应 sprites 的下标），便于区分命中了哪一张模板。

接口说明

接口类型

findImages

参数

参数名	类型	必填	说明
deviceId	string	是	设备ID
sprites	array	是	模板图片数组（base64字符串数组）
threshold	number	否	相似度阈值 (0-1)，默认 0.9
rect	array	否	搜索区域 [x1, y1, x2, y2]，默认全屏
direction	number	否	搜索方向 0-3，默认 0
findAll	boolean	否	是否返回全部匹配，默认 false， 找到一张就返回
distance	number	否	结果间最小距离（像素），默认 8

返回值

最优匹配（findAll = false）：

• 未匹配到返回 null
• 匹配到返回对象：

{
    x: 100,           // 匹配区域中心点X坐标
    y: 200,           // 匹配区域中心点Y坐标
    confidence: 0.95, // 相似度 (0-1)
    index: 0          // 命中模板在 sprites 中的下标
}

全部匹配（findAll = true）：

• 未匹配到返回空数组 []
• 匹配到返回数组：

[
    { x: 100, y: 200, confidence: 0.95, index: 0 },
    { x: 150, y: 250, confidence: 0.92, index: 2 },
    { x: 200, y: 300, confidence: 0.90, index: 1 }
]
// 按相似度降序排列，最多返回 88 个结果

功能说明

查找策略（findAll = false）

• direction = 0（默认）：在所有 sprites 的匹配结果中选择全局最优（相似度最高）的那个点返回。
• direction != 0：按 sprites 的顺序依次尝试，找到任意一个模板命中后立即返回（并遵循方向偏好）。

搜索方向

direction	说明	适用场景
0	最优匹配	查找相似度最高的位置（默认）
1	从右到左	优先查找屏幕右侧的目标
2	从下到上	优先查找屏幕下方的目标
3	从右下到左上	优先查找屏幕右下角的目标

相似度阈值

threshold 控制匹配精度：

• 1.0 - 完全相同（很难匹配成功）
• 0.95 - 几乎完全相同
• 0.9 - 高度相似（推荐，默认值）
• 0.85 - 相似
• 0.8 - 基本相似
• < 0.8 - 可能误匹配

去重策略（distance）

当 findAll = true 时，如果两个结果点在 X 与 Y 方向上都小于 distance 像素，会被视为“太近”，从而过滤掉低相似度的结果，减少重复命中。

💡 提示

建议模板图片尽量小且特征明显（避免大面积纯色或重复纹理）。在已知目标出现区域时优先使用 rect 限定搜索范围，可显著提升速度与准确率。