image - 图片处理

2022/10/22约 2884 字大约 10 分钟老猫

image 模块主要提供图片读写、灰度化、剪切、缩放、模板匹配等图像处理函数，其主要 API 在本页展示的函数以及 Image 类。

类似 Pro 8 中截图函数已迁移到 media_projection 模块。另外，要直接使用 opencv 相关函数和功能，参见 @autojs/opencv 模块。

目录

类

枚举

接口

类型别名

常量

MAX_LEVEL_AUTO

函数

类型别名

ImageFormat

Ƭ ImageFormat: "jpg" | "jpeg" | "png" | "webp"

图片格式类型。

Region

Ƭ Region: cv.Rect | Array<number>

区域类型，可以是 opencv 的 Rect 对象或数组 [x, y, width, height]。

常量

MAX_LEVEL_AUTO

• Const MAX_LEVEL_AUTO: -1

自动图像金字塔级别，用于模板匹配等操作。

函数

decodeImage

▸ decodeImage(str, encoding?): Promise<Image>

将字符串解码为图片对象，并异步返回该图片对象。若无法解码，则抛出异常。

参数

名称	类型	默认值	描述
`str`	`string`	`undefined`	字符串，根据 encoding 参数决定格式，默认为 base64
`encoding`	`BufferEncoding`	`"base64"`	编码格式，默认为 base64

返回值

Promise<Image>

返回一个 Promise，resolve 时返回 Image 对象。

decodeImageFromBuffer

▸ decodeImageFromBuffer(buffer): Promise<Image>

从 Buffer 中解码图片，并异步返回解码后的图片对象。若无法解码，则抛出异常。

参数

名称	类型	描述
`buffer`	`Buffer`	包含图片数据的 Buffer

返回值

Promise<Image>

返回一个 Promise，resolve 时返回 Image 对象。

decodeImageFromBufferSync

▸ decodeImageFromBufferSync(buffer): Image

从 Buffer 中解码图片，并同步返回解码后的图片对象。若无法解码，则抛出异常。

参数

名称	类型	描述
`buffer`	`Buffer`	包含图片数据的 Buffer

返回值

返回 Image 对象。

decodeImageSync

▸ decodeImageSync(str, encoding?): Image

将字符串解码为图片对象，并同步返回该图片对象。若无法解码，则抛出异常。

参数

名称	类型	默认值	描述
`str`	`string`	`undefined`	字符串，根据 encoding 参数决定格式，默认为 base64
`encoding`	`BufferEncoding`	`"base64"`	编码格式，默认为 base64

返回值

返回 Image 对象。

detectsColor

▸ detectsColor(src, color, x, y, options?): boolean

检测图片在指定位置的颜色是否匹配。

参数

名称	类型	描述
`src`	`Image`	源图片
`color`	`Color`	要检测的颜色
`x`	`number`	X 坐标
`y`	`number`	Y 坐标
`options`	`CompareColorOptions`	颜色比较选项

返回值

boolean

如果颜色匹配则返回 true，否则返回 false。

detectsMultiColors

▸ detectsMultiColors(src, colors, x, y, options?): boolean

检测图片在指定位置的多色是否匹配。

参数

名称	类型	描述
`src`	`Image`	源图片
`colors`	`ColorPath`	要检测的多色路径
`x`	`number`	X 坐标
`y`	`number`	Y 坐标
`options`	`CompareColorOptions`	颜色比较选项

返回值

boolean

如果多色匹配则返回 true，否则返回 false。

encodeImage

▸ encodeImage(img, encoding?, format?, quality?): Promise<string>

将图片编码为字符串，并异步返回编码后的字符串。

参数

名称	类型	默认值	描述
`img`	`Image`	`undefined`	要编码的图片
`encoding`	`BufferEncoding`	`"base64"`	编码格式，默认为 base64
`format`	`ImageFormat`	`"png"`	图片压缩格式，默认为 png。可选的值有：png、jpg、jpeg、webp
`quality`	`number`	`100`	图片质量，范围 0-100。默认值为 100

返回值

Promise<string>

返回一个 Promise，resolve 时返回编码后的字符串。

encodeImageSync

▸ encodeImageSync(img, encoding?, format?, quality?): string

将图片编码为字符串，并同步返回编码后的字符串。

参数

名称	类型	默认值	描述
`img`	`Image`	`undefined`	要编码的图片
`encoding`	`BufferEncoding`	`"base64"`	编码格式，默认为 base64
`format`	`ImageFormat`	`"png"`	图片压缩格式，默认为 png。可选的值有：png、jpg、jpeg、webp
`quality`	`number`	`100`	图片质量，范围 0-100。默认值为 100

