跳到主要内容

找图

from ascript.android.screen import FindImages

从屏幕中找到 局部图片 的 位置，支持透明 PNG、多图搜索、多尺度匹配。

使用场景
  • 在屏��上查找特定图标、按钮、头像等图片元素的位置
  • 判断某个 UI 元素是否出现（如加载完成的图标、红点提醒）
  • 游戏中查找怪物、道具、技能图标等固定图案
  • 一次查找多张模板图，判断当前匹配的是哪一个
  • 跨分辨率设备适配，同一套模板图在不同 DPI 下使用

返回值格式​

所有找图方法返回 dict 字典（单个）或 dict 数组（多个）：

{
    'rect': [915, 1761, 1076, 1899],  # 子图在屏幕中的范围
    'center_x': 995,                   # 中心点 X 坐标
    'center_y': 1830,                  # 中心点 Y 坐标
    'confidence': 0.949,               # 相似度 0-1
    'index': 0                         # 多图搜索时，属于第几张模板图
}

方法​

find — 找一个​

在屏幕中查找局部图片，返回第一个匹配结果。

  • 函数
FindImages.find(part_img, rect=None, confidence=0.1, rgb=False,
                source_img=None, ori=2, scale_range=None, image=None)
  • 参数
参数类型是否必填说明
part_imgstr/list是局部图片路径或路径列表。只填文件名时自动在 res/img/ 下查找
rectlist否搜索范围 [x, y, x1, y1]
confidencefloat否可信度阈值 0-1，低于此值的结果被过滤，默认 0.1
rgbbool否True=彩色匹配，False=灰度匹配（可找到相同形状不同颜色的图案）
oriint否排序方向 1-8，默认 2（左上→右下横向）
scale_rangelist否多尺度匹配范围，如 [0.5, 2.0]，None=单尺度
imageBitmap/ndarray否传入源图，None=自动截屏
  • 示例
from ascript.android.screen import FindImages
from ascript.android.system import R

# 基本找图
res = FindImages.find(R.res("/img/btn.png"))
if res:
    print("位置:", res["center_x"], res["center_y"])
    print("相似度:", res["confidence"])

# 指定范围 + 可信度
res = FindImages.find(R.res("/img/btn.png"), rect=[59, 932, 374, 1207], confidence=0.8)

# 一次找多张图
res = FindImages.find(R.img("a.png", "b.png", "c.png"), confidence=0.8)
if res:
    print("匹配的是第", res["index"], "张图")

find_all — 找所有​

查找所有匹配的图片位置。

  • 函数
FindImages.find_all(part_img, rect=None, confidence=0.1, rgb=False,
                    source_img=None, maxcnt=0, ori=2, scale_range=None, image=None)
  • 参数
参数类型是否必填说明
maxcntint否最大返回数量，0=不限制
其他参数--同 find()
  • 返回值

dict 数组，或 None

  • 示例
from ascript.android.screen import FindImages
from ascript.android.system import R

res = FindImages.find_all(R.res("/img/icon.png"), confidence=0.8)
if res:
    for item in res:
        print("位置:", item["center_x"], item["center_y"], "相似度:", item["confidence"])

find_template — 模板匹配（单个）​

基于 OpenCV 模板匹配，速度快，支持透明 PNG。

  • 函数
FindImages.find_template(part_img, rect=None, confidence=0.5, rgb=False,
                         source_img=None, ori=2, scale_range=None, image=None)

参数同 find()，默认 confidence=0.5。

find_all_template — 模板匹配（所有）​

  • 函数
FindImages.find_all_template(part_img, rect=None, confidence=0.5, rgb=False,
                             maxcnt=0, source_img=None, ori=2, scale_range=None, image=None)

参数同 find_all()，默认 confidence=0.5。

多尺度匹配​

普通模板匹配要求模板图和屏幕上的目标大小一致，但实际使用中经常遇到：

  • 模板图在 1080p 设备截取，运行在 720p 或 2K 设备上
  • 游戏界面有缩放动画，按钮大小会变化
  • 同一个 APP 在不同 DPI 设备上图标尺寸不同

scale_range 参数可以解决这些问题。

参数说明​

scale_range = [最小缩放比, 最大缩放比]
值含义
None不启用多尺度，使用原始大小匹配（默认）
[0.5, 1.5]模板在 50%~150% 范围内逐步缩放匹配
[0.8, 1.2]小幅度搜索，适合轻微尺寸偏差
[0.5, 2.0]大范围搜索，适合跨分辨率场景

引擎会在范围内自动生成约 15 个缩放步长（如 0.5, 0.53, 0.57, ... 2.0），逐一尝试匹配，返回得分最高的结果。如果范围包含 1.0，会确保 1.0（原尺寸）被包含在内。

示例​

from ascript.android.screen import FindImages
from ascript.android.system import R

# 场景一：1080p 截的模板，跑在不同分辨率设备
res = FindImages.find(R.res("/img/btn.png"), scale_range=[0.5, 2.0], confidence=0.7)
if res:
    print("找到:", res["center_x"], res["center_y"])

# 场景二：按钮可能有轻微缩放，小范围搜索即可
res = FindImages.find(R.res("/img/icon.png"), scale_range=[0.9, 1.1], confidence=0.8)

# 场景三：配合 rect 缩小搜索区域，提升速度
res = FindImages.find(R.res("/img/btn.png"),
                      rect=[0, 1500, 1080, 1920],
                      scale_range=[0.6, 1.5],
                      confidence=0.7)
性能提示

多尺度匹配约比单尺度慢 15 倍（15 个缩放步长），建议：

  • 配合 rect 缩小搜索区域
  • 缩放范围尽量精确（如 [0.8, 1.2] 而非 [0.3, 3.0]）
  • 对性能要求高的场景，先用单尺度测试，确实不匹配再启用

image 参数说明​

所有方法都支持 image 参数，可传入 Android Bitmap 或 OpenCV ndarray，系统自动转换：

from ascript.android.screen import FindImages, capture

# 先截屏，再找图（避免多次截屏）
bmp = capture()
res1 = FindImages.find("a.png", image=bmp)
res2 = FindImages.find("b.png", image=bmp)

关于 SIFT​

兼容说明

find_sift() 和 find_all_sift() 方法因压缩版 OpenCV 不支持 SIFT 算法，已自动降级为模板匹配。如需跨分辨率匹配，请使用 scale_range 参数。