图色模块-Images

稳定

images 模块提供了一些手机设备中常见的图片处理函数，包括截图、读写图片、图片剪裁、旋转、二值化、找色找图等。 该模块分为两个部分，找图找色部分和图片处理部分。 需要注意的是，image 对象创建后尽量在不使用时进行回收，同时避免循环创建大量图片。因为图片是一种占用内存比较大的资源，尽管 Auto.js 通过各种方式（比如图片缓存机制、垃圾回收时回收图片、脚本结束时回收所有图片）尽量降低图片资源的泄漏和内存占用，但是糟糕的代码仍然可以占用大量内存。 Image 对象通过调用recycle()函数来回收。例如：

// 读取图片
var img = images.read("./1.png");
//对图片进行操作
...
// 回收图片
img.recycle();

例外的是，caputerScreen()返回的图片不需要回收。

images.read(path)

  • path {string} 图片路径
  • retrun {Image}

读取在路径 path 的图片文件并返回一个 Image 对象。如果文件不存在或者文件无法解码则返回 null。

images.load(url)

  • url {string} 图片 URL 地址
  • retrun {Image}

加载在地址 URL 的网络图片并返回一个 Image 对象。如果地址不存在或者图片无法解码则返回 null。

images.copy(img)

  • img {Image} 图片
  • retrun {Image}

复制一张图片并返回新的副本。该函数会完全复制 img 对象的数据。

images.save(image, path[, format = "png", quality = 100])

  • image {Image} 图片
  • path {string} 路径
  • format {string} 图片格式，可选的值为:
    • png
    • jpeg/jpg
    • webp
  • quality {number} 图片质量，为 0~100 的整数值

把图片 image 以 PNG 格式保存到 path 中。如果文件不存在会被创建；文件存在会被覆盖。

//把图片压缩为原来的一半质量并保存
var img = images.read("/sdcard/1.png");
images.save(img, "/sdcard/1.jpg", "jpg", 50);
app.viewFile("/sdcard/1.jpg");

images.fromBase64(base64)

  • base64 {string} 图片的 Base64 数据
  • retrun {Image}

解码 Base64 数据并返回解码后的图片 Image 对象。如果 base64 无法解码则返回null。

images.toBase64(image[, format = "png", quality = 100])

  • image {Image} 图片
  • format {string} 图片格式，可选的值为:
    • png
    • jpeg/jpg
    • webp
  • quality {number} 图片质量，为 0~100 的整数值
  • retrun {string}

把图片编码为 base64 数据并返回。

images.fromBytes(bytes)

  • bytes {byte[]} 字节数组

解码字节数组 bytes 并返回解码后的图片 Image 对象。如果 bytes 无法解码则返回null。

images.toBytes(img[, format = "png", quality = 100])

  • img {Image} 图片
  • format {string} 图片格式，可选的值为:
    • png
    • jpeg/jpg
    • webp
  • quality {number} 图片质量，为 0~100 的整数值
  • retrun {byte[]}

把图片编码为字节数组并返回。

images.clip(img, x, y, w, h)

  • img {Image} 图片
  • x {number} 剪切区域的左上角横坐标
  • y {number} 剪切区域的左上角纵坐标
  • w {number} 剪切区域的宽度
  • h {number} 剪切区域的高度
  • retrun {Image}

从图片 img 的位置(x, y)处剪切大小为 w * h 的区域，并返回该剪切区域的新图片。

var src = images.read("/sdcard/1.png");
var clip = images.clip(src, 100, 100, 400, 400);
images.save(clip, "/sdcard/clip.png");

images.resize(img, size[, interpolation])

  • img {Image} 图片
  • size {Array} 两个元素的数组[w, h]，分别表示宽度和高度；如果只有一个元素，则宽度和高度相等
  • interpolation {string} 插值方法，可选，默认为"LINEAR"（线性插值），可选的值有：
  • retrun {Image}

调整图片大小，并返回调整后的图片。例如把图片放缩为 200*300：images.resize(img, [200, 300])。

参见Imgproc.resizeopen in new window。

images.scale(img, fx, fy[, interpolation])

  • img {Image} 图片
  • fx {number} 宽度放缩倍数
  • fy {number} 高度放缩倍数
  • interpolation {string} 插值方法，可选，默认为"LINEAR"（线性插值），可选的值有：
  • retrun {Image}

