2026-05-20-02-15-10 优化融合视角方向标识

工程分析/实现方案-2026-05-20-02-15-10.md

@@ -0,0 +1,56 @@
+# 实现方案-2026-05-20-02-15-10
+
+## 实现方案文档路径
+
+`工程分析/实现方案-2026-05-20-02-15-10.md`
+
+## 修改目标
+
+缩小“影像与模型融合视角”右下角 XYZ 标识，并将其从静态 SVG 改为随模型位姿和三维场景旋转联动的方向指示器。
+
+## 涉及路径
+
+- `WebSite/src/components/ReverseWorkspace.tsx`
+- `工程分析/需求分析-2026-05-20-02-15-10.md`
+- `工程分析/实现方案-2026-05-20-02-15-10.md`
+- `工程分析/测试方案-2026-05-20-02-15-10.md`
+- `工程分析/经验记录.md`
+
+## 技术路线
+
+1. 新增轴向投影数据结构：
+   - 定义 X/Y/Z 三个方向在屏幕 inset SVG 中的投影向量。
+   - 提供默认轴向，避免 DICOM/模型未加载时空白。
+2. 改造 `CoordinateAxesInset`：
+   - 视觉尺寸由 72px 缩小到约 54px。
+   - 线段终点、标签位置和透明度由投影数据驱动。
+3. 在 `FusionThreeView` 中计算动态方向：
+   - 在 Three.js animation loop 中让 `fusionRoot` 和 `modelPoseGroup` 更新矩阵。
+   - 读取 `modelPoseGroup.getWorldPosition()` 与 `getWorldQuaternion()`。
+   - 将模型局部 X/Y/Z 方向投影到当前 camera 屏幕空间。
+   - 仅在投影签名变化时更新 React 状态，减少无意义重渲染。
+
+## 执行步骤
+
+- 增加 AxisProjection 类型、默认值和投影辅助函数。
+- 改造坐标轴 inset 的 SVG 尺寸和绘制逻辑。
+- 在融合视图动画中调用投影计算并传给 inset。
+- 执行 `npm run lint` 和 `npm run build`。
+- 追加经验记录、提交、推送并重新部署。
+
+## 兼容性与回滚方案
+
+- 如果动态投影出现异常，默认轴向仍可显示。
+- 不修改 DICOM/STL 真实数据、模型位姿状态和实际渲染变换，仅增加可视化辅助。
+- 回滚只需恢复 `CoordinateAxesInset` 为静态 SVG。
+
+## 预计文件变更
+
+- `ReverseWorkspace.tsx`：动态坐标轴投影与缩小样式。
+- 工程分析文档：新增本次三份文档，更新经验记录。
+
+## 提交与部署策略
+
+- Commit message：`2026-05-20-02-15-10 优化融合视角方向标识`
+- 显式暂存本次相关文件，避免提交历史删除状态。
+- 推送到 Gitea `origin/main`，并使用 `tmux` 会话 `revoxelseg-dicom` 重新部署。

工程分析/测试方案-2026-05-20-02-15-10.md

@@ -0,0 +1,52 @@
+# 测试方案-2026-05-20-02-15-10
+
+## 测试方案文档路径
+
+`工程分析/测试方案-2026-05-20-02-15-10.md`
+
+## 静态检查
+
+- 在 `WebSite/` 下执行 `npm run lint`。
+
+## 构建检查
+
+- 在 `WebSite/` 下执行 `npm run build`。
+
+## 关键业务场景验证
+
+- “影像与模型融合视角”右下角 XYZ 标识尺寸比旧版更小。
+- 调整模型旋转 X/Y/Z 后，右下角 XYZ 方向随模型世界方向变化。
+- 拖拽旋转三维融合视角后，右下角 XYZ 方向随场景旋转变化。
+- 右下角标识不阻挡画布拖拽、滚轮缩放、右键/Shift 平移。
+
+## 医学影像数据相关边界验证
+
+- 该改动不改变 DICOM 体数据、STL 模型加载、FOV、右侧映射视图和 NIfTI 导出逻辑。
+- 模型位姿状态仍是右侧映射和分割导出的权威输入。
+
+## 部署验证
+
+- 重启 `tmux` 会话 `revoxelseg-dicom`。
+- 验证：
+  - `curl http://127.0.0.1:4000/api/health`
+  - `curl -I http://127.0.0.1:4000/`
+
+## Git/Gitea 备份验证
+
+- 显式暂存本次相关代码和文档。
+- 创建包含时间戳和描述的 commit。
+- 推送到 Gitea `origin/main`。
+
+## 实测结果
+
+- `npm run lint`：通过。
+- `npm run build`：通过；仅保留 Vite chunk size 提醒。
+- 代码检查确认右下角方向标识尺寸从 72px 缩小为 54px。
+- 代码检查确认方向标识由 `modelPoseGroup.getWorldPosition()` 和 `getWorldQuaternion()` 投影生成，会包含模型位姿和 `fusionRoot` 场景旋转。
+- 代码检查确认方向投影使用签名去重，避免每帧无条件触发 React 状态更新。
+
+## 风险与回归关注点
+
+- 避免每帧无条件触发 React 状态更新。
+- 避免提交历史工程文档删除状态。
+- 保持右下角标识在 DICOM 未加载时也有默认可见状态。

