admin/Pre_Seg_Server
1
1
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 1 Wiki Activity

feat: 完善 mask 编辑、传播平滑与开发重启闭环

Browse Source 
功能增加：

- 新增后端 /api/ai/smooth-mask 接口，对当前 mask polygon 执行 Chaikin 边缘平滑，并返回 polygon、bbox、area 与拓扑锚点。

- 在右侧实例属性面板加入边缘平滑强度和应用边缘平滑操作，应用后将 mask 标记为 draft/dirty，并通过正常保存链路落库。

- 保存标注与传播 seed 时保留 geometry_smoothing 元数据，自动传播 forward/backward 结果保存前应用同一平滑参数。

- 自动传播 seed signature 纳入平滑参数，修改平滑强度后会触发旧同源传播结果清理并重新传播。

- 支持跨帧跟随同一传播链 mask，AI 推送回工作区时保留当前帧视角。

Bugfix：

- 修复中间帧向前传播时旧 forward/backward 同物体结果未被清理导致双重 mask 的问题。

- 修复 propagation worker 写入目标帧前只按旧方向清理导致 backward 重传残留的问题。

- 修复多边形顶点拖拽和编辑后画布视口异常移动的问题，并补充拖拽状态回写。

- 修复实例属性标题跟随全局 active class 而不是当前 mask label 的问题，并移除后端模型置信度展示。

开发与部署：

- 新增 restart_dev_services.sh，使用 setsid 独立后台重启 FastAPI、Celery 和前端，写入 pid/log 文件并做 3000/8000 健康检查。

- 明确后端或 Celery 相关改动完成后需要运行重启脚本，保证运行态加载最新代码。

测试与文档：

- 补充后端 smooth-mask、传播平滑 metadata、seed signature、传播去重方向覆盖等测试。

- 补充前端 OntologyInspector、VideoWorkspace、CanvasArea 和 api 契约测试，覆盖边缘平滑、传播参数、跨帧选区跟随和画布编辑行为。

- 更新 README、AGENTS、安装文档、前端元素审计、需求冻结、设计冻结和测试计划，记录当前真实行为与重启要求。
This commit is contained in:
admin
2026-05-02 17:04:02 +08:00
parent f365539ff2
commit 4c1d3dba73
20 changed files with 1358 additions and 71 deletions
Download Patch File Download Diff File Expand all files Collapse all files

15
AGENTS.md
View File

@@ -60,6 +60,7 @@ Seg_Server/
│ └── logo.png # Sidebar 使用的 /logo.png │ └── logo.png # Sidebar 使用的 /logo.png
├── doc/ # 当前实现审计、接口契约和后续实施文档 ├── doc/ # 当前实现审计、接口契约和后续实施文档
├── start_services.sh # 本地一键启动 PostgreSQL/Redis/MinIO/FastAPI/Celery/前端 ├── start_services.sh # 本地一键启动 PostgreSQL/Redis/MinIO/FastAPI/Celery/前端
├── restart_dev_services.sh # 本地开发重启脚本；重启 FastAPI/Celery/前端并检查 3000/8000
├── backend/ # FastAPI 后端 ├── backend/ # FastAPI 后端
│ ├── main.py # 应用入口、lifespan、CORS、路由注册、WebSocket │ ├── main.py # 应用入口、lifespan、CORS、路由注册、WebSocket
│ ├── config.py # Pydantic Settings；读取 backend/.env │ ├── config.py # Pydantic Settings；读取 backend/.env
@@ -162,6 +163,14 @@ uvicorn main:app --host 0.0.0.0 --port 8000 --reload
该脚本会依次检查/启动 PostgreSQL、Redis、MinIO、FastAPI 后端、Celery worker 和前端。 该脚本会依次检查/启动 PostgreSQL、Redis、MinIO、FastAPI 后端、Celery worker 和前端。
### 开发重启
```bash
./restart_dev_services.sh
```
本地代码改完后不要靠手工试进程。前端 `src/` 通常由 Vite 热更新；凡是修改 FastAPI 后端、Celery worker、拆帧/SAM runner 或任务逻辑，完成验证后都要运行 `./restart_dev_services.sh`，确保运行态加载最新代码。`restart_dev_services.sh` 会停止旧 FastAPI/Celery/前端进程，用独立后台进程重启三者，并检查 `http://localhost:8000/health` 和 `http://localhost:3000`。
--- ---
## 运行时架构 ## 运行时架构
@@ -197,6 +206,7 @@ uvicorn main:app --host 0.0.0.0 --port 8000 --reload
- `POST /api/tasks/{task_id}/cancel` - `POST /api/tasks/{task_id}/cancel`
- `POST /api/tasks/{task_id}/retry` - `POST /api/tasks/{task_id}/retry`
- `POST /api/ai/predict` - `POST /api/ai/predict`
- `POST /api/ai/smooth-mask`
- `POST /api/ai/propagate` - `POST /api/ai/propagate`
- `POST /api/ai/propagate/task` - `POST /api/ai/propagate/task`
- `GET /api/ai/models/status` - `GET /api/ai/models/status`
@@ -228,8 +238,8 @@ uvicorn main:app --host 0.0.0.0 --port 8000 --reload
5. worker 执行：Celery worker 用 FFmpeg 优先拆视频帧，失败后用 OpenCV fallback，DICOM 使用 pydicom；视频帧按 `frame_%06d.jpg` 连续命名并记录 `timestamp_ms`、`source_frame_number` 和任务 `frame_sequence` 元数据。 5. worker 执行：Celery worker 用 FFmpeg 优先拆视频帧，失败后用 OpenCV fallback，DICOM 使用 pydicom；视频帧按 `frame_%06d.jpg` 连续命名并记录 `timestamp_ms`、`source_frame_number` 和任务 `frame_sequence` 元数据。
6. 帧展示：`VideoWorkspace.tsx` 调用 `/api/projects/{id}/frames`，`CanvasArea.tsx` 和 `FrameTimeline.tsx` 显示当前帧与时间轴缩略图；`CanvasArea` 会按容器和帧尺寸默认居中放大底图并保留边距；`FrameTimeline` 会根据已保存标注回显到 `Mask.metadata` 的传播来源，把自动传播生成的帧在视频处理进度条显示为蓝色区段，人工/AI 标注帧显示红色竖线；每次自动传播成功处理帧后，`VideoWorkspace` 会把本次传播范围作为当前会话历史片段传给 `FrameTimeline`，在视频处理进度条上叠加不同色系的深到浅渐变条；视频处理进度条和红/蓝标识可点击跳转到对应帧；底部缩略图中人工/AI 标注帧用红色边框、自动传播/推理帧用蓝色边框，同一帧同时具备两种状态时红色标注边框优先保留，蓝色传播状态以内描边表达；当前帧仍以青色外框高亮优先；若当前帧同时是人工/AI 标注帧，则在青色外框内增加红色内描边，固定为外层当前帧、内层人工/AI 标注；只有进入自动传播范围选择模式时，播放进度条和视频处理进度条才显示黄色范围框，并可点击/拖拽选择传播起止帧；前端 `Frame` 会保留后端返回的帧序列时间戳和源帧号。 6. 帧展示：`VideoWorkspace.tsx` 调用 `/api/projects/{id}/frames`，`CanvasArea.tsx` 和 `FrameTimeline.tsx` 显示当前帧与时间轴缩略图；`CanvasArea` 会按容器和帧尺寸默认居中放大底图并保留边距；`FrameTimeline` 会根据已保存标注回显到 `Mask.metadata` 的传播来源，把自动传播生成的帧在视频处理进度条显示为蓝色区段，人工/AI 标注帧显示红色竖线；每次自动传播成功处理帧后，`VideoWorkspace` 会把本次传播范围作为当前会话历史片段传给 `FrameTimeline`，在视频处理进度条上叠加不同色系的深到浅渐变条；视频处理进度条和红/蓝标识可点击跳转到对应帧；底部缩略图中人工/AI 标注帧用红色边框、自动传播/推理帧用蓝色边框，同一帧同时具备两种状态时红色标注边框优先保留，蓝色传播状态以内描边表达；当前帧仍以青色外框高亮优先；若当前帧同时是人工/AI 标注帧，则在青色外框内增加红色内描边，固定为外层当前帧、内层人工/AI 标注；只有进入自动传播范围选择模式时，播放进度条和视频处理进度条才显示黄色范围框，并可点击/拖拽选择传播起止帧；前端 `Frame` 会保留后端返回的帧序列时间戳和源帧号。
7. 手工标注：`CanvasArea.tsx` 支持多边形、矩形、圆、点区域和线段生成 polygon mask；多边形可按 Enter 或点击首节点闭合；绘制工具可在已有 mask 上继续落点；Canvas 左上角工具上下文提示会在切换工具或操作状态变化时短暂显示，数秒后自动隐藏，避免长期遮挡底图；工具栏有“调整多边形”入口，左侧 `ToolsPalette` 使用紧凑垂直布局并在高度不足时自身滚动；点击 mask 后可按住顶点直接拖动并实时更新 polygon，顶点/seed point 拖拽结束不会触发 Stage 平移或重置 Canvas 视口；也可删除 polygon 顶点、通过边中点或双击边界插入新顶点，并能选择编辑多 polygon mask 的单个子区域；选中整块 mask 可用 Delete/Backspace 删除，已保存 mask 会同步后端删除；区域合并/去除会隐藏编辑手柄并显示已选数量，第一个选中的主区域用黄色实线轮廓，后续参与合并/扣除的区域用红色虚线轮廓，使用 `polygon-clipping` 做 union/difference，内含去除结果用 even-odd 规则渲染 hole；Zustand 维护 `maskHistory/maskFuture` 支持撤销/重做。 7. 手工标注：`CanvasArea.tsx` 支持多边形、矩形、圆、点区域和线段生成 polygon mask；多边形可按 Enter 或点击首节点闭合；绘制工具可在已有 mask 上继续落点；Canvas 左上角工具上下文提示会在切换工具或操作状态变化时短暂显示，数秒后自动隐藏，避免长期遮挡底图；工具栏有“调整多边形”入口，左侧 `ToolsPalette` 使用紧凑垂直布局并在高度不足时自身滚动；点击 mask 后可按住顶点直接拖动并实时更新 polygon，顶点/seed point 拖拽结束不会触发 Stage 平移或重置 Canvas 视口；也可删除 polygon 顶点、通过边中点或双击边界插入新顶点，并能选择编辑多 polygon mask 的单个子区域；选中整块 mask 可用 Delete/Backspace 删除，已保存 mask 会同步后端删除；区域合并/去除会隐藏编辑手柄并显示已选数量，第一个选中的主区域用黄色实线轮廓，后续参与合并/扣除的区域用红色虚线轮廓，使用 `polygon-clipping` 做 union/difference，内含去除结果用 even-odd 规则渲染 hole；Zustand 维护 `maskHistory/maskFuture` 支持撤销/重做。
8. 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` 可按分数和负向点过滤结果。 8. 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` 可按分数和负向点过滤结果。
9. 视频片段传播：工作区以当前打开帧作为参考帧，使用该帧全部 mask 作为 seed，并用传播起始帧和传播结束帧指定追踪范围；用户可直接修改数字框，也可点击“自动传播”进入时间轴范围选择模式，在播放进度条或视频处理进度条上点击/拖拽选择范围，再点击“开始传播”。工作区顶栏有独立“传播权重”选择器，可为本次传播二次选择 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` 后台任务；后端入队时会规范化/校验权重 id 并把规范化后的 id 写入任务 payload/result；Celery worker 顺序执行各 step，避免多个视频 tracker 并发抢占 GPU；每个 step 会根据 seed 来源 id、方向和 seed 签名做幂等判断，同权重且未改变的 seed 直接跳过，已改变或换用其他权重的 seed 会先删除同源旧自动传播标注再重传；旧版本用前端临时 `source_mask_id` 生成的传播标注会按同一参考帧、方向和语义信息兼容清理；后端按项目帧序列下载片段帧，当前使用所选 SAM 2.1 权重变体的 `SAM2VideoPredictor.add_new_mask()` + `propagate_in_video()`，并把后续帧结果保存为 `Annotation`。工作区轮询 `GET /api/tasks/{task_id}` 展示进度并刷新标注，Dashboard 也能显示/取消/重试传播任务。 9. 视频片段传播：工作区以当前打开帧作为参考帧，使用该帧全部 mask 作为 seed，并用传播起始帧和传播结束帧指定追踪范围；用户可直接修改数字框，也可点击“自动传播”进入时间轴范围选择模式，在播放进度条或视频处理进度条上点击/拖拽选择范围，再点击“开始传播”。工作区顶栏有独立“传播权重”选择器，可为本次传播二次选择 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` 后台任务；后端入队时会规范化/校验权重 id 并把规范化后的 id 写入任务 payload/result；Celery worker 顺序执行各 step，避免多个视频 tracker 并发抢占 GPU；每个 step 会根据 seed 来源 id、方向、平滑参数和 seed 签名做幂等判断，同权重且未改变的 seed 直接跳过，已改变、改动平滑参数或换用其他权重的 seed 会先删除同源旧自动传播标注再重传；旧版本用前端临时 `source_mask_id` 生成的传播标注会按同一参考帧、方向和语义信息兼容清理；中间帧人工新增/修改同一物体后重新传播时，后端会在写入目标帧新结果前按语义和空间重叠清理旧传播结果，且写入前清理不受旧结果传播方向限制；后端按项目帧序列下载片段帧，当前使用所选 SAM 2.1 权重变体的 `SAM2VideoPredictor.add_new_mask()` + `propagate_in_video()`，并把后续帧结果保存为 `Annotation`；如果 seed 带 `geometry_smoothing`，forward/backward 两个方向的传播结果保存前都会应用同一参数。工作区轮询 `GET /api/tasks/{task_id}` 展示进度并刷新标注，Dashboard 也能显示/取消/重试传播任务。
10. GT 导入：工作区“导入 GT Mask”调用 `/api/ai/import-gt-mask`；后端按非零像素值和连通域生成 polygon 标注，并用 distance transform 生成 seed point；前端回显 seed point，拖动后可归档更新。 10. GT 导入：工作区“导入 GT Mask”调用 `/api/ai/import-gt-mask`；后端按非零像素值和连通域生成 polygon 标注，并用 distance transform 生成 seed point；前端回显 seed point，拖动后可归档更新。
11. 模板管理：`TemplateRegistry.tsx` 管理分类、颜色和 z-index；`OntologyInspector.tsx` 在工作区显示当前模板分类树。 11. 模板管理：`TemplateRegistry.tsx` 管理分类、颜色和 z-index；`OntologyInspector.tsx` 在工作区显示当前模板分类树。
12. 导出：后端支持 COCO JSON 和 PNG mask ZIP 导出；PNG ZIP 包含单标注 mask、按 zIndex 融合的语义 mask 和 `semantic_classes.json`。 12. 导出：后端支持 COCO JSON 和 PNG mask ZIP 导出；PNG ZIP 包含单标注 mask、按 zIndex 融合的语义 mask 和 `semantic_classes.json`。
@@ -246,6 +256,7 @@ uvicorn main:app --host 0.0.0.0 --port 8000 --reload
- 前端 `importGtMask()` 已对齐后端 `/api/ai/import-gt-mask`；工作区“导入 GT Mask”会导入后端生成的多类别标注和 seed point 并回显。 - 前端 `importGtMask()` 已对齐后端 `/api/ai/import-gt-mask`；工作区“导入 GT Mask”会导入后端生成的多类别标注和 seed point 并回显。
- 前端 `exportCoco()` 已对齐后端 `/api/export/{project_id}/coco`；前端 `exportMasks()` 已对齐后端 `/api/export/{project_id}/masks`；工作区导出按钮会先保存当前待归档 mask。 - 前端 `exportCoco()` 已对齐后端 `/api/export/{project_id}/coco`；前端 `exportMasks()` 已对齐后端 `/api/export/{project_id}/masks`；工作区导出按钮会先保存当前待归档 mask。
- 工作区“结构化归档保存”按钮已接入 `POST /api/ai/annotate` 和 `PATCH /api/ai/annotations/{id}`；加载工作区时会通过 `GET /api/ai/annotations` 回显已保存标注。 - 工作区“结构化归档保存”按钮已接入 `POST /api/ai/annotate` 和 `PATCH /api/ai/annotations/{id}`；加载工作区时会通过 `GET /api/ai/annotations` 回显已保存标注。
- 右侧实例属性面板“边缘平滑强度/应用边缘平滑”已接入 `POST /api/ai/smooth-mask`；后端用 Chaikin smoothing 返回新 polygon、bbox、area 和拓扑锚点，前端将当前 mask 标记为 dirty/draft，保存后 `geometry_smoothing` 会随标注和传播 seed 保留。
- 工作区“自动传播”按钮已接入 `POST /api/ai/propagate/task`；若用户尚未显式设置范围，第一次点击会进入时间轴范围选择模式，第二次点击“开始传播”才提交后台任务；当前启用所选 SAM 2.1 变体的视频 predictor 后台任务，运行中轮询任务进度，完成后刷新后端已保存标注；工作区顶栏模型状态用紧凑 GPU/CPU 徽标，具体 SAM 2.1 传播权重由旁边下拉选择；同步 `POST /api/ai/propagate` 仍作为单 seed 兼容接口保留。 - 工作区“自动传播”按钮已接入 `POST /api/ai/propagate/task`；若用户尚未显式设置范围，第一次点击会进入时间轴范围选择模式，第二次点击“开始传播”才提交后台任务；当前启用所选 SAM 2.1 变体的视频 predictor 后台任务，运行中轮询任务进度，完成后刷新后端已保存标注；工作区顶栏模型状态用紧凑 GPU/CPU 徽标，具体 SAM 2.1 传播权重由旁边下拉选择；同步 `POST /api/ai/propagate` 仍作为单 seed 兼容接口保留。
- 工作区顶栏短状态会自动消失；保存、导出、导入 GT、传播进行中和无帧项目提示会保留到状态变化。 - 工作区顶栏短状态会自动消失；保存、导出、导入 GT、传播进行中和无帧项目提示会保留到状态变化。
- 工作区“清空遮罩”会调用 `DELETE /api/ai/annotations/{id}` 删除当前帧已保存标注，并清空当前帧本地 mask。 - 工作区“清空遮罩”会调用 `DELETE /api/ai/annotations/{id}` 删除当前帧已保存标注，并清空当前帧本地 mask。

33
README.md
View File

@@ -318,6 +318,7 @@ nohup uvicorn main:app --host 0.0.0.0 --port 8000 > /tmp/fastapi.log 2>&1 &
- 测试 Redis 连接 - 测试 Redis 连接
- 懒加载所选 SAM 2.1 模型；`GET /api/ai/models/status` 会返回 tiny/small/base+/large 和 GPU 的真实可用状态，`selected_model=sam3` 会返回不支持 - 懒加载所选 SAM 2.1 模型；`GET /api/ai/models/status` 会返回 tiny/small/base+/large 和 GPU 的真实可用状态，`selected_model=sam3` 会返回不支持
- `/api/ai/predict` 支持 AI 参数 `crop_to_prompt`、`auto_filter_background` 和 `min_score`，用于点/框 prompt 的局部裁剪推理、回映射和背景过滤 - `/api/ai/predict` 支持 AI 参数 `crop_to_prompt`、`auto_filter_background` 和 `min_score`，用于点/框 prompt 的局部裁剪推理、回映射和背景过滤
- `/api/ai/smooth-mask` 支持对当前 mask polygon 做后端边缘平滑，返回新的 polygon、bbox、面积和拓扑锚点；前端应用后仍走正常标注保存链路
- `/api/ai/propagate/task` 支持从当前帧 seed 区域向视频片段创建后台传播任务：当前使用所选 SAM 2.1 变体的 `SAM2VideoPredictor.add_new_mask()` + `propagate_in_video()`；同步 `/api/ai/propagate` 仍作为单 seed 兼容接口保留 - `/api/ai/propagate/task` 支持从当前帧 seed 区域向视频片段创建后台传播任务：当前使用所选 SAM 2.1 变体的 `SAM2VideoPredictor.add_new_mask()` + `propagate_in_video()`；同步 `/api/ai/propagate` 仍作为单 seed 兼容接口保留
### 步骤 6.1: 启动 Celery Worker ### 步骤 6.1: 启动 Celery Worker
@@ -368,6 +369,34 @@ cd ~/Desktop/Seg_Server
脚本将依次检查并启动：PostgreSQL → Redis → MinIO → FastAPI 后端 → Celery Worker → 前端。 脚本将依次检查并启动：PostgreSQL → Redis → MinIO → FastAPI 后端 → Celery Worker → 前端。
### 开发重启
如果只是确认本机开发服务使用最新代码，优先用：
```bash
cd ~/Desktop/Seg_Server
./restart_dev_services.sh
```
热更新规则：
| 改动 | 需要重启什么 | 说明 |
|------|--------------|------|
| 前端组件/样式 | 一般不需要 | Vite 会热更新 |
| 前端依赖、`.env`、`vite.config.ts` | 重启前端 | 依赖和环境变量只在进程启动时读取 |
| FastAPI 路由/普通后端代码 | 需要重启后端 | 本项目开发重启脚本用独立后台进程运行后端，后端改动后应显式重启，确保运行态和代码一致 |
| `backend/.env`、模型路径、依赖 | 重启后端 | 配置和依赖在进程启动时生效 |
| Celery 任务、拆帧、自动传播、SAM runner | 必须重启 Celery worker | worker 不会自动加载代码改动 |
`restart_dev_services.sh` 会检查 PostgreSQL/Redis/MinIO，停止旧 FastAPI/Celery/前端进程，用 `setsid` 作为独立后台进程重新启动三者，并检查 `http://localhost:8000/health` 和 `http://localhost:3000`。脚本退出后服务仍会继续运行；pid 文件默认写到 `/tmp/seg_server_*.pid`，日志默认写到：
```text
/tmp/seg_server_fastapi.log
/tmp/seg_server_celery.log
/tmp/seg_server_frontend.log
/tmp/seg_server_minio.log
```
--- ---
## 访问地址与默认凭证 ## 访问地址与默认凭证
@@ -469,8 +498,8 @@ pip install -e . --no-build-isolation
- 前端 `predictMask()` 已发送后端需要的 `image_id`、`prompt_type`、`prompt_data`，并把后端 `polygons` 转成 Konva `pathData`。 - 前端 `predictMask()` 已发送后端需要的 `image_id`、`prompt_type`、`prompt_data`，并把后端 `polygons` 转成 Konva `pathData`。
- 工作区点选/框选会使用当前帧的数据库 `frame.id` 调用 `/api/ai/predict`。 - 工作区点选/框选会使用当前帧的数据库 `frame.id` 调用 `/api/ai/predict`。
- 工作区 SAM 2.1 交互式细化包含反向点时会启用后端背景过滤；若反向点排除了当前候选区域并返回空结果，前端会移除旧候选 mask。 - 工作区 SAM 2.1 交互式细化包含反向点时会启用后端背景过滤；若反向点排除了当前候选区域并返回空结果，前端会移除旧候选 mask。
- AI 页面只显示本页最新生成的 SAM 2.1 候选，不会把工作区已有 mask 带入 AI 画布；重复执行高精度分割会替换上一次 AI 页候选；新生成 mask 会写入全局 `masks` 并自动选中，右侧分类树可直接给生成结果换标签，“推送至工作区编辑”会切回工作区的多边形调整工具并保留选择。 - AI 页面只显示本页最新生成的 SAM 2.1 候选，不会把工作区已有 mask 带入 AI 画布；重复执行高精度分割会替换上一次 AI 页候选；新生成 mask 会写入全局 `masks` 并自动选中，右侧分类树可直接给生成结果换标签，“推送至工作区编辑”会切回工作区的多边形调整工具并保留选择和当前帧视角，不会因工作区重新加载而跳回第一帧。
- 工作区传播功能会使用当前打开参考帧的全部 mask 作为 seed，按用户设置的传播起始帧和传播结束帧向前/向后追踪；用户可直接修改数字框，也可先点击“自动传播”进入时间轴范围选择模式，在播放进度条或视频处理进度条上点击/拖拽选择范围，再点击“开始传播”。工作区顶栏可单独选择本次传播使用的 SAM 2.1 tiny/small/base+/large 权重，不提供 SAM2/SAM3 家族切换；前端提交传播前会先保存当前项目中的 draft/dirty mask，使 seed 优先携带稳定的后端 `source_annotation_id`，再把传播权重 id、seed、seed 来源 id 和方向组装为 `/api/ai/propagate/task` 后台任务。后端入队时会规范化/校验权重 id，并把规范化后的 id 写入任务 payload/result；worker 会按 seed 来源、方向和 seed 签名去重，同权重且未改变的 mask 二次传播时直接跳过，已改变或换用其他权重的 mask 会先删除同源旧自动传播标注再重传；旧版本使用前端临时 `source_mask_id` 生成的传播结果会按同一参考帧、方向和语义信息兼容清理，避免同一个 mask 传播两次产生重叠。任务进度写入 `processing_tasks` 并可在 Dashboard 查看/取消/重试，工作区轮询任务状态并刷新已保存标注。传播结果回显后，视频处理进度条会把自动传播生成的帧区段标为蓝色，人工/AI 标注帧显示为红色竖线；每次自动传播成功处理过的范围会在当前会话中额外叠加不同色系的深到浅渐变片段，用于辨认最近处理过哪一段视频；普通状态下点击视频处理进度条或红/蓝帧标识可跳转到对应帧，底部缩略图也会用红色边框标识人工/AI 标注帧、蓝色边框标识传播/推理帧；如果同一帧同时有人工作业和传播结果，红色人工/AI 标注框优先保留，蓝色传播状态以内描边表达；当前帧如果同时是人工/AI 标注帧，会显示青色外框加红色内描边，固定为外层当前帧、内层标注框。 - 工作区传播功能会使用当前打开参考帧的全部 mask 作为 seed，按用户设置的传播起始帧和传播结束帧向前/向后追踪；用户可直接修改数字框，也可先点击“自动传播”进入时间轴范围选择模式，在播放进度条或视频处理进度条上点击/拖拽选择范围，再点击“开始传播”。工作区顶栏可单独选择本次传播使用的 SAM 2.1 tiny/small/base+/large 权重，不提供 SAM2/SAM3 家族切换；前端提交传播前会先保存当前项目中的 draft/dirty mask，使 seed 优先携带稳定的后端 `source_annotation_id`，再把传播权重 id、seed、seed 来源 id、边缘平滑参数和方向组装为 `/api/ai/propagate/task` 后台任务。后端入队时会规范化/校验权重 id，并把规范化后的 id 写入任务 payload/result；worker 会按 seed 来源、方向、平滑参数和 seed 签名去重，同权重且未改变的 mask 二次传播时直接跳过，已改变、修改平滑参数或换用其他权重的 mask 会先删除同源旧自动传播标注再重传；旧版本使用前端临时 `source_mask_id` 生成的传播结果会按同一参考帧、方向和语义信息兼容清理，中间帧人工新增或修改同一物体后重新传播时，也会在写入目标帧新结果前按语义和空间重叠清理旧传播结果，且写入前清理不受旧结果传播方向限制，避免向前传播时与早先向后生成的旧 mask 叠加。带 `geometry_smoothing` 的 seed 在 forward/backward 两个方向保存前都会应用同一平滑参数。任务进度写入 `processing_tasks` 并可在 Dashboard 查看/取消/重试，工作区轮询任务状态并刷新已保存标注。传播结果回显后，视频处理进度条会把自动传播生成的帧区段标为蓝色，人工/AI 标注帧显示为红色竖线；每次自动传播成功处理过的范围会在当前会话中额外叠加不同色系的深到浅渐变片段，用于辨认最近处理过哪一段视频；普通状态下点击视频处理进度条或红/蓝帧标识可跳转到对应帧，底部缩略图也会用红色边框标识人工/AI 标注帧、蓝色边框标识传播/推理帧；如果同一帧同时有人工作业和传播结果，红色人工/AI 标注框优先保留，蓝色传播状态以内描边表达；当前帧如果同时是人工/AI 标注帧，会显示青色外框加红色内描边，固定为外层当前帧、内层标注框。
- 前端 `exportCoco()` 已对齐到 `/api/export/{projectId}/coco`。 - 前端 `exportCoco()` 已对齐到 `/api/export/{projectId}/coco`。
- 工作区“导出 JSON 标注集”和“导出 PNG Mask ZIP”按钮已绑定下载流程；导出前会先保存当前待归档的前端 mask。 - 工作区“导出 JSON 标注集”和“导出 PNG Mask ZIP”按钮已绑定下载流程；导出前会先保存当前待归档的前端 mask。
- 工作区“导入 GT Mask”按钮已绑定 `/api/ai/import-gt-mask`，导入后会刷新并回显已保存标注和 seed point。 - 工作区“导入 GT Mask”按钮已绑定 `/api/ai/import-gt-mask`，导入后会刷新并回显已保存标注和 seed point。

