2026-05-07-16-35-52 优化3D模型位姿控制

工程分析/实现方案-2026-05-07-16-35-52.md

@@ -0,0 +1,111 @@
+# 实现方案 - 2026-05-07-16-35-52
+
+## 修改目标
+
+围绕项目库 3D 模型预览页，完善整体位姿控制、旋转中心和方位提示：
+
+- 将单个 `重置位姿` 拆为 `重置旋转位姿`、`重置平移缩放位姿`。
+- 旋转 X/Y/Z 增加 `-90°` 和 `+90°` 快捷按钮。
+- 平移 X/Y/Z 增加负向/正向快捷步进按钮，缩放增加缩小/放大快捷按钮。
+- 将模型旋转中心稳定在所有 STL 拼装后整体包围盒的中心。
+- 在 3D 模型画布右下角增加 X/Y/Z 方位坐标提示和当前旋转角度。
+
+## 涉及路径
+
+- `WebSite/src/components/ProjectLibrary.tsx`
+
+## 技术路线
+
+### 1. 拆分重置按钮
+
+新增两个函数：
+
+- `resetModelRotationPose()`
+  - 只重置 `rotateX`、`rotateY`、`rotateZ` 为 `0`。
+  - 保留 `translateX/Y/Z` 和 `scale`。
+- `resetModelTransformPose()`
+  - 重置 `translateX`、`translateY`、`translateZ` 为 `0`，`scale` 为 `1`。
+  - 保留 `rotateX/Y/Z`。
+
+将 `整体位姿` 标题右侧按钮改为两个小按钮：
+
+- `重置旋转位姿`
+- `重置平移缩放位姿`
+
+### 2. 增加快捷调整按钮
+
+为位姿控制行增加快捷按钮：
+
+- 旋转 X/Y/Z：
+  - `-90°`：当前角度减 90，并限制在 `[-180, 180]`。
+  - `+90°`：当前角度加 90，并限制在 `[-180, 180]`。
+- 平移 X/Y/Z：
+  - 负向按钮：每次减 `0.25`。
+  - 正向按钮：每次加 `0.25`。
+  - 仍限制在 `[-2, 2]`。
+- 缩放：
+  - 缩小按钮：每次减 `0.1`。
+  - 放大按钮：每次加 `0.1`。
+  - 仍限制在 `[0.5, 2.5]`。
+
+为避免数值越界和重复逻辑，新增统一的 `clampModelPoseValue()` 和 `nudgeModelPose()`。
+
+### 3. 修正模型旋转中心
+
+当前 STL 预览已经会对 mesh geometry 进行中心化处理。本次进一步显式拆分 Three.js 层级：
+
+- `poseGroup`：负责整体平移。
+- `pivotGroup`：位于模型整体几何中心，负责旋转和缩放。
+- 所有 STL mesh 挂载在 `pivotGroup` 下，并在写入顶点时先减去整体包围盒中心。
+
+动画循环中：
+
+- `poseGroup.position = translateX/Y/Z`
+- `pivotGroup.rotation = rotateX/Y/Z`
+- `pivotGroup.scale = baseScale * scale`
+
+这样模型始终围绕整体包围盒中心旋转，平移不会改变旋转轴心。
+
+### 4. 增加右下角 X/Y/Z 方位提示
+
+在 `NativeStlViewer` 容器中增加绝对定位 overlay：
+
+- 显示三个彩色轴向：X 红色、Y 绿色、Z 蓝色。
+- 显示当前 `rotateX/Y/Z` 数值，随滑块、快捷按钮、鼠标拖拽同步刷新。
+- 放置于画布右下角，避免遮挡左下角 `MODEL PATH` 状态信息。
+
+## 数据流与交互流程
+
+1. 用户点击快捷按钮或拖动滑块。
+2. 前端调用 `updateModelPose()` 或 `nudgeModelPose()`。
+3. `modelPose` React 状态更新。
+4. `NativeStlViewer` 通过 `poseRef` 在 Three.js 动画循环中读取最新状态。
+5. Three.js 更新 `poseGroup` 与 `pivotGroup`。
+6. 右下角方位提示读取同一份 `modelPose` 并更新显示。
+
+## 兼容性与回滚方案
+
+- 修改只影响 3D 模型页面，不影响 DICOM 影像、分割结果、后端 API。
+- 若旋转中心方案出现异常，可回滚到单 group 结构，同时保留 UI 快捷按钮。
+- 若 overlay 影响视觉，可只保留文本角度提示，不影响核心模型显示。
+
+## 预计文件变更
+
+- `WebSite/src/components/ProjectLibrary.tsx`
+  - 新增位姿 clamp/nudge/reset 方法。
+  - 更新整体位姿控制区 UI。
+  - 调整 `NativeStlViewer` 的 group 层级。
+  - 增加右下角方位提示 overlay。
+
+## 人工审核状态
+
+- 实现方案：用户已确认。
+- 确认信息：用户回复“都确认，后续直接搞”。
+
+## 执行结果
+
+- 已在 `WebSite/src/components/ProjectLibrary.tsx` 完成实现。
+- 已拆分 `重置旋转位姿`、`重置平移缩放位姿`。
+- 已为旋转、平移、缩放增加快捷调整按钮。
+- 已将 3D 模型渲染层级拆为平移容器和中心旋转容器。
+- 已新增右下角 X/Y/Z 方位与旋转角度提示。