colors

稳定性: 稳定

在Auto.js有两种方式表示一个颜色。

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

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

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

colors

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

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

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

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

[v4.1.0新增]

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

[v4.1.0新增]

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

[v4.1.0新增]

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

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

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

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

[v4.1.0新增]

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)

[v4.1.0新增]

img {Image} 图片
返回 {Image}

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

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

[v4.1.0新增]

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)

[v4.1.0新增]

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

[v4.1.0新增]

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

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

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

images.inRange(img, lowerBound, upperBound)

[v4.1.0新增]

img {Image} 图片
lowerBound {string} | {number} 颜色下界
upperBound {string} | {number} 颜色下界
返回 {Image}

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

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

images.interval(img, color, interval)

[v4.1.0新增]

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

[v4.1.0新增]

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)

[v4.1.0新增]

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

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

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

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

[v4.1.0新增]

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

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

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

images.matToImage(mat)

[v4.1.0新增]

mat {Mat} OpenCV的Mat对象
返回 {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选项，则找色区域为整张图片。
- threshold {number} 找色时颜色相似度的临界值，范围为0~~255（越小越相似，0为颜色相等，255为任何颜色都能匹配）。默认为4。threshold和浮点数相似度(0.0~~1.0)的换算为 similarity = (255 - threshold) / 255.

在图片中寻找颜色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} 找色区域的高度
返回 {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.

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

在图片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]
});

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

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

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

找图。在大图片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.matchTemplate(img, template, options)

[v4.1.0新增]

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参数控制最大的结果数量。也可以对匹配结果进行排序、求最值等操作。

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();
// 截图
let img = captureScreen();
// 灰度化图片
let gray = images.grayscale(img);
// 找圆
let arr = findCircles(gray, {
    dp: 1,
    minDst: 80,
    param1: 100,
    param2: 100,
    minRadius: 50,
    maxRadius: 80,
});
// 回收图片
gray.recycle();

MatchingResult

[v4.1.0新增]

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

纵坐标。

Files

images.md

Latest commit

History

images.md

File metadata and controls

colors

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

colors.MAGENTA

colors.TRANSPARENT

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.readPixels(path)

images.findColor(image, color, options)

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

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

images.findAllPointsForColor(img, color, options)

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

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)

images.findCircles(gray, options)

MatchingResult

matches

points

first()

last()

leftmost()

topmost()

rightmost()

bottommost()