# 实现方案 - 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 方位与旋转角度提示。