# 实现方案 - 2026-05-04-05-56-34

## 修改目标

修正 DICOM 矢状面/冠状面的物理比例，新增 DICOM 详细信息查询；简化 3D 模型显示控制，加入更高实体化档位，并实现画布内鼠标旋转、平移、滚轮缩放且同步整体位姿控件。

## 涉及路径

- `WebSite/server.ts`
- `WebSite/src/types.ts`
- `WebSite/src/lib/api.ts`
- `WebSite/src/components/ProjectLibrary.tsx`
- `工程分析/经验记录.md`

## 技术路线

### 1. DICOM 空间信息解析

- 扩展后端 DICOM tag 解析：
  - Pixel Spacing `(0028,0030)`：单张切片内行/列像素实际距离。
  - Slice Thickness `(0018,0050)`。
  - Spacing Between Slices `(0018,0088)`。
  - Image Position Patient `(0020,0032)`：优先用相邻切片空间位置差计算真实切片间距。
  - Patient、Study、Series、Modality、Manufacturer、Rows、Columns、Window、Rescale 等基础信息。
- 在 DICOM volume cache 中保存 `rowSpacing`、`columnSpacing`、`sliceSpacing`。

### 2. 多平面物理比例重采样

- 当前矢状面/冠状面生成后先得到原始矩阵。
- 根据物理尺寸计算目标比例：
  - 横向：`切片数 * sliceSpacing`
  - 矢状面纵向：`rows * rowSpacing`
  - 冠状面纵向：`columns * columnSpacing`
- 以较小物理间距作为输出采样单位，将重建图像最近邻重采样到接近真实物理比例的像素宽高。
- 返回 `spacing` 和 `physicalSize`，供前端信息展示。

### 3. DICOM 详细信息查询

- 新增后端接口：`GET /api/projects/:projectId/dicom-info`。
- 返回默认项目第一张 DICOM 与序列聚合信息：
  - patient、study、series、image、window、spacing、sequence、source 等分组。
- 前端 DICOM 影像页新增“信息”按钮，打开弹窗/面板展示基本信息、像素间距、切片间距、图像矩阵、物理尺寸、文件数量、首尾文件等。

### 4. 3D 模型控制简化与增强

- 去掉“白色实体”开关和“自动旋转”开关。
- 默认模型不自动旋转，正向放置。
- 实体化档位改为：`预览 / 标准 / 精细 / 超精细`。
- 后端 STL preview 抽样上限提升到 `72000`，前端超精细档使用 `72000`。
- 重置位姿按钮移动到“整体位姿”标题右侧。

### 5. 鼠标/滚轮位姿交互

- 在 `NativeStlViewer` 容器上监听 pointer 和 wheel：
  - 左键拖拽：旋转 X/Y。
  - 右键或 Shift+拖拽：平移 X/Y。
  - 滚轮：缩放。
- 交互时通过 `onPoseChange` 回写 React state，使滑块数值同步变化。
- 禁用浏览器右键菜单，避免右键平移时弹出菜单。
- 位姿仍作用于整体 group，不改变 STL 构件相对位置。

## 数据流或交互流程

1. 前端请求 DICOM preview，后端解析/缓存体数据和空间信息，按真实物理比例输出矢状面/冠状面。
2. 前端点击 DICOM 信息按钮，请求 dicom-info，弹窗展示元数据和空间参数。
3. 前端进入 3D 模型页，按当前实体化档位请求 STL preview。
4. 用户拖拽/滚轮操作画布，`NativeStlViewer` 更新位姿并回写父组件，右侧滑块同步变化。
5. 用户点击重置位姿，模型回到默认正向摆放。

## 兼容性与回滚方案

- 若某些 DICOM tag 缺失，后端使用默认 spacing `1mm`，并在详情中展示“未知/默认”。
- 多平面重采样使用最近邻，避免引入新依赖；如比例异常可回滚到原始矩阵输出。
- 超精细档可能更慢，但保留低档位可回退。
- 鼠标交互只作用于项目库 3D 视图，不影响 DICOM、导出和逆向工作区。

## 预计文件变更

- 后端：DICOM metadata/spacing 解析、多平面重采样、dicom-info API、STL 上限。
- 前端：DICOM 信息弹窗、3D 控件重构、鼠标交互回写位姿。
- 文档：测试结果和经验记录追加。

## 人工审核状态

用户已明确本次无需人工二次确认，文档落地后直接执行。