Skip to content

Images

images 模块提供了一些手机设备中常见的图片处理函数,包括截图、读写图片、图片剪裁、旋转、二值化、找色找图等。

该模块分为两个部分,找图找色部分和图片处理部分。

需要注意的是,image 对象创建后尽量在不使用时进行回收,同时避免循环创建大量图片。因为图片是一种占用内存比较大的资源,尽管 Hamibot 通过各种方式(比如图片缓存机制、垃圾回收时回收图片、脚本结束时回收所有图片)尽量降低图片资源的泄漏和内存占用,但是糟糕的代码仍然可以占用大量内存。

Image 对象通过调用recycle()函数来回收。例如:

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

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

图片处理

images.read(path)

  • path <String> 图片路径

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

images.load(url)

  • url <String> 图片 URL 地址

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

images.copy(img)

  • img <Image> 图片
  • 返回 <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 中。如果文件不存在会被创建;文件存在会被覆盖。

js
//把图片压缩为原来的一半质量并保存
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 数据
  • 返回 <Image>

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

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

  • image <Image> 图片
  • format <String> 图片格式,可选的值为:
    • png
    • jpeg/jpg
    • webp
  • quality <Number> 图片质量,为 0~100 的整数值
  • 返回 <String>

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

images.fromBytes(bytes)

  • bytes <byte[]> 字节数组

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

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

  • image <Image> 图片
  • format <String> 图片格式,可选的值为:
    • png
    • jpeg/jpg
    • webp
  • quality <Number> 图片质量,为 0~100 的整数值
  • 返回 <byte[]>

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

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

  • img <Image> 图片
  • x <Number> 剪切区域的左上角横坐标
  • y <Number> 剪切区域的左上角纵坐标
  • w <Number> 剪切区域的宽度
  • h <Number> 剪切区域的高度
  • 返回 <Image>

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

js
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"(线性插值),可选的值有:

    • NEAREST 最近邻插值
    • LINEAR 线性插值(默认)
    • AREA 区域插值
    • CUBIC 三次样条插值
    • LANCZOS4 Lanczos 插值 参见 InterpolationFlags
  • 返回 <Image>

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

参见 Imgproc.resize

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

  • img <Image> 图片

  • fx <Number> 宽度放缩倍数

  • fy <Number> 高度放缩倍数

  • interpolation <String> 插值方法,可选,默认为"LINEAR"(线性插值),可选的值有:

    • NEAREST 最近邻插值
    • LINEAR 线性插值(默认)
    • AREA 区域插值
    • CUBIC 三次样条插值
    • LANCZOS4 Lanczos 插值 参见 InterpolationFlags
  • 返回 <Image>

放缩图片,并返回放缩后的图片。例如把图片变成原来的一半:images.scale(img, 0.5, 0.5)

参见 Imgproc.resize

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

  • img <Image> 图片
  • degress <Number> 旋转角度。
  • x <Number> 旋转中心 x 坐标,默认为图片中点
  • y <Number> 旋转中心 y 坐标,默认为图片中点
  • 返回 <Image>

将图片逆时针旋转 degress 度,返回旋转后的图片对象。

例如逆时针旋转 90 度为images.rotate(img, 90)

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

  • img1 <Image> 图片 1
  • img2 <Image> 图片 2
  • direction <String> 连接方向,默认为"RIGHT",可选的值有:
    • LEFT 将图片 2 接到图片 1 左边
    • RIGHT 将图片 2 接到图片 1 右边
    • TOP 将图片 2 接到图片 1 上边
    • BOTTOM 将图片 2 接到图片 1 下边
  • 返回 <Image>

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

images.grayscale(img)

  • img <Image> 图片
  • 返回 <Image>

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

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

  • img <Image> 图片

  • threshold <Number> 阈值

  • maxVal <Number> 最大值

  • type <String> 阈值化类型,默认为"BINARY",参见 ThresholdTypes, 可选的值:

    • BINARY
    • BINARY_INV
    • TRUNC
    • TOZERO
    • TOZERO_INV
    • OTSU
    • TRIANGLE
  • 返回 <Image>

将图片阈值化,并返回处理后的图像。可以用这个函数进行图片二值化。例如:images.threshold(img, 100, 255, "BINARY"),这个代码将图片中大于 100 的值全部变成 255,其余变成 0,从而达到二值化的效果。如果 img 是一张灰度化图片,这个代码将会得到一张黑白图片。

可以参考有关博客(比如threshold 函数的使用)或者 OpenCV 文档threshold

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> 偏移值调整量
  • 返回 <Image>

对图片进行自适应阈值化处理,并返回处理后的图像。

