图片 - Images
images模块提供了一些手机设备中常见的图片处理函数，包括截图、读写图片、图片剪裁、旋转、二值化、找色找图等。
该模块分为两个部分，找图找色部分和图片处理部分。
需要注意的是，image对象创建后尽量在不使用时进行回收，同时避免循环创建大量图片。因为图片是一种占用内存比较大的资源，尽管Auto.js通过各种方式（比如图片缓存机制、垃圾回收时回收图片、脚本结束时回收所有图片）尽量降低图片资源的泄漏和内存占用，但是糟糕的代码仍然可以占用大量内存。
Image对象通过调用`recycle()`函数来回收。例如：
```javascript
// 读取图片
var img = images.read("./1.png");
//对图片进行操作
...
// 回收图片
img.recycle();
```
例外的是，`caputerScreen()`返回的图片不需要回收。
## 读取图片文件 |read
| 函数名 | 返回值 | 备注 |
| ------------- | --------- | ------------------------------------------------------- |
| images.read() | Image对象 | 读取图片文件,如果文件不存在或者文件无法解码则返回null。 |
| **参数名** | **类型** | |
| 图片路径 | 字符串 | |
```javascript
images.read('/sdcard/1.png');
```
## 读取网络图片 |load
| 函数名 | 返回值 | 备注 |
| ------------- | --------- | ------------------------------------------------------------ |
| images.load() | Image对象 | 读取URL的网络图片，如果地址不存在或者图片无法解码则返回null。 |
| **参数名** | **类型** | |
| 图片URL地址 | 字符串 | |
```javascript
images.load('http://www.baidu.com/1.png');
```
## 复制图片 |copy
| 函数名 | 返回值 | 备注 |
| ------------- | --------- | ----------------------------------------------------------- |
| images.copy() | Image对象 | 复制一张图片并返回新的副本。该函数会完全复制img对象的数据。 |
| **参数名** | **类型** | |
| 图片 | Image对象 | |
```javascript
images.copy(img);
```
## 图片转换格式 |save
| 函数名 | 返回值 | | 备注 |
| ------------- | --------- | ------ | ------------------------------------------------------------ |
| images.save() | Image对象 | | 把图片image以PNG格式保存到path中。如果文件不存在会被创建；文件存在会被覆盖。 |
| **参数名** | **类型** | **空** | |
| 图片 | Image | | |
| 路径 | 字符串 | | |
| 图片格式 | 字符串 | ✔ | png、jpeg/jpg、webp |
| 图片质量 | 整数型 | ✔ | 为0~100的整数值 |
```javascript
//把图片压缩为原来的一半质量并保存
var img = images.read("/sdcard/1.png");
images.save(img, "/sdcard/1.jpg", "jpg", 50);
app.viewFile("/sdcard/1.jpg");
```
## 解码Base64数据 |fromBase64
| 函数名 | 返回值 | 备注 |
| ------------------- | --------- | ------------------------------------------------------------ |
| images.fromBase64() | Image对象 | 解码Base64数据并返回解码后的图片Image对象。如果base64无法解码则返回`null`。 |
| **参数名** | **类型** | |
| 图片的Base64数据 | 字符串 | |
## 编码base64数据 |toBase64
| 函数名 | 返回值 | | 备注 |
| ----------------- | -------- | ---- | ------------------------------ |
| images.toBase64() | 字符串 | | 把图片编码为base64数据并返回。 |
| **参数名** | **类型** | 空 | |
| 图片 | Image | | |
| 图片格式 | 字符串 | ✔ | png、jpeg/jpg、webp |
| 图片质量 | 整数型 | ✔ | 为0~100的整数值 |
```
images.toBase64(img,"png",100)；
```
## 解码字节数组 |fromBytes
| 函数名 | 返回值 | 备注 |
| ------------------ | --------- | ------------------------------------------------------------ |
| images.fromBytes() | Image对象 | 解码字节数组bytes并返回解码后的图片Image对象。如果bytes无法解码则返回`null`。 |
| **参数名** | **类型** | |
| 字节数组 | 字节数组 | |
```javascript
images.fromBytes(bytes);
```
## 编码字节数组 |toBytes
| 函数名 | 返回值 | | 备注 |
| ---------------- | -------- | ------ | ---------------------------- |
| images.toBytes() | 字节数组 | | 把图片编码为字节数组并返回。 |
| **参数名** | **类型** | **空** | |
| 图片 | Image | | |
| 图片格式 | 字符串 | ✔ | png、jpeg/jpg、webp |
| 图片质量 | 整数型 | ✔ | 为0~100的整数值 |
```javascript
images.toBytes(img,"png",100)；
```
## 剪切区域图片 |clip
| 函数名 | 返回值 | 备注 |
| ---------------------- | --------- | ------------------------------------------------------------ |
| images.clip() | Image对象 | 从图片img的位置(x, y)处剪切大小为w * h的区域，并返回该剪切区域的新图片。 |
| **参数名** | **类型** | |
| 图片 | Image | |
| 剪切区域的左上角横坐标 | 整数型 | |
| 剪切区域的左上角纵坐标 | 整数型 | |
| 剪切区域的宽度 | 整数型 | |
| 剪切区域的高度 | 整数型 | |
```javascript
var src = images.read("/sdcard/1.png");
var clip = images.clip(src, 100, 100, 400, 400);
images.save(clip, "/sdcard/clip.png");
```
## 调整图片大小 |resize
| 函数名 | 返回值 | | 备注 |
| --------------- | ---------- | ------ | ------------------------------------------------------------ |
| images.resize() | Image对象 | | 调整图片大小 |
| **参数名** | **类型** | **空** | |
| 图片 | Image | | |
| 宽高数组 | 整数型数组 | | 两个元素的数组[w, h]，分别表示宽度和高度；如果只有一个元素，则宽度和高度相等。 |
| 插值方法 | 字符串 | ✔ | 默认为"LINEAR 、NEAREST 最近邻插值、LINEAR 线性插值（默认）、AREA 区域插值、CUBIC 三次样条插值、LANCZOS4 Lanczos插值 参见InterpolationFlags |
```javascript
images.resize(img, 200, 300)； //把图片放缩为200*300：。
```
## 缩放图片 |scale
| 函数名 | 返回值 | | 备注 |
| -------------- | --------- | ------ | ------------------------------------------------------------ |
| images.scale() | Image对象 | | 放缩图片，并返回放缩后的图片 |
| **参数名** | **类型** | **空** | |
| 图片 | Image | | |
| 宽度放缩倍数 | 整数型 | | |
| 高度放缩倍数 | 整数型 | | |
| 插值方法 | 字符串 | ✔ | 默认为"LINEAR 、NEAREST 最近邻插值、LINEAR 线性插值（默认）、AREA 区域插值、CUBIC 三次样条插值、LANCZOS4 Lanczos插值 参见InterpolationFlags |
```javascript
images.scale(img, 0.5, 0.5)； //把图片变成原来的一半
```
## 旋转图片 |rotate
| 函数名 | 返回值 | | 备注 |
| ----------------------------------- | --------- | ------ | ------------------------------------------------- |
| images.rotate(img, degress[, x, y]) | Image对象 | | 将图片逆时针旋转degress度，返回旋转后的图片对象。 |
| **参数名** | **类型** | **空** | |
| 图片 | Image | | |
| 旋转角度 | 整数型 | | |
| 旋转中心x坐标 | 整数型 | ✔ | 默认为图片中点 |
| 旋转中心y坐标 | 整数型 | ✔ | 默认为图片中点 |
```javascript
images.rotate(img, 90); //逆时针旋转90度为
```
## 灰度化图片 |grayscale
| 函数名 | 返回值 | 备注 |
| ------------------ | --------- | ---------------------------------- |
| images.grayscale() | Image对象 | 灰度化图片，并返回灰度化后的图片。 |
| **参数名** | **类型** | |
| 图片 | Image | |
```javascript
images.grayscale(img);
```
## 图片阈值化 |threshold
| 函数名 | 返回值 | | 备注 |
| ----------------- | --------- | ---- | ------------------------------------------------------------ |
| image.threshold() | Image对象 | | 将图片阈值化，并返回处理后的图像 |
| **参数名** | **类型** | 空 | |
| 图片 | Image | | |
| 阈值 | 整数型 | | |
| 最大值 | 整数型 | | |
| 阈值化类型 | 字符串 | ✔ | 默认为"BINARY"、参见[ThresholdTypes](https://docs.opencv.org/3.4.4/d7/d1b/group__imgproc__misc.html#gaa9e58d2860d4afa658ef70a9b1115576), 可选的值: |
```javascript
images.threshold(img, 100, 255, "BINARY")； //这个代码将图片中大于100的值全部变成255，其余变成0，从而达到二值化的效果
可以用这个函数进行图片二值化。如果img是一张灰度化图片，这个代码将会得到一张黑白图片。
```
可以参考有关博客（比如[threshold函数的使用](https://blog.csdn.net/u012566751/article/details/77046445)）或者OpenCV文档[threshold](https://docs.opencv.org/3.4.4/d7/d1b/group__imgproc__misc.html#gae8a4a146d1ca78c626a53577199e9c57)。
## 图片自适应阈值化 |adaptiveThreshold
| 函数名 | 返回值 | 备注 |
| -------------------------- | --------- | ------------------------------------------------ |
| images.adaptiveThreshold() | Image对象 | 对图片进行自适应阈值化处理，并返回处理后的图像。 |
| **参数名** | **类型** | |
| 图片 | Image | |
| 最大值 | 整数型 | |
| 阈值算法 | 字符串 | MEAN_C、GAUSSIAN_C |
| 阈值化类型 | 字符串 | BINARY、BINARY_INV |
| 邻域块大小 | 整数型 | |
| 偏移值调整量 | 整数型 | |
```javascript
images.adaptiveThreshold(img, maxValue, adaptiveMethod, thresholdType, blockSize, C)；
```
可以参考有关博客（比如[threshold与adaptiveThreshold](https://blog.csdn.net/guduruyu/article/details/68059450)）或者OpenCV文档[adaptiveThreshold](https://docs.opencv.org/3.4.4/d7/d1b/group__imgproc__misc.html#ga72b913f352e4a1b1b397736707afcde3)。
## 图像颜色空间转换 |cvtColor
| 函数名 | 返回值 | | 备注 |
| ---------------------- | --------- | ---- | ------------------------------------------------ |
| images.cvtColor() | Image对象 | | 对图像进行颜色空间转换，并返回转换后的图像。 |
| **参数名** | **类型** | 空 | |
| 图片 | Image | | |
| 颜色空间转换的类型 | 字符串 | | `BGR2GRAY` BGR转换为灰度、`BGR2HSV` BGR转换为HSV |
| 目标图像的颜色通道数量 | 整数型 | ✔ | 如果不填写则根据其他参数自动决定。 |
```javascript
images.cvtColor(img, code, dstCn);
```
可以参考有关博客（比如[颜色空间转换](https://blog.csdn.net/u011574296/article/details/70896811?locationNum=14&fps=1)）或者OpenCV文档[cvtColor](https://docs.opencv.org/3.4.4/d8/d01/group__imgproc__color__conversions.html#ga397ae87e1288a81d2363b61574eb8cab)。
## 图片二值化 |inRange
| 函数名 | 返回值 | 备注 |
| ---------------- | ------------- | ------------ |
| images.inRange() | Image对象 | 将图片二值化 |
| **参数名** | **类型** | |
| 图片 | Image | |
| 颜色下界 | 字符串/整数型 | |
| 颜色上界 | 字符串/整数型 | |
```javascript
images.inRange(img, "#000000", "#222222");
在lowerBound~upperBound范围以外的颜色都变成0，在范围以内的颜色都变成255。
```
## 图片二值化 |interval
| 函数名 | 返回值 | 备注 |
| ------------------------------------- | ------------- | ------------ |
| images.interval(img, color, interval) | Image对象 | 将图片二值化 |
| **参数名** | **类型** | |
| 图片 | Image | |
| 颜色值 | 字符串/整数型 | |
| 每个通道的范围间隔 | 整数型 | |
```javascript
//每个通道的颜色值均为0x88，加减16后的范围是[0x78, 0x98]，因此这个代码将把#787878~#989898的颜色变成#FFFFFF，而把这个范围以外的变成#000000。
images.interval(img, "#888888", 16);
在color-interval ~ color+interval范围以外的颜色都变成0，在范围以内的颜色都变成255。这里对color的加减是对每个通道而言的。
```
## 图像进行模糊 |blur
| 函数名 | 返回值 | | 备注 |
| ---------------------- | ---------- | :--: | ---------------------------------------------- |
| images.blur() | Image对象 | | 对图像进行模糊（平滑处理），返回处理后的图像。 |
| **参数名** | **类型** | 空 | |
| 图片 | Image | | |
| 定义滤波器的大小 | 整数型数组 | | 如[3, 3] |
| 指定锚点位置(被平滑点) | 整数型数组 | ✔ | 默认为图像中心 |
| 推断边缘像素类型 | 字符串 | ✔ | 默认为"DEFAULT" |
```javascript
images.blur(img, size, anchor, type)
```
- **推断边缘像素类型** 可选的值有
- `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
可以参考有关博客（比如[实现图像平滑处理](https://www.cnblogs.com/denny402/p/3848316.html)）或者OpenCV文档[blur](https://docs.opencv.org/3.4.4/d4/d86/group__imgproc__filter.html#ga8c45db9afe636703801b0b2e440fce37)。
## 图像中值滤波 |medianBlur
| 函数名 | 返回值 | 备注 |
| ------------------- | ---------- | -------------------------------------- |
| images.medianBlur() | Image对象 | 对图像进行中值滤波，返回处理后的图像。 |
| **参数名** | **类型** | |
| 图片 | Image | |
| 定义滤波器的大小 | 整数型数组 | 如[3, 3] |
```javascript
images.medianBlur(img, size)
```
可以参考有关博客（比如[实现图像平滑处理](https://www.cnblogs.com/denny402/p/3848316.html)）或者OpenCV文档[blur](https://docs.opencv.org/3.4.4/d4/d86/group__imgproc__filter.html#ga564869aa33e58769b4469101aac458f9)。
## 图像高斯模糊 |gaussianBlur
| 函数名 | 返回值 | | 备注 |
| --------------------- | ---------- | :--: | -------------------------------------- |
| images.gaussianBlur() | Image对象 | | 对图像进行高斯模糊，返回处理后的图像。 |
| **参数名** | **类型** | 空 | |
| 图片 | Image | | |
| 定义滤波器的大小 | 整数型数组 | | 如[3, 3] |
| x方向的标准方差 | 整数型 | ✔ | 不填写则自动计算 |
| y方向的标准方差 | 整数型 | ✔ | 不填写则自动计算 |
| 推断边缘像素类型 | 字符串 | ✔ | 默认为"DEFAULT"，参见`images.blur` |
```javascript
images.gaussianBlur(img, size, sigmaX, sigmaY, type)
```
可以参考有关博客（比如[实现图像平滑处理](https://www.cnblogs.com/denny402/p/3848316.html)）或者OpenCV文档[GaussianBlur](https://docs.opencv.org/3.4.4/d4/d86/group__imgproc__filter.html#gaabe8c836e97159a9193fb0b11ac52cf1)。
## Mat对象转Image对象 |matToImage
| 函数名 | 返回值 | 备注 |
| ---------------------- | --------- | -------------------------- |
| images.matToImage(mat) | Image对象 | 把Mat对象转换为Image对象。 |
| **参数名** | **类型** | |
| OpenCV的Mat对象 | Mat | |
```javascript
images.matToImage(mat);
```