NavisworksTransport/doc/introduction/2.4.1_交互式导航控件功能设计说明.md

2.4.1 交互式导航控件功能设计说明

2.4.1.1. 模块描述

交互式导航控件模块是交互式导航功能的核心模块，负责创建交互式导航控件，允许用户选择不同的起点和终点，动态生成路径。该模块提供直观友好的用户界面，使用户能够轻松地进行路径规划操作，并实时预览生成的路径结果。

该模块与NavigationMapGenerator、PathPlanningManager和WPF视图层紧密集成，提供完整的路径规划交互体验。

2.4.1.2. 功能

核心功能

1. 起点选择：交互式选择路径起点
2. 终点选择：交互式选择路径终点
3. 路径生成：根据选择的起终点动态生成路径
4. 实时预览：实时显示生成的路径
5. 路径调整：支持调整路径参数重新生成

子功能

功能编号	功能名称	功能描述
2.4.1.F1	起点设置	在三维视图中设置起点
2.4.1.F2	终点设置	在三维视图中设置终点
2.4.1.F3	路径计算	自动计算最优路径
2.4.1.F4	路径显示	在三维视图中显示路径
2.4.1.F5	参数调整	调整路径规划参数
2.4.1.F6	路径保存	保存生成的路径
2.4.1.F7	多点导航	支持多个途经点
2.4.1.F8	路径比较	比较不同路径方案

2.4.1.3. 性能

性能指标

指标名称	目标值	说明
路径生成响应	< 2秒	从选择到生成路径的响应时间
界面响应时间	< 100ms	控件操作的响应时间
路径渲染时间	< 500ms	路径可视化渲染时间
支持并发操作	5个	同时处理的路径规划请求数

性能优化策略

1. 异步路径计算避免阻塞UI
2. 路径结果缓存
3. 增量渲染路径

2.4.1.4. 输入输出项

1. 字段输入输出

输入字段

字段名	类型	必填	说明
StartPoint	Point3D	是	起点坐标
EndPoint	Point3D	是	终点坐标
ViaPoints	List	否	途经点列表
ObjectSize	double	否	物体尺寸（米）
Strategy	PathStrategy	否	路径策略，默认Shortest

输出字段

字段名	类型	说明
GeneratedPath	PathRoute	生成的路径对象
PathLength	double	路径长度（米）
EstimatedTime	double	预估时间（秒）
PathPoints	List	路径点列表

2. 界面交互输入输出

界面输入

• 起点/终点选择按钮
• 途经点添加/删除
• 参数设置控件
• 路径生成按钮

界面输出

• 起终点标记显示
• 路径连线显示
• 路径信息显示面板
• 操作提示信息

2.4.1.5. 算法

动态路径生成算法

算法：根据起终点动态生成路径
输入：起点，终点，途经点，参数
输出：生成的路径

1. 验证起终点有效性
2. 构建路径点序列
   - 起点
   - 途经点（如果有）
   - 终点
3. 调用路径规划算法
4. 生成平滑路径
5. 计算路径长度和时间
6. 返回路径对象

A*路径规划算法

算法：A*寻路算法
输入：起点，终点，网格地图
输出：最优路径

1. 初始化开放列表和关闭列表
2. 将起点加入开放列表
3. 当开放列表不为空：
   4. 取出F值最小的节点
   5. 如果是终点， reconstruct path
   6. 移动到关闭列表
   7. 遍历邻居节点：
      8. 如果在关闭列表，跳过
      9. 计算G、H、F值
      10. 如果在开放列表，更新值
      11. 否则加入开放列表
12. 返回路径

2.4.1.6. 流程逻辑

开始
  │
  ▼
┌─────────────────┐
│  打开导航控件    │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  选择起点        │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  选择终点        │
└────────┬────────┘
         │
         ▼
┌─────────────────┐      是
│  添加途经点？    │──────────┐
└────────┬────────┘          │
         │否                 │
         ▼                   │
┌─────────────────┐          │
│  设置规划参数    │          │
└────────┬────────┘          │
         │                   │
         ▼                   │
┌─────────────────┐          │
│  点击生成路径    │          │
└────────┬────────┘          │
         │                   │
         ▼                   │
┌─────────────────┐          │
│  执行路径计算    │          │
└────────┬────────┘          │
         │                   │
         ▼                   │
┌─────────────────┐          │
│  显示路径结果    │◄─────────┘
└────────┬────────┘
         │
    ┌────┴────┐
    ▼         ▼
┌────────┐  ┌────────┐
│调整参数│  │保存路径│
└───┬────┘  └───┬────┘
    │           │
    └─────┬─────┘
          │
          ▼
         结束

2.4.1.7. 接口

公共接口

/// <summary>
/// 导航地图生成器
/// </summary>
public class NavigationMapGenerator
{
    /// <summary>
    /// 生成导航路径
    /// </summary>
    /// <param name="startPoint">起点</param>
    /// <param name="endPoint">终点</param>
    /// <param name="parameters">路径参数</param>
    /// <returns>生成的路径</returns>
    public PathRoute GenerateNavigationPath(Point3D startPoint, Point3D endPoint, PathParameters parameters);
    
    /// <summary>
    /// 添加途经点
    /// </summary>
    public void AddViaPoint(Point3D point);
    
    /// <summary>
    /// 清除途经点
    /// </summary>
    public void ClearViaPoints();
    
    /// <summary>
    /// 设置路径策略
    /// </summary>
    public void SetPathStrategy(PathStrategy strategy);
}

/// <summary>
/// 路径参数
/// </summary>
public class PathParameters
{
    public double ObjectLength { get; set; }
    public double ObjectWidth { get; set; }
    public double ObjectHeight { get; set; }
    public double SafetyMargin { get; set; }
    public PathStrategy Strategy { get; set; }
}

2.4.1.8. 注释设计

代码注释规范

/// <summary>
/// 路径策略枚举
/// </summary>
public enum PathStrategy
{
    /// <summary>
    /// 最短路径
    /// </summary>
    Shortest,
    
    /// <summary>
    /// 最快路径
    /// </summary>
    Fastest,
    
    /// <summary>
    /// 最安全路径（避开障碍物）
    /// </summary>
    Safest,
    
    /// <summary>
    /// 平衡路径
    /// </summary>
    Balanced
}

2.4.1.9. 数据结构

PathParameters 结构

字段名	类型	说明
ObjectLength	double	物体长度（米）
ObjectWidth	double	物体宽度（米）
ObjectHeight	double	物体高度（米）
SafetyMargin	double	安全间隙（米）
Strategy	PathStrategy	路径策略
MaxSlope	double	最大坡度（度）

PathStrategy 枚举

值	说明
Shortest	优先最短距离
Fastest	优先最快速度
Safest	优先最安全
Balanced	平衡考虑

NavigationResult 结构

字段名	类型	说明
Path	PathRoute	生成的路径
Success	bool	是否成功
Message	string	结果消息
CalculationTime	TimeSpan	计算耗时