更新文档

files.md

@@ -245,10 +245,10 @@ log(jsFiles);
 ## open(path[, mode = "r", encoding = "utf-8", bufferSize = 8192])
 * `path` {string} 文件路径，例如"/sdcard/1.txt"。
 * `mode` {string} 文件打开模式，包括:
-    * "r": 只读文本模式。该模式下只能对文件执行**文本**读取操作。
-    * "w": 只写文本模式。该模式下只能对文件执行**文本**覆盖写入操作。
-    * "a": 附加文本模式。该模式下将会把写入的文本附加到文件末尾。  
-    * "rw": 随机读写文本模式。该模式下将会把写入的文本附加到文件末尾。  
+    * `r`: 只读文本模式。该模式下只能对文件执行**文本**读取操作。
+    * `w`: 只写文本模式。该模式下只能对文件执行**文本**覆盖写入操作。
+    * `a`: 附加文本模式。该模式下将会把写入的文本附加到文件末尾。  
+    * `rw`: 随机读写文本模式。该模式下将会把写入的文本附加到文件末尾。  
     目前暂不支持二进制模式，随机读写模式。
 * `encoding` {string} 字符编码。
 * `bufferSize` {number} 文件读写的缓冲区大小。

floaty.md

@@ -7,19 +7,17 @@ floaty模块提供了悬浮窗的相关函数，可以在屏幕上显示自定
 setInterval(()=>{}, 1000);
 ```
 
-## floaty.checkPermission()
+# Floaty
 
-##### [4.2.17 新增]
+## floaty.checkPermission()
+**[4.2.17 新增]**
 
 - 返回 {boolean}
 
 返回当前应用是否有悬浮窗权限。（不会触发请求权限操作）
 
-
-
 ## floaty.requestPermission()
-
-##### [4.2.17 新增]
+**[4.2.17 新增]**
 
 跳转到系统的悬浮窗权限请求界面。
 
@@ -38,7 +36,7 @@ if (!floaty.checkPermission()) {
 
 * `layout` {xml} | {View} 悬浮窗界面的XML或者View
 
-指定悬浮窗的布局，创建并**显示**一个悬浮窗，返回一个`FloatyWindow`对象。
+指定悬浮窗的布局，创建并**显示**一个悬浮窗，返回一个[FloatyWindow](#floatywindow)对象。
 
 该悬浮窗自带关闭、调整大小、调整位置按键，可根据需要调用`setAdjustEnabled()`函数来显示或隐藏。
 
@@ -69,7 +67,7 @@ ui.run(function(){
 ## floaty.rawWindow(layout)
 * `layout` {xml} | {View} 悬浮窗界面的XML或者View
 
-指定悬浮窗的布局，创建并**显示**一个原始悬浮窗，返回一个`FloatyRawWindow`对象。
+指定悬浮窗的布局，创建并**显示**一个原始悬浮窗，返回一个[FloatyRawWindow](#floatyrawwindow)对象。
 
 与`floaty.window()`函数不同的是，该悬浮窗不会增加任何额外设施（例如调整大小、位置按钮），您可以根据自己需要编写任何布局。
 

images.md

@@ -9,6 +9,7 @@
 另一种是使用一个16进制的"32位整数" 0xAARRGGBB 来表示一个颜色，例如 `0xFF112233`表示颜色"#112233", `0x11223344`表示颜色"#11223344"。
 
 可以通过`colors.toString()`把颜色整数转换为字符串，通过`colors.parseColor()`把颜色字符串解析为颜色整数。
+# colors
 
 ## colors.toString(color)
 * `color` {number} 整数RGB颜色值
@@ -87,52 +88,51 @@
 log(colors.equals("#112233", "#112234"));
 log(colors.equals(0xFF112233, 0xFF223344));
 ```
-
-# colors.BLACK
+## colors.BLACK
 
 黑色，颜色值 #FF000000
 
-# colors.DKGRAY  
+## colors.DKGRAY  
 
 深灰色，颜色值 #FF444444
 
-# colors.GRAY  
+## colors.GRAY  
 
 灰色，颜色值 #FF888888
 
-# colors.LTGRAY  
+## colors.LTGRAY  
 
 亮灰色，颜色值 #FFCCCCCC
 
-# colors.WHITE  
+## colors.WHITE  
 
 白色，颜色值 #FFFFFFFF
 
-# colors.RED  
+## colors.RED  
 
 红色，颜色值 #FFFF0000
 
-# colors.GREEN  
+## colors.GREEN  
 
 绿色，颜色值 #FF00FF00
 
-# colors.BLUE  
+## colors.BLUE  
 
 蓝色，颜色值 #FF0000FF
 
-# colors.YELLOW  
+## colors.YELLOW  
 
 黄色，颜色值 #FFFFFF00
 
-# colors.CYAN  
+## colors.CYAN  
 
 青色，颜色值 #FF00FFFF
 
-# colors.MAGENTA  
+## colors.MAGENTA  
 
 品红色，颜色值 #FFFF00FF
 
