# 实现方案 - 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 模型整体旋转、平移、缩放。