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

## 背景

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

- 已知箱体最终安装后的准确位置和空间方向
- 该场景只需要一条起点到终点的直线运动
- 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 使用指南。