Consider it done. The open-source AI agent that works out of the box · 想到,就能做到。开源、开箱即用的 AI Agent。
TypeScript agentai-agentai-assistantandroidclaude-codecodexelectroniosllmmacosreact-nativetypescriptwindows
feat(maker-shared): 抽出图片标注跨端纯函数核心
Dash0cde17f9bdf8
diff --git a/packages/maker-shared/package.json b/packages/maker-shared/package.jsonindex 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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)}`;+}