2026-05-08-03-57-51 接入DICOM SEG双切面展示

工程分析/实现方案-2026-05-08-03-57-51.md

@@ -0,0 +1,58 @@
+# 实现方案 - 2026-05-08-03-57-51
+
+## 方案路径
+
+将右侧“Mask 展示”从 STL/3D 几何结果展示改为真实 DICOM Segmentation Mask 的二维实心切片展示。模型切分操作只决定需要展示的切分位置和上下端点；实际像素内容必须来自与当前 DICOM 数据配准的语义分割 mask 体数据。
+
+## 涉及文件
+
+- `web_backend.py`
+  - 新增 segmentation mask 数据发现、读取、缓存和切片渲染逻辑。
+  - 新增或扩展 mask 预览接口，返回切分上侧/下侧两张二维实心 mask 图片。
+  - 保留 STL 切分用于确定范围或几何参考，但不再用 STL Cap 作为最终 mask 图像数据源。
+- `WebSite/src/App.tsx`
+  - 调整模型切分触发后的“Mask 展示”请求和渲染逻辑。
+  - 右侧面板固定展示两张二维实心 Segmentation Mask 图片。
+  - 对无 segmentation 数据、无交集、加载失败分别给出状态。
+- `工程分析/经验记录.md`
+  - 完成后追加本轮关键问题、原因、解决方案和后续避免方式。
+
+## 执行步骤
+
+1. 数据源梳理：
+   - 检查 `web_library/` 和现有接口中是否已有 DICOM SEG、RTSTRUCT、NIfTI、NRRD、PNG mask 序列或其他语义分割文件。
+   - 当前未发现现成 segmentation 数据源，因此新增“上传/关联 Segmentation Mask”的后端入口和前端入口，避免继续从 STL 伪造 mask。
+2. 后端 mask 体数据读取：
+   - 优先支持 DICOM SEG / DICOM label-map 文件。
+   - 将 mask 读取为与 CT 体数据对齐的三维 label map。
+   - 使用缓存避免每次切分重复读取整套 mask。
+3. 后端二维实心截面渲染：
+   - 根据当前模型切分范围计算上侧/下侧两张目标切片。
+   - 从 Segmentation Mask label map 中取对应切片。
+   - 生成二维实心 mask-only PNG，而不是 CT 叠加图、STL Cap 或点云投影。
+   - 多标签情况下保留标签差异，可按固定颜色表渲染。
+4. 前端“Mask 展示”调整：
+   - 点击“模型切分”后，右侧面板请求新的 segmentation mask 双图接口。
+   - 面板标题保持“Mask 展示”，内容为两张二维图片：上侧切面、下侧切面。
+   - 移除或隐藏任何 3D 外壳/点云/半透明模型展示路径。
+5. 错误与降级处理：
+   - 若没有绑定 segmentation mask 数据，提示需要上传或关联 DICOM Segmentation Mask。
+   - 若某一切面 mask 为空，显示“该切面无分割区域”，但不生成假 mask。
+6. 验证通过后更新经验记录、提交 Gitea，并重新部署。
+
+## 回滚思路
+
+若新接口或前端展示出现问题，可回滚 `web_backend.py` 中新增 segmentation mask 读取/渲染逻辑和 `WebSite/src/App.tsx` 中“Mask 展示”的请求渲染改动，恢复当前 STL mask-only 双图逻辑。
+
+## 风险控制
+
+- 不将 STL Cap、封闭面或几何填充作为最终 mask 数据源。
+- 对 segmentation 数据缺失做显式错误提示，不用临时绘制图形代替。
+- DICOM SEG 坐标对齐需严格参考 CT 的方向、间距、原点和切片顺序。
+- 若缺少测试数据，只做接口和类型验证不足以证明医学对齐正确，必须标注残余风险。
+
+## 需要用户确认
+
+- 用户已确认方案，允许新增 Segmentation Mask 上传/关联入口。
+- “上、下两个视角”本次按当前切分范围的起点帧/终点帧实现。
+- 如果已有真实 segmentation mask 数据，请提供其所在目录或文件格式说明。

