minimal-agent 0.10.0 → 0.12.0

package/src/tools/computeruse/vision/raster.js

@@ -0,0 +1,320 @@
+/**
+ * ============================================================
+ *  vision/raster.ts —— 像素运算（零依赖，纯函数）
+ * ------------------------------------------------------------
+ *  这一层只做「把像素搬来搬去」，不知道屏幕、坐标约定、模型预算是什么。
+ *
+ *  两个刻意的取舍：
+ *
+ *  ① 缩放只做**盒式平均**（box filter），不做 Lanczos。
+ *     我们只会缩小、不会放大，而盒式平均对下采样是无偏的、且对文字边缘的
+ *     保留明显好于最近邻。Lanczos 在小字上还能再好一点，但它的复杂度与
+ *     参数调优不值得 —— 真要读清文字，正确做法是**不缩放地裁出 ROI**，
+ *     而不是把全屏缩得更清楚。
+ *
+ *  ② 自带一套 5×7 位图数字，用来给标注框打编号。
+ *     引字体渲染库是荒谬的；但没有编号，模型就只能报坐标，而坐标正是我们
+ *     想让它避开的东西（「点 ①里的第二项」比「点 (520,340)」稳得多）。
+ * ============================================================
+ */
+// ============================================================
+//  基本变换
+// ============================================================
+/** RGBA → 灰度（Rec.601 亮度权重）。帧差只在灰度上做，省 4 倍内存与带宽。 */
+export function toGray(rgba, width, height) {
+    const out = new Uint8Array(width * height);
+    for (let i = 0, p = 0; p < out.length; p += 1, i += 4) {
+        out[p] = (rgba[i] * 77 + rgba[i + 1] * 150 + rgba[i + 2] * 29) >> 8;
+    }
+    return out;
+}
+/**
+ * 盒式平均下采样（单通道）。目标尺寸必须 ≤ 源尺寸。
+ * 用于把全屏压到 1/16 做帧差 —— 这是「不需要 GPU 也不需要 OpenCV」的关键：
+ * 480×270 上的 absdiff 只有 13 万次运算。
+ */
+export function downsampleGray(gray, width, height, targetWidth, targetHeight) {
+    const out = new Uint8Array(targetWidth * targetHeight);
+    const xRatio = width / targetWidth;
+    const yRatio = height / targetHeight;
+    for (let ty = 0; ty < targetHeight; ty += 1) {
+        const y0 = Math.floor(ty * yRatio);
+        const y1 = Math.max(y0 + 1, Math.floor((ty + 1) * yRatio));
+        for (let tx = 0; tx < targetWidth; tx += 1) {
+            const x0 = Math.floor(tx * xRatio);
+            const x1 = Math.max(x0 + 1, Math.floor((tx + 1) * xRatio));
+            let sum = 0;
+            let count = 0;
+            for (let y = y0; y < y1 && y < height; y += 1) {
+                const row = y * width;
+                for (let x = x0; x < x1 && x < width; x += 1) {
+                    sum += gray[row + x];
+                    count += 1;
+                }
+            }
+            out[ty * targetWidth + tx] = count > 0 ? (sum / count) | 0 : 0;
+        }
+    }
+    return out;
+}
+/** 盒式平均下采样（RGBA）。逐通道独立平均，alpha 一并处理。 */
+export function resizeRgba(rgba, width, height, targetWidth, targetHeight) {
+    const out = new Uint8Array(targetWidth * targetHeight * 4);
+    const xRatio = width / targetWidth;
+    const yRatio = height / targetHeight;
+    for (let ty = 0; ty < targetHeight; ty += 1) {
+        const y0 = Math.floor(ty * yRatio);
+        const y1 = Math.max(y0 + 1, Math.floor((ty + 1) * yRatio));
+        for (let tx = 0; tx < targetWidth; tx += 1) {
+            const x0 = Math.floor(tx * xRatio);
+            const x1 = Math.max(x0 + 1, Math.floor((tx + 1) * xRatio));
+            let r = 0;
+            let g = 0;
+            let b = 0;
+            let a = 0;
+            let count = 0;
+            for (let y = y0; y < y1 && y < height; y += 1) {
+                for (let x = x0; x < x1 && x < width; x += 1) {
+                    const i = (y * width + x) * 4;
+                    r += rgba[i];
+                    g += rgba[i + 1];
+                    b += rgba[i + 2];
+                    a += rgba[i + 3];
+                    count += 1;
+                }
+            }
+            const o = (ty * targetWidth + tx) * 4;
+            if (count > 0) {
+                out[o] = (r / count) | 0;
+                out[o + 1] = (g / count) | 0;
+                out[o + 2] = (b / count) | 0;
+                out[o + 3] = (a / count) | 0;
+            }
+        }
+    }
+    return { data: out, width: targetWidth, height: targetHeight };
+}
+/** 按长边等比缩放；已经不超过 longSide 时原样返回（不放大）。 */
+export function fitLongSide(image, longSide) {
+    const { width, height } = image;
+    const current = Math.max(width, height);
+    if (current <= longSide)
+        return image;
+    const scale = longSide / current;
+    return resizeRgba(image.data, width, height, Math.max(1, Math.round(width * scale)), Math.max(1, Math.round(height * scale)));
+}
+/** 裁剪（矩形会先被钳进画布，越界不抛错 —— 模型给的框常常轻微越界）。 */
+export function crop(image, rect) {
+    const r = clampRect(rect, image.width, image.height);
+    const out = new Uint8Array(r.width * r.height * 4);
+    for (let y = 0; y < r.height; y += 1) {
+        const src = ((r.y + y) * image.width + r.x) * 4;
+        out.set(image.data.subarray(src, src + r.width * 4), y * r.width * 4);
+    }
+    return { data: out, width: r.width, height: r.height };
+}
+export function clampRect(rect, width, height) {
+    const x = Math.max(0, Math.min(width - 1, Math.round(rect.x)));
+    const y = Math.max(0, Math.min(height - 1, Math.round(rect.y)));
+    return {
+        x,
+        y,
+        width: Math.max(1, Math.min(width - x, Math.round(rect.width))),
+        height: Math.max(1, Math.min(height - y, Math.round(rect.height))),
+    };
+}
+/** 深拷贝一张图（画框/合成前用，避免就地改坏原始帧）。 */
+export function cloneImage(image) {
+    return { data: Uint8Array.from(image.data), width: image.width, height: image.height };
+}
+/**
+ * 在 (cx, cy) 画一个十字准星标记，用于标示上次点击位置。
+ * 中心 3×3 实心点 + 十字线，线宽 2px，臂长 armLen。
+ * 颜色默认 ANNOTATION_COLOR（高饱和橙红）。
+ */
+export function drawCrosshair(image, cx, cy, color = ANNOTATION_COLOR, armLen = 12, thickness = 2) {
+    const put = (x, y) => {
+        if (x < 0 || y < 0 || x >= image.width || y >= image.height)
+            return;
+        const i = (y * image.width + x) * 4;
+        image.data[i] = color[0];
+        image.data[i + 1] = color[1];
+        image.data[i + 2] = color[2];
+        image.data[i + 3] = 255;
+    };
+    // 中心 3×3 实心点
+    for (let dy = -1; dy <= 1; dy += 1) {
+        for (let dx = -1; dx <= 1; dx += 1) {
+            put(Math.round(cx) + dx, Math.round(cy) + dy);
+        }
+    }
+    // 水平线
+    for (let dx = -armLen; dx <= armLen; dx += 1) {
+        for (let t = 0; t < thickness; t += 1) {
+            put(Math.round(cx) + dx, Math.round(cy) - Math.floor(thickness / 2) + t);
+        }
+    }
+    // 垂直线
+    for (let dy = -armLen; dy <= armLen; dy += 1) {
+        for (let t = 0; t < thickness; t += 1) {
+            put(Math.round(cx) - Math.floor(thickness / 2) + t, Math.round(cy) + dy);
+        }
+    }
+    return image;
+}
+/**
+ * 历史操作标记颜色：最近1次红色，上1次橙色，最早1次黄色
+ */
+export const ACTION_MARKER_COLORS = [
+    [255, 0, 0],
+    [255, 136, 0],
+    [255, 204, 0],
+];
+/**
+ * 画带序号的历史操作标记：十字准星 + 右上角数字徽标
+ */
+export function drawActionMarker(image, cx, cy, index, armLen = 12, thickness = 2) {
+    const color = ACTION_MARKER_COLORS[Math.min(index, ACTION_MARKER_COLORS.length - 1)] ?? ACTION_MARKER_COLORS[0];
+    drawCrosshair(image, cx, cy, color, armLen, thickness);
+    const badgeScale = 2;
+    const badgeX = Math.round(cx) + armLen + 2;
+    const badgeY = Math.round(cy) - armLen - 2;
+    drawBadge(image, badgeX, badgeY, index + 1, color, badgeScale);
+    return image;
+}
+// ============================================================
+//  标注
+// ============================================================
+/** 默认标注色：高饱和橙红，在绝大多数 UI 配色里都突出，且不与「选中蓝」混淆。 */
+export const ANNOTATION_COLOR = [255, 59, 48];
+/** 就地画空心矩形框。 */
+export function drawRect(image, rect, color = ANNOTATION_COLOR, thickness = 3) {
+    const r = clampRect(rect, image.width, image.height);
+    const put = (x, y) => {
+        if (x < 0 || y < 0 || x >= image.width || y >= image.height)
+            return;
+        const i = (y * image.width + x) * 4;
+        image.data[i] = color[0];
+        image.data[i + 1] = color[1];
+        image.data[i + 2] = color[2];
+        image.data[i + 3] = 255;
+    };
+    for (let t = 0; t < thickness; t += 1) {
+        for (let x = r.x; x < r.x + r.width; x += 1) {
+            put(x, r.y + t);
+            put(x, r.y + r.height - 1 - t);
+        }
+        for (let y = r.y; y < r.y + r.height; y += 1) {
+            put(r.x + t, y);
+            put(r.x + r.width - 1 - t, y);
+        }
+    }
+    return image;
+}
+/** 就地填充实心矩形（标号底板）。 */
+export function fillRect(image, rect, color) {
+    const r = clampRect(rect, image.width, image.height);
+    for (let y = r.y; y < r.y + r.height; y += 1) {
+        for (let x = r.x; x < r.x + r.width; x += 1) {
+            const i = (y * image.width + x) * 4;
+            image.data[i] = color[0];
+            image.data[i + 1] = color[1];
+            image.data[i + 2] = color[2];
+            image.data[i + 3] = 255;
+        }
+    }
+    return image;
+}
+/**
+ * 5×7 位图数字。每个字形是 7 行、每行 5 位（bit4 最左）。
+ * 只有 0-9 —— 标注编号不需要字母，够用即止。
+ */
+const GLYPHS = {
+    0: [0x0e, 0x11, 0x13, 0x15, 0x19, 0x11, 0x0e],
+    1: [0x04, 0x0c, 0x04, 0x04, 0x04, 0x04, 0x0e],
+    2: [0x0e, 0x11, 0x01, 0x02, 0x04, 0x08, 0x1f],
+    3: [0x1f, 0x02, 0x04, 0x02, 0x01, 0x11, 0x0e],
+    4: [0x02, 0x06, 0x0a, 0x12, 0x1f, 0x02, 0x02],
+    5: [0x1f, 0x10, 0x1e, 0x01, 0x01, 0x11, 0x0e],
+    6: [0x06, 0x08, 0x10, 0x1e, 0x11, 0x11, 0x0e],
+    7: [0x1f, 0x01, 0x02, 0x04, 0x08, 0x08, 0x08],
+    8: [0x0e, 0x11, 0x11, 0x0e, 0x11, 0x11, 0x0e],
+    9: [0x0e, 0x11, 0x11, 0x0f, 0x01, 0x02, 0x0c],
+};
+const GLYPH_WHITE = [255, 255, 255];
+/**
+ * 在 (x, y) 画一个编号徽标（实心底板 + 放大的位图数字）。
+ * scale 决定字号；底板用标注色、数字用白色，保证任何背景上都可读。
+ */
+export function drawBadge(image, x, y, value, color = ANNOTATION_COLOR, scale = 3) {
+    const digits = String(value).split('');
+    const glyphW = 5 * scale;
+    const glyphH = 7 * scale;
+    const gap = scale;
+    const padding = 2 * scale;
+    const boxW = digits.length * glyphW + (digits.length - 1) * gap + padding * 2;
+    const boxH = glyphH + padding * 2;
+    fillRect(image, { x, y, width: boxW, height: boxH }, color);
+    let cursor = x + padding;
+    for (const digit of digits) {
+        const glyph = GLYPHS[digit];
+        if (glyph) {
+            for (let row = 0; row < 7; row += 1) {
+                for (let col = 0; col < 5; col += 1) {
+                    if (!(glyph[row] & (1 << (4 - col))))
+                        continue;
+                    fillRect(image, { x: cursor + col * scale, y: y + padding + row * scale, width: scale, height: scale }, GLYPH_WHITE);
+                }
+            }
+        }
+        cursor += glyphW + gap;
+    }
+    return image;
+}
+// ============================================================
+//  遮罩（注意力）
+// ============================================================
+const WHITE_BACKGROUND = [255, 255, 255];
+/**
+ * 把 keep 矩形**之外**的像素朝背景色混合，做出「其余虚化」的效果。
+ *
+ * ⚠️ 这就是 alpha 合成 —— 4 通道的透明度到不了模型（视觉编码器吃 RGB，
+ * alpha 要么被合成掉、要么被丢弃，且是 provider 相关的未定义行为）。
+ * 想要「透明感」就必须在这里自己合成到确定的背景色。
+ *
+ * ⚠️ 已知风险：真实 UI 语义里「变淡 = 禁用/加载中」，模型可能把遮罩区
+ * 描述成「灰显不可点击」。凡是用了本函数的观测，**必须在随图的说明里明写
+ * 「淡化只表示这里没变化，不表示该控件被禁用」**，否则模型会照着误读行动。
+ */
+export function fadeOutside(image, keepRects, alpha = 0.3, background = WHITE_BACKGROUND) {
+    const keep = keepRects.map((r) => clampRect(r, image.width, image.height));
+    const inKeep = (x, y) => keep.some((r) => x >= r.x && x < r.x + r.width && y >= r.y && y < r.y + r.height);
+    for (let y = 0; y < image.height; y += 1) {
+        for (let x = 0; x < image.width; x += 1) {
+            if (inKeep(x, y))
+                continue;
+            const i = (y * image.width + x) * 4;
+            for (let c = 0; c < 3; c += 1) {
+                image.data[i + c] = (image.data[i + c] * alpha + background[c] * (1 - alpha)) | 0;
+            }
+        }
+    }
+    return image;
+}
+/** 把 keep 矩形之外的像素转灰度（保留对比度，无「禁用」语义碰撞）。 */
+export function grayscaleOutside(image, keepRects) {
+    const keep = keepRects.map((r) => clampRect(r, image.width, image.height));
+    const inKeep = (x, y) => keep.some((r) => x >= r.x && x < r.x + r.width && y >= r.y && y < r.y + r.height);
+    for (let y = 0; y < image.height; y += 1) {
+        for (let x = 0; x < image.width; x += 1) {
+            if (inKeep(x, y))
+                continue;
+            const i = (y * image.width + x) * 4;
+            const g = (image.data[i] * 77 + image.data[i + 1] * 150 + image.data[i + 2] * 29) >> 8;
+            image.data[i] = g;
+            image.data[i + 1] = g;
+            image.data[i + 2] = g;
+        }
+    }
+    return image;
+}