2026-05-08-01-19-42 优化融合视角和模型位姿控制

工程分析/实现方案-2026-05-08-01-19-42.md

@@ -0,0 +1,108 @@
+# 实现方案 - 2026-05-08-01-19-42
+
+## 修改目标
+
+1. 修复模型库大缩放时构件层级不可见或不可滚动的问题。
+2. 更换逆向工作区侧栏图标，避免与模型库重复。
+3. 优化逆向工作区模型位姿控制：拆分重置按钮、增加 ±90° 旋转、位姿重命名、单击最低刻度、长按连续移动。
+4. 为融合视角增加 DICOM 体数据缓存与五个预存点位。
+5. 在融合视角显示 DICOM 边界框、模型边界框，并以 DICOM 中心作为模型旋转中心。
+6. 增加 DICOM 透明度三档控制。
+7. 增加基于 DICOM 帧的模型切分预览，显示切割面。
+
+## 涉及路径
+
+- `WebSite/src/components/Sidebar.tsx`
+- `WebSite/src/components/ProjectLibrary.tsx`
+- `WebSite/src/components/ReverseWorkspace.tsx`
+- `WebSite/src/lib/api.ts`
+- `WebSite/src/types.ts`
+- `WebSite/server.ts`
+- `工程分析/经验记录.md`
+
+## 技术路线
+
+### 模型库滚动
+
+- 调整项目库 3D 模型页右侧栏为 `min-h-0` + 内部滚动结构。
+- 构件层级列表占用剩余高度，标题和控制区固定，防止浏览器放大后构件列表被挤出。
+
+### 侧栏图标
+
+- 侧栏中模型库继续使用 `Box`，逆向工作区改用 `Workflow` 或 `ScanLine` 类图标，保证含义和视觉不同。
+
+### 位姿控制
+
+- 在逆向工作区可视化工具栏中替换 `重置默认位姿` 为：
+  - `重置旋转位姿`
+  - `重置平移缩放位姿`
+- 旋转 X/Y/Z 增加 `-90°` 和 `+90°` 按钮。
+- 平移和缩放增加正负最小步进按钮。
+- 单击按钮只移动一个最低刻度；鼠标或触摸长按时启动定时器连续移动。
+- 保存位姿列表中允许重命名非默认位姿，默认位姿保持不可改名。
+
+### DICOM 缓存与预存点
+
+- 前端维护 `fusionVolumeCacheRef`，以 `projectId/mode/end` 作为 key 缓存融合体数据。
+- DICOM 切片范围显示五个点位按钮，分别映射 20%、40%、60%、80%、100%。
+- 点击预存点位时优先从缓存读取；缓存未命中则请求接口并写入缓存。
+- 增加“预存五点”按钮，后台并发预取五个点位。
+
+### 边界框与旋转中心
+
+- FusionThreeView 增加 DICOM BoxHelper/LineSegments 边界和模型边界。
+- 模型 STL 顶点以自身中心归一化后，整体 group 的 pivot 固定在 DICOM 体中心。
+- 旋转、缩放围绕 DICOM 中心进行，平移作为模型相对 DICOM 中心的偏移。
+
+### DICOM 透明度
+
+- 新增 `dicomOpacityLevel`，提供低/中/高三档。
+- 传入 FusionThreeView，控制 DICOM 体素切片和切片纹理材质透明度。
+
+### 模型切分
+
+- 新增切割开关、切割帧滑条和切割面显示。
+- Three.js 中使用 DICOM 切片帧在 Z 方向的相对位置作为切割平面。
+- 通过 local clipping plane 对模型材质裁剪，并显示半透明切割面。
+
+## 数据流或交互流程
+
+1. 进入逆向工作区后读取项目与 `moduleStyles`。
+2. Fusion 视角按当前切片范围加载体数据，先查前端缓存，未命中再请求后端。
+3. 用户点击五个点位或预存按钮，前端将对应 `end` 的 DICOM volume 写入缓存。
+4. 用户调整模型位姿，模型围绕 DICOM 中心旋转缩放，并实时更新边界框。
+5. 用户启用模型切分并选择 DICOM 帧，Three.js 使用对应切割平面裁剪模型并显示切割面。
+
+## 兼容性与回滚方案
+
+- 缓存仅存在浏览器内存中，不改变后端数据结构。
+- 新增控制项都保留默认值，旧项目数据可直接使用。
+- 若切割平面对部分浏览器性能影响较大，可关闭切割功能回到原始渲染。
+- 回滚本次 commit 即可恢复。
+
+## 预计文件变更
+
+- `Sidebar.tsx`：调整逆向工作区图标。
+- `ProjectLibrary.tsx`：修复右侧构件层级滚动布局。
+- `ReverseWorkspace.tsx`：增加缓存、预存点、位姿控制、边界框、透明度和切割功能。
+- `api.ts/types.ts/server.ts`：如需支持缓存辅助或类型扩展则同步调整。
+
+## 人工审核状态
+
+用户已声明本次不需要二次人工确认，按默认执行确认规则直接执行。
+
+## 执行记录
+
+- 已将左侧逆向工作区图标从 `Box` 改为 `Workflow`，与模型库图标区分。
+- 已将模型库 3D 模型右侧栏改为整栏滚动结构，解决浏览器放大后构件层级下方内容不可见的问题。
+- 已在逆向工作区模型位姿中增加：
+  - `重置旋转位姿`
+  - `重置平移缩放位姿`
+  - X/Y/Z 的 ±90° 快捷旋转
+  - 旋转/平移/缩放的最低刻度单击步进与长按连续步进
+  - 非默认位姿重命名输入
+- 已在融合视角中增加 DICOM 透明度低/中/高三档。
+- 已在融合视角中增加 DICOM 边界框和模型边界框显示开关。
+- 已将模型旋转中心改为以 DICOM 体中心为 pivot，模型自身偏移放入子节点，避免旋转时围绕模型偏移点运动。
+- 已增加 DICOM 切片范围五个点位和 `预存五点` 功能，前端使用内存 Map 缓存融合体数据。
+- 已增加模型切分开关、切割帧滑条、橙色切割面显示，并通过 Three.js clipping plane 裁剪模型。