NavisworksTransport/doc/design/2026/linear-assembly-reference-path.md

终点反推的直线装配路径设计

背景

当前空轨路径已经扩展出轨上/轨下、顶面对接/底面对接、局部姿态等能力，但用户进一步澄清了真实业务：

• 已知箱体最终安装后的准确位置和空间方向
• 该场景只需要一条起点到终点的直线运动
• Navisworks 里用户无法点击空气中的点，必须点击到某个实际对象

因此，这类路径不应继续建模为“轨道识别”问题，而应建模为“已知终点位姿的直线装配运动”问题。

核心思路

1. 终点位姿作为主输入

由用户选择终点处已经组装好的箱体，系统读取：

• 包围盒
• 当前朝向
• 终点构件中心 / 顶面中心 / 底面中心

终点位姿是整个运动仿真的主基准。

2. 生成可点击的参考杆

为了满足 Navisworks 的点击限制，系统不只绘制一条渲染线，而是生成一个临时参考实体：

• 形态：细长杆体
• 初版建议：直接复用 unit_cube.nwc，通过缩放生成细长方杆
• 作用：
  • 可视化直线参考路径
  • 允许用户点击取点
  • 为起点吸附提供稳定对象

3. 用户点击参考杆确定起点

用户在三维视图中点击参考杆上的某个位置后：

• 获取点击坐标
• 将点击点投影到参考杆轴线
• 该投影点作为真实起点

4. 生成最终直线路径

系统根据：

• 起点
• 终点位姿
• 轨上/轨下
• 顶面对接/底面对接

生成直线路径点列，并继续复用现有：

• 动画
• 通行空间
• 碰撞检测

与当前 Rail 方案的关系

保留

• RailMountMode
• RailPayloadAnchorMode
• RailPathDefinitionMode
• RailPathPoseHelper
• 动画完整姿态支持

这些都仍然有价值，因为终点和路径参考点之间仍需要姿态推导。

弱化 / 退出主路径

• 轨道几何识别
• 双轨自动分析
• 基于轨道装置的中心线提取

这些能力可保留为辅助模式，但不再作为该场景的主生成逻辑。

最小可行实现

Phase 1

新增“终点反推参考杆”基础能力：

• 选择终点箱体
• 读取终点包围盒和朝向
• 生成参考杆临时实体
• 支持显示 / 隐藏 / 更新参考杆

Phase 2

新增“点击参考杆生成直线路径”：

• 用户点击参考杆
• 起点投影到参考线
• 终点由终点箱体位姿推导
• 自动生成两点直线路径

Phase 3

补齐 UI 与持久化：

• 在 PathEditingViewModel / PathEditingView 中新增入口
• 保存终点箱体引用、参考线方向、参考杆长度等参数

推荐复用点

• VirtualObjectManager
  • 复用 unit_cube.nwc 的加载、缩放、隐藏逻辑
• ModelItemTransformHelper
  • 复用带缩放的位姿变换
• NavisworksSelectionHelper
  • 复用当前选择对象读取
• PathPlanningManager
  • 复用点击工具和路径点落点链路

需要新增的能力

建议新增一个专用管理器，而不是继续塞进 VirtualObjectManager：

• AssemblyReferencePathManager

职责：

• 管理参考杆临时实体
• 根据终点箱体位姿生成参考轴线
• 提供点击点到参考线的投影
• 输出最终直线路径点

结论

本需求的主问题是“箱体的直线装配运动仿真”，不是“轨道识别”。
推荐将实现重心切换为：

终点箱体位姿 -> 参考杆 -> 点击起点 -> 直线路径 -> 动画/碰撞

这条路线比轨道几何分析更稳定、更符合 Navisworks 交互约束，也更贴近用户真实使用方式。

当前实现状态

当前 worktree 中已经完成一版可试用实现，核心能力包括：

