OpenCV 模块

android.openCv 提供图像处理与图色搜索能力，包括截屏、颜色操作、模板匹配、多色搜索等。是插件能力，不是 Android 主程序默认注册路由。

前置条件

通过 android.file.writeBase64() 将 opencv-plugin.zip 推送到设备
通过 android.app.loadPlugin() 加载插件
需要截图权限（android.auth.openScreenCap()）

// 1. 推送插件
await android.file.writeBase64(
  '/data/local/tmp/opencv-plugin.zip',
  base64Content,
)
// 2. 加载插件
await android.app.loadPlugin('/data/local/tmp/opencv-plugin.zip')

图像缓存

所有图像操作通过 imageId 访问。截图和处理后的图像默认存入临时缓存（最多 5 张，LRU 淘汰）。调用 save() 可将临时缓存转为永久缓存（需手动释放）。

截图与加载

screenshot(x?, y?, w?, h?)

截屏，返回 imageId。

参数：
- x?: number：区域左上角 x（可选，不传则全屏）
- y?: number：区域左上角 y
- w?: number：区域宽度
- h?: number：区域高度
返回值：Promise<number> — imageId

const id = await android.openCv.screenshot()
const id2 = await android.openCv.screenshot(0, 0, 500, 500)

loadImage(base64)

从 Base64 字符串加载图片到缓存。

参数：
- base64: string：Base64 编码的图片数据
返回值：Promise<number> — imageId

const id = await android.openCv.loadImage(base64Str)

缓存管理

save(imageId)

将临时缓存转为永久缓存。

返回值：Promise<boolean>

list()

查询所有缓存中的图像。

返回值：Promise<ImageCacheInfo[]>

interface ImageCacheInfo {
  imageId: number
  width: number
  height: number
  type: 'temp' | 'saved'
  size: number
}

release(imageId)

释放指定图像缓存。

返回值：Promise<boolean>

releaseAll()

释放所有图像缓存。

返回值：Promise<boolean>

颜色操作

getColor(imageId, x, y)

获取图像指定坐标的像素颜色。

返回值：Promise<[number, number, number]> — [R, G, B]

cvtColor(imageId)

灰度转换，返回新 imageId（原图不变）。

返回值：Promise<number> — 新 imageId

binaryThreshold(imageId, threshold?)

二值化处理（自适应阈值），返回新 imageId。

参数：
- threshold?: number：阈值（可选，默认使用自适应算法）
返回值：Promise<number> — 新 imageId

drawImg(imageId, x, y, w, h)

裁剪图像，返回新 imageId。

返回值：Promise<number> — 新 imageId

delBackground(imageId, colors, qua)

删除背景色。与 colors 列表中颜色差异大于 qua 的像素保留，其余设为黑色。

参数：
- colors: number[][]：保留的颜色列表，如 [[255, 255, 255]]
- qua: number：相似度阈值（1-100）
返回值：Promise<number> — 新 imageId

swapColor(imageId, colorA, colorB)

像素级颜色交换。完全匹配 colorA 的像素变为 colorB，反之亦然。

参数：
- colorA: [number, number, number]：颜色 A [R, G, B]
- colorB: [number, number, number]：颜色 B [R, G, B]
返回值：Promise<number> — 新 imageId

图像搜索

findImg(imageId, smallImageId, qua)

模板匹配。在大图中搜索小图位置。

参数：
- imageId: number：大图（被搜索的图）
- smallImageId: number：小图（要找的模板）
- qua: number：相似度阈值（1-100）
返回值：Promise<FindImageRes | null>

interface FindImageRes {
  x: number
  y: number // 匹配中心坐标
  x1: number
  y1: number // 匹配区域左上角
  x2: number
  y2: number // 匹配区域右下角
  qua: number // 实际匹配度
}