找图找色
## 申请屏幕截图权限 |requestScreenCapture
| 函数名 | 返回值 | | 备注 |
| ----------------------------- | -------- | ---- | ------------------------------------------ |
| images.requestScreenCapture() | | | 向系统申请屏幕截图权限，返回是否请求成功。 |
| **参数名** | **类型** | 空 | |
| 截屏是否为横屏 | 布尔值 | ✔ | false, 则表示竖屏截图; true为横屏截图。 |
```javascript
//请求截图
if(!requestScreenCapture()){
toast("请求截图失败");
exit();
}
//连续截图10张图片(间隔1秒)并保存到存储卡目录
for(var i = 0; i < 10; i++){
captureScreen("/sdcard/screencapture" + i + ".png");
sleep(1000);
}
该函数在截图脚本中只需执行一次，而无需每次调用`captureScreen()`都调用一次。
建议在本软件界面运行该函数，在其他软件界面运行时容易出现一闪而过的黑屏现象。
```
## 截取屏幕 |captureScreen
| 函数名 | 返回值 | 备注 |
| ---------------------- | --------- | ------------------------------- |
| images.captureScreen() | Image对象 | 截取当前屏幕并返回一个Image对象 |
```javascript
//请求横屏截图
requestScreenCapture(true);
//截图
var img = captureScreen();
//获取在点(100, 100)的颜色值
var color = images.pixel(img, 100, 100);
//显示该颜色值
toast(colors.toString(color));
没有截图权限时执行该函数会抛出SecurityException。
该函数不会返回null，两次调用可能返回相同的Image对象。这是因为设备截图的更新需要一定的时间，短时间内（一般来说是16ms）连续调用则会返回同一张截图。
截图需要转换为Bitmap格式，从而该函数执行需要一定的时间(0~20ms)。
另外在requestScreenCapture()执行成功后需要一定时间后才有截图可用，因此如果立即调用captureScreen()，会等待一定时间后(一般为几百ms)才返回截图。
```
## 截取屏幕保存文件 |captureScreen
| 函数名 | 返回值 | 备注 |
| ---------------------- | -------- | ------------------------------------- |
| images.captureScreen() | | 截取当前屏幕并以PNG格式保存到path中。 |
| **参数名** | **类型** | |
| 截图保存路径 | 字符串 | |
```javascript
images.captureScreen('/sdcard/1.png');
如果文件不存在会被创建；文件存在会被覆盖。
该函数不会返回任何值。该函数也可以作为全局函数使用。
```
## 取图片单点颜色 |pixel
| 函数名 | 返回值 | 备注 |
| -------------- | -------- | ----------------------------------------- |
| images.pixel() | 整数型 | 返回图片image在点(x, y)处的像素的ARGB值。 |
| **参数名** | **类型** | |
| 图片 | Image | |
| 横坐标。 | 整数型 | 要获取的像素的横坐标 |
| 纵坐标。 | 整数型 | 要获取的像素的纵坐标。 |
```javascript
images.pixel(image, x, y)
该值的格式为0xAARRGGBB，是一个"32位整数"(虽然JavaScript中并不区分整数类型和其他数值类型)。
坐标系以图片左上角为原点。以图片左侧边为y轴，上侧边为x轴。
```
## 找色 |findColor
| 函数名 | 返回值 | 备注 |
| ------------------ | ------------- | ------------------------------------------------------------ |
| images.findColor() | 坐标 | 在图片中寻找颜色color |
| **参数名** | **类型** | |
| 图片 | Image | |
| 颜色的RGB值 | 整数型/字符串 | 如果是一个整数，则以0xRRGGBB代表RGB值（A通道会被忽略）；如果是字符串，则以"#RRGGBB"代表RGB值。 |
| 选项 | 对象 | |
选项包括：
- `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.
一个循环找色的例子如下：
```javascript
//请求截图
if(!requestScreenCapture()){
toast("请求截图失败");
exit();
}
//循环找色，找到红色(#ff0000)时停止并报告坐标
while(true){
var img = captureScreen();
var point = findColor(img, "#ff0000");
if(point){
toast("找到红色，坐标为(" + point.x + ", " + point.y + ")");
}
}
```
一个区域找色的例子如下：
```javascript
//请求截图
if(!requestScreenCapture()){
toast("请求截图失败");
exit();
}
var img = captureScreen();
//在该图片中找色，指定找色区域为在位置(400, 500)的宽为300长为200的区域，指定找色临界值为4
var point = findColor(img, "#00ff00", {
region: [400, 500, 300, 200],
threshold: 4
});
if(point){
toast("找到啦:" + point);
}else{
toast("没找到");
}
```
## 区域找色(相似) |findColorInRegion
| 函数名 | 返回值 | | 备注 |
| -------------------------- | ------------- | ------ | -------------------------- |
| images.findColorInRegion() | Point | | 区域找色的简便方法 |
| **参数名** | **类型** | **空** | |
| 图片 | Image | | |
| 要寻找的颜色 | 整数型/字符串 | | |
| 横坐标 | 整数型 | | |
| 纵坐标 | 整数型 | | |
| 区域的宽度 | 整数型 | ✔ | |
| 区域的高度 | 整数型 | ✔ | |
| 相似度 | 整数型 | ✔ | 默认为4。取值范围为0~255。 |
```javascript
//请求截图
if(!requestScreenCapture()){
toast("请求截图失败");
exit();
}
var img = captureScreen();
//在该图片中找色，指定找色区域为在位置(400, 500)的宽为300长为200的区域，指定找色临界值为4
var point = images.findColorInRegion(img,"#00ff00",400, 500, 300, 200,4);
if(point){
toast("找到啦:" + point);
}else{
toast("没找到");
}
```
## 区域找色(相等) |findColorEquals
| 函数名 | 返回值 | | 备注 |
| ------------------------ | ------------- | ---- | ------------------------------------------------------------ |
| images.findColorEquals() | Point | | 在图片img指定区域中找到颜色和color完全相等的某个点，并返回该点的左边；如果没有找到，则返回`null`。 |
| **参数名** | **类型** | 空 | |
| 图片 | Image | | |
| 要寻找的颜色 | 整数型/字符串 | | |
| 横坐标 | 整数型 | ✔ | 如果不指定找色区域，则在整张图片中寻找。 |
| 纵坐标 | 整数型 | ✔ | 如果不指定找色区域，则在整张图片中寻找。 |
| 区域的宽度 | 整数型 | ✔ | 如果不指定找色区域，则在整张图片中寻找。 |
| 区域的高度 | 整数型 | ✔ | 如果不指定找色区域，则在整张图片中寻找。 |
```javascript
//请求截图
if(!requestScreenCapture()){
toast("请求截图失败");
exit();
}
var img = captureScreen();
var point = images.findColorInRegion(img,"#00ff00");
if(point){
toast("找到啦:" + point);
}else{
toast("没找到");
}
```
## 多点找色 |findMultiColors
| 函数名 | 返回值 | | 备注 |
| ------------------------ | ------------- | ------ | ------------------------------------------------------------ |
| images.findMultiColors() | Point | | 多点找色，类似于按键精灵的多点找色，找不到时返回`null` |
| **参数名** | **类型** | **空** | |
| 图片 | Image | | |
| 第一个点的颜色 | 整数型/字符串 | | |
| 相对点 | 整数型数组 | | 相对于第一个点的位置和颜色的数组，数组的每个元素为[x, y, color] |
| 选项 | 对象 | ✔ | `region` {Array} 找色区域、`threshold` {number} 相似度 |
1. 在图片img中找到颜色firstColor的位置(x0, y0)
2. 对于数组colors的每个元素[x, y, color]，检查图片img在位置(x + x0, y + y0)上的像素是否是颜色color，是的话返回(x0, y0)，否则继续寻找firstColor的位置，重新执行第1步
3. 整张图片都找不到时返回`null`
```javascript
//请求截图
if(!requestScreenCapture()){
toast("请求截图失败");
exit();
}
var img = captureScreen();
var p = images.findMultiColors(img, "#123456", [[10, 20, "#ffffff"], [30, 40, "#000000"]]);
var p = images.findMultiColors(img, "#123456", [[10, 20, "#ffffff"], [30, 40, "#000000"]], {
region: [0, 960, 1080, 960]
threshold:5
});
```
## 单点找色 |detectsColor
| 函数名 | 返回值 | | 备注 |
| --------------------- | ------------- | :----: | ------------------------------------------------------------ |
| images.detectsColor() | Point | | 返回图片image在位置(x, y)处是否匹配到颜色color。用于检测图片中某个位置是否是特定颜色。 |
| **参数名** | **类型** | **空** | |
| 图片 | Image | | |
| 要检测的颜色 | 整数型/字符串 | | |
| 横坐标 | 整数型 | | |
| 纵坐标 | 整数型 | | |
| 相似度 | 整数型 | ✔ | 默认为16。取值范围为0~255。 |
| 匹配算法 | 字符串 | ✔ | |
```javascript
//请求截图
if(!requestScreenCapture()){
toast("请求截图失败");
exit();
}
//找到点赞控件
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();
}
```
## 找图 |findImage
| 函数名 | 返回值 | | 备注 |
| ------------------ | -------- | ------ | ------------------------------------------------------------ |
| images.findImage() | Point | | 找图。模块匹配，找到时返回位置坐标(Point)，找不到时返回null。 |
| **参数名** | **类型** | **空** | |
| 大图片 | Image | | |
| 小图片 | Image | | |
| 找图选项 | Object | ✔ | |
选项包括：
- `threshold` {number} 图片相似度。取值范围为0~1的浮点数。默认值为0.9。
- `region` {Array} 找图区域。参见findColor函数关于region的说明。
- `level` {number} **一般而言不必修改此参数**。不加此参数时该参数会根据图片大小自动调整。找图算法是采用图像金字塔进行的, level参数表示金字塔的层次, level越大可能带来越高的找图效率，但也可能造成找图失败（图片因过度缩小而无法分辨）或返回错误位置。因此，除非您清楚该参数的意义并需要进行性能调优，否则不需要用到该参数。
一个最简单的找图例子如下：
```javascript
var img = images.read("/sdcard/大图.png");
var templ = images.read("/sdcard/小图.png");
var p = findImage(img, templ);
if(p){
toast("找到啦:" + p);
}else{
toast("没找到");
}
```
稍微复杂点的区域找图例子如下：
```javascript
auto();
//请求截图
if(!requestScreenCapture()){
toast("请求截图失败");
exit();
}
var wx = images.read("/sdcard/微信图标.png");
//返回桌面
home();
//截图并找图
var p = findImage(captureScreen(), wx, {
region: [0, 50],
threshold: 0.8
});
if(p){
toast("在桌面找到了微信图标啦: " + p);
}else{
toast("在桌面没有找到微信图标");
}
```
## 区域找图(简便) |findImageInRegion
| 函数名 | 返回值 | | 备注 |
| -------------------------- | -------- | ------ | --------------------- |
| images.findImageInRegion() | Point | | 区域找图的简便方法。 |
| **参数名** | **类型** | **空** | |
| 大图片 | Image | | |
| 小图片 | Image | | |
| 横坐标 | 整数型 | | |
| 纵坐标 | 整数型 | | |
| 区域的宽度 | 整数型 | ✔ | |
| 区域的高度 | 整数型 | ✔ | |
| 图片相似度 | 浮点数 | ✔ | 取值范围为0~1的浮点数 |
```javascript
images.findImageInRegion(img, template,x, y, width, height,4)
```
## 区域找图(多位置) |matchTemplate
| 函数名 | 返回值 | 备注 |
| ---------------------- | ------------------ | -------------------------------------- |
| images.matchTemplate() | MatchingResult对象 | 找多图，并返回搜索结果MatchingResult。 |
| **参数名** | **类型** | |
| 大图片 | Image | |
| 小图片 | Image | |
| 找图选项 | Object | |
- `options` {Object} 找图选项：
- `threshold` {number} 图片相似度。取值范围为0~1的浮点数。默认值为0.9。
- `region` {Array} 找图区域。参见findColor函数关于region的说明。
- `max` {number} 找图结果最大数量，默认为5
- `level` {number} **一般而言不必修改此参数**。不加此参数时该参数会根据图片大小自动调整。找图算法是采用图像金字塔进行的, level参数表示金字塔的层次, level越大可能带来越高的找图效率，但也可能造成找图失败（图片因过度缩小而无法分辨）或返回错误位置。因此，除非您清楚该参数的意义并需要进行性能调优，否则不需要用到该参数。
```javascript
images.matchTemplate(img,template,{
region: [0, 50],
threshold: 0.8
})
```