查找图像

使用 OpenCV 模板匹配技术，在设备屏幕截图中查找指定的图像模板，支持相似度控制和多结果查找。

接口说明

接口类型

findImage

参数

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

返回值

单个匹配（multiple = false）：

{
    x: 100,          // 匹配区域中心点X坐标
    y: 200,          // 匹配区域中心点Y坐标
    confidence: 0.95 // 相似度 (0-1)
}

多个匹配（multiple = true）：

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

功能说明

搜索方向

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

相似度阈值

threshold 控制匹配精度：

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

多结果查找

使用 multiple = true 查找所有匹配位置：

• 自动按相似度降序排列
• 使用 distance 参数过滤距离太近的结果
• 最多返回 88 个结果

💡 提示

图像匹配使用 OpenCV 的模板匹配算法，基于灰度图进行匹配，因此对颜色变化有一定容忍度。建议模板图片包含明显的特征，避免纯色或重复图案，这样可以提高匹配准确度和速度。