工程分析/经验记录.md

@@ -1081,3 +1081,21 @@ C. 解决问题方案
 D. 后续如何避免问题
 
 成对设计导入/导出功能时，应把导出样例作为导入测试用例，同时兼容最小可用对象。导入端必须对字段缺失、字符串数字、越界数值和重复 id 做归一化处理。
+
+## 2026-05-20-02-15-10 三维方向标识必须来自真实世界矩阵
+
+A. 具体问题
+
+右下角 XYZ 标识原先是静态 SVG，无法随模型旋转位姿和三维融合场景拖拽旋转变化；用户调整模型后，标识仍显示固定方向，容易误导“平移 X/Y/Z 后模型会往哪里移动”的判断。
+
+B. 产生问题原因
+
+旧标识只是界面装饰，没有读取 Three.js 中 `fusionRoot` 和 `modelPoseGroup` 的实时变换。模型实际显示方向由场景根节点旋转、模型位姿旋转和相机投影共同决定，静态二维箭头无法表达这个组合结果。
+
+C. 解决问题方案
+
+新增轴向投影辅助函数，在动画循环中读取 `modelPoseGroup` 的 world position 与 world quaternion，将模型局部 X/Y/Z 方向投影到当前 camera 屏幕空间，再驱动右下角小 SVG 的线段终点。使用投影签名去重，只有方向变化时才更新 React 状态。
+
+D. 后续如何避免问题
+
+凡是三维视图中的方向、法向、切面或平移提示，都应从 Three.js 真实对象矩阵或统一坐标变换链路推导，不能手写静态示意。若该提示会随拖拽视角变化，还必须包含场景根节点和相机投影。

工程分析/需求分析-2026-05-20-02-15-10.md

@@ -0,0 +1,46 @@
+# 需求分析-2026-05-20-02-15-10
+
+## 开始时间
+
+2026-05-20-02-15-10
+
+## 原始需求摘要
+
+用户要求将“影像与模型融合视角”右下角的 XYZ 标识缩小，并让该标识根据模型旋转位姿和三维场景视角变化实时旋转，用来表达模型执行平移 X/Y/Z 后的实际移动方向。
+
+## 业务目标
+
+- 降低右下角方向标识对三维融合视图的遮挡。
+- 将静态方向标识升级为动态方向指示器。
+- 让用户在调整模型位姿和拖拽三维场景后，仍能理解平移 X/Y/Z 在当前视角下的方向含义。
+
+## 输入与输出
+
+- 输入：
+  - 可视化工具栏中的模型旋转位姿。
+  - 三维融合视图内鼠标拖拽产生的场景旋转。
+- 输出：
+  - 右下角更小的 XYZ 指示器。
+  - 指示器中的 X/Y/Z 方向随当前模型世界方向投影实时更新。
+
+## 影响范围
+
+- `WebSite/src/components/ReverseWorkspace.tsx`
+- 工程分析文档与经验记录。
+
+## 关键约束
+
+- 坐标轴标识不能影响三维场景交互，仍然保持 `pointer-events-none`。
+- 标识需要使用当前 `modelPoseGroup` 世界矩阵/四元数，不做另一套独立的视觉猜测。
+- 不修改实际模型平移逻辑，只让方向标识准确反映当前视角下的方向。
+
+## 风险点
+
+- 如果每帧强制 React 大量重渲染，可能影响三维场景流畅度。
+- 如果只读取模型位姿而不读取场景根节点旋转，用户拖动三维视角后标识会再次失真。
+- 如果标识过小，标签可读性可能下降。
+
+## 默认假设
+
+- “三维场景中的移动”按当前融合视图的场景旋转/拖拽视角理解；场景平移不会改变方向，因此方向标识主要跟随旋转。
+- 方向标识表达的是当前屏幕视角下 X/Y/Z 平移方向，不作为绝对医学坐标系标尺。