dsh-drawai 0.2.7 → 0.3.1

package/README.md

@@ -16,6 +16,7 @@
 4. **SVG 图形节点** —— 图标 / logo 可直接当节点内容，拼流程图与示意图。
 5. **位图矢量化（`traceImage`）** —— 照着工作区图片逐像素描成 SVG 节点，不是凭印象手写近似图。
 6. **原生 `.drawio` 载体** —— 无需导入导出；画布读不懂的单元逐字节保留，文件可直接用 drawio / diagrams.net 继续编辑。
+7. **视频复刻** —— 选中已导入视频，点击悬浮工具条「绘制复刻」自主设置画质、帧率、完整视频或起止范围，自动抽帧并绘制成 SVG 视频；显示预计帧数、实际进度与帧预览，支持取消，原视频保留。支持 SVG 帧序列包，以及保留原帧率、白底和片段音频的 MP4 / WebM 离线导出；也可导出白底、循环播放的无声 GIF。渲染、编码和保存由宿主后台执行，切换标签或刷新网页后仍继续，完成文件自动保存到画布旁（编码需 FFmpeg）。详见[视频节点说明](docs/video-nodes.md)。
 
 ![整体界面：右侧栏画布与多标签](docs/picture/整体界面图.png)
 
@@ -70,8 +71,8 @@ dsh plugin --profile web add github:fourzkw/dsh-drawai
 | **画布外观** | 矩形 / 圆角 / 椭圆 / 菱形 / 圆柱 / 文档 / **SVG 图形** / **位图** 等形状族（右侧元素条按族放置）、8 色调色板、白纸 + 网格、正交折线 + 障碍避让、明暗切换 |
 | **SVG 图形节点** | 节点内容直接是一段 **SVG 标记**（图标 / logo / 示意图这种形状词汇表里没有的东西）：右键「SVG 内容…」贴进去即可，或让模型用 `addNode {shape:"svg", svg:"<svg viewBox…>…</svg>"}`。落盘是 drawio **原生**的图片形状（`shape=image` + `image=data:image/svg+xml,<百分号编码>`），所以 drawio 桌面版打开同样画得出来；标记只喂给 `<image>`（独立文档，脚本不执行、也不碰页面 DOM） |
 | **内嵌位图** | 从剪贴板粘贴或拖入 PNG / JPEG / GIF / WebP，画布会**真的画出来**（同为 `shape=image` + data URI）。`diagram_read` 把 base64 省略成 `«image N 字符»`，不撑爆上下文 |
-| **位图矢量化 traceImage** | 让模型照着工作区里一张图**逐像素**描成 SVG 内容节点（读像素 → 泛洪去背景 → k-means 调色板 → 3× 超采样归类 → 按颜色取像素级闭合轮廓 → 每色一条 nonzero path）。形状词汇表表达不了的照片 / 插画走这条，而不是让模型手写一段近似 SVG 冒充复刻 |
-| **文本** | 双击节点就地改字；「T 文字」放一段无边框、无底色的独立文字；字号有 10 / 12 / 14 / 18 / 24 五档，也可以手调 8–72；字色板 |
+| **位图矢量化 traceImage** | 让模型照着工作区里一张图**逐像素**描成 SVG 内容节点（读像素 → 按必填的 `removeBg` 决定是否泛洪抠底 → k-means 调色板 → 3× 超采样归类 → 按颜色取像素级闭合轮廓 → 每色一条 nonzero path）。形状词汇表表达不了的照片 / 插画走这条，而不是让模型手写一段近似 SVG 冒充复刻 |
+| **文本** | 双击节点就地改字。「T 文字」是独立的文字节点；支持字号与字色。图片和视频节点不显示文字 |
 | **连线** | 四选一画法（直线 / 直角折线 / 圆角折线 / 曲线）× 线型（含虚线间距）× 箭头（单向 / 双向 / 无 / 反向）× 颜色 × 引出段长度；自环；悬空端（从节点脱开后成为自由端点，还能再拖回去） |
 | **连线上的文字** | 双击改、按住拖（半格 + 贴线吸附）、右键「标签居中」；**线在文字的位置真的断开**（不盖白底） |
 | **选中与移动** | 框选 / Shift 加选 / `Ctrl+A`；整体拖动（折点与自由端点跟着同一个位移走）；对齐辅助线；多选对齐与分布 |
@@ -104,7 +105,7 @@ dsh plugin --profile web add github:fourzkw/dsh-drawai
 - **照着一张位图描矢量图用 `traceImage`**：
 
   ```
-  diagram_apply({ op:"traceImage", image:"refs/角色.png", x:40, y:40 })
+  diagram_apply({ op:"traceImage", image:"refs/角色.png", removeBg:false, x:40, y:40 })
   ```
 
   它**真的去读那张图的像素**，在宿主里跑一条完整管线：
