图片处理 — 剪裁、旋转、二值化、滤波详解

处理函数总览

剪裁 — clip

最常用的处理操作，提取图像的指定矩形区域：

let screen = images.captureScreen();

// 基础剪裁：x, y, width, height
let topBar = images.clip(screen, 0, 0, 1080, 100);
let bottomBar = images.clip(screen, 0, 1700, 1080, 220);

images.save(topBar, "top_bar.png");
images.save(bottomBar, "bottom_bar.png");

// 用完记得 recycle
topBar.recycle();
bottomBar.recycle();
screen.recycle();

剪裁的实际用途

// 1. 缩小模板匹配的搜索范围
let cropped = images.clip(screen, 0, 900, 1080, 1000);
let result = images.match(cropped, template); // 只在底部 100px 找
cropped.recycle();
screen.recycle();

// 2. 从截图中提取单个控件作为模板
let btnRegion = images.clip(screen, 200, 800, 680, 120);
images.save(btnRegion, "btn_template.png"); // 存起来下次用
btnRegion.recycle();

// 3. OCR 前剪裁，大幅提速
let textRegion = images.clip(screen, 0, 500, 1080, 300); // 只识别中间部分
let ocrResult = ocr.detect(textRegion);
textRegion.recycle();

旋转 — rotate

// 顺时针旋转指定角度（0-360）
let rotated90 = images.rotate(screen, 90);
let rotated180 = images.rotate(screen, 180);

适配横竖屏切换

// 某些应用支持横屏，截图是横的需要转正
let screen = images.captureScreen();
if (screen.width > screen.height) {
    // 横屏截图，逆时针转 90 度转正
    let portrait = images.rotate(screen, -90);
    // 后续操作 portrait...
    portrait.recycle();
}
screen.recycle();

灰度 — grayscale

// 转为灰度图
let gray = images.grayscale(screen);
images.save(gray, "gray.png");

灰度的用途

模板匹配对颜色不敏感时，转灰度可以：

• 减少色彩空间带来的匹配误差
• 提升匹配速度（像素计算量减少）
• 消除主题色（深色/浅色模式）带来的颜色差异

let template = images.read("icon.png");
let grayTemplate = images.grayscale(template);
let grayScreen = images.grayscale(images.captureScreen());

// 在灰度空间做匹配，适配不同主题
let result = images.match(grayScreen, grayTemplate, { threshold: 0.85 });

grayScreen.recycle();
grayTemplate.recycle();
template.recycle();

二值化 — binary

二值化把图像转为纯黑白，适合文字提取和高亮对比度场景：

let binary = images.binary(img, {
    threshold: 128,  // 0-255，默认 128
    // 小于阈值的变 0（黑），大于的变 255（白）
    adaptive: false, // 是否自适应阈值
    blockSize: 15,   // 自适应时的块大小
    C: 5             // 自适应的偏移常量
});

自适应 vs 固定阈值

// 固定阈值：适合明暗均匀的场景
let fixed = images.binary(img, { threshold: 128 });

// 自适应阈值：适合光照不均匀的场景
let adaptive = images.binary(img, {
    adaptive: true,
    blockSize: 31,
    C: 10
});

双边滤波 — bilateralFilter

双边滤波在模糊降噪的同时保留边缘，比普通高斯模糊更适合图像识别前处理：

let filtered = images.bilateralFilter(img, {
    d: 9,       // 每个像素邻域直径
    sigmaColor: 75,  // 颜色空间标准差
    sigmaSpace: 75   // 坐标空间标准差
});

滤波的用途

// 截图有压缩噪点时，先滤波再匹配
let screen = images.captureScreen();
let denoised = images.bilateralFilter(screen);

let result = images.match(denoised, template);

denoised.recycle();
screen.recycle();

色彩调整 — adjustColor

let adjusted = images.adjustColor(img, {
    brightness: 1.2,   // 亮度（0-2，1=原亮度）
    contrast: 1.5,     // 对比度（0-2，1=原对比度）
    saturation: 0.8    // 饱和度（0-2，1=原饱和度）
});

色彩调整的用途

// 深色模式下界面暗，调亮后再 OCR
let screen = images.captureScreen();
let brightened = images.adjustColor(screen, { brightness: 1.3 });
let result = ocr.detect(brightened);
brightened.recycle();
screen.recycle();

链接网络图片 — loadAsync

v6.7 新增的网络图片加载能力：

// 异步加载网络图片
let imgPromise = images.loadAsync("https://example.com/icon.png");
imgPromise.then(img => {
    console.log("加载成功: " + img.width + "x" + img.height);
    // 使用 img...
    img.recycle();
}).catch(err => {
    console.error("加载失败: " + err.message);
});

// images.saveTo / stream / close
// v6.7 新增 http body 对象的这些方法

实用处理流水线

OCR 前处理

/**
 * 高质量 OCR 预处理流水线
 */
function preprocessForOcr(screen) {
    // 1. 剪裁感兴趣区域
    let region = images.clip(screen, 0, 960, 1080, 500);
    
    // 2. 转灰度减少色彩干扰
    let gray = images.grayscale(region);
    
    // 3. 提高对比度让文字更清晰
    let enhanced = images.adjustColor(gray, {
        contrast: 1.5,
        brightness: 1.1
    });
    
    region.recycle();
    gray.recycle();
    
    return enhanced;
}

let screen = images.captureScreen();
let processed = preprocessForOcr(screen);
let ocrResult = ocr.detect(processed);
processed.recycle();
screen.recycle();

模板匹配前处理

/**
 * 模板匹配预处理
 */
function preprocessForMatch(screen, template) {
    // 双方都转灰度，消除主题色差异
    let grayScreen = images.grayscale(screen);
    let grayTemplate = images.grayscale(template);
    
    // 剪裁限定搜索区域
    let croppedScreen = images.clip(grayScreen, 0, 960, 1080, 500);
    
    grayScreen.recycle();
    
    return { screen: croppedScreen, template: grayTemplate };
}

内存管理提醒

所有图片处理函数都返回新的 Image 对象，原图像不会被修改。用完后所有 Image 对象都要 recycle：

let a = images.captureScreen();
let b = images.grayscale(a);      // 新对象
let c = images.binary(b);          // 又一个新对象

// 用完三个都要释放
c.recycle();
b.recycle();
a.recycle();