Skip to main content

Image - The process of processing images

老猫10/22/22About 5 min

The image module provides image I/O, transforms, template matching, and related helpers. Main APIs on this page and the Image class.

Screenshot capture moved to the media_projection module (as in Pro 8). For direct OpenCV usage see the @autojs/opencv package.

Table of contents

Classes

Enums

Interfaces

Type aliases

Constants

Functions

Type aliases

ImageFormat

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

Supported image formats when encoding or decoding.

Region

Region: OpenCV cv.Rect or a four-number array [x, y, width, height].

MAX_LEVEL_AUTO

  • MAX_LEVEL_AUTO: -1

Automatic pyramid depth for template matching and similar operations.

Functions

decodeImage

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

Decode a string (typically base64) into an image. Throws if decoding fails.

Parameters

  • str: Input string; format depends on encoding (default treats input as base64).
  • encoding: Encoding name; default "base64".

Returns

Promise<Image>

Resolves to an Image instance.

decodeImageFromBuffer

decodeImageFromBuffer(buffer: Buffer): Promise<Image>

Decode raw image bytes from a Buffer. Throws if decoding fails.

Parameters

  • buffer: Buffer containing encoded image data.

Returns

Promise<Image>

Resolves to an Image instance.

decodeImageFromBufferSync

decodeImageFromBufferSync(buffer: Buffer): Image

Same as decodeImageFromBuffer but synchronous.

Parameters

  • buffer: Buffer containing encoded image data.

Returns

Image

decodeImageSync

decodeImageSync(str: string, encoding?: BufferEncoding): Image

Same as decodeImage but synchronous.

Parameters

  • str: Input string; format depends on encoding (default treats input as base64).
  • encoding: Encoding name; default "base64".

Returns

Image

detectsColor

detectsColor(src: Image, color: Color, x: number, y: number, options?: CompareColorOptions): boolean

Check whether the pixel at (x, y) in src matches color.

Parameters

  • src: Source image.
  • color: Color to compare.
  • x: X coordinate.
  • y: Y coordinate.
  • options: Optional color comparison settings.

Returns

boolean

true if the colors match, otherwise false.

detectsMultiColors

detectsMultiColors(src: Image, colors: ColorPath, x: number, y: number, options?: CompareColorOptions): boolean

Check whether the multi-color path colors matches at the given anchor position.

Parameters

  • src: Source image.
  • colors: Color path to test.
  • x: X coordinate.
  • y: Y coordinate.
  • options: Optional color comparison settings.

Returns

boolean

true if the path matches, otherwise false.

encodeImage

encodeImage(img: Image, encoding?: BufferEncoding, format?: ImageFormat, quality?: number): Promise<string>

Encode the image to a string (for example base64) asynchronously.

Parameters

  • img: Image to encode.
  • encoding: String encoding; default "base64".
  • format: Container format; default "png". One of png, jpg, jpeg, webp.
  • quality: Quality 0–100; default 100.

Returns

Promise<string>

Resolves to the encoded string.

encodeImageSync

encodeImageSync(img: Image, encoding?: BufferEncoding, format?: ImageFormat, quality?: number): string

Same as encodeImage, but synchronous.

Parameters

  • img: Image to encode.
  • encoding: String encoding; default "base64".
  • format: Container format; default "png".
  • quality: Quality 0–100; default 100.

Returns

string

The encoded string.

encodeImageToBuffer

encodeImageToBuffer(img: Image, format?: ImageFormat, quality?: number): Promise<Buffer>

Encode the image to raw bytes asynchronously.

Parameters

  • img: Image to encode.
  • format: Container format; default "png".
  • quality: Quality 0–100; default 100.

Returns

Promise<Buffer>

Resolves to a Buffer of encoded image data.

encodeImageToBufferSync

encodeImageToBufferSync(img: Image, format?: ImageFormat, quality?: number): Buffer

Same as encodeImageToBuffer, but synchronous.

Parameters

  • img: Image to encode.
  • format: Container format; default "png".
  • quality: Quality 0–100; default 100.

Returns

Buffer

Encoded image bytes.

findColor

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

Find the first pixel matching color in src. Returns asynchronously.

Parameters

  • src: Source image.
  • color: Color to find.
  • options: Threshold, region, and other find-color settings.