@@ -112,19 +113,32 @@ dsh plugin --profile web add github:fourzkw/dsh-drawai
   | 步骤 | 做什么 |
   |---|---|
   | ① 解码 | PNG 走**自带解码器**（零依赖，只用 `node:zlib`）；JPEG/GIF/WebP 需要宿主装了 sharp |
-  | ② 去背景 | 从四边泛洪，把近白/近灰/透明像素排除（不画截图底色；与边界不连通的白围裙不会误删） |
+  | ② 去背景 | **`removeBg` 必填**（无 auto）：`true` = 抠（先识纯色底，否则近白泛洪）；`false` = 整图保留。由模型按图意判断后传入 |
   | ③ 调色板 | k-means（K 默认 12，k-means++ 初始化，多次重启取最优）；背景单独占一色 |
   | ④ 归类 | 3× 双线性超采样 → 3×3 众数滤波 → 降回原分辨率 → 小于 `minArea` 的碎块并进**颜色最接近**的邻色 |
   | ⑤ 轮廓 | 按颜色分 4 连通域，沿**像素格边**建"区域恒在左侧"的有向图，左转优先走闭合环（外环顺时针 / 洞逆时针） |
   | ⑥ 输出 | RDP 简化 + 相对增量编码 → 每色一条 `fill-rule="nonzero"` 的 `<path>`，按面积降序铺 |
 
-  - 默认 **`w/h` = 原图像素尺寸**、`viewBox` = 原图像素坐标系，所以画布坐标就是图片坐标（1:1 铺满）。
+  - 默认 **`w/h` = 原图像素尺寸**（裁剪时为裁剪块尺寸）；`viewBox` 使用工作图局部坐标，内容铺满节点框。裁剪时 `x/y` 默认取裁剪原点，按原图像素 1:1 放置；显式 `w/h` 表示裁剪块的目标尺寸。
   - 要更简洁：`colors` 调小、`scale:2|3`（先降采样）、`grid` 调小；要更保真：`epsilon` 调小（默认 2px）、`minArea` 调小（默认 10px²）。
-  - 返回的 summary 会报**色数 / 路径数 / 轮廓环数 / 字符数 / 像素覆盖是否精确**（精确 = 各色轮廓面积之和等于图像总像素，没有像素丢失或重复）。
-  - 单次上限：SVG 标记 60000 字符；宿主会先自己收紧 `epsilon` 与碎块阈值，仍超才报错让你调参。
+  - 返回的 summary 会报**色数 / 路径数 / 轮廓环数 / 字符数 / 量化图轮廓是否无损**。`labelPartitionComplete` 只验证标签分区完整；`exactPixelCoverage` 还要求最终输出保留全部前景轮廓几何，两者都不代表与原图颜色、细节一致。简化后无法证明无损时 `drawnPixels` 为 `null`。
+  - 字符预算充足时不额外按环面积删除小碎片；风格由减色、`epsilon` 与 `minArea` 等参数控制。预算紧时仍会进一步简化、删小环，回执中的 `attempts / appliedEpsilon / loopsDropped / budgetExceeded` 会报告降级与超预算情况。
+  - 单次硬上限：SVG 标记 250000 字符（默认预算 248000）；宿主先收紧轮廓，仍超硬上限才报错让你调参。
   - 落盘仍是 drawio **原生**的图片形状（`shape=image` + `image=data:image/svg+xml,<百分号编码>`），drawio 桌面版打开同样画得出来。
   - **它不是"让模型凭印象画"**：形状取决于像素，同一张图同样的参数跑两次结果一致（已纳入自测）。
 
