From 84895bd9bd4f2aec4c30305e779ec057456d3920 Mon Sep 17 00:00:00 2001 From: admin <572701190@qq.com> Date: Mon, 4 May 2026 04:36:53 +0800 Subject: [PATCH] =?UTF-8?q?=E6=98=BE=E7=A4=BA=E6=96=B0=E5=BB=BA=E5=9B=BE?= =?UTF-8?q?=E5=BD=A2=E8=BE=B9=E7=95=8C=E7=82=B9=E5=B9=B6=E9=AA=8C=E8=AF=81?= =?UTF-8?q?=E4=B8=AD=E7=A9=BA=E7=94=BB=E7=AC=94?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 让多边形、矩形和圆创建完成后即使仍处于创建工具，也显示已选 mask 的边界顶点。 - 保持创建工具下的边界点为只读提示，不改变继续创建新 mask 的交互。 - 补充 Canvas 回归测试，覆盖矩形、圆、多边形创建后的边界点显示。 - 补充中空画笔回归测试，验证闭合画笔区域保留 hasHoles/polygonRingCounts、evenodd 渲染和内外圈顶点显示。 - 更新 README、AGENTS、前端审计、需求冻结、设计冻结、测试计划和交互状态机文档。 --- AGENTS.md | 2 +- README.md | 2 +- doc/03-frontend-element-audit.md | 4 +-- doc/07-current-requirements-freeze.md | 4 +-- doc/08-current-design-freeze.md | 4 +-- doc/09-test-plan.md | 5 +-- doc/11-frontend-interaction-state-machines.md | 6 ++-- src/components/CanvasArea.test.tsx | 34 +++++++++++++++++++ src/components/CanvasArea.tsx | 3 +- 9 files changed, 50 insertions(+), 14 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 0915726..9c90b41 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -245,7 +245,7 @@ uvicorn main:app --host 0.0.0.0 --port 8000 --reload 5. 生成帧入队：用户在项目库点击“生成帧”，选择目标 FPS 后前端调用 `/api/media/parse`；后端创建 `ProcessingTask` 并投递 Celery，接口支持 `parse_fps`、`max_frames` 和 `target_width` 标准帧序列参数；项目库和模板库的成功/失败短反馈使用非阻塞 `TransientNotice`，会自动消失。 6. worker 执行：Celery worker 用 FFmpeg 优先拆视频帧，失败后用 OpenCV fallback，DICOM 使用 pydicom；worker 下载和读取 DICOM 时也按文件名自然顺序排序；视频/DICOM 解析完成后都按 `frame_%06d.jpg` 连续生成项目帧序列，并记录 `timestamp_ms`、`source_frame_number` 和任务 `frame_sequence` 元数据，后续工作区、时间轴、AI 传播、标注和导出共用同一套帧序列逻辑。 7. 帧展示：`VideoWorkspace.tsx` 调用 `/api/projects/{id}/frames`，`CanvasArea.tsx` 和 `FrameTimeline.tsx` 显示当前帧与时间轴缩略图；`CanvasArea` 会按容器和帧尺寸默认居中放大底图并保留边距，右下角显示“当前帧：XX/XXX”；`FrameTimeline` 会根据已保存标注回显到 `Mask.metadata` 的传播来源，把自动传播生成的帧在视频处理进度条显示为蓝色区段，人工/AI 标注帧显示红色竖线；每次自动传播成功处理帧后，`VideoWorkspace` 会把本次传播范围作为当前会话历史片段传给 `FrameTimeline`，在视频处理进度条上叠加同一蓝色系、最新传播最亮、旧传播逐次变暗且第 5 次及更早统一为阈值旧记录色的纯色条；传播历史条只显示当前仍有自动传播 mask 的帧，删除 mask 或清空范围后会按剩余传播 mask 自动裁剪，空帧不保留红/蓝颜色；视频处理进度条和红/蓝标识可点击跳转到对应帧；底部缩略图中人工/AI 标注帧用红色边框、自动传播/推理帧用蓝色边框，同一帧同时具备两种状态时红色标注边框优先保留，蓝色传播状态以内描边表达；当前帧仍以青色外框高亮优先；若当前帧同时是人工/AI 标注帧，则在青色外框内增加红色内描边，固定为外层当前帧、内层人工/AI 标注；进入自动传播、布尔操作或特定范围帧导出选择模式时，播放进度条和视频处理进度条会显示黄色范围框，并可点击/拖拽选择起止帧；前端 `Frame` 会保留后端返回的帧序列时间戳和源帧号。 -8. 手工标注：`CanvasArea.tsx` 支持多边形、矩形、圆、画笔和橡皮擦生成/编辑 polygon mask；多边形可按 Enter 或点击首节点闭合；多边形/矩形/圆在右侧语义分类树未选中类别时会自动归入黑色 `maskid:0` 的“待分类”；切换到创建多边形、创建矩形或创建圆时会清空旧 mask 选区，创建完成后自动选中新 mask；按 `Esc` 或点击左侧工具栏“取消选中”按钮会清空当前 mask 选区和临时绘制状态；画笔/橡皮擦可在左侧工具栏调整大小，画笔要求右侧语义分类树已有选中类别，画出的圆形连续笔触会在鼠标松开时一次性 union 成新的独立 mask，即使与当前选中 mask 连通或重叠也不能自动合并，创建后自动选中新 mask；橡皮擦要求已选中 mask 并在松开时从该 mask 中 difference 扣除；普通 mask 和导入 mask 都不显示黄色 seed point，也不提供 seed point 拖动；未选中特定 mask 时，Canvas 会按右侧语义分类树拖拽得到的内部覆盖优先级从低到高渲染 mask，使高优先级类别显示在上层；Canvas 左上角工具上下文提示会在切换工具或操作状态变化时短暂显示，数秒后自动隐藏，避免长期遮挡底图；工具栏有“调整多边形”和“取消选中”入口，左侧 `ToolsPalette` 使用紧凑垂直布局并在高度不足时自身滚动，基础绘制、画笔/橡皮擦/AI自动推理、布尔/删除、导入/AI 入口之间用浅灰分隔线区分；橡皮擦下方提供彩色 AI 大脑图标“AI自动推理”入口，布尔/删除组包含区域合并、重叠区域去除、`DEL` 和“清空遮罩”，其后通过 `data-testid="tool-group-separator"` 分隔紫色“导入 GT Mask”和 AI 智能分割入口；清空遮罩优先作用于当前帧选中 mask，没有选中时作用于当前帧全部 mask；无传播链结果时直接清当前帧，存在传播链结果时弹窗同一行选择取消、只清当前帧、按帧范围选择或清空所有传播帧，按帧范围选择会进入时间轴范围选择并二次确认；Canvas 右下角不再提供旧的“清空遮罩”或“应用分类”按钮，分类改由右侧语义分类树点击完成；工作区左侧工具栏不展示 AI 页的正向选点、反向选点和边界框选，也不重复放置撤销/重做；点击 mask 后可按住顶点直接拖动并实时更新 polygon，顶点拖拽结束不会触发 Stage 平移或重置 Canvas 视口；也可删除 polygon 顶点、通过边中点或双击边界插入新顶点；多 polygon/分离区域组成的同一 mask 进入编辑时所有子区域都会显示顶点和插点手柄，同帧同传播链的分散 mask 点选时会按 `source_annotation_id`、`source_mask_id`、`propagation_seed_key` 或 `propagation_seed_signature` 联动高亮；对旧传播结果缺少这些稳定 lineage 的情况，会用传播来源、来源帧、分类/标签/颜色构造兼容分组，使同一传播 mask 拆出的不连通片段仍能一起高亮；从参考帧手工 mask 执行区域合并/去除同步到旧传播帧时，如果稳定 lineage 缺失，会在同来源帧且同语义/颜色的传播结果中选取空间最近者作为对应实例，避免漏合并同类不同实例；区域合并支持跨语义链路，当前帧把 A mask 合并进 B mask 时，传播帧中的 A 对应结果会并入 B 对应结果；若某个传播帧没有 B 对应结果但有 A 对应结果，则把该 A 结果转换为 B 语义并标记为 dirty；带中空洞的 mask 会用 `metadata.polygonRingCounts` 记录外圈与内圈的 ring 分组，调整多边形时外圈和内洞都显示可编辑顶点和插点手柄，保存时把内洞拆到 `mask_data.holes`；选中整块 mask 可用 Delete/Backspace 或左侧 `DEL` 删除，已保存 mask 删除前会预检当前后端 annotation id，只对仍存在的 id 调用后端删除，避免陈旧本地 id 产生 DELETE 404；删除传播 seed 或任一传播结果时会扩展删除同一传播链上的自动传播 mask，但保留其他帧独立 AI 推理或人工标注 mask；区域合并/去除会隐藏编辑手柄并显示已选数量，第一个选中的主区域用黄色实线轮廓，后续参与合并/扣除的区域用红色虚线轮廓，使用 `polygon-clipping` 做 union/difference，若存在传播帧对应 mask 会先弹窗选择只处理当前帧、处理所有传播帧或按帧范围选择；按帧范围选择会进入时间轴范围选择并二次确认，只把同一布尔操作同步到所选范围内具备对应关系的传播帧；同步后的传播 mask 保留原 `source`/lineage metadata，只进入 dirty 状态等待保存，不会在时间轴上变成人工/AI 标注帧；内含去除结果用 even-odd 规则渲染 hole；Zustand 维护 `maskHistory/maskFuture` 支持撤销/重做。 +8. 手工标注：`CanvasArea.tsx` 支持多边形、矩形、圆、画笔和橡皮擦生成/编辑 polygon mask；多边形可按 Enter 或点击首节点闭合；多边形/矩形/圆在右侧语义分类树未选中类别时会自动归入黑色 `maskid:0` 的“待分类”；切换到创建多边形、创建矩形或创建圆时会清空旧 mask 选区，创建完成后自动选中新 mask 并显示只读边界点；按 `Esc` 或点击左侧工具栏“取消选中”按钮会清空当前 mask 选区和临时绘制状态；画笔/橡皮擦可在左侧工具栏调整大小，画笔要求右侧语义分类树已有选中类别，画出的圆形连续笔触会在鼠标松开时一次性 union 成新的独立 mask，即使与当前选中 mask 连通或重叠也不能自动合并，创建后自动选中新 mask；画笔闭合形成中空区域时会保留外圈/内洞 ring 分组、使用 even-odd 渲染并显示内外圈顶点；橡皮擦要求已选中 mask 并在松开时从该 mask 中 difference 扣除；普通 mask 和导入 mask 都不显示黄色 seed point，也不提供 seed point 拖动；未选中特定 mask 时，Canvas 会按右侧语义分类树拖拽得到的内部覆盖优先级从低到高渲染 mask，使高优先级类别显示在上层；Canvas 左上角工具上下文提示会在切换工具或操作状态变化时短暂显示，数秒后自动隐藏，避免长期遮挡底图；工具栏有“调整多边形”和“取消选中”入口，左侧 `ToolsPalette` 使用紧凑垂直布局并在高度不足时自身滚动，基础绘制、画笔/橡皮擦/AI自动推理、布尔/删除、导入/AI 入口之间用浅灰分隔线区分；橡皮擦下方提供彩色 AI 大脑图标“AI自动推理”入口，布尔/删除组包含区域合并、重叠区域去除、`DEL` 和“清空遮罩”，其后通过 `data-testid="tool-group-separator"` 分隔紫色“导入 GT Mask”和 AI 智能分割入口；清空遮罩优先作用于当前帧选中 mask，没有选中时作用于当前帧全部 mask；无传播链结果时直接清当前帧，存在传播链结果时弹窗同一行选择取消、只清当前帧、按帧范围选择或清空所有传播帧，按帧范围选择会进入时间轴范围选择并二次确认；Canvas 右下角不再提供旧的“清空遮罩”或“应用分类”按钮，分类改由右侧语义分类树点击完成；工作区左侧工具栏不展示 AI 页的正向选点、反向选点和边界框选，也不重复放置撤销/重做；点击 mask 后可按住顶点直接拖动并实时更新 polygon，顶点拖拽结束不会触发 Stage 平移或重置 Canvas 视口；也可删除 polygon 顶点、通过边中点或双击边界插入新顶点；多 polygon/分离区域组成的同一 mask 进入编辑时所有子区域都会显示顶点和插点手柄，同帧同传播链的分散 mask 点选时会按 `source_annotation_id`、`source_mask_id`、`propagation_seed_key` 或 `propagation_seed_signature` 联动高亮；对旧传播结果缺少这些稳定 lineage 的情况，会用传播来源、来源帧、分类/标签/颜色构造兼容分组，使同一传播 mask 拆出的不连通片段仍能一起高亮；从参考帧手工 mask 执行区域合并/去除同步到旧传播帧时，如果稳定 lineage 缺失，会在同来源帧且同语义/颜色的传播结果中选取空间最近者作为对应实例，避免漏合并同类不同实例；区域合并支持跨语义链路，当前帧把 A mask 合并进 B mask 时，传播帧中的 A 对应结果会并入 B 对应结果；若某个传播帧没有 B 对应结果但有 A 对应结果，则把该 A 结果转换为 B 语义并标记为 dirty；带中空洞的 mask 会用 `metadata.polygonRingCounts` 记录外圈与内圈的 ring 分组，调整多边形时外圈和内洞都显示可编辑顶点和插点手柄，保存时把内洞拆到 `mask_data.holes`；选中整块 mask 可用 Delete/Backspace 或左侧 `DEL` 删除，已保存 mask 删除前会预检当前后端 annotation id，只对仍存在的 id 调用后端删除，避免陈旧本地 id 产生 DELETE 404；删除传播 seed 或任一传播结果时会扩展删除同一传播链上的自动传播 mask，但保留其他帧独立 AI 推理或人工标注 mask；区域合并/去除会隐藏编辑手柄并显示已选数量，第一个选中的主区域用黄色实线轮廓，后续参与合并/扣除的区域用红色虚线轮廓，使用 `polygon-clipping` 做 union/difference，若存在传播帧对应 mask 会先弹窗选择只处理当前帧、处理所有传播帧或按帧范围选择；按帧范围选择会进入时间轴范围选择并二次确认，只把同一布尔操作同步到所选范围内具备对应关系的传播帧；同步后的传播 mask 保留原 `source`/lineage metadata，只进入 dirty 状态等待保存，不会在时间轴上变成人工/AI 标注帧；内含去除结果用 even-odd 规则渲染 hole；Zustand 维护 `maskHistory/maskFuture` 支持撤销/重做。 9. AI 分割：侧栏和工作区工具栏的 AI 智能分割入口使用 Bot + Sparkles 组合图标强化 AI 识别；前端工具包括 SAM 2.1 变体选择、正向点、反向点和框选；AI 画布会按容器和当前帧尺寸默认居中放大底图并保留边距；工作区和 AI 页面都可点击已有提示点删除单点，AI 页面也可删除最近锚点、删除选中候选或清空本页锚点；这些删除入口会限制在当前提示点/本页 AI 候选范围内，避免误删工作区已有 mask。SAM 2.1 框选会建立候选 mask，后续正/反点通过 `interactive` prompt 携带原始框和累计点细化同一个候选 mask；AI 页面框选会先固化 `promptBox`，执行分割时只框选发送 `box` prompt，框选后继续加正/反点发送 `interactive` prompt；重复执行高精度分割会替换上一次 AI 页候选，只保留最新一个候选。包含反向点时工作区会传 `options.auto_filter_background=true` 和 `min_score=0.05`，如果后端过滤为空则移除旧候选 mask。后端 `ai.py` 期望按 `image_id`、`prompt_type`、`prompt_data`、`model` 和可选 `options` 调用 SAM registry。当前 registry 暴露 `sam2.1_hiera_tiny`、`sam2.1_hiera_small`、`sam2.1_hiera_base_plus`、`sam2.1_hiera_large`，并兼容 `sam2` 作为 tiny 别名；`model=sam3` 会被拒绝，`semantic` 文本提示也被禁用。SAM 2.1 支持点/框/interactive/自动分割和 video predictor 传播；多候选默认只采用最高分区域，避免重叠候选同时显示；AI 页面只渲染本页最新生成的候选 mask，不会把工作区已有 mask 带入 AI 画布；AI 页面生成的 mask 会写入全局 `masks` 并自动选中，右侧分类树可直接改标签，推送到工作区会切到“调整多边形”并保留选择和当前帧视角。`options.crop_to_prompt` 可对点/框/interactive prompt 做局部裁剪推理并回映射，`options.auto_filter_background` 可按分数和负向点过滤结果。 10. 视频片段传播：工作区以当前打开帧作为参考帧，使用该帧全部 mask 作为 seed，并用传播起始帧和传播结束帧指定追踪范围；如果当前参考帧没有 mask，点击开始传播会提示“当前参考帧无遮罩”，不会提交任务或保存其它帧标注；用户点击左侧工具栏橡皮擦下方的彩色 AI 大脑图标“AI自动推理”进入时间轴范围选择模式，在播放进度条或视频处理进度条上点击/拖拽选择范围，也可直接修改数字框，再点击顶栏“开始传播”。传播权重选择器只在进入自动传播选择/执行状态后显示，可为本次传播二次选择 SAM 2.1 tiny/small/base+/large 权重，不提供 SAM2/SAM3 家族切换，也不影响 AI 单帧分割权重；进入自动传播范围选择时，顶栏会显示当前传播权重以及相对参考帧的向前/向后帧数；前端提交传播前只保存当前参考帧中的 draft/dirty mask，使 seed 优先带稳定的后端 `source_annotation_id`，再按传播权重 id、seed mask、seed 来源 id 和前/后方向组装 `steps` 并调用 `POST /api/ai/propagate/task` 创建 `propagate_masks` 后台任务；同一参考帧多个同类别 mask 会各自作为独立 seed 传播，后端按 `source_annotation_id/source_mask_id/propagation_seed_key` 区分实例，避免同类不同实例互相删除；中空 seed 会携带和 `polygons` 对齐的 `holes`，后端注入 SAM 2 video predictor 前会先填充外圈再扣除内洞，避免以实心 mask 传播；后端入队时会规范化/校验权重 id 并把规范化后的 id 写入任务 payload/result；Celery worker 顺序执行各 step，避免多个视频 tracker 并发抢占 GPU；每个 step 会根据 seed 来源 id、方向和包含 `holes` 的 seed 签名做幂等判断，同权重且未改变的 seed 直接跳过，已改变或换用其他权重的 seed 会先删除同源旧自动传播标注再重传；旧版本缺少稳定来源 id 的传播标注只在没有可靠 lineage 时走 label/color/class 兼容匹配，写入新结果前仍会通过空间重叠清理同一物体旧结果；中间帧人工新增/修改同一物体后重新传播时，后端会在写入目标帧新结果前按语义和空间重叠清理旧传播结果，且写入前清理不受旧结果传播方向限制；后端按项目帧序列下载片段帧，当前使用所选 SAM 2.1 权重变体的 `SAM2VideoPredictor.add_new_mask()` + `propagate_in_video()`，并把后续帧结果保存为 `Annotation`，同一个 seed 在同一目标帧得到的多个不连通外轮廓会保存到同一个 annotation 的 `mask_data.polygons` 中，而不是拆成多个 mask；传播结果轮廓用 CCOMP 层级提取并把内洞写入 `mask_data.holes`；若历史或外部 seed 仍带 `geometry_smoothing`，forward/backward 两个方向的传播结果保存前仍会应用同一参数；当前工作区平滑按钮应用后会直接改写实际 polygon，后续传播以新几何参与签名和追踪。工作区轮询 `GET /api/tasks/{task_id}` 展示进度并刷新标注，Dashboard 也能显示/取消/重试传播任务。 11. GT 导入：工作区左侧工具栏“导入 GT Mask”调用 `/api/ai/import-gt-mask`；选择文件后前端会显示导入结果预览，并让用户决定未知 maskid 处理方式，可舍弃未知类别，也可导入为“未定义类别”等待重新命名。后端用 `cv2.IMREAD_UNCHANGED` 读取 mask 并校验 dtype；GT 图片必须是 8-bit 灰度 maskid 图，或 8-bit RGB 三通道完全相同的 `[X,X,X]` maskid 图，0 为背景、X 为 1-255 的 maskid，16-bit/uint16 GT_label、普通彩色类别图和全背景 0 图都会返回明确错误；全背景图错误信息固定为“GT Mask 图片中没有非背景 maskid 区域。”；灰度/RGB 等通道图按模板 `maskId` 匹配类别，超出现有类别时按 `unknown_color_policy` 处理；如果 mask 图片尺寸和当前帧不同，会按当前帧长宽最近邻拉伸后再提取区域；每个连通域用高精度 contour 生成 polygon 标注，保留更多边界点并设置点数上限避免拖慢前端；导入结果与普通 mask 共用拓扑锚点统计、边缘平滑、顶点编辑、分类和保存链路；后端仍可写入 distance transform seed point 供数据兼容，但前端不显示或拖动 seed point。 diff --git a/README.md b/README.md index 82ed4cb..ac99e81 100644 --- a/README.md +++ b/README.md @@ -14,7 +14,7 @@ - **多媒体资产管理** — 支持视频（MP4/AVI/MOV）和 DICOM 医学影像上传，项目库会在导入时显示上传进度条、已上传字节、DICOM 文件数量和上传后的解析任务进度；视频导入与生成帧分离，生成帧时选择目标 FPS，项目卡片可重命名、复制或删除项目及其关联帧、标注和任务记录；复制时可选择“新项目重置”只保留媒体/帧序列，或“全内容复制”连同标注和 mask 元数据一起复制 - **AI 智能分割引擎** — 当前产品入口启用 SAM 2.1 四个变体（tiny/small/base+/large）选择；侧栏和工作区跳转入口使用 Bot + Sparkles 组合图标强化 AI 识别；支持点分割（point）、框分割（box）、交互式正/反点细化、提示点单点删除、AI 候选单独删除、自动分割（auto）和 Celery 后台 video predictor 传播，前端默认只采用最高分候选避免重叠备选同时显示 -- **交互式画布标注** — 基于 Konva 的高性能 Canvas，工作区和 AI 画布会默认居中放大底图并保留边距；工作区支持缩放/平移/手工多边形/矩形/圆/画笔/橡皮擦、polygon 顶点直接拖动/删除、边中点插点、双击边界插点、区域合并/去除、撤销/重做；mask 不再显示黄色 seed point，也不提供 seed point 拖动；左侧工具栏提供等同 `Esc` 的“取消选中”实体按钮，用于清空选区和临时绘制状态；画笔和橡皮擦支持尺寸调节，画笔可按当前语义分类生成新的独立连续区域，即使与选中 mask 连通或重叠也不自动合并，橡皮擦可从选中 mask 扣除区域；删除传播 seed 或传播结果时会同步删除同一传播链上的自动传播 mask，但保留其他帧独立 AI 推理/人工标注 mask；未选中特定 mask 时按右侧语义分类树的内部优先级叠放显示，AI 智能分割页单独提供正/反点和框选，实时渲染 Mask 遮罩 +- **交互式画布标注** — 基于 Konva 的高性能 Canvas，工作区和 AI 画布会默认居中放大底图并保留边距；工作区支持缩放/平移/手工多边形/矩形/圆/画笔/橡皮擦、polygon 顶点直接拖动/删除、边中点插点、双击边界插点、区域合并/去除、撤销/重做；mask 不再显示黄色 seed point，也不提供 seed point 拖动；创建多边形/矩形/圆后会自动选中新 mask 并立即显示边界点；左侧工具栏提供等同 `Esc` 的“取消选中”实体按钮，用于清空选区和临时绘制状态；画笔和橡皮擦支持尺寸调节，画笔可按当前语义分类生成新的独立连续区域，即使与选中 mask 连通或重叠也不自动合并，画笔闭合成中空区域时会保留内洞 ring 并显示内外圈顶点，橡皮擦可从选中 mask 扣除区域；删除传播 seed 或传播结果时会同步删除同一传播链上的自动传播 mask，但保留其他帧独立 AI 推理/人工标注 mask；未选中特定 mask 时按右侧语义分类树的内部优先级叠放显示，AI 智能分割页单独提供正/反点和框选，实时渲染 Mask 遮罩 - **GT Mask 导入** — 工作区可导入 8-bit 二值/灰度 maskid 图或 8-bit RGB 三通道完全相同的 `[X,X,X]` maskid 图；导入前会显示本地预览，不符合 8-bit 灰度/maskid 图要求时反馈错误，尺寸不同会按当前帧长宽最近邻拉伸；后端按 maskid 匹配当前模板类别并生成高精度 polygon 标注，导入后与普通 mask 一样不显示黄色 seed point，并共用拓扑锚点统计、边缘平滑、顶点编辑、分类和保存链路；超出现有类别的 maskid 可由用户选择舍弃或导入为“未定义类别”等待重新命名 - **本体字典管理** — 可配置的分类体系、颜色映射、稳定且跨图一致的 maskid；所有模板默认带 `maskid: 0` 的黑色“待分类”保留类，该类固定在语义分类树最后、不可删除也不可拖到上层；模板库“生效中模板架构清单”可用鼠标复制现有模板为当前用户私有副本，详情页“语义分类树（拖拽调层级）”支持新建分类、拖拽调层级和垃圾桶删除 label，模板编辑弹窗和右侧分类树也可拖拽调整内部图层覆盖顺序，maskid 不参与排序 - **项目工作区** — 项目创建、帧浏览、多图层标注、自动传播帧提示、进度追踪 diff --git a/doc/03-frontend-element-audit.md b/doc/03-frontend-element-audit.md index c333ad1..be81fe4 100644 --- a/doc/03-frontend-element-audit.md +++ b/doc/03-frontend-element-audit.md @@ -95,7 +95,7 @@ | 正向/反向选点 | 真实可用 | UI 能加点，并按当前帧 `frame.id` 调用 `/api/ai/predict`；结果需点击归档保存才持久化 | | 框选 | 真实可用 | UI 能画框，并把框坐标归一化后调用后端推理；结果需点击归档保存才持久化 | | AI 推理中提示 | 真实可用 | 请求期间会显示 | -| 手工多边形/矩形/圆/画笔/橡皮擦 | 真实可用 | 多边形点击取点后可按 Enter 完成，也可在三点后点击首节点闭合；矩形/圆拖拽生成 polygon；切换到多边形/矩形/圆会清空旧 mask 选区，创建完成后自动选中新 mask；多边形/矩形/圆未选语义分类时自动归入黑色 `maskid:0` 的“待分类”；画笔按当前语义分类生成连续圆形笔触并在松开时 union 成新的独立 mask，即使与选中 mask 连通或重叠也不自动合并；按 `Esc` 或点击左侧“取消选中”按钮可清空选区和临时绘制状态；橡皮擦从选中 mask 中扣除笔触区域；均写入 `Mask.segmentation`，可归档保存 | +| 手工多边形/矩形/圆/画笔/橡皮擦 | 真实可用 | 多边形点击取点后可按 Enter 完成，也可在三点后点击首节点闭合；矩形/圆拖拽生成 polygon；切换到多边形/矩形/圆会清空旧 mask 选区，创建完成后自动选中新 mask，并在创建工具下显示边界顶点作为只读选中提示；多边形/矩形/圆未选语义分类时自动归入黑色 `maskid:0` 的“待分类”；画笔按当前语义分类生成连续圆形笔触并在松开时 union 成新的独立 mask，即使与选中 mask 连通或重叠也不自动合并；画笔闭合形成中空区域时保留内洞 ring，使用 even-odd 渲染并显示内外圈顶点；按 `Esc` 或点击左侧“取消选中”按钮可清空选区和临时绘制状态；橡皮擦从选中 mask 中扣除笔触区域；均写入 `Mask.segmentation`，可归档保存 | | 画布上下文提示 | 真实可用 | 切换到多边形、矩形、圆、画笔、橡皮擦、区域合并/去除、调整多边形等隐性操作工具时，画布左上角显示当前工具的完成/取消/选择顺序提示；提示会在数秒后自动隐藏，避免长期遮挡待编辑图像，工具或操作状态变化时会重新出现 | | Mask 渲染 | 真实可用 | 前端会把推理、手工绘制、GT 导入和已保存标注转成 Konva `pathData` 渲染；普通 mask 和导入 mask 都不显示黄色 seed point；未选中特定 mask 时，当前帧 mask 会按右侧“语义分类树”拖拽得到的内部覆盖优先级从低到高渲染，使高优先级类别显示在上层；有选中 mask 时保留编辑态置顶行为，方便操作 | | Mask 透明度 | 真实可用 | 右侧语义分类树上方的“遮罩透明度”滑杆写入全局 `maskPreviewOpacity`，工作区 Canvas 和 AI 智能分割页都会使用该值调整 mask 预览透明度，选中 mask 会在该基础上略微加亮 | @@ -110,7 +110,7 @@ | 元素 | 状态 | 说明 | |------|------|------| -| 工具分组分隔线 | 真实可用 | 拖拽/选择到创建圆为绘制/基础编辑组，画笔/橡皮擦/自动传播为局部与追踪组，区域合并/重叠区域去除/DEL/清空遮罩为布尔与删除组，导入 GT Mask 和 AI 智能分割为外部动作组；组间使用浅灰横线分隔，`data-testid="tool-group-separator"` 位于清空遮罩下方的外部动作组分隔线 | +| 工具分组分隔线 | 真实可用 | 拖拽/选择到创建圆为绘制/基础编辑组，画笔/橡皮擦/AI自动推理为局部与追踪组，区域合并/重叠区域去除/DEL/清空遮罩为布尔与删除组，导入 GT Mask 和 AI 智能分割为外部动作组；组间使用浅灰横线分隔，`data-testid="tool-group-separator"` 位于清空遮罩下方的外部动作组分隔线 | | 拖拽/选择 | 真实可用 | 控制 Canvas 是否可拖拽 | | 取消选中 | 真实可用 | 位于拖拽/选择按钮下方，实体按钮等同 `Esc`：清空当前 mask 选区、临时绘制点/笔触和顶点选择，不删除 mask、不清空 active class | | 调整多边形 | 真实可用 | 选中 polygon mask 后显示顶点和边中点；支持按住顶点直接拖动、点击边中点插点、双击边界按位置插点 | diff --git a/doc/07-current-requirements-freeze.md b/doc/07-current-requirements-freeze.md index e3df302..cc52d82 100644 --- a/doc/07-current-requirements-freeze.md +++ b/doc/07-current-requirements-freeze.md @@ -75,8 +75,8 @@ - 侧栏“AI智能分割”和工作区工具栏 AI 跳转入口必须使用带明确 AI 语义的图标，而不是普通魔法棒等泛化工具图标。 - 工作区 AI 智能分割入口切换到 AI 页面。 - 多边形、矩形、圆、画笔、橡皮擦工具会在 Canvas 上生成或编辑可保存的 polygon mask；左侧工具栏不再提供创建点和创建线段入口。 -- 多边形通过点击取点并按 Enter 完成，也支持三点后点击首节点闭合；矩形、圆通过拖拽生成；点击创建多边形、创建矩形或创建圆工具时必须清空当前 mask 选区；新建完成后必须自动选中新创建的 mask；画笔和橡皮擦支持调整大小。 -- 画笔工具只在语义分类树有选中类别时可用，按住拖动时以圆形笔触采样，鼠标松开后一次性 union 成新的独立 mask；即使笔触与当前选中 mask 连通或重叠，也不能自动合并到旧 mask；笔触只在当前图像范围内采样，最终几何也必须裁剪到当前帧边界内。 +- 多边形通过点击取点并按 Enter 完成，也支持三点后点击首节点闭合；矩形、圆通过拖拽生成；点击创建多边形、创建矩形或创建圆工具时必须清空当前 mask 选区；新建完成后必须自动选中新创建的 mask，并在仍处于创建工具时显示该 mask 边界顶点作为只读选中提示；画笔和橡皮擦支持调整大小。 +- 画笔工具只在语义分类树有选中类别时可用，按住拖动时以圆形笔触采样，鼠标松开后一次性 union 成新的独立 mask；即使笔触与当前选中 mask 连通或重叠，也不能自动合并到旧 mask；笔触只在当前图像范围内采样，最终几何也必须裁剪到当前帧边界内；如果画笔闭合形成中空区域，必须保留外圈与内洞 ring 分组，并按中空 mask 规则渲染、编辑和保存。 - 橡皮擦工具只在当前帧已选中 mask 时可用，按住拖动时以圆形笔触采样，鼠标松开后从选中 mask 中 difference 扣除；扣空时删除该 mask，已保存 mask 仍需同步后端删除；进入画笔或橡皮擦模式后，当前选中 mask 的顶点提示仍保持可见，但这些顶点在笔触模式下只读不可拖动。 - 创建多边形、创建矩形、区域合并/去除、调整多边形等 Canvas 左上角上下文提示只作为短提示，切换工具或操作状态变化时显示，数秒后自动隐藏，避免长期遮挡待编辑图像；再次切换工具或操作状态变化会重新显示。 - 绘制工具点击已有 mask 时应继续执行当前绘制动作，不应被 mask 选择逻辑吞掉；按 `Esc` 或点击左侧工具栏“取消选中”实体按钮，必须清空当前 mask 选区和正在绘制的临时点/笔触，使用户可以重新选择语义分类并用画笔创建一个新 mask。 diff --git a/doc/08-current-design-freeze.md b/doc/08-current-design-freeze.md index 9c65f54..edb8bb7 100644 --- a/doc/08-current-design-freeze.md +++ b/doc/08-current-design-freeze.md @@ -183,8 +183,8 @@ 3. 多边形工具逐次记录节点，三点后点击首节点或按 Enter 时生成闭合 polygon。 4. Canvas 左上角根据当前工具和操作阶段显示上下文短提示；多边形提示会随已放置点数切换，明确 Enter 完成、Esc 取消和点击首节点闭合。`Esc` 和左侧工具栏“取消选中”按钮只取消当前 mask 选区、临时多边形点、矩形/圆拖拽状态、画笔/橡皮擦临时笔触和顶点选择，不删除已有 mask，也不清空右侧语义分类树的当前类别。提示会在工具或操作状态变化时出现，并在数秒后自动隐藏，避免长期遮挡底图。 5. mask path 只在 `move`、`edit_polygon`、`area_merge` 和 `area_remove` 工具下拦截点击；绘制、画笔、橡皮擦和 AI prompt 工具点击已有 mask 时继续冒泡给 Stage。 -6. 画笔/橡皮擦尺寸保存在 Zustand 中；拖动期间只保留采样后的圆形笔触预览，鼠标松开后再用 `polygon-clipping` 计算一次几何结果，避免拖动中反复重算复杂 polygon。画笔只把本次采样笔触 union 成一个新的独立 mask，不与当前选中 mask 自动合并；橡皮擦则对当前选中 mask 执行 difference 扣除。 -7. 多边形、矩形、圆和画笔创建的新 mask 写入 `pathData`、像素 `segmentation`、`bbox`、`area` 和当前模板分类元数据，并自动写入 `selectedMaskIds` 成为当前选中 mask。若右侧没有选中具体分类，新建 mask 默认使用 `maskid: 0` 的“待分类”。 +6. 画笔/橡皮擦尺寸保存在 Zustand 中；拖动期间只保留采样后的圆形笔触预览，鼠标松开后再用 `polygon-clipping` 计算一次几何结果，避免拖动中反复重算复杂 polygon。画笔只把本次采样笔触 union 成一个新的独立 mask，不与当前选中 mask 自动合并；如果画笔笔触闭合形成中空区域，`segmentation` 保留外圈和内洞 ring，`metadata.hasHoles/polygonRingCounts` 记录 ring 分组，并使用 even-odd 渲染；橡皮擦则对当前选中 mask 执行 difference 扣除。 +7. 多边形、矩形、圆和画笔创建的新 mask 写入 `pathData`、像素 `segmentation`、`bbox`、`area` 和当前模板分类元数据，并自动写入 `selectedMaskIds` 成为当前选中 mask。若右侧没有选中具体分类，新建 mask 默认使用 `maskid: 0` 的“待分类”。创建工具仍处于激活状态时，刚创建并选中的 mask 会显示只读边界顶点；切换到 `move` 或“调整多边形”后这些顶点可拖动编辑。 8. `addMask()`、`setMasks()`、`updateMask()`、`clearMasks()` 会维护 `maskHistory/maskFuture`。 9. 工作区撤销/重做只保留顶栏按钮和快捷键入口，AI 页保留自己的撤销/重做按钮；工作区由 `VideoWorkspace` 在 window capture 阶段统一处理 `Ctrl/Cmd+Z`、`Ctrl/Cmd+Shift+Z` 和 `Ctrl/Cmd+Y`，快捷键判断由 `src/lib/keyboardShortcuts.ts` 同时兼容 `event.key` 与物理键码 `event.code=KeyZ/KeyY`；输入框、下拉框和可编辑文本聚焦时跳过快捷键，避免影响帧范围输入。 diff --git a/doc/09-test-plan.md b/doc/09-test-plan.md index a104b4a..ad6737d 100644 --- a/doc/09-test-plan.md +++ b/doc/09-test-plan.md @@ -18,7 +18,7 @@ | R2 项目管理 | `src/lib/api.test.ts`, `src/components/ProjectLibrary.test.tsx`, `backend/tests/test_projects.py` | 前端字段映射、PATCH 更新、项目卡片复制/删除、修改项目名称时隐藏生成帧、DICOM 项目不显示生成帧、复制项目 reset/full 契约、DELETE 契约、后端 CRUD、删除级联、帧列表、项目按当前 JWT 用户隔离 | | R3 媒体上传与拆帧 | `src/components/ProjectLibrary.test.tsx`, `src/components/TransientNotice.test.tsx`, `backend/tests/test_media.py`, `backend/tests/test_tasks.py` | 视频导入不自动拆帧、视频/DICOM 上传进度可视化、DICOM 导入显示有效文件数量并在上传后持续显示解析任务进度、显式生成帧 FPS 选择、项目卡片显示目标 parse_fps 而非原视频 FPS、扩展名校验、自动建项目、关联项目、创建异步任务、非阻塞自动消失操作提示、标准帧序列参数、帧时间戳/源帧号、任务序列元数据、worker 注册帧、取消任务、重试任务、取消后 worker 停止 | | R4 工作区与帧浏览 | `src/components/VideoWorkspace.test.tsx`, `src/components/FrameTimeline.test.tsx` | 加载帧、无帧项目不自动解析并提示生成帧、工作区短状态自动消失、工作区/AI 画布底图默认居中且保留边距、工作区 mask 透明度、回显已保存标注时保留本地未保存 draft mask、选中 mask 后跨帧自动跟随同一传播链结果、左侧工具栏清空遮罩优先作用于当前帧选中 mask/无选中时作用于当前帧全部 mask、无传播链时直接执行、有传播链时可选取消/只清当前帧/按帧范围选择/清空所有传播帧且按范围清空需最终确认、按范围清空或清空所有传播帧遇到人工/AI 标注帧时二次询问并支持保留人工帧、顶栏不显示重复的清空片段遮罩、传播链布尔操作按帧范围选择并二次确认、清空/删除前预检后端 annotation id 并跳过本地陈旧 id、删除单个传播 mask 后空帧不保留传播历史颜色、传播权重下拉深色可读配色、自动传播范围选择时显示传播权重和向前/向后帧数、缩略图/range/视频处理进度条、视频处理进度条点击跳帧、人工/AI 标注帧红色竖线和标识点击跳帧、自动传播帧通过 source/lineage metadata 识别为蓝色区段和标识点击跳帧、最近自动传播历史片段同一蓝色系按新旧递进纯色显示，旧记录第 5 次后统一阈值色、当前帧白色贯穿线、传播/布尔/清空范围边界贯穿线、缩略图红/蓝边框、人工/AI 标注帧叠加传播状态时红框优先保留并显示蓝色内描边、当前人工/AI 标注帧青色外框加红色内描边、普通状态不显示传播范围黄色选区、播放进度条和视频处理进度条选择传播/布尔/清空范围、左右方向键切帧、播放、按项目 FPS 显示当前/总时长 | -| R5 工具栏 | `src/components/ToolsPalette.test.tsx`, `src/components/CanvasArea.test.tsx`, `src/components/VideoWorkspace.test.tsx`, `src/lib/keyboardShortcuts.test.ts`, `src/store/useStore.test.ts` | 工具切换、切换到多边形/矩形/圆会清空旧 mask 选区、手工新建 mask 后自动选中新 mask、Esc 和左侧“取消选中”按钮清空当前 mask 选区和临时绘制状态、工具栏紧凑垂直布局和高度不足时滚动、工具栏低对比滚动条、工具栏外扩滚动条槽位不挤占按钮列、调整多边形工具、AI 跳转、清空遮罩唯一左侧工具栏入口、清空遮罩上方 DEL 删除按钮、橡皮擦下方彩色 AI自动推理入口、Canvas 右下角不再重复显示清空遮罩或应用分类按钮、GT Mask 导入位于清空遮罩分隔线之后且使用紫色底色、工具栏分隔线位于创建圆后、AI自动推理后和清空遮罩后、GT Mask 未知类别导入策略选择、工作区工具栏不展示 AI 正/反点和框选、左侧工具栏不重复撤销/重做、左侧工具栏不展示创建点/创建线段、矩形/圆/多边形手工 mask 绘制且未选分类时默认待分类、普通/导入 polygon mask 不显示黄色 seed point、画笔/橡皮擦尺寸控制、画笔新建当前类别独立 mask、画笔与选中 mask 连通或重叠时也不自动合并、画笔/橡皮擦模式下保留当前选中 mask 顶点提示且只读、画笔从图外落笔不创建 mask、靠边画笔生成几何裁剪到当前帧边界内、橡皮擦从选中 mask 扣除、未选中 mask 时画布按语义分类树内部优先级渲染、多边形 Enter/首节点闭合、上下文提示提示 Enter/Esc/首节点闭合且数秒后自动隐藏、polygon 顶点直接拖动/删除、顶点拖拽结束不改变 Canvas 视口、边中点插点、双击边界按位置插点、多 polygon/分离区域全部显示编辑顶点、中空 mask 内洞 ring 顶点和插点可编辑、整块 mask 删除、DEL 和 Delete/Backspace 删除共用传播链范围确认、同帧传播链分散 mask 点选联动高亮、传播链自动传播 mask 随 seed/传播结果删除、独立 AI 推理 mask 不被误删、区域合并/去除存在传播帧时弹窗选择当前帧/所有传播帧/按帧范围选择、范围确认前重新开始当前帧布尔操作会取消旧顶栏范围请求、区域合并/去除按帧范围同步到对应传播帧且保留传播 metadata、布尔选择主区域/扣除区域视觉区分和选择顺序提示、内含去除 hole 渲染和 ring 分组保存、合并模式隐藏编辑手柄、工作区顶栏撤销/重做按钮、顶栏撤销/重做图标强调色、撤销/重做快捷键 Ctrl/Cmd+Z、Ctrl/Cmd+Shift+Z、Ctrl/Cmd+Y、物理键码 fallback 和输入框快捷键跳过、撤销/重做历史栈 | +| R5 工具栏 | `src/components/ToolsPalette.test.tsx`, `src/components/CanvasArea.test.tsx`, `src/components/VideoWorkspace.test.tsx`, `src/lib/keyboardShortcuts.test.ts`, `src/store/useStore.test.ts` | 工具切换、切换到多边形/矩形/圆会清空旧 mask 选区、手工新建 mask 后自动选中新 mask 并显示创建后边界点、Esc 和左侧“取消选中”按钮清空当前 mask 选区和临时绘制状态、工具栏紧凑垂直布局和高度不足时滚动、工具栏低对比滚动条、工具栏外扩滚动条槽位不挤占按钮列、调整多边形工具、AI 跳转、清空遮罩唯一左侧工具栏入口、清空遮罩上方 DEL 删除按钮、橡皮擦下方彩色 AI自动推理入口、Canvas 右下角不再重复显示清空遮罩或应用分类按钮、GT Mask 导入位于清空遮罩分隔线之后且使用紫色底色、工具栏分隔线位于创建圆后、AI自动推理后和清空遮罩后、GT Mask 未知类别导入策略选择、工作区工具栏不展示 AI 正/反点和框选、左侧工具栏不重复撤销/重做、左侧工具栏不展示创建点/创建线段、矩形/圆/多边形手工 mask 绘制且未选分类时默认待分类、普通/导入 polygon mask 不显示黄色 seed point、画笔/橡皮擦尺寸控制、画笔新建当前类别独立 mask、画笔与选中 mask 连通或重叠时也不自动合并、画笔/橡皮擦模式下保留当前选中 mask 顶点提示且只读、画笔从图外落笔不创建 mask、靠边画笔生成几何裁剪到当前帧边界内、橡皮擦从选中 mask 扣除、未选中 mask 时画布按语义分类树内部优先级渲染、多边形 Enter/首节点闭合、上下文提示提示 Enter/Esc/首节点闭合且数秒后自动隐藏、polygon 顶点直接拖动/删除、顶点拖拽结束不改变 Canvas 视口、边中点插点、双击边界按位置插点、多 polygon/分离区域全部显示编辑顶点、中空 mask 与中空画笔 mask 内洞 ring 顶点和插点可编辑、整块 mask 删除、DEL 和 Delete/Backspace 删除共用传播链范围确认、同帧传播链分散 mask 点选联动高亮、传播链自动传播 mask 随 seed/传播结果删除、独立 AI 推理 mask 不被误删、区域合并/去除存在传播帧时弹窗选择当前帧/所有传播帧/按帧范围选择、范围确认前重新开始当前帧布尔操作会取消旧顶栏范围请求、区域合并/去除按帧范围同步到对应传播帧且保留传播 metadata、布尔选择主区域/扣除区域视觉区分和选择顺序提示、内含去除 hole 渲染和 ring 分组保存、合并模式隐藏编辑手柄、工作区顶栏撤销/重做按钮、顶栏撤销/重做图标强调色、撤销/重做快捷键 Ctrl/Cmd+Z、Ctrl/Cmd+Shift+Z、Ctrl/Cmd+Y、物理键码 fallback 和输入框快捷键跳过、撤销/重做历史栈 | | R6 AI 推理 | `src/lib/api.test.ts`, `src/components/CanvasArea.test.tsx`, `src/components/AISegmentation.test.tsx`, `src/components/VideoWorkspace.test.tsx`, `src/components/ModelStatusBadge.test.tsx`, `backend/tests/test_ai.py`, `backend/tests/test_sam2_engine.py` | SAM 2.1 变体选择、点/框/interactive 契约、semantic 禁用、SAM 3 入口隐藏和后端拒绝、SAM 2.1 最高分候选去重、SAM 2.1 框选后正负点细化同一候选 mask、AI 页框选发送 box prompt、AI 页框选后加点发送 interactive prompt、AI 页提示工具上下文提示、AI 页重复执行替换旧候选、SAM 2.1 反向点启用背景过滤且空结果移除旧候选、AI 页不渲染工作区已有 mask、AI 页可在候选 mask 上继续添加正/反点、AI 页可单点删除提示点并删除最近锚点、AI 页可删除选中候选且不删除工作区 mask、AI 页清空只移除本页候选、AI 页参数开关可读性文案且 options 字段不变、AI 页/右侧共享遮罩透明度只改预览 opacity、AI 页生成 mask 自动选中并可通过分类树换标签、AI 页无语义候选禁止推送到工作区并用 error toast 提示、离开 AI 页时清理未分类候选、AI 页推送到工作区编辑保留选择和当前帧、SAM 2.1 视频以当前参考帧全部 mask 和起止帧范围自动传播、同类多实例按来源 id 分开传播、当前参考帧无遮罩提示、传播前只保存参考帧 draft/dirty seed mask、传播前独立选择 SAM 2.1 tiny/small/base+/large 权重、自动传播创建 Celery 任务、传播入队权重 id 规范化/拒绝不支持 id、传播 seed 来源 id/签名和历史平滑 metadata 兼容、中空传播 seed 扣除 holes 后注入 SAM 2 且传播结果保留 holes、历史平滑 seed 保存前对 forward/backward polygon 实际应用边缘平滑并减少密集轮廓点、边缘平滑强度缓入递进曲线、未编辑传播结果作为 seed 时继承原始签名并跳过重复传播、已编辑传播结果保留 lineage 但重算签名并清理旧结果、中间帧人工新增替代 seed 时清理下游同物体旧传播结果、中间帧 backward 传播清理旧 forward 结果、换权重传播先清理旧结果、旧临时 seed id 传播结果兼容清理、传播中轮询任务进度、传播任务取消/重试、传播来源 metadata 回显、空提示/空结果反馈、GPU/SAM2.1 状态、AI 参数 options、局部裁剪推理、背景过滤、状态徽标、坐标归一化、正负点 labels、polygons 转 path、后端 fake registry | | R7 标注保存 | `src/components/VideoWorkspace.test.tsx`, `src/components/CanvasArea.test.tsx`, `src/lib/api.test.ts`, `backend/tests/test_ai.py` | 保存状态按钮“保存 X 个改动/已全部保存”、保存标注、保存后用后端 saved annotation 替换已提交 draft、加载回显、更新 dirty 标注、dirty 本地旧 annotationId 预检缺失时直接重新 POST 创建、预检后 PATCH 404 时重新 POST 创建并回显替换、中空 mask 保存为 `polygons` + `holes` 并可回显为 ring 分组、清空删除已保存标注、GT mask 多类别导入、高精度 GT contour、导入 mask 可直接拓扑统计和边缘平滑、后端 seed point 归一化兼容但前端不显示或拖动、缺失 seed point 的普通 polygon 保存时自动写入代表点、项目不存在、帧不存在 | | R8 模板库 | `src/components/TemplateRegistry.test.tsx`, `src/components/TransientNotice.test.tsx`, `src/lib/api.test.ts`, `backend/tests/test_templates.py` | 前端模板加载/新建/编辑/删除、删除模板站内确认、鼠标复制模板为私有副本、所有模板归一化包含黑色 `maskid:0`“待分类”保留类、保留类固定最后且不可删除/拖拽上移、详情页“语义分类树（拖拽调层级）”标题、详情页“编辑模板”按钮和编辑图标、详情页垃圾桶删除 label 且不显示来源标签、编辑弹窗分类编辑不显示旧 category 来源元信息、编辑后详情页刷新、详情页和编辑弹窗拖拽语义层级顺序、拖拽保存 `zIndex` 且不改变 maskid、JSON 分类导入预览、`[[colors],[names]]` 数组格式、`{colors,names}` 对象格式、带前缀/宽松 keys/中文标点粘贴格式、JSON 错误内联提示、保存错误非阻塞提示、mapping_rules 解包/打包、后端模板 CRUD | @@ -37,7 +37,7 @@ | R3 | 文件类型校验、自动/指定项目上传、视频导入与生成帧分离、视频/DICOM 上传进度可视化、DICOM 导入显示有效文件数量并在上传后持续显示解析任务进度、显式 FPS 生成帧、项目卡片 FPS 徽标显示 `parse_fps`、视频/DICOM 拆帧任务、DICOM 上传/下载/读取自然排序、非阻塞自动消失操作提示、`parse_fps/max_frames/target_width`、标准帧序列 metadata、任务查询、取消、重试、worker 取消停止 | `ProjectLibrary.test.tsx`, `TransientNotice.test.tsx`, `api.test.ts`, `test_media.py`, `test_tasks.py` | 已覆盖 | | R4 | 工作区加载帧、无帧项目不自动解析、工作区短状态自动消失、后端标注回显保留本地未保存 draft mask、Canvas/AI 底图居中适配且保留边距、工作区 mask 透明度、选中 mask 后跨帧自动跟随同一传播链结果、左侧工具栏当前帧清空优先作用于选中 mask、无传播链时直接执行、有传播链时可选当前帧/传播所有帧/取消、清空人工/AI 标注帧前二次确认、取消确认不删除、仅自动传播帧不确认、删除单个传播 mask 后空帧不保留传播历史颜色、传播权重下拉深色可读配色、缩略图/range/视频处理进度条、视频处理进度条点击跳帧、人工/AI 标注帧红色竖线和标识点击跳帧、自动传播帧蓝色区段和标识点击跳帧、最近自动传播历史片段同一蓝色系按新旧递进显示，旧记录第 5 次后统一阈值色、当前帧白色贯穿线、传播范围洋红/黄绿色边界贯穿线、缩略图红/蓝边框、人工/AI 标注帧叠加传播状态时红框优先保留并显示蓝色内描边、当前人工/AI 标注帧青色外框加红色内描边、普通状态不显示传播范围黄色选区、播放进度条/视频处理进度条拖拽选择传播范围、Canvas/AI 画布拖拽平移回写 position state、左右方向键切帧、播放、按 FPS 显示时间 | `VideoWorkspace.test.tsx`, `FrameTimeline.test.tsx`, `CanvasArea.test.tsx`, `AISegmentation.test.tsx` | 已覆盖 | | R5 | 工具切换、工具栏紧凑滚动布局、低对比滚动条、外扩滚动条槽位、调整多边形入口、清空遮罩唯一左侧入口、Canvas 右下角旧清空/应用分类按钮移除、GT Mask 导入入口位置和紫色底色、工作区工具栏隐藏 AI 正/反点和框选、左侧工具栏不重复撤销/重做、AI 跳转、矩形/圆/线/点/多边形绘制、已有 mask 上继续绘制、多边形和布尔工具上下文提示、Canvas 上下文提示数秒后自动隐藏 | `ToolsPalette.test.tsx`, `CanvasArea.test.tsx` | 已覆盖 | -| R5 | 顶点直接拖动编辑、顶点拖拽结束不改变 Canvas 视口、边中点插点、双击边界按位置插点、中空 mask 内洞 ring 顶点和插点可编辑、顶点删除、整块删除、删除传播链自动传播 mask 且保留独立 AI 推理 mask、工作区顶栏撤销/重做按钮、顶栏撤销/重做图标强调色、撤销/重做快捷键 Ctrl/Cmd+Z、Ctrl/Cmd+Shift+Z、Ctrl/Cmd+Y 和 KeyZ/KeyY fallback、区域合并、区域去除、布尔选择主区域黄色实线/扣除区域红色虚线、布尔选择顺序提示、hole even-odd 渲染 | `CanvasArea.test.tsx`, `VideoWorkspace.test.tsx`, `keyboardShortcuts.test.ts`, `useStore.test.ts` | 已覆盖 | +| R5 | 顶点直接拖动编辑、顶点拖拽结束不改变 Canvas 视口、边中点插点、双击边界按位置插点、中空 mask 与中空画笔 mask 内洞 ring 顶点和插点可编辑、顶点删除、整块删除、删除传播链自动传播 mask 且保留独立 AI 推理 mask、工作区顶栏撤销/重做按钮、顶栏撤销/重做图标强调色、撤销/重做快捷键 Ctrl/Cmd+Z、Ctrl/Cmd+Shift+Z、Ctrl/Cmd+Y 和 KeyZ/KeyY fallback、区域合并、区域去除、布尔选择主区域黄色实线/扣除区域红色虚线、布尔选择顺序提示、hole even-odd 渲染 | `CanvasArea.test.tsx`, `VideoWorkspace.test.tsx`, `keyboardShortcuts.test.ts`, `useStore.test.ts` | 已覆盖 | | R6 | SAM 2.1 变体选择、点/框/interactive、semantic 禁用、SAM 3 入口隐藏和后端拒绝、SAM 2.1 最高分候选去重、AI 页框选/框选后加点、AI 页提示工具上下文提示、AI 页重复执行替换旧候选、AI 页不渲染工作区已有 mask、AI 页可在候选 mask 上继续添加正/反点、AI 页可删除提示点、AI 页可删除选中候选、AI 页清空只移除本页候选、AI 页/右侧共享遮罩透明度只改预览 opacity、AI 页生成 mask 自动选中并可换标签、AI 页无语义候选禁止推送到工作区并用 error toast 提示、离开 AI 页时清理未分类候选、AI 页推送到工作区编辑保留选择和当前帧、SAM 2.1 视频按参考帧全部 mask 和范围自动传播、同类多实例按来源 id 分开传播、当前参考帧无遮罩提示、传播前只保存参考帧 draft/dirty seed mask、传播前独立选择 SAM 2.1 tiny/small/base+/large 权重、自动传播 Celery 任务入队、传播入队权重 id 规范化/拒绝不支持 id、传播 seed 来源 id/签名和历史平滑 metadata 兼容、中空 seed holes 栅格化扣除和传播结果 holes 提取、历史平滑 seed 保存前对 forward/backward polygon 实际应用边缘平滑并减少密集轮廓点、边缘平滑强度缓入递进曲线、未编辑传播结果作为 seed 时继承原始签名并跳过重复传播、已编辑传播结果保留 lineage 但重算签名并清理旧结果、中间帧人工新增替代 seed 时清理下游同物体旧传播结果、中间帧 backward 传播清理旧 forward 结果、换权重传播先清理旧结果、旧临时 seed id 传播结果兼容清理、前端任务轮询进度、传播任务 runner 保存标注和结果权重 id、传播任务重试、传播空结果提示、GPU/模型状态、参数 options、polygons 转 mask | `api.test.ts`, `CanvasArea.test.tsx`, `AISegmentation.test.tsx`, `VideoWorkspace.test.tsx`, `ModelStatusBadge.test.tsx`, `test_ai.py`, `test_tasks.py`, `test_sam2_engine.py` | 已覆盖 | | R7 | 保存状态按钮“保存 X 个改动/已全部保存”、保存、保存后替换已提交 draft、查询、更新、dirty 本地旧 annotationId 的预检缺失直接重新创建和 PATCH 404 重新创建、删除标注、工作区回显、清空已保存标注、GT mask 导入和 seed point 数据兼容、导入 mask 不显示黄色 seed point、高精度 GT contour、导入 mask 拓扑统计和边缘平滑、8-bit 低数值 GT_label 图导入、16-bit/uint16 GT_label 图拒绝、全背景 0 GT_label 图拒绝并保留“没有非背景 maskid 区域”提示、RGB 等通道 maskid 图导入、导入预览、未知 maskid 导入策略、非法彩色 GT mask 拒绝、尺寸不一致自动最近邻拉伸 | `VideoWorkspace.test.tsx`, `CanvasArea.test.tsx`, `api.test.ts`, `test_ai.py` | 已覆盖 | | R8 | 模板加载、新建、编辑、删除、删除模板站内确认、鼠标复制模板为私有副本并保留 maskid/颜色/层级/规则、所有模板归一化包含黑色 `maskid:0`“待分类”保留类、保留类固定最后且不可删除/拖拽上移、详情页标题/编辑模板按钮/垃圾桶删 label、编辑弹窗分类编辑不显示旧 category 来源元信息、默认模板“腹腔镜胆囊切除术”和“头颈部CT分割”幂等 seed、头颈部 CT 默认分类名纯中文且不带括号英文翻译、恢复出厂设置保留并权威恢复系统模板、默认模板缺失后重建、默认语义分类树被修改/删减后覆盖恢复、编辑后详情页刷新、详情页和编辑弹窗拖拽语义层级顺序、拖拽保存 `zIndex` 且不改变 maskid、JSON 分类导入预览、数组/对象/常见粘贴格式导入、JSON 错误内联提示、保存错误非阻塞提示、mapping_rules 映射、后端 CRUD | `TemplateRegistry.test.tsx`, `TransientNotice.test.tsx`, `api.test.ts`, `test_templates.py`, `test_admin.py` | 已覆盖 | @@ -76,6 +76,7 @@ - R5/R13：补充 `CanvasArea.test.tsx` 中 `Esc` 交互测试，验证 `Esc` 只取消当前 mask 选中和临时多边形点，不删除已有 mask、不清空 `activeClass`；新增 `doc/11-frontend-interaction-state-machines.md` 记录工作区工具、语义分类树、范围选择、AI 页、模板确认和导入导出状态机。 - R5/R13：完成文档一致性回查，修正 `doc/02-current-implementation-map.md` 和 `doc/08-current-design-freeze.md` 中手工绘制、画笔独立新建、Esc、工具切换保留选区和无选区点击语义分类树的旧描述，使实现映射、设计冻结、状态机文档和测试计划保持一致。 - R5/R13：补充左侧工具栏“取消选中”实体按钮测试和 Canvas `clearSelectionSignal` 测试，验证实体按钮与 `Esc` 共享取消选区/临时绘制状态语义。 +- R5：补充创建后边界点和中空画笔回归测试，验证多边形/矩形/圆创建完成后即使仍在创建工具下也显示已选 mask 边界点，并验证画笔闭合成中空区域时保留 `hasHoles/polygonRingCounts`、使用 even-odd 渲染且内外圈顶点可显示。 ## 运行命令 diff --git a/doc/11-frontend-interaction-state-machines.md b/doc/11-frontend-interaction-state-machines.md index 79d5788..5163f9e 100644 --- a/doc/11-frontend-interaction-state-machines.md +++ b/doc/11-frontend-interaction-state-machines.md @@ -19,9 +19,9 @@ |------|----------|----------|----------|------| | `idle/no-selection` | 初始、切换到创建工具、`Esc`、左侧“取消选中”、切帧无对应传播结果 | 右侧语义树只设置后续新建类别；清空遮罩作用于当前帧全部 mask | 点击 mask、AI 推送、创建新 mask | `CanvasArea.test.tsx`、`OntologyInspector.test.tsx` | | `mask-selected` | `move/edit_polygon` 下点击 mask、新建 mask 完成、AI 候选选中 | 右侧语义树给已选 mask 换类；Delete/Backspace/DEL 删除；橡皮擦可扣除；顶点可编辑 | `Esc`、左侧“取消选中”、切换到创建工具、删除 mask、切帧无对应传播结果 | `CanvasArea.test.tsx` | -| `polygon-drawing` | `create_polygon` 下点击画布 | 继续加点；三点后 Enter 或点击首点闭合 | Enter/首点创建新独立 mask；`Esc` 放弃临时点并清选区 | `CanvasArea.test.tsx` | -| `shape-dragging` | `create_rectangle/create_circle` 下按下鼠标 | 拖拽预览形状 | 鼠标释放创建新独立 mask；切工具取消临时状态 | `CanvasArea.test.tsx` | -| `brush-stroking` | `brush` 且已有 `activeClass` 时按下鼠标 | 采样图像范围内圆形笔触 | 鼠标释放创建新的独立 mask；图外落笔不创建；`Esc` 取消笔触和选区 | `CanvasArea.test.tsx` | +| `polygon-drawing` | `create_polygon` 下点击画布 | 继续加点；三点后 Enter 或点击首点闭合 | Enter/首点创建新独立 mask 并显示边界点；`Esc` 放弃临时点并清选区 | `CanvasArea.test.tsx` | +| `shape-dragging` | `create_rectangle/create_circle` 下按下鼠标 | 拖拽预览形状 | 鼠标释放创建新独立 mask 并显示边界点；切工具取消临时状态 | `CanvasArea.test.tsx` | +| `brush-stroking` | `brush` 且已有 `activeClass` 时按下鼠标 | 采样图像范围内圆形笔触 | 鼠标释放创建新的独立 mask；闭合成中空区域时保留内洞 ring；图外落笔不创建；`Esc` 取消笔触和选区 | `CanvasArea.test.tsx` | | `eraser-stroking` | `eraser` 且已有选中 mask 时按下鼠标 | 采样图像范围内圆形笔触 | 鼠标释放从选中 mask 扣除；扣空则删除该 mask；`Esc` 取消笔触和选区 | `CanvasArea.test.tsx` | | `boolean-selecting` | `area_merge/area_remove` | 选择多个 mask；主区域黄色实线，参与区域红色虚线 | 当前帧执行、所有传播帧、按帧范围、取消、切换工具 | `CanvasArea.test.tsx`、`VideoWorkspace.test.tsx` | diff --git a/src/components/CanvasArea.test.tsx b/src/components/CanvasArea.test.tsx index 64ec4e1..8c322c1 100644 --- a/src/components/CanvasArea.test.tsx +++ b/src/components/CanvasArea.test.tsx @@ -1624,6 +1624,8 @@ describe('CanvasArea', () => { bbox: [120, 80, 140, 120], })); expect(useStore.getState().selectedMaskIds).toEqual([useStore.getState().masks[0].id]); + expect(screen.getAllByTestId('konva-circle') + .filter((element) => element.getAttribute('data-fill') === '#ffffff')).toHaveLength(4); useStore.getState().undoMasks(); expect(useStore.getState().masks).toEqual([]); @@ -1655,6 +1657,8 @@ describe('CanvasArea', () => { })); expect(useStore.getState().masks[0].segmentation?.[0]).toHaveLength(64); expect(useStore.getState().selectedMaskIds).toEqual([useStore.getState().masks[0].id]); + expect(screen.getAllByTestId('konva-circle') + .filter((element) => element.getAttribute('data-fill') === '#ffffff')).toHaveLength(32); }); it('clears the selected mask when switching to manual creation tools', async () => { @@ -1714,6 +1718,34 @@ describe('CanvasArea', () => { expect(useStore.getState().masks[0].area).toBeGreaterThan(1000); }); + it('preserves hollow brush masks as editable inner rings', () => { + useStore.setState({ + activeTemplateId: '2', + activeClass: { id: 'c1', name: '胆囊', color: '#ff0000', zIndex: 20, maskId: 1 }, + activeClassId: 'c1', + }); + + render(); + const stage = screen.getByTestId('konva-stage'); + fireEvent.mouseDown(stage, { clientX: 100, clientY: 100 }); + fireEvent.mouseMove(stage, { clientX: 240, clientY: 100 }); + fireEvent.mouseMove(stage, { clientX: 240, clientY: 240 }); + fireEvent.mouseMove(stage, { clientX: 100, clientY: 240 }); + fireEvent.mouseMove(stage, { clientX: 100, clientY: 100 }); + fireEvent.mouseUp(stage, { clientX: 100, clientY: 100 }); + + const brushMask = useStore.getState().masks[0]; + expect(brushMask.metadata).toEqual(expect.objectContaining({ + hasHoles: true, + shape: '画笔', + })); + expect(brushMask.metadata?.polygonRingCounts).toEqual([2]); + expect(brushMask.segmentation).toHaveLength(2); + expect(screen.getByTestId('konva-path')).toHaveAttribute('data-fill-rule', 'evenodd'); + expect(screen.getAllByTestId('konva-circle') + .filter((element) => element.getAttribute('data-fill') === '#ffffff').length).toBeGreaterThan(8); + }); + it('keeps selected mask vertex markers visible while using brush and eraser', () => { useStore.setState({ activeTemplateId: '2', @@ -1915,6 +1947,8 @@ describe('CanvasArea', () => { })); expect(screen.queryAllByTestId('konva-circle') .filter((element) => element.getAttribute('data-fill') === '#facc15')).toHaveLength(0); + expect(screen.queryAllByTestId('konva-circle') + .filter((element) => element.getAttribute('data-fill') === '#ffffff')).toHaveLength(3); }); it('clears selected masks with Escape so brush can create a new unmerged mask', async () => { diff --git a/src/components/CanvasArea.tsx b/src/components/CanvasArea.tsx index 71ac716..d1aedc6 100644 --- a/src/components/CanvasArea.tsx +++ b/src/components/CanvasArea.tsx @@ -602,8 +602,9 @@ export function CanvasArea({ const isBooleanTool = BOOLEAN_TOOLS.has(effectiveTool); const isPaintTool = PAINT_TOOLS.has(effectiveTool); const isPolygonEditTool = effectiveTool === 'move' || effectiveTool === EDIT_POLYGON_TOOL; + const isManualCreateTool = effectiveTool === POLYGON_TOOL || DRAG_MANUAL_TOOLS.has(effectiveTool); const canKeepMaskSelection = isPolygonEditTool || isBooleanTool || isPaintTool; - const showSelectedMaskVertices = Boolean(selectedMask && (isPolygonEditTool || isPaintTool)); + const showSelectedMaskVertices = Boolean(selectedMask && (isPolygonEditTool || isPaintTool || isManualCreateTool)); const activePaintSize = effectiveTool === ERASER_TOOL ? eraserSize : brushSize; const activePaintRadius = Math.max(2, activePaintSize / 2); const setPaintStrokePoints = useCallback((nextPoints: CanvasPoint[]) => {