NavisworksTransport/doc/working/2026-04-08-ground-remove-fragment-dependency-plan.md

Ground 去 Fragment 依赖实施方案

更新时间：2026-04-08

1. 这份方案现在只解决什么

只解决一件事：

• Ground + 真实物体 主链里，尽量去掉 fragment 参考姿态依赖

只允许改动：

• PathAnimationManager.cs
• 必要时补少量日志

明确不做：

• 不新建大范围工具链
• 不改 Hoisting
• 不改 Rail
• 不重写 ModelItemTransformHelper
• 不删除 RealObjectReferencePoseResolver
• 不做“整项目去 fragment”

这份方案的目标是：缩小修改范围，先把 Ground 主链收干净。

---

2. 当前已确认的事实

1. Ground 的变换更适合走最简单的宿主增量法：
   • 宿主旋转增量
   • 宿主平移增量
2. Ground 这条链不应该再扩散 local/reference/fragment 概念。
3. fragment 现在的问题，不在于“所有地方都要立刻删”，而在于：
   • Ground 主链还会读它
   • 导致旋转来源不稳定
4. Ground 这条链仍然有旋转目标，但这个旋转目标不再来自 fragment 参考姿态解释。
5. Ground 后续只需要求：
   • 路径在宿主平面里的方向
   • 对应的宿主平面旋转量
6. 也就是说，Ground 不再求“reference-based pose”，而只求：
   • hostForward
   • hostUp
   • host-planar rotation delta

---

3. 只保留的改造目标

这轮只保留 3 个具体目标：

1. Ground 初始化时，不再优先读 fragment 参考姿态
2. Ground 平面姿态求解时，不再走 fragment 参考旋转入口，而只求宿主平面旋转量
3. Ground 不再允许 fragment planar fallback

只要这 3 点做到，就算这一轮完成。

---

4. 当前 Ground 需要处理的入口

4.1 初始化入口

当前重点看：

• SyncTrackedRotationToObjectReference(...)

要求：

• 当 PathType == Ground 且是真实物体时
• 不再去走 TryCaptureRealObjectReferenceRotation(...)
• 直接改用当前实际几何姿态，或现有非 fragment 入口
• 这一步的目的不是继续建立另一套“参考姿态定义”，而只是拿到当前增量起点

4.2 平面姿态求解入口

当前重点看：

• TryGetRealObjectReferenceRotation(...)
• TryCreateReferenceBasedRealObjectPlanarPoseSolution(...)

要求：

• Ground 不再从这里拿 fragment 参考旋转
• Ground 不再继续求 reference-based pose
• Ground 只求宿主平面旋转量：
  • 路径 hostForward
  • 宿主 hostUp
  • 当前对象在宿主坐标系下要追加的平面旋转量

4.3 fallback 入口

当前重点看：

• ShouldAllowFragmentPlanarFallback(PathType pathType)

要求：

• Ground 改成和 Hoisting 一样，不再允许 fragment planar fallback

---

5. 实施顺序

只按下面顺序做，不扩展：

1. 先改 Ground 初始化入口
2. 再改 Ground 平面姿态求解入口
3. 再改 Ground 尺寸/通行空间入口，避免它们继续偷偷走 reference-based pose
4. 最后关掉 Ground 的 fragment fallback

每一步都要求：

• 先看日志
• 只改 Ground
• 不顺手改别的路径

5.1 2026-04-07 夜间分析结论

第一刀已经证明：

• Ground 初始化入口可以先切掉 fragment
• 但这还不够

这次日志暴露出的真正问题是：

• Ground 虽然不再直接读 fragment
• 但起点姿态求解仍然在走 TryCreateRealObjectPlanarPoseSolution(...)
• 也就是仍然在走 reference-based pose 入口

所以第二刀必须明确成：

1. Ground 不再进入 TryCreateRealObjectPlanarPoseSolution(...)
2. Ground 起点旋转改成：
   • 当前显示旋转
   • 当前宿主平面 yaw
   • 路径目标宿主平面 yaw
   • 基于这三者直接求目标旋转
