NavisworksTransport/doc/working/current-engineering-state.md

当前工程状态

更新时间：2026-03-22

1. 当前稳定状态

• Rail 路径主链路已稳定：
  • ZUp 模型下，轨上/轨下路径的真实物体与虚拟物体起点、动画、终点贴合正确。
  • YUp 模型下，终端安装仿真、Rail 姿态、真实物体与虚拟物体通行空间、起点与动画主链路已基本跑通。
• 地面路径在 YUp 模型下：
  • 虚拟物体起点姿态、动画姿态、转弯姿态已恢复正常。
  • 当前已禁止地面/吊装路径偷偷退回旧 yaw 链路。
• 碰撞检测/恢复主链路已稳定：
  • ClashDetective 三维恢复不能再先 ResetPermanentTransform。
  • 碰撞恢复、自动报告、自动截图已重新对齐到动画主链路。
• 虚拟物体资源问题已确认并修复：
  • 旧 unit_cube.nwc 局部几何中心不在原点，会导致虚拟物体中心偏差。
  • 新 unit_cube.nwc 已替换为几何中心在原点的版本。

2. 当前坐标系架构

• 外部坐标：
  • Navisworks 世界坐标，统一视为外部输入坐标。
• 内部统一坐标：
  • Canonical Space，固定 Z-up。
• 业务基准层：
  • ProjectReferenceFrame
  • 球心、项目 up、默认模型轴约定
• 模型局部轴约定：
  • ModelAxisConvention
  • 明确 ForwardAxis / UpAxis
• Rail 局部坐标系：
  • RailLocalFrame
  • Forward / Normal / Lateral

3. 当前关键基础工具

• src/Utils/CoordinateSystem/HostCoordinateAdapter.cs
• src/Utils/CoordinateSystem/ProjectReferenceFrame.cs
• src/Utils/CoordinateSystem/ModelAxisConvention.cs
• src/Utils/CoordinateSystem/CanonicalRailPoseBuilder.cs
• src/Utils/CoordinateSystem/RailLocalFrame.cs
• src/Utils/CoordinateSystem/CanonicalRailOffsetResolver.cs
• src/Utils/CoordinateSystem/CanonicalTrackedPositionResolver.cs
• src/Utils/CoordinateSystem/CanonicalPlanarPoseBuilder.cs

4. 当前必须记住的根因与规则

4.1 Rotation / 矩阵语义

• Rotation3D(a, b, c, d) 的参数顺序是四元数 x, y, z, w。
• 不要再随意在 System.Numerics 矩阵、四元数、Navisworks Rotation3D 之间猜行列语义。
• 新的姿态构造应优先复用已经验证过的坐标框架工具，不要临时手拼矩阵。

4.2 碰撞恢复

• 对受 PathAnimationManager 控制的对象，ClashDetective 验证前绝不能先 ResetPermanentTransform。
• 否则宿主姿态会被清回单位姿态，后续增量恢复会错误地认为“不需要再旋转”。

4.3 动画跟踪点语义

• AnimatedObjectTrackedPosition 的唯一语义：
  • 当前动画主链路使用的跟踪点位置。
• 当前主链路已经切到：
  • 几何中心跟踪。
• 如果后续动画跟踪点再变，数据库和碰撞结果语义必须同步更新。

4.4 虚拟物体资源

• 虚拟物体资源的局部几何中心必须在原点。
• 如果资源局部原点不对，上层姿态和坐标框架再正确，也会表现为固定偏差。
• 日志里优先看：
  • 包围盒中心
  • 目标中心
  • 应用后偏差
• 不要再用虚拟物体 Transform 的即时读回值判断 override 后的真实姿态。

4.5 地面/吊装路径

• 地面/吊装路径已经开始走完整姿态链路，不再允许悄悄退回旧 yaw 方案。
• 如果完整姿态生成失败，应直接暴露错误，而不是 fallback。
• YUp 吊装路径创建主链路已补齐到宿主坐标适配架构：
  • 提升、水平移动、下降、终点落地都不能再把世界 Z 硬编码成“向上”。
  • 终点必须使用用户最后一次点击的地面点，不能回填起点地面高程。
• 吊装路径相关的当前稳定约束：
  • 路径创建、终点补点、路径点修改、斜线正交化、通行空间识别，必须共用同一套“宿主坐标 -> Canonical -> 宿主坐标”的高度语义。
  • 高度过渡点 这类自动生成点，本质上仍是吊装路径点，不能在渲染或可视化阶段再退回旧 ZUp 假设。
  • 通行空间如果遇到“纯垂直段却从前方空中偏出去一截、变成斜的”，优先检查：
  • 垂直段识别是否仍在比较 dz
  • 低点补物体高度是否仍在直接改 Z
  • 吊装水平参考方向是否仍在固定 XY 平面求