放缩图片，并返回放缩后的图片。例如把图片变成原来的一半：images.scale(img, 0.5, 0.5)。 参见Imgproc.resizeopen in new window。

images.rotate(img, degress[, x, y])

  • img {Image} 图片
  • degress {number} 旋转角度。
  • x {number} 旋转中心 x 坐标，默认为图片中点
  • y {number} 旋转中心 y 坐标，默认为图片中点
  • retrun {Image}

将图片逆时针旋转 degress 度，返回旋转后的图片对象。 例如逆时针旋转 90 度为images.rotate(img, 90)。

images.concat(img1, img2, [direction])

  • img1 {Image} 图片 1
  • img2 {Image} 图片 2
  • direction {string} 连接方向，默认为"RIGHT"，可选的值有：
    • LEFT 将图片 2 接到图片 1 左边
    • RIGHT 将图片 2 接到图片 1 右边
    • TOP 将图片 2 接到图片 1 上边
    • BOTTOM 将图片 2 接到图片 1 下边
  • retrun {Image}

连接两张图片，并返回连接后的图像。如果两张图片大小不一致，小的那张将适当居中。

images.grayscale(img)

  • img {Image} 图片
  • retrun {Image}

灰度化图片，并返回灰度化后的图片。

image.threshold(img, threshold, maxVal[, type])

  • img {Image} 图片
  • threshold {number} 阈值
  • maxVal {number} 最大值
  • type {string} 阈值化类型，默认为"BINARY"，参见ThresholdTypesopen in new window, 可选的值:
    • BINARY
    • BINARY_INV
    • TRUNC
    • TOZERO
    • TOZERO_INV
    • OTSU
    • TRIANGLE
  • retrun {Image}

将图片阈值化，并返回处理后的图像。可以用这个函数进行图片二值化。例如：images.threshold(img, 100, 255, "BINARY")，这个代码将图片中大于 100 的值全部变成 255，其余变成 0，从而达到二值化的效果。如果 img 是一张灰度化图片，这个代码将会得到一张黑白图片。 可以参考有关博客（比如threshold 函数的使用open in new window）或者 OpenCV 文档thresholdopen in new window。

images.adaptiveThreshold(img, maxValue, adaptiveMethod, thresholdType, blockSize, C)

  • img {Image} 图片
  • maxValue {number} 最大值
  • adaptiveMethod {string} 在一个邻域内计算阈值所采用的算法，可选的值有：
    • MEAN_C 计算出领域的平均值再减去参数 C 的值
    • GAUSSIAN_C 计算出领域的高斯均值再减去参数 C 的值
  • thresholdType {string} 阈值化类型，可选的值有：
    • BINARY
    • BINARY_INV
  • blockSize {number} 邻域块大小
  • C {number} 偏移值调整量
  • retrun {Image}

对图片进行自适应阈值化处理，并返回处理后的图像。 可以参考有关博客（比如threshold 与 adaptiveThresholdopen in new window）或者 OpenCV 文档adaptiveThresholdopen in new window。

images.cvtColor(img, code[, dstCn])

  • img {Image} 图片
  • code {string} 颜色空间转换的类型，可选的值有一共有 205 个（参见ColorConversionCodesopen in new window），这里只列出几个：
    • BGR2GRAY BGR 转换为灰度
    • BGR2HSV BGR 转换为 HSV
    • ``
  • dstCn {number} 目标图像的颜色通道数量，如果不填写则根据其他参数自动决定。
  • retrun {Image}

对图像进行颜色空间转换，并返回转换后的图像。 可以参考有关博客（比如颜色空间转换open in new window）或者 OpenCV 文档cvtColoropen in new window。

images.inRange(img, lowerBound, upperBound)

  • img {Image} 图片
  • lowerBound {string} | {number} 颜色下界
  • upperBound {string} | {number} 颜色下界
  • retrun {Image}

将图片二值化，在 lowerBound~upperBound 范围以外的颜色都变成 0，在范围以内的颜色都变成 255。 例如images.inRange(img, "#000000", "#222222")。

images.interval(img, color, interval)

  • img {Image} 图片
  • color {string} | {number} 颜色
  • interval {number} 每个通道的范围间
  • retrun {Image}

