2026-05-07-17-28-34 实现DICOM与模型三维融合视角

2026-05-07 17:36:34 +08:00
parent 97f5c78907
commit cbac61eabc
8 changed files with 930 additions and 174 deletions
--- a/工程分析/实现方案-2026-05-07-17-28-34.md
+++ b/工程分析/实现方案-2026-05-07-17-28-34.md
@@ -0,0 +1,119 @@
+# 实现方案 - 2026-05-07-17-28-34
+
+## 修改目标
+
+在逆向工作区实现三维 DICOM 体与 STL 模型融合视角：
+
+- DICOM 切片范围可控。
+- DICOM 以黑色长方体和多张切片纹理展示。
+- 最后一张切片显示在体表面。
+- STL 模型叠加在 DICOM 体中。
+- 用户可以调整模型位姿。
+- DICOM 和 STL 可以一起旋转、平移、缩放观察。
+
+## 涉及路径
+
+- `WebSite/server.ts`
+- `WebSite/src/types.ts`
+- `WebSite/src/lib/api.ts`
+- `WebSite/src/components/ReverseWorkspace.tsx`
+
+## 技术路线
+
+### 1. 后端新增 DICOM 融合体接口
+
+新增接口：
+
+```text
+GET /api/projects/:projectId/dicom-fusion-volume?start=0&end=49&mode=soft
+```
+
+返回内容：
+
+- `width`、`height`
+- `start`、`end`、`total`
+- `indices`
+- `frames`：每张切片灰度图 base64
+- `spacing`：row/column/slice
+- `physicalSize`：width/height/depth
+
+为控制传输和纹理压力：
+
+- 单次最多返回 64 张切片。
+- 纹理最大边长限制为 256。
+- 使用已有 `getDicomVolume()` 和 `resampleNearest()`，避免重复实现 DICOM 解析。
+
+### 2. 前端新增类型与 API
+
+- 在 `types.ts` 新增 `DicomFusionVolume`。
+- 在 `api.ts` 新增 `getDicomFusionVolume(projectId, start, end, mode)`。
+
+### 3. 重构融合视角为 Three.js 场景
+
+在 `ReverseWorkspace.tsx` 中新增 `FusionThreeView`：
+
+- 创建 Three.js scene/camera/renderer。
+- DICOM：
+  - 用半透明黑色 box 表示 CT 体。
+  - 将范围内切片转为 `CanvasTexture`。
+  - 按切片索引在 Z 方向分层放置。
+  - 最后一帧贴到体表面并提高不透明度。
+- STL：
+  - 调用已有 STL preview 接口加载模型构件。
+  - 使用后端返回 `bounds` 合成稳定模型中心。
+  - 将模型挂到 `modelGroup`。
+- 场景：
+  - DICOM 体和模型都放入 `fusionRoot`，整体旋转和平移缩放作用在 `fusionRoot`。
+  - 模型位姿单独作用在 `modelPoseGroup`。
+
+### 4. 交互与控制
+
+- 鼠标左键拖拽：旋转整体融合场景。
+- Shift/右键拖拽：平移整体融合场景。
+- 滚轮：缩放整体融合场景。
+- UI 控件：
+  - 切片起点、切片终点。
+  - 模型旋转 X/Y/Z。
+  - 模型平移 X/Y/Z。
+  - 模型缩放。
+  - 重置模型位姿。
+
+## 数据流或交互流程
+
+1. 进入逆向工作区后加载项目详情。
+2. 根据默认切片范围请求 DICOM 融合体数据。
+3. 请求 STL preview 并加载模型。
+4. Three.js 创建 DICOM 体和 STL 模型。
+5. 用户拖拽场景时 DICOM 与 STL 一起旋转。
+6. 用户调整模型位姿时只改变 STL 模型相对 DICOM 的位置。
+7. 用户调整切片范围时重新请求 DICOM 融合体数据并刷新 CT 体。
+
+## 兼容性与回滚方案
+
+- 若 WebGL 不可用，显示加载失败/不支持提示，不影响其他页面。
+- 若融合体接口失败，保留逆向工作区其他 mask 导出功能。
+- 若性能不足，可降低最大返回切片数和纹理尺寸。
+
+## 预计文件变更
+
+- `WebSite/server.ts`
+  - 新增 `createDicomFusionVolume()` 和 API route。
+- `WebSite/src/types.ts`
+  - 新增 `DicomFusionVolume` 类型。
+- `WebSite/src/lib/api.ts`
+  - 新增 `getDicomFusionVolume()`。
+- `WebSite/src/components/ReverseWorkspace.tsx`
+  - 新增 Three.js 融合视角组件和位姿控制。
+
+## 人工审核状态
+
+- 本次免二次确认，方案写入后直接执行。
+
+## 执行结果
+
+- 已新增 `GET /api/projects/:projectId/dicom-fusion-volume`，支持按 `start/end/mode` 返回一段轴向 DICOM 体数据纹理。
+- 已新增 `DicomFusionVolume` 类型和 `api.getDicomFusionVolume()`。
+- 已将逆向工作区 `影像与模型融合视角` 重构为 Three.js 三维场景。
+- 已实现黑色 DICOM 长方体、范围内切片纹理层叠、最后一帧体表面显示。
+- 已将 STL 模型加载进同一融合场景，可通过模型位姿控件相对 DICOM 体调整。
+- 已支持鼠标拖拽/滚轮对 DICOM 体和 STL 模型整体旋转、平移、缩放。
--- a/工程分析/测试方案-2026-05-07-17-28-34.md
+++ b/工程分析/测试方案-2026-05-07-17-28-34.md
@@ -0,0 +1,51 @@
+# 测试方案 - 2026-05-07-17-28-34
+
+## 静态检查
+
+1. `git status --short --branch`
+2. `cd WebSite && npm run build`
+3. `cd WebSite && npm run lint`
+
+## 单元或集成测试
+
+当前项目没有独立单元测试体系，本次采用构建、类型检查、API 冒烟和页面运行时验证。
+
+## 关键业务场景验证
+
+1. 打开 `http://192.168.3.11:4000/`。
+2. 进入 `逆向工作区`。
+3. 验证 `影像与模型融合视角` 出现三维融合场景。
+4. 验证 DICOM 体是黑色长方体，体表面显示当前范围最后一张切片。
+5. 调整切片起点/终点：
+   - 显示范围变化。
+   - 范围文本同步变化。
+   - 场景重新加载后仍可交互。
+6. 验证 STL 模型叠加在 CT 体上。
+7. 鼠标拖拽整体场景：
+   - DICOM 体和 STL 模型一起旋转。
+8. 调整模型位姿：
+   - 只有 STL 模型相对 DICOM 体移动或旋转。
+9. 验证 `开始自动配准`、`导出 NII.GZ` 按钮仍可操作。
+
+## 医学影像数据相关边界验证
+
+- 融合接口最多返回 64 张切片，避免过量纹理。
+- 切片起止范围需要 clamp 到 `[0, dicomCount - 1]`。
+- DICOM spacing 与 physicalSize 需要从现有体数据缓存中输出。
+
+## 回归风险
+
+- Three.js 纹理和 STL 共同渲染会增加 GPU 压力。
+- 逆向工作区布局变更可能影响 Mask 选择和导出信息。
+- 当前融合为归一化同场景叠加，不是最终医学空间刚性配准矩阵。
+
+## 人工审核状态
+
+- 本次免二次确认。
+
+## 执行记录
+
+- `npm run lint`：通过，实际执行 `tsc --noEmit`。
+- `npm run build`：通过。
+- 重新部署后 `curl -I http://127.0.0.1:4000/`：返回 `HTTP/1.1 200 OK`。
+- 重新部署后请求 `GET /api/projects/head-ct-demo/dicom-fusion-volume?start=0&end=49&mode=soft`：返回 `width=256`、`height=256`、`start=0`、`end=49`、`total=300`、50 个切片索引、spacing 和 physicalSize。
--- a/工程分析/经验记录.md
+++ b/工程分析/经验记录.md
@@ -631,3 +631,21 @@ C. 解决问题方案
 D. 后续如何避免问题

 模型显示档位应明确区分“性能抽样”和“实体查看”；若新增高质量档位，需要同步检查前端请求 limit、后端 clamp、材质表现和浏览器性能边界。