• 在路径编辑页新增“直线装配参考”区域
• 支持捕获终点处已安装箱体
• 支持选择 轨上安装 / 轨下安装
• 支持选择 顶面对接 / 底面对接
• 根据终点箱体位姿生成一根可点击的参考杆
• 在三维中渲染终点对接点标记
• 用户点击参考杆后，自动吸附到参考线并生成两点直线路径
• 新生成路径仍使用 PathType.Rail，因此可继续复用现有 Rail 动画、通行空间和碰撞检测链路

说明：

• 顶部原有“空轨路径”入口仍保留，但已改名为“传统空轨路径”
• 当前推荐优先使用“直线装配参考”流程

当前操作流程

1. 选择终点箱体

先在 Navisworks 三维视图中选中终点处已经安装好的箱体，然后在路径编辑页点击：

• 捕获终点箱体

系统会记录：

• 箱体名称
• 包围盒中心与尺寸
• 当前选择的安装方式
• 当前选择的对接基准
• 推导出的终点对接点

2. 设置装配构型

在“直线装配参考”区域中设置：

• 安装方式
  • 轨下安装
  • 轨上安装
• 对接基准
  • 顶面对接
  • 底面对接

这两个参数会直接写入最终生成的 PathRoute：

• RailMountMode
• RailPayloadAnchorMode

3. 生成参考杆

设置参考杆参数后点击：

• 生成参考杆

当前实现会：

• 从终点对接点沿箱体前向反推出参考杆
• 在三维场景中生成一根可点击的细长参考杆
• 同时渲染终点对接点标记，便于确认当前到底是顶面中心还是底面中心

参考杆资源优先使用：

• resources/unit_cylinder.nwc

如果该资源暂未放入，则会临时退回：

• resources/unit_cube.nwc

4. 点击参考杆生成路径

点击：

• 取起点并生成路径

然后在三维中点击参考杆附近任意可拾取位置。系统会：

• 获取点击坐标
• 投影到参考杆轴线
• 将投影点作为真实起点
• 将终点对接点作为真实终点
• 自动创建一条两点直线路径

生成后的路径名称形如：

• 直线装配_1

当前界面入口

相关界面位于：

• 路径编辑页 -> 直线装配参考

当前主要按钮：

• 捕获终点箱体
• 生成参考杆
• 取起点并生成路径
• 隐藏参考杆

传统模式入口：

• 传统空轨路径

当前已知边界

1. 终点对接点依赖包围盒和当前朝向

当前终点对接点通过以下信息推导：

• 世界包围盒
• 当前变换的局部 Z 方向
• 估算出的局部箱体高度

这对规则箱型构件是可行的，但如果对象几何明显偏离箱体、或包围盒受附属零件影响较大，终点锚点可能仍需进一步校核。

2. 参考杆方向当前取箱体前向

当前参考杆方向来自：

• 箱体变换后的局部 X 轴

这适合“装配移动方向与构件主朝向一致”的场景。
如果后续遇到“箱体朝向正确，但装配退让方向不是局部 X 轴”的场景，需要再补一个“参考方向选择”输入。

3. 仍然复用 Rail 路径类型

当前新路径仍记为：

• PathType.Rail

这是有意为之，目的是复用已有 Rail 动画和通行空间逻辑。
如果未来这类路径越来越多，可以再考虑单独抽象成新的路径类型，例如 LinearAssembly。

建议测试用例

建议至少验证以下组合：

1. 轨下安装 + 顶面对接
2. 轨下安装 + 底面对接
3. 轨上安装 + 顶面对接
4. 轨上安装 + 底面对接

每组建议检查：

• 终点对接点标记是否落在预期位置
• 参考杆是否从终点沿正确方向反推
• 点击参考杆后起点是否吸附到参考线上
• 生成路径后，动画位置和通行空间偏移是否符合构型

后续建议

下一阶段建议优先做这几项：

1. 增加“参考方向来源”选项 例如允许用户直接指定反推方向，而不只使用箱体局部 X 轴。
2. 为直线装配路径增加更明确的导出字段 便于区分“传统空轨路径”和“终点反推的直线装配路径”。
3. 补一份面向最终用户的简短操作说明 可以从本节内容提炼成更短的 UI 使用指南。