NavisworksTransport/doc/introduction/2.3.3_路径时间标签功能设计说明.md

2.3.3 路径时间标签功能设计说明

2.3.3.1. 模块描述

路径时间标签模块是层级创建功能的重要组成部分，负责支持路径时间标签设置，以预估运输时间。该模块通过分析路径的长度、元素类型（如门、电梯、楼梯的速度限制）等因素，计算物流运输的预估时间，为路径规划提供时间维度的参考。

该模块与TimeTagService、TimeTagCalculator和PathRoute紧密集成，实现基于路径特征的时间估算功能。

2.3.3.2. 功能

核心功能

1. 时间估算：基于路径特征估算运输时间
2. 分段计时：对路径的不同段进行分段计时
3. 时间标签显示：在路径上显示时间标签
4. 速度限制应用：应用通道元素的速度限制
5. 时间导出：导出时间估算结果

子功能

功能编号	功能名称	功能描述
2.3.3.F1	路径分析	分析路径的长度、坡度等特征
2.3.3.F2	速度计算	根据元素类型计算各段速度
2.3.3.F3	时间计算	计算总运输时间和分段时间
2.3.3.F4	时间标签	在路径点显示时间标签
2.3.3.F5	分段显示	显示各段的预计时间
2.3.3.F6	时间导出	导出时间数据到文件
2.3.3.F7	TimeLiner集成	与TimeLiner任务时间同步

2.3.3.3. 性能

性能指标

指标名称	目标值	说明
时间计算响应	< 200ms	计算路径时间的响应时间
批量计算时间	< 1秒	批量计算多条路径的时间
标签渲染时间	< 100ms	渲染时间标签的时间
内存占用	< 50MB	时间计算的额外内存占用

性能优化策略

1. 缓存路径特征计算结果
2. 批量时间计算优化
3. 时间标签按需渲染

2.3.3.4. 输入输出项

1. 字段输入输出

输入字段

字段名	类型	必填	说明
Route	PathRoute	是	要计算时间的路径
ObjectSpeed	double	否	物体移动速度（米/秒），默认0.8
ApplySpeedLimits	bool	否	是否应用速度限制，默认true

输出字段

字段名	类型	说明
TotalTime	double	总运输时间（秒）
SegmentTimes	List	分段时间列表
TimeTags	List	时间标签列表
AverageSpeed	double	平均速度（米/秒）

2. 界面交互输入输出

界面输入

• 路径选择
• 速度参数设置
• 时间标签显示选项

界面输出

• 总时间显示
• 分段时间表
• 时间标签可视化
• 导出结果提示

2.3.3.5. 算法

时间估算算法

算法：基于路径特征的时间估算
输入：路径，物体速度
输出：时间估算结果

1. 初始化总时间为0
2. 对于路径的每个段：
   3. 获取段长度
   4. 获取段的元素类型和速度限制
   5. 计算段速度：
      - 取物体速度和速度限制的较小值
   6. 计算段时间：长度 / 速度
   7. 累加到总时间
8. 返回总时间和分段详情

分段计时算法

算法：路径分段计时
输入：路径点列表
输出：分段时间列表

1. 对于每对相邻路径点：
   2. 计算两点间距离
   3. 识别经过的物流元素
   4. 获取元素的速度限制
   5. 计算通过时间
   6. 记录分段信息
7. 返回分段时间列表

2.3.3.6. 流程逻辑

开始
  │
  ▼
┌─────────────────┐
│  选择路径        │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  分析路径特征    │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  获取速度限制    │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  计算分段时间    │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  计算总时间      │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  生成时间标签    │
└────────┬────────┘
         │
    ┌────┴────┐
    ▼         ▼
┌────────┐  ┌────────┐
│显示标签│  │导出时间│
└───┬────┘  └───┬────┘
    │           │
    └─────┬─────┘
          │
          ▼
         结束

2.3.3.7. 接口

公共接口

/// <summary>
/// 时间标签服务
/// </summary>
public class TimeTagService
{
    /// <summary>
    /// 计算路径时间
    /// </summary>
    /// <param name="route">路径对象</param>
    /// <param name="objectSpeed">物体速度</param>
    /// <returns>时间计算结果</returns>
    public TimeCalculationResult CalculatePathTime(PathRoute route, double objectSpeed = 0.8);
    
    /// <summary>
    /// 生成时间标签
    /// </summary>
    /// <param name="result">时间计算结果</param>
    /// <returns>时间标签列表</returns>
    public List<TimeTag> GenerateTimeTags(TimeCalculationResult result);
    
    /// <summary>
    /// 在视图中显示时间标签
    /// </summary>
    /// <param name="timeTags">时间标签</param>
    public void DisplayTimeTags(List<TimeTag> timeTags);
    
    /// <summary>
    /// 导出时间数据
    /// </summary>
    /// <param name="result">时间计算结果</param>
    /// <param name="filePath">导出路径</param>
    public void ExportTimeData(TimeCalculationResult result, string filePath);
}

辅助接口

/// <summary>
/// 时间计算器
/// </summary>
public class TimeTagCalculator
{
    /// <summary>
    /// 计算段的通过时间
    /// </summary>
    public double CalculateSegmentTime(PathSegment segment, double speed);
    
    /// <summary>
    /// 获取元素的速度限制
    /// </summary>
    public double GetSpeedLimit(ModelItem element);
}

2.3.3.8. 注释设计

代码注释规范

/// <summary>
/// 时间计算结果
/// </summary>
public class TimeCalculationResult
{
    /// <summary>
    /// 总运输时间（秒）
    /// </summary>
    public double TotalTimeSeconds { get; set; }
    
    /// <summary>
    /// 总运输时间（格式化为 mm:ss）
    /// </summary>
    public string TotalTimeFormatted => FormatTime(TotalTimeSeconds);
    
    /// <summary>
    /// 分段时间详情
    /// </summary>
    public List<SegmentTimeInfo> SegmentTimes { get; set; }
    
    /// <summary>
    /// 平均速度（米/秒）
    /// </summary>
    public double AverageSpeed { get; set; }
}

/// <summary>
/// 分段时间信息
/// </summary>
public class SegmentTimeInfo
{
    /// <summary>
    /// 段索引
    /// </summary>
    public int SegmentIndex { get; set; }
    
    /// <summary>
    /// 段长度（米）
    /// </summary>
    public double Length { get; set; }
    
    /// <summary>
    /// 通过时间（秒）
    /// </summary>
    public double TimeSeconds { get; set; }
    
    /// <summary>
    /// 段速度（米/秒）
    /// </summary>
    public double Speed { get; set; }
}

2.3.3.9. 数据结构

TimeCalculationResult 结构

字段名	类型	说明
TotalTimeSeconds	double	总运输时间（秒）
SegmentTimes	List	分段时间列表
AverageSpeed	double	平均速度（米/秒）
RouteName	string	路径名称
CalculationTime	DateTime	计算时间

SegmentTimeInfo 结构

字段名	类型	说明
SegmentIndex	int	段索引
StartPoint	PathPoint	起点
EndPoint	PathPoint	终点
Length	double	段长度（米）
TimeSeconds	double	通过时间（秒）
Speed	double	段速度（米/秒）
ElementType	LogisticsElementType	主要元素类型

TimeTag 结构

字段名	类型	说明
Position	Point3D	标签位置
TimeValue	double	时间值（秒）
TimeText	string	时间显示文本
LabelType	TimeTagType	标签类型

TimeTagType 枚举

值	说明
Start	起点时间
Segment	分段点
Cumulative	累计时间
End	终点时间