可以参考有关博客(比如threshold 与 adaptiveThreshold)或者 OpenCV 文档adaptiveThreshold

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

  • img <Image> 图片

  • code <String> 颜色空间转换的类型,可选的值有一共有 205 个(参见 ColorConversionCodes),这里只列出几个:

    • BGR2GRAY BGR 转换为灰度
    • BGR2HSV BGR 转换为 HSV
  • dstCn <Number> 目标图像的颜色通道数量,如果不填写则根据其他参数自动决定。

  • 返回 <Image>

对图像进行颜色空间转换,并返回转换后的图像。

可以参考有关博客(比如颜色空间转换)或者 OpenCV 文档cvtColor

images.inRange(img, lowerBound, upperBound)

  • img <Image> 图片
  • lowerBound <String> | <Number> 颜色下界
  • upperBound <String> | <Number> 颜色下界
  • 返回 <Image>

将图片二值化,在 lowerBound~upperBound 范围以外的颜色都变成 0,在范围以内的颜色都变成 255。

例如images.inRange(img, "#000000", "#222222")

images.interval(img, color, interval)

  • img <Image> 图片
  • color <String> | <Number> 颜色值
  • interval <Number> 每个通道的范围间隔
  • 返回 <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
  • 返回 <Image>

对图像进行模糊(平滑处理),返回处理后的图像。

可以参考有关博客(比如实现图像平滑处理)或者 OpenCV 文档blur

images.medianBlur(img, size)

  • img <Image> 图片
  • size <Array> 定义滤波器的大小,如[3, 3]
  • 返回 <Image>

对图像进行中值滤波,返回处理后的图像。

可以参考有关博客(比如实现图像平滑处理)或者 OpenCV 文档blur

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

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

对图像进行高斯模糊,返回处理后的图像。

可以参考有关博客(比如实现图像平滑处理)或者 OpenCV 文档GaussianBlur

images.matToImage(mat)

  • mat <Mat> OpenCV 的 Mat 对象
  • 返回 <Image>

把 Mat 对象转换为 Image 对象。

找图找色

images.requestScreenCapture([landscape])

  • landscape <Boolean> 布尔值, 表示将要执行的截屏是否为横屏。如果 landscape 为 false, 则表示竖屏截图; true 为横屏截图。

向系统申请屏幕截图权限,返回是否请求成功。

第一次使用该函数会弹出截图权限请求,建议选择“总是允许”。

这个函数只是申请截图权限,并不会真正执行截图,真正的截图函数是captureScreen()

该函数在截图脚本中只需执行一次,而无需每次调用captureScreen()都调用一次。

如果不指定 landscape 值,则截图方向由当前设备屏幕方向决定,因此务必注意执行该函数时的屏幕方向。

建议在本软件界面运行该函数,在其他软件界面运行时容易出现一闪而过的黑屏现象。

示例:

js
//请求截图
auto.waitFor();
if (!requestScreenCapture()) {
  toastLog('没有授予 Hamibot 屏幕截图权限');
  hamibot.exit();
}
//连续截图10张图片(间隔1秒)并保存到存储卡目录
for (var i = 0; i < 10; i++) {
  captureScreen('/sdcard/screencapture' + i + '.png');
  sleep(1000);
}

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

images.captureScreen()

截取当前屏幕并返回一个 Image 对象。

没有截图权限时执行该函数会抛出 SecurityException。

该函数不会返回 null,两次调用可能返回相同的 Image 对象。这是因为设备截图的更新需要一定的时间,短时间内(一般来说是 16ms)连续调用则会返回同一张截图。

截图需要转换为 Bitmap 格式,从而该函数执行需要一定的时间(0~20ms)。

另外在 requestScreenCapture()执行成功后需要一定时间后才有截图可用,因此如果立即调用 captureScreen(),会等待一定时间后(一般为几百 ms)才返回截图。

例子:

js
auto.waitFor();
//请求横屏截图
if (!requestScreenCapture(true)) {
  toastLog('没有授予 Hamibot 屏幕截图权限');
  hamibot.exit();
}
sleep(1000);
//截图
var img = captureScreen();
//获取在点(100, 100)的颜色值
var color = images.pixel(img, 100, 100);
//显示该颜色值
toastLog(colors.toString(color));
hamibot.exit();

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

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.findColor(image, color, options)

  • image <Image> 图片
  • color <Number> | <String> 要寻找的颜色的 RGB 值。如果是一个整数,则以 0xRRGGBB 的形式代表 RGB 值(A 通道会被忽略);如果是字符串,则以"#RRGGBB"代表其 RGB 值。
  • options <Object> 选项

在图片中寻找颜色 color。找到时返回找到的点 Point,找不到时返回 null。

选项包括:

  • 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.

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

一个循环找色的例子如下:

js
auto.waitFor();
if (!requestScreenCapture()) {
  toastLog('没有授予 Hamibot 屏幕截图权限');
  hamibot.exit();
}
sleep(1000);
//循环找色,找到红色(#ff0000)时停止并报告坐标
while (true) {
  var img = captureScreen();
  var point = findColor(img, '#ff0000');
  if (point) {
    toastLog('找到红色,坐标为(' + point.x + ', ' + point.y + ')');
    break;
  }
}

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

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

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

区域找色的简便方法。

相当于

js
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> 找色区域的高度
  • 返回 <Point>

在图片 img 指定区域中找到颜色和 color 完全相等的某个点,并返回该点的左边;如果没有找到,则返回null

找色区域通过x, y, width, height指定,如果不指定找色区域,则在整张图片中寻找。

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

示例: (通过找 QQ 红点的颜色来判断是否有未读消息)

js
auto.waitFor();
if (!requestScreenCapture()) {
  toastLog('没有授予 Hamibot 屏幕截图权限');
  hamibot.exit();
}
sleep(1000);
launchApp('QQ');
sleep(5000);
var p = findColorEquals(captureScreen(), '#f64d30');
if (p) {
  toastLog('有未读消息');
} else {
  toastLog('没有未读消息');
}

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.

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

  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 中指定,例如:

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

【完整示例】寻找 Hamibot 图标并点击打开

js
auto.waitFor();
if (!requestScreenCapture()) {
  toastLog('没有授予 Hamibot 屏幕截图权限');
  hamibot.exit();
}
sleep(1000);
var img = captureScreen();
var p = images.findMultiColors(
  img,
  '#0052CC',
  [
    [5, 5, '#0052CC'],
    [10, 10, '#0052CC'],
  ],
  {
    // region: [0, 960, 1080, 960],
    // threshold: 4,
  }
);
if (p) {
  toastLog('找到啦:' + p);
  click(p.x, p.y);
} else {
  toastLog('没找到');
}
hamibot.exit();

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

  • image <Image> 图片

  • color <Number> | <String> 要检测的颜色

  • x <Number> 要检测的位置横坐标

  • y <Number> 要检测的位置纵坐标

  • threshold <Number> 颜色相似度临界值,默认为 16。取值范围为 0~255。

  • algorithm <String> 颜色匹配算法,包括:

    • "equal": 相等匹配,只有与给定颜色 color 完全相等时才匹配。

    • "diff": 差值匹配。与给定颜色的 R、G、B 差的绝对值之和小于 threshold 时匹配。

    • "rgb": rgb 欧拉距离相似度。与给定颜色 color 的 rgb 欧拉距离小于等于 threshold 时匹配。

    • "rgb+": 加权 rgb 欧拉距离匹配(LAB Delta E)。

    • "hs": hs 欧拉距离匹配。hs 为 HSV 空间的色调值。

返回图片 image 在位置(x, y)处是否匹配到颜色 color。用于检测图片中某个位置是否是特定颜色。

一个判断微博客户端的某个微博是否被点赞过的例子:

js
auto.waitFor();
if (!requestScreenCapture()) {
  toastLog('没有授予 Hamibot 屏幕截图权限');
  hamibot.exit();
}
sleep(1000);
//找到点赞控件
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> 找图选项

找图。在大图片 img 中查找小图片 template 的位置(模块匹配),找到时返回位置坐标(Point),找不到时返回 null。

选项包括:

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

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

一个最简单的找图例子如下:

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

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

js
auto.waitFor();
if (!requestScreenCapture()) {
  toastLog('没有授予 Hamibot 屏幕截图权限');
  hamibot.exit();
}
sleep(1000);
var wx = images.read('/sdcard/微信图标.png');
//返回桌面
home();
//截图并找图
var p = findImage(captureScreen(), wx, {
  region: [0, 50],
  threshold: 0.8,
});
if (p) {
  toastLog('在桌面找到了微信图标啦:' + p);
} else {
  toastLog('在桌面没有找到微信图标');
}
hamibot.exit();

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

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

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

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

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 越大可能带来越高的找图效率,但也可能造成找图失败(图片因过度缩小而无法分辨)或返回错误位置。因此,除非您清楚该参数的意义并需要进行性能调优,否则不需要用到该参数。
  • 返回 <MatchingResult>

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

MatchingResult

matches

  • <Array> 匹配结果的数组。

数组的元素是一个 Match 对象:

  • point <Point> 匹配位置
  • similarity <Number> 相似度

例如:

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

points

  • <Array> 匹配位置的数组。

first()

  • 返回 <Match>

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

last()

  • 返回 <Match>

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

leftmost()

  • 返回 <Match>

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

topmost()

  • 返回 <Match>

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

rightmost()

  • 返回 <Match>

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

bottommost()

  • 返回 <Match>

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

best()

  • 返回 <Match>

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

worst()

  • 返回 <Match>

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

