NavisworksTransport/doc/introduction/2.1.3_路径点规划功能设计说明.md

2.1.3 路径点规划功能设计说明

2.1.3.1. 模块描述

路径点规划模块是物流路径规划系统的核心功能，针对较为复杂的环境，支持路径点功能。用户可以在三维视图中，在通道上点击指定起点、路径点、终点的位置及方向，并以三维可视化的方式显示路径。该模块支持多条路径的保存、选择和编辑，为物流运输提供精确的路径规划能力。

路径点规划模块与PathPlanningManager、PathClickToolPlugin和PathPointRenderPlugin紧密协作，实现从用户交互到路径生成的完整流程。

2.1.3.2. 功能

核心功能

1. 路径点创建：在三维视图中点击创建起点、路径点、终点
2. 方向设置：为每个路径点设置方向向量
3. 路径生成：根据路径点自动生成平滑路径
4. 多路径管理：支持多条路径的创建、保存和切换
5. 三维可视化：实时显示路径点和路径线

子功能

功能编号	功能名称	功能描述
2.1.3.F1	起点设置	在三维视图中指定路径起点
2.1.3.F2	终点设置	在三维视图中指定路径终点
2.1.3.F3	中间点设置	添加路径中间点进行路径控制
2.1.3.F4	方向调整	调整路径点的方向向量
2.1.3.F5	路径预览	实时预览生成的路径
2.1.3.F6	路径编辑	编辑已有路径的点位置和方向
2.1.3.F7	多路径切换	在多条路径之间切换编辑
2.1.3.F8	路径删除	删除不需要的路径

2.1.3.3. 性能

性能指标

指标名称	目标值	说明
路径点创建响应	< 200ms	点击到点显示的响应时间
路径生成时间	< 1秒	根据路径点生成完整路径的时间
支持路径点数量	> 50个	单条路径支持的最大路径点数量
支持路径数量	> 100条	支持保存的最大路径数量
渲染帧率	> 30FPS	路径可视化渲染帧率

性能优化策略

1. 使用缓存避免重复的路径计算
2. 路径点批量渲染，减少Draw Call
3. 懒加载策略，非活动路径不渲染

2.1.3.4. 输入输出项

1. 字段输入输出

输入字段

字段名	类型	必填	说明
PointType	PathPointType	是	路径点类型（起点/中间点/终点）
Position	Point3D	是	路径点三维坐标
Direction	Vector3D	否	路径点方向向量
PathName	string	否	路径名称

输出字段

字段名	类型	说明
PathRoute	PathRoute	生成的路径对象
PathLength	double	路径总长度
EstimatedTime	double	预估通行时间
PathPoints	List	路径点列表

2. 界面交互输入输出

界面输入

• 鼠标点击选择路径点位置
• 方向调整操作
• 路径参数设置

界面输出

• 三维路径点标记显示
• 路径连线显示
• 路径信息面板显示

2.1.3.5. 算法

路径点插值算法

算法：基于Catmull-Rom样条的路径平滑
输入：路径点列表
输出：平滑路径点列表

1. 对于每对相邻路径点：
   2. 计算控制点（使用前后点作为切线参考）
   3. 使用Catmull-Rom样条插值生成中间点
   4. 将插值点加入结果列表
5. 返回平滑后的路径点列表

路径生成算法

算法：路径点驱动的路径生成
输入：起点、中间点列表、终点
输出：完整路径

1. 创建PathRoute对象
2. 添加起点到路径
3. 对于每个中间点：
   4. 计算与前一点的方向向量
   5. 添加中间点到路径
6. 添加终点到路径
7. 计算路径长度和预估时间
8. 触发路径生成事件

2.1.3.6. 流程逻辑

开始
  │
  ▼
┌─────────────────┐
│  进入路径编辑模式 │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  设置起点        │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  添加中间点？    │────否────┐
└────────┬────────┘          │
         │是                 │
         ▼                  │
┌─────────────────┐          │
│  点击添加中间点  │          │
└────────┬────────┘          │
         │                   │
         └─────────┬─────────┘
                   │
                   ▼
┌─────────────────┐
│  设置终点        │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  生成路径预览    │
└────────┬────────┘
         │
    ┌────┴────┐
    ▼         ▼
┌────────┐  ┌────────┐
│调整点  │  │确认保存│
└───┬────┘  └───┬────┘
    │           │
    └─────┬─────┘
          │
          ▼
         结束

2.1.3.7. 接口

公共接口

/// <summary>
/// 路径规划管理器
/// </summary>
public class PathPlanningManager
{
    /// <summary>
    /// 添加路径点
    /// </summary>
    /// <param name="position">点位置</param>
    /// <param name="type">点类型</param>
    /// <returns>创建的路径点</returns>
    public PathPoint AddPathPoint(Point3D position, PathPointType type);
    
    /// <summary>
    /// 生成路径
    /// </summary>
    /// <returns>生成的路径</returns>
    public PathRoute GeneratePath();
    
    /// <summary>
    /// 获取当前路径
    /// </summary>
    /// <returns>当前路径</returns>
    public PathRoute GetCurrentRoute();
    
    /// <summary>
    /// 切换当前路径
    /// </summary>
    /// <param name="routeName">路径名称</param>
    public void SwitchRoute(string routeName);
}

事件接口

/// <summary>
/// 路径点添加事件
/// </summary>
public event EventHandler<PathPointAddedEventArgs> PathPointAdded;

/// <summary>
/// 路径生成完成事件
/// </summary>
public event EventHandler<PathGeneratedEventArgs> PathGenerated;

/// <summary>
/// 当前路径变更事件
/// </summary>
public event EventHandler<RouteChangedEventArgs> CurrentRouteChanged;

2.1.3.8. 注释设计

代码注释规范

/// <summary>
/// 路径点类型
/// </summary>
public enum PathPointType
{
    /// <summary>
    /// 起点
    /// </summary>
    Start,
    
    /// <summary>
    /// 中间点（路径点）
    /// </summary>
    WayPoint,
    
    /// <summary>
    /// 终点
    /// </summary>
    End
}

/// <summary>
/// 路径点类
/// 表示路径上的一个关键节点
/// </summary>
public class PathPoint
{
    /// <summary>
    /// 点唯一标识
    /// </summary>
    public string Id { get; set; }
    
    /// <summary>
    /// 点位置（模型单位）
    /// </summary>
    public Point3D Position { get; set; }
    
    /// <summary>
    /// 点方向（用于控制路径走向）
    /// </summary>
    public Vector3D Direction { get; set; }
}

2.1.3.9. 数据结构

PathPoint 结构

字段名	类型	说明
Id	string	点唯一标识符
Position	Point3D	三维坐标位置
Direction	Vector3D	方向向量
Type	PathPointType	点类型
Index	int	在路径中的索引

PathRoute 结构

字段名	类型	说明
Id	string	路径唯一标识符
Name	string	路径名称
Points	List	路径点列表
TotalLength	double	路径总长度（米）
EstimatedTime	double	预估通行时间（秒）
CreateTime	DateTime	创建时间

PathPointAddedEventArgs 结构

字段名	类型	说明
Point	PathPoint	添加的路径点
PointIndex	int	点索引
TotalPoints	int	当前总点数