返回值

string

返回编码后的字符串。

encodeImageToBuffer

▸ encodeImageToBuffer(img, format?, quality?): Promise<Buffer>

将图片编码为二进制数据，并异步返回编码后的 Buffer 对象。

参数

名称	类型	默认值	描述
`img`	`Image`	`undefined`	要编码的图片
`format`	`ImageFormat`	`"png"`	图片压缩格式，默认为 png。可选的值有：png、jpg、jpeg、webp
`quality`	`number`	`100`	图片质量，范围 0-100。默认值为 100

返回值

Promise<Buffer>

返回一个 Promise，resolve 时返回编码后的 Buffer 对象。

encodeImageToBufferSync

▸ encodeImageToBufferSync(img, format?, quality?): Buffer

将图片编码为二进制数据，并同步返回编码后的 Buffer 对象。

参数

名称	类型	默认值	描述
`img`	`Image`	`undefined`	要编码的图片
`format`	`ImageFormat`	`"png"`	图片压缩格式，默认为 png。可选的值有：png、jpg、jpeg、webp
`quality`	`number`	`100`	图片质量，范围 0-100。默认值为 100

返回值

Buffer

返回编码后的 Buffer 对象。

findColor

▸ findColor(src, color, options): Promise<cv.Point2 | null>

在图片中查找指定颜色的位置，异步返回。

参数

名称	类型	描述
`src`	`Image`	源图片
`color`	`Color`	要查找的颜色
`options`	`FindColorOptions`	找色选项，包括阈值、搜索区域等

返回值

Promise<cv.Point2 | null>

返回一个 Promise，resolve 时返回找到的位置，如果未找到则返回 null。

findColorSync

▸ findColorSync(src, color, options): cv.Point2 | null

在图片中查找指定颜色的位置，同步返回。

参数

名称	类型	描述
`src`	`Image`	源图片
`color`	`Color`	要查找的颜色
`options`	`FindColorOptions`	找色选项，包括阈值、搜索区域等

返回值

cv.Point2 | null

返回找到的位置，如果未找到则返回 null。

findImage

▸ findImage(src, template, options?): Promise<cv.Point2 | null>

在大图中搜索小图，并返回匹配结果。通过找图选项可以指定匹配精度、搜索区域和图像金字塔级别。

示例

"nodejs";

const { requestScreenCapture } = require("media_projection");
const { findImage, readImage } = require("image");

async function main() {
  const capturer = await requestScreenCapture();
  const template = await readImage("./template.png");
  const img = await capturer.nextImage();
  console.log(await findImage(img, template));
}
main();

参数

名称	类型	描述
`src`	`Image`	大图
`template`	`Image`	小图，即模板图片
`options`	`FindImageOptions`	找图选项

返回值

Promise<cv.Point2 | null>

返回一个 Promise，resolve 时返回模板图片在大图中的位置，或者 null。

findImageInRegion

▸ findImageInRegion(src, template, x, y, width?, height?, threshold?): Promise<cv.Point2 | null>

在指定区域中查找图片，异步返回。

参数

名称	类型	描述
`src`	`Image`	大图
`template`	`Image`	小图，即模板图片
`x`	`number`	搜索区域的 X 坐标
`y`	`number`	搜索区域的 Y 坐标
`width`	`number`	搜索区域的宽度
`height`	`number`	搜索区域的高度
`threshold`	`number`	匹配阈值，范围 0-1，默认值根据图片大小自动计算

返回值

Promise<cv.Point2 | null>

返回一个 Promise，resolve 时返回找到的位置，如果未找到则返回 null。

findImageInRegionSync

▸ findImageInRegionSync(src, template, x, y, width?, height?, threshold?): cv.Point2 | null

在指定区域中查找图片，同步返回。

参数

名称	类型	描述
`src`	`Image`	大图
`template`	`Image`	小图，即模板图片
`x`	`number`	搜索区域的 X 坐标
`y`	`number`	搜索区域的 Y 坐标
`width`	`number`	搜索区域的宽度
`height`	`number`	搜索区域的高度
`threshold`	`number`	匹配阈值，范围 0-1，默认值根据图片大小自动计算

返回值

cv.Point2 | null

返回找到的位置，如果未找到则返回 null。

findImageSync

▸ findImageSync(src, template, options?): cv.Point2 | null

在大图中搜索小图，并返回匹配结果，同步返回。

参数