工程分析/测试方案-2026-05-08-03-57-51.md

@@ -0,0 +1,55 @@
+# 测试方案 - 2026-05-08-03-57-51
+
+## 测试范围
+
+- Segmentation Mask 数据发现或上传/关联流程。
+- 后端 mask 读取、缓存、切片提取和 PNG 渲染。
+- 前端模型切分触发后右侧“Mask 展示”双图渲染。
+- 无 segmentation 数据、空 mask、加载失败等状态。
+- 既有 DICOM 阅览、STL 上传和模型切分范围控件不发生回归。
+
+## 测试命令
+
+```bash
+python -m py_compile web_backend.py
+```
+
+```bash
+cd WebSite
+npm run lint
+npm run build
+```
+
+后端烟测：
+
+```bash
+python - <<'PY'
+from web_backend import list_segmentations
+print(list_segmentations('demo_ori_head_ct'))
+PY
+```
+
+使用临时 DICOM mask 文件验证上传解析和 segmentation preview 生成，验证后删除临时文件。
+
+## 手工验证点
+
+- 打开逆向工作区或 DICOM 阅览，加载 CT 数据。
+- 上传或关联真实 DICOM Segmentation Mask。
+- 执行“模型切分”后，右侧“Mask 展示”显示两张二维实心切面图片。
+- 两张图分别对应切分位置上侧/下侧，或确认后的起点帧/终点帧。
+- 图片像素来自 segmentation mask；不显示 3D 外壳、点云、空心模型或 STL Cap。
+- 没有 segmentation 数据时，界面提示需要上传/关联 mask，不生成假图。
+- 切换显示平面或调整切分范围后，双图刷新到对应切面。
+
+## 验收标准
+
+- “Mask 展示”在模型切分后只显示二维实心 Segmentation Mask 双图。
+- 双图数据源为真实 DICOM 语义分割 mask，而非 STL 几何封顶或点云投影。
+- 无 mask 数据时不伪造结果。
+- `python -m py_compile web_backend.py`、`npm run lint`、`npm run build` 均通过。
+- 项目重新部署后 `http://192.168.3.11:3005` 可访问。
+
+## 无法测试的风险
+
+- 若当前环境没有真实 DICOM SEG/语义分割数据，只能验证缺失数据提示和代码结构，无法验证医学空间对齐准确性。
+- 若 segmentation mask 来源不是标准 DICOM SEG，可能需要针对实际格式补充解析和配准逻辑。

工程分析/经验记录.md

@@ -127,3 +127,21 @@ C. 解决问题方案
 D. 后续如何避免问题
 
 涉及 mask 或语义分割结果展示时，应区分“CT 背景叠加图”和“mask-only 结果图”。如果用户要求展示模型切面或分割形态，优先提供独立 mask 图片，并在 UI 上明确区分普通阅览与切分结果。
+
+## 2026-05-08-03-57-51 接入 DICOM SEG 双切面展示
+
+A. 具体问题
+
+用户进一步明确右侧“Mask 展示”不能显示切分后的三维模型外壳、点云、空心模型，也不能用 STL 截面封顶 Cap 作为结果；模型切分后应展示上、下两个二维实心切面，并且像素数据必须来自 DICOM 语义分割影像。
+
+B. 产生问题原因
+
+此前实现虽然把右侧改成了双图，但数据仍可来自 STL 与 DICOM 平面求交后的 mask-only 渲染。该结果属于几何投影/轮廓填充，不等价于真实 DICOM Segmentation Mask label map。
+
+C. 解决问题方案
+
+新增与影像库条目绑定的 DICOM SEG 上传、列表和预览接口，后端将 SEG 像素解析成与 CT 体数据对齐的三维 label map，并按当前切分范围上、下端点渲染二维实心 mask 图片。前端新增 DICOM SEG 上传入口，模型切分后的“Mask 展示”改为请求 segmentation 预览接口；没有绑定 SEG 时只提示缺少数据，不再回退到 STL 生成假结果。
+
+D. 后续如何避免问题
+
+凡是用户明确要求 DICOM 语义分割或 Segmentation Mask 时，不能用 STL、mesh cap、点云投影或图形填充替代。实现前应先确认真实 label map 数据源；若数据源缺失，界面应提示上传或关联，而不是生成看似合理的伪 mask。