将图片二值化，在 color-interval ~ color+interval 范围以外的颜色都变成 0，在范围以内的颜色都变成 255。这里对 color 的加减是对每个通道而言的。
例如images.interval(img, "#888888", 16)，每个通道的颜色值均为 0x88，加减 16 后的范围是[0x78, 0x98]，因此这个代码将把#787878~#989898 的颜色变成#FFFFFF，而把这个范围以外的变成#000000。

images.blur(img, size[, anchor, type])

  • img {Image} 图片
  • size {Array} 定义滤波器的大小，如[3, 3]
  • anchor {Array} 指定锚点位置(被平滑点)，默认为图像中心
  • type {string} 推断边缘像素类型，默认为"DEFAULT"，可选的值有：
    • CONSTANT iiiiii|abcdefgh|iiiiiii with some specified i
    • REPLICATE aaaaaa|abcdefgh|hhhhhhh
    • REFLECT fedcba|abcdefgh|hgfedcb
    • WRAP cdefgh|abcdefgh|abcdefg
    • REFLECT_101 gfedcb|abcdefgh|gfedcba
    • TRANSPARENT uvwxyz|abcdefgh|ijklmno
    • REFLECT101 same as BORDER_REFLECT_101
    • DEFAULT same as BORDER_REFLECT_101
    • ISOLATED do not look outside of ROI
  • retrun {Image}

对图像进行模糊（平滑处理），返回处理后的图像。
可以参考有关博客（比如实现图像平滑处理open in new window）或者 OpenCV 文档bluropen in new window。

images.medianBlur(img, size)

  • img {Image} 图片
  • size {Array} 定义滤波器的大小，如[3, 3]
  • retrun {Image}

对图像进行中值滤波，返回处理后的图像。
可以参考有关博客（比如实现图像平滑处理open in new window）或者 OpenCV 文档medianBluropen in new window。

images.gaussianBlur(img, size[, sigmaX, sigmaY, type])

  • img {Image} 图片
  • size {Array} 定义滤波器的大小，如[3, 3]
  • sigmaX {number} x 方向的标准方差，不填写则自动计算
  • sigmaY {number} y 方向的标准方差，不填写则自动计算
  • type {string} 推断边缘像素类型，默认为"DEFAULT"，参见images.blur
  • retrun {Image}

对图像进行高斯模糊，返回处理后的图像。
可以参考有关博客（比如实现图像平滑处理open in new window）或者 OpenCV 文档GaussianBluropen in new window。

images.matToImage(mat)

  • mat {Mat} OpenCV 的 Mat 对象
  • retrun {Image}

把 Mat 对象转换为 Image 对象。

找图找色

images.requestScreenCapture([landscape])

  • landscape {boolean} 截屏方向
    • true 横屏截图
    • false 竖屏截图
    • 不指定值，由当前设备屏幕方向决定截图方向
  • return {boolean}

向系统申请屏幕截图权限，返回是否请求成功,仅需执行一次 建议在本软件界面运行该函数，在其他软件界面运行时容易出现一闪而过的黑屏现象。 示例:

//请求截图
//每次使用该函数都会弹出截图权限请求，建议选择“总是允许”。
if (!requestScreenCapture()) {
  toast("请求截图失败");
  exit();
}
//连续截图 10 张图片(间隔 1 秒)并保存到存储卡目录
for (var i = 0; i < 10; i++) {
  captureScreen("/sdcard/screencapture" + i + ".png");
  sleep(1000);
}

//安卓版本高于 Android 9
if (device.sdkInt > 28) {
  //等待截屏权限申请并同意
  threads.start(function () {
    packageName("com.android.systemui").text("立即开始").waitFor();
    text("立即开始").click();
  });
}
//申请截屏权限
if (!requestScreenCapture()) {
  toast("请求截图失败");
  exit();
}

该函数也可以作为全局函数使用。

images.captureScreen()

  • return {Image}

截取当前屏幕并返回一个 Image 对象。 没有截图权限时执行该函数会抛出 SecurityException。
该函数不会返回 null，两次调用可能返回相同的 Image 对象。这是因为设备截图的更新需要一定的时间，短时间内（一般来说是 16ms）连续调用则会返回同一张截图。 截图需要转换为 Bitmap 格式，从而该函数执行需要一定的时间(0~20ms)。
另外在 requestScreenCapture()执行成功后需要一定时间后才有截图可用，因此如果立即调用 captureScreen()，会等待一定时间后(一般为几百 ms)才返回截图。 例子:

//请求横屏截图
requestScreenCapture(true);
//截图
var img = captureScreen();
//获取在点(100, 100)的颜色值
var color = images.pixel(img, 100, 100);
//显示该颜色值
toast(colors.toString(color));

该函数也可以作为全局函数使用。

images.captureScreen(path)

  • path {string} 截图保存路径

截取当前屏幕并以 PNG 格式保存到 path 中。如果文件不存在会被创建；文件存在会被覆盖。 该函数不会返回任何值。该函数也可以作为全局函数使用。

images.pixel(image, x, y)

  • image {Image} 图片
  • x {number} 要获取的像素的横坐标。
  • y {number} 要获取的像素的纵坐标。

返回图片 image 在点(x, y)处的像素的 ARGB 值。 该值的格式为 0xAARRGGBB，是一个"32 位整数"(虽然 JavaScript 中并不区分整数类型和其他数值类型)。
坐标系以图片左上角为原点。以图片左侧边为 y 轴，上侧边为 x 轴。

images.readPixels(path)

  • path {string} 图片的地址

  • return {Object} 包括图片的像素数据和宽高，{data,width,height}

读取图片的像素数据和宽高。

images.findColor(image, color, [options])

  • image {Image} 图片
  • color {number} | {string} 要寻找的颜色的 RGB 值。如果是一个整数，则以 0xRRGGBB 的形式代表 RGB 值（A 通道会被忽略）；如果是字符串，则以"#RRGGBB"代表其 RGB 值。
  • options {Object} 可选项包括：
    • region {Array} 找色区域。是一个两个或四个元素的数组。(region[0], region[1])表示找色区域的左上角；region[2]*region[3]表示找色区域的宽高。如果 region只有两个元素，则找色区域为(region[0], region[1])到图片右下角。如果不指定region选项，则找色区域为整张图片。
    • similarity {number} 颜色相似度，范围为 0~1（越大越相似，1 为颜色相等，0 为任何颜色都能匹配）。
    • threshold {number} 颜色相似度的临界值，范围为 0 ~ 255（越小越相似，0 为颜色相等，255 为任何颜色都能匹配）。默认为 4。
    • similarity与threshold的换算为similarity = (255 - threshold) / 255 。二选一，同时存在则以similarity为准。
  • return {Point}

在图片中寻找颜色 color。找到时返回找到的点 Point，找不到时返回 null。 该函数也可以作为全局函数使用。
一个循环找色的例子如下：

requestScreenCapture();
//循环找色，找到红色(#ff0000)时停止并报告坐标
while (true) {
  var img = captureScreen();
  var point = findColor(img, "#ff0000");
  if (point) {
    toast("找到红色，坐标为(" + point.x + ", " + point.y + ")");
  }
}

一个区域找色的例子如下：

//读取本地图片/sdcard/1.png
var img = images.read("/sdcard/1.png");
//判断图片是否加载成功
if (!img) {
  toast("没有该图片");
  exit();
}
//在该图片中找色，指定找色区域为在位置(400, 500)的宽为 300 长为 200 的区域，指定找色临界值为 4
var point = findColor(img, "#00ff00", {
  region: [400, 500, 300, 200],
  threshold: 4,
});
if (point) {
  toast("找到啦:" + point);
} else {
  toast("没找到");
}

images.findColorInRegion(img, color, [x, y, width, height, threshold])

区域找色的简便方法。 相当于

images.findColor(img, color, {
  region: [x, y, width, height],
  threshold: threshold,
});

该函数也可以作为全局函数使用。

images.findColorEquals(img, color[, x, y, width, height])

  • img {Image} 图片
  • color {number} | {string} 要寻找的颜色
  • x {number} 找色区域的左上角横坐标
  • y {number} 找色区域的左上角纵坐标
  • width {number} 找色区域的宽度
  • height {number} 找色区域的高度
  • return {Point}

在图片 img 指定区域中找到颜色和 color 完全相等的某个点，并返回该点的坐标；如果没有找到，则返回null。
找色区域通过x, y, width, height指定，如果不指定找色区域，则在整张图片中寻找。 该函数也可以作为全局函数使用。
示例： (通过找 QQ 红点的颜色来判断是否有未读消息)

requestScreenCapture();
launchApp("QQ");
sleep(1200);
var p = findColorEquals(captureScreen(), "#f64d30");
if (p) {
  toast("有未读消息");
} else {
  toast("没有未读消息");
}