名称	类型	描述
`src`	`Image`	大图
`template`	`Image`	小图，即模板图片
`options`	`FindImageOptions`	找图选项

返回值

cv.Point2 | null

返回模板图片在大图中的位置，或者 null。

findMultiColors

▸ findMultiColors(src, colors, options?): Promise<cv.Point2 | null>

在图片中查找多色路径的位置，异步返回。

参数

名称	类型	描述
`src`	`Image`	源图片
`colors`	`ColorPath`	要查找的多色路径
`options`	`FindColorOptions`	找色选项，包括阈值、搜索区域等

返回值

Promise<cv.Point2 | null>

返回一个 Promise，resolve 时返回找到的位置，如果未找到则返回 null。

findMultiColorsSync

▸ findMultiColorsSync(src, colors, options?): cv.Point2 | null

在图片中查找多色路径的位置，同步返回。

参数

名称	类型	描述
`src`	`Image`	源图片
`colors`	`ColorPath`	要查找的多色路径
`options`	`FindColorOptions`	找色选项，包括阈值、搜索区域等

返回值

cv.Point2 | null

返回找到的位置，如果未找到则返回 null。

loadImage

▸ loadImage(url): Promise<Image>

加载指定 url 地址的图片，异步返回 Image 对象。若 url 无法访问或图片无法解析，则抛出异常。

参数

名称	类型	描述
`url`	`string`	图片地址，需要以 https 或 http 开头

返回值

Promise<Image>

返回一个 Promise，resolve 时返回 Image 对象。

matchFeatures

▸ matchFeatures(scene, object, options?): Promise<ObjectFrame | null>

使用特征匹配算法在场景图中查找目标对象。

参数

名称	类型	描述
`scene`	`ImageFeatures`	场景图的特征
`object`	`ImageFeatures`	目标对象的特征
`options`	`FeatureMatchingOptions`	特征匹配选项

返回值

Promise<ObjectFrame | null>

返回一个 Promise，resolve 时返回对象框架，如果未找到则返回 null。

matchTemplate

▸ matchTemplate(src, template, options): Promise<Match[]>

使用模板匹配算法在图片中查找模板，返回所有匹配结果。

参数

名称	类型	描述
`src`	`Image`	源图片
`template`	`Image`	模板图片
`options`	`MatchTemplateOptions`	模板匹配选项

返回值

Promise<Match[]>

返回一个 Promise，resolve 时返回匹配结果数组。

matchTemplateSync

▸ matchTemplateSync(src, template, options): Match[]

使用模板匹配算法在图片中查找模板，返回所有匹配结果，同步返回。

参数

名称	类型	描述
`src`	`Image`	源图片
`template`	`Image`	模板图片
`options`	`MatchTemplateOptions`	模板匹配选项

返回值

返回匹配结果数组。

readImage

▸ readImage(file): Promise<Image>

读取指定路径的文件，异步返回 Image 对象。若文件不存在或无法解析，则抛出异常。

参数

名称	类型	描述
`file`	`string`	文件路径，支持相对路径

返回值

Promise<Image>

返回一个 Promise，resolve 时返回 Image 对象。

readImageSync

▸ readImageSync(file): Image

读取指定路径的文件，同步返回 Image 对象。若文件不存在或无法解析，则抛出异常。

参数

名称	类型	描述
`file`	`string`	文件路径，支持相对路径

返回值

返回 Image 对象。

writeImage

▸ writeImage(img, file, quality?): Promise<void>

将图片异步写入到指定的路径。

示例

"nodejs";

const { loadImage, writeImage } = require("image");
async function main() {
  const img = await loadImage("https://picsum.photos/200/300");
  await writeImage(img, "./output-200x300.png");
}
main();

参数

名称	类型	默认值	描述
`img`	`Image`	`undefined`	要写入的图片
`file`	`string`	`undefined`	文件路径，支持相对路径。文件路径需要以特定后缀名结束，目前支持的后缀名有：.jpg、.jpeg、.png、.webp
`quality`	`number`	`100`	图片质量，范围 0-100。默认值为 100

返回值

Promise<void>

返回一个 Promise，写入完成时 resolve。

writeImageSync

▸ writeImageSync(img, file, quality?): void

将图片同步写入到指定的路径。

参数

名称	类型	默认值	描述
`img`	`Image`	`undefined`	要写入的图片
`file`	`string`	`undefined`	文件路径，支持相对路径。文件路径需要以特定后缀名结束，目前支持的后缀名有：.jpg、.jpeg、.png、.webp
`quality`	`number`	`100`	图片质量，范围 0-100。默认值为 100

返回值

void