-# colors.TRANSPARENT  
+## colors.TRANSPARENT  
 
 透明，颜色值 #00000000
 
@@ -442,38 +442,51 @@ images.save(clip, "/sdcard/clip.png");
 ## 找图找色
 
 ## images.requestScreenCapture([landscape])
-* `landscape` {boolean} 布尔值， 表示将要执行的截屏是否为横屏。如果landscape为false, 则表示竖屏截图; true为横屏截图。
-
-向系统申请屏幕截图权限，返回是否请求成功。
-
-第一次使用该函数会弹出截图权限请求，建议选择“总是允许”。
+- `landscape` {boolean} 截屏方向
+  - `true` 横屏截图
+  - `false` 竖屏截图
+  - 不指定值，由当前设备屏幕方向决定截图方向
+- `return` {boolean}
 
-这个函数只是申请截图权限，并不会真正执行截图，真正的截图函数是`captureScreen()`。
+向系统申请屏幕截图权限，返回是否请求成功,仅需执行一次
 
-该函数在截图脚本中只需执行一次，而无需每次调用`captureScreen()`都调用一次。
-
-**如果不指定landscape值，则截图方向由当前设备屏幕方向决定**，因此务必注意执行该函数时的屏幕方向。
-
-建议在本软件界面运行该函数，在其他软件界面运行时容易出现一闪而过的黑屏现象。  
+建议在本软件界面运行该函数，在其他软件界面运行时容易出现一闪而过的黑屏现象。
 
 示例:
 ```js
 //请求截图
+//每次使用该函数都会弹出截图权限请求，建议选择“总是允许”。
 if(!requestScreenCapture()){
     toast("请求截图失败");
     exit();
 }
-//连续截图10张图片(间隔1秒)并保存到存储卡目录
+//连续截图 10 张图片(间隔 1 秒)并保存到存储卡目录
 for(var i = 0; i < 10; i++){
     captureScreen("/sdcard/screencapture" + i + ".png");
     sleep(1000);
 }
 
+```
+```js
+//安卓版本高于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对象。
 
@@ -518,17 +531,21 @@ toast(colors.toString(color));
 
 坐标系以图片左上角为原点。以图片左侧边为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} 选项
+- `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。
 
-选项包括：
-* `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.
-
 该函数也可以作为全局函数使用。
 
 一个循环找色的例子如下：
@@ -610,6 +627,23 @@ if(p){
 }
 ```
 
+## 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`。
+
+例如找出所有白色的点：
+```js
+log(images.findAllPointsForColor(img, "#ffffff"));
+```
+
 ## images.findMultiColors(img, firstColor, colors[, options])
 * `img` {Image} 要找色的图片
 * `firstColor` {number} | {string} 第一个点的颜色
@@ -672,15 +706,13 @@ if(images.detectsColor(img, "#fed9a8", x, y)){
 ## images.findImage(img, template[, options])
 * `img` {Image} 大图片
 * `template` {Image} 小图片（模板）
-* `options` {Object} 找图选项
+* `options` {Object} 选项包括：
+  - `threshold` {number} 图片相似度。取值范围为0~1的浮点数。默认值为0.9。
+  - `region` {Array} 找图区域。参见findColor函数关于region的说明。
+  - `level` {number} **一般而言不必修改此参数**。不加此参数时该参数会根据图片大小自动调整。找图算法是采用图像金字塔进行的, level参数表示金字塔的层次, level越大可能带来越高的找图效率，但也可能造成找图失败（图片因过度缩小而无法分辨）或返回错误位置。因此，除非您清楚该参数的意义并需要进行性能调优，否则不需要用到该参数。
 
 找图。在大图片img中查找小图片template的位置（模块匹配），找到时返回位置坐标(Point)，找不到时返回null。
 
-选项包括：
-* `threshold` {number} 图片相似度。取值范围为0~1的浮点数。默认值为0.9。
-* `region` {Array} 找图区域。参见findColor函数关于region的说明。
-* `level` {number} **一般而言不必修改此参数**。不加此参数时该参数会根据图片大小自动调整。找图算法是采用图像金字塔进行的, level参数表示金字塔的层次, level越大可能带来越高的找图效率，但也可能造成找图失败（图片因过度缩小而无法分辨）或返回错误位置。因此，除非您清楚该参数的意义并需要进行性能调优，否则不需要用到该参数。
-
 该函数也可以作为全局函数使用。
 
 一个最简单的找图例子如下：
@@ -738,6 +770,41 @@ images.findImage(img, template, {
 
 在大图片中搜索小图片，并返回搜索结果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。
+
+一个寻找圆的例子：
+```js
+// 请求截图
+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
@@ -840,8 +907,6 @@ log(result.sortBy("top-right"));
 
 坐标系以图片左上角为原点。以图片左侧边为y轴，上侧边为x轴。
 
-##
-
 # Point
 
 findColor, findImage返回的对象。表示一个点（坐标）。