refine hoisting path fixes

2026-04-09 23:09:56 +08:00 · 2026-04-09 23:09:56 +08:00 · 144ee4e6b2
commit 144ee4e6b2
parent 4fbab52880
1 changed files with 134 additions and 0 deletions
--- a/doc/working/2026-04-06-navisworks-transform-api-official-reference.md
+++ b/doc/working/2026-04-06-navisworks-transform-api-official-reference.md
@ -1010,3 +1010,137 @@ incremental = target * current.Inverse()

 - **只有最简单的宿主坐标系增量法，才能尽量无副作用地做真实物体变换。**
 - **旋转和平移不需要物体局部映射，局部坐标的概念可以从这条变换链里彻底移除。**
+
+---
+
+## 28. 2026-04-09 Ground 真实物体增量链追加结论
+
+以下结论来自 2026-04-09 对 `Ground + 真实物体` 的连续回归：
+
+- 起点落位
+- `X / Y / Z` 角度调整
+- 逐帧动画
+- 通行空间尺寸
+
+以及同一对象在 Navisworks 中的实际可视结果与日志对照。
+
+### 28.1 Ground 角度调整的正确主语
+
+对 `Ground + 真实物体`，角度调整的正确主语仍然只有：
+
+- 宿主世界 `X` 轴
+- 宿主世界 `Y` 轴
+- 宿主世界 `Z` 轴
+
+也就是说：
+
+- `XDegrees` 就是绕宿主 `X` 轴的增量
+- `YDegrees` 就是绕宿主 `Y` 轴的增量
+- `ZDegrees` 就是绕宿主 `Z` 轴的增量
+
+不需要再额外解释：
+
+- 物体当前局部轴
+- 参考姿态
+- 基姿态
+- fragment 代表姿态
+- 局部轴业务映射
+
+### 28.2 角度调整必须按“单轴增量”逐次应用
+
+本轮实验已经验证：
+
+- `Ground` 的角度调整不能先重建“完整目标姿态”
+- 也不能把多个轴的旋转先合成为一份“总姿态”再去应用
+
+更稳定的工程做法是：
+
+1. 对当前物体直接叠加一个宿主轴旋转增量
+2. 一次只处理一个轴
+3. 非 `up` 轴修正做完后，再处理路径方向对应的 `yaw`
+4. 最后再做平移补偿 / tracked point 对齐
+
+一句话：
+
+- **Ground 真实物体的角度调整应实现为“直接对物体叠加宿主轴增量”，而不是“先解释姿态，再重建目标姿态”。**
+
+### 28.3 不要从当前显示姿态反解新的平面角
+
+本轮实际问题证明：
+
+- 对 `X / Z` 非 `up` 轴修正，如果先应用一次宿主轴增量
+- 再从修正后的当前显示姿态里重新反解 `currentYaw`
+- 很容易把非平面旋转的结果错误混入后续平面转向链
+
+对 `Ground` 这条链，更稳定的做法是：
+
+- 非 `up` 轴修正只负责自身的单轴增量旋转
+- 路径 `yaw` 仍然只作为“平面转向”处理
+- 不再把前一步的三维旋转结果重新解释成新的 `yaw` 起点
+
+### 28.4 Ground 通行空间的正确数学模型
+
+对 `Ground + 真实物体` 的通行空间，当前验证通过的最简单数学模型是：
+
+1. 先确定一组固定的宿主语义尺寸：
+   - `forward`
+   - `side`
+   - `up`
+2. 再只根据宿主轴角度修正，计算旋转后的：
+   - `forwardExtent`
+   - `sideExtent`
+   - `upExtent`
+3. 不再把这组三个尺寸二次投影到 `pathForward`
+
+原因是：
+
+- 渲染器本身已经会把：
+  - `along`
+  - `across`
+  - `normal`
+  摆到路径上
+- 如果在尺寸链里再按路径方向投影一次，就会把路径方向重复计算
+
+因此对 `Ground` 通行空间，更合理的输入应当是：
+
+- 角度修正后的宿主语义尺寸
+
+而不是：
+
+- 再投影到路径方向后的尺寸
+
+### 28.5 当前已补齐的最小数学测试集合
+
+本轮已经在：
+
+- [RotatedObjectExtentHelperTests.cs](/C:/Users/Tellme/apps/NavisworksTransport-rail-mount-modes/UnitTests/CoordinateSystem/RotatedObjectExtentHelperTests.cs)
+
+补齐 `Ground / YUp` 下的宿主轴尺寸测试，包括：
+
+- `X / Y / Z`
+- `45 / 90 / 135 / 180 / 270`
+
+这些测试锁住的不是业务解释，而是最基础的数学结论：
+
+- 一个长方体在宿主语义尺寸下
+- 经宿主轴旋转后
+- `forward / side / up` 三个尺寸应如何变化
+
+### 28.6 当前可以正式采用的 Ground 工程约束
+
+对 `Ground + 真实物体`，当前可以正式采用以下工程约束：
+
+1. 起点、角度调整、逐帧动画都优先走宿主坐标系增量链。
+2. `X / Y / Z` 角度调整一次只处理一个宿主轴，不重建总姿态。
+3. `yaw` 只处理平面路径转向，不再承担三维姿态解释职责。
+4. 通行空间只消费“角度调整后的宿主语义尺寸”，不再重复按路径方向投影。
+5. 这条链不再传播：
+   - 基姿态
+   - 参考姿态
+   - 局部轴映射
+   - fragment 代表姿态
+   这些概念作为变换主语。
+
+一句话总结：
+
+- **Ground 真实物体这条链，已经证明“宿主轴单轴增量 + 平面 yaw + 平移补偿”是目前最稳定、最可控的实现方式。**