images.findAllPointsForColor(img, color, [options])

  • img {Image} 图片

  • color {number | string} 要检测的颜色

  • options {Object} 选项包括：

    • region {Array} 找色区域。是一个两个或四个元素的数组。(region[0], region[1])表示找色区域的左上角；region[2]*region[3]表示找色区域的宽高。如果 region只有两个元素，则找色区域为(region[0], region[1])到图片右下角。如果不指定region选项，则找色区域为整张图片。
    • similarity {number} 找色时颜色相似度，范围为 0 ~ 1（越大越相似，1 为颜色相等，0 为任何颜色都能匹配）。
    • threshold {number} 找色时颜色相似度的临界值，范围为 0 ~ 255（越小越相似，0 为颜色相等，255 为任何颜色都能匹配）。默认为 4。
    • similarity与threshold的换算为similarity = (255 - threshold) / 255 。二选一，同时存在则以similarity为准。

  • return {Array}

在图片中寻找所有颜色为color的点。找到时返回找到的点 Point 的数组，找不到时返回null。 例如找出所有白色的点：

log(images.findAllPointsForColor(img, "#ffffff"));

images.findMultiColors(img, firstColor, colors[, options])

  • img {Image} 要找色的图片
  • firstColor {number} | {string} 第一个点的颜色
  • colors {Array} 表示剩下的点相对于第一个点的位置和颜色的数组，数组的每个元素为[x, y, color]
  • options {Object} 选项包括：
    • region {Array} 找色区域。是一个两个或四个元素的数组。(region[0], region[1])表示找色区域的左上角；region[2]*region[3]表示找色区域的宽高。如果只有 region 只有两个元素，则找色区域为(region[0], region[1])到屏幕右下角。如果不指定 region 选项，则找色区域为整张图片。
    • threshold {number} 找色时颜色相似度的临界值，范围为 0 ~ 255（越小越相似，0 为颜色相等，255 为任何颜色都能匹配）,默认为 4。threshold 和浮点数相似度(0.0~1.0)的换算为 similarity = (255 - threshold) / 255.
  • return {Point}

多点找色，类似于按键精灵的多点找色，其过程如下：

  1. 在图片 img 中找到颜色 firstColor 的位置(x0, y0)
  2. 对于数组 colors 的每个元素[x, y, color]，检查图片 img 在位置(x + x0, y + y0)上的像素是否是颜色 color，是的话返回(x0, y0)，否则继续寻找 firstColor 的位置，重新执行第 1 步
  3. 整张图片都找不到时返回null

例如:images.findMultiColors(img, "#123456", [[10, 20, "#ffffff"], [30, 40, "#000000"]])，假设图片在(100, 200)的位置的颜色为#123456, 当左边(110, 220)的位置的颜色为#fffff 且(130, 240)的位置的颜色为#000000，则函数返回点(100, 200)。
如果要指定找色区域，则在 options 中指定，例如:

var p = images.findMultiColors(
  img,
  "#123456",
  [
    [10, 20, "#ffffff"],
    [30, 40, "#000000"],
  ],
  {
    region: [0, 960, 1080, 960],
  }
);

images.detectsColor(image, color, x, y[, threshold = 4, algorithm = "diff"])

  • image {Image} 图片
  • color {number} | {string} 要检测的颜色
  • x {number} 要检测的位置横坐标
  • y {number} 要检测的位置纵坐标
  • threshold {number} 颜色相似度临界值，默认为 4。取值范围为 0~255。
  • algorithm {string} 颜色匹配算法，包括:
    • equal: 相等匹配，只有与给定颜色 color 完全相等时才匹配。
    • diff: 差值匹配。与给定颜色的 R、G、B 差的绝对值之和小于 threshold 时匹配。
    • rgb: rgb 欧拉距离相似度。与给定颜色 color 的 rgb 欧拉距离小于等于 threshold 时匹配。
    • rgb+: 加权 rgb 欧拉距离匹配(LAB Delta Eopen in new window)。
    • hs: hs 欧拉距离匹配。hs 为 HSV 空间的色调值。

返回图片 image 在位置(x, y)处是否匹配到颜色 color。用于检测图片中某个位置是否是特定颜色。 一个判断微博客户端的某个微博是否被点赞过的例子：

