Skip to content

armgit / cindy

Public Imported from GitHub
0

Consider it done. The open-source AI agent that works out of the box · 想到,就能做到。开源、开箱即用的 AI Agent。

feat(maker-shared): 抽出图片标注跨端纯函数核心

Dash0cde17f9bdf8
diff --git a/packages/maker-shared/package.json b/packages/maker-shared/package.json
index 261a3dfaf7..1589f4cccf 100644
--- a/packages/maker-shared/package.json
+++ b/packages/maker-shared/package.json
@@ -28,6 +28,7 @@
"./file-preview": "./src/filePreview.ts",
"./fixtures": "./src/fixtures.ts",
"./history-gap": "./src/historyGap.ts",
+ "./image-annotation": "./src/imageAnnotation.ts",
"./interaction": "./src/interaction.ts",
"./internal-citation": "./src/internalCitation.ts",
"./live-task-priority": "./src/liveTaskPriority.ts",
diff --git a/packages/maker-shared/src/__tests__/imageAnnotation.test.ts b/packages/maker-shared/src/__tests__/imageAnnotation.test.ts
new file mode 100644
index 0000000000..7012543572
--- /dev/null
+++ b/packages/maker-shared/src/__tests__/imageAnnotation.test.ts
@@ -0,0 +1,232 @@
+import { describe, expect, it } from 'vitest';
+import {
+ ANNOTATION_CANVAS_SCRIPT,
+ ANNOTATION_OUTLINE_COLOR,
+ ANNOTATION_STROKE_COLOR,
+ MAX_ANNOTATION_REGIONS,
+ annotationOutlineWidth,
+ annotationStrokeToSvgPath,
+ annotationStrokeWidth,
+ drawAnnotationStrokes,
+ formatAnnotationRegion,
+ normalizeAnnotationPoint,
+ sanitizeAnnotationRegions,
+ shouldAppendAnnotationPoint,
+ summarizeAnnotationRegions,
+ type AnnotationCanvasContext,
+ type AnnotationStroke,
+} from '../imageAnnotation';
+
+/** 旧版(单一短边)公式:常规比例图片的线宽必须与它完全一致。 */
+function legacyStrokeWidth(w: number, h: number): number {
+ return Math.min(24, Math.max(4, Math.round(Math.min(w, h) * 0.005)));
+}
+
+function recordingContext(): AnnotationCanvasContext & { calls: unknown[][] } {
+ const calls: unknown[][] = [];
+ const ctx = {
+ calls,
+ _lineCap: '',
+ _lineJoin: '',
+ _strokeStyle: '' as unknown,
+ _lineWidth: 0,
+ get lineCap() { return this._lineCap; },
+ set lineCap(v: string) { this._lineCap = v; calls.push(['lineCap', v]); },
+ get lineJoin() { return this._lineJoin; },
+ set lineJoin(v: string) { this._lineJoin = v; calls.push(['lineJoin', v]); },
+ get strokeStyle() { return this._strokeStyle; },
+ set strokeStyle(v: unknown) { this._strokeStyle = v; calls.push(['strokeStyle', v]); },
+ get lineWidth() { return this._lineWidth; },
+ set lineWidth(v: number) { this._lineWidth = v; calls.push(['lineWidth', v]); },
+ beginPath() { calls.push(['beginPath']); },
+ moveTo(x: number, y: number) { calls.push(['moveTo', x, y]); },
+ lineTo(x: number, y: number) { calls.push(['lineTo', x, y]); },
+ stroke() { calls.push(['stroke']); },
+ };
+ return ctx;
+}
+
+function loadScript(): {
+ width: (w: number, h: number) => number;
+ draw: (ctx: unknown, strokes: unknown, w: number, h: number) => void;
+} {
+ // eslint-disable-next-line @typescript-eslint/no-implied-eval
+ const factory = new Function(
+ `${ANNOTATION_CANVAS_SCRIPT}\nreturn { width: cindyAnnotationStrokeWidth, draw: cindyDrawAnnotationStrokes };`,
+ );
+ return factory();
+}
+
+const STROKES: AnnotationStroke[] = [
+ { points: [{ x: 0.1, y: 0.1 }, { x: 0.5, y: 0.2 }, { x: 0.6, y: 0.7 }] },
+ { points: [{ x: 0.3, y: 0.3 }] },
+ { points: [] },
+ { points: [{ x: 0.9, y: 0.05 }, { x: 0.95, y: 0.1 }] },
+];
+
+describe('annotationStrokeWidth', () => {
+ it('keeps the legacy width for ordinary aspect ratios', () => {
+ const sizes: Array<[number, number]> = [
+ [320, 240], [800, 600], [1179, 2556], [1920, 1080], [2560, 1600],
+ [3024, 4032], [4000, 3000], [6000, 4000], [8000, 6000], [1000, 2500],
+ ];
+ for (const [w, h] of sizes) {
+ expect(annotationStrokeWidth(w, h)).toBe(legacyStrokeWidth(w, h));
+ expect(annotationStrokeWidth(h, w)).toBe(legacyStrokeWidth(w, h));
+ }
+ });
+
+ it('thickens strokes on very long screenshots so they survive model downscaling', () => {
+ const width = annotationStrokeWidth(1000, 8000);
+ expect(width).toBeGreaterThan(legacyStrokeWidth(1000, 8000));
+ // 缩到长边 1568 后仍至少约 3px。
+ expect((width * 1568) / 8000).toBeGreaterThanOrEqual(2.9);
+ });
+
+ it('caps the long-edge term relative to the short edge', () => {
+ expect(annotationStrokeWidth(1000, 200_000)).toBe(20);
+ });
+
+ it('never goes below 4px', () => {
+ expect(annotationStrokeWidth(10, 10)).toBe(4);
+ });
+});
+
+describe('normalizeAnnotationPoint', () => {
+ it('clamps to the image and quantizes to 4 decimals', () => {
+ const rect = { left: 10, top: 20, width: 300, height: 200 };
+ expect(normalizeAnnotationPoint(0, 0, rect)).toEqual({ x: 0, y: 0 });
+ expect(normalizeAnnotationPoint(1000, 1000, rect)).toEqual({ x: 1, y: 1 });
+ expect(normalizeAnnotationPoint(110, 70, rect)).toEqual({ x: 0.3333, y: 0.25 });
+ });
+
+ it('rejects empty rects', () => {
+ expect(normalizeAnnotationPoint(1, 1, { left: 0, top: 0, width: 0, height: 10 })).toBeNull();
+ expect(normalizeAnnotationPoint(1, 1, { left: 0, top: 0, width: Number.NaN, height: 10 })).toBeNull();
+ });
+});
+
+describe('shouldAppendAnnotationPoint', () => {
+ it('always accepts the first point and filters jitter', () => {
+ expect(shouldAppendAnnotationPoint({ points: [] }, { x: 0.5, y: 0.5 })).toBe(true);
+ const stroke = { points: [{ x: 0.5, y: 0.5 }] };
+ expect(shouldAppendAnnotationPoint(stroke, { x: 0.5005, y: 0.5 })).toBe(false);
+ expect(shouldAppendAnnotationPoint(stroke, { x: 0.51, y: 0.5 })).toBe(true);
+ });
+});
+
+describe('annotationStrokeToSvgPath', () => {
+ it('renders single points as a tiny segment', () => {
+ expect(annotationStrokeToSvgPath({ points: [{ x: 0.5, y: 0.5 }] }, 100, 100)).toBe('M 50.0 50.0 L 50.1 50.0');
+ });
+ it('renders polylines', () => {
+ expect(
+ annotationStrokeToSvgPath({ points: [{ x: 0, y: 0 }, { x: 1, y: 0.5 }] }, 200, 100),
+ ).toBe('M 0.0 0.0 L 200.0 50.0');
+ });
+ it('returns empty for empty strokes', () => {
+ expect(annotationStrokeToSvgPath({ points: [] }, 100, 100)).toBe('');
+ });
+});
+
+describe('drawAnnotationStrokes', () => {
+ it('draws every outline before any red stroke', () => {
+ const ctx = recordingContext();
+ drawAnnotationStrokes(ctx, STROKES, 1000, 800);
+ const styles = ctx.calls.filter((c) => c[0] === 'strokeStyle').map((c) => c[1]);
+ expect(styles).toEqual([ANNOTATION_OUTLINE_COLOR, ANNOTATION_STROKE_COLOR]);
+ const widths = ctx.calls.filter((c) => c[0] === 'lineWidth').map((c) => c[1]);
+ const w = annotationStrokeWidth(1000, 800);
+ expect(widths).toEqual([annotationOutlineWidth(w), w]);
+ // 3 条非空笔迹 × 2 遍。
+ expect(ctx.calls.filter((c) => c[0] === 'stroke')).toHaveLength(6);
+ });
+});
+
+describe('ANNOTATION_CANVAS_SCRIPT (mobile WebView copy)', () => {
+ const script = loadScript();
+
+ it('computes the same stroke width as the TS implementation', () => {
+ for (const w of [10, 320, 799, 1000, 1179, 1920, 3024, 4096, 8000, 20_000]) {
+ for (const h of [10, 240, 1080, 2556, 4032, 8000, 12_000, 200_000]) {
+ expect(script.width(w, h)).toBe(annotationStrokeWidth(w, h));
+ }
+ }
+ });
+
+ it('issues the exact same canvas calls as drawAnnotationStrokes', () => {
+ for (const [w, h] of [[1000, 800], [1000, 8000], [4096, 3072]] as const) {
+ const expected = recordingContext();
+ drawAnnotationStrokes(expected, STROKES, w, h);
+ const actual = recordingContext();
+ script.draw(actual, STROKES, w, h);
+ expect(actual.calls).toEqual(expected.calls);
+ }
+ });
+});
+
+describe('summarizeAnnotationRegions', () => {
+ it('returns one box per separate mark, sorted top-to-bottom', () => {
+ const regions = summarizeAnnotationRegions([
+ { points: [{ x: 0.6, y: 0.7 }, { x: 0.8, y: 0.9 }] },
+ { points: [{ x: 0.1, y: 0.1 }, { x: 0.2, y: 0.15 }] },
+ ]);
+ expect(regions).toEqual([
+ { x0: 0.1, y0: 0.1, x1: 0.2, y1: 0.15 },
+ { x0: 0.6, y0: 0.7, x1: 0.8, y1: 0.9 },
+ ]);
+ });
+
+ it('merges strokes that overlap or nearly touch (chained merges included)', () => {
+ const regions = summarizeAnnotationRegions([
+ { points: [{ x: 0.1, y: 0.1 }, { x: 0.2, y: 0.2 }] },
+ { points: [{ x: 0.5, y: 0.1 }, { x: 0.6, y: 0.2 }] },
+ // 桥接前两处。
+ { points: [{ x: 0.21, y: 0.15 }, { x: 0.49, y: 0.15 }] },
+ ]);
+ expect(regions).toEqual([{ x0: 0.1, y0: 0.1, x1: 0.6, y1: 0.2 }]);
+ });
+
+ it('handles taps, invalid points and empty input', () => {
+ expect(summarizeAnnotationRegions(undefined)).toEqual([]);
+ expect(summarizeAnnotationRegions([{ points: [] }])).toEqual([]);
+ expect(
+ summarizeAnnotationRegions([{ points: [{ x: Number.NaN, y: 0 }, { x: 0.5, y: 0.5 }] }]),
+ ).toEqual([{ x0: 0.5, y0: 0.5, x1: 0.5, y1: 0.5 }]);
+ });
+
+ it('keeps only the largest regions when there are too many', () => {
+ const strokes: AnnotationStroke[] = [];
+ for (let i = 0; i < MAX_ANNOTATION_REGIONS + 3; i++) {
+ const x = i * 0.1;
+ const size = i === 0 ? 0.001 : 0.05;
+ strokes.push({ points: [{ x, y: 0.5 }, { x: x + size, y: 0.5 + size }] });
+ }
+ const regions = summarizeAnnotationRegions(strokes);
+ expect(regions).toHaveLength(MAX_ANNOTATION_REGIONS);
+ expect(regions.some((r) => r.x0 === 0)).toBe(false);
+ });
+});
+
+describe('sanitizeAnnotationRegions', () => {
+ it('drops malformed entries and clamps values', () => {
+ expect(
+ sanitizeAnnotationRegions([
+ { x0: -1, y0: 0.2, x1: 0.5, y1: 2 },
+ { x0: 0.5, y0: 0.5, x1: 0.1, y1: 0.9 },
+ { x0: 'a', y0: 0, x1: 1, y1: 1 },
+ null,
+ ]),
+ ).toEqual([{ x0: 0, y0: 0.2, x1: 0.5, y1: 1 }]);
+ expect(sanitizeAnnotationRegions('nope')).toBeUndefined();
+ expect(sanitizeAnnotationRegions([])).toBeUndefined();
+ });
+});
+
+describe('formatAnnotationRegion', () => {
+ it('formats with two decimals', () => {
+ expect(formatAnnotationRegion({ x0: 0.1, y0: 0.25, x1: 0.5, y1: 1 })).toBe(
+ 'x 0.10–0.50, y 0.25–1.00',
+ );
+ });
+});
diff --git a/packages/maker-shared/src/imageAnnotation.ts b/packages/maker-shared/src/imageAnnotation.ts
new file mode 100644
index 0000000000..bde833338e
--- /dev/null
+++ b/packages/maker-shared/src/imageAnnotation.ts
@@ -0,0 +1,327 @@
+/**
+ * imageAnnotation — 图片圈点标注的跨端纯函数核心(desktop + mobile 共用)。
+ * ---------------------------------------------------------------------------
+ * 笔迹一律存**归一化坐标**(0..1,相对图片自然尺寸)。显示(SVG overlay)与
+ * 烧录(canvas)共用同一映射与同一线宽,所见即所得。各端只保留自己的事件采集
+ * 与布局推导(desktop 用 getBoundingClientRect,mobile 从容器尺寸 + transform
+ * 推导),视觉参数与绘制算法以本文件为唯一真相源。
+ *
+ * mobile 的烧录跑在 WebView 里(RN 无 DOM canvas),Hermes 不保留函数源码,
+ * 不能 `fn.toString()` 注入,因此 WebView 侧脚本以 ES5 字符串
+ * `ANNOTATION_CANVAS_SCRIPT` 维护;单测把它在 node 里求值,与本文件的
+ * TS 实现逐调用对比,保证两份实现不漂移。
+ */
+
+export interface AnnotationPoint {
+ x: number;
+ y: number;
+}
+
+/** 一条手绘笔迹:归一化坐标点序列(0..1,相对图片自然尺寸)。 */
+export interface AnnotationStroke {
+ points: AnnotationPoint[];
+}
+
+/** 标注笔迹主色(红,语义豁免色;白描边保证深色 / 红色背景上仍醒目)。 */
+export const ANNOTATION_STROKE_COLOR = '#FF3B30';
+export const ANNOTATION_OUTLINE_COLOR = 'rgba(255,255,255,0.9)';
+
+/** 白描边相对红线的宽度倍率。 */
+export const ANNOTATION_OUTLINE_WIDTH_RATIO = 1.8;
+/** 采集时的最小点距(归一化):小于该距离的 move 点丢弃,抑制点数爆炸。 */
+export const MIN_POINT_DISTANCE_RATIO = 0.002;
+
+/**
+ * 模型侧图片预处理的长边目标(maker-core image-resizer 的 MAX_LONG_EDGE)。
+ * 线宽下限按"缩到该长边后仍至少 {@link MODEL_VISIBLE_MIN_LINE_PX} px"推导,
+ * 避免超长截图上的笔迹在送模前被缩没。
+ */
+const MODEL_IMAGE_LONG_EDGE = 1568;
+const MODEL_VISIBLE_MIN_LINE_PX = 3;
+/** 长边兜底项相对短边的上限,防止极端长宽比下线条糊满整张图。 */
+const LONG_EDGE_TERM_MAX_SHORT_RATIO = 0.02;
+
+/** 归一化坐标保留的小数位:1e-4 在 10000px 边长上也只有 1px,肉眼无差。 */
+const COORDINATE_DECIMALS = 4;
+
+function clamp01(v: number): number {
+ return Math.min(1, Math.max(0, v));
+}
+
+/**
+ * 屏幕 / 容器坐标 → 归一化图片坐标。`rect` 为图片当前的实际显示矩形。
+ * 越界点钳制到边缘(画到图外时贴边),坐标量化到 4 位小数以缩小持久化体积。
+ */
+export function normalizeAnnotationPoint(
+ pointX: number,
+ pointY: number,
+ rect: { left: number; top: number; width: number; height: number },
+): AnnotationPoint | null {
+ if (!(rect.width > 0) || !(rect.height > 0)) return null;
+ return {
+ x: quantizeAnnotationCoordinate(clamp01((pointX - rect.left) / rect.width)),
+ y: quantizeAnnotationCoordinate(clamp01((pointY - rect.top) / rect.height)),
+ };
+}
+
+export function quantizeAnnotationCoordinate(v: number): number {
+ const factor = 10 ** COORDINATE_DECIMALS;
+ return Math.round(v * factor) / factor;
+}
+
+/**
+ * 是否应把新点追加进笔迹:与上一点距离(归一化)超过阈值才收,
+ * 抑制高频 move 事件造成的点数爆炸。首点恒收。
+ */
+export function shouldAppendAnnotationPoint(
+ stroke: AnnotationStroke,
+ point: AnnotationPoint,
+ minDistance = MIN_POINT_DISTANCE_RATIO,
+): boolean {
+ const last = stroke.points[stroke.points.length - 1];
+ if (!last) return true;
+ return Math.hypot(point.x - last.x, point.y - last.y) >= minDistance;
+}
+
+/**
+ * 烧录 / 显示用线宽(像素,相对图片自然尺寸)。
+ *
+ * - 主项:0.5% 短边,4px 下限、24px 上限(常规比例图片的一贯观感)。
+ * - 长边兜底:超长截图(如 1000×8000)按短边算只有 5px,送模前缩到长边 1568
+ * 后不足 1px、基本被压没;因此再保证"缩到 1568 长边后仍 ≥3px",该项以
+ * 2% 短边封顶。长宽比约 2.6:1 以内的图片兜底项永远不超过主项,线宽与旧公式
+ * 完全一致。
+ */
+export function annotationStrokeWidth(naturalWidth: number, naturalHeight: number): number {
+ const shortEdge = Math.min(naturalWidth, naturalHeight);
+ const longEdge = Math.max(naturalWidth, naturalHeight);
+ const primary = Math.min(24, Math.max(4, shortEdge * 0.005));
+ const longEdgeFloor = Math.min(
+ (longEdge / MODEL_IMAGE_LONG_EDGE) * MODEL_VISIBLE_MIN_LINE_PX,
+ shortEdge * LONG_EDGE_TERM_MAX_SHORT_RATIO,
+ );
+ return Math.round(Math.max(primary, longEdgeFloor));
+}
+
+/** 白描边线宽(与 {@link annotationStrokeWidth} 配套)。 */
+export function annotationOutlineWidth(strokeWidth: number): number {
+ return Math.round(strokeWidth * ANNOTATION_OUTLINE_WIDTH_RATIO);
+}
+
+/**
+ * 归一化笔迹 → SVG path `d`(映射到 width×height 像素空间)。
+ * 单点笔迹(点按)画一个极短线段,配合 round linecap 呈现为圆点。
+ */
+export function annotationStrokeToSvgPath(
+ stroke: AnnotationStroke,
+ width: number,
+ height: number,
+): string {
+ const pts = stroke.points;
+ if (pts.length === 0) return '';
+ const fmt = (p: AnnotationPoint) => `${(p.x * width).toFixed(1)} ${(p.y * height).toFixed(1)}`;
+ if (pts.length === 1) {
+ const x = pts[0].x * width;
+ const y = pts[0].y * height;
+ return `M ${x.toFixed(1)} ${y.toFixed(1)} L ${(x + 0.1).toFixed(1)} ${y.toFixed(1)}`;
+ }
+ return `M ${fmt(pts[0])} ${pts.slice(1).map((p) => `L ${fmt(p)}`).join(' ')}`;
+}
+
+/** canvas 2D context 中烧录所需的最小接口(便于单测注入 fake)。 */
+export interface AnnotationCanvasContext {
+ lineCap: string;
+ lineJoin: string;
+ strokeStyle: unknown;
+ lineWidth: number;
+ beginPath(): void;
+ moveTo(x: number, y: number): void;
+ lineTo(x: number, y: number): void;
+ stroke(): void;
+}
+
+/**
+ * 把笔迹重放到 canvas context(width×height 为绘制目标尺寸)。
+ * 两遍绘制:先全部白描边、再全部红线——笔迹交叉处不会出现白边压红线的断裂。
+ * SVG 预览必须保持同一分层顺序(先全部描边层、后全部红线层)。
+ */
+export function drawAnnotationStrokes(
+ ctx: AnnotationCanvasContext,
+ strokes: readonly AnnotationStroke[],
+ width: number,
+ height: number,
+): void {
+ const strokeWidth = annotationStrokeWidth(width, height);
+ ctx.lineCap = 'round';
+ ctx.lineJoin = 'round';
+ const drawPass = (color: string, lineWidth: number) => {
+ ctx.strokeStyle = color;
+ ctx.lineWidth = lineWidth;
+ for (const stroke of strokes) {
+ const pts = stroke.points;
+ if (!pts || pts.length === 0) continue;
+ ctx.beginPath();
+ ctx.moveTo(pts[0].x * width, pts[0].y * height);
+ if (pts.length === 1) {
+ ctx.lineTo(pts[0].x * width + 0.1, pts[0].y * height);
+ } else {
+ for (let i = 1; i < pts.length; i++) {
+ ctx.lineTo(pts[i].x * width, pts[i].y * height);
+ }
+ }
+ ctx.stroke();
+ }
+ };
+ drawPass(ANNOTATION_OUTLINE_COLOR, annotationOutlineWidth(strokeWidth));
+ drawPass(ANNOTATION_STROKE_COLOR, strokeWidth);
+}
+
+/**
+ * {@link annotationStrokeWidth} 与 {@link drawAnnotationStrokes} 的 ES5 字符串版,
+ * 供 mobile 烧录 WebView 内联。定义两个全局函数:
+ * `cindyAnnotationStrokeWidth(width, height)` 与
+ * `cindyDrawAnnotationStrokes(ctx, strokes, width, height)`。
+ * 修改任一实现必须同步另一份;`imageAnnotation.test.ts` 会逐调用比对。
+ */
+export const ANNOTATION_CANVAS_SCRIPT = `
+function cindyAnnotationStrokeWidth(width, height) {
+ var shortEdge = Math.min(width, height);
+ var longEdge = Math.max(width, height);
+ var primary = Math.min(24, Math.max(4, shortEdge * 0.005));
+ var longEdgeFloor = Math.min(
+ (longEdge / ${MODEL_IMAGE_LONG_EDGE}) * ${MODEL_VISIBLE_MIN_LINE_PX},
+ shortEdge * ${LONG_EDGE_TERM_MAX_SHORT_RATIO}
+ );
+ return Math.round(Math.max(primary, longEdgeFloor));
+}
+function cindyDrawAnnotationStrokes(ctx, strokes, width, height) {
+ var strokeWidth = cindyAnnotationStrokeWidth(width, height);
+ ctx.lineCap = 'round';
+ ctx.lineJoin = 'round';
+ function drawPass(color, lineWidth) {
+ ctx.strokeStyle = color;
+ ctx.lineWidth = lineWidth;
+ for (var s = 0; s < strokes.length; s++) {
+ var pts = strokes[s].points;
+ if (!pts || pts.length === 0) continue;
+ ctx.beginPath();
+ ctx.moveTo(pts[0].x * width, pts[0].y * height);
+ if (pts.length === 1) {
+ ctx.lineTo(pts[0].x * width + 0.1, pts[0].y * height);
+ } else {
+ for (var i = 1; i < pts.length; i++) {
+ ctx.lineTo(pts[i].x * width, pts[i].y * height);
+ }
+ }
+ ctx.stroke();
+ }
+ }
+ drawPass(${JSON.stringify(ANNOTATION_OUTLINE_COLOR)}, Math.round(strokeWidth * ${ANNOTATION_OUTLINE_WIDTH_RATIO}));
+ drawPass(${JSON.stringify(ANNOTATION_STROKE_COLOR)}, strokeWidth);
+}
+`;
+
+/** 归一化矩形区域(0..1)。 */
+export interface AnnotationRegion {
+ x0: number;
+ y0: number;
+ x1: number;
+ y1: number;
+}
+
+/** 区域合并时的邻近容差(归一化):相距小于它的笔迹视为同一处标注。 */
+const REGION_MERGE_GAP = 0.02;
+/** 单张图最多描述的区域数;超出时只保留面积最大的若干处。 */
+export const MAX_ANNOTATION_REGIONS = 6;
+
+function regionsTouch(a: AnnotationRegion, b: AnnotationRegion, gap: number): boolean {
+ return a.x0 - gap <= b.x1 && b.x0 - gap <= a.x1 && a.y0 - gap <= b.y1 && b.y0 - gap <= a.y1;
+}
+
+function roundRegionCoordinate(v: number): number {
+ return Math.round(clamp01(v) * 100) / 100;
+}
+
+/**
+ * 把笔迹归纳为若干标注区域(每处标注的外接框,归一化坐标,保留两位小数)。
+ * 相交或相距很近的笔迹合并为一处(一次圈选常由多笔组成);结果按从上到下、
+ * 从左到右排序,最多 {@link MAX_ANNOTATION_REGIONS} 处(超出时保留面积最大的)。
+ * 用于给模型的隐藏说明,帮助它在多处标注 / 多张图时定位用户所指。
+ */
+export function summarizeAnnotationRegions(
+ strokes: readonly AnnotationStroke[] | undefined,
+): AnnotationRegion[] {
+ if (!strokes) return [];
+ let regions: AnnotationRegion[] = [];
+ for (const stroke of strokes) {
+ const pts = stroke?.points;
+ if (!Array.isArray(pts) || pts.length === 0) continue;
+ let x0 = Infinity;
+ let y0 = Infinity;
+ let x1 = -Infinity;
+ let y1 = -Infinity;
+ for (const p of pts) {
+ if (!Number.isFinite(p?.x) || !Number.isFinite(p?.y)) continue;
+ x0 = Math.min(x0, p.x);
+ y0 = Math.min(y0, p.y);
+ x1 = Math.max(x1, p.x);
+ y1 = Math.max(y1, p.y);
+ }
+ if (!Number.isFinite(x0)) continue;
+ regions.push({ x0: clamp01(x0), y0: clamp01(y0), x1: clamp01(x1), y1: clamp01(y1) });
+ }
+ // 反复合并直到稳定:合并后的框可能又与其它框相邻。
+ let merged = true;
+ while (merged) {
+ merged = false;
+ const next: AnnotationRegion[] = [];
+ for (const region of regions) {
+ const target = next.find((candidate) => regionsTouch(candidate, region, REGION_MERGE_GAP));
+ if (target) {
+ target.x0 = Math.min(target.x0, region.x0);
+ target.y0 = Math.min(target.y0, region.y0);
+ target.x1 = Math.max(target.x1, region.x1);
+ target.y1 = Math.max(target.y1, region.y1);
+ merged = true;
+ } else {
+ next.push({ ...region });
+ }
+ }
+ regions = next;
+ }
+ if (regions.length > MAX_ANNOTATION_REGIONS) {
+ const area = (r: AnnotationRegion) => (r.x1 - r.x0) * (r.y1 - r.y0);
+ regions = [...regions].sort((a, b) => area(b) - area(a)).slice(0, MAX_ANNOTATION_REGIONS);
+ }
+ return regions
+ .map((r) => ({
+ x0: roundRegionCoordinate(r.x0),
+ y0: roundRegionCoordinate(r.y0),
+ x1: roundRegionCoordinate(r.x1),
+ y1: roundRegionCoordinate(r.y1),
+ }))
+ .sort((a, b) => a.y0 - b.y0 || a.x0 - b.x0);
+}
+
+/** 校验并规范化外部传入的区域列表(跨端 / 持久化数据不可信)。 */
+export function sanitizeAnnotationRegions(value: unknown): AnnotationRegion[] | undefined {
+ if (!Array.isArray(value)) return undefined;
+ const out: AnnotationRegion[] = [];
+ for (const item of value) {
+ if (!item || typeof item !== 'object') continue;
+ const r = item as Record<string, unknown>;
+ const coords = [r.x0, r.y0, r.x1, r.y1];
+ if (!coords.every((c) => typeof c === 'number' && Number.isFinite(c))) continue;
+ const [x0, y0, x1, y1] = (coords as number[]).map(roundRegionCoordinate);
+ if (x1 < x0 || y1 < y0) continue;
+ out.push({ x0, y0, x1, y1 });
+ if (out.length >= MAX_ANNOTATION_REGIONS) break;
+ }
+ return out.length > 0 ? out : undefined;
+}
+
+/** 区域 → 模型可读的短文本,如 `x 0.31–0.46, y 0.12–0.20`。 */
+export function formatAnnotationRegion(region: AnnotationRegion): string {
+ const f = (v: number) => v.toFixed(2);
+ return `x ${f(region.x0)}–${f(region.x1)}, y ${f(region.y0)}–${f(region.y1)}`;
+}