132 lines
5.5 KiB
Markdown
132 lines
5.5 KiB
Markdown
# 当前工程状态
|
||
|
||
更新时间：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` 硬编码成“向上”。
|
||
- 终点必须使用用户最后一次点击的地面点，不能回填起点地面高程。
|
||
- 吊装路径“设为终点直接结束”如果出现：
|
||
- 核心路径点数正确，但路径列表/路径点列表仍显示为 `0`
|
||
- 切到别的路径再切回来后才恢复正常
|
||
- 这类问题优先检查 `UIStateManager` 的 UI 队列消费，而不是先怀疑路径数据或坐标系。
|
||
- 本次真实根因已经确认：
|
||
- `FinishEditing()` 期间会连续追加 `CurrentRouteChanged / PathPointsListUpdated / RouteGenerated` 等 UI 事件。
|
||
- 旧的 `UIStateManager.ProcessQueuedUpdates()` 只消费“当前这一批”队列项，执行过程中新增的后续事件会滞留。
|
||
- 所以路径数据其实已经完成，只是 UI 直到下一次路径切换时才把滞留事件顺带处理掉。
|
||
- 当前修复原则：
|
||
- `UIStateManager` 必须持续消费后续批次，直到 UI 队列真正为空。
|
||
- 不要用“手动切换路径”“先选空再选回”“强行补 OnPropertyChanged”这类 UI 和稀泥方式掩盖队列问题。
|
||
|
||
## 5. 当前保留的日志策略
|
||
|
||
- 保留：
|
||
- 终点诊断
|
||
- 保存/恢复姿态
|
||
- 关键碰撞恢复
|
||
- 虚拟物体应用后中心/偏差
|
||
- 已降级或删除：
|
||
- 大量重复逐帧宿主姿态轴日志
|
||
- 虚拟物体 `Transform` 即时读回日志（容易误导）
|
||
|
||
## 6. 当前还值得继续观察的点
|
||
|
||
- 空轨路径里仍有一个旧 warning：
|
||
- `[空轨] 双轨几何中心线提取失败，退回 OBB 主轴中线`
|
||
- 这与当前 `YUp` 地面路径问题无关，但后续可以单独处理。
|
||
|
||
## 7. 下一步建议
|
||
|
||
- 继续按“先框架、先测试、后接业务”的方式推进。
|
||
- 新问题优先：
|
||
1. 先看日志
|
||
2. 若日志不足，先补日志
|
||
3. 再补针对性的回归测试
|
||
4. 最后再改业务代码
|
||
|
||
## 8. 当前阶段的工作边界
|
||
|
||
- 不要回到“直接补旧 `yaw` 链路”的方式。
|
||
- 不要再增加隐藏错误的 fallback。
|
||
- 不要再混淆：
|
||
- 外部宿主坐标
|
||
- 内部 `Canonical` 坐标
|
||
- 业务参考点
|
||
- 模型局部轴约定
|