requestScreenCapture();
//找到点赞控件
var like = id("ly_feed_like_icon").findOne();
//获取该控件中点坐标
var x = like.bounds().centerX();
var y = like.bounds().centerY();
//截图
var img = captureScreen();
//判断在该坐标的颜色是否为橙红色
if (images.detectsColor(img, "#fed9a8", x, y)) {
  //是的话则已经是点赞过的了，不做任何动作
} else {
  //否则点击点赞按钮
  like.click();
}

images.findImage(img, template[, options])

  • img {Image} 大图片
  • template {Image} 小图片（模板）
  • options {Object} 选项包括：
    • threshold {number} 图片相似度。取值范围为 0~1 的浮点数。默认值为 0.9。
    • region {Array} 找图区域。参见 findColor 函数关于 region 的说明。
    • level {number} 一般而言不必修改此参数。不加此参数时该参数会根据图片大小自动调整。找图算法是采用图像金字塔进行的, level 参数表示金字塔的层次, level 越大可能带来越高的找图效率，但也可能造成找图失败（图片因过度缩小而无法分辨）或返回错误位置。因此，除非您清楚该参数的意义并需要进行性能调优，否则不需要用到该参数。
  • return {Point}

找图。在大图片 img 中查找小图片 template 的位置（模块匹配），找到时返回位置坐标(Point)，找不到时返回 null。 该函数也可以作为全局函数使用。 一个最简单的找图例子如下：

var img = images.read("/sdcard/大图.png");
var templ = images.read("/sdcard/小图.png");
var p = findImage(img, templ);
if (p) {
  toast("找到啦:" + p);
} else {
  toast("没找到");
}

稍微复杂点的区域找图例子如下：

auto();
requestScreenCapture();
var wx = images.read("/sdcard/微信图标.png");
//返回桌面
home();
//截图并找图
var p = findImage(captureScreen(), wx, {
  region: [0, 50],
  threshold: 0.8,
});
if (p) {
  toast("在桌面找到了微信图标啦: " + p);
} else {
  toast("在桌面没有找到微信图标");
}

images.findImageInRegion(img, template, [x, y, width, height, threshold])

区域找图的简便方法。相当于：

images.findImage(img, template, {
  region: [x, y, width, height],
  threshold: threshold,
});

该函数也可以作为全局函数使用。

images.findCircles(gray, [options])

  • gray {Image} 灰度图片

  • options {Object} 可选项包括：

    • region {Array} 找圆区域。是一个两个或四个元素的数组。(region[0], region[1])表示找圆区域的左上角；region[2]*region[3]表示找圆区域的宽高。如果只有 region 只有两个元素，则找圆区域为(region[0], region[1])到图片右下角。如果不指定region选项，则找圆区域为整张图片。
    • dp {number} dp 是累加面与原始图像相比的分辨率的反比参数，dp=2 时累计面分辨率是元素图像的一半，宽高都缩减为原来的一半，dp=1 时，两者相同。默认为 1。
    • minDst {number} minDist 定义了两个圆心之间的最小距离。默认为图片高度的八分之一。
    • param1 {number} param1 是 Canny 边缘检测的高阈值，低阈值被自动置为高阈值的一半。默认为 100，范围为 0-255。
    • param2 {number} param2 是累加平面对是否是圆的判定阈值，默认为 100。
    • minRadius {number} 定义了检测到的圆的半径的最小值，默认为 0。
    • maxRadius {number} 定义了检测到的圆的半径的最大值，0 为不限制最大值，默认为 0。

  • return {Array}

在图片中寻找圆（做霍夫圆变换）。返回包含所有圆坐标{x,y,radius}的数组，找不到时返回 null。 一个寻找圆的例子：

// 请求截图
requestScreenCapture();
// 截图
sleep(1000);
let img = captureScreen();
// 灰度化图片
let gray = images.grayscale(img);
// 找圆
let arr = images.findCircles(gray);
// 回收图片
gray.recycle();
log(arr);

images.matchTemplate(img, template, [options])

  • img {Image} 大图片
  • template {Image} 小图片（模板）
  • options {Object} 找图选项：
    • threshold {number} 图片相似度。取值范围为 0~1 的浮点数。默认值为 0.9。
    • region {Array} 找图区域。参见 findColor 函数关于 region 的说明。
    • max {number} 找图结果最大数量，默认为 5
    • level {number} 一般而言不必修改此参数。不加此参数时该参数会根据图片大小自动调整。找图算法是采用图像金字塔进行的, level 参数表示金字塔的层次, level 越大可能带来越高的找图效率，但也可能造成找图失败（图片因过度缩小而无法分辨）或返回错误位置。因此，除非您清楚该参数的意义并需要进行性能调优，否则不需要用到该参数。
  • retrun {MatchingResult}

