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

当前工程状态

更新时间：2026-03-25

1. 当前稳定状态

• Rail 路径主链路已稳定：
  • ZUp 模型下，轨上/轨下路径的真实物体与虚拟物体起点、动画、终点贴合正确。
  • YUp 模型下，终端安装仿真、Rail 姿态、真实物体与虚拟物体通行空间、起点与动画主链路已基本跑通。
• 地面路径在 YUp 模型下：
  • 虚拟物体起点姿态、动画姿态、转弯姿态已恢复正常。
  • 真实物体地面路径当前已恢复到可用状态：
    • 起点落位补偿已接入；
    • 逐帧补偿会随当前目标姿态一起旋转，不再使用固定世界补偿矢量；
    • 动画结束后不再因恢复链或重复落最后一帧而再次跳动。
  • Ground + 真实物体 的逐帧姿态约束已经明确：
    • 动画播放阶段只允许绕宿主 up 轴转动；
    • 不再在播放阶段每帧重建完整三维姿态。
  • Ground/Hoisting + 真实物体 的前进轴语义当前已固定：
    • 对象级前进轴统一按 PositiveX 解释；
    • 不再因为路径初始方向更偏 Z 就把对象前进轴自动切换成 PositiveZ。
• 当前已禁止地面/吊装路径偷偷退回旧 yaw 链路。
• 碰撞检测/恢复主链路已稳定：
  • ClashDetective 三维恢复不能再先 ResetPermanentTransform。
  • 碰撞恢复、自动报告、自动截图已重新对齐到动画主链路。
• 虚拟物体资源问题已确认并修复：
  • 旧 unit_cube.nwc 局部几何中心不在原点，会导致虚拟物体中心偏差。
  • 新 unit_cube.nwc 已替换为几何中心在原点的版本。
• 旋转适配入口当前稳定分流：
  • 虚拟物体继续走 HostCoordinateAdapter 的 Legacy 入口；
  • 真实物体走 Direct 入口；
  • 两者不能再强行共用同一条旋转转换链。

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.0 真实物体参考姿态与 Fragment默认Up

• 真实物体不能再默认使用 ModelItem.Transform 或包围盒正交框架当“原始姿态”。
• 当前稳定做法是：
  • 先从 fragment 统计得到代表姿态
  • 再用当前文档级 Fragment默认Up 解释这组 fragment 参考轴
  • 最终得到当前宿主语义下的真实参考姿态
• Fragment默认Up 的真正用途不是“找一个竖直候选轴”，而是：
  • 解释 fragment 参考姿态的原始 Y/Z 语义
  • 把 fragment 参考姿态转换成当前宿主坐标语义下可用的真实姿态
• 当前文档如果 Fragment默认Up 设错，会直接导致：
  • 真实物体起点姿态错误
  • Ground / Hoisting / Rail 的参考姿态解释错误
  • 后续角度修正、通行空间、路径贴合全部建立在错误姿态上
• 当前规则：
  • 先解释真实物体参考姿态，再做路径对齐
  • 不能跳过这一步，直接拿 fragment 世界轴去猜业务姿态
• 当前补充规则：
  • Ground/Hoisting 的真实物体“对象前进轴”与 fragment 参考姿态解释是两层语义；
  • fragment 负责解释真实参考姿态；
  • 对象前进轴当前在 Ground/Hoisting 上固定按 PositiveX 语义使用，不再做“按路径方向选最近轴”的自动切换。

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。
• 当前已知边界：
  • 地面路径播放阶段，真实物体的多轴角度修正还没有完全收稳。
  • 目前稳定可用的是：Y 轴转动。
  • X / Z 轴在起点静态预览或直线段里可能看起来合理，但路径一旦拐弯，逐帧按宿主世界轴重算会让“俯仰/侧倾”语义发生耦合，表现成不符合现场直觉的侧旋。
  • 因此当前阶段，对地面路径应按“只稳定支持 Y 轴转动”使用；X / Z 轴播放链问题留待后续专项修复。
• 当前新增稳定规则（2026-03-25）：
  • Ground + 真实物体 的播放阶段不能再每帧应用完整三维姿态；
  • 必须以起点基姿态为基线，只叠加宿主 up 轴上的单轴旋转。
• 当前新增稳定规则（2026-03-25）：
  • Ground + 真实物体 的起点目标点语义仍然是路径跟踪点，不允许修改路径点本身；
  • 如真实物体起点落位存在固定偏差，应把补偿施加到物体位置，而不是回写路径点或路径跟踪点语义。
• 当前新增稳定规则（2026-03-25）：
  • Ground + 真实物体 的补偿不是固定世界矢量；
  • 起点测得的偏差必须随当前目标姿态一起旋转后，再参与逐帧位置应用。
• 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

4.7 Rail 角度修正

• Rail 的“调整角度”和 Ground / Hoisting 不是同一种实现语义。
• Ground / Hoisting 当前语义：
  • 在内部 Canonical 坐标系里，绕统一 CanonicalUp 做水平角度修正。
• Rail 当前正确语义：
  • 角度修正必须先作用在构件局部轴约定上，等价于“CAD 原位局部预旋转”
  • 然后再进入 Rail 的切向/法向姿态求解
  • 不能在物体已经落到起点后，再在宿主空间对最终 pose 补一个世界轴旋转
• 当前实现链路已经收束到：
  • CanonicalRailPoseBuilder
  • RailPathPoseHelper
  • PathAnimationManager
• 当前规则：
  • Rail 0° 时，必须严格保持当前稳定基线，不允许改变既有 Rail 姿态
  • Rail 有角度修正时，对齐到路径切向的是“修正后的 local forward”
  • Rail 路径切向/法向框架本身不能因为角度修正被改坏
  • Rail 通行空间和真实物体姿态必须共享同一套角度语义，不能一个改局部 footprint、一个改世界 pose
• 调试优先级：
  1. 先验证 0° 基线是否保持不变
  2. 再验证修正后 forward 是否仍沿 rail 切向
  3. 最后再看 Navisworks 应用层是否正确按三步增量姿态落位

4.8 Rail 真实物体必须复用统一姿态解释层

• Rail 不应再单独退回默认 PositiveX / PositiveY 轴约定。
• 当前稳定原则：
  • Ground / Hoisting / Rail 三类路径的真实物体，必须先共用同一个“真实参考姿态解释层”
  • 路径类型的差异只体现在目标路径框架：
    • Ground / Hoisting：up = 宿主 up
    • Rail：up = rail 法向 / preferred normal
• 当前 Rail 真实物体稳定链路：
  1. fragment 代表姿态
  2. Fragment默认Up 解释后的真实参考姿态
  3. Rail 路径框架（切向 / 法向）
  4. 宿主 X/Y/Z 角度修正
• 不要再让 Rail 真实物体单独维护一套与 Ground / Hoisting 不同的对象姿态来源。

4.9 Rail 真实物体的通行空间与路径偏移

• Rail 真实物体的通行空间、起点中心偏移、逐帧法向偏移，必须共享“最终姿态”的同一套尺寸语义。
• 当前稳定规则：
  • 不能只根据“宿主轴角度修正”单独投影尺寸
  • 必须同时吃到：
    • Rail 基姿态
    • 宿主 X/Y/Z 角度修正后的最终姿态
• 否则会出现典型错误：
  • 物体本体姿态正确，但起点偏离路径
  • 单轴旋转时通行空间看起来对，双轴旋转后只跟上一个角度
  • Rail 真实物体通行空间与物体本体方向不一致
• 当前消费规则：
  • AnimationControlViewModel.UpdatePassageSpaceVisualization() 中，真实物体的 Rail 和 Hoisting 必须分开消费
  • Rail 真实物体不能再复用 Hoisting 的法向/分段参数语义

5. 当前保留的日志策略

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

6. 当前 Navisworks 变换 API 结论

• ModelItem.Transform
  • 只表示原始设计文件变换；
  • 不反映 OverridePermanentTransform 后的当前显示姿态。
• ModelGeometry.ActiveTransform
  • 是当前几何实际生效的变换；
  • 当前项目里，凡是要读“当前姿态/当前位置”，优先使用这一层。
• ModelGeometry
  • 关键四层语义：
    • OriginalTransform
    • PermanentOverrideTransform
    • PermanentTransform
    • ActiveTransform
• OverridePermanentTransform(...)
  • 官方语义是增量变换；
  • 不是“直接设成最终世界姿态”。
• ResetPermanentTransform(...)
  • 清掉的是永久增量层；
  • 不会修改原始设计文件变换。

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

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

7. 下一步建议

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

8. 当前阶段的工作边界

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