pic_match

基于 WASM 的图像偏移检测库，使用相位相关（Phase Correlation）算法，支持部分重叠场景。

安装

npm install picture_match

API

import { findOffset } from "pic_match";

const result = await findOffset(imageA, imageB);
// result: { dx: number, dy: number, confidence: number }

参数

参数	类型	说明
imageA	ImageData	参考图像，包含 data（Uint8ClampedArray RGBA）、width、height
imageB	ImageData	待匹配图像，格式同上

返回值

字段	类型	说明
dx	number	X 方向偏移量（正数表示 imageB 相对于 imageA 右移）
dy	number	Y 方向偏移量（正数表示 imageB 相对于 imageA 下移）
confidence	number	置信度，值越高匹配越可靠

性能

分辨率	耗时
64×64	~70ms
512×512	~350ms
1920×1080	~300ms
3840×2160	~400ms

测试环境：Linux x86_64, Node.js 20

算法说明

使用相位相关（Phase Correlation）算法：

1. 将两张图像转为灰度图并降采样
2. 应用 Hanning 窗减少频谱泄漏
3. 对两张图分别做 2D FFT
4. 计算互功率谱（Cross-Power Spectrum）
5. 反 FFT 得到相关面，峰值位置即为偏移量

该算法对部分重叠场景有良好支持，即使两张图只有部分内容相同也能正确检测偏移。

开发环境准备

1. 安装 Rust 工具链

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source $HOME/.cargo/env

添加 WASM 编译目标：

rustup target add wasm32-unknown-unknown

2. 安装 wasm-pack

cargo install wasm-pack

3. 安装 Node.js 环境

推荐使用 pnpm，否则把下面相关命令中pnpm换成npm

4. 安装项目依赖

pnpm install

5. 环境检查

确认以下命令可用：

rustc --version      # >= 1.70
cargo --version
wasm-pack --version  # >= 0.12
node --version       # >= 18

构建

pnpm build

该命令依次执行：

1. build:wasm - 使用 wasm-pack 编译 Rust 为 WASM
2. embed:wasm - 将 WASM 二进制嵌入 TypeScript（base64）
3. build:ts - 使用 Vite 构建 TypeScript 库

测试

pnpm test

包含准确性测试和性能基准测试。