image - 图片处理

更新: 2025/7/20 字数: 0 字时长: 0 分钟

image - 图片处理

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

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

类型别名

ImageFormat

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

Region

Region: Rect | number[]

变量

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>

decodeImageFromBuffer

decodeImageFromBuffer(buffer): Promise<Image>

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

参数

名称	类型
`buffer`	`Buffer`

返回值

Promise<Image>

decodeImageFromBufferSync

decodeImageFromBufferSync(buffer): Image

从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`
`y`	`number`
`options?`	`CompareColorOptions`

返回值

boolean

detectsMultiColors

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

参数

名称	类型
`src`	`Image`
`colors`	`ColorPath`
`x`	`number`
`y`	`number`
`options?`	`CompareColorOptions`

返回值

boolean

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>

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>

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

findColor

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

参数

名称	类型
`src`	`Image`
`color`	`Color`
`options`	`FindColorOptions`

返回值

Promise<Point2 | null>

findColorSync

findColorSync(src, color, options): Point2 | null

参数

名称	类型
`src`	`Image`
`color`	`Color`
`options`	`FindColorOptions`

返回值

Point2 | null

findImage

findImage(src, template, options?): Promise<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<Point2 | null>

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

findImageInRegion

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

参数

名称	类型
`src`	`Image`
`template`	`Image`
`x`	`number`
`y`	`number`
`width?`	`number`
`height?`	`number`
`threshold?`	`number`

返回值

Promise<Point2 | null>

findImageInRegionSync

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

参数

名称	类型
`src`	`Image`
`template`	`Image`
`x`	`number`
`y`	`number`
`width?`	`number`
`height?`	`number`
`threshold?`	`number`

返回值

Point2 | null

findImageSync

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

参数

名称	类型
`src`	`Image`
`template`	`Image`
`options`	`FindImageOptions`

返回值

Point2 | null

findMultiColors

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

参数

名称	类型
`src`	`Image`
`colors`	`ColorPath`
`options`	`FindColorOptions`

返回值

Promise<Point2 | null>

findMultiColorsSync

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

参数

名称	类型
`src`	`Image`
`colors`	`ColorPath`
`options`	`FindColorOptions`

返回值

Point2 | null

loadImage

loadImage(url): Promise<Image>

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

参数

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

返回值

Promise<Image>

matchFeatures

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

参数

名称	类型
`scene`	`ImageFeatures`
`object`	`ImageFeatures`
`options?`	`FeatureMatchingOptions`

返回值

Promise<ObjectFrame | null>

matchTemplate

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

参数

名称	类型
`src`	`Image`
`template`	`Image`
`options`	`MatchTemplateOptions`

返回值

Promise<Match[]>

matchTemplateSync

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

参数

名称	类型
`src`	`Image`
`template`	`Image`
`options`	`MatchTemplateOptions`

返回值

Match[]

readImage

readImage(file): Promise<Image>

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

参数

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

返回值

Promise<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>

writeImageSync

writeImageSync(img, file, quality?): void

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

参数

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

返回值

void

image - 图片处理 ​