# 自动调整物体姿态以最小化通行截面投影面积

更新时间：2026-05-27

## 1. 背景

动画检测中的“调整物体”窗口目前支持手工输入 X/Y/Z 三轴角度修正。用户希望增加一个“自动调整”按钮：对任意动画物体，在路径起点处自动寻找一个合适姿态，让物体经过路径上的门洞、狭窄通道时具有最大通过性。

Navisworks 当前主要提供 AABB 包围盒，真实物体的 fragment 代表姿态只能大概判断方向，不足以作为自动调整的精确依据。因此本功能不能依赖 fragment 推断“物体真实方向”，也不能只做绕宿主 up 轴的单轴旋转。单轴 yaw 调整手工即可完成，不满足目标。

## 2. 目标

在“调整物体”窗口增加自动调整能力：

- 支持三轴联动搜索，允许任意三维旋转。
- 允许物体横放、倒放、斜放，不施加运输姿态限制。
- 以路径起点方向为基准，最小化物体在门洞截面上的投影面积。
- 在投影面积相同或接近时，优先选择投影高度更小的姿态，让物体尽量平放。
- 结果写回现有 X/Y/Z 三个角度输入框，用户可继续手工微调。
- 不依赖 fragment 方向作为优化真值。
- 遵守宿主坐标系 / 内部坐标系 / 资产坐标系语义，不硬编码世界 Z 为 up。

## 3. 非目标

- 不在本阶段判断真实门洞尺寸，也不保证某条路径一定可通过。
- 不修改路径规划算法。
- 不重建物体 mesh 或 OBB。
- 不引入姿态限制，例如“保持底面朝下”或“禁止倒置”。
- 不用静默 fallback 掩盖优化失败；失败应明确提示。

## 4. 坐标系语义

UI 输入、日志、用户看到的 X/Y/Z 角度仍按宿主坐标系解释。

路径起点方向使用宿主坐标系点计算：

1. 取路径起点到下一个有效路径点的方向。
2. 剔除宿主 up 分量，得到水平路径前进方向 `HostPathForward`。
3. 通过 `HostCoordinateAdapter` 获取宿主 up：`HostUp`。
4. 截面横向方向为 `HostSide = normalize(cross(HostPathForward, HostUp))`。

如果路径起始段过短或剔除 up 后方向退化，应继续查找后续有效路径段；若仍无法得到方向，则自动调整失败并提示用户。

## 5. 目标函数

自动调整的主目标函数是门洞截面投影面积：

```text
Score(rotation) = ProjectedWidthAcrossPath(rotation) * ProjectedHeightAlongHostUp(rotation)
```

其中：

- `ProjectedWidthAcrossPath`：物体在 `HostSide` 方向上的投影宽度。
- `ProjectedHeightAlongHostUp`：物体在 `HostUp` 方向上的投影高度。
- 路径前进方向上的长度不参与目标函数。

该目标符合“穿门”语义：门洞主要限制的是横向净宽和竖向净高，而不是物体沿路径方向占多长。

在工程现场中，门洞通常“宽度大于高度”，因此仅比较面积不够。两个姿态可能具有相同或非常接近的面积，但一个姿态更高、更窄，另一个姿态更低、更宽；实际通行时应优先选择更低、更平放的姿态。

因此最终排序应采用词典序或近似平局策略：

1. 先最小化 `ProjectedArea`。
2. 当面积差异小于容差时，选择 `ProjectedHeightAlongHostUp` 更小的姿态。
3. 当面积和高度都接近时，再选择 `ProjectedWidthAcrossPath` 更小的姿态。

面积容差建议使用相对容差，例如 `1%`，避免因为 AABB 或浮点误差导致高度明显更优的姿态被面积微小差异淘汰。

## 6. 推荐算法

采用业界常见的黑盒无导数优化路线：

### 6.1 全局粗搜索

在完整三维旋转空间中生成候选姿态，避免只绕某一轴或只优化 yaw。

候选生成应满足：

- 覆盖三维姿态空间。
- 结果确定性，不依赖随机数。
- 粗搜索粒度可配置，默认优先保证交互速度。

可选实现：

- 均匀方向采样加 roll 角采样。
- Fibonacci sphere / icosphere 风格方向采样。
- 固定欧拉角网格作为初始版本，但需要避免只覆盖少量手工角度。

### 6.2 局部精修

对粗搜索评分最好的若干候选执行无导数局部优化，例如：

- Powell method。
- Nelder-Mead simplex。

Navisworks AABB 目标函数不平滑，也不可求导，因此不使用梯度法。局部优化的终止条件应包含：

- 最大迭代次数。
- 角度步长阈值。
- 评分改善阈值。

### 6.3 输出角度

优化器内部可用四元数表示候选姿态，最终需要转换为当前窗口使用的宿主 X/Y/Z 三轴角度修正，并写回：

- `RotationXDegrees`
- `RotationYDegrees`
- `RotationZDegrees`

角度顺序必须遵守项目当前约束：X -> Y -> Z，对应 `qz * qy * qx`。

## 7. 评估方式

第一阶段建议实现为纯几何优化器：

- 输入物体三轴尺寸。
- 输入宿主坐标系下的 `HostPathForward` / `HostSide` / `HostUp`。
- 输入候选旋转。
- 输出截面投影宽度、高度、面积。

这样可以用单元测试充分锁定算法，不需要启动 Navisworks。

真实物体的 fragment 代表姿态不作为优化真值。若后续发现数学预测与 Navisworks 实际 AABB 存在明显偏差，再增加“慢速精确模式”：

1. 保存当前动画物体状态。
2. 临时应用候选姿态到路径起点。
3. 读取 Navisworks 更新后的 AABB。
4. 计算截面投影面积。
5. 恢复状态。

慢速模式必须复用 `PathAnimationManager` / `ModelItemTransformHelper` 的现有姿态链路，不能绕过主链路直接写入临时补丁。

## 8. UI 行为

“调整物体”窗口增加一个“自动调整”按钮。

建议行为：

1. 用户打开“调整物体”窗口。
2. 点击“自动调整”。
3. 系统根据当前路径起点方向、当前物体尺寸和宿主坐标系执行优化。
4. 将最优 X/Y/Z 角度写入输入框。
5. 用户可继续修改角度。
6. 点击“确认”后沿用现有 `ObjectStartPlacementRequest.CreateRotationCorrection(...)` 链路。

自动调整失败时，窗口不关闭，并显示明确错误：

- 未选择路径。
- 路径点不足。
- 起点方向退化。
- 未选择动画物体。
- 物体尺寸无效。
- 优化器未找到有效姿态。

## 9. 测试计划

新增纯几何单元测试，建议放在 `UnitTests/CoordinateSystem/`。

必须覆盖：

- 长方体通过三轴旋转得到比初始姿态更小的截面面积。
- 三轴优化能找到单轴 yaw 无法达到的更小截面面积。
- `YUp` 和 `ZUp` 下 `HostUp` 高度语义正确。
- 路径横向宽度和宿主 up 高度共同参与目标函数。
- 面积接近时优先选择投影高度更小的平放姿态。
- 任意旋转允许倒置，不强制保持原 up 方向。
- 优化结果确定性：同一输入多次运行输出一致。
- 退化路径方向会失败而不是回退默认方向。

后续接入 UI 后，补充 ViewModel 或窗口级测试：

- 点击自动调整后会更新 X/Y/Z 输入值。
- 自动调整后确认仍走现有角度修正请求。
- 失败时保留原输入值。

## 10. 实现落点

候选落点：

- `src/Utils/CoordinateSystem/ObjectPassageProjectionOptimizer.cs`
- `UnitTests/CoordinateSystem/ObjectPassageProjectionOptimizerTests.cs`
- `src/UI/WPF/Views/EditRotationWindow.xaml`
- `src/UI/WPF/Views/EditRotationWindow.xaml.cs`
- `src/UI/WPF/ViewModels/AnimationControlViewModel.cs`

如果需要从 ViewModel 提供路径和尺寸上下文，可新增一个小的请求对象，避免窗口直接依赖大型 ViewModel。

## 11. 风险与注意事项

- Euler 角存在多解和万向节锁风险；优化内部应优先用四元数，Euler 只作为 UI 输出格式。
- AABB 只能近似真实几何，通过性结果应理解为基于包围盒的保守估计。
- 对真实物体，fragment 仅可作为现有动画链路的弱参考，不作为自动调整的优化真值。
- 对 Ground / Hoisting / Rail 的路径姿态链路不得引入旧 yaw fallback。
- 若候选姿态会改变落位补偿，必须同步更新通行空间尺寸和起点预览。