+  **图像节点工具栏绘制**：单选已导入的位图节点，浮动工具栏出现「绘制」（与填充/描边同款悬停悬浮卡片）。卡片内可选碎片数量档位、画风、颜色数与是否去背景；点「让大肥鱼开始画画！」后先分析原图，再从大色块到细节自动逐步展示完整复刻图，展示过程只保留进度条；原图保留，结果在右侧新建 SVG（同尺寸与图层）。最终完整 SVG 一次落盘，过程不逐帧保存，走正常的撤销和保存通道。
+
+  | 碎片数量 | 效果 |
+  |---|---|
+  | 低 | 粗颗粒棱角色块，保留明显折面与尖角 |
+  | 中 | 中等碎片密度，增加装饰与局部轮廓 |
+  | 高 | 细密棱角碎片，保留更多发丝、衣饰和五官色块 |
+
+  三档以用户提供的三张碎片画风参考图校准，统一使用减色、超采样归类、受保护的小块合并和折线轮廓管线。高档基准长边为 887px，低/中档采样密度分别约为高档的 64%/80%；小图按自身尺寸等比适配，不虚增分辨率。对于校准原图，工作图分别为 320×569、400×711、499×887，三档都使用 2px 折线容差和 10px² 小块阈值。小图的容差、面积阈值按尺寸归一化；不再使用原始像素标签直出或多轮强力合并来追赶数量目标。
+
+  数量区间按当前图像实际测量：分别计算三档碎片数，结合有效面积、碎片密度给出本图参考范围，不为凑数字破坏已校准的画风。极少色图片降采样后若重新聚类产生更多过渡色碎片，会复用高档调色板，避免低档反而更碎。平坦或孤立同色块图片的三档数量可能相同；颜色数独立控制，内部容量无需选择，超限导致额外简化时提示细节降低。外链或相对路径图片须先导入为内嵌位图。
+
 ### `diagram_read` —— 模型怎么看见图
 
 读回：节点 / 边 / 标签、每个单元的**样式键**（就是文件里那串 `style`，另外给出派生的形状、线型、箭头、颜色名便于阅读）、图层表与单元所属层、容器父级 `parent`、页面尺寸、边标签的 `labelX/labelY`、**`revision`**（文件内容指纹）、当前选区。SVG 图形节点的内容单独放在 `svg` 字段里（style 串里的 `image=` 则省略成 `«svg N 字符»`，避免一次读取被 data URI 撑爆）。
@@ -196,7 +210,33 @@ id / layer / parent、选区能上报给模型、写回是逐单元的、画布
 | 显示层、当前层 | 「图层」菜单（会写进文件） |
 
 **右侧常驻元素条**：按类型（图形 / 文字 / 分区 / SVG / 图片）放置，点画布落下**一次**即卸工具；
-「图形」的矩形、圆角、菱形等是同族变体，只在侧面板展开，不全部铺在主条上。悬停或选中图形后可换同族形状。就地改标签用 `Enter` 提交、`Shift+Enter` 换行、`Esc` 取消。
+「图形」的矩形、圆角、菱形等是同族变体，只在侧面板展开，不全部铺在主条上。选中图形后可换同族形状；悬停画布节点不会触发右侧工具栏浮窗。
+
+**选中后的浮动样式工具栏**：选中图形或连线，会在选区附近显示单行工具栏，图标在上、文字标签在下。悬停入口自动展开上方浮窗；形状以图标网格展示，填充与字色使用色板，描边面板合并线型、粗细、颜色和不透明度，字号提供常用档位与手动输入。选中连线时还可改线型和箭头。支持批量修改，保留每个对象未修改的样式；字号输入后按 Enter 或点击外部生效。窄面板可水平滚动，右键菜单仍可使用。
+
+图片、视频绘制及 AI 视频抽帧由宿主持久队列执行，提交前自动保存素材，不需要手工确认保存。切换页面、对话、关闭画布或刷新网页后继续计算并安全写入原画布。统一后台任务面板支持筛选、排序、暂停续绘、重试、打开原页面和撤销单次生成；发生冲突时保留产物及本地编辑。宿主重启后未完成绘制标为中断，可校验检查点后继续；导出需重新编码。原视频和复刻片段保留音频来源。详见[后台任务说明](docs/background-workflow-assessment.md)。
+
+「形状」仅在选区内的节点全部属于基础图形时显示，选项也仅包含矩形、椭圆等基础图形。SVG、图片、文字、分区节点及包含这些节点的混合选区不提供直接换形入口，以保留原有内容和节点类别。
+
+图片、SVG 内容和视频默认没有外框，不提供无效的描边工具；独立文字同样隐藏描边。混合选择时，描边只修改有边框的图形和连线。图片、视频及独立文字的右键菜单只提供字色，不提供无效的填充与描边配色。
+
+单选图像或 SVG 节点，通过悬浮工具栏「导出图片」或右键菜单即可下载，无需先保存画布。位图保留 PNG / JPEG / GIF / WebP 原格式、原始分辨率和透明度；SVG 可选择「导出 SVG」保留矢量内容，或「导出 PNG」按节点尺寸的 4× 分辨率生成透明背景位图（超大尺寸自动限制）。文件名优先使用节点标签，没有标签时使用节点 ID。
+
+浮动工具栏的填充、描边和字色均使用色板：点击颜色入口展开 24 个标准颜色与已保存的自定义颜色。自定义颜色可用取色器或输入 `#RGB` / `#RRGGBB`，点击「添加并应用」后存入本机偏好；三个颜色入口及本机其他画布共用自定义颜色，刷新后仍保留。
+
+各工具面板以独立浮窗优先显示在工具栏上方，靠近窗口边缘时自动调整位置，不撑开工具栏。移出入口后延迟关闭，鼠标进入浮窗会保持打开；点击外部或按 Esc 关闭。色板使用圆形色块、蓝色选中色环与「无颜色」选项，点击「＋」展开自定义颜色输入；底部滑杆可设置填充、描边或文字的不透明度，选色后面板保持打开以便继续调整。
+
+右键菜单用于编辑，不提供创建元素入口：空白处保留撤销、重做、全选和粘贴；节点、连线与多选菜单提供复制、剪切、粘贴等操作，不可用时禁用。新建图形或连线请使用右侧元素条；已有 SVG 节点仍可右键编辑 SVG 内容。
+
+**图层面板**：右上角「图层」以列表显示每层的内容缩略图、名称、元素数量、可见性和锁定状态，隐藏层也保留缩略图。点击名称或缩略图设为当前层；双击名称或点击铅笔编辑名称，Enter/点击外部保存，Esc 取消。新建图层会立即进入命名；更多菜单可合并并删除图层，删除时内容移入相邻层。底部的目标选择器可移动选中元素，锁定层不能作为目标；超过八层时支持搜索。
+
+**导出面板**：右上角「导出」可选择当前页全部可见图层、选区、当前图层或指定多个图层，支持 PNG/SVG、透明背景与文件名。展开「更多设置」可指定像素宽高、保持宽高比、调整四周留白、独立开关网格，并选择预设或自定义背景色；PNG 也可按 1×/2×/4× 输出。面板显示实际输出尺寸，并通过编码预估文件大小，下载复用相同结果。显式选择隐藏图层时也会导出其内容。PNG 单边最多 16384 像素、总像素约 3200 万，超出时等比缩小并提示；SVG 保留矢量内容。导出设置记入本机偏好。文件、编辑、视图菜单按用途分组，快捷键单列；页面切换集中到视图中的页面选择器。
+
+**就地文字编辑**：双击节点或连线标签开始编辑，`Enter` / `Shift+Enter` 换行，点击外部或 `Ctrl+Enter`（Mac 为 `Command+Enter`）完成，`Esc` 取消。输入法确认文字不会提前完成编辑。
+
+编辑框与显示标签共用文字区域、字体、行高和缩放：普通节点居中，分区标题左上对齐；换行在浏览器中按实际字体宽度计算，编辑中的节点撑高会先预览再提交。连线标签也支持多行显示，并按实际字号设置编辑框与连线避让区域。
+
+**连线工具与修改入口**：悬停右侧连线图标选择直线、直角折线、圆角折线或曲线，然后在空白处拖拽确定起终点；直接点击连线图标使用上次选择的类型。连线工具用于新建；修改已有连线请选中后使用浮动工具栏的「线型」，也可使用右键菜单。
 
 ## 须知 / Good to know
 