• 吊装路径这轮重构后，相关职责已经收束到：
  • HoistingCoordinateHelper
  • PathPlanningManager
  • AerialPathGenerator
  • PathPointRenderPlugin
• 当前规则：
  • 吊装“向上”只能通过宿主 up 语义表达，不能直接写 point.Z +/- height
  • 通行空间垂直延伸必须沿宿主 down 方向补物体高度
  • 吊装水平参考方向必须先剔除宿主 up 分量，再在宿主水平面内求方向
• 吊装路径“设为终点直接结束”如果出现：
  • 核心路径点数正确，但路径列表/路径点列表仍显示为 0
  • 切到别的路径再切回来后才恢复正常
  • 这类问题优先检查 UIStateManager 的 UI 队列消费，而不是先怀疑路径数据或坐标系。
• 本次真实根因已经确认：
  • FinishEditing() 期间会连续追加 CurrentRouteChanged / PathPointsListUpdated / RouteGenerated 等 UI 事件。
  • 旧的 UIStateManager.ProcessQueuedUpdates() 只消费“当前这一批”队列项，执行过程中新增的后续事件会滞留。
  • 所以路径数据其实已经完成，只是 UI 直到下一次路径切换时才把滞留事件顺带处理掉。
• 当前修复原则：
  • UIStateManager 必须持续消费后续批次，直到 UI 队列真正为空。
  • 不要用“手动切换路径”“先选空再选回”“强行补 OnPropertyChanged”这类 UI 和稀泥方式掩盖队列问题。
  • “设为终点直接结束”和“点结束按钮完成路径”都必须走到同样完整的收尾语义：
  • 路径数据完成
  • 当前路径切换完成
  • 路径列表与路径点列表同步完成
• 动画自然结束时，必须先显式应用最后一帧姿态，再进入后续碰撞检测/恢复链路。
  • 否则会出现：
  • 播放停下时视觉上离终点还差一点
  • 碰撞检测开始前又被后续姿态应用“往前补一下”
• 当前播放链路已经统一：
  • 逐帧播放和动画结束落点都复用同一套姿态应用入口
  • 地面/吊装路径如果缺少完整姿态，应直接报错，不能回退旧 yaw
• Rail / Ground / Hoisting 终点诊断日志的比较基准必须是：
  • 该路径类型真实使用的“期望跟踪点/几何中心”
  • 不能再把地面接触点或终点锚点直接拿来和动画跟踪中心比较

4.6 聚焦 / 视点

• ViewpointHelper 的聚焦/俯视逻辑不能再把世界 Z 硬编码成“上方向”。
• 在 YUp 模型里：
  • 相机位置必须沿宿主 HostUpVector 偏移
  • 屏幕上方向也必须通过宿主坐标适配得到
• 如果继续写死：
  • cameraPosition = (x, y, z + distance)
  • upVector = (0, 1, 0)
  • 那么 YUp 模型下聚焦就会跑到侧视图。
• 当前原则：
  • 聚焦输入/输出使用宿主坐标
  • 方向语义通过 HostCoordinateAdapter 明确适配
  • 不要在视点辅助逻辑里直接假设宿主一定是 ZUp

5. 当前保留的日志策略

• 保留：
  • 终点诊断
  • 保存/恢复姿态
  • 关键碰撞恢复
  • 虚拟物体应用后中心/偏差
• 已降级或删除：
  • 大量重复逐帧宿主姿态轴日志
  • 虚拟物体 Transform 即时读回日志（容易误导）

6. 当前还值得继续观察的点

• 空轨路径里仍有一个旧 warning：
  • [空轨] 双轨几何中心线提取失败，退回 OBB 主轴中线
• 这与当前 YUp 地面路径问题无关，但后续可以单独处理。

7. 下一步建议

• 继续按“先框架、先测试、后接业务”的方式推进。
• 新问题优先：
  1. 先看日志
  2. 若日志不足，先补日志
  3. 再补针对性的回归测试
  4. 最后再改业务代码

8. 当前阶段的工作边界

• 不要回到“直接补旧 yaw 链路”的方式。
• 不要再增加隐藏错误的 fallback。
• 不要再混淆：
  • 外部宿主坐标
  • 内部 Canonical 坐标
  • 业务参考点
  • 模型局部轴约定