Images

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

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

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

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

// 读取图片
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 中。如果文件不存在会被创建；文件存在会被覆盖。

//把图片压缩为原来的一半质量并保存
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 的区域，并返回该剪切区域的新图片。

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 值，则截图方向由当前设备屏幕方向决定，因此务必注意执行该函数时的屏幕方向。

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

示例:

//请求截图
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)才返回截图。

例子:

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.

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

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

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;
  }
}

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

//读取本地图片/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])

区域找色的简便方法。

相当于

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 红点的颜色来判断是否有未读消息)

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.

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

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

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

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。用于检测图片中某个位置是否是特定颜色。

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

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

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

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

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

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

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])

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

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> 相似度

例如:

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>

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

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 通道的值进行比较。

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

Images ​

图片处理 ​

images.read(path) ​

images.load(url) ​

images.copy(img) ​

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

images.fromBase64(base64) ​

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

images.fromBytes(bytes) ​

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

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

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

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

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

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

images.grayscale(img) ​

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

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

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

images.inRange(img, lowerBound, upperBound) ​

images.interval(img, color, interval) ​

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

images.medianBlur(img, size) ​

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

images.matToImage(mat) ​

找图找色 ​

images.requestScreenCapture([landscape]) ​

images.captureScreen() ​

images.captureScreen(path) ​

images.pixel(image, x, y) ​

images.findColor(image, color, options) ​

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

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

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

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

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

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

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

images.matchTemplate(img, template, options) ​

MatchingResult ​

matches ​

points ​

first() ​

last() ​

leftmost() ​

topmost() ​

rightmost() ​

bottommost() ​

best() ​

worst() ​

sortBy(cmp) ​

Image ​

Image.getWidth() ​

Image.getHeight() ​

Image.saveTo(path) ​

Image.pixel(x, y) ​

Point ​

Point.x ​

Point.y ​

Colors ​

colors.toString(color) ​

colors.red(color) ​

colors.green(color) ​

colors.blue(color) ​

colors.alpha(color) ​

colors.rgb(red, green, blue) ​

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

colors.parseColor(colorStr) ​

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

colors.equals(color1, color2) ​

colors.BLACK ​

colors.DKGRAY ​

colors.GRAY ​

colors.LTGRAY ​

colors.WHITE ​

colors.RED ​

colors.GREEN ​

colors.BLUE ​

colors.YELLOW ​

colors.CYAN ​

Images

图片处理

images.read(path)

images.load(url)

images.copy(img)

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

images.fromBase64(base64)

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

images.fromBytes(bytes)

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

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

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

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

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

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

images.grayscale(img)

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

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

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

images.inRange(img, lowerBound, upperBound)

images.interval(img, color, interval)

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

images.medianBlur(img, size)

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

images.matToImage(mat)

找图找色

images.requestScreenCapture([landscape])

images.captureScreen()

images.captureScreen(path)

images.pixel(image, x, y)

images.findColor(image, color, options)

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

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

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

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

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

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

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

images.matchTemplate(img, template, options)

MatchingResult

matches

points

first()

last()

leftmost()

topmost()

rightmost()

bottommost()

best()

worst()

sortBy(cmp)

Image

Image.getWidth()

Image.getHeight()

Image.saveTo(path)

Image.pixel(x, y)

Point

Point.x

Point.y

Colors

colors.toString(color)

colors.red(color)

colors.green(color)

colors.blue(color)

colors.alpha(color)

colors.rgb(red, green, blue)

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

colors.parseColor(colorStr)

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

colors.equals(color1, color2)

colors.BLACK

colors.DKGRAY

colors.GRAY

colors.LTGRAY

colors.WHITE

colors.RED

colors.GREEN

colors.BLUE

colors.YELLOW

colors.CYAN