在大图片中搜索小图片，并返回搜索结果 MatchingResult。该函数可以用于找图时找出多个位置，可以通过 max 参数控制最大的结果数量。也可以对匹配结果进行排序、求最值等操作。

MatchingResult

MatchingResult.matches

  • {Array} 匹配结果的数组,数组的元素是一个 Match 对象：
    • point {Point} 匹配位置
    • similarity {number} 相似度

例如:

var result = images.matchTemplate(img, template, {
  max: 100,
});
result.matches.forEach((match) => {
  log("point = " + match.point + ", similarity = " + match.similarity);
});

MatchingResult.points

  • retrun {Array} 匹配位置的数组。

MatchingResult.first()

  • retrun {Match}

第一个匹配结果。如果没有任何匹配，则返回null。

MatchingResult.last()

  • retrun {Match}

最后一个匹配结果。如果没有任何匹配，则返回null。

MatchingResult.leftmost()

  • retrun {Match}

位于大图片最左边的匹配结果。如果没有任何匹配，则返回null。

MatchingResult.topmost()

  • retrun {Match}

位于大图片最上边的匹配结果。如果没有任何匹配，则返回null。

MatchingResult.rightmost()

  • retrun {Match}

位于大图片最右边的匹配结果。如果没有任何匹配，则返回null。

MatchingResult.bottommost()

  • retrun {Match}

位于大图片最下边的匹配结果。如果没有任何匹配，则返回null。

MatchingResult.best()

  • retrun {Match}

相似度最高的匹配结果。如果没有任何匹配，则返回null。

MatchingResult.worst()

  • retrun {Match}

相似度最低的匹配结果。如果没有任何匹配，则返回null。

MatchingResult.sortBy(cmp)

  • cmp {Function} | {string} 比较函数，或者是一个字符串表示排序方向。方向值为：
    • left 从左往右
    • right 从右往左
    • top 从上往下
    • bottom 从下往上
  • return {MatchingResult}

对匹配结果进行排序，并返回排序后的结果。 例如"left"表示将匹配结果按匹配位置从左往右排序、"top"表示将匹配结果按匹配位置从上往下排序，"left-top"表示将匹配结果按匹配位置从左往右、从上往下排序。

var result = images.matchTemplate(img, template, {
  max: 100,
});
log(result.sortBy("top-right"));

Image

ImageWrapper类

new Image(width, height)

  • width {number} 图片宽度
  • height {number} 图片高度
  • return {Image}

新建一张空白图片。

Image.ofImage(Image)

将 Image 对象转换为 Image 对象。

Image.ofMat(Mat)

  • Mat {Mat} 矩阵
  • return {Image}

将 Mat 对象转换为 Image 对象。

Image.ofBitmap(Bitmap)

将 Bitmap 对象转换为 Image 对象。

Image.toBitmap(Image)

将 Image 对象转换为 Bitmap 对象。

Image.getMat()

  • return {Mat}

将 Image 对象转换为 Mat 对象。

Image.getBitmap()

将 Image 对象转换为 Bitmap 对象。

Image.ensureNotRecycled()

检查图片是否已经被回收，如果被回收则抛出异常。

Image.recycle()

释放图片

Image.clone()

  • return {Image}

复制图片

Image.getWidth()

返回以像素为单位图片宽度。

Image.getHeight()

返回以像素为单位的图片高度。

Image.saveTo(path)

  • path {string} 绝对路径

把图片保存到路径 path。（如果文件存在则覆盖）

Image.pixel(x, y)

  • x {number} 横坐标
  • y {number} 纵坐标

返回图片 image 在点(x, y)处的像素的 ARGB 值。 该值的格式为 0xAARRGGBB，是一个"32 位整数"(虽然 JavaScript 中并不区分整数类型和其他数值类型)。
坐标系以图片左上角为原点。以图片左侧边为 y 轴，上侧边为 x 轴。

Point

findColor, findImage 返回的对象。表示一个点（坐标）。

Point.x

横坐标。

Point.y

纵坐标。