@@ -211,7 +251,7 @@ id / layer / parent、选区能上报给模型、写回是逐单元的、画布
 - **多页**：可切换编辑当前页（视图菜单）；其它页保存时原样保留。AI 可用 `diagram_read` / `diagram_apply` 的 `page` 参数指定页。多页的**新建页**尚未实现。
 - 独立 `edgeLabel` 单元只读；`entityRelation` 等其它 edgeStyle、箭头字形、旋转 / 翻转 / 透明、stencil 形状只保留、不渲染；`.drawio.svg` / `.png` / `.html` 内嵌载体不支持。
 - **图片**：内嵌 SVG（`data:image/svg+xml,…`）与内嵌位图（PNG/JPEG/GIF/WebP data URI）都会画出来；**外链 / 相对路径**图片仍按矩形占位，单元原样保留（工作区磁盘上的图片文件画布直接读不到——要复刻请用 `traceImage`）。
-- 导出只有 SVG、PNG(4×) 与透明 PNG(4×)：没有 PDF。
+- 导出支持 SVG 与 PNG（透明背景、倍数或指定尺寸）：没有 PDF。
 - 交互细节：对齐辅助线只跟节点比（不与折点、端点对齐）；单条选中的连线不能复制。
 
 完整的取舍与实现细节在 [docs/design.md](docs/design.md)。
@@ -230,6 +270,8 @@ npm test        # 六份自测（mxfile 编解码 / 路由预览 / 宿主行为
 
 目录结构，以及两侧各自的生效路径，见 [docs/design.md 的「目录」一节](docs/design.md#目录)。
 
+本机参考图片放在 `_local/references/`，视频示例及其同名 `.media/` 资源目录放在 `_local/video-demo/`，下载文件、辅助工具与历史自检输出分别归入 `_local/downloads/`、`_local/tools/` 和 `_local/artifacts/`。这些内容不提交 Git；可复现的测试夹具保留在 `tools/fixtures/`。测试自动生成的根目录 `artifacts/` 同样忽略。
+
 ## 觉得有用？ / Like it?
 
 如果这块画布帮上了忙，欢迎在 [GitHub](https://github.com/fourzkw/dsh-drawai) 上点个 ⭐；issue 与 PR 同样欢迎。