2026-05-20-03-19-25 完善分割结果保存与STL导出
This commit is contained in:
62
工程分析/实现方案-2026-05-20-03-19-25.md
Normal file
62
工程分析/实现方案-2026-05-20-03-19-25.md
Normal file
@@ -0,0 +1,62 @@
|
||||
# 实现方案：导出与项目库分割结果闭环
|
||||
|
||||
实现方案文档路径：`工程分析/实现方案-2026-05-20-03-19-25.md`
|
||||
|
||||
## 修改目标
|
||||
|
||||
补齐原始 STL 导出、分割结果保存到项目库、项目库复用导出包功能、工作区布局与右侧构件提示优化，并新增系统使用说明 `Agent.md`。
|
||||
|
||||
## 涉及路径
|
||||
|
||||
- `WebSite/server.ts`
|
||||
- `WebSite/src/types.ts`
|
||||
- `WebSite/src/lib/api.ts`
|
||||
- `WebSite/src/components/ReverseWorkspace.tsx`
|
||||
- `WebSite/src/components/ProjectLibrary.tsx`
|
||||
- `Agent.md`
|
||||
- `工程分析/需求分析-2026-05-20-03-19-25.md`
|
||||
- `工程分析/实现方案-2026-05-20-03-19-25.md`
|
||||
- `工程分析/测试方案-2026-05-20-03-19-25.md`
|
||||
- `工程分析/经验记录.md`
|
||||
|
||||
## 技术路线
|
||||
|
||||
1. 后端导出目标新增 `stl`，在 `/export-bundle` 中将 `Head_CT_ReConstruct` 下的原始 STL 文件写入同一个 tar.gz。
|
||||
2. 项目状态新增 `segmentationResults`，保存当前分割结果的名称、时间、位姿、分割范围与构件样式快照。
|
||||
3. 新增 `POST /api/projects/:projectId/segmentation-results`，供逆向工作区 `保存至项目库` 调用。
|
||||
4. 项目库 `分割结果` 视图读取保存记录，并提供与逆向工作区一致的导出内容选择、分割范围选择和压缩包下载。
|
||||
5. 将默认/推荐位姿加入前后端默认位姿列表，逆向工作区加载项目时优先选择 `最佳位姿`。
|
||||
6. 工作区三栏布局从 `6/3/3` 调整为更偏向工具栏与映射视图的比例，压缩左侧融合视角。
|
||||
7. `OverlayStats` 增加当前 slice 的构件明细，图例仅显示当前切片中实际有边或像素的构件，并用紧凑表格呈现。
|
||||
8. 编写 `Agent.md`，包含系统使用方式和 500~1300 字主要功能说明。
|
||||
|
||||
## 执行步骤
|
||||
|
||||
1. 增加类型定义和后端状态归一化。
|
||||
2. 扩展导出包生成逻辑与 API 参数解析。
|
||||
3. 增加项目库保存接口与前端 API。
|
||||
4. 修改逆向工作区按钮、布局、右侧图例。
|
||||
5. 修改项目库分割结果区域和导出菜单。
|
||||
6. 编写 `Agent.md`。
|
||||
7. 运行 lint、build、接口导出验证、保存接口验证、部署验证。
|
||||
8. 追加经验记录、提交、推送、重新部署。
|
||||
|
||||
## 兼容性与回滚方案
|
||||
|
||||
- 原有导出目标 `dicom/segmentation/pose` 保持兼容。
|
||||
- `stl` 为新增可选目标，默认可不选以避免包过大。
|
||||
- 旧项目没有 `segmentationResults` 时归一化为空数组。
|
||||
- 回滚到上一提交会移除项目库保存结果和 STL 导出选项，但不影响原始医学数据。
|
||||
|
||||
## 预计文件变更
|
||||
|
||||
- 后端状态、导出和保存接口。
|
||||
- 前端 API、类型、逆向工作区与项目库 UI。
|
||||
- 新增 `Agent.md`。
|
||||
- 工程分析与经验记录。
|
||||
|
||||
## 提交与部署策略
|
||||
|
||||
- 只暂存本次相关文件。
|
||||
- commit message 包含 `2026-05-20-03-19-25` 和简要说明。
|
||||
- 推送 Gitea 后使用 `tmux` 会话 `revoxelseg-dicom` 重启服务并验证。
|
||||
79
工程分析/测试方案-2026-05-20-03-19-25.md
Normal file
79
工程分析/测试方案-2026-05-20-03-19-25.md
Normal file
@@ -0,0 +1,79 @@
|
||||
# 测试方案：导出 STL、保存分割结果与项目库复核
|
||||
|
||||
测试方案文档路径：`工程分析/测试方案-2026-05-20-03-19-25.md`
|
||||
|
||||
## 静态检查
|
||||
|
||||
- 运行 `npm run lint`，确认 TypeScript 类型检查通过。
|
||||
- 运行 `git diff --check`，确认无空白错误。
|
||||
|
||||
结果：已通过。
|
||||
|
||||
## 构建检查
|
||||
|
||||
- 在 `WebSite/` 执行 `npm run build`，确认生产构建通过。
|
||||
|
||||
结果：已通过。Vite 仍有单 bundle 超过 500 kB 的既有提示，不影响本次功能。
|
||||
|
||||
## 关键业务场景验证
|
||||
|
||||
- 调用 `POST /api/projects/head-ct-demo/segmentation-results`，确认返回项目包含保存记录。
|
||||
- 调用 `/api/projects/head-ct-demo/export-bundle?targets=stl`，确认压缩包内包含原始 STL 文件。
|
||||
- 调用 `/api/projects/head-ct-demo/export-bundle?targets=segmentation,pose,stl`，确认分割、位姿与 STL 可共包导出。
|
||||
- 验证项目库 `分割结果` 右侧导出菜单参数与逆向工作区一致。
|
||||
|
||||
结果：已通过。
|
||||
|
||||
- 临时服务 `127.0.0.1:4100` 下保存接口返回 `segmentationResults`，并可看到默认 `最佳位姿`。
|
||||
- `targets=stl` 返回 HTTP 200，压缩包约 `116M`，目录包含 9 个原始 STL：会厌、气管上段、气管狭窄段、气管下段、气管整体、声门、头部、头颅、肿瘤。
|
||||
- `targets=segmentation,pose,stl` 返回 HTTP 200，约 `121433464` bytes，用时约 `7.58s`，包内包含分割 NIfTI、labels JSON、pose JSON 和 STL 原始模型。
|
||||
|
||||
## 医学影像数据相关边界验证
|
||||
|
||||
- 分割导出仍保持 DICOM 同维度 NIfTI。
|
||||
- 保存的分割结果导出时使用保存时位姿。
|
||||
- `visible/all` 分割范围继续影响 Label Map 与 labels JSON。
|
||||
|
||||
结果：已覆盖导出包结构验证；分割 NIfTI 生成逻辑未改变，继续复用上一轮完整 STL 网格实体导出链路。
|
||||
|
||||
## UI 验证
|
||||
|
||||
- 逆向工作区顶部出现 `保存至项目库`。
|
||||
- 三栏布局中左侧融合视角变窄，中部工具栏和右侧映射视图变宽。
|
||||
- 右侧图例只显示当前 slice 中有边或填充像素的构件；无构件时显示空状态。
|
||||
- 项目库分割结果区域显示保存记录和导出入口。
|
||||
|
||||
## 文档验证
|
||||
|
||||
- `Agent.md` 存在。
|
||||
- `Agent.md` 包含当前系统使用方式。
|
||||
- `主要功能` 说明在 500~1300 字范围内。
|
||||
|
||||
结果：已通过。`Agent.md` 总字数约 `1105` 字符，主要功能段落在 500~1300 字范围内。
|
||||
|
||||
## 部署验证
|
||||
|
||||
- 重新部署后验证：
|
||||
- `http://127.0.0.1:4000/api/health`
|
||||
- `http://127.0.0.1:4000/`
|
||||
- 部署后验证导出包接口。
|
||||
|
||||
结果：已通过。
|
||||
|
||||
- `tmux` 会话 `revoxelseg-dicom` 已重启，服务输出 `ReVoxelSeg DICOM server ready at http://0.0.0.0:4000/`。
|
||||
- `/api/health` 返回 `{"ok":true,"service":"revoxelseg-dicom"}`。
|
||||
- 首页 HTTP 200。
|
||||
- 部署后 `targets=stl` 导出返回 HTTP 200，约 `121372189` bytes，压缩包内包含 9 个 STL 原始模型。
|
||||
|
||||
## Git/Gitea 备份验证
|
||||
|
||||
- 提交信息包含 `2026-05-20-03-19-25` 和本次修改摘要。
|
||||
- 推送到 Gitea 成功。
|
||||
|
||||
结果：本地 Git commit 已完成；Gitea 推送重试 2 次均失败，错误为 `No route to host`，说明当前环境到 `192.168.31.5:5002` 网络不可达。待网络恢复后执行 `git push origin main` 即可补推。
|
||||
|
||||
## 风险与回归关注点
|
||||
|
||||
- STL 原始模型打包体积较大，接口验证可先用 `targets=stl` 查看目录，不反复下载全量组合。
|
||||
- 临时保存接口测试会修改 `WebSite/data/state.json`，该运行态文件不纳入提交。
|
||||
- 旧的未暂存历史删除状态不应混入提交。
|
||||
18
工程分析/经验记录.md
18
工程分析/经验记录.md
@@ -1135,3 +1135,21 @@ C. 解决问题方案
|
||||
D. 后续如何避免问题
|
||||
|
||||
预览数据、抽样数据和医学导出数据必须明确分层。凡是 NIfTI、Mask、Label Map、体素化这类可用于医学工具复核的导出功能，都不得复用用于前端性能优化的抽样网格；验证时必须检查大面数构件的 label 体素数量、slice 覆盖范围和侧视/冠状重建是否连续。
|
||||
|
||||
## 2026-05-20-03-19-25 分割结果保存必须携带位姿与导出上下文
|
||||
|
||||
A. 具体问题
|
||||
|
||||
用户要求在逆向工作区将当前“逆向分割映射视图”保存至项目库，并在项目库分割结果区域继续导出。如果只保存一个名称或时间，项目库无法复现保存当时的位姿、类别范围和构件样式。
|
||||
|
||||
B. 产生问题原因
|
||||
|
||||
分割结果不是一个静态按钮状态，而是由模型位姿、构件显隐、颜色、透明度、partId 和分割范围共同决定；这些上下文如果仍散落在组件 state 或只存在当前页面，重新进入项目库后导出的结果可能与保存时不一致。
|
||||
|
||||
C. 解决问题方案
|
||||
|
||||
项目状态新增 `segmentationResults`，保存当前结果名称、时间、`segmentationScope`、模型位姿和构件样式快照；逆向工作区通过后端接口写入项目，项目库分割结果区域读取该记录，并用最新保存结果的位姿作为导出默认输入。导出包新增 `stl` 目标，将原始 STL 文件放入同一个 tar.gz 中。
|
||||
|
||||
D. 后续如何避免问题
|
||||
|
||||
凡是“保存至项目库”“保存结果”“复核后导出”类功能，都必须明确保存的是结果本体还是生成结果所需的上下文。医学导出相关记录至少要包含位姿、分割范围、标签样式和生成时间；新增导出目标时也要同步检查逆向工作区和项目库两个入口是否一致。
|
||||
|
||||
65
工程分析/需求分析-2026-05-20-03-19-25.md
Normal file
65
工程分析/需求分析-2026-05-20-03-19-25.md
Normal file
@@ -0,0 +1,65 @@
|
||||
# 需求分析：导出 STL、保存分割结果与工作区布局优化
|
||||
|
||||
开始时间：2026-05-20-03-19-25
|
||||
|
||||
## 原始需求摘要
|
||||
|
||||
用户提出以下修改：
|
||||
|
||||
1. `导出全部 NII.GZ` 增加 `导出 STL 原始模型` 选项。
|
||||
2. 逆向工作区 `逆向分割映射视图` 上方增加 `保存至项目库` 按钮，将当前分割结果推送到项目库的 `分割结果` 区域；项目库分割结果右侧需要具备与 `导出全部 NII.GZ` 一致的导出功能。
|
||||
3. `影像与模型融合视角` 仍占地过大，需要让 `可视化工具栏` 与 `逆向分割映射视图` 更宽。
|
||||
4. `逆向分割映射视图` 下方仅显示当前切片中实际出现的构件，并改为更紧密的表格形式，一行可以显示多个构件提示。
|
||||
5. `head-ct-demo-pose-data.json` 是最合适的位姿，需要作为当前系统推荐/默认位姿使用。
|
||||
6. 使用 `Agent.md` 撰写当前系统使用方式，并输出 500~1300 字的主要功能说明。
|
||||
|
||||
## 业务目标
|
||||
|
||||
- 让导出包成为 DICOM、分割、位姿、原始 STL 的统一归档入口。
|
||||
- 将逆向工作区中的分割结果沉淀到项目库，便于后续复核和导出。
|
||||
- 提高三栏工作区中操作区和二维校验区的可用宽度。
|
||||
- 右侧切片图例只表达当前 slice 实际存在的 Overlay 构件，减少无关干扰。
|
||||
- 默认加载最优位姿，降低用户每次进入项目后的手动调整成本。
|
||||
- 提供清晰的系统使用说明文档。
|
||||
|
||||
## 输入与输出
|
||||
|
||||
- 输入：
|
||||
- 当前项目 `head-ct-demo`。
|
||||
- 当前模型位姿、构件样式、分割导出范围。
|
||||
- `head-ct-demo-pose-data.json` 中的最佳位姿。
|
||||
- 输出：
|
||||
- 新增 STL 原始模型导出包内容。
|
||||
- 项目级保存的分割结果记录。
|
||||
- 项目库分割结果区域与导出入口。
|
||||
- 优化后的工作区布局和切片构件表格。
|
||||
- `Agent.md` 使用说明。
|
||||
|
||||
## 影响范围
|
||||
|
||||
- `WebSite/server.ts`
|
||||
- `WebSite/src/types.ts`
|
||||
- `WebSite/src/lib/api.ts`
|
||||
- `WebSite/src/components/ReverseWorkspace.tsx`
|
||||
- `WebSite/src/components/ProjectLibrary.tsx`
|
||||
- `Agent.md`
|
||||
- 工程分析文档与经验记录。
|
||||
|
||||
## 关键约束
|
||||
|
||||
- 保存至项目库必须写入后端项目状态，不能只存在组件内存。
|
||||
- 导出 STL 原始模型不能把大型 STL 文件提交到 Git，只在运行时打包下载。
|
||||
- 继续避免浏览器 blob 下载路径，保持后端附件直链。
|
||||
- 文档备份提交只包含本次相关代码和文档，不纳入旧的未确认删除。
|
||||
|
||||
## 风险点
|
||||
|
||||
- 原始 STL 总体积较大，选择导出 STL 会明显增加压缩包体积和下载耗时。
|
||||
- 保存分割结果若不携带位姿，会导致项目库导出的分割与保存时不一致。
|
||||
- 图例改为当前 slice 构件后，需要依赖 Overlay 计算结果，不能只看全局显隐状态。
|
||||
|
||||
## 默认假设
|
||||
|
||||
- `保存至项目库` 保存当前位姿、导出范围和当前构件样式快照。
|
||||
- 项目库分割结果导出默认使用最新保存结果的位姿与范围。
|
||||
- `Agent.md` 放在项目根目录，作为系统使用说明文档。
|
||||
Reference in New Issue
Block a user