Rework layout engine around exact-glyph collision, add tests and docs sync
Replace the old bbox/heuristic placement (scale search rounds, large-font capping, stratified sampling, fill-retry ladders) with an area-model font sizing pass feeding a C++ exact-glyph collision engine (centroid-biased spiral + random probing, HD clearance refinement, density/hole optimization). Simplify the frontend advanced-params panel and JobParams type to match the surviving config surface, add a layout-constraints test suite and a repeatable benchmark tool, and bring docs/*.md back in sync with current code (plus new TESTING.md and DEPLOYMENT.md). Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
This commit is contained in:
Claude Sonnet 5
+72
-37
@@ -1,23 +1,30 @@
|
||||
# 画布与贴纸功能
|
||||
|
||||
本文档描述当前前端代码中已经实现的画布设计功能。事实来源是 `frontend/src/App.tsx`、`frontend/src/pages/CanvasStudio.tsx`、`frontend/src/components/ExportPanel.tsx`、`frontend/src/lib/stickerLibrary.ts` 和 `frontend/src/types.ts`。
|
||||
本文档描述当前前端代码中已实现的画布设计功能。事实来源是 `frontend/src/pages/CanvasStudio.tsx`、`frontend/src/App.tsx`、`frontend/src/components/ExportPanel.tsx`、`frontend/src/lib/stickerLibrary.ts`、`frontend/src/lib/canvasDocument.ts` 和 `frontend/src/types.ts`。
|
||||
|
||||
## 页面关系
|
||||
|
||||
- 应用默认进入画布设计页。
|
||||
- 画布页顶部的“添加词云”会切换到原有词云生成页。
|
||||
- 词云生成页顶部的“返回画布”会回到画布设计页。
|
||||
- 词云生成页的导出面板保留下载 SVG/位图功能，并新增“作为贴纸导入贴纸库”。
|
||||
```
|
||||
TemplateHome（首页）
|
||||
├── CanvasStudio（画布设计页）─ 添加词云 ─→ TestWorkbench（词云生成页）
|
||||
├── TestWorkbench（词云生成页）─ 返回画布 ─→ CanvasStudio
|
||||
└── HelpPage（帮助页）
|
||||
```
|
||||
|
||||
- 应用默认进入首页，展示模板列表
|
||||
- 画布页顶部的"添加词云"会切换到词云生成页
|
||||
- 词云生成页顶部的"返回画布"会回到画布设计页
|
||||
- 词云生成页导出面板保留下载 SVG/位图功能，并新增"作为贴纸导入贴纸库"
|
||||
|
||||
## 贴纸库
|
||||
|
||||
贴纸库是前端本地能力，不依赖后端接口：
|
||||
|
||||
- 存储位置：`localStorage` 的 `wordcloud-sticker-library`。
|
||||
- 数据类型：`StickerAsset`，当前支持 `svg` 和 `image` 两类，已实现入口主要使用 `svg`。
|
||||
- 用户导入 SVG：画布页左侧“贴纸”面板读取 `.svg` 文件文本，写入贴纸库，并立即插入画布。
|
||||
- 词云作为贴纸：导出面板按当前 SVG 导出参数请求 `/api/jobs/{job_id}/custom.svg`，读取返回的 SVG 文本后写入贴纸库。
|
||||
- 贴纸删除只删除本地贴纸库记录，不会删除已经导出的总图文件。
|
||||
- 存储位置：`localStorage` 的 `wordcloud-sticker-library`
|
||||
- 数据类型：`StickerAsset`，当前支持 `svg` 和 `image` 两类，已实现入口主要使用 `svg`
|
||||
- 用户导入 SVG：画布页左侧"贴纸"面板读取 `.svg` 文件文本，写入贴纸库，并立即插入画布
|
||||
- 词云作为贴纸：导出面板按当前 SVG 导出参数请求 `/api/jobs/{job_id}/custom.svg`，读取返回的 SVG 文本后写入贴纸库
|
||||
- 贴纸删除只删除本地贴纸库记录，不会删除已经导出的总图文件
|
||||
|
||||
## 画布模型
|
||||
|
||||
@@ -25,43 +32,71 @@
|
||||
|
||||
当前模型字段：
|
||||
|
||||
- `width`：画布宽度，默认 `1600`。
|
||||
- `height`：画布高度，默认 `1000`。
|
||||
- `background`：画布背景色，默认 `#ffffff`。
|
||||
- `elements`：画布元素数组。
|
||||
- `width`：画布宽度，默认 `1600`
|
||||
- `height`：画布高度，默认 `1000`
|
||||
- `background`：画布背景色，默认 `#ffffff`，支持透明 `#00000000`
|
||||
- `elements`：画布元素数组
|
||||
- `layers`：图层数组（可选，支持可见性、锁定、文件夹分组）
|
||||
- `layerFolders`：图层文件夹数组（可选）
|
||||
|
||||
当前元素类型：
|
||||
|
||||
- `sticker`：引用贴纸库中的 SVG 或图片。
|
||||
- `text`：普通文字，支持内容、颜色、字号、字体、字重、位置、尺寸、旋转、透明度。
|
||||
- `rect`：矩形，支持填充、描边、描边宽度、位置、尺寸、旋转、透明度。
|
||||
- `ellipse`：椭圆，支持填充、描边、描边宽度、位置、尺寸、旋转、透明度。
|
||||
- `line`：线条，支持描边、描边宽度、位置、尺寸、旋转、透明度。
|
||||
- `sticker`：引用贴纸库中的 SVG 或图片（`assetId`）
|
||||
- `text`：普通文字（内容、颜色、字号、字体、字重、位置、尺寸、旋转、透明度）
|
||||
- `rect`：矩形（填充、描边、描边宽度、位置、尺寸、旋转、透明度）
|
||||
- `ellipse`：椭圆（同上）
|
||||
- `line`：线条（描边、描边宽度、位置、尺寸、旋转、透明度）
|
||||
|
||||
## 编辑行为
|
||||
|
||||
- 点击贴纸库中的贴纸会把该贴纸插入画布中央区域。
|
||||
- 画布元素可拖拽移动。
|
||||
- 选中元素后可通过右下角手柄调整大小。
|
||||
- 右侧属性面板可以精确编辑位置、尺寸、旋转、透明度和元素特有属性。
|
||||
- 右侧属性面板提供上移、下移和删除。
|
||||
- 画布面板支持修改画布宽高、背景色、导出 SVG、清空画布。
|
||||
- 点击贴纸库中的贴纸会把该贴纸插入画布中央区域
|
||||
- 画布元素支持：
|
||||
- **拖拽移动**：鼠标/触摸拖拽
|
||||
- **大小调整**：选中后通过右下角手柄调整
|
||||
- **精确编辑**：右侧面板可修改位置、尺寸、旋转、透明度、元素特有属性
|
||||
- **层级调整**：上移、下移
|
||||
- **删除**：删除元素
|
||||
- 右侧面板支持修改画布宽高、背景色
|
||||
- 支持导出总图 SVG、清空画布
|
||||
- **图层管理**：支持图层可见性、锁定、文件夹分组
|
||||
- **吸附对齐**：元素拖拽时自动吸附到附近元素边缘
|
||||
- **缩放**：编辑视图可缩放（不影响导出尺寸）
|
||||
|
||||
## SVG 导出
|
||||
|
||||
“导出总图 SVG”由前端序列化当前画布模型完成：
|
||||
"导出总图 SVG"由前端序列化当前画布模型完成：
|
||||
|
||||
- 导出文件名：`canvas-design.svg`。
|
||||
- 背景输出为一个覆盖全画布的 `<rect>`。
|
||||
- 贴纸输出为 `<image>`，SVG 贴纸会以内联 `data:image/svg+xml` 的形式嵌入。
|
||||
- 文字输出为 `<text>`。
|
||||
- 基础形状输出为原生 SVG 的 `<rect>`、`<ellipse>`、`<line>`。
|
||||
- 元素的位移和旋转写入 SVG `transform`，透明度写入 `opacity`。
|
||||
- 导出文件名：`canvas-design.svg`
|
||||
- 背景输出为一个覆盖全画布的 `<rect>`（透明背景时 fill="none"）
|
||||
- 贴纸输出为 `<image>`，SVG 贴纸会以内联 `data:image/svg+xml` 的形式嵌入
|
||||
- 文字输出为 `<text>`
|
||||
- 基础形状输出为原生 SVG 的 `<rect>`、`<ellipse>`、`<line>`
|
||||
- 元素的位移和旋转写入 SVG `transform`，透明度写入 `opacity`
|
||||
|
||||
## ZIP 导出
|
||||
|
||||
支持导出含以下内容的 ZIP 包：
|
||||
|
||||
- `canvas.svg`：总图 SVG
|
||||
- `sticker_{id}.svg`：画布中所有独立 SVG 贴纸
|
||||
- `manifest.json`：元素元数据清单
|
||||
|
||||
## 同底图换名单（Replace Session）
|
||||
|
||||
画布页支持"替换词云名单"功能：
|
||||
|
||||
1. 用户右键点击画布上的词云贴纸，选择"同底图换名单"
|
||||
2. 生成一个 `WordcloudReplaceSession`，包含：
|
||||
- `mask`：原词云的底图遮罩（SVG/Image）
|
||||
- `target`：目标元素信息（含宽度、高度、原遮罩元素 ID）
|
||||
3. 会话传递到词云生成页
|
||||
4. 词云生成页锁定底图，只替换名单内容，生成后自动按原尺寸贴回画布
|
||||
|
||||
## 当前边界
|
||||
|
||||
- 贴纸库和画布文档只保存在当前浏览器本地，不会跨浏览器或跨设备同步。
|
||||
- 当前没有服务端素材库、项目文件格式或协作编辑接口。
|
||||
- SVG 导入按用户信任文件处理；编辑器预览使用图片方式加载，不在页面中直接执行 SVG 内容。
|
||||
- 当前缩放只影响编辑视图，不改变导出尺寸。
|
||||
- 当前导出目标是 SVG；没有在画布页实现 PNG/JPG 总图导出。
|
||||
- 贴纸库和画布文档只保存在当前浏览器 `localStorage`，不会跨浏览器或跨设备同步
|
||||
- 当前没有服务端素材库、项目文件格式或协作编辑接口（Projects 接口存在但服务层级较浅）
|
||||
- SVG 导入按用户信任文件处理；编辑器预览使用图片方式加载，不在页面中直接执行 SVG 内容
|
||||
- 当前缩放只影响编辑视图，不改变导出尺寸
|
||||
- 当前导出目标是 SVG；没有在画布页实现 PNG/JPG 总图导出
|
||||
- 线距分析结果显示在元素属性面板中，辅助激光加工参数设定
|
||||
|
||||
Reference in New Issue
Block a user