找图找色2(文档限制)
# $images.detectAndComputeFeatures(img[, options]）
[v9.2新增]
- img {Image} 图片，要计算特征的图片
- options {object} 特征计算选项，可选参数：
1. scale {number} 计算特征时图片的缩放比例，缩放比例越小，计算特征越快，但可能因为放缩过度导致特征计算错误。对于宽度 * 高度 > 1000000的图片，scale参数默认为0.5，否则scale默认为1
1. grayscale {boolean} 是否灰度化后再计算特征，默认为true
1. method {string} 图像特征匹配的方法，默认为SIFT，也可指定为ORB（不推荐）
1. region {Array} 图像的匹配区域，不填此字段时则为整个图片计算特征
- 返回 {ImageFeatures} 保存图片特征的对象，不用时需要调用recycle()回收
对给定图片计算特征，将图片计算后的特征信息返回。该特征信息对象可用于后续使用matchFeatures函数做特征匹配。
一般而言，小图的特征可以在程序开始时就计算，在程序结束时再回收。如果每次截图时都去读取小图、计算小图特征，不仅会导致程序运行效率低，而且会导致内存碎片，从而使得内存难以利用和更快耗尽。
# $images.matchFeatures(scene, object[, options])
[v9.2新增]
- scene {ImageFeatures} 场景图片的特征对象（大图特征）
- object {ImageFeatures} 目标图片的特征对象（小图特征）
- options {object} 可选参数：
1. matcher {string} 特征匹配方式，默认为FLANNBASED，可选的值有"FLANNBASED", "BRUTEFORCE", "BRUTEFORCE_L1", "BRUTEFORCE_HAMMING", "BRUTEFORCE_HAMMINGLUT", "BRUTEFORCE_SL2"，除了FLANNBASED外其他匹配方式未经过充分测试
1. drawMatches {string} 绘制图片匹配详情的路径，若为空则不绘制匹配详情。此选项一般为调试使用，在真正匹配时请勿指定，否则会增加耗时。
1. thredshold {number} 匹配阈值，默认为0.7
- 返回 {ObjectFrame} | {null} 小图在大图中的匹配位置，若未找到则返回null
特征匹配提供了全分辨率找图功能，可以识别检测图像中明显的特征并根据特征来查找类似图片。即使图片的分辨率、形状、旋转有差异也能识别出来，但匹配速度相对较慢。
需要注意的是，计算特征的过程也比较耗时，因此请勿在每次匹配时才计算小图的特征，小图若不变可以提前计算特征并复用特征对象。
以下是一个简单的示例，也在Auto.js Pro内置示例"图片与图色处理 - 找图找色"文件夹中，可直接运行。
```
// 读取小图
let hellokitty = $images.read('./hellokitty.jpg');
// 计算小图特征
let objectFeatures = $images.detectAndComputeFeatures(hellokitty);
// 请求截图权限
requestScreenCapture();
// 打开HelloKitty图片
$app.openUrl('https://baike.baidu.com/item/Hello%20Kitty/984270')
let n = 3;
for (let i = 0; i < n; i++) {
sleep(3000);
let capture = captureScreen();
// 若要提高效率，可以在计算大图特征时调整scale参数，默认为0.5，
// 越小越快，但可以放缩过度导致匹配错误。若在特征匹配时无法搜索到正确结果，可以调整这里的参数，比如{scale: 1}
// 也可以在这里指定{region: [...]}参数只计算这个区域的特征提高效率
let sceneFeatures = $images.detectAndComputeFeatures(capture);
// 最后一次匹配时，我们将特征和匹配绘制出来，在调试时更容易看出匹配效果，但会增加耗时
let drawMatches = (i === n - 1 ? './matches.jpg' : undefined);
let result = $images.matchFeatures(sceneFeatures, objectFeatures, { drawMatches });
// 打印结果和中心点，可使用click(reuslt.centerX, result.centerY)点击
console.log(result, result ? result.center : null);
// 回收特征对象
sceneFeatures.recycle();
if (drawMatches) {
// 可以在当前目录查看matches.jpg图片，会绘制详细匹配详情
app.viewFile('./matches.jpg');
}
}
// 回收小图特征对象
objectFeatures.recycle();
hellokitty.recycle();
```
# ImageFeatures
[v9.2新增]
存储特征信息的类，仅用于特征匹配。
## ImageFeatures.recycle()
回收特征对象。必须显式在不使用该对象时调用，否则会导致内存泄露而程序崩溃。
# ObjectFrame
[v9.2新增]
特征匹配返回的结果，表示一个四边形。
## ObjectFrame.topLeft
{Point}
四边形的左上角坐标。
## ObjectFrame.topRight
{Point}
四边形的右上角坐标。
## ObjectFrame.bottomLeft
{Point}
四边形的左下角坐标。
## ObjectFrame.bottomRight
{Point}
四边形的右下角坐标。
## ObjectFrame.center
{Point}
四边形的中心点坐标。
## ObjectFrame.centerX
{number}
四边形的中心点x坐标。
## ObjectFrame.centerY
{number}
四边形的中心点y坐标。
# MatchingResult
**[v4.1.0新增]**
## 匹配结果 |matches
| 方法名 | 返回值 | 备注 |
| -------------- | -------- | ------------------------------------------------------ |
| matches | | 返回图片image在点(x, y)处的像素的ARGB值。 |
| **参数名** | **类型** | |
| 匹配结果的数组 | 数组 | `point` {Point} 匹配位置、`similarity` {number} 相似度 |
matches
* {Array} 匹配结果的数组。
数组的元素是一个Match对象：
* `point` {Point} 匹配位置
* `similarity` {number} 相似度
例如:
```javascript
var result = images.matchTemplate(img, template, {
max: 100
});
result.matches.forEach(match => {
log("point = " + match.point + ", similarity = " + match.similarity);
});
```
## 匹配位置 |points
| 方法名 | 返回值 | 备注 |
| -------------- | -------- | -------------- |
| points | | 匹配位置的数组 |
| **参数名** | **类型** | |
| 匹配位置的数组 | 数组 | |
points
* {Array} 匹配位置的数组。
## 第一个匹配结果 |first
| 方法名 | 返回值 | 备注 |
| ------- | ------ | ------------------------------------------------ |
| first() | Match | 第一个匹配结果。如果没有任何匹配，则返回`null`。 |
first()
* 返回 {Match}
第一个匹配结果。如果没有任何匹配，则返回`null`。
## 最后一个匹配结果 |last
| 方法名 | 返回值 | 备注 |
| ------ | ------ | -------------------------------------------------- |
| last() | Match | 最后一个匹配结果。如果没有任何匹配，则返回`null`。 |
last()
* 返回 {Match}
最后一个匹配结果。如果没有任何匹配，则返回`null`。
## 最左边的匹配结果 |leftmost
| 方法名 | 返回值 | 备注 |
| ---------- | ------ | ------------------------------------------------------------ |
| leftmost() | Match | 位于大图片最左边的匹配结果。如果没有任何匹配，则返回`null`。 |
leftmost()
* 返回 {Match}
位于大图片最左边的匹配结果。如果没有任何匹配，则返回`null`。
## 最上边的匹配结果 |topmost
| 方法名 | 返回值 | 备注 |
| --------- | ------ | ------------------------------------------------------------ |
| topmost() | Match | 位于大图片最上边的匹配结果。如果没有任何匹配，则返回`null`。 |
topmost()
* 返回 {Match}
位于大图片最上边的匹配结果。如果没有任何匹配，则返回`null`。
## 最右边的匹配结果 |rightmost
| 方法名 | 返回值 | 备注 |
| ----------- | ------ | ------------------------------------------------------------ |
| rightmost() | Match | 位于大图片最右边的匹配结果。如果没有任何匹配，则返回`null`。 |
rightmost()
* 返回 {Match}
位于大图片最右边的匹配结果。如果没有任何匹配，则返回`null`。
## 最下边的匹配结果 |bottommost
| 方法名 | 返回值 | 备注 |
| ------------ | ------ | ------------------------------------------------------------ |
| bottommost() | Match | 位于大图片最下边的匹配结果。如果没有任何匹配，则返回`null`。 |
bottommost()
* 返回 {Match}
位于大图片最下边的匹配结果。如果没有任何匹配，则返回`null`。
## 相似度最高的匹配结果 |best
| 方法名 | 返回值 | 备注 |
| ------ | ------ | ------------------------------------------------------ |
| best() | Match | 相似度最高的匹配结果。如果没有任何匹配，则返回`null`。 |
best()
* 返回 {Match}
相似度最高的匹配结果。如果没有任何匹配，则返回`null`。
## 相似度最低的匹配结果 |worst
| 方法名 | 返回值 | 备注 |
| ------- | ------ | ------------------------------------------------------ |
| worst() | Match | 相似度最低的匹配结果。如果没有任何匹配，则返回`null`。 |
worst()
* 返回 {Match}
相似度最低的匹配结果。如果没有任何匹配，则返回`null`。
## 对匹配结果进行排序 |sortBy
| 方法名 | 返回值 | 备注 |
| ---------- | --------------- | ------------------------------------------------------------ |
| sortBy() | Match | 对匹配结果进行排序，并返回排序后的结果。 |
| **参数名** | **类型** | |
| 比较函数 | Function/string | 比较函数，或者是一个字符串表示排序方向。例如\"left\"表示将匹配结果按匹配位置从左往右排序、\"top\"表示将匹配结果按匹配位置从上往下排序，\"left-top\"表示将匹配结果按匹配位置从左往右、从上往下排序。方向包括left（左）, top （上）, right （右）, bottom（下）。 |
sortBy(cmp)
* cmp {Function}|{string} 比较函数，或者是一个字符串表示排序方向。例如"left"表示将匹配结果按匹配位置从左往右排序、"top"表示将匹配结果按匹配位置从上往下排序，"left-top"表示将匹配结果按匹配位置从左往右、从上往下排序。方向包括`left`（左）, `top` （上）, `right` （右）, `bottom`（下）。
* {MatchingResult}
对匹配结果进行排序，并返回排序后的结果。
```javascript
var result = images.matchTemplate(img, template, {
max: 100
});
log(result.sortBy("top-right"));
```
# Image
表示一张图片，可以是截图的图片，或者本地读取的图片，或者从网络获取的图片。
## 取图片宽度 | getWidth
| 方法名 | 返回值 | 备注 |
| ---------------- | ------ | -------------------------- |
| Image.getWidth() | 整数型 | 返回以像素为单位图片宽度。 |
Image.getWidth()
返回以像素为单位图片宽度。
## 取图片高度 | getHeight
| 方法名 | 返回值 | 备注 |
| ----------------- | ------ | ---------------------------- |
| Image.getHeight() | 整数型 | 返回以像素为单位的图片高度。 |
Image.getHeight()
返回以像素为单位的图片高度。
## 图片保存 | saveTo
| 方法名 | 返回值 | 备注 |
| -------------- | -------- | -------------------------------------------- |
| Image.saveTo() | | 把图片保存到路径path。（如果文件存在则覆盖） |
| **参数名** | **类型** | |
| 路径 | 字符串 | 图片保存路径 |
Image.saveTo(path)
* `path` {string} 路径
把图片保存到路径path。（如果文件存在则覆盖）
## 取图片某点像素 | pixel
| 方法名 | 返回值 | 备注 |
| ------------- | -------- | ----------------------------------------- |
| Image.pixel() | 字符串 | 返回图片image在点(x, y)处的像素的ARGB值。 |
| **参数名** | **类型** | |
| 横坐标 | 整数型 | |
| 纵坐标 | 整数型 | |
Image.pixel(x, y)
* `x` {number} 横坐标
* `y` {number} 纵坐标
返回图片image在点(x, y)处的像素的ARGB值。
该值的格式为0xAARRGGBB，是一个"32位整数"(虽然JavaScript中并不区分整数类型和其他数值类型)。
坐标系以图片左上角为原点。以图片左侧边为y轴，上侧边为x轴。
##
# Point
findColor, findImage返回的对象。表示一个点（坐标）。
## 横坐标 | Point.x
| 方法名 | 返回值 | 备注 |
| ------- | ------ | ------ |
| Point.x | 整数型 | 横坐标 |
Point.x
横坐标。
## 纵坐标 | Point.y
| 方法名 | 返回值 | 备注 |
| ------- | ------ | ------ |
| Point.y | 整数型 | 纵坐标 |
Point.y
纵坐标。
# ColorMapping
通过颜色映射的实现一种找色方式，对于同一张图找多次色，每次找色相比images模块里的函数非常快，只是需要相比一般找色需要一个初始化过程。
注意！ColorMapping仅能使用**截图的图片对象**初始化颜色映射。
初始化方式：
```javascript
// 申请截图权限
$images.requestScreenCapture();
// 初始化ColorMapping
let ColorMapping = $colors.mapping;
// 创建ColorMapping实例
let cm = new ColorMapping();
// 截屏
let img = $images.captureScreen();
// 初始化颜色映射
cm.reset(img);
// 使用完后及时回收
cm.recycle();
```
如果不想手动回收，可以用ColorMapping的单例，这个单例会自动在脚本结束时回收。
```javascript
// 申请截图权限
$images.requestScreenCapture();
// 初始化ColorMapping
let ColorMapping = $colors.mapping;
// 创建ColorMapping实例
let cm = ColorMapping.singleton;
// 截屏
let img = $images.captureScreen();
// 初始化颜色映射
cm.reset(img);
// 找色
cm.findColor("#ffffff")
```
## ColorMapping.singleton
* `ColorMapping`
ColorMapping的全局单例对象。
## ColorMapping.reset(img)
* `img` {Image} 截图
此操作会重新初始化颜色映射的数据。
## ColorMapping.recycle()
此操作会释放ColorMapping对象。
## ColorMapping.findColor(color[, options])
* `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。threshold和浮点数相似度(0.0~1.0)的换算为 similarity = (255 - threshold) / 255 。相似度与阈值二选一，同时存在则以相似度为准。
* 返回 {Point}
在图片中寻找颜色color。找到时返回找到的点Point，找不到时返回null。
一个同一张图多次找色的例子如下：
```javascript
// 申请截图权限
$images.requestScreenCapture();
// 初始化ColorMapping
let ColorMapping = $colors.mapping;
// 创建ColorMapping实例
let cm = new ColorMapping();
// 使用ColorMapping找色
while (true) {
// 截屏
let img = $images.captureScreen();
// 初始化颜色映射
cm.reset(img);
let p1 = cm.findColor("#ffffff");
if (p1) {
// ...
console.log("白色点坐标" + p1);
continue;
}
let p2 = cm.findColor("#000000");
if (p2) {
// ...
console.log("黑色点坐标" + p2);
continue;
}
}
// 释放ColorMapping
cm.recycle();
```
一个区域找色的例子如下：
```javascript
// 申请截图权限
$images.requestScreenCapture();
// 初始化ColorMapping
let ColorMapping = $colors.mapping;
// 创建ColorMapping实例
let cm = new ColorMapping();
// 截屏
let img = $images.captureScreen();
// 初始化颜色映射
cm.reset(img);
// 使用ColorMapping找色，指定找色区域为在位置(400, 500)的宽为300长为200的区域，指定找色临界值为4
let point = cm.findColor("#00ff00", {
region: [400, 500, 300, 200],
threshold: 4
});
if(point){
toast("找到啦:" + point);
}else{
toast("没找到");
}
// 释放ColorMapping
cm.recycle();
```
## ColorMapping.findMultiColors(firstColor, colors, options)
* `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。
* 返回 {Point}
多点找色，与images.findMultiColors类似,但多次在同一张图片中找色速度极快。
一个同一张图片多次多点找色的例子：
```javascript
// 申请截图权限
$images.requestScreenCapture();
// 初始化ColorMapping
let ColorMapping = $colors.mapping;
// 创建ColorMapping实例
let cm = new ColorMapping();
// 截屏
let img = $images.captureScreen();
// 初始化颜色映射
cm.reset(img);
// 使用ColorMapping多点找色
let p1 = cm.findMultiColors("#ff00ff", [[10, 20, "#ffffff"], [30, 40, "#000000"]]);
let p2 = cm.findMultiColors("#ff00ff", [[10, 20, "#ffffff"], [30, 40, "#000000"]]);
log("p1" + p1 + "p2" + p2);
// 释放ColorMapping
cm.recycle();
```
## ColorMapping.findAllPointsForColor(color, options)
* `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。threshold和浮点数相似度(0.0~1.0)的换算为 similarity = (255 - threshold) / 255 。相似度与阈值二选一，同时存在则以相似度为准。
* 返回 {Array}
在图片中寻找所有颜色为color的点。找到时返回找到的点Point的数组，找不到时返回null。
找出所有白色点和所有黑色点的例子：
```javascript
// 申请截图权限
$images.requestScreenCapture();
// 初始化ColorMapping
let ColorMapping = $colors.mapping;
// 创建ColorMapping实例
let cm = new ColorMapping();
// 截屏
let img = $images.captureScreen();
// 初始化颜色映射
cm.reset(img);
// 使用ColorMapping多点找色
let whitePoints = cm.findAllPointsForColor("#ffffff");
let blackPoints = cm.findAllPointsForColor("#000000");
if (whitePoints != null) {
log("白色点有" + whitePoints.length + "个");
} else {
log("未找到白色点");
}
if (blackPoints != null) {
log("黑色点有" + blackPoints.length + "个");
} else {
log("未找到黑色点");
}
// 释放ColorMapping
cm.recycle();
```