126
backend/routers/ai.py
View File

@@ -17,6 +17,8 @@ from schemas import (
AiRuntimeStatus, AiRuntimeStatus,
MaskAnalysisRequest, MaskAnalysisRequest,
MaskAnalysisResponse, MaskAnalysisResponse,
SmoothMaskRequest,
SmoothMaskResponse,
PredictRequest, PredictRequest,
PredictResponse, PredictResponse,
PropagateRequest, PropagateRequest,
@@ -96,6 +98,14 @@ def _polygon_area(polygon: list[list[float]]) -> float:
return abs(total) / 2.0 return abs(total) / 2.0
def _normalize_polygon(polygon: list[list[float]]) -> list[list[float]]:
return [[_clamp01(point[0]), _clamp01(point[1])] for point in polygon if len(point) >= 2]
def _normalize_polygons(polygons: list[list[list[float]]]) -> list[list[list[float]]]:
return [polygon for polygon in (_normalize_polygon(polygon) for polygon in polygons) if len(polygon) >= 3]
def _analysis_anchors(polygons: list[list[list[float]]], points: list[list[float]] | None) -> list[list[float]]: def _analysis_anchors(polygons: list[list[list[float]]], points: list[list[float]] | None) -> list[list[float]]:
if points: if points:
return [[_clamp01(point[0]), _clamp01(point[1])] for point in points if len(point) >= 2] return [[_clamp01(point[0]), _clamp01(point[1])] for point in points if len(point) >= 2]
@@ -108,6 +118,63 @@ def _analysis_anchors(polygons: list[list[list[float]]], points: list[list[float
return anchors[:32] return anchors[:32]
def _normalize_smoothing_options(strength: float | int | None, method: str | None = None) -> dict[str, Any]:
clamped_strength = max(0.0, min(float(strength or 0.0), 100.0))
normalized_method = (method or "chaikin").lower()
if normalized_method != "chaikin":
normalized_method = "chaikin"
return {
"strength": round(clamped_strength, 2),
"method": normalized_method,
}
def _chaikin_smooth_polygon(polygon: list[list[float]], iterations: int) -> list[list[float]]:
points = polygon
for _ in range(max(0, iterations)):
if len(points) < 3:
break
next_points: list[list[float]] = []
for index, current in enumerate(points):
following = points[(index + 1) % len(points)]
next_points.append([
_clamp01(0.75 * current[0] + 0.25 * following[0]),
_clamp01(0.75 * current[1] + 0.25 * following[1]),
])
next_points.append([
_clamp01(0.25 * current[0] + 0.75 * following[0]),
_clamp01(0.25 * current[1] + 0.75 * following[1]),
])
points = next_points
return points
def _simplify_polygon(polygon: list[list[float]], strength: float) -> list[list[float]]:
if len(polygon) < 3 or strength <= 0:
return polygon
contour = np.array([[[point[0], point[1]]] for point in polygon], dtype=np.float32)
arc_length = cv2.arcLength(contour, True)
epsilon = arc_length * (0.001 + (strength / 100.0) * 0.006)
approx = cv2.approxPolyDP(contour, epsilon, True).reshape(-1, 2)
if len(approx) < 3:
return polygon
return [[_clamp01(float(x)), _clamp01(float(y))] for x, y in approx]
def _smooth_polygon(polygon: list[list[float]], smoothing: dict[str, Any]) -> list[list[float]]:
strength = float(smoothing.get("strength") or 0.0)
if strength <= 0:
return _normalize_polygon(polygon)
iterations = max(1, min(3, int(strength // 35) + 1))
smoothed = _chaikin_smooth_polygon(_normalize_polygon(polygon), iterations)
simplified = _simplify_polygon(smoothed, strength)
return simplified if len(simplified) >= 3 else _normalize_polygon(polygon)
def _smooth_polygons(polygons: list[list[list[float]]], smoothing: dict[str, Any]) -> list[list[list[float]]]:
return [polygon for polygon in (_smooth_polygon(polygon, smoothing) for polygon in polygons) if len(polygon) >= 3]
def _frame_window( def _frame_window(
frames: list[Frame], frames: list[Frame],
source_position: int, source_position: int,
@@ -436,11 +503,7 @@ def analyze_mask(payload: MaskAnalysisRequest, db: Session = Depends(get_db)) ->
if not polygons: if not polygons:
raise HTTPException(status_code=400, detail="Mask analysis requires polygons") raise HTTPException(status_code=400, detail="Mask analysis requires polygons")
valid_polygons = [ valid_polygons = _normalize_polygons(polygons)
[[_clamp01(point[0]), _clamp01(point[1])] for point in polygon if len(point) >= 2]
for polygon in polygons
]
valid_polygons = [polygon for polygon in valid_polygons if len(polygon) >= 3]
if not valid_polygons: if not valid_polygons:
raise HTTPException(status_code=400, detail="Mask analysis requires at least one valid polygon") raise HTTPException(status_code=400, detail="Mask analysis requires at least one valid polygon")
@@ -473,6 +536,46 @@ def analyze_mask(payload: MaskAnalysisRequest, db: Session = Depends(get_db)) ->
} }
@router.post(
"/smooth-mask",
response_model=SmoothMaskResponse,
summary="Smooth editable mask polygons with backend geometry rules",
)
def smooth_mask(payload: SmoothMaskRequest, db: Session = Depends(get_db)) -> dict:
"""Return a smoothed polygon mask without persisting it.
The frontend keeps this as an explicit edit operation: users preview/apply it
to the current mask, then save through the normal annotation endpoint.
"""
if payload.frame_id is not None:
frame = db.query(Frame).filter(Frame.id == payload.frame_id).first()
if not frame:
raise HTTPException(status_code=404, detail="Frame not found")
polygons = payload.mask_data.get("polygons") or []
valid_polygons = _normalize_polygons(polygons)
if not valid_polygons:
raise HTTPException(status_code=400, detail="Mask smoothing requires at least one valid polygon")
smoothing = _normalize_smoothing_options(payload.strength, payload.method)
smoothed_polygons = _smooth_polygons(valid_polygons, smoothing)
if not smoothed_polygons:
raise HTTPException(status_code=400, detail="Mask smoothing produced no valid polygons")
area = sum(_polygon_area(polygon) for polygon in smoothed_polygons)
bbox = _polygon_bbox(smoothed_polygons[0])
anchors = _analysis_anchors(smoothed_polygons, payload.points)
return {
"polygons": smoothed_polygons,
"topology_anchor_count": len(anchors),
"topology_anchors": anchors,
"area": area,
"bbox": bbox,
"smoothing": smoothing,
"message": f"已应用边缘平滑强度 {smoothing['strength']:.0f}",
}
@router.post( @router.post(
"/propagate", "/propagate",
response_model=PropagateResponse, response_model=PropagateResponse,
@@ -544,6 +647,13 @@ def propagate(payload: PropagateRequest, db: Session = Depends(get_db)) -> dict:
label = seed.get("label") or "Propagated Mask" label = seed.get("label") or "Propagated Mask"
color = seed.get("color") or "#06b6d4" color = seed.get("color") or "#06b6d4"
model_id = sam_registry.normalize_model_id(payload.model) model_id = sam_registry.normalize_model_id(payload.model)
seed_smoothing = seed.get("smoothing")
smoothing = _normalize_smoothing_options(
seed_smoothing.get("strength"),
seed_smoothing.get("method"),
) if isinstance(seed_smoothing, dict) else None
if smoothing and smoothing["strength"] <= 0:
smoothing = None
for frame_result in propagated: for frame_result in propagated:
relative_index = int(frame_result.get("frame_index", -1)) relative_index = int(frame_result.get("frame_index", -1))
@@ -557,22 +667,24 @@ def propagate(payload: PropagateRequest, db: Session = Depends(get_db)) -> dict:
for polygon_index, polygon in enumerate(result_polygons): for polygon_index, polygon in enumerate(result_polygons):
if len(polygon) < 3: if len(polygon) < 3:
continue continue
polygon_to_save = _smooth_polygon(polygon, smoothing) if smoothing else polygon
annotation = Annotation( annotation = Annotation(
project_id=payload.project_id, project_id=payload.project_id,
frame_id=frame.id, frame_id=frame.id,
template_id=template_id, template_id=template_id,
mask_data={ mask_data={
"polygons": [polygon], "polygons": [polygon_to_save],
"label": label, "label": label,
"color": color, "color": color,
"source": f"{model_id}_propagation", "source": f"{model_id}_propagation",
"propagated_from_frame_id": source_frame.id, "propagated_from_frame_id": source_frame.id,
"propagated_from_frame_index": source_frame.frame_index, "propagated_from_frame_index": source_frame.frame_index,
"score": scores[polygon_index] if polygon_index < len(scores) else None, "score": scores[polygon_index] if polygon_index < len(scores) else None,
**({"geometry_smoothing": smoothing} if smoothing else {}),
**({"class": class_metadata} if class_metadata else {}), **({"class": class_metadata} if class_metadata else {}),
}, },
points=None, points=None,
bbox=_polygon_bbox(polygon), bbox=_polygon_bbox(polygon_to_save),
) )
db.add(annotation) db.add(annotation)
created.append(annotation) created.append(annotation)

20
backend/schemas.py
View File

@@ -209,6 +209,25 @@ class MaskAnalysisResponse(BaseModel):
message: str message: str
class SmoothMaskRequest(BaseModel):
frame_id: Optional[int] = None
mask_data: dict[str, Any]
points: Optional[list[list[float]]] = None
bbox: Optional[list[float]] = None
strength: float = 0.0
method: str = "chaikin"
class SmoothMaskResponse(BaseModel):
polygons: list[list[list[float]]]
topology_anchor_count: int
topology_anchors: list[list[float]]
area: float
bbox: Optional[list[float]] = None
smoothing: dict[str, Any]
message: str
class PropagationSeed(BaseModel): class PropagationSeed(BaseModel):
polygons: Optional[list[list[list[float]]]] = None polygons: Optional[list[list[list[float]]]] = None
bbox: Optional[list[float]] = None bbox: Optional[list[float]] = None
@@ -221,6 +240,7 @@ class PropagationSeed(BaseModel):
source_mask_id: Optional[str] = None source_mask_id: Optional[str] = None
source_annotation_id: Optional[int] = None source_annotation_id: Optional[int] = None
propagation_seed_signature: Optional[str] = None propagation_seed_signature: Optional[str] = None
smoothing: Optional[dict[str, Any]] = None
class PropagateRequest(BaseModel): class PropagateRequest(BaseModel):

176
backend/services/propagation_task_runner.py
View File

@@ -8,6 +8,8 @@ from datetime import datetime, timezone
from pathlib import Path from pathlib import Path
from typing import Any from typing import Any
import cv2
import numpy as np
from sqlalchemy.orm import Session from sqlalchemy.orm import Session
from minio_client import download_file from minio_client import download_file
@@ -81,6 +83,87 @@ def _polygon_bbox(polygon: list[list[float]]) -> list[float]:
return [left, top, max(right - left, 0.0), max(bottom - top, 0.0)] return [left, top, max(right - left, 0.0), max(bottom - top, 0.0)]
def _normalize_polygon(polygon: list[list[float]]) -> list[list[float]]:
return [[_clamp01(point[0]), _clamp01(point[1])] for point in polygon if len(point) >= 2]
def _normalize_smoothing_options(value: Any) -> dict[str, Any] | None:
if not isinstance(value, dict):
return None
try:
strength = max(0.0, min(float(value.get("strength") or 0.0), 100.0))
except (TypeError, ValueError):
strength = 0.0
if strength <= 0:
return None
method = str(value.get("method") or "chaikin").lower()
if method != "chaikin":
method = "chaikin"
return {"strength": round(strength, 2), "method": method}
def _chaikin_smooth_polygon(polygon: list[list[float]], iterations: int) -> list[list[float]]:
points = _normalize_polygon(polygon)
for _ in range(max(0, iterations)):
if len(points) < 3:
break
next_points: list[list[float]] = []
for index, current in enumerate(points):
following = points[(index + 1) % len(points)]
next_points.append([
_clamp01(0.75 * current[0] + 0.25 * following[0]),
_clamp01(0.75 * current[1] + 0.25 * following[1]),
])
next_points.append([
_clamp01(0.25 * current[0] + 0.75 * following[0]),
_clamp01(0.25 * current[1] + 0.75 * following[1]),
])
points = next_points
return points
def _simplify_polygon(polygon: list[list[float]], strength: float) -> list[list[float]]:
if len(polygon) < 3:
return polygon
contour = np.array([[[point[0], point[1]]] for point in polygon], dtype=np.float32)
arc_length = cv2.arcLength(contour, True)
epsilon = arc_length * (0.001 + (strength / 100.0) * 0.006)
approx = cv2.approxPolyDP(contour, epsilon, True).reshape(-1, 2)
if len(approx) < 3:
return polygon
return [[_clamp01(float(x)), _clamp01(float(y))] for x, y in approx]
def _smooth_polygon(polygon: list[list[float]], smoothing: dict[str, Any] | None) -> list[list[float]]:
if not smoothing:
return _normalize_polygon(polygon)
strength = float(smoothing.get("strength") or 0.0)
if strength <= 0:
return _normalize_polygon(polygon)
iterations = max(1, min(3, int(strength // 35) + 1))
smoothed = _chaikin_smooth_polygon(polygon, iterations)
simplified = _simplify_polygon(smoothed, strength)
return simplified if len(simplified) >= 3 else _normalize_polygon(polygon)
def _bbox_area(bbox: list[float]) -> float:
return max(float(bbox[2]), 0.0) * max(float(bbox[3]), 0.0)
def _bbox_overlap_ratio(a: list[float], b: list[float]) -> float:
ax1, ay1, aw, ah = a
bx1, by1, bw, bh = b
ax2 = ax1 + aw
ay2 = ay1 + ah
bx2 = bx1 + bw
by2 = by1 + bh
overlap_width = max(0.0, min(ax2, bx2) - max(ax1, bx1))
overlap_height = max(0.0, min(ay2, by2) - max(ay1, by1))
overlap_area = overlap_width * overlap_height
smallest_area = min(_bbox_area(a), _bbox_area(b))
return overlap_area / smallest_area if smallest_area > 0 else 0.0
def _stable_json(value: Any) -> str: def _stable_json(value: Any) -> str:
return json.dumps(value, ensure_ascii=False, sort_keys=True, separators=(",", ":")) return json.dumps(value, ensure_ascii=False, sort_keys=True, separators=(",", ":"))
@@ -109,6 +192,7 @@ def _seed_signature(seed: dict[str, Any]) -> str:
"color": seed.get("color"), "color": seed.get("color"),
"class_metadata": seed.get("class_metadata") or {}, "class_metadata": seed.get("class_metadata") or {},
"template_id": seed.get("template_id"), "template_id": seed.get("template_id"),
"smoothing": _normalize_smoothing_options(seed.get("smoothing")),
} }
return hashlib.sha256(_stable_json(_canonicalize_signature_value(signature_payload)).encode("utf-8")).hexdigest() return hashlib.sha256(_stable_json(_canonicalize_signature_value(signature_payload)).encode("utf-8")).hexdigest()
@@ -131,6 +215,20 @@ def _seed_key(seed: dict[str, Any]) -> str:
}) })
def _semantic_seed_matches(mask_data: dict[str, Any], seed: dict[str, Any]) -> bool:
"""Best-effort match when a manually edited replacement lacks old lineage ids."""
class_metadata = seed.get("class_metadata") or {}
previous_class = mask_data.get("class") or {}
previous_class_id = previous_class.get("id") or previous_class.get("name")
class_id = class_metadata.get("id") or class_metadata.get("name")
if previous_class_id and class_id and str(previous_class_id) != str(class_id):
return False
return (
mask_data.get("label") == seed.get("label")
and mask_data.get("color") == seed.get("color")
)
def _legacy_seed_matches(mask_data: dict[str, Any], seed: dict[str, Any]) -> bool: def _legacy_seed_matches(mask_data: dict[str, Any], seed: dict[str, Any]) -> bool:
"""Best-effort match for propagation annotations created before seed keys.""" """Best-effort match for propagation annotations created before seed keys."""
class_metadata = seed.get("class_metadata") or {} class_metadata = seed.get("class_metadata") or {}
@@ -174,6 +272,52 @@ def _direction_matches(mask_data: dict[str, Any], direction: str) -> bool:
return previous_direction in {None, direction} return previous_direction in {None, direction}
def _annotation_spatially_matches(annotation: Annotation, polygon: list[list[float]]) -> bool:
"""Use target-frame overlap as a final guard before replacing same-object propagation."""
candidate_bbox = _polygon_bbox(polygon)
for previous_polygon in (annotation.mask_data or {}).get("polygons") or []:
if len(previous_polygon) < 3:
continue
if _bbox_overlap_ratio(_polygon_bbox(previous_polygon), candidate_bbox) >= 0.15:
return True
return False
def _delete_replaced_frame_annotations(
db: Session,
*,
payload: dict[str, Any],
frame_id: int,
seed_key: str,
seed: dict[str, Any],
polygon: list[list[float]],
) -> int:
"""Delete old propagated masks for the same object immediately before writing a new result."""
previous_annotations = (
db.query(Annotation)
.filter(Annotation.project_id == int(payload["project_id"]))
.filter(Annotation.frame_id == frame_id)
.all()
)
deleted_count = 0
for annotation in previous_annotations:
mask_data = annotation.mask_data or {}
source = str(mask_data.get("source") or "")
if not source.endswith("_propagation"):
continue
same_lineage = _seed_identity_matches(mask_data, seed_key, seed)
same_manual_replacement = (
_semantic_seed_matches(mask_data, seed)
and _annotation_spatially_matches(annotation, polygon)
)
if same_lineage or same_manual_replacement:
db.delete(annotation)
deleted_count += 1
if deleted_count:
db.commit()
return deleted_count
def _prepare_seed_propagation( def _prepare_seed_propagation(
db: Session, db: Session,
*, *,
@@ -264,10 +408,10 @@ def _save_propagated_annotations(
source_frame: Frame, source_frame: Frame,
propagated: list[dict[str, Any]], propagated: list[dict[str, Any]],
seed: dict[str, Any], seed: dict[str, Any],
) -> list[Annotation]: ) -> tuple[list[Annotation], int]:
created: list[Annotation] = [] created: list[Annotation] = []
if payload.get("save_annotations", True) is False: if payload.get("save_annotations", True) is False:
return created return created, 0
class_metadata = seed.get("class_metadata") class_metadata = seed.get("class_metadata")
template_id = seed.get("template_id") template_id = seed.get("template_id")
@@ -279,7 +423,10 @@ def _save_propagated_annotations(
seed_signature = _seed_signature(seed) seed_signature = _seed_signature(seed)
source_annotation_id = seed.get("source_annotation_id") source_annotation_id = seed.get("source_annotation_id")
source_mask_id = seed.get("source_mask_id") source_mask_id = seed.get("source_mask_id")
smoothing = _normalize_smoothing_options(seed.get("smoothing"))
direction = str(payload.get("current_direction") or "") direction = str(payload.get("current_direction") or "")
deleted_count = 0
cleaned_frame_ids: set[int] = set()
for frame_result in propagated: for frame_result in propagated:
relative_index = int(frame_result.get("frame_index", -1)) relative_index = int(frame_result.get("frame_index", -1))
@@ -290,7 +437,23 @@ def _save_propagated_annotations(
continue continue
result_polygons = frame_result.get("polygons") or [] result_polygons = frame_result.get("polygons") or []
scores = frame_result.get("scores") or [] scores = frame_result.get("scores") or []
for polygon_index, polygon in enumerate(result_polygons): smoothed_polygons = [
_smooth_polygon(polygon, smoothing)
for polygon in result_polygons
if len(polygon) >= 3
]
cleanup_polygon = next((polygon for polygon in smoothed_polygons if len(polygon) >= 3), None)
if cleanup_polygon is not None and frame.id not in cleaned_frame_ids:
deleted_count += _delete_replaced_frame_annotations(
db,
payload=payload,
frame_id=int(frame.id),
seed_key=seed_key,
seed=seed,
polygon=cleanup_polygon,
)
cleaned_frame_ids.add(int(frame.id))
for polygon_index, polygon in enumerate(smoothed_polygons):
if len(polygon) < 3: if len(polygon) < 3:
continue continue
annotation = Annotation( annotation = Annotation(
@@ -310,6 +473,7 @@ def _save_propagated_annotations(
"source_annotation_id": source_annotation_id, "source_annotation_id": source_annotation_id,
"source_mask_id": source_mask_id, "source_mask_id": source_mask_id,
"score": scores[polygon_index] if polygon_index < len(scores) else None, "score": scores[polygon_index] if polygon_index < len(scores) else None,
**({"geometry_smoothing": smoothing} if smoothing else {}),
**({"class": class_metadata} if class_metadata else {}), **({"class": class_metadata} if class_metadata else {}),
}, },
points=None, points=None,
@@ -321,7 +485,7 @@ def _save_propagated_annotations(
db.commit() db.commit()
for annotation in created: for annotation in created:
db.refresh(annotation) db.refresh(annotation)
return created return created, deleted_count
def _run_one_step( def _run_one_step(
@@ -381,7 +545,7 @@ def _run_one_step(
) )
save_payload = {**payload, "current_direction": direction} save_payload = {**payload, "current_direction": direction}
created = _save_propagated_annotations( created, write_cleanup_count = _save_propagated_annotations(
db, db,
payload=save_payload, payload=save_payload,
selected_frames=selected_frames, selected_frames=selected_frames,
@@ -394,7 +558,7 @@ def _run_one_step(
"direction": direction, "direction": direction,
"processed_frame_count": len(selected_frames), "processed_frame_count": len(selected_frames),
"created_annotation_count": len(created), "created_annotation_count": len(created),
"deleted_annotation_count": int(seed_state["deleted_annotation_count"]), "deleted_annotation_count": int(seed_state["deleted_annotation_count"]) + write_cleanup_count,
"skipped_seed_count": 0, "skipped_seed_count": 0,
"seed_label": seed.get("label"), "seed_label": seed.get("label"),
"seed_key": seed_state["seed_key"], "seed_key": seed_state["seed_key"],

206
backend/tests/test_ai.py
View File

@@ -223,6 +223,41 @@ def test_analyze_mask_returns_backend_geometry_properties(client):
assert body["message"] == "已从后端重新提取几何拓扑锚点" assert body["message"] == "已从后端重新提取几何拓扑锚点"
def test_smooth_mask_returns_backend_smoothed_geometry(client):
_, frame, _ = _create_project_and_frame(client)
response = client.post("/api/ai/smooth-mask", json={
"frame_id": frame["id"],
"mask_data": {
"polygons": [[[0.1, 0.1], [0.3, 0.1], [0.3, 0.3], [0.1, 0.3]]],
"label": "胆囊",
"color": "#ff0000",
},
"strength": 45,
})
assert response.status_code == 200
body = response.json()
assert body["smoothing"] == {"strength": 45.0, "method": "chaikin"}
assert len(body["polygons"]) == 1
assert len(body["polygons"][0]) > 4
assert body["topology_anchor_count"] > 0
assert body["message"] == "已应用边缘平滑强度 45"
def test_seed_signature_includes_smoothing_parameters():
seed = {
"polygons": [[[0.1, 0.1], [0.3, 0.1], [0.3, 0.3]]],
"label": "胆囊",
"color": "#ff0000",
}
assert _seed_signature({**seed, "smoothing": {"strength": 20, "method": "chaikin"}}) != _seed_signature({
**seed,
"smoothing": {"strength": 40, "method": "chaikin"},
})
def test_propagate_saves_tracked_annotations(client, monkeypatch): def test_propagate_saves_tracked_annotations(client, monkeypatch):
project = client.post("/api/projects", json={"name": "Video Project"}).json() project = client.post("/api/projects", json={"name": "Video Project"}).json()
frames = [ frames = [
@@ -324,6 +359,7 @@ def test_queue_propagation_task_creates_processing_task(client, monkeypatch):
"seed": { "seed": {
"polygons": [[[0.1, 0.1], [0.2, 0.1], [0.2, 0.2]]], "polygons": [[[0.1, 0.1], [0.2, 0.1], [0.2, 0.2]]],
"label": "胆囊", "label": "胆囊",
"smoothing": {"strength": 35, "method": "chaikin"},
}, },
}], }],
}) })
@@ -335,6 +371,7 @@ def test_queue_propagation_task_creates_processing_task(client, monkeypatch):
assert body["celery_task_id"] == "celery-propagate-1" assert body["celery_task_id"] == "celery-propagate-1"
assert body["payload"]["model"] == "sam2.1_hiera_tiny" assert body["payload"]["model"] == "sam2.1_hiera_tiny"
assert body["payload"]["steps"][0]["seed"]["label"] == "胆囊" assert body["payload"]["steps"][0]["seed"]["label"] == "胆囊"
assert body["payload"]["steps"][0]["seed"]["smoothing"] == {"strength": 35, "method": "chaikin"}
assert queued == [body["id"]] assert queued == [body["id"]]
@@ -418,6 +455,7 @@ def test_propagation_task_runner_saves_annotations_and_progress(client, db_sessi
"label": "胆囊", "label": "胆囊",
"color": "#ff0000", "color": "#ff0000",
"class_metadata": {"id": "c1", "name": "胆囊"}, "class_metadata": {"id": "c1", "name": "胆囊"},
"smoothing": {"strength": 40, "method": "chaikin"},
}, },
}], }],
}, },
@@ -452,6 +490,8 @@ def test_propagation_task_runner_saves_annotations_and_progress(client, db_sessi
listing = client.get(f"/api/ai/annotations?project_id={project['id']}") listing = client.get(f"/api/ai/annotations?project_id={project['id']}")
assert listing.json()[0]["frame_id"] == frames[1]["id"] assert listing.json()[0]["frame_id"] == frames[1]["id"]
assert listing.json()[0]["mask_data"]["source"] == "sam2.1_hiera_tiny_propagation" assert listing.json()[0]["mask_data"]["source"] == "sam2.1_hiera_tiny_propagation"
assert listing.json()[0]["mask_data"]["geometry_smoothing"] == {"strength": 40.0, "method": "chaikin"}
assert len(listing.json()[0]["mask_data"]["polygons"][0]) > 3
def test_propagation_task_runner_skips_unchanged_seed_and_replaces_changed_seed(client, db_session, monkeypatch): def test_propagation_task_runner_skips_unchanged_seed_and_replaces_changed_seed(client, db_session, monkeypatch):
@@ -614,6 +654,172 @@ def test_propagation_task_runner_replaces_legacy_or_different_weight_results(cli
assert annotations[0].mask_data["polygons"] == [output_polygon] assert annotations[0].mask_data["polygons"] == [output_polygon]
def test_propagation_task_runner_replaces_downstream_result_from_middle_frame_manual_seed(client, db_session, monkeypatch):
project = client.post("/api/projects", json={"name": "Propagation Middle Frame Replacement"}).json()
frames = [
client.post(f"/api/projects/{project['id']}/frames", json={
"project_id": project["id"],
"frame_index": idx,
"image_url": f"frames/{idx}.jpg",
"width": 640,
"height": 360,
}).json()
for idx in range(3)
]
old_downstream_polygon = [[0.18, 0.18], [0.28, 0.18], [0.28, 0.28]]
replacement_seed_polygon = [[0.16, 0.16], [0.26, 0.16], [0.26, 0.26]]
replacement_downstream_polygon = [[0.19, 0.19], [0.29, 0.19], [0.29, 0.29]]
db_session.add(Annotation(
project_id=project["id"],
frame_id=frames[2]["id"],
template_id=3,
mask_data={
"polygons": [old_downstream_polygon],
"label": "胆囊",
"color": "#ff0000",
"class": {"id": "c1", "name": "胆囊", "color": "#ff0000"},
"source": "sam2.1_hiera_tiny_propagation",
"propagated_from_frame_id": frames[0]["id"],
"propagation_seed_key": "annotation:7",
"propagation_seed_signature": "old-signature",
"propagation_direction": "forward",
"source_annotation_id": 7,
"source_mask_id": "annotation-7",
},
bbox=[0.18, 0.18, 0.1, 0.1],
))
db_session.commit()
task = ProcessingTask(
task_type="propagate_masks",
status="queued",
progress=0,
project_id=project["id"],
payload={
"project_id": project["id"],
"frame_id": frames[1]["id"],
"model": "sam2.1_hiera_tiny",
"include_source": False,
"save_annotations": True,
"steps": [{
"direction": "forward",
"max_frames": 2,
"seed": {
"polygons": [replacement_seed_polygon],
"label": "胆囊",
"color": "#ff0000",
"source_annotation_id": 20,
"source_mask_id": "annotation-20",
},
}],
},
)
db_session.add(task)
db_session.commit()
db_session.refresh(task)
monkeypatch.setattr("services.propagation_task_runner.download_file", lambda object_name: b"jpeg")
monkeypatch.setattr("services.propagation_task_runner.publish_task_progress_event", lambda event_task: None)
monkeypatch.setattr("services.propagation_task_runner.sam_registry.propagate_video", lambda model, frame_paths, source_frame_index, seed, direction, max_frames: [
{"frame_index": 0, "polygons": [seed["polygons"][0]], "scores": [0.9]},
{"frame_index": 1, "polygons": [replacement_downstream_polygon], "scores": [0.8]},
])
result = run_propagate_project_task(db_session, task.id)
assert result["created_annotation_count"] == 1
assert result["deleted_annotation_count"] == 1
annotations = db_session.query(Annotation).filter(Annotation.project_id == project["id"]).all()
assert len(annotations) == 1
assert annotations[0].frame_id == frames[2]["id"]
assert annotations[0].mask_data["polygons"] == [replacement_downstream_polygon]
assert annotations[0].mask_data["source_annotation_id"] == 20
assert annotations[0].mask_data["source_mask_id"] == "annotation-20"
def test_propagation_task_runner_replaces_forward_result_when_middle_frame_propagates_backward(client, db_session, monkeypatch):
project = client.post("/api/projects", json={"name": "Propagation Backward Middle Replacement"}).json()
frames = [
client.post(f"/api/projects/{project['id']}/frames", json={
"project_id": project["id"],
"frame_index": idx,
"image_url": f"frames/{idx}.jpg",
"width": 640,
"height": 360,
}).json()
for idx in range(3)
]
old_upstream_polygon = [[0.12, 0.12], [0.22, 0.12], [0.22, 0.22]]
replacement_seed_polygon = [[0.16, 0.16], [0.26, 0.16], [0.26, 0.26]]
replacement_upstream_polygon = [[0.13, 0.13], [0.23, 0.13], [0.23, 0.23]]
db_session.add(Annotation(
project_id=project["id"],
frame_id=frames[0]["id"],
mask_data={
"polygons": [old_upstream_polygon],
"label": "胆囊",
"color": "#ff0000",
"source": "sam2.1_hiera_tiny_propagation",
"propagated_from_frame_id": frames[0]["id"],
"propagation_seed_key": "annotation:7",
"propagation_seed_signature": "old-signature",
"propagation_direction": "forward",
"source_annotation_id": 7,
"source_mask_id": "annotation-7",
},
bbox=[0.12, 0.12, 0.1, 0.1],
))
db_session.commit()
task = ProcessingTask(
task_type="propagate_masks",
status="queued",
progress=0,
project_id=project["id"],
payload={
"project_id": project["id"],
"frame_id": frames[1]["id"],
"model": "sam2.1_hiera_tiny",
"include_source": False,
"save_annotations": True,
"steps": [{
"direction": "backward",
"max_frames": 2,
"seed": {
"polygons": [replacement_seed_polygon],
"label": "胆囊",
"color": "#ff0000",
"source_annotation_id": 20,
"source_mask_id": "annotation-20",
},
}],
},
)
db_session.add(task)
db_session.commit()
db_session.refresh(task)
monkeypatch.setattr("services.propagation_task_runner.download_file", lambda object_name: b"jpeg")
monkeypatch.setattr("services.propagation_task_runner.publish_task_progress_event", lambda event_task: None)
monkeypatch.setattr("services.propagation_task_runner.sam_registry.propagate_video", lambda model, frame_paths, source_frame_index, seed, direction, max_frames: [
{"frame_index": 0, "polygons": [replacement_upstream_polygon], "scores": [0.8]},
{"frame_index": 1, "polygons": [seed["polygons"][0]], "scores": [0.9]},
])
result = run_propagate_project_task(db_session, task.id)
assert result["created_annotation_count"] == 1
assert result["deleted_annotation_count"] == 1
annotations = db_session.query(Annotation).filter(Annotation.project_id == project["id"]).all()
assert len(annotations) == 1
assert annotations[0].frame_id == frames[0]["id"]
assert annotations[0].mask_data["polygons"] == [replacement_upstream_polygon]
assert annotations[0].mask_data["propagation_direction"] == "backward"
assert annotations[0].mask_data["source_annotation_id"] == 20
def test_propagation_task_runner_skips_unmodified_propagated_seed_on_overlapping_frames(client, db_session, monkeypatch): def test_propagation_task_runner_skips_unmodified_propagated_seed_on_overlapping_frames(client, db_session, monkeypatch):
project = client.post("/api/projects", json={"name": "Propagation Overlap Skip"}).json() project = client.post("/api/projects", json={"name": "Propagation Overlap Skip"}).json()
frames = [ frames = [

8
doc/03-frontend-element-audit.md
View File

@@ -68,7 +68,7 @@
| “导出 JSON 标注集”按钮 | 真实可用 | 导出前会保存未归档 mask，然后调用 `exportCoco()` 下载 JSON | | “导出 JSON 标注集”按钮 | 真实可用 | 导出前会保存未归档 mask，然后调用 `exportCoco()` 下载 JSON |
| “导出 PNG Mask ZIP”按钮 | 真实可用 | 导出前会保存未归档 mask，然后调用 `GET /api/export/{project_id}/masks` 下载 ZIP；后端同时包含单标注 mask、每帧语义融合 mask 和 `semantic_classes.json` | | “导出 PNG Mask ZIP”按钮 | 真实可用 | 导出前会保存未归档 mask，然后调用 `GET /api/export/{project_id}/masks` 下载 ZIP；后端同时包含单标注 mask、每帧语义融合 mask 和 `semantic_classes.json` |
| “导入 GT Mask”按钮 | 真实可用 | 选择图片后调用 `POST /api/ai/import-gt-mask`，后端按非零像素值和连通域生成 polygon 标注与距离变换 seed point，再回显到工作区 | | “导入 GT Mask”按钮 | 真实可用 | 选择图片后调用 `POST /api/ai/import-gt-mask`，后端按非零像素值和连通域生成 polygon 标注与距离变换 seed point，再回显到工作区 |
| 参考帧/起止帧/传播权重/自动传播 | 真实可用 | 当前打开帧即参考帧，前端会使用该帧全部 mask 作为 seed；工作区顶栏有独立“传播权重”下拉，可在传播前二次选择 SAM 2.1 tiny/small/base+/large 权重，不提供 SAM2/SAM3 家族切换，不影响 AI 智能分割页的单帧推理权重选择；传播权重下拉使用深色背景和青色文字，避免默认灰底白字不可读；如果用户尚未显式设置范围，点击“自动传播”会先进入时间轴范围选择模式，播放进度条和视频处理进度条都可点击/拖拽回填传播起始帧和传播结束帧，再点击“开始传播”提交；用户也可直接改数字框后点击按钮传播。提交后前端把传播权重 id、seed mask、seed 来源 id、未编辑传播结果的原始 seed 签名和前/后方向步骤提交到 `POST /api/ai/propagate/task`，后端先规范化/校验权重 id，再创建 `processing_tasks` 并由 Celery 执行对应 SAM 2.1 video predictor；worker 会在本次目标帧段内按 seed 来源和几何/语义签名做幂等判断，未改变且目标帧已有结果的 seed 直接跳过，已改变、目标帧只部分覆盖或换权重时会先删除本次目标帧段内同源旧自动传播标注再重新传播，避免重复传播产生重叠 mask；传播中顶栏显示任务进度、已处理帧次、删除旧区域数和已保存区域数，前端轮询 `GET /api/tasks/{task_id}` 并刷新已保存标注；任务可取消，若完成后 0 个新区域会明确提示没有生成新 mask 或已跳过未改变 mask | | 参考帧/起止帧/传播权重/自动传播 | 真实可用 | 当前打开帧即参考帧，前端会使用该帧全部 mask 作为 seed；工作区顶栏有独立“传播权重”下拉，可在传播前二次选择 SAM 2.1 tiny/small/base+/large 权重，不提供 SAM2/SAM3 家族切换，不影响 AI 智能分割页的单帧推理权重选择；传播权重下拉使用深色背景和青色文字，避免默认灰底白字不可读；如果用户尚未显式设置范围，点击“自动传播”会先进入时间轴范围选择模式，播放进度条和视频处理进度条都可点击/拖拽回填传播起始帧和传播结束帧，再点击“开始传播”提交；用户也可直接改数字框后点击按钮传播。提交后前端把传播权重 id、seed mask、seed 来源 id、未编辑传播结果的原始 seed 签名、mask 边缘平滑参数和前/后方向步骤提交到 `POST /api/ai/propagate/task`，后端先规范化/校验权重 id，再创建 `processing_tasks` 并由 Celery 执行对应 SAM 2.1 video predictor；worker 会在本次目标帧段内按 seed 来源和几何/语义/平滑参数签名做幂等判断，未改变且目标帧已有结果的 seed 直接跳过，已改变、目标帧只部分覆盖、换权重或平滑参数变化时会先删除本次目标帧段内同源旧自动传播标注再重新传播；中间帧人工新增/修改同一物体后重新传播时，后端会按语义和目标帧空间重叠清理旧传播结果，写入前清理不受旧结果 `propagation_direction` 限制，避免 backward 重传时与旧 forward mask 重叠；传播中顶栏显示任务进度、已处理帧次、删除旧区域数和已保存区域数，前端轮询 `GET /api/tasks/{task_id}` 并刷新已保存标注；任务可取消，若完成后 0 个新区域会明确提示没有生成新 mask 或已跳过未改变 mask |
| 清空片段遮罩 | 真实可用 | 点击“清空片段遮罩”后会进入和自动传播一致的时间轴范围选择模式，用户可在播放进度条或视频处理进度条上点击/拖拽选择起止帧，再点“确认清空”；执行后删除该帧段内所有本地 draft mask，并对已保存 mask 调用 `DELETE /api/ai/annotations/{annotation_id}` 删除后端标注；不在范围内的 mask 和选区会保留 | | 清空片段遮罩 | 真实可用 | 点击“清空片段遮罩”后会进入和自动传播一致的时间轴范围选择模式，用户可在播放进度条或视频处理进度条上点击/拖拽选择起止帧，再点“确认清空”；执行后删除该帧段内所有本地 draft mask，并对已保存 mask 调用 `DELETE /api/ai/annotations/{annotation_id}` 删除后端标注；不在范围内的 mask 和选区会保留 |
| “结构化归档保存”按钮 | 真实可用 | 未保存 mask 写入 `POST /api/ai/annotate`；dirty mask 写入 `PATCH /api/ai/annotations/{id}`；保存成功后会重新拉取后端标注，并用 saved annotation 替换本次提交的 draft mask，避免仍显示未保存 | | “结构化归档保存”按钮 | 真实可用 | 未保存 mask 写入 `POST /api/ai/annotate`；dirty mask 写入 `PATCH /api/ai/annotations/{id}`；保存成功后会重新拉取后端标注，并用 saved annotation 替换本次提交的 draft mask，避免仍显示未保存 |
@@ -87,6 +87,7 @@
| 画布上下文提示 | 真实可用 | 切换到多边形、矩形、圆、线、点、正/反向选点、框选、区域合并/去除、调整多边形等隐性操作工具时，画布左上角显示当前工具的完成/取消/选择顺序提示；提示会在数秒后自动隐藏，避免长期遮挡待编辑图像，工具或操作状态变化时会重新出现 | | 画布上下文提示 | 真实可用 | 切换到多边形、矩形、圆、线、点、正/反向选点、框选、区域合并/去除、调整多边形等隐性操作工具时，画布左上角显示当前工具的完成/取消/选择顺序提示；提示会在数秒后自动隐藏，避免长期遮挡待编辑图像，工具或操作状态变化时会重新出现 |
| Mask 渲染 | 真实可用 | 前端会把推理、手工绘制、GT 导入和已保存标注转成 Konva `pathData` 渲染 | | Mask 渲染 | 真实可用 | 前端会把推理、手工绘制、GT 导入和已保存标注转成 Konva `pathData` 渲染 |
| Mask 透明度 | 真实可用 | 右侧语义分类树上方的“遮罩透明度”滑杆写入全局 `maskPreviewOpacity`，Canvas 使用该值调整所有工作区 mask 预览透明度，选中 mask 会在该基础上略微加亮 | | Mask 透明度 | 真实可用 | 右侧语义分类树上方的“遮罩透明度”滑杆写入全局 `maskPreviewOpacity`，Canvas 使用该值调整所有工作区 mask 预览透明度，选中 mask 会在该基础上略微加亮 |
| 传播链跨帧选区跟随 | 真实可用 | 用户选中某个 mask 后切到同一自动传播结果覆盖的其他帧时，`CanvasArea` 会根据 `source_annotation_id`、`source_mask_id` 和 `propagation_seed_key` 查找目标帧对应传播 mask 并自动选中；找不到同链结果时才清空选区 |
| Polygon 逐点编辑 / 删除 | 真实可用 | 点击 mask 后显示 polygon 顶点；按住顶点即可直接拖动并实时重算 `pathData/segmentation/bbox/area`，不需要先单击选中顶点，已保存 mask 标为 dirty；顶点拖拽结束不会触发 Stage 平移，Canvas 当前缩放和位置保持不变；选中顶点后 Delete/Backspace 可删点但保留至少三点；选中 mask 但未选中顶点时 Delete/Backspace 删除整个 mask，已保存 mask 会同步调用后端删除 | | Polygon 逐点编辑 / 删除 | 真实可用 | 点击 mask 后显示 polygon 顶点；按住顶点即可直接拖动并实时重算 `pathData/segmentation/bbox/area`，不需要先单击选中顶点，已保存 mask 标为 dirty；顶点拖拽结束不会触发 Stage 平移，Canvas 当前缩放和位置保持不变；选中顶点后 Delete/Backspace 可删点但保留至少三点；选中 mask 但未选中顶点时 Delete/Backspace 删除整个 mask，已保存 mask 会同步调用后端删除 |
| GT seed point 回显/编辑 | 真实可用 | 已保存标注的 `points` 会显示为黄色 seed 点；拖动后标记为 dirty，归档保存会更新后端 | | GT seed point 回显/编辑 | 真实可用 | 已保存标注的 `points` 会显示为黄色 seed 点；拖动后标记为 dirty，归档保存会更新后端 |
| 应用分类 | 真实可用 | Canvas 右下角按钮可将当前选择的模板分类应用到本帧 mask；右侧语义分类树点击分类时会优先改当前已选 mask，并把已选 mask 移到前端渲染最上层方便继续编辑；已保存 mask 会标为 dirty，归档保存时更新后端 | | 应用分类 | 真实可用 | Canvas 右下角按钮可将当前选择的模板分类应用到本帧 mask；右侧语义分类树点击分类时会优先改当前已选 mask，并把已选 mask 移到前端渲染最上层方便继续编辑；已保存 mask 会标为 dirty，归档保存时更新后端 |
@@ -128,9 +129,10 @@
| 面板标题 | 已简化 | 原“本体论与属性分类管理树”固定说明栏已移除，右侧面板直接展示模板、透明度和语义分类树 | | 面板标题 | 已简化 | 原“本体论与属性分类管理树”固定说明栏已移除，右侧面板直接展示模板、透明度和语义分类树 |
| 分类树展示 / 换标签 | 真实可用 | 显示当前模板 classes；点击分类会设为后续新 mask 的 activeClass，如果 Canvas 已选 mask，则同步更新已选 mask 的标签、颜色和 class 元数据，并把已选 mask 移到前端渲染最上层；当用户在 Canvas 点击已有 mask 时，本面板会按 mask 的 class id / 名称自动切换模板、设置 active class，并滚动/聚焦到对应分类按钮 | | 分类树展示 / 换标签 | 真实可用 | 显示当前模板 classes；点击分类会设为后续新 mask 的 activeClass，如果 Canvas 已选 mask，则同步更新已选 mask 的标签、颜色和 class 元数据，并把已选 mask 移到前端渲染最上层；当用户在 Canvas 点击已有 mask 时，本面板会按 mask 的 class id / 名称自动切换模板、设置 active class，并滚动/聚焦到对应分类按钮 |
| 添加自定义分类 | 真实可用 | 需要先选择模板；新增分类通过 `PATCH /api/templates/{id}` 写入后端模板 `mapping_rules.classes`，并同步全局模板 store | | 添加自定义分类 | 真实可用 | 需要先选择模板；新增分类通过 `PATCH /api/templates/{id}` 写入后端模板 `mapping_rules.classes`，并同步全局模板 store |
| 后端模型置信度 | 真实可用 | 选中 mask 后调用 `POST /api/ai/analyze-mask`，优先显示后端返回的模型分数；手工/导入 mask 无模型分数时显示“无模型分数” | | 目标实例属性标题 | 真实可用 | “特定目标实例属性追踪”下方显示当前选中 mask 的 `className/label`，不再跟随全局 active class，避免点过其他分类后标题固定成旧分类 |
| 后端拓扑锚点数量 | 真实可用 | 选中 mask 后调用 `POST /api/ai/analyze-mask`，由后端根据 seed points 或 polygon 顶点采样返回锚点数量 | | 后端拓扑锚点数量 | 真实可用 | 选中 mask 后调用 `POST /api/ai/analyze-mask`，由后端根据 seed points 或 polygon 顶点采样返回锚点数量 |
| 重新提取拓扑锚点按钮 | 真实可用 | 调用 `POST /api/ai/analyze-mask` 并带 `extract_skeleton=true`，刷新后端几何锚点统计 | | 重新提取拓扑锚点按钮 | 真实可用 | 调用 `POST /api/ai/analyze-mask` 并带 `extract_skeleton=true`，刷新后端几何锚点统计 |
| 边缘平滑强度 / 应用边缘平滑 | 真实可用 | 选中 mask 后可调整 0-100 的平滑强度并调用 `POST /api/ai/smooth-mask`；后端用 Chaikin polygon smoothing 返回新 polygon、bbox、面积和拓扑锚点，前端把当前 mask 标记为 dirty/draft，保存后 `geometry_smoothing` 写入标注 metadata；自动传播 seed 会携带同一参数，前/后传播结果保存前应用一致平滑 |
## AISegmentation 独立 AI 页 ## AISegmentation 独立 AI 页
@@ -145,7 +147,7 @@
| 参数开关 | 真实可用 | UI 展示为“局部专注模式（自动裁剪无锚区域）”和“严格除杂模式（自动清理干涉点）”，只是为了让用户更容易理解，不重命名内部字段；`cropMode` 会随 `/api/ai/predict` 发送 `crop_to_prompt`，后端对点/框 prompt 裁剪推理区域并回映射 polygon；`autoDeleteBg` 会发送 `auto_filter_background` 和 `min_score`，后端过滤低分结果和覆盖负向点的结果 | | 参数开关 | 真实可用 | UI 展示为“局部专注模式（自动裁剪无锚区域）”和“严格除杂模式（自动清理干涉点）”，只是为了让用户更容易理解，不重命名内部字段；`cropMode` 会随 `/api/ai/predict` 发送 `crop_to_prompt`，后端对点/框 prompt 裁剪推理区域并回映射 polygon；`autoDeleteBg` 会发送 `auto_filter_background` 和 `min_score`，后端过滤低分结果和覆盖负向点的结果 |
| 遮罩清晰度 | 真实可用 | 调节 AI 页候选 mask 的预览透明度，只影响本页显示，不改变 mask 几何、分类或保存数据 | | 遮罩清晰度 | 真实可用 | 调节 AI 页候选 mask 的预览透明度，只影响本页显示，不改变 mask 几何、分类或保存数据 |
| 执行高精度语义分割 | 真实可用 | 使用当前项目帧和所选 SAM 2.1 变体调用 `/api/ai/predict`；SAM 2.1 需要点/框提示且只采用最高分候选；AI 页只渲染本页最新候选，不显示工作区已有 mask，重复执行会替换上一次 AI 页候选而不是叠加；生成结果写入全局 masks 并自动选中，右侧分类树可立即换标签 | | 执行高精度语义分割 | 真实可用 | 使用当前项目帧和所选 SAM 2.1 变体调用 `/api/ai/predict`；SAM 2.1 需要点/框提示且只采用最高分候选；AI 页只渲染本页最新候选，不显示工作区已有 mask，重复执行会替换上一次 AI 页候选而不是叠加；生成结果写入全局 masks 并自动选中，右侧分类树可立即换标签 |
| 推送至工作区编辑 | 真实可用 | 切回工作区并把工具切到“调整多边形”，保留 AI 页选中的未保存 mask；工作区回显后端标注时不会覆盖这类 draft mask | | 推送至工作区编辑 | 真实可用 | 切回工作区并把工具切到“调整多边形”，保留 AI 页选中的未保存 mask 和当前帧视角；工作区回显后端标注时不会覆盖这类 draft mask，也不会强制跳回第一帧 |
| 撤销/重做 | 真实可用 | 绑定全局 mask 历史栈 | | 撤销/重做 | 真实可用 | 绑定全局 mask 历史栈 |
| 删除最近锚点 | 真实可用 | 删除 AI 页最近一次放置的正/反向提示点，不影响已生成候选 mask 或工作区 mask | | 删除最近锚点 | 真实可用 | 删除 AI 页最近一次放置的正/反向提示点，不影响已生成候选 mask 或工作区 mask |
| 删除选中候选 | 真实可用 | 删除 AI 页当前选中的本页候选 mask；不会删除工作区已有 mask，Delete/Backspace 也遵循同一范围 | | 删除选中候选 | 真实可用 | 删除 AI 页当前选中的本页候选 mask；不会删除工作区已有 mask，Delete/Backspace 也遵循同一范围 |

11
doc/07-current-requirements-freeze.md
View File

@@ -49,6 +49,7 @@
- Canvas 显示当前帧图片。 - Canvas 显示当前帧图片。
- Canvas 支持滚轮缩放、移动工具拖拽、鼠标坐标显示。 - Canvas 支持滚轮缩放、移动工具拖拽、鼠标坐标显示。
- 时间轴支持缩略图点击切帧、range 拖动切帧、视频处理进度条点击切帧、人工/AI 标注帧和自动传播帧标识点击切帧、键盘左右方向键切帧、播放/暂停顺序推进帧。 - 时间轴支持缩略图点击切帧、range 拖动切帧、视频处理进度条点击切帧、人工/AI 标注帧和自动传播帧标识点击切帧、键盘左右方向键切帧、播放/暂停顺序推进帧。
- 用户在某帧选中 mask 后，如果切换到同一自动传播结果覆盖的其他帧，工作区应自动识别并选中目标帧中对应的传播 mask；匹配依据为传播结果回显到 mask metadata 的 seed 来源和传播链字段，而不是仅凭标签或颜色。
- 播放帧率使用项目 `parse_fps` 或 `original_fps`，限制在 1 到 30 FPS。 - 播放帧率使用项目 `parse_fps` 或 `original_fps`，限制在 1 到 30 FPS。
- 时间轴显示当前帧时间和总时长，时间基准使用项目 `parse_fps` 或 `original_fps`，格式为 `mm:ss.cc`。 - 时间轴显示当前帧时间和总时长，时间基准使用项目 `parse_fps` 或 `original_fps`，格式为 `mm:ss.cc`。
- 时间轴顶部播放进度条只表达当前播放位置；其下方的视频处理进度条表达处理状态：人工绘制或 AI 智能分割生成的帧显示红色竖线，自动传播生成的帧显示蓝色区段，最近自动传播处理过的片段叠加不同色系的横向渐变条，片段内部随时间从深到浅，帮助识别最近处理范围；未处理背景使用中性灰以和标记保持明显区分。底部帧可视化栏中，人工/AI 标注帧缩略图边框为红色，自动传播/推理帧缩略图边框为蓝色，当前帧仍用青色外框高亮优先；如果同一帧既有人工/AI 标注又有自动传播结果，红色人工/AI 标注框优先保留，自动传播状态只作为蓝色内描边或次级提示；如果当前帧同时是人工/AI 标注帧，则显示青色外框加红色内描边，外层选中框和内层标注框顺序不能交换。 - 时间轴顶部播放进度条只表达当前播放位置；其下方的视频处理进度条表达处理状态：人工绘制或 AI 智能分割生成的帧显示红色竖线，自动传播生成的帧显示蓝色区段，最近自动传播处理过的片段叠加不同色系的横向渐变条，片段内部随时间从深到浅，帮助识别最近处理范围；未处理背景使用中性灰以和标记保持明显区分。底部帧可视化栏中，人工/AI 标注帧缩略图边框为红色，自动传播/推理帧缩略图边框为蓝色，当前帧仍用青色外框高亮优先；如果同一帧既有人工/AI 标注又有自动传播结果，红色人工/AI 标注框优先保留，自动传播状态只作为蓝色内描边或次级提示；如果当前帧同时是人工/AI 标注帧，则显示青色外框加红色内描边，外层选中框和内层标注框顺序不能交换。
@@ -96,7 +97,7 @@
- AI 页面参数开关展示文案使用“局部专注模式（自动裁剪无锚区域）”和“严格除杂模式（自动清理干涉点）”；这是 UI 可读性文案，不改变 `cropMode`、`autoDeleteBg` 或后端 `options` 字段。 - AI 页面参数开关展示文案使用“局部专注模式（自动裁剪无锚区域）”和“严格除杂模式（自动清理干涉点）”；这是 UI 可读性文案，不改变 `cropMode`、`autoDeleteBg` 或后端 `options` 字段。
- AI 页面生成的 SAM 2.1 mask 会写入全局 `masks`，自动同步到当前项目帧，并写入全局 `selectedMaskIds`；右侧语义分类树可以直接给新生成 mask 换标签。 - AI 页面生成的 SAM 2.1 mask 会写入全局 `masks`，自动同步到当前项目帧，并写入全局 `selectedMaskIds`；右侧语义分类树可以直接给新生成 mask 换标签。
- AI 页“清空全体锚点”只清空本页提示点和本页生成的候选 mask，不删除工作区已有 mask。 - AI 页“清空全体锚点”只清空本页提示点和本页生成的候选 mask，不删除工作区已有 mask。
- AI 页面“推送至工作区编辑”会切回工作区并把工具切到“调整多边形”，保留当前选中的 AI mask 以便继续编辑轮廓和归档保存。 - AI 页面“推送至工作区编辑”会切回工作区并把工具切到“调整多边形”，保留当前选中的 AI mask 和当前帧视角，以便继续编辑轮廓和归档保存；如果 AI 操作发生在非第一帧，回到工作区后不得强制跳回第一帧。
- 工作区加载后端已保存标注时，必须保留当前项目帧里尚未保存的 AI/手工 draft mask，避免 AI 页推送到工作区的候选 mask 被异步回显流程覆盖。 - 工作区加载后端已保存标注时，必须保留当前项目帧里尚未保存的 AI/手工 draft mask，避免 AI 页推送到工作区的候选 mask 被异步回显流程覆盖。
- 语义文本提示 `semantic` 当前被后端禁用并返回 400。 - 语义文本提示 `semantic` 当前被后端禁用并返回 400。
- SAM 3 源码和历史测试保留，但不属于当前产品可用功能；前端不再展示 SAM 3 入口，后端 registry 不暴露 `sam3`。 - SAM 3 源码和历史测试保留，但不属于当前产品可用功能；前端不再展示 SAM 3 入口，后端 registry 不暴露 `sam3`。
@@ -107,8 +108,8 @@
- 前端会把多个 seed 或双向范围拆成 `steps`，通过 `POST /api/ai/propagate/task` 创建 `propagate_masks` 后台任务，避免长 HTTP 请求卡在浏览器侧，同时避免并发抢占 GPU。 - 前端会把多个 seed 或双向范围拆成 `steps`，通过 `POST /api/ai/propagate/task` 创建 `propagate_masks` 后台任务，避免长 HTTP 请求卡在浏览器侧，同时避免并发抢占 GPU。
- `POST /api/ai/propagate` 作为单 seed 同步兼容接口保留；`POST /api/ai/propagate/task` 是工作区自动传播使用的任务接口。两者当前支持四个 SAM 2.1 变体；兼容 `model=sam2` 并归一化为 tiny。SAM 2.1 使用官方 `SAM2VideoPredictor.add_new_mask()` 和 `propagate_in_video()`。 - `POST /api/ai/propagate` 作为单 seed 同步兼容接口保留；`POST /api/ai/propagate/task` 是工作区自动传播使用的任务接口。两者当前支持四个 SAM 2.1 变体；兼容 `model=sam2` 并归一化为 tiny。SAM 2.1 使用官方 `SAM2VideoPredictor.add_new_mask()` 和 `propagate_in_video()`。
- 自动传播任务写入 `processing_tasks`，前端轮询 `GET /api/tasks/{task_id}` 显示进度并刷新标注；Dashboard 也能看到该任务，任务可取消和重试。 - 自动传播任务写入 `processing_tasks`，前端轮询 `GET /api/tasks/{task_id}` 显示进度并刷新标注；Dashboard 也能看到该任务，任务可取消和重试。
- 传播结果会写入后续帧 `annotations`，`mask_data.source` 标记为 `<model_id>_propagation`，并保留 label、color、class 元数据、seed 来源 id、seed 签名和传播方向。 - 传播结果会写入后续帧 `annotations`，`mask_data.source` 标记为 `<model_id>_propagation`，并保留 label、color、class 元数据、seed 来源 id、seed 签名、传播方向和 `geometry_smoothing` 边缘平滑参数。
- 自动传播任务必须避免重复叠加：同一目标帧段内，同一参考 seed、同一权重、同一方向且所有目标帧已有未变化结果时，worker 直接跳过；同一参考 seed 已变化、目标帧段只部分覆盖或用户改用其他 SAM 2.1 权重时，worker 先删除本次目标帧段内对应旧自动传播标注，再保存新传播结果；对早期只记录前端临时 `source_mask_id` 的旧传播结果，worker 会按传播方向和语义信息做兼容清理。未编辑的自动传播结果再次作为参考 seed 时，会继承原始 `propagation_seed_signature` 以避免重复传播；被编辑后的传播结果只保留 lineage，不继承旧签名，以便触发删除旧结果并重新传播。 - 自动传播任务必须避免重复叠加：同一目标帧段内，同一参考 seed、同一权重、同一方向、同一平滑参数且所有目标帧已有未变化结果时，worker 直接跳过；同一参考 seed 已变化、目标帧段只部分覆盖、用户改用其他 SAM 2.1 权重或修改平滑参数时，worker 先删除本次目标帧段内对应旧自动传播标注，再保存新传播结果；对早期只记录前端临时 `source_mask_id` 的旧传播结果，worker 会按传播方向和语义信息做兼容清理。用户在自动传播链中间帧人工新增或修改同一物体 mask 后重新向前/向后传播时，即使新 seed 缺少旧传播链 source id，也要按语义信息和目标帧空间重叠清理旧传播结果后再写入新结果；写入前清理不受旧结果 `propagation_direction` 限制，因此当前帧向前传播时也会替换原先由更早帧向后传播出来的旧 mask，避免同一物体新旧 mask 堆叠。未编辑的自动传播结果再次作为参考 seed 时，会继承原始 `propagation_seed_signature` 以避免重复传播；被编辑后的传播结果只保留 lineage，不继承旧签名，以便触发删除旧结果并重新传播。带 `geometry_smoothing` 的 seed 在 forward/backward 两个方向都会用同一参数平滑保存结果。
- AI 页面会对未放置点提示、后端错误和返回 0 个 mask 的情况显示明确反馈。 - AI 页面会对未放置点提示、后端错误和返回 0 个 mask 的情况显示明确反馈。
- AI 参数支持 `crop_to_prompt`、`auto_filter_background` 和 `min_score`；点/框 prompt 可以裁剪局部区域推理并回映射结果，背景过滤会移除低分结果和包含负向点的 polygon。 - AI 参数支持 `crop_to_prompt`、`auto_filter_background` 和 `min_score`；点/框 prompt 可以裁剪局部区域推理并回映射结果，背景过滤会移除低分结果和包含负向点的 polygon。
- 后端返回 `polygons` 和 `scores`。 - 后端返回 `polygons` 和 `scores`。
@@ -145,7 +146,9 @@
- 用户可以选择具体分类；新 AI mask 会记录 `classId`、`className`、`classZIndex`，并在保存时写入 `mask_data.class`。 - 用户可以选择具体分类；新 AI mask 会记录 `classId`、`className`、`classZIndex`，并在保存时写入 `mask_data.class`。
- 如果 Canvas 当前已经选中一个或多个 mask，点击语义分类树会把这些 mask 的 `label`、`color` 和 class 元数据改为该分类；已保存 mask 会进入 `dirty` 状态，归档保存时更新后端。 - 如果 Canvas 当前已经选中一个或多个 mask，点击语义分类树会把这些 mask 的 `label`、`color` 和 class 元数据改为该分类；已保存 mask 会进入 `dirty` 状态，归档保存时更新后端。
- 添加自定义分类需要先选择模板，保存时调用 `PATCH /api/templates/{id}` 并同步全局模板 store。 - 添加自定义分类需要先选择模板，保存时调用 `PATCH /api/templates/{id}` 并同步全局模板 store。
- 选中 mask 后，置信度、拓扑锚点和重新提取拓扑锚点按钮调用 `POST /api/ai/analyze-mask`，不再显示固定占位值。 - “特定目标实例属性追踪”下方显示当前选中 mask 的 `className/label`，不显示全局 active class 的旧值。
- 选中 mask 后，拓扑锚点和重新提取拓扑锚点按钮调用 `POST /api/ai/analyze-mask`，不再显示固定占位值；前端不再展示“后端模型置信度”条目。
- 选中 mask 后，右侧实例属性面板提供“边缘平滑强度”和“应用边缘平滑”；应用时调用 `POST /api/ai/smooth-mask`，后端返回平滑后的 polygon、bbox、area 和拓扑锚点，前端将 mask 标记为 dirty/draft，用户仍需通过结构化归档保存落库。
## R10 Dashboard 与 WebSocket ## R10 Dashboard 与 WebSocket

29
doc/08-current-design-freeze.md
View File

@@ -106,16 +106,17 @@
2. 若无帧但项目有 `video_path`，显示“尚未生成帧”的状态提示，不自动触发 `parseMedia()`。 2. 若无帧但项目有 `video_path`，显示“尚未生成帧”的状态提示，不自动触发 `parseMedia()`。
3. 帧数据映射为 store `Frame[]`，包含 `timestampMs` 和 `sourceFrameNumber`，供时间轴和后续视频传播使用。 3. 帧数据映射为 store `Frame[]`，包含 `timestampMs` 和 `sourceFrameNumber`，供时间轴和后续视频传播使用。
4. 工作区调用 `GET /api/ai/annotations` 回显已保存标注时，会替换当前项目帧中的已保存 mask，但保留没有 `annotationId` 的未保存 draft mask；这保证 AI 页推送到工作区的候选 mask 不会被异步回显覆盖，并会在合并完成后恢复仍然存在的已选 mask id。 4. 工作区调用 `GET /api/ai/annotations` 回显已保存标注时，会替换当前项目帧中的已保存 mask，但保留没有 `annotationId` 的未保存 draft mask；这保证 AI 页推送到工作区的候选 mask 不会被异步回显覆盖，并会在合并完成后恢复仍然存在的已选 mask id。
5. `CanvasArea` 会把全局 `selectedMaskIds` 中仍存在于当前帧的 id 同步回本地选区，避免帧初始化时的临时清空覆盖 AI 页推送过来的选中态。 5. `VideoWorkspace` 加载项目帧时会优先按当前选中 mask 的 `frameId` 和当前打开帧 id 恢复 `currentFrameIndex`；只有没有可恢复帧时才回到第一帧，避免 AI 页在非第一帧推送回工作区时视角被重置。
6. `CanvasArea` 根据容器和帧尺寸按 86% 适配比例计算初始 scale/position，使底图默认居中且尽量大，但保留画布边距；滚轮缩放和拖拽平移仍由用户后续控制。 6. `CanvasArea` 会把全局 `selectedMaskIds` 中仍存在于当前帧的 id 同步回本地选区，避免帧初始化时的临时清空覆盖 AI 页推送过来的选中态；如果切换到另一帧时原 id 不存在，但目标帧存在同一自动传播链的结果，前端会用 `source_annotation_id`、`source_mask_id` 和 `propagation_seed_key` 匹配对应传播 mask 并自动选中。
7. `FrameTimeline` 顶部播放进度条显示当前播放位置；其下方视频处理进度条根据 `Mask.metadata.source` / `propagated_from_frame_id` 计算自动传播帧并显示蓝色区段，对人工绘制或 AI 智能分割等非传播 mask 帧显示红色竖线。普通状态下，视频处理进度条可点击跳转到对应帧，红色人工/AI 标注帧和蓝色自动传播帧标识本身也可点击跳转。处理条未处理背景使用中性灰，和红色/蓝色标记保持明显区分。`VideoWorkspace` 会记录当前会话最近 8 次成功处理过的自动传播范围，并通过 `propagationHistory` 传给 `FrameTimeline`；时间轴会把这些片段叠加为不同色系的横向渐变条，片段内按视频时间从深到浅，较早片段降低透明度。底部缩略图导航轴对非当前帧使用红色边框标识人工/AI 标注帧，使用蓝色边框标识自动传播/推理帧；如果同一帧同时存在人工/AI 标注和自动传播结果，红色人工/AI 标注边框优先保留，自动传播状态只作为蓝色内描边。当前帧使用青色外框高亮优先，若当前帧同时是人工/AI 标注帧，则以青色外框加红色内描边同时表达两个状态，外层当前帧框和内层人工/AI 框的顺序固定。工作区进入自动传播或清空片段遮罩范围选择模式时，播放进度条和视频处理进度条显示 amber 覆盖层，并可点击/拖拽设置处理起止帧。 7. `CanvasArea` 根据容器和帧尺寸按 86% 适配比例计算初始 scale/position，使底图默认居中且尽量大，但保留画布边距；滚轮缩放和拖拽平移仍由用户后续控制。
8. 当前帧传入 `CanvasArea`。 8. `FrameTimeline` 顶部播放进度条显示当前播放位置；其下方视频处理进度条根据 `Mask.metadata.source` / `propagated_from_frame_id` 计算自动传播帧并显示蓝色区段，对人工绘制或 AI 智能分割等非传播 mask 帧显示红色竖线。普通状态下，视频处理进度条可点击跳转到对应帧，红色人工/AI 标注帧和蓝色自动传播帧标识本身也可点击跳转。处理条未处理背景使用中性灰，和红色/蓝色标记保持明显区分。`VideoWorkspace` 会记录当前会话最近 8 次成功处理过的自动传播范围，并通过 `propagationHistory` 传给 `FrameTimeline`；时间轴会把这些片段叠加为不同色系的横向渐变条，片段内按视频时间从深到浅，较早片段降低透明度。底部缩略图导航轴对非当前帧使用红色边框标识人工/AI 标注帧，使用蓝色边框标识自动传播/推理帧；如果同一帧同时存在人工/AI 标注和自动传播结果，红色人工/AI 标注边框优先保留，自动传播状态只作为蓝色内描边。当前帧使用青色外框高亮优先，若当前帧同时是人工/AI 标注帧，则以青色外框加红色内描边同时表达两个状态，外层当前帧框和内层人工/AI 框的顺序固定。工作区进入自动传播或清空片段遮罩范围选择模式时，播放进度条和视频处理进度条显示 amber 覆盖层，并可点击/拖拽设置处理起止帧。
9. 工作区顶栏短状态文本会在空闲状态下自动消失；保存、导出、导入 GT 和传播任务运行中仍保留进度状态，无帧项目提示也会保留。 9. 当前帧传入 `CanvasArea`。
10. 左侧工具栏和右侧本体/语义分类面板使用 `seg-scrollbar` 定制纵向滚动条；默认滚动条 thumb 低透明度融入深色背景，hover/focus 时增强为青色提示，避免系统默认滚动条在工具区中过于突兀。左侧工具栏额外保留右侧滚动条槽位，按钮列仍按原 48px 布局，避免滚动条和图标抢空间。 10. 工作区顶栏短状态文本会在空闲状态下自动消失；保存、导出、导入 GT 和传播任务运行中仍保留进度状态，无帧项目提示也会保留。
11. 右侧面板不再显示“本体论与属性分类管理树”固定说明栏，直接展示实际可操作内容。 11. 左侧工具栏和右侧本体/语义分类面板使用 `seg-scrollbar` 定制纵向滚动条；默认滚动条 thumb 低透明度融入深色背景，hover/focus 时增强为青色提示，避免系统默认滚动条在工具区中过于突兀。左侧工具栏额外保留右侧滚动条槽位，按钮列仍按原 48px 布局，避免滚动条和图标抢空间。
12. 右侧“遮罩透明度”滑杆写入 Zustand `maskPreviewOpacity`，`CanvasArea` 用该值计算 mask group opacity；选中 mask 在基础透明度上加亮，方便保留选中反馈。 12. 右侧面板不再显示“本体论与属性分类管理树”固定说明栏，直接展示实际可操作内容。
13. Canvas 点击 mask 后，全局 `selectedMaskIds` 会同步到 `OntologyInspector`；本体面板按选中 mask 的 `classId`、`className/label` 和颜色匹配模板分类，自动设置 active class，并把分类按钮滚动/聚焦到可见区域。 13. 右侧“遮罩透明度”滑杆写入 Zustand `maskPreviewOpacity`，`CanvasArea` 用该值计算 mask group opacity；选中 mask 在基础透明度上加亮，方便保留选中反馈。
14. 工作区顶栏“清空片段遮罩”和“自动传播”共用时间轴范围选择交互；第一次点击“清空片段遮罩”会进入范围选择模式，按钮变为“确认清空”，用户可在播放进度条或视频处理进度条上点击/拖拽选择起止帧；确认执行时对范围内已保存 mask 调用 `DELETE /api/ai/annotations/{id}`，同时移除范围内本地 draft mask 和被清空的选区，范围外 mask 保持不变。 14. Canvas 点击 mask 后，全局 `selectedMaskIds` 会同步到 `OntologyInspector`；本体面板按选中 mask 的 `classId`、`className/label` 和颜色匹配模板分类，自动设置 active class，并把分类按钮滚动/聚焦到可见区域。
15. 工作区顶栏“清空片段遮罩”和“自动传播”共用时间轴范围选择交互；第一次点击“清空片段遮罩”会进入范围选择模式，按钮变为“确认清空”，用户可在播放进度条或视频处理进度条上点击/拖拽选择起止帧；确认执行时对范围内已保存 mask 调用 `DELETE /api/ai/annotations/{id}`，同时移除范围内本地 draft mask 和被清空的选区，范围外 mask 保持不变。
### AI 点/框推理 ### AI 点/框推理
@@ -150,14 +151,14 @@
2. 用户可以直接修改传播起始帧/结束帧数字框，并可通过工作区顶栏“传播权重”下拉独立选择本次传播使用的 SAM 2.1 tiny/small/base+/large 权重；该入口不提供 SAM2/SAM3 家族切换，默认跟随全局 AI 权重，用户手动选择后不再被 AI 页权重切换覆盖。 2. 用户可以直接修改传播起始帧/结束帧数字框，并可通过工作区顶栏“传播权重”下拉独立选择本次传播使用的 SAM 2.1 tiny/small/base+/large 权重；该入口不提供 SAM2/SAM3 家族切换，默认跟随全局 AI 权重，用户手动选择后不再被 AI 页权重切换覆盖。
3. `VideoWorkspace` 以当前参考帧为 seed，将起止帧拆成 `backward` 和/或 `forward` 两段；只包含当前帧时不传播。 3. `VideoWorkspace` 以当前参考帧为 seed，将起止帧拆成 `backward` 和/或 `forward` 两段；只包含当前帧时不传播。
4. `VideoWorkspace` 在提交传播前会先调用现有归档保存链路保存当前项目中的 draft/dirty mask，并重新读取 store 中的回显结果；参考帧 seed 因此优先携带稳定的后端 `source_annotation_id`，避免用前端临时 mask id 生成传播结果后，二次传播无法找到旧结果。 4. `VideoWorkspace` 在提交传播前会先调用现有归档保存链路保存当前项目中的 draft/dirty mask，并重新读取 store 中的回显结果；参考帧 seed 因此优先携带稳定的后端 `source_annotation_id`，避免用前端临时 mask id 生成传播结果后，二次传播无法找到旧结果。
5. `VideoWorkspace` 用 `buildAnnotationPayload()` 把每个 seed mask 转成 normalized polygon、bbox、label、color、class 元数据、`source_mask_id` 和可用时的 `source_annotation_id`；如果 seed mask 是未编辑的自动传播结果，会沿用其原始 `source_annotation_id/source_mask_id/propagation_seed_signature`，让后端把它识别为原传播链的同一个 seed；如果该传播结果被编辑并保存，更新 payload 只保留 lineage，不保留旧签名，使后端按“已修改”路径清理旧结果并重传。 5. `VideoWorkspace` 用 `buildAnnotationPayload()` 把每个 seed mask 转成 normalized polygon、bbox、label、color、class 元数据、`geometry_smoothing`、`source_mask_id` 和可用时的 `source_annotation_id`；如果 seed mask 是未编辑的自动传播结果，会沿用其原始 `source_annotation_id/source_mask_id/propagation_seed_signature`，让后端把它识别为原传播链的同一个 seed；如果该传播结果被编辑并保存，更新 payload 只保留 lineage，不保留旧签名，使后端按“已修改”路径清理旧结果并重传。
6. 前端把传播权重 id、每个 seed、每个方向组装成 `steps`，一次调用 `POST /api/ai/propagate/task`，`include_source=false`、`save_annotations=true`；接口先规范化/校验 `model` 字段中的权重 id，再创建 `processing_tasks.task_type=propagate_masks` 并投递 Celery，避免长 HTTP 请求阻塞前端等待。 6. 前端把传播权重 id、每个 seed、每个方向组装成 `steps`，一次调用 `POST /api/ai/propagate/task`，`include_source=false`、`save_annotations=true`；接口先规范化/校验 `model` 字段中的权重 id，再创建 `processing_tasks.task_type=propagate_masks` 并投递 Celery，避免长 HTTP 请求阻塞前端等待。
7. `VideoWorkspace` 记录返回的 `task_id`，轮询 `GET /api/tasks/{task_id}` 显示任务 message、步骤进度、已处理帧次和已保存区域数；任务运行期间提供取消传播按钮，调用通用 `POST /api/tasks/{task_id}/cancel`。 7. `VideoWorkspace` 记录返回的 `task_id`，轮询 `GET /api/tasks/{task_id}` 显示任务 message、步骤进度、已处理帧次和已保存区域数；任务运行期间提供取消传播按钮，调用通用 `POST /api/tasks/{task_id}/cancel`。
8. Celery worker 逐 step 顺序执行传播，避免多个视频 tracker 并发抢占 GPU；每个 step 开始/完成都会写入 `processing_tasks.progress/result/message` 并发布 Redis `seg:progress`，Dashboard 可同步显示。每个 step 开始前，worker 会在本次目标帧段内用 seed 来源 id、传播方向和 seed 签名查找旧传播标注：同权重、签名相同且目标帧都已有结果时跳过该 seed；签名不同、目标帧只部分覆盖或本次使用了其他 SAM 2.1 权重则先删除本次目标帧段内对应方向的旧自动传播标注，再执行新的 video predictor 传播。对旧版本只记录前端临时 `source_mask_id` 的传播标注，worker 会按 label/color/class 做兼容匹配，确保可被后续稳定 `source_annotation_id` 的传播替换。 8. Celery worker 逐 step 顺序执行传播，避免多个视频 tracker 并发抢占 GPU；每个 step 开始/完成都会写入 `processing_tasks.progress/result/message` 并发布 Redis `seg:progress`，Dashboard 可同步显示。每个 step 开始前，worker 会在本次目标帧段内用 seed 来源 id、传播方向和包含 `geometry_smoothing` 的 seed 签名查找旧传播标注：同权重、签名相同且目标帧都已有结果时跳过该 seed；签名不同、目标帧只部分覆盖、本次使用了其他 SAM 2.1 权重或平滑参数变化则先删除本次目标帧段内对应方向的旧自动传播标注，再执行新的 video predictor 传播。对旧版本只记录前端临时 `source_mask_id` 的传播标注，worker 会按 label/color/class 做兼容匹配，确保可被后续稳定 `source_annotation_id` 的传播替换；对中间帧人工新增的替代 seed，若缺少旧 source id，worker 仍会用语义信息识别候选旧传播结果，并在写入目标帧新 polygon 前用目标帧 bbox 重叠做二次确认和清理。写入前这层清理不限制旧结果方向，确保 backward 传播可覆盖早先 forward 传播留下的同物体旧 mask。
9. 后端按项目帧序列截取片段，下载对应帧到临时目录，并写成 `000000.jpg` 这类纯数字文件名；这是 `SAM2VideoPredictor` 对视频帧排序的要求，和项目库中持久化的 `frame_%06d.jpg` 对象名无关。 9. 后端按项目帧序列截取片段，下载对应帧到临时目录，并写成 `000000.jpg` 这类纯数字文件名；这是 `SAM2VideoPredictor` 对视频帧排序的要求，和项目库中持久化的 `frame_%06d.jpg` 对象名无关。
10. `model` 为任一 SAM 2.1 权重变体时，`sam2_engine` 使用对应 checkpoint/config 加载 `SAM2VideoPredictor.add_new_mask()` 注入 seed mask，再用 `propagate_in_video()` 传播；`model=sam2` 会在入队时规范化为 tiny，任务 payload/result 会保留规范化后的权重 id；单个 SAM2 video predictor 调用内部暂不提供逐帧流式进度。 10. `model` 为任一 SAM 2.1 权重变体时，`sam2_engine` 使用对应 checkpoint/config 加载 `SAM2VideoPredictor.add_new_mask()` 注入 seed mask，再用 `propagate_in_video()` 传播；`model=sam2` 会在入队时规范化为 tiny，任务 payload/result 会保留规范化后的权重 id；单个 SAM2 video predictor 调用内部暂不提供逐帧流式进度。
11. `model=sam3` 当前不支持；SAM 3 video tracker 代码保留但没有接入产品路径。 11. `model=sam3` 当前不支持；SAM 3 video tracker 代码保留但没有接入产品路径。
12. 后端把传播返回的 normalized polygon 保存为后续帧 `Annotation`，跳过源帧，`mask_data.source` 记录权重传播来源，同时写入 `propagation_seed_key`、`propagation_seed_signature`、`propagation_direction`、`source_annotation_id` 和 `source_mask_id` 供后续幂等传播判断。 12. 后端把传播返回的 normalized polygon 保存为后续帧 `Annotation`，跳过源帧；如果 seed 带 `geometry_smoothing`，保存前会用同一 Chaikin 平滑参数处理 forward/backward 两个方向的结果。`mask_data.source` 记录权重传播来源，同时写入 `propagation_seed_key`、`propagation_seed_signature`、`propagation_direction`、`source_annotation_id`、`source_mask_id` 和 `geometry_smoothing` 供后续幂等传播判断。
13. 前端轮询到已创建区域后刷新 `GET /api/ai/annotations` 并回显新标注；任务结束后如果后端返回 0 个新区域，工作区会明确提示没有生成新的 mask，若是未改变 seed 被跳过则提示未改变 mask 已跳过。处理过帧次大于 0 的成功任务会追加一条本地传播历史片段，用于视频处理进度条显示最近传播范围；`annotationToMask()` 会保留传播来源 metadata，供时间轴视频处理进度条显示蓝色传播区段。 13. 前端轮询到已创建区域后刷新 `GET /api/ai/annotations` 并回显新标注；任务结束后如果后端返回 0 个新区域，工作区会明确提示没有生成新的 mask，若是未改变 seed 被跳过则提示未改变 mask 已跳过。处理过帧次大于 0 的成功任务会追加一条本地传播历史片段，用于视频处理进度条显示最近传播范围；`annotationToMask()` 会保留传播来源 metadata，供时间轴视频处理进度条显示蓝色传播区段。
### 手工绘制与历史栈 ### 手工绘制与历史栈
@@ -275,5 +276,5 @@
- 已保存标注支持通过“应用分类”、polygon 顶点拖动/删除、边中点插入、多 polygon 子区域编辑和区域合并/去除进入 dirty 状态并归档更新；选中整块 mask 可用 Delete/Backspace 删除并同步后端；复杂洞结构编辑尚未实现。 - 已保存标注支持通过“应用分类”、polygon 顶点拖动/删除、边中点插入、多 polygon 子区域编辑和区域合并/去除进入 dirty 状态并归档更新；选中整块 mask 可用 Delete/Backspace 删除并同步后端；复杂洞结构编辑尚未实现。
- SAM 3 文本语义分割已从当前产品路径中禁用；相关源码保留，恢复时需要重新接入前端入口、registry、状态接口和测试。 - SAM 3 文本语义分割已从当前产品路径中禁用；相关源码保留，恢复时需要重新接入前端入口、registry、状态接口和测试。
- 自定义分类通过 `PATCH /api/templates/{id}` 写入当前激活模板的 `mapping_rules.classes`。 - 自定义分类通过 `PATCH /api/templates/{id}` 写入当前激活模板的 `mapping_rules.classes`。
- 选中 mask 后，本体面板调用 `POST /api/ai/analyze-mask` 显示后端模型置信度、拓扑锚点数量、面积等属性；“重新提取拓扑锚点”会带 `extract_skeleton=true` 重新请求后端分析。 - 选中 mask 后，本体面板的“特定目标实例属性追踪”标题值来自当前 mask 的 `className/label`，不使用全局 active class；面板调用 `POST /api/ai/analyze-mask` 显示拓扑锚点数量等属性，“重新提取拓扑锚点”会带 `extract_skeleton=true` 重新请求后端分析；“边缘平滑强度/应用边缘平滑”调用 `POST /api/ai/smooth-mask`，由后端按 Chaikin smoothing 返回新 polygon 并把 `geometry_smoothing` 写回 mask metadata。前端不再展示“后端模型置信度”。
- GT mask 导入已完成多类别像素值拆分、contour、distance transform seed point 和前端 seed point 拖拽编辑；骨架提取、HDBSCAN 聚类和模板自动映射尚未实现。 - GT mask 导入已完成多类别像素值拆分、contour、distance transform seed point 和前端 seed point 拖拽编辑；骨架提取、HDBSCAN 聚类和模板自动映射尚未实现。

14
doc/09-test-plan.md
View File

@@ -17,12 +17,12 @@
| R1 登录与会话 | `src/components/Login.test.tsx`, `backend/tests/test_auth.py` | 成功登录、失败提示、后端 401 | | R1 登录与会话 | `src/components/Login.test.tsx`, `backend/tests/test_auth.py` | 成功登录、失败提示、后端 401 |
| R2 项目管理 | `src/lib/api.test.ts`, `src/components/ProjectLibrary.test.tsx`, `backend/tests/test_projects.py` | 前端字段映射、PATCH 更新、项目卡片删除、DELETE 契约、后端 CRUD、删除级联、帧列表 | | R2 项目管理 | `src/lib/api.test.ts`, `src/components/ProjectLibrary.test.tsx`, `backend/tests/test_projects.py` | 前端字段映射、PATCH 更新、项目卡片删除、DELETE 契约、后端 CRUD、删除级联、帧列表 |
| R3 媒体上传与拆帧 | `src/components/ProjectLibrary.test.tsx`, `src/components/TransientNotice.test.tsx`, `backend/tests/test_media.py`, `backend/tests/test_tasks.py` | 视频导入不自动拆帧、显式生成帧 FPS 选择、项目卡片显示目标 parse_fps 而非原视频 FPS、扩展名校验、自动建项目、关联项目、创建异步任务、非阻塞自动消失操作提示、标准帧序列参数、帧时间戳/源帧号、任务序列元数据、worker 注册帧、取消任务、重试任务、取消后 worker 停止 | | R3 媒体上传与拆帧 | `src/components/ProjectLibrary.test.tsx`, `src/components/TransientNotice.test.tsx`, `backend/tests/test_media.py`, `backend/tests/test_tasks.py` | 视频导入不自动拆帧、显式生成帧 FPS 选择、项目卡片显示目标 parse_fps 而非原视频 FPS、扩展名校验、自动建项目、关联项目、创建异步任务、非阻塞自动消失操作提示、标准帧序列参数、帧时间戳/源帧号、任务序列元数据、worker 注册帧、取消任务、重试任务、取消后 worker 停止 |
| R4 工作区与帧浏览 | `src/components/VideoWorkspace.test.tsx`, `src/components/FrameTimeline.test.tsx` | 加载帧、无帧项目不自动解析并提示生成帧、工作区短状态自动消失、工作区/AI 画布底图默认居中且保留边距、工作区 mask 透明度、回显已保存标注时保留本地未保存 draft mask、清空片段遮罩进入时间轴范围选择并按选区批量清空、传播权重下拉深色可读配色、缩略图/range/视频处理进度条、视频处理进度条点击跳帧、人工/AI 标注帧红色竖线和标识点击跳帧、自动传播帧蓝色区段和标识点击跳帧、最近自动传播历史片段不同色系渐变显示、缩略图红/蓝边框、人工/AI 标注帧叠加传播状态时红框优先保留并显示蓝色内描边、当前人工/AI 标注帧青色外框加红色内描边、普通状态不显示传播范围黄色选区、播放进度条和视频处理进度条选择传播/清空范围、当前帧由播放进度条末端和缩略图青色高亮表达/左右方向键切帧、播放、按项目 FPS 显示当前/总时长 | | R4 工作区与帧浏览 | `src/components/VideoWorkspace.test.tsx`, `src/components/FrameTimeline.test.tsx` | 加载帧、无帧项目不自动解析并提示生成帧、工作区短状态自动消失、工作区/AI 画布底图默认居中且保留边距、工作区 mask 透明度、回显已保存标注时保留本地未保存 draft mask、选中 mask 后跨帧自动跟随同一传播链结果、清空片段遮罩进入时间轴范围选择并按选区批量清空、传播权重下拉深色可读配色、缩略图/range/视频处理进度条、视频处理进度条点击跳帧、人工/AI 标注帧红色竖线和标识点击跳帧、自动传播帧蓝色区段和标识点击跳帧、最近自动传播历史片段不同色系渐变显示、缩略图红/蓝边框、人工/AI 标注帧叠加传播状态时红框优先保留并显示蓝色内描边、当前人工/AI 标注帧青色外框加红色内描边、普通状态不显示传播范围黄色选区、播放进度条和视频处理进度条选择传播/清空范围、当前帧由播放进度条末端和缩略图青色高亮表达/左右方向键切帧、播放、按项目 FPS 显示当前/总时长 |
| R5 工具栏 | `src/components/ToolsPalette.test.tsx`, `src/components/CanvasArea.test.tsx`, `src/components/VideoWorkspace.test.tsx`, `src/store/useStore.test.ts` | 工具切换、工具栏紧凑垂直布局和高度不足时滚动、工具栏低对比滚动条、工具栏外扩滚动条槽位不挤占按钮列、调整多边形工具、AI 跳转、矩形/圆/线/点/多边形手工 mask 绘制、点工具在已有 mask 上落点、多边形 Enter/首节点闭合、上下文提示提示 Enter/Esc/首节点闭合且数秒后自动隐藏、polygon 顶点直接拖动/删除、顶点拖拽结束不改变 Canvas 视口、边中点插点、双击边界按位置插点、整块 mask 删除、区域合并/去除、布尔选择主区域/扣除区域视觉区分和选择顺序提示、内含去除 hole 渲染、合并模式隐藏编辑手柄、工作区 SAM 提示点点击删除且不冒泡新增点、工作区顶栏撤销/重做按钮、撤销/重做快捷键和输入框快捷键跳过、撤销/重做历史栈 | | R5 工具栏 | `src/components/ToolsPalette.test.tsx`, `src/components/CanvasArea.test.tsx`, `src/components/VideoWorkspace.test.tsx`, `src/store/useStore.test.ts` | 工具切换、工具栏紧凑垂直布局和高度不足时滚动、工具栏低对比滚动条、工具栏外扩滚动条槽位不挤占按钮列、调整多边形工具、AI 跳转、矩形/圆/线/点/多边形手工 mask 绘制、点工具在已有 mask 上落点、多边形 Enter/首节点闭合、上下文提示提示 Enter/Esc/首节点闭合且数秒后自动隐藏、polygon 顶点直接拖动/删除、顶点拖拽结束不改变 Canvas 视口、边中点插点、双击边界按位置插点、整块 mask 删除、区域合并/去除、布尔选择主区域/扣除区域视觉区分和选择顺序提示、内含去除 hole 渲染、合并模式隐藏编辑手柄、工作区 SAM 提示点点击删除且不冒泡新增点、工作区顶栏撤销/重做按钮、撤销/重做快捷键和输入框快捷键跳过、撤销/重做历史栈 |
| 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 页推送到工作区编辑保留选择、SAM 2.1 视频以当前参考帧全部 mask 和起止帧范围自动传播、传播前自动保存 draft/dirty seed mask、传播前独立选择 SAM 2.1 tiny/small/base+/large 权重、自动传播创建 Celery 任务、传播入队权重 id 规范化/拒绝不支持 id、传播 seed 来源 id/签名 metadata、未编辑传播结果作为 seed 时继承原始签名并跳过重复传播、已编辑传播结果保留 lineage 但重算签名并清理旧结果、换权重传播先清理旧权重结果、旧临时 seed id 传播结果兼容清理、传播中轮询任务进度、传播任务取消/重试、传播来源 metadata 回显、空提示/空结果反馈、GPU/SAM2.1 状态、AI 参数 options、局部裁剪推理、背景过滤、状态徽标、坐标归一化、正负点 labels、polygons 转 path、后端 fake registry | | 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 页推送到工作区编辑保留选择和当前帧、SAM 2.1 视频以当前参考帧全部 mask 和起止帧范围自动传播、传播前自动保存 draft/dirty seed mask、传播前独立选择 SAM 2.1 tiny/small/base+/large 权重、自动传播创建 Celery 任务、传播入队权重 id 规范化/拒绝不支持 id、传播 seed 来源 id/签名/边缘平滑 metadata、未编辑传播结果作为 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` | 保存标注、保存后用后端 saved annotation 替换已提交 draft、加载回显、更新 dirty 标注、清空删除已保存标注、GT mask 多类别导入、seed point 回显/归一化、项目不存在、帧不存在 | | R7 标注保存 | `src/components/VideoWorkspace.test.tsx`, `src/components/CanvasArea.test.tsx`, `src/lib/api.test.ts`, `backend/tests/test_ai.py` | 保存标注、保存后用后端 saved annotation 替换已提交 draft、加载回显、更新 dirty 标注、清空删除已保存标注、GT mask 多类别导入、seed point 回显/归一化、项目不存在、帧不存在 |
| R8 模板库 | `src/components/TemplateRegistry.test.tsx`, `src/components/TransientNotice.test.tsx`, `src/lib/api.test.ts`, `backend/tests/test_templates.py` | 前端模板加载/新建/编辑/删除、JSON 分类导入、JSON/保存错误非阻塞提示、mapping_rules 解包/打包、后端模板 CRUD | | R8 模板库 | `src/components/TemplateRegistry.test.tsx`, `src/components/TransientNotice.test.tsx`, `src/lib/api.test.ts`, `backend/tests/test_templates.py` | 前端模板加载/新建/编辑/删除、JSON 分类导入、JSON/保存错误非阻塞提示、mapping_rules 解包/打包、后端模板 CRUD |
| R9 本体检查面板 | `src/components/OntologyInspector.test.tsx`, `src/components/CanvasArea.test.tsx`, `src/store/useStore.test.ts`, `backend/tests/test_ai.py` | 模板选择、面板标题简化、面板低对比滚动条、工作区遮罩透明度滑杆、分类展示、具体分类选择、Canvas 选区同步、点击 Canvas mask 后自动聚焦对应语义分类、点击分类给已选 mask 换标签并移动到前端渲染最上层、自定义分类 PATCH 后端模板、选中 mask 后端属性分析、重新提取拓扑锚点 | | R9 本体检查面板 | `src/components/OntologyInspector.test.tsx`, `src/components/CanvasArea.test.tsx`, `src/store/useStore.test.ts`, `backend/tests/test_ai.py` | 模板选择、面板标题简化、面板低对比滚动条、工作区遮罩透明度滑杆、分类展示、具体分类选择、Canvas 选区同步、点击 Canvas mask 后自动聚焦对应语义分类、点击分类给已选 mask 换标签并移动到前端渲染最上层、自定义分类 PATCH 后端模板、目标实例标题显示当前 mask label、隐藏后端模型置信度、选中 mask 后端拓扑属性分析、重新提取拓扑锚点、边缘平滑强度调用后端并将 mask 标记为 dirty |
| R10 Dashboard 与 WebSocket | `src/lib/api.test.ts`, `src/lib/websocket.test.ts`, `src/components/Dashboard.test.tsx`, `backend/tests/test_dashboard.py`, `backend/tests/test_main.py`, `backend/tests/test_progress_events.py`, `backend/tests/test_tasks.py` | 后端概览接口、任务表驱动进度区、最近完成任务保留显示、任务取消/重试/详情、cancelled 事件、Redis 进度事件 payload/发布、地址推导、消息订阅、连接状态回调、队列更新、heartbeat | | R10 Dashboard 与 WebSocket | `src/lib/api.test.ts`, `src/lib/websocket.test.ts`, `src/components/Dashboard.test.tsx`, `backend/tests/test_dashboard.py`, `backend/tests/test_main.py`, `backend/tests/test_progress_events.py`, `backend/tests/test_tasks.py` | 后端概览接口、任务表驱动进度区、最近完成任务保留显示、任务取消/重试/详情、cancelled 事件、Redis 进度事件 payload/发布、地址推导、消息订阅、连接状态回调、队列更新、heartbeat |
| R11 导出 | `src/components/VideoWorkspace.test.tsx`, `src/lib/api.test.ts`, `backend/tests/test_export.py` | COCO/PNG 按钮下载、导出前自动保存、导出路径、JSON 结构、mask ZIP、zIndex 语义融合 | | R11 导出 | `src/components/VideoWorkspace.test.tsx`, `src/lib/api.test.ts`, `backend/tests/test_export.py` | COCO/PNG 按钮下载、导出前自动保存、导出路径、JSON 结构、mask ZIP、zIndex 语义融合 |
| R12 配置 | `src/lib/config.test.ts` | env 优先、hostname 推导、WS 推导 | | R12 配置 | `src/lib/config.test.ts` | env 优先、hostname 推导、WS 推导 |
@@ -35,13 +35,13 @@
| R1 | 登录页、默认开发凭证、token 写入、失败提示、后端 401 | `Login.test.tsx`, `test_auth.py` | 已覆盖 | | R1 | 登录页、默认开发凭证、token 写入、失败提示、后端 401 | `Login.test.tsx`, `test_auth.py` | 已覆盖 |
| R2 | 项目列表/创建/选择、视频导入、DICOM 导入、后端项目和帧 CRUD | `ProjectLibrary.test.tsx`, `api.test.ts`, `test_projects.py` | 已覆盖 | | R2 | 项目列表/创建/选择、视频导入、DICOM 导入、后端项目和帧 CRUD | `ProjectLibrary.test.tsx`, `api.test.ts`, `test_projects.py` | 已覆盖 |
| R3 | 文件类型校验、自动/指定项目上传、视频导入与生成帧分离、显式 FPS 生成帧、项目卡片 FPS 徽标显示 `parse_fps`、视频/DICOM 拆帧任务、非阻塞自动消失操作提示、`parse_fps/max_frames/target_width`、标准帧序列 metadata、任务查询、取消、重试、worker 取消停止 | `ProjectLibrary.test.tsx`, `TransientNotice.test.tsx`, `api.test.ts`, `test_media.py`, `test_tasks.py` | 已覆盖 | | R3 | 文件类型校验、自动/指定项目上传、视频导入与生成帧分离、显式 FPS 生成帧、项目卡片 FPS 徽标显示 `parse_fps`、视频/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 透明度、清空片段遮罩进入时间轴范围选择并按选区批量清空、传播权重下拉深色可读配色、缩略图/range/视频处理进度条、视频处理进度条点击跳帧、人工/AI 标注帧红色竖线和标识点击跳帧、自动传播帧蓝色区段和标识点击跳帧、最近自动传播历史片段不同色系渐变显示、缩略图红/蓝边框、人工/AI 标注帧叠加传播状态时红框优先保留并显示蓝色内描边、当前人工/AI 标注帧青色外框加红色内描边、普通状态不显示传播范围黄色选区、播放进度条/视频处理进度条拖拽选择传播/清空范围、Canvas/AI 画布拖拽平移回写 position state、当前帧由播放进度条末端和缩略图青色高亮表达/左右方向键切帧、播放、按 FPS 显示时间 | `VideoWorkspace.test.tsx`, `FrameTimeline.test.tsx`, `CanvasArea.test.tsx`, `AISegmentation.test.tsx` | 已覆盖 | | R4 | 工作区加载帧、无帧项目不自动解析、工作区短状态自动消失、后端标注回显保留本地未保存 draft mask、Canvas/AI 底图居中适配且保留边距、工作区 mask 透明度、选中 mask 后跨帧自动跟随同一传播链结果、清空片段遮罩进入时间轴范围选择并按选区批量清空、传播权重下拉深色可读配色、缩略图/range/视频处理进度条、视频处理进度条点击跳帧、人工/AI 标注帧红色竖线和标识点击跳帧、自动传播帧蓝色区段和标识点击跳帧、最近自动传播历史片段不同色系渐变显示、缩略图红/蓝边框、人工/AI 标注帧叠加传播状态时红框优先保留并显示蓝色内描边、当前人工/AI 标注帧青色外框加红色内描边、普通状态不显示传播范围黄色选区、播放进度条/视频处理进度条拖拽选择传播/清空范围、Canvas/AI 画布拖拽平移回写 position state、当前帧由播放进度条末端和缩略图青色高亮表达/左右方向键切帧、播放、按 FPS 显示时间 | `VideoWorkspace.test.tsx`, `FrameTimeline.test.tsx`, `CanvasArea.test.tsx`, `AISegmentation.test.tsx` | 已覆盖 |
| R5 | 工具切换、工具栏紧凑滚动布局、低对比滚动条、外扩滚动条槽位、调整多边形入口、AI 跳转、矩形/圆/线/点/多边形绘制、已有 mask 上继续绘制、多边形和布尔工具上下文提示、Canvas 上下文提示数秒后自动隐藏 | `ToolsPalette.test.tsx`, `CanvasArea.test.tsx` | 已覆盖 | | R5 | 工具切换、工具栏紧凑滚动布局、低对比滚动条、外扩滚动条槽位、调整多边形入口、AI 跳转、矩形/圆/线/点/多边形绘制、已有 mask 上继续绘制、多边形和布尔工具上下文提示、Canvas 上下文提示数秒后自动隐藏 | `ToolsPalette.test.tsx`, `CanvasArea.test.tsx` | 已覆盖 |
| R5 | 顶点直接拖动编辑、顶点拖拽结束不改变 Canvas 视口、边中点插点、双击边界按位置插点、顶点删除、整块删除、工作区 SAM 提示点删除优先级、工作区顶栏撤销/重做按钮、撤销/重做快捷键、区域合并、区域去除、布尔选择主区域黄色实线/扣除区域红色虚线、布尔选择顺序提示、hole even-odd 渲染 | `CanvasArea.test.tsx`, `VideoWorkspace.test.tsx`, `useStore.test.ts` | 已覆盖 | | R5 | 顶点直接拖动编辑、顶点拖拽结束不改变 Canvas 视口、边中点插点、双击边界按位置插点、顶点删除、整块删除、工作区 SAM 提示点删除优先级、工作区顶栏撤销/重做按钮、撤销/重做快捷键、区域合并、区域去除、布尔选择主区域黄色实线/扣除区域红色虚线、布尔选择顺序提示、hole even-odd 渲染 | `CanvasArea.test.tsx`, `VideoWorkspace.test.tsx`, `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 页推送到工作区编辑保留选择、SAM 2.1 视频按参考帧全部 mask 和范围自动传播、传播前自动保存 draft/dirty seed mask、传播前独立选择 SAM 2.1 tiny/small/base+/large 权重、自动传播 Celery 任务入队、传播入队权重 id 规范化/拒绝不支持 id、传播 seed 来源 id/签名 metadata、未编辑传播结果作为 seed 时继承原始签名并跳过重复传播、已编辑传播结果保留 lineage 但重算签名并清理旧结果、换权重传播先清理旧权重结果、旧临时 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` | 已覆盖 | | 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 页推送到工作区编辑保留选择和当前帧、SAM 2.1 视频按参考帧全部 mask 和范围自动传播、传播前自动保存 draft/dirty seed mask、传播前独立选择 SAM 2.1 tiny/small/base+/large 权重、自动传播 Celery 任务入队、传播入队权重 id 规范化/拒绝不支持 id、传播 seed 来源 id/签名/边缘平滑 metadata、未编辑传播结果作为 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 | 保存、保存后替换已提交 draft、查询、更新、删除标注、工作区回显、清空已保存标注、GT mask 导入和 seed point 回写 | `VideoWorkspace.test.tsx`, `CanvasArea.test.tsx`, `api.test.ts`, `test_ai.py` | 已覆盖 | | R7 | 保存、保存后替换已提交 draft、查询、更新、删除标注、工作区回显、清空已保存标注、GT mask 导入和 seed point 回写 | `VideoWorkspace.test.tsx`, `CanvasArea.test.tsx`, `api.test.ts`, `test_ai.py` | 已覆盖 |
| R8 | 模板加载、新建、编辑、删除、JSON 分类导入、JSON/保存错误非阻塞提示、mapping_rules 映射、后端 CRUD | `TemplateRegistry.test.tsx`, `TransientNotice.test.tsx`, `api.test.ts`, `test_templates.py` | 已覆盖 | | R8 | 模板加载、新建、编辑、删除、JSON 分类导入、JSON/保存错误非阻塞提示、mapping_rules 映射、后端 CRUD | `TemplateRegistry.test.tsx`, `TransientNotice.test.tsx`, `api.test.ts`, `test_templates.py` | 已覆盖 |
| R9 | 模板选择、面板标题简化、工作区遮罩透明度滑杆、分类展示、分类选择、点击 mask 自动聚焦对应分类、已选 mask 换标签并置顶显示、自定义分类写入后端模板、后端属性分析、占位状态 | `OntologyInspector.test.tsx`, `CanvasArea.test.tsx`, `useStore.test.ts`, `test_ai.py` | 已覆盖 | | R9 | 模板选择、面板标题简化、工作区遮罩透明度滑杆、分类展示、分类选择、点击 mask 自动聚焦对应分类、已选 mask 换标签并置顶显示、自定义分类写入后端模板、目标实例标题显示当前 mask label、隐藏后端模型置信度、后端拓扑属性分析、边缘平滑强度应用、占位状态 | `OntologyInspector.test.tsx`, `CanvasArea.test.tsx`, `useStore.test.ts`, `test_ai.py` | 已覆盖 |
| R10 | Dashboard 概览、任务进度区、最近完成任务保留显示、活动日志、WebSocket progress/complete/error/status/cancelled、取消/重试/详情、连接状态回调、heartbeat | `Dashboard.test.tsx`, `websocket.test.ts`, `test_dashboard.py`, `test_main.py`, `test_progress_events.py`, `test_tasks.py` | 已覆盖 | | R10 | Dashboard 概览、任务进度区、最近完成任务保留显示、活动日志、WebSocket progress/complete/error/status/cancelled、取消/重试/详情、连接状态回调、heartbeat | `Dashboard.test.tsx`, `websocket.test.ts`, `test_dashboard.py`, `test_main.py`, `test_progress_events.py`, `test_tasks.py` | 已覆盖 |
| R11 | COCO/PNG ZIP 导出、导出前保存、路径和 JSON/ZIP 结构、zIndex 融合 | `VideoWorkspace.test.tsx`, `api.test.ts`, `test_export.py` | 已覆盖 | | R11 | COCO/PNG ZIP 导出、导出前保存、路径和 JSON/ZIP 结构、zIndex 融合 | `VideoWorkspace.test.tsx`, `api.test.ts`, `test_export.py` | 已覆盖 |
| R12 | API/WS 地址 env 优先和 hostname 推导 | `config.test.ts` | 已覆盖 | | R12 | API/WS 地址 env 优先和 hostname 推导 | `config.test.ts` | 已覆盖 |
@@ -61,7 +61,7 @@
- R4/R6：补充时间轴传播范围选择测试，验证点击“自动传播”后可在播放进度条或视频处理进度条上拖拽回填起止帧，再提交后台传播任务。 - R4/R6：补充时间轴传播范围选择测试，验证点击“自动传播”后可在播放进度条或视频处理进度条上拖拽回填起止帧，再提交后台传播任务。
- R4/R6：补充视频处理进度条传播历史测试，验证多次自动传播后会按不同色系渐变片段显示最近处理范围。 - R4/R6：补充视频处理进度条传播历史测试，验证多次自动传播后会按不同色系渐变片段显示最近处理范围。
- R6/R10：补充 `queuePropagationTask()`、`POST /api/ai/propagate/task`、传播 Celery runner 和传播任务重试测试，验证工作区自动传播不再依赖长 HTTP 请求，并验证传给 `SAM2VideoPredictor` 的临时帧文件名是纯数字序列。 - R6/R10：补充 `queuePropagationTask()`、`POST /api/ai/propagate/task`、传播 Celery runner 和传播任务重试测试，验证工作区自动传播不再依赖长 HTTP 请求，并验证传给 `SAM2VideoPredictor` 的临时帧文件名是纯数字序列。
- R6：补充传播去重回归测试，验证前端传播前会先保存 draft seed mask 并用稳定 `source_annotation_id` 入队；后端在 seed 来源由前端临时 id 迁移到后端 annotation id、用户换用其他 SAM 2.1 权重、未编辑传播结果再次作为 seed、已编辑传播结果重新作为 seed 时，会分别跳过或清理旧传播标注再保存新结果。 - R6：补充传播去重回归测试，验证前端传播前会先保存 draft seed mask 并用稳定 `source_annotation_id` 入队；后端在 seed 来源由前端临时 id 迁移到后端 annotation id、用户换用其他 SAM 2.1 权重、未编辑传播结果再次作为 seed、已编辑传播结果重新作为 seed、中间帧人工新增替代 seed 时，会分别跳过或清理旧传播标注再保存新结果。
- R6：`backend/tests/test_sam3_engine.py` 已标记跳过，仅作为历史保留实现的参考测试，不计入当前产品功能覆盖。 - R6：`backend/tests/test_sam3_engine.py` 已标记跳过，仅作为历史保留实现的参考测试，不计入当前产品功能覆盖。
- R3：补充 `parseMedia()` 查询参数和后端拆帧任务 payload 测试，验证 `parse_fps`、`max_frames`、`target_width` 会进入任务。 - R3：补充 `parseMedia()` 查询参数和后端拆帧任务 payload 测试，验证 `parse_fps`、`max_frames`、`target_width` 会进入任务。
- R3：补充 worker 注册标准帧序列测试，验证帧 `timestamp_ms`、`source_frame_number` 和 `result.frame_sequence` 元数据。 - R3：补充 worker 注册标准帧序列测试，验证帧 `timestamp_ms`、`source_frame_number` 和 `result.frame_sequence` 元数据。

68
doc/10-installation.md
View File

@@ -330,6 +330,73 @@ PostgreSQL -> Redis -> MinIO -> FastAPI -> Celery worker -> 前端
- MinIO 数据目录 `/home/wkmgc/minio_data` - MinIO 数据目录 `/home/wkmgc/minio_data`
- 脚本里包含本机 sudo 密码写法，迁移机器时应移除或改成安全的 systemd/service 管理方式 - 脚本里包含本机 sudo 密码写法，迁移机器时应移除或改成安全的 systemd/service 管理方式
### 10.1 开发重启速查
本地开发时不要靠猜。不同服务的热更新行为如下：
| 改动类型 | 是否需要重启 | 原因 |
|----------|--------------|------|
| 前端 `src/`、`server.ts` | 通常不需要 | `npm run dev` 使用 Vite/tsx，前端会热更新 |
| 前端依赖、`.env`、`vite.config.ts` | 需要重启前端 | 依赖和环境变量只在进程启动时读取 |
| FastAPI 路由/普通后端代码 | 需要重启后端 | 开发重启脚本用独立后台进程运行后端；显式重启可以保证接口和运行态一致 |
| `backend/.env`、模型路径、依赖安装 | 需要重启后端 | 配置和依赖在进程启动时生效 |
| Celery 任务、拆帧、自动传播、SAM runner | 必须重启 Celery worker | worker 不是 `uvicorn --reload` 的子进程，不会自动加载代码改动 |
推荐使用项目根目录的开发重启脚本：
```bash
cd /home/wkmgc/Desktop/Seg_Server
./restart_dev_services.sh
```
该脚本会：
```text
检查 PostgreSQL/Redis/MinIO -> 停止旧 FastAPI/Celery/前端 -> 用独立后台进程启动 FastAPI/Celery/前端 -> 检查 3000/8000
```
脚本通过 `setsid` 启动应用层服务，脚本退出后服务会继续运行；pid 文件默认位于 `/tmp/seg_server_*.pid`，日志默认位于 `/tmp/seg_server_*.log`。
默认日志：
```text
/tmp/seg_server_fastapi.log
/tmp/seg_server_celery.log
/tmp/seg_server_frontend.log
/tmp/seg_server_minio.log
```
如果只想手动重启应用层服务，可以使用：
```bash
cd /home/wkmgc/Desktop/Seg_Server
# 停止旧进程
pkill -f "uvicorn main:app" || true
pkill -f "celery -A celery_app:celery_app worker" || true
pkill -f "/home/wkmgc/Desktop/Seg_Server/node_modules/.bin/tsx server.ts" || true
pkill -f "npm run dev" || true
# 启动后端和 worker
cd /home/wkmgc/Desktop/Seg_Server/backend
setsid ~/miniconda3/bin/conda run -n seg_server uvicorn main:app --host 0.0.0.0 --port 8000 \
> /tmp/seg_server_fastapi.log 2>&1 < /dev/null &
setsid ~/miniconda3/bin/conda run -n seg_server celery -A celery_app:celery_app worker --loglevel=info --concurrency=1 \
> /tmp/seg_server_celery.log 2>&1 < /dev/null &
# 启动前端
cd /home/wkmgc/Desktop/Seg_Server
setsid npm run dev > /tmp/seg_server_frontend.log 2>&1 < /dev/null &
```
验收：
```bash
curl http://localhost:8000/health
curl -I http://localhost:3000
ps -ef | grep -E "(uvicorn main:app|celery -A celery_app:celery_app worker|tsx server.ts)" | grep -v grep
```
--- ---
## 11. 生产构建方式 ## 11. 生产构建方式
@@ -487,4 +554,3 @@ curl http://localhost:8000/api/ai/models/status
### 不需要 SAM 3 ### 不需要 SAM 3
当前版本不用 SAM 3。不要为了正常部署执行 `backend/setup_sam3_env.sh`，也不要在项目里保存 Hugging Face token。 当前版本不用 SAM 3。不要为了正常部署执行 `backend/setup_sam3_env.sh`，也不要在项目里保存 Hugging Face token。

160
restart_dev_services.sh Executable file
View File

@@ -0,0 +1,160 @@
#!/usr/bin/env bash
# Restart local development app services for Seg_Server.
# Infra services (PostgreSQL/Redis/MinIO) are checked and started if possible.
set -euo pipefail
PROJECT_DIR="${PROJECT_DIR:-/home/wkmgc/Desktop/Seg_Server}"
CONDA_ENV="${CONDA_ENV:-seg_server}"
CONDA_BIN="${CONDA_BIN:-${HOME}/miniconda3/bin/conda}"
BACKEND_PORT="${BACKEND_PORT:-8000}"
FRONTEND_PORT="${FRONTEND_PORT:-3000}"
LOG_DIR="${LOG_DIR:-/tmp}"
PID_DIR="${PID_DIR:-/tmp}"
FASTAPI_LOG="${LOG_DIR}/seg_server_fastapi.log"
CELERY_LOG="${LOG_DIR}/seg_server_celery.log"
FRONTEND_LOG="${LOG_DIR}/seg_server_frontend.log"
MINIO_LOG="${LOG_DIR}/seg_server_minio.log"
FASTAPI_PID="${PID_DIR}/seg_server_fastapi.pid"
CELERY_PID="${PID_DIR}/seg_server_celery.pid"
FRONTEND_PID="${PID_DIR}/seg_server_frontend.pid"
MINIO_PID="${PID_DIR}/seg_server_minio.pid"
echo "== Seg_Server development restart =="
echo "Project: ${PROJECT_DIR}"
start_system_service() {
local service_name="$1"
if command -v systemctl >/dev/null 2>&1; then
sudo systemctl start "${service_name}"
else
echo "systemctl not found; please start ${service_name} manually." >&2
return 1
fi
}
ensure_conda() {
if [[ -x "${CONDA_BIN}" ]]; then
return
fi
if command -v conda >/dev/null 2>&1; then
CONDA_BIN="$(command -v conda)"
return
fi
echo "conda not found; set CONDA_BIN to the conda executable." >&2
exit 1
}
stop_pidfile_group() {
local pidfile="$1"
if [[ ! -f "${pidfile}" ]]; then
return
fi
local pid
pid="$(cat "${pidfile}" 2>/dev/null || true)"
rm -f "${pidfile}"
if [[ -z "${pid}" ]]; then
return
fi
if kill -0 "${pid}" >/dev/null 2>&1; then
kill -- "-${pid}" >/dev/null 2>&1 || kill "${pid}" >/dev/null 2>&1 || true
fi
}
start_detached() {
local name="$1"
local workdir="$2"
local pidfile="$3"
local logfile="$4"
shift 4
mkdir -p "$(dirname "${pidfile}")" "$(dirname "${logfile}")"
: >"${logfile}"
setsid bash -c 'cd "$1" || exit 1; shift; exec "$@"' bash "${workdir}" "$@" >"${logfile}" 2>&1 < /dev/null &
local pid=$!
echo "${pid}" >"${pidfile}"
echo " ${name} pid ${pid}"
}
wait_for_http() {
local label="$1"
local url="$2"
local logfile="$3"
local method="${4:-GET}"
for _ in $(seq 1 30); do
if [[ "${method}" == "HEAD" ]]; then
curl -fsS -I "${url}" >/dev/null 2>&1 && echo " ${label} ready" && return
else
curl -fsS "${url}" >/dev/null 2>&1 && echo " ${label} ready" && return
fi
sleep 1
done
echo "${label} did not become ready: ${url}" >&2
echo "Last log lines from ${logfile}:" >&2
tail -n 80 "${logfile}" >&2 || true
exit 1
}
ensure_conda
echo "[1/6] Checking PostgreSQL..."
if ! pg_isready -q; then
start_system_service postgresql
fi
pg_isready >/dev/null
echo " PostgreSQL ready"
echo "[2/6] Checking Redis..."
if ! redis-cli ping >/dev/null 2>&1; then
start_system_service redis-server
fi
redis-cli ping >/dev/null
echo " Redis ready"
echo "[3/6] Checking MinIO..."
if ! curl -fsS http://localhost:9000/minio/health/live >/dev/null 2>&1; then
stop_pidfile_group "${MINIO_PID}"
start_detached "MinIO" "${PROJECT_DIR}" "${MINIO_PID}" "${MINIO_LOG}" minio server "${HOME}/minio_data" --console-address :9001
fi
wait_for_http "MinIO" "http://localhost:9000/minio/health/live" "${MINIO_LOG}"
echo "[4/6] Stopping app services..."
stop_pidfile_group "${FASTAPI_PID}"
stop_pidfile_group "${CELERY_PID}"
stop_pidfile_group "${FRONTEND_PID}"
pkill -f "uvicorn main:app --host .*--port ${BACKEND_PORT}" || true
pkill -f "uvicorn main:app" || true
pkill -f "conda run -n ${CONDA_ENV} uvicorn main:app" || true
pkill -f "celery -A celery_app:celery_app worker" || true
pkill -f "conda run -n ${CONDA_ENV} celery -A celery_app:celery_app worker" || true
pkill -f "${PROJECT_DIR}/node_modules/.bin/tsx server.ts" || true
pkill -f "npm run dev" || true
sleep 1
echo "[5/6] Starting backend and worker..."
start_detached "FastAPI" "${PROJECT_DIR}/backend" "${FASTAPI_PID}" "${FASTAPI_LOG}" \
"${CONDA_BIN}" run -n "${CONDA_ENV}" uvicorn main:app --host 0.0.0.0 --port "${BACKEND_PORT}"
start_detached "Celery" "${PROJECT_DIR}/backend" "${CELERY_PID}" "${CELERY_LOG}" \
"${CONDA_BIN}" run -n "${CONDA_ENV}" celery -A celery_app:celery_app worker --loglevel=info --concurrency=1
echo "[6/6] Starting frontend..."
start_detached "Frontend" "${PROJECT_DIR}" "${FRONTEND_PID}" "${FRONTEND_LOG}" npm run dev
wait_for_http "FastAPI" "http://127.0.0.1:${BACKEND_PORT}/health" "${FASTAPI_LOG}"
wait_for_http "Frontend" "http://127.0.0.1:${FRONTEND_PORT}" "${FRONTEND_LOG}" HEAD
echo "== Restart complete =="
echo "Frontend: http://localhost:${FRONTEND_PORT}"
echo "Backend: http://localhost:${BACKEND_PORT}/docs"
echo "PID files:"
echo " FastAPI: ${FASTAPI_PID}"
echo " Celery: ${CELERY_PID}"
echo " Frontend: ${FRONTEND_PID}"
echo "Logs:"
echo " FastAPI: ${FASTAPI_LOG}"
echo " Celery: ${CELERY_LOG}"
echo " Frontend: ${FRONTEND_LOG}"
echo " MinIO: ${MINIO_LOG}"

85
src/components/CanvasArea.test.tsx
View File

@@ -381,6 +381,91 @@ describe('CanvasArea', () => {
.filter((element) => element.getAttribute('data-fill') === '#ffffff')).toHaveLength(3); .filter((element) => element.getAttribute('data-fill') === '#ffffff')).toHaveLength(3);
}); });
it('selects the linked propagated mask when switching from the seed frame', async () => {
const propagatedFrame = { ...frame, id: 'frame-2', index: 1, url: '/frame-2.jpg' };
useStore.setState({
selectedMaskIds: ['annotation-7'],
masks: [
{
id: 'annotation-7',
annotationId: '7',
frameId: 'frame-1',
pathData: 'M 0 0 L 10 0 L 10 10 Z',
label: '胆囊',
color: '#facc15',
segmentation: [[0, 0, 10, 0, 10, 10]],
},
{
id: 'annotation-20',
annotationId: '20',
frameId: 'frame-2',
pathData: 'M 1 1 L 11 1 L 11 11 Z',
label: '胆囊',
color: '#facc15',
segmentation: [[1, 1, 11, 1, 11, 11]],
metadata: {
source: 'sam2.1_hiera_tiny_propagation',
source_annotation_id: 7,
source_mask_id: 'annotation-7',
propagation_seed_key: 'annotation:7',
},
},
],
});
const { rerender } = render(<CanvasArea activeTool="edit_polygon" frame={frame} />);
rerender(<CanvasArea activeTool="edit_polygon" frame={propagatedFrame} />);
await waitFor(() => expect(useStore.getState().selectedMaskIds).toEqual(['annotation-20']));
expect(screen.getByText('当前图层: 胆囊 #20')).toBeInTheDocument();
});
it('keeps following the same propagation chain between propagated frames', async () => {
const propagatedFrame = { ...frame, id: 'frame-2', index: 1, url: '/frame-2.jpg' };
const laterPropagatedFrame = { ...frame, id: 'frame-3', index: 2, url: '/frame-3.jpg' };
useStore.setState({
selectedMaskIds: ['annotation-20'],
masks: [
{
id: 'annotation-20',
annotationId: '20',
frameId: 'frame-2',
pathData: 'M 1 1 L 11 1 L 11 11 Z',
label: '胆囊',
color: '#facc15',
segmentation: [[1, 1, 11, 1, 11, 11]],
metadata: {
source: 'sam2.1_hiera_tiny_propagation',
source_annotation_id: 7,
source_mask_id: 'annotation-7',
propagation_seed_key: 'annotation:7',
},
},
{
id: 'annotation-21',
annotationId: '21',
frameId: 'frame-3',
pathData: 'M 2 2 L 12 2 L 12 12 Z',
label: '胆囊',
color: '#facc15',
segmentation: [[2, 2, 12, 2, 12, 12]],
metadata: {
source: 'sam2.1_hiera_tiny_propagation',
source_annotation_id: 7,
source_mask_id: 'annotation-7',
propagation_seed_key: 'annotation:7',
},
},
],
});
const { rerender } = render(<CanvasArea activeTool="edit_polygon" frame={propagatedFrame} />);
rerender(<CanvasArea activeTool="edit_polygon" frame={laterPropagatedFrame} />);
await waitFor(() => expect(useStore.getState().selectedMaskIds).toEqual(['annotation-21']));
expect(screen.getByText('当前图层: 胆囊 #21')).toBeInTheDocument();
});
it('renders imported GT seed points for editable point regions', () => { it('renders imported GT seed points for editable point regions', () => {
useStore.setState({ useStore.setState({
masks: [ masks: [

99
src/components/CanvasArea.tsx
View File

@@ -31,6 +31,72 @@ function clamp(value: number, min: number, max: number): number {
return Math.min(Math.max(value, min), max); return Math.min(Math.max(value, min), max);
} }
function metadataNumber(value: unknown): number | null {
const parsed = Number(value);
return Number.isFinite(parsed) && parsed > 0 ? parsed : null;
}
function propagationSourceMaskTokens(value: unknown): string[] {
if (typeof value !== 'string' || value.length === 0) return [];
const tokens = [`mask:${value}`];
const annotationMatch = value.match(/^annotation-(\d+)$/);
if (annotationMatch) {
tokens.push(`annotation:${annotationMatch[1]}`);
}
return tokens;
}
function isPropagationMask(mask: Mask): boolean {
const metadata = mask.metadata || {};
const source = typeof metadata.source === 'string' ? metadata.source : '';
return source.includes('_propagation')
|| metadata.propagated_from_frame_id !== undefined
|| metadata.propagation_seed_key !== undefined
|| metadata.source_annotation_id !== undefined
|| metadata.source_mask_id !== undefined;
}
function propagationLineageTokens(mask: Mask): Set<string> {
const metadata = mask.metadata || {};
const tokens = new Set<string>([`mask:${mask.id}`]);
if (mask.annotationId) {
tokens.add(`annotation:${mask.annotationId}`);
}
const sourceAnnotationId = metadataNumber(metadata.source_annotation_id);
if (sourceAnnotationId !== null) {
tokens.add(`annotation:${sourceAnnotationId}`);
}
propagationSourceMaskTokens(metadata.source_mask_id).forEach((token) => tokens.add(token));
if (typeof metadata.propagation_seed_key === 'string' && metadata.propagation_seed_key.length > 0) {
tokens.add(`seed-key:${metadata.propagation_seed_key}`);
}
return tokens;
}
function findLinkedMasksOnFrame(selectedIds: string[], allMasks: Mask[], targetFrameId?: string): string[] {
if (!targetFrameId || selectedIds.length === 0) return [];
const selectedMasks = selectedIds
.map((id) => allMasks.find((mask) => mask.id === id))
.filter((mask): mask is Mask => Boolean(mask));
if (selectedMasks.length === 0) return [];
const selectedTokens = new Set<string>();
const selectedHasPropagation = selectedMasks.some(isPropagationMask);
selectedMasks.forEach((mask) => {
propagationLineageTokens(mask).forEach((token) => selectedTokens.add(token));
});
return allMasks
.filter((mask) => String(mask.frameId) === String(targetFrameId))
.filter((mask) => {
const candidateHasPropagation = isPropagationMask(mask);
if (!selectedHasPropagation && !candidateHasPropagation) return false;
const candidateTokens = propagationLineageTokens(mask);
return [...candidateTokens].some((token) => selectedTokens.has(token));
})
.map((mask) => mask.id);
}
function polygonPath(points: CanvasPoint[]): string { function polygonPath(points: CanvasPoint[]): string {
if (points.length === 0) return ''; if (points.length === 0) return '';
return points return points
@@ -425,11 +491,19 @@ export function CanvasArea({ activeTool, frame, onClearMasks, onDeleteMaskAnnota
useEffect(() => { useEffect(() => {
if (previousFrameIdRef.current === frame?.id) return; if (previousFrameIdRef.current === frame?.id) return;
previousFrameIdRef.current = frame?.id; previousFrameIdRef.current = frame?.id;
const linkedMaskIds = findLinkedMasksOnFrame(useStore.getState().selectedMaskIds, masks, frame?.id);
if (linkedMaskIds.length > 0) {
setSelectedMaskId(linkedMaskIds[0]);
setSelectedMaskIds(linkedMaskIds);
setGlobalSelectedMaskIds(linkedMaskIds);
} else {
setSelectedMaskId(null); setSelectedMaskId(null);
setSelectedMaskIds([]); setSelectedMaskIds([]);
setGlobalSelectedMaskIds([]);
}
setSelectedPolygonIndex(0); setSelectedPolygonIndex(0);
setSelectedVertexIndex(null); setSelectedVertexIndex(null);
}, [frame?.id]); }, [frame?.id, masks, setGlobalSelectedMaskIds]);
useEffect(() => { useEffect(() => {
setPoints([]); setPoints([]);
@@ -439,16 +513,23 @@ export function CanvasArea({ activeTool, frame, onClearMasks, onDeleteMaskAnnota
useEffect(() => { useEffect(() => {
const currentGlobalSelectedIds = useStore.getState().selectedMaskIds; const currentGlobalSelectedIds = useStore.getState().selectedMaskIds;
const validLocalSelectedIds = selectedMaskIds.filter((id) => (
frameMasks.some((mask) => mask.id === id)
));
if (selectedMaskIds.length > 0 && validLocalSelectedIds.length === 0) {
return;
}
if (selectedMaskIds.length === 0) { if (selectedMaskIds.length === 0) {
const validGlobalSelectedIds = currentGlobalSelectedIds.filter((id) => ( const validGlobalSelectedIds = currentGlobalSelectedIds.filter((id) => (
frameMasks.some((mask) => mask.id === id) frameMasks.some((mask) => mask.id === id)
)); ));
if (validGlobalSelectedIds.length > 0) return; if (validGlobalSelectedIds.length > 0) return;
} }
const isSameSelection = currentGlobalSelectedIds.length === selectedMaskIds.length const nextSelectedMaskIds = selectedMaskIds.length > 0 ? validLocalSelectedIds : selectedMaskIds;
&& currentGlobalSelectedIds.every((id, index) => id === selectedMaskIds[index]); const isSameSelection = currentGlobalSelectedIds.length === nextSelectedMaskIds.length
&& currentGlobalSelectedIds.every((id, index) => id === nextSelectedMaskIds[index]);
if (!isSameSelection) { if (!isSameSelection) {
setGlobalSelectedMaskIds(selectedMaskIds); setGlobalSelectedMaskIds(nextSelectedMaskIds);
} }
}, [frameMasks, selectedMaskIds, setGlobalSelectedMaskIds]); }, [frameMasks, selectedMaskIds, setGlobalSelectedMaskIds]);
@@ -468,12 +549,20 @@ export function CanvasArea({ activeTool, frame, onClearMasks, onDeleteMaskAnnota
} }
} }
if (selectedMaskId && !frameMasks.some((mask) => mask.id === selectedMaskId)) { if (selectedMaskId && !frameMasks.some((mask) => mask.id === selectedMaskId)) {
const linkedMaskIds = findLinkedMasksOnFrame([selectedMaskId, ...selectedMaskIds], masks, frame?.id);
if (linkedMaskIds.length > 0) {
setSelectedMaskId(linkedMaskIds[0]);
setSelectedMaskIds(linkedMaskIds);
setGlobalSelectedMaskIds(linkedMaskIds);
} else {
setSelectedMaskId(null); setSelectedMaskId(null);
setSelectedMaskIds([]); setSelectedMaskIds([]);
setGlobalSelectedMaskIds([]);
}
setSelectedPolygonIndex(0); setSelectedPolygonIndex(0);
setSelectedVertexIndex(null); setSelectedVertexIndex(null);
} }
}, [frameMasks, selectedMaskId]); }, [frame?.id, frameMasks, masks, selectedMaskId, selectedMaskIds, setGlobalSelectedMaskIds]);
const handleWheel = (e: any) => { const handleWheel = (e: any) => {
e.evt.preventDefault(); e.evt.preventDefault();

62
src/components/OntologyInspector.test.tsx
View File

@@ -6,11 +6,13 @@ import { OntologyInspector } from './OntologyInspector';
const apiMock = vi.hoisted(() => ({ const apiMock = vi.hoisted(() => ({
analyzeMask: vi.fn(), analyzeMask: vi.fn(),
smoothMaskGeometry: vi.fn(),
updateTemplate: vi.fn(), updateTemplate: vi.fn(),
})); }));
vi.mock('../lib/api', () => ({ vi.mock('../lib/api', () => ({
analyzeMask: apiMock.analyzeMask, analyzeMask: apiMock.analyzeMask,
smoothMaskGeometry: apiMock.smoothMaskGeometry,
updateTemplate: apiMock.updateTemplate, updateTemplate: apiMock.updateTemplate,
})); }));
@@ -28,6 +30,17 @@ describe('OntologyInspector', () => {
source: 'sam2.1_hiera_tiny', source: 'sam2.1_hiera_tiny',
message: '已读取后端几何属性', message: '已读取后端几何属性',
}); });
apiMock.smoothMaskGeometry.mockResolvedValue({
polygons: [[[0.12, 0.12], [0.28, 0.12], [0.28, 0.28], [0.12, 0.28]]],
pathData: 'M 12 12 L 28 12 L 28 28 L 12 28 Z',
segmentation: [[12, 12, 28, 12, 28, 28, 12, 28]],
bbox: [12, 12, 16, 16],
area: 256,
topology_anchor_count: 4,
topology_anchors: [],
smoothing: { strength: 35, method: 'chaikin' },
message: '已应用边缘平滑强度 35',
});
useStore.setState({ useStore.setState({
templates: [ templates: [
{ {
@@ -177,6 +190,8 @@ describe('OntologyInspector', () => {
it('loads selected mask properties from the backend analyzer', async () => { it('loads selected mask properties from the backend analyzer', async () => {
useStore.setState({ useStore.setState({
frames: [{ id: 'frame-1', projectId: 'p1', index: 0, url: '/1.jpg', width: 100, height: 100 }], frames: [{ id: 'frame-1', projectId: 'p1', index: 0, url: '/1.jpg', width: 100, height: 100 }],
activeClass: { id: 'c3', name: '肿瘤', color: '#f97316', zIndex: 30 },
activeClassId: 'c3',
selectedMaskIds: ['m1'], selectedMaskIds: ['m1'],
masks: [ masks: [
{ {
@@ -193,7 +208,11 @@ describe('OntologyInspector', () => {
render(<OntologyInspector />); render(<OntologyInspector />);
expect(await screen.findByText('0.8200')).toBeInTheDocument(); expect(await screen.findByText('4 节点')).toBeInTheDocument();
expect(screen.getAllByText('胆囊')).toHaveLength(2);
expect(screen.queryByText('肿瘤')).not.toBeInTheDocument();
expect(screen.queryByText('后端模型置信度')).not.toBeInTheDocument();
expect(screen.queryByText('0.8200')).not.toBeInTheDocument();
expect(screen.getByText('4 节点')).toBeInTheDocument(); expect(screen.getByText('4 节点')).toBeInTheDocument();
fireEvent.click(screen.getByRole('button', { name: '重新提取拓扑锚点' })); fireEvent.click(screen.getByRole('button', { name: '重新提取拓扑锚点' }));
expect(apiMock.analyzeMask).toHaveBeenLastCalledWith( expect(apiMock.analyzeMask).toHaveBeenLastCalledWith(
@@ -202,4 +221,45 @@ describe('OntologyInspector', () => {
{ extractSkeleton: true }, { extractSkeleton: true },
); );
}); });
it('applies backend edge smoothing to the selected mask and marks it dirty', async () => {
useStore.setState({
frames: [{ id: 'frame-1', projectId: 'p1', index: 0, url: '/1.jpg', width: 100, height: 100 }],
selectedMaskIds: ['m1'],
masks: [
{
id: 'm1',
annotationId: '10',
frameId: 'frame-1',
pathData: 'M 10 10 L 30 10 L 30 30 Z',
label: '胆囊',
color: '#ff0000',
segmentation: [[10, 10, 30, 10, 30, 30]],
saveStatus: 'saved',
saved: true,
},
],
});
render(<OntologyInspector />);
fireEvent.change(screen.getByLabelText('边缘平滑强度'), { target: { value: '35' } });
fireEvent.click(screen.getByRole('button', { name: '应用边缘平滑' }));
await waitFor(() => expect(apiMock.smoothMaskGeometry).toHaveBeenCalledWith(
expect.objectContaining({ id: 'm1' }),
expect.objectContaining({ id: 'frame-1' }),
35,
));
await waitFor(() => expect(useStore.getState().masks[0]).toEqual(expect.objectContaining({
pathData: 'M 12 12 L 28 12 L 28 28 L 12 28 Z',
segmentation: [[12, 12, 28, 12, 28, 28, 12, 28]],
bbox: [12, 12, 16, 16],
area: 256,
saveStatus: 'dirty',
saved: false,
metadata: { geometry_smoothing: { strength: 35, method: 'chaikin' } },
})));
expect(screen.getByText('已应用边缘平滑强度 35，请保存后生效')).toBeInTheDocument();
});
}); });

102
src/components/OntologyInspector.tsx
View File

@@ -4,7 +4,7 @@ import { useStore } from '../store/useStore';
import type { TemplateClass } from '../store/useStore'; import type { TemplateClass } from '../store/useStore';
import { cn } from '../lib/utils'; import { cn } from '../lib/utils';
import { getActiveTemplate } from '../lib/templateSelection'; import { getActiveTemplate } from '../lib/templateSelection';
import { analyzeMask, updateTemplate, type MaskAnalysisResult } from '../lib/api'; import { analyzeMask, smoothMaskGeometry, updateTemplate, type MaskAnalysisResult } from '../lib/api';
export function OntologyInspector() { export function OntologyInspector() {
const templates = useStore((state) => state.templates); const templates = useStore((state) => state.templates);
@@ -30,13 +30,17 @@ export function OntologyInspector() {
const [maskAnalysis, setMaskAnalysis] = useState<MaskAnalysisResult | null>(null); const [maskAnalysis, setMaskAnalysis] = useState<MaskAnalysisResult | null>(null);
const [isAnalyzingMask, setIsAnalyzingMask] = useState(false); const [isAnalyzingMask, setIsAnalyzingMask] = useState(false);
const [analysisMessage, setAnalysisMessage] = useState(''); const [analysisMessage, setAnalysisMessage] = useState('');
const [smoothingStrength, setSmoothingStrength] = useState(0);
const [isSmoothingMask, setIsSmoothingMask] = useState(false);
const activeTemplate = getActiveTemplate(templates, activeTemplateId); const activeTemplate = getActiveTemplate(templates, activeTemplateId);
const templateClasses = activeTemplate?.classes || []; const templateClasses = activeTemplate?.classes || [];
const allClasses = [...templateClasses].sort((a, b) => b.zIndex - a.zIndex); const allClasses = [...templateClasses].sort((a, b) => b.zIndex - a.zIndex);
const selectedMask = masks.find((mask) => selectedMaskIds.includes(mask.id)) || null; const selectedMask = masks.find((mask) => selectedMaskIds.includes(mask.id)) || null;
const selectedMaskLabel = selectedMask?.className || selectedMask?.label || '未选择';
const currentFrame = frames[currentFrameIndex] || null; const currentFrame = frames[currentFrameIndex] || null;
const classButtonRefs = useRef(new Map<string, HTMLButtonElement>()); const classButtonRefs = useRef(new Map<string, HTMLButtonElement>());
const skipNextAutoAnalysisRef = useRef(false);
const selectedMaskClass = useMemo(() => { const selectedMaskClass = useMemo(() => {
if (!selectedMask) return null; if (!selectedMask) return null;
@@ -119,11 +123,68 @@ export function OntologyInspector() {
}; };
React.useEffect(() => { React.useEffect(() => {
if (skipNextAutoAnalysisRef.current) {
skipNextAutoAnalysisRef.current = false;
return;
}
void refreshMaskAnalysis(false); void refreshMaskAnalysis(false);
// selectedMask is intentionally tracked by id and geometry fields to avoid // selectedMask is intentionally tracked by id and geometry fields to avoid
// re-running analysis for unrelated store changes. // re-running analysis for unrelated store changes.
}, [selectedMask?.id, selectedMask?.segmentation, selectedMask?.points, currentFrame?.id]); }, [selectedMask?.id, selectedMask?.segmentation, selectedMask?.points, currentFrame?.id]);
React.useEffect(() => {
const smoothing = selectedMask?.metadata?.geometry_smoothing;
const strength = smoothing && typeof smoothing === 'object'
? Number((smoothing as Record<string, unknown>).strength)
: 0;
setSmoothingStrength(Number.isFinite(strength) ? Math.min(Math.max(strength, 0), 100) : 0);
}, [selectedMask?.id]);
const handleApplySmoothing = async () => {
if (!selectedMask || !currentFrame) {
setAnalysisMessage('请选择一个 mask 后再应用边缘平滑');
return;
}
setIsSmoothingMask(true);
setAnalysisMessage('');
try {
const result = await smoothMaskGeometry(selectedMask, currentFrame, smoothingStrength);
skipNextAutoAnalysisRef.current = true;
setMasks(masks.map((mask) => {
if (mask.id !== selectedMask.id) return mask;
return {
...mask,
pathData: result.pathData,
segmentation: result.segmentation,
bbox: result.bbox,
area: result.area,
metadata: {
...(mask.metadata || {}),
geometry_smoothing: result.smoothing,
},
saveStatus: mask.annotationId ? 'dirty' as const : 'draft' as const,
saved: mask.annotationId ? false : mask.saved,
};
}));
setMaskAnalysis({
confidence: null,
confidence_source: 'manual_or_imported',
topology_anchor_count: result.topology_anchor_count,
topology_anchors: result.topology_anchors,
area: result.area,
bbox: result.bbox,
source: selectedMask.metadata?.source as string | undefined,
message: result.message,
});
setAnalysisMessage(`${result.message}，请保存后生效`);
} catch (err) {
console.error('Mask smoothing failed:', err);
setAnalysisMessage('边缘平滑失败，请检查后端服务');
} finally {
setIsSmoothingMask(false);
}
};
const handleAddCustom = async () => { const handleAddCustom = async () => {
if (!newClassName.trim()) return; if (!newClassName.trim()) return;
if (!activeTemplate) { if (!activeTemplate) {
@@ -301,7 +362,7 @@ export function OntologyInspector() {
<div className="flex items-center gap-2 mb-3"> <div className="flex items-center gap-2 mb-3">
<Tag size={12} className="text-cyan-400" /> <Tag size={12} className="text-cyan-400" />
<span className="text-xs font-semibold text-gray-200"> <span className="text-xs font-semibold text-gray-200">
{activeClass?.name || activeTemplate?.name || '未选择'} {selectedMaskLabel}
</span> </span>
</div> </div>
<div className="space-y-3"> <div className="space-y-3">
@@ -309,22 +370,35 @@ export function OntologyInspector() {
<span className="text-[10px] text-gray-500 uppercase">当前选中区域:</span> <span className="text-[10px] text-gray-500 uppercase">当前选中区域:</span>
<span className="text-xs font-mono text-gray-300">{selectedMaskIds.length}</span> <span className="text-xs font-mono text-gray-300">{selectedMaskIds.length}</span>
</div> </div>
<div className="space-y-1">
<label className="text-[10px] text-gray-500 uppercase">后端模型置信度</label>
<div className="h-1.5 w-full bg-white/10 rounded-full overflow-hidden">
<div
className="h-full bg-green-500"
style={{ width: `${Math.round((maskAnalysis?.confidence ?? 0) * 100)}%` }}
/>
</div>
<div className="text-[10px] font-mono text-green-500 text-right">
{maskAnalysis?.confidence != null ? maskAnalysis.confidence.toFixed(4) : '无模型分数'}
</div>
</div>
<div className="flex items-center justify-between"> <div className="flex items-center justify-between">
<span className="text-[10px] text-gray-500 uppercase">后端拓扑锚点:</span> <span className="text-[10px] text-gray-500 uppercase">后端拓扑锚点:</span>
<span className="text-xs font-mono text-gray-300">{maskAnalysis?.topology_anchor_count ?? 0} 节点</span> <span className="text-xs font-mono text-gray-300">{maskAnalysis?.topology_anchor_count ?? 0} 节点</span>
</div> </div>
<div>
<div className="mb-2 flex items-center justify-between">
<label htmlFor="mask-edge-smoothing" className="text-[10px] text-gray-500 uppercase">边缘平滑强度:</label>
<span className="text-xs font-mono text-gray-300">{smoothingStrength}%</span>
</div>
<input
id="mask-edge-smoothing"
aria-label="边缘平滑强度"
type="range"
min={0}
max={100}
step={5}
value={smoothingStrength}
onChange={(event) => setSmoothingStrength(Number(event.target.value))}
disabled={!selectedMask || isSmoothingMask}
className="w-full accent-cyan-500 disabled:opacity-40"
/>
<button
onClick={handleApplySmoothing}
disabled={!selectedMask || !currentFrame || isSmoothingMask}
className="mt-2 w-full bg-cyan-500/10 hover:bg-cyan-500/20 border border-cyan-500/20 text-xs text-cyan-100 py-1.5 rounded transition-colors disabled:opacity-40 disabled:cursor-not-allowed"
>
{isSmoothingMask ? '平滑中...' : '应用边缘平滑'}
</button>
</div>
{analysisMessage && ( {analysisMessage && (
<div className="text-[10px] leading-relaxed text-gray-500">{analysisMessage}</div> <div className="text-[10px] leading-relaxed text-gray-500">{analysisMessage}</div>
)} )}

38
src/components/VideoWorkspace.test.tsx
View File

@@ -233,6 +233,41 @@ describe('VideoWorkspace', () => {
expect(useStore.getState().activeTool).toBe('edit_polygon'); expect(useStore.getState().activeTool).toBe('edit_polygon');
}); });
it('keeps the current non-first frame when returning from AI segmentation to the workspace', async () => {
apiMock.getProjectFrames.mockResolvedValueOnce([
{ id: 10, project_id: 1, frame_index: 0, image_url: '/frame-1.jpg', width: 640, height: 360 },
{ id: 11, project_id: 1, frame_index: 1, image_url: '/frame-2.jpg', width: 640, height: 360 },
{ id: 12, project_id: 1, frame_index: 2, image_url: '/frame-3.jpg', width: 640, height: 360 },
]);
useStore.setState({
frames: [
{ id: '10', projectId: '1', index: 0, url: '/frame-1.jpg', width: 640, height: 360 },
{ id: '11', projectId: '1', index: 1, url: '/frame-2.jpg', width: 640, height: 360 },
{ id: '12', projectId: '1', index: 2, url: '/frame-3.jpg', width: 640, height: 360 },
],
currentFrameIndex: 1,
activeTool: 'edit_polygon',
selectedMaskIds: ['ai-mask-frame-2'],
masks: [{
id: 'ai-mask-frame-2',
frameId: '11',
pathData: 'M 10 10 L 40 10 L 40 40 Z',
label: 'AI Mask',
color: '#06b6d4',
segmentation: [[10, 10, 40, 10, 40, 40]],
saveStatus: 'draft',
saved: false,
metadata: { source: 'ai_segmentation' },
}],
});
render(<VideoWorkspace />);
await waitFor(() => expect(useStore.getState().frames).toHaveLength(3));
expect(useStore.getState().currentFrameIndex).toBe(1);
expect(useStore.getState().selectedMaskIds).toEqual(['ai-mask-frame-2']);
});
it('saves pending masks through the archive button', async () => { it('saves pending masks through the archive button', async () => {
apiMock.getProjectFrames.mockResolvedValueOnce([ apiMock.getProjectFrames.mockResolvedValueOnce([
{ id: 10, project_id: 1, frame_index: 0, image_url: '/frame.jpg', width: 640, height: 360 }, { id: 10, project_id: 1, frame_index: 0, image_url: '/frame.jpg', width: 640, height: 360 },
@@ -533,6 +568,7 @@ describe('VideoWorkspace', () => {
label: '胆囊', label: '胆囊',
color: '#ff0000', color: '#ff0000',
class: { id: 'c1', name: '胆囊', color: '#ff0000', zIndex: 20 }, class: { id: 'c1', name: '胆囊', color: '#ff0000', zIndex: 20 },
geometry_smoothing: { strength: 35, method: 'chaikin' },
}, },
bbox: [0.1, 0.1, 0.2, 0.2], bbox: [0.1, 0.1, 0.2, 0.2],
}; };
@@ -573,6 +609,7 @@ describe('VideoWorkspace', () => {
source_annotation_id: 5, source_annotation_id: 5,
source_mask_id: 'annotation-5', source_mask_id: 'annotation-5',
propagation_seed_signature: 'seed-signature-5', propagation_seed_signature: 'seed-signature-5',
geometry_smoothing: { strength: 35, method: 'chaikin' },
}, },
}], }],
}); });
@@ -602,6 +639,7 @@ describe('VideoWorkspace', () => {
template_id: 2, template_id: 2,
source_mask_id: 'annotation-5', source_mask_id: 'annotation-5',
source_annotation_id: 5, source_annotation_id: 5,
smoothing: { strength: 35, method: 'chaikin' },
}, },
}], }],
})); }));

32
src/components/VideoWorkspace.tsx
View File

@@ -159,6 +159,12 @@ export function VideoWorkspace({ onNavigateToAI }: { onNavigateToAI?: () => void
const loadFrames = async () => { const loadFrames = async () => {
const selectedIdsBeforeLoad = latestSelectedMaskIdsRef.current; const selectedIdsBeforeLoad = latestSelectedMaskIdsRef.current;
const stateBeforeLoad = useStore.getState();
const selectedFrameIdBeforeLoad = stateBeforeLoad.masks.find((mask) => (
selectedIdsBeforeLoad.includes(mask.id)
&& String(mask.frameId)
))?.frameId;
const currentFrameBeforeLoad = stateBeforeLoad.frames[stateBeforeLoad.currentFrameIndex];
try { try {
const data = await getProjectFrames(String(currentProject.id)); const data = await getProjectFrames(String(currentProject.id));
if (cancelled) return; if (cancelled) return;
@@ -174,8 +180,8 @@ export function VideoWorkspace({ onNavigateToAI }: { onNavigateToAI?: () => void
sourceFrameNumber: f.source_frame_number ?? undefined, sourceFrameNumber: f.source_frame_number ?? undefined,
})); }));
setFrames(mappedFrames); setFrames(mappedFrames);
setCurrentFrame(0);
if (mappedFrames.length === 0) { if (mappedFrames.length === 0) {
setCurrentFrame(0);
setMasks([]); setMasks([]);
if (currentProject.status === 'parsing') { if (currentProject.status === 'parsing') {
setStatusMessage('生成帧任务正在后台运行，可在 Dashboard 查看进度'); setStatusMessage('生成帧任务正在后台运行，可在 Dashboard 查看进度');
@@ -186,6 +192,16 @@ export function VideoWorkspace({ onNavigateToAI }: { onNavigateToAI?: () => void
} }
return; return;
} }
const currentProjectId = String(currentProject.id);
const preferredFrameId = selectedFrameIdBeforeLoad
|| (currentFrameBeforeLoad?.projectId === currentProjectId ? currentFrameBeforeLoad.id : undefined);
const preferredIndex = preferredFrameId
? mappedFrames.findIndex((frame) => frame.id === String(preferredFrameId))
: -1;
const fallbackIndex = currentFrameBeforeLoad?.projectId === currentProjectId
? Math.min(Math.max(stateBeforeLoad.currentFrameIndex, 0), mappedFrames.length - 1)
: 0;
setCurrentFrame(preferredIndex >= 0 ? preferredIndex : fallbackIndex);
setStatusMessage(''); setStatusMessage('');
await hydrateSavedAnnotations(String(currentProject.id), mappedFrames, selectedIdsBeforeLoad); await hydrateSavedAnnotations(String(currentProject.id), mappedFrames, selectedIdsBeforeLoad);
} catch (err) { } catch (err) {
@@ -491,6 +507,19 @@ export function VideoWorkspace({ onNavigateToAI }: { onNavigateToAI?: () => void
const inheritedSeedSignature = typeof seedMask.metadata?.propagation_seed_signature === 'string' const inheritedSeedSignature = typeof seedMask.metadata?.propagation_seed_signature === 'string'
? seedMask.metadata.propagation_seed_signature ? seedMask.metadata.propagation_seed_signature
: undefined; : undefined;
const rawSmoothing = seedPayload.mask_data?.geometry_smoothing
|| (seedMask.metadata?.geometry_smoothing && typeof seedMask.metadata.geometry_smoothing === 'object'
? seedMask.metadata.geometry_smoothing
: undefined);
const smoothingStrength = rawSmoothing && typeof rawSmoothing === 'object'
? Number((rawSmoothing as Record<string, unknown>).strength)
: NaN;
const geometrySmoothing = Number.isFinite(smoothingStrength) && smoothingStrength > 0
? {
strength: Math.min(Math.max(smoothingStrength, 0), 100),
method: 'chaikin' as const,
}
: undefined;
return { return {
polygons: seedPayload.mask_data?.polygons, polygons: seedPayload.mask_data?.polygons,
bbox: seedPayload.bbox, bbox: seedPayload.bbox,
@@ -502,6 +531,7 @@ export function VideoWorkspace({ onNavigateToAI }: { onNavigateToAI?: () => void
source_mask_id: metadataSourceMaskId || seedMask.id, source_mask_id: metadataSourceMaskId || seedMask.id,
source_annotation_id: sourceAnnotationId, source_annotation_id: sourceAnnotationId,
propagation_seed_signature: inheritedSeedSignature, propagation_seed_signature: inheritedSeedSignature,
smoothing: geometrySmoothing,
}; };
}, [activeTemplateId, currentFrame, currentProject?.id]); }, [activeTemplateId, currentFrame, currentProject?.id]);

49
src/lib/api.test.ts
View File

@@ -346,6 +346,7 @@ describe('api client contracts', () => {
classZIndex: 20, classZIndex: 20,
segmentation: [[10, 10, 90, 10, 90, 40]], segmentation: [[10, 10, 90, 10, 90, 40]],
bbox: [10, 10, 80, 30], bbox: [10, 10, 80, 30],
metadata: { geometry_smoothing: { strength: 35, method: 'chaikin' } },
}, frame, '2'); }, frame, '2');
expect(payload).toEqual({ expect(payload).toEqual({
@@ -357,6 +358,7 @@ describe('api client contracts', () => {
label: '胆囊', label: '胆囊',
color: '#ff0000', color: '#ff0000',
class: { id: 'c1', name: '胆囊', color: '#ff0000', zIndex: 20 }, class: { id: 'c1', name: '胆囊', color: '#ff0000', zIndex: 20 },
geometry_smoothing: { strength: 35, method: 'chaikin' },
}, },
bbox: [0.1, 0.2, 0.8, 0.6], bbox: [0.1, 0.2, 0.8, 0.6],
}); });
@@ -373,6 +375,7 @@ describe('api client contracts', () => {
class: { id: 'c1', name: '胆囊', color: '#ff0000', zIndex: 20 }, class: { id: 'c1', name: '胆囊', color: '#ff0000', zIndex: 20 },
source: 'sam2.1_hiera_tiny_propagation', source: 'sam2.1_hiera_tiny_propagation',
propagated_from_frame_id: 4, propagated_from_frame_id: 4,
geometry_smoothing: { strength: 35, method: 'chaikin' },
}, },
points: [[0.5, 0.5]], points: [[0.5, 0.5]],
bbox: null, bbox: null,
@@ -396,10 +399,56 @@ describe('api client contracts', () => {
metadata: { metadata: {
source: 'sam2.1_hiera_tiny_propagation', source: 'sam2.1_hiera_tiny_propagation',
propagated_from_frame_id: 4, propagated_from_frame_id: 4,
geometry_smoothing: { strength: 35, method: 'chaikin' },
}, },
})); }));
}); });
it('sends selected mask geometry to backend smoothing and maps smoothed polygons back to pixels', async () => {
const { smoothMaskGeometry } = await import('./api');
axiosMock.client.post.mockResolvedValueOnce({
data: {
polygons: [[[0.12, 0.24], [0.88, 0.24], [0.88, 0.76], [0.12, 0.76]]],
topology_anchor_count: 4,
topology_anchors: [[0.12, 0.24]],
area: 0.4,
bbox: [0.12, 0.24, 0.76, 0.52],
smoothing: { strength: 35, method: 'chaikin' },
message: '已应用边缘平滑强度 35',
},
});
const result = await smoothMaskGeometry({
id: 'm1',
frameId: '5',
pathData: 'M 10 10 L 90 10 L 90 40 Z',
label: '胆囊',
color: '#ff0000',
segmentation: [[10, 10, 90, 10, 90, 40]],
bbox: [10, 10, 80, 30],
}, { id: '5', projectId: '9', index: 0, url: '/frame.jpg', width: 100, height: 50 }, 35);
expect(axiosMock.client.post).toHaveBeenCalledWith('/api/ai/smooth-mask', {
frame_id: 5,
mask_data: {
polygons: [[[0.1, 0.2], [0.9, 0.2], [0.9, 0.8]]],
label: '胆囊',
color: '#ff0000',
},
points: undefined,
bbox: [0.1, 0.2, 0.8, 0.6],
strength: 35,
method: 'chaikin',
});
expect(result).toEqual(expect.objectContaining({
pathData: 'M 12 12 L 88 12 L 88 38 L 12 38 Z',
segmentation: [[12, 12, 88, 12, 88, 38, 12, 38]],
bbox: [12, 12, 76, 26],
area: 1976,
smoothing: { strength: 35, method: 'chaikin' },
}));
});
it('preserves editable point regions in annotation payloads', async () => { it('preserves editable point regions in annotation payloads', async () => {
const { buildAnnotationPayload } = await import('./api'); const { buildAnnotationPayload } = await import('./api');
const frame = { id: '5', projectId: '9', index: 0, url: '/frame.jpg', width: 100, height: 50 }; const frame = { id: '5', projectId: '9', index: 0, url: '/frame.jpg', width: 100, height: 50 };

88
src/lib/api.ts
View File

@@ -303,6 +303,7 @@ export interface SavedAnnotation {
source?: string; source?: string;
propagated_from_frame_id?: number; propagated_from_frame_id?: number;
propagated_from_frame_index?: number; propagated_from_frame_index?: number;
geometry_smoothing?: GeometrySmoothingOptions;
score?: number | null; score?: number | null;
[key: string]: unknown; [key: string]: unknown;
} | null; } | null;
@@ -327,6 +328,8 @@ export interface SaveAnnotationPayload {
zIndex?: number; zIndex?: number;
category?: string; category?: string;
}; };
geometry_smoothing?: GeometrySmoothingOptions;
[key: string]: unknown;
}; };
points?: number[][]; points?: number[][];
bbox?: number[]; bbox?: number[];
@@ -354,6 +357,8 @@ export interface PropagateMasksPayload {
template_id?: number; template_id?: number;
source_mask_id?: string; source_mask_id?: string;
source_annotation_id?: number; source_annotation_id?: number;
propagation_seed_signature?: string;
smoothing?: GeometrySmoothingOptions;
}; };
direction?: 'forward' | 'backward' | 'both'; direction?: 'forward' | 'backward' | 'both';
max_frames?: number; max_frames?: number;
@@ -394,6 +399,23 @@ export interface MaskAnalysisResult {
message: string; message: string;
} }
export interface GeometrySmoothingOptions {
strength: number;
method: 'chaikin';
}
export interface SmoothMaskGeometryResult {
polygons: number[][][];
pathData: string;
segmentation: number[][];
bbox: [number, number, number, number];
area: number;
topology_anchor_count: number;
topology_anchors: number[][];
smoothing: GeometrySmoothingOptions;
message: string;
}
export interface DashboardTask { export interface DashboardTask {
id: string; id: string;
task_id?: number; task_id?: number;
@@ -461,6 +483,28 @@ function polygonToBbox(points: number[][], width: number, height: number): [numb
return [minX, minY, maxX - minX, maxY - minY]; return [minX, minY, maxX - minX, maxY - minY];
} }
function polygonAreaPixels(points: number[][], width: number, height: number): number {
if (points.length < 3) return 0;
let total = 0;
points.forEach(([x, y], index) => {
const [nx, ny] = points[(index + 1) % points.length];
total += (x * width) * (ny * height);
total -= (nx * width) * (y * height);
});
return Math.abs(total) / 2;
}
function normalizeGeometrySmoothing(value: unknown): GeometrySmoothingOptions | undefined {
if (!value || typeof value !== 'object') return undefined;
const source = value as Record<string, unknown>;
const strength = Number(source.strength);
if (!Number.isFinite(strength) || strength <= 0) return undefined;
return {
strength: Math.min(Math.max(strength, 0), 100),
method: 'chaikin',
};
}
function pixelSegmentationToNormalizedPolygons( function pixelSegmentationToNormalizedPolygons(
segmentation: number[][] | undefined, segmentation: number[][] | undefined,
width: number, width: number,
@@ -498,6 +542,7 @@ export function buildAnnotationPayload(
zIndex: mask.classZIndex, zIndex: mask.classZIndex,
} }
: undefined; : undefined;
const geometrySmoothing = normalizeGeometrySmoothing(mask.metadata?.geometry_smoothing);
const payload: SaveAnnotationPayload = { const payload: SaveAnnotationPayload = {
project_id: Number(projectId), project_id: Number(projectId),
@@ -508,6 +553,7 @@ export function buildAnnotationPayload(
label: mask.label, label: mask.label,
color: mask.color, color: mask.color,
...(classMetadata ? { class: classMetadata } : {}), ...(classMetadata ? { class: classMetadata } : {}),
...(geometrySmoothing ? { geometry_smoothing: geometrySmoothing } : {}),
}, },
bbox: mask.bbox bbox: mask.bbox
? [ ? [
@@ -587,6 +633,48 @@ export async function analyzeMask(mask: Mask, frame: Frame, options: { extractSk
return response.data; return response.data;
} }
export async function smoothMaskGeometry(mask: Mask, frame: Frame, strength: number): Promise<SmoothMaskGeometryResult> {
const polygons = pixelSegmentationToNormalizedPolygons(mask.segmentation, frame.width, frame.height);
const response = await apiClient.post('/api/ai/smooth-mask', {
frame_id: Number(frame.id),
mask_data: {
polygons,
label: mask.label,
color: mask.color,
},
points: mask.points?.map(([x, y]) => [
clamp01(x / Math.max(frame.width, 1)),
clamp01(y / Math.max(frame.height, 1)),
]),
bbox: mask.bbox
? [
clamp01(mask.bbox[0] / Math.max(frame.width, 1)),
clamp01(mask.bbox[1] / Math.max(frame.height, 1)),
clamp01(mask.bbox[2] / Math.max(frame.width, 1)),
clamp01(mask.bbox[3] / Math.max(frame.height, 1)),
]
: undefined,
strength,
method: 'chaikin',
});
const resultPolygons: number[][][] = response.data.polygons || [];
const firstPolygon = resultPolygons[0] || [];
const bbox = firstPolygon.length > 0
? polygonToBbox(firstPolygon, frame.width, frame.height)
: [0, 0, 0, 0] as [number, number, number, number];
return {
polygons: resultPolygons,
pathData: firstPolygon.length > 0 ? polygonToPath(firstPolygon, frame.width, frame.height) : '',
segmentation: resultPolygons.map((polygon) => polygon.flatMap(([x, y]) => [x * frame.width, y * frame.height])),
bbox,
area: resultPolygons.reduce((total, polygon) => total + polygonAreaPixels(polygon, frame.width, frame.height), 0),
topology_anchor_count: response.data.topology_anchor_count,
topology_anchors: response.data.topology_anchors || [],
smoothing: response.data.smoothing,
message: response.data.message,
};
}
export async function predictMask(payload: PredictMaskPayload): Promise<PredictMaskResult> { export async function predictMask(payload: PredictMaskPayload): Promise<PredictMaskResult> {
let prompt_type: 'point' | 'box' | 'semantic' | 'interactive'; let prompt_type: 'point' | 'box' | 'semantic' | 'interactive';
let prompt_data: unknown; let prompt_data: unknown;