+
+## 2026-05-07-17-28-34 逆向工作区三维融合视角
+
+A. 具体问题
+
+逆向工作区原来的 `影像与模型融合视角` 只是二维 DICOM 图片和示意轮廓叠加，不能表现 DICOM 体数据、切片范围、STL 模型同场景融合，也不能让 DICOM 和模型作为整体旋转观察。
+
+B. 产生问题原因
+
+早期实现更偏演示界面，没有后端接口提供一段 DICOM 体数据纹理；前端也没有 Three.js 融合场景，只是在二维 canvas 上放置静态标注层。
+
+C. 解决问题方案
+
+新增 `dicom-fusion-volume` 后端接口，按起止切片返回最多 64 张、最大 256 像素边长的轴向 CT 纹理和 spacing/physicalSize；前端逆向工作区新增 Three.js 融合场景，将 DICOM 渲染为黑色长方体和切片纹理，将 STL preview 模型加载到同一场景，并提供切片范围与模型位姿控件。
+
+D. 后续如何避免问题
+
+融合、配准、体素化相关视图应优先使用三维数据结构，而不是二维示意图；DICOM 体数据接口必须限制切片数量和纹理尺寸，保证浏览器交互稳定；模型相对 DICOM 的调整和整体场景观察要分开管理。
--- a/工程分析/需求分析-2026-05-07-17-28-34.md
+++ b/工程分析/需求分析-2026-05-07-17-28-34.md
@@ -0,0 +1,63 @@
+# 需求分析 - 2026-05-07-17-28-34
+
+## 原始需求摘要
+
+用户要求在 `逆向工作区 - 影像与模型融合视角` 中实现真实的 DICOM 与 3D 模型融合浏览：
+
+1. 将 DICOM 转为三维影像体。
+2. DICOM 可以按切片范围显示，例如显示第 1 到第 50 张。
+3. DICOM 在三维中表现为一个黑色长方体，表面显示待显示范围的最后一帧图片。
+4. 3D 模型叠加在 DICOM 体上方。
+5. 可以调整模型位姿。
+6. DICOM 与模型可以一起旋转，最终达到模型显示在 CT 上的效果。
+7. 本次需求分析、实现方案、测试方案、执行修改都不需要人工二次确认。
+
+## 业务目标
+
+- 将逆向工作区从二维示意融合升级为三维 DICOM 体与 STL 模型同场景融合。
+- 为后续模型逆向体素化和 DICOM 分割标注提供更接近真实配准场景的交互基础。
+- 支持用户通过切片范围控制 CT 体显示，并通过模型位姿微调对齐模型。
+
+## 输入与输出
+
+输入：
+
+- 当前项目 `Head_CT_DICOM` 的 DICOM 切片序列。
+- 当前项目 `Head_CT_ReConstruct` 的 STL 模型构件。
+- 用户选择的 DICOM 切片起止范围。
+- 用户拖拽/滚轮旋转缩放整体场景，以及通过控件调整模型位姿。
+
+输出：
+
+- 逆向工作区中出现三维融合视角。
+- DICOM 以黑色体数据长方体展示，最后一帧贴在体表面。
+- 选定范围内的 CT 切片以半透明层叠方式呈现。
+- STL 模型叠加在 CT 体上，可单独调整模型位姿。
+- DICOM 体和 STL 模型作为一个场景整体旋转查看。
+
+## 影响范围
+
+- `WebSite/server.ts`
+  - 新增 DICOM 融合体数据接口。
+- `WebSite/src/types.ts`
+  - 新增融合体数据类型。
+- `WebSite/src/lib/api.ts`
+  - 新增融合体数据请求方法。
+- `WebSite/src/components/ReverseWorkspace.tsx`
+  - 重构影像与模型融合视角为 Three.js 三维融合场景。
+  - 新增切片范围控制、模型位姿控制、整体视角交互。
+
+## 风险点
+
+- 一次性加载过多 DICOM 切片会导致接口响应和 WebGL 纹理压力较大。
+- STL 与 DICOM 的真实坐标系还没有完整医学空间配准矩阵，本次属于同场景归一化融合和手动位姿调整。
+- 透明 CT 切片过多可能遮挡模型，需要控制默认范围和透明度。
+- 逆向工作区当前布局还有 Mask 展示等内容，融合视角变为三维后需要保持布局可用。
+
+## 待确认问题
+
+- 本次用户已明确免二次确认，直接执行。
+
+## 人工审核状态
+
+- 本次免二次确认。