sortBy(cmp)

  • cmp <Function>|<String> 比较函数,或者是一个字符串表示排序方向。例如"left"表示将匹配结果按匹配位置从左往右排序、"top"表示将匹配结果按匹配位置从上往下排序,"left-top"表示将匹配结果按匹配位置从左往右、从上往下排序。方向包括left(左), top (上), right (右), bottom(下)。
  • <MatchingResult>

对匹配结果进行排序,并返回排序后的结果。

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

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

纵坐标。


Colors

在 Hamibot 有两种方式表示一个颜色。

一种是使用一个字符串"#AARRGGBB"或"#RRGGBB",其中 AA 是 Alpha 通道(透明度)的值,RR 是 R 通道(红色)的值,GG 是 G 通道(绿色)的值,BB 是 B 通道(蓝色)的值。例如"#ffffff"表示白色, "#7F000000"表示半透明的黑色。

另一种是使用一个 16 进制的"32 位整数" 0xAARRGGBB 来表示一个颜色,例如 0xFF112233表示颜色"#112233", 0x11223344表示颜色"#11223344"。

可以通过colors.toString()把颜色整数转换为字符串,通过colors.parseColor()把颜色字符串解析为颜色整数。

colors.toString(color)

  • color <Number> 整数 RGB 颜色值
  • 返回 <String>

返回颜色值的字符串,格式为 "#AARRGGBB"。

colors.red(color)

  • color <Number> | <String> 颜色值
  • 返回 <Number>

返回颜色 color 的 R 通道的值,范围 0~255.

colors.green(color)

  • color <Number> | <String> 颜色值
  • 返回 <Number>

返回颜色 color 的 G 通道的值,范围 0~255.

colors.blue(color)

  • color <Number> | <String> 颜色值
  • 返回 <Number>

返回颜色 color 的 B 通道的值,范围 0~255.

colors.alpha(color)

  • color <Number> | <String> 颜色值
  • 返回 <Number>

返回颜色 color 的 Alpha 通道的值,范围 0~255.

colors.rgb(red, green, blue)

  • red <Number> 颜色的 R 通道的值
  • blue <Number> 颜色的 G 通道的值
  • green <Number> 颜色的 B 通道的值
  • 返回 <Number>

返回这些颜色通道构成的整数颜色值。Alpha 通道将是 255(不透明)。

colors.argb(alpha, red, green, blue)

  • alpha <Number> 颜色的 Alpha 通道的值
  • red <Number> 颜色的 R 通道的值
  • green <Number> 颜色的 G 通道的值
  • blue <Number> 颜色的 B 通道的值
  • 返回 <Number>

返回这些颜色通道构成的整数颜色值。

colors.parseColor(colorStr)

  • colorStr <String> 表示颜色的字符串,例如"#112233"
  • 返回 <Number>

返回颜色的整数值。

colors.isSimilar(color2, color2[, threshold, algorithm])

  • color1 <Number> | <String> 颜色值 1
  • color1 <Number> | <String> 颜色值 2
  • threshold <Number> 颜色相似度临界值,默认为 4。取值范围为 0~255。这个值越大表示允许的相似程度越小,如果这个值为 0,则两个颜色相等时该函数才会返回 true。
  • algorithm <String> 颜色匹配算法,默认为"diff", 包括:
    • "diff": 差值匹配。与给定颜色的 R、G、B 差的绝对值之和小于 threshold 时匹配。
    • "rgb": rgb 欧拉距离相似度。与给定颜色 color 的 rgb 欧拉距离小于等于 threshold 时匹配。
    • "rgb+": 加权 rgb 欧拉距离匹配(LAB Delta E)。
    • "hs": hs 欧拉距离匹配。hs 为 HSV 空间的色调值。
  • 返回 <Boolean>

返回两个颜色是否相似。

colors.equals(color1, color2)

  • color1 <Number> | <String> 颜色值 1
  • color1 <Number> | <String> 颜色值 2
  • 返回 <Boolean>

返回两个颜色是否相等。*注意该函数会忽略 Alpha 通道的值进行比较

js
log(colors.equals('#112233', '#112234'));
log(colors.equals(0xff112233, 0xff223344));

colors.BLACK

黑色,颜色值 #FF000000

colors.DKGRAY

深灰色,颜色值 #FF444444

colors.GRAY

灰色,颜色值 #FF888888

colors.LTGRAY

亮灰色,颜色值 #FFCCCCCC

colors.WHITE

白色,颜色值 #FFFFFFFF

colors.RED

红色,颜色值 #FFFF0000

colors.GREEN

绿色,颜色值 #FF00FF00

colors.BLUE

蓝色,颜色值 #FF0000FF

colors.YELLOW

黄色,颜色值 #FFFFFF00

colors.CYAN

青色,颜色值 #FF00FFFF

colors.MAGENTA

品红色,颜色值 #FFFF00FF

colors.TRANSPARENT

透明,颜色值 #00000000