306 lines
15 KiB
Markdown
306 lines
15 KiB
Markdown
# 当前工程状态
|
||
|
||
更新时间：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` 坐标
|
||
- 业务参考点
|
||
- 模型局部轴约定
|