工程分析/需求分析-2026-05-08-03-57-51.md

@@ -0,0 +1,52 @@
+# 需求分析 - 2026-05-08-03-57-51
+
+## 原始需求
+
+【需求模块】：逆向工作区 -> 右侧“Mask 展示”面板
+
+【触发条件】：用户在可视化工具栏点击执行“模型切分”操作后。
+
+【当前表现】：“Mask 展示”区目前显示的仍是切分后的三维模型外壳/点云，呈半透明或空心状态。
+
+【期望表现】：“Mask 展示”区需要切换显示为二维的实心截面图像。需要同时展示模型被切开处上、下两个视角的切面。
+
+【数据源要求】：这两个实心切面不能仅仅是 3D 模型的截面封顶 Cap，而必须直接映射并渲染对应的 DICOM 语义分割影像 Segmentation Mask。
+
+## 目标
+
+- 模型切分执行后，右侧“Mask 展示”不再显示 3D 外壳、半透明点云、空心模型或几何封顶。
+- “Mask 展示”改为二维图像区域，并同时展示切分位置上侧、下侧两张实心截面图。
+- 两张截面图的数据源必须来自 DICOM 语义分割影像/Segmentation Mask，而不是由 STL 外壳临时封顶生成。
+- 截面图需与当前 DICOM 切分范围和显示平面保持一致。
+
+## 影响范围
+
+- 前端：
+  - 逆向工作区或 DICOM 阅览弹窗中的“Mask 展示”条件渲染。
+  - 模型切分执行后的右侧双图布局、加载状态和无 mask 状态展示。
+- 后端：
+  - 当前 `web_backend.py` 已有 STL 上传、STL 与 DICOM 切片平面求交 mask 生成逻辑。
+  - 需要新增或接入真实 DICOM Segmentation Mask 数据读取、缓存和二维切片渲染能力。
+- 数据：
+  - 需要确认工程中是否已有 DICOM SEG、RTSTRUCT、NIfTI/NRRD mask、PNG mask 序列或其他语义分割数据源。
+
+## 约束
+
+- 必须遵循仓库 `AGENTS.md` 中的项目修改工作流。
+- 本轮使用统一开始时间戳 `2026-05-08-03-57-51`。
+- 实现方案和测试方案写完后，必须等待用户二次人工审核确认；未经确认不得修改业务代码。
+- 不得用 STL Cap、几何封闭面、点云投影或装饰性填充冒充 DICOM Segmentation Mask。
+- 不得提交 DICOM 原始数据、STL 模型、mask 缓存图、构建产物或凭据。
+
+## 风险点
+
+- 当前仓库现有 mask 逻辑主要来自 STL 三角面与 DICOM 平面的交线填充，不等同于真实 DICOM Segmentation Mask。
+- 如果本项目数据目录中没有现成 segmentation mask 数据源，则仅靠 STL 无法满足“直接映射 DICOM 语义分割影像”的要求，需要先补充数据上传/关联入口。
+- DICOM SEG、RTSTRUCT、NIfTI、NRRD、PNG mask 序列的数据坐标系和 CT 坐标系可能不同，必须处理 spacing、origin、orientation、slice order 和标签值映射。
+- “上、下两个视角”需要在实现中落到明确的切片端点：通常对应当前切分范围的起点帧和终点帧，或当前切割平面的上下两侧相邻 mask 切片。
+
+## 待确认事项
+
+- 当前项目是否已有真实 DICOM Segmentation Mask 文件或目录。如果没有，应由本次新增上传/关联入口，还是由用户先提供数据路径。
+- “上、下两个视角”是指切分范围的起点帧/终点帧，还是同一切割平面上下两侧相邻切片。
+- 需要展示的 mask 标签是否只有一个目标结构，还是多标签语义分割并按标签分别着色。