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

实现方案 - 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 裁剪模型。