9.7 KiB
9.7 KiB
坐标系统一架构实施清单
1. 文档目的
本文档基于 coordinate-system-canonical-space-design.md 中的方案，拆解出一份可执行的实施清单。
目标不是一次性全项目重构，而是：
- 先建立“外部坐标 -> 内部统一坐标 -> 业务基准坐标”的边界
- 再优先改造当前最重要的非自动路径规划功能
- 逐步把历史
Z-up假设收口
2. 总体原则
2.1 本轮范围
当前优先范围：
- 终端安装仿真
- Rail 三维姿态
- 动画播放
- 碰撞检测与碰撞恢复
- 辅助线、通行空间、碰撞点相关渲染
当前明确不优先处理：
- 自动路径规划
- 高度检测
- 坡度分析
- 旧网格高度/通道高度相关算法
2.2 内部统一坐标
当前实施目标固定为：
- 内部统一坐标 = Canonical Space = Z-up
2.3 外部坐标定义
当前实施中，统一定义：
- Navisworks API 返回的世界坐标 = 外部坐标
即：
Point3DVector3DBoundingBox3DTransform3DDocument.UpVectorModelItem.BoundingBox()- 鼠标点击拾取点
都先视为外部输入。
3. 里程碑划分
M1. 建立坐标边界层
目标：
- 引入统一的宿主坐标适配器
- 不再在业务代码里直接解释 Navisworks 坐标
M2. 接入终端安装仿真
目标：
- 终端安装仿真不再直接依赖世界原点和世界
Z - 球心与项目 up 都走统一边界层/业务基准层
M3. 接入 Rail 三维姿态
目标：
- Rail 姿态和动画只认内部统一坐标
- 不再在姿态 helper 中写死
(0,0,1)
M4. 接入碰撞恢复和可视化
目标：
- 碰撞报告、碰撞点恢复、自动截图、辅助线渲染统一使用同一套内部语义
4. 任务清单
4.1 M1 建立坐标边界层
Task 1. 新增 HostCoordinateAdapter
目标：
- 建立 Navisworks 外部坐标与内部统一坐标之间的唯一适配入口
建议职责：
ToCanonicalPoint(...)ToCanonicalVector(...)ToCanonicalBounds(...)ToCanonicalTransform(...)FromCanonicalPoint(...)FromCanonicalVector(...)FromCanonicalBounds(...)FromCanonicalTransform(...)
建议要求：
- 统一使用完整三维变换语义
- 不再停留在
GetElevation()/GetHorizontalCoords()这种偏二维接口 - 点、向量、包围盒、旋转、变换都必须有明确变换规则
- 坐标定义中必须显式暴露：
UpAxisElevationAxisHorizontalPlane
验收：
- 对同一组 Navisworks 输入，适配结果在 Y-up 和 Z-up 项目中都能稳定输出 Canonical Space 数据
Task 2. 新增 ProjectReferenceFrame
目标：
- 承载业务基准点，不再把业务基准混进坐标系层
建议职责：
SphereCenterInCanonicalProjectUpInCanonical- 终端安装参考方向
- 轨道参考面
验收：
- 程序内不再把世界原点直接当球心使用
Task 3. 约束边界：禁止业务代码直接解释宿主坐标
目标：
- 收口“谁可以直接碰 Navisworks 坐标”
需要收口的入口：
- 鼠标点击取点
ModelItem.BoundingBox()Transform3DDocument.UpVector- 3D 渲染输入
- 动画对象位姿输出
验收：
- 新功能主链路中，业务代码不再直接从
BoundingBox().Center开始做业务推导
4.2 M2 接入终端安装仿真
Task 4. 改造 PathEditingViewModel
文件：
目标：
- 终端安装辅助线全部改为基于 Canonical Space + ProjectReferenceFrame
重点修改点：
BuildAssemblyReferenceLine()GetAssemblyTerminalAnchorPoint()- 与辅助线、终点锚点、参考方向相关的计算
必须消除：
Vector3D direction = new Vector3D(centerPoint.X, centerPoint.Y, centerPoint.Z);- 直接把世界原点当球心
验收：
- Y-up 项目中，若球心配置正确，辅助线方向与业务预期一致
- Z-up 项目中，行为保持不退化
Task 5. 明确 UI 和日志的坐标语义
目标：
- 终端安装相关 UI、日志输出不混淆内部坐标和外部坐标
建议：
- 内部计算使用 Canonical
- 对用户显示时，明确是否转回 Navisworks 外部坐标
验收：
- 日志中坐标语义一致，不再出现“内部算的是一种，打印的是另一种”
4.3 M3 接入 Rail 三维姿态
Task 6. 改造 RailPathPoseHelper
文件：
目标：
- Rail 姿态计算统一基于 Canonical Space
必须消除：
new Vector3D(0, 0, 1)worldUp = new Vector3D(0, 0, 1)
替换方式：
- 改用适配层提供的 Canonical up
- 或由
ProjectReferenceFrame提供项目参考 up
验收：
- Y-up 项目与 Z-up 项目中，Rail 参考方向一致、俯仰/侧倾逻辑一致
Task 7. 清理 Rail 动画输入边界
涉及文件：
目标：
- 动画内部只消费 Canonical 姿态
- 输出到 Navisworks 时再做反向转换
验收：
- Rail 虚拟物体与真实模型在 Y-up / Z-up 项目中的姿态语义一致
Task 7.1 明确模型局部轴约定
目标：
- 将“模型本地哪个轴代表 forward/up”从隐含假设提升为显式定义
需要覆盖：
- 虚拟物体资源
- 终端安装辅助杆资源
- 真实模型在
Y-up/Z-up项目中的默认局部轴约定
最低要求：
- 至少明确
LocalForwardAxis - 至少明确
LocalUpAxis
验收：
- 不再出现“路径方向和通行空间都正确，但真实模型仍按错误本地 up 站立”的现象
Y-up真实模型与Z-up真实模型都能通过显式局部轴约定接入 Rail 姿态链路
4.4 M4 接入碰撞恢复和渲染
Task 8. 改造碰撞恢复链路
涉及文件：
目标：
- 碰撞点恢复、报告截图、碰撞点回看全部使用统一的内部姿态语义
验收：
- Rail 碰撞报告恢复位置和动画实际姿态一致
- 二维路径不被三维逻辑污染
Task 9. 改造渲染层
文件：
目标：
- 辅助线、通行空间、点标记、碰撞点渲染，不再直接写死
Normal = (0,0,1) - 渲染层不仅要改“中心点/偏移量”，还要统一渲染几何的局部轴语义
验收：
- Y-up 项目中，渲染法向和可视化朝向不再依赖世界 Z
- Y-up 项目中，默认通行空间和
SP模式通行空间的高度轴与宿主 up 一致 - 不再出现“中心点位置正确，但长方体/杆体本体仍按 Z-up 构造”的现象
实施提示：
- 长方体、圆柱体、辅助杆这类几何渲染，必须同时检查：
- 中心点是否正确
right/up/height局部轴是否正确Normal是否仍偷用世界Z
- 不能只修改
ApplyVerticalOffset(...)或中心点偏移，而保留旧的XY + Z轴构造公式
5. 已知问题与注意事项
5.1 当前不应优先展开的模块
以下模块虽然也存在坐标系写死问题，但暂不作为本轮主线：
原因：
- 它们主要服务于自动路径规划
- 当前项目主线优先级不在这里
5.2 不能依赖 fallback 掩盖问题
实施过程中禁止：
- 三维路径恢复失败时偷偷退回
yaw - 外部坐标转换失败时偷偷按世界
Z继续算 - 业务基准点缺失时默认球心为
(0,0,0)
必须让错误显式暴露。
6. 当前实施优先顺序
建议实际推进顺序如下：
HostCoordinateAdapterProjectReferenceFramePathEditingViewModelRailPathPoseHelperPathAnimationManagerCollisionSceneHelperPathPointRenderPlugin
7. 完成判定
当以下条件同时满足时，可认为本轮非自动路径规划坐标系统一改造达到阶段目标：
- 终端安装仿真在 Y-up / Z-up 项目中语义一致
- Rail 三维姿态在 Y-up / Z-up 项目中语义一致
- 动画播放与碰撞恢复姿态一致
- 碰撞报告截图与实际动画姿态一致
- 主链路业务代码中不再直接写死世界原点和世界
Z
8. 备注
本清单服务于“先稳定非自动路径规划主线”的目标，不代表自动路径规划相关模块不重要。
后续如要继续推进全项目坐标系统一，应单独启动自动路径规划相关的第二阶段清理计划。