3. 也就是 Ground 只保留：
   • 当前显示状态作为增量起点
   • 路径方向作为目标方向
   • 宿主平面旋转量作为唯一旋转语义

5.2 现有链路与目标链路

当前代码里，Ground + 真实物体 至少有 3 个入口会接触姿态：

1. 起点
   • MoveObjectToPathStart(...)
   • TryCreatePlanarPathRotationAtStart(...)
   • TryCreateRealObjectPlanarRotationFromHostForward(...)
2. 逐帧
   • ApplyGroundAnimationFrame(...)
3. 尺寸/通行空间
   • TryCalculateCurrentRealObjectPlanarProjectedExtents(...)

这一轮的目标链路应该统一成：

1. 初始化
   • 当前显示姿态只用来拿“当前增量起点”
   • 不再把它包装成 referenceRotation
2. 起点/逐帧旋转
   • 只求 hostForward
   • 只求宿主平面旋转量
   • 不再进入 TryCreateRealObjectPlanarPoseSolution(...)
   • 起点应用层不再走 currentRotation -> targetRotation -> deltaRotation
   • 改成直接施加宿主轴旋转增量，再补平移把 tracked point 拉回目标点
3. 尺寸/通行空间
   • 对 Ground 直接复用固定业务约定：
     • forward = PositiveX
     • up = HostUp
   • 不再通过 reference-based pose 推导 ModelAxisConvention

这 3 条链必须保持同一件事：

• Ground 不再解释 reference pose
• Ground 只解释“当前显示状态 + 路径方向 + 宿主平面旋转量”

---

6. 验证标准

这轮不追求“大而全测试矩阵”，只看 3 条：

1. 起点

   • Ground + 真实物体 到起点后不再读 fragment 姿态

2. 逐帧

   • Ground 播放时旋转来源不再依赖 fragment
   • Ground 只根据路径方向继续求宿主平面旋转量

3. 尺寸/通行空间

   • Ground 的 projected extents 不再因为 fragment/reference pose 缺失而失败
   • Ground 的 ModelAxisConvention 不再来自 TryCreateRealObjectPlanarPoseSolution(...)

4. fallback

   • Ground 关闭 fragment fallback 后，主链要么成功，要么明确报错
   • 不允许再偷偷回退

---

7. 当前停止线

如果做到下面这句话，就先停：

• Ground 主链不再依赖 fragment，但 Hoisting / Rail / 通用参考姿态系统暂时不动。

不要在这一轮里再继续追求：

• 抽象统一工具类
• 清理全部 reference/local 命名
• 一次性删光 fragment 代码
• 统一三类路径的所有姿态入口

这些都属于下一轮的事。

---

8. 2026-04-08 夜间新增：Ground 角度调整的最小实现策略

在 Ground + 真实物体 这条新纯增量链上，角度调整不再通过“完整目标姿态重建”实现，而只允许走最单纯的宿主增量法：

1. up 轴修正

   • 不单独构造三维姿态
   • 直接并入路径目标 yaw
   • YUp 取 YDegrees
   • ZUp 取 ZDegrees

2. 非 up 轴修正

   • 不与 yaw 一次性组合
   • 只在起点落位后，围绕业务跟踪点按宿主轴逐次增量应用
   • 当前约定：
     • YUp：应用 XDegrees、ZDegrees
     • ZUp：应用 XDegrees、YDegrees

3. 逐帧播放

   • 继续只吃“路径宿主平面角 + up 轴修正”
   • 不在每帧重复叠加非 up 轴修正
   • 非 up 轴修正应由起点姿态一次性建立，并在后续 yaw 增量中自然保持

明早优先验证

1. Ground + 真实物体 到起点

   • 位置是否继续保持正确
   • X/Y/Z 角度调整是否真正进入增量旋转链

2. Ground 逐帧播放

   • 转弯是否仍保持当前已修好的效果
   • up 轴修正是否能跟随路径持续生效

3. 非 up 轴修正

   • 是否表现为“起点一次性按宿主轴旋转”
   • 播放过程中不应每帧累加放大