Returns

Promise<cv.Point2 | null>

Resolves to the match position, or null if not found.

findColorSync

findColorSync(src: Image, color: Color, options: FindColorOptions): cv.Point2 | null

Same as findColor, but synchronous.

Parameters

  • src: Source image.
  • color: Color to find.
  • options: Find-color options.

Returns

cv.Point2 | null

Match position, or null if not found.

findImage

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

Search for template inside src. Options control match threshold, search region, pyramid levels, etc.

Example

"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();

Parameters

  • src: Large image (haystack).
  • template: Template image (needle).
  • options: Optional find-image settings.

Returns

Promise<cv.Point2 | null>

Resolves to the template position in src, or null if not found.

findImageInRegion

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

Search for template within a rectangular region of src.

Parameters

  • src: Large image.
  • template: Template image.
  • x, y: Top-left of the search region.
  • width, height: Region size.
  • threshold: Match threshold in 0–1; default is chosen from image size.

Returns

Promise<cv.Point2 | null>

Resolves to the match position, or null if not found.

findImageInRegionSync

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

Same as findImageInRegion, but synchronous.

Parameters

  • src: Large image.
  • template: Template image.
  • x, y: Top-left of the search region.
  • width, height: Region size.
  • threshold: Match threshold in 0–1.

Returns

cv.Point2 | null

Match position, or null if not found.

findImageSync

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

Same as findImage, but synchronous.

Parameters

  • src: Large image.
  • template: Template image.
  • options: Optional find-image settings.

Returns

cv.Point2 | null

Template position in src, or null if not found.

findMultiColors

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

Find the anchor position for a multi-color path in src.

Parameters

  • src: Source image.
  • colors: Color path to find.
  • options: Optional find-color settings.

Returns

Promise<cv.Point2 | null>

Resolves to the found position, or null if not found.

findMultiColorsSync

findMultiColorsSync(src: Image, colors: ColorPath, options?: FindColorOptions): cv.Point2 | null

Same as findMultiColors, but synchronous.

Parameters

  • src: Source image.
  • colors: Color path to find.
  • options: Optional find-color settings.

Returns

cv.Point2 | null

Match position, or null if not found.

loadImage

loadImage(url: string): Promise<Image>

Load an image from url (http or https). Throws if the URL is unreachable or the payload cannot be decoded.

Parameters

  • url: Image URL.

Returns

Promise<Image>

Resolves to an Image instance.

matchFeatures

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

Feature-based matching: locate object in scene.

Parameters

  • scene: Features of the scene image.
  • object: Features of the target object.
  • options: Matching options.

Returns

Promise<ObjectFrame | null>

Resolves to a detected ObjectFrame, or null if not found.

matchTemplate

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

Template matching: find all occurrences of template in src.

Parameters

  • src: Source image.
  • template: Template patch.
  • options: Template matching options.

Returns

Promise<Match[]>

Resolves to an array of Match results.

matchTemplateSync

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

Same as matchTemplate, but synchronous.

Parameters

  • src: Source image.
  • template: Template patch.
  • options: Template matching options.

Returns

Match[]

Array of match results.

readImage

readImage(file: string): Promise<Image>

Read an image file asynchronously. Throws if the file is missing or cannot be decoded.

Parameters

  • file: File path (relative paths allowed).

Returns

Promise<Image>

Resolves to an Image instance.

readImageSync

readImageSync(file: string): Image`

Same as readImage, but synchronous.

Parameters

  • file: File path (relative paths allowed).

Returns

Image

writeImage

writeImage(img: Image, file: string, quality?: number): Promise<void>

Write img to file asynchronously. The file extension selects format: .jpg, .jpeg, .png, or .webp.

Example

"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();

Parameters

  • img: Image to write.
  • file: Output path; must end with a supported extension (.jpg, .jpeg, .png, .webp).
  • quality: Quality 0–100; default 100.

Returns

Promise<void>

Resolves when the file has been written.

writeImageSync

writeImageSync(img: Image, file: string, quality?: number): void

Same as writeImage, but synchronous.

Parameters

  • img: Image to write.
  • file: Output path; must end with a supported extension.
  • quality: Quality 0–100; default 100.

Returns

void

Copyright © 2026 老猫