NavisworksTransport/doc/introduction/2.1.2_通道选择功能设计说明.md

2.1.2 通道选择功能设计说明

2.1.2.1. 模块描述

通道选择模块是物流路径规划系统的核心功能模块，负责支持用户通过选择树或三维视图点选的方式选择通道模型，并将其指定为通道类型。该模块是后续自动路径规划的基础，为A*算法提供可通行的通道区域数据。

通道选择模块与CategoryAttributeManager紧密集成，将选中的模型元素标记为物流属性中的"通道"类型，并设置相应的通行属性。

2.1.2.2. 功能

核心功能

1. 选择树选择：通过Navisworks选择树面板选择模型元素
2. 三维点选：在三维视图中直接点击选择模型元素
3. 通道类型指定：将选中的模型指定为通道类型
4. 批量选择：支持框选和批量选择多个元素

子功能

功能编号	功能名称	功能描述
2.1.2.F1	选择树集成	与Navisworks选择树面板集成，支持树形结构选择
2.1.2.F2	三维点选	支持在三维视图中点击选择模型
2.1.2.F3	框选支持	支持矩形框选多个模型元素
2.1.2.F4	类型指定	将选中的模型指定为通道类型
2.1.2.F5	选择预览	高亮显示当前选中的模型元素
2.1.2.F6	选择确认	确认选择并应用通道属性

2.1.2.3. 性能

性能指标

指标名称	目标值	说明
点选响应时间	< 100ms	三维视图中点击选择的响应时间
批量选择支持	> 1000个	单次批量选择的最大元素数量
属性应用时间	< 500ms	通道属性应用到选中元素的时间
内存占用	< 100MB	选择过程中的额外内存占用

性能优化策略

1. 使用空间索引加速三维点选
2. 批量属性设置，减少COM API调用次数
3. 选择结果缓存，避免重复查询

2.1.2.4. 输入输出项

1. 字段输入输出

输入字段

字段名	类型	必填	说明
SelectedItems	ModelItemCollection	是	选中的模型元素集合
ChannelType	LogisticsElementType	否	通道类型，默认Channel
Priority	int	否	优先级，默认5
IsTraversable	bool	否	是否可通行，默认true

输出字段

字段名	类型	说明
AppliedCount	int	成功应用属性的元素数量
FailedItems	List	应用失败的元素列表
ChannelItems	List	当前所有通道元素列表

2. 界面交互输入输出

界面输入

• 鼠标点击/框选操作
• 选择树节点勾选
• 通道属性参数设置

界面输出

• 选中元素高亮显示
• 选择数量统计
• 通道类型应用结果提示

2.1.2.5. 算法

三维点选算法

算法：基于射线检测的三维点选
输入：鼠标屏幕坐标，相机参数
输出：选中的模型元素

1. 将屏幕坐标转换为射线（Ray）
2. 遍历所有可见模型元素：
   3. 计算射线与元素包围盒的交点
   4. 如果有交点，计算精确交点距离
5. 返回距离最近的元素

通道属性应用算法

算法：批量应用通道属性
输入：选中的模型元素集合
输出：应用结果

1. 初始化COM API
2. 对于每个选中的元素：
   3. 检查元素是否已有物流属性
   4. 如果存在且冲突，记录冲突
   5. 应用通道类型属性
   6. 应用优先级、可通行性等属性
7. 批量提交属性更改
8. 返回应用统计

2.1.2.6. 流程逻辑

开始
  │
  ▼
┌─────────────────┐
│  进入选择模式    │
└────────┬────────┘
         │
    ┌────┴────┐
    ▼         ▼
┌────────┐  ┌────────┐
│选择树  │  │三维点选│
└───┬────┘  └───┬────┘
    │           │
    └─────┬─────┘
          │
          ▼
┌─────────────────┐
│  显示选中预览    │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  确认通道类型    │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  应用通道属性    │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  显示应用结果    │
└────────┬────────┘
         │
         ▼
        结束

2.1.2.7. 接口

公共接口

/// <summary>
/// 通道选择管理器
/// </summary>
public class ChannelSelectionManager
{
    /// <summary>
    /// 设置选中元素为通道
    /// </summary>
    /// <param name="items">选中的模型元素</param>
    /// <returns>应用结果</returns>
    public ChannelSelectionResult SetAsChannel(ModelItemCollection items);
    
    /// <summary>
    /// 获取所有通道元素
    /// </summary>
    /// <returns>通道元素列表</returns>
    public List<ModelItem> GetAllChannels();
    
    /// <summary>
    /// 清除元素的通道属性
    /// </summary>
    /// <param name="items">要清除的元素</param>
    /// <returns>清除的元素数量</returns>
    public int ClearChannelAttribute(ModelItemCollection items);
}

事件接口

/// <summary>
/// 选择变更事件
/// </summary>
public event EventHandler<SelectionChangedEventArgs> SelectionChanged;

/// <summary>
/// 通道属性应用完成事件
/// </summary>
public event EventHandler<ChannelAppliedEventArgs> ChannelApplied;

2.1.2.8. 注释设计

代码注释规范

/// <summary>
/// 通道选择结果
/// </summary>
public class ChannelSelectionResult
{
    /// <summary>
    /// 成功应用的元素数量
    /// </summary>
    public int AppliedCount { get; set; }
    
    /// <summary>
    /// 应用失败的元素列表
    /// 失败原因可能是元素已被锁定或API调用失败
    /// </summary>
    public List<ModelItem> FailedItems { get; set; }
}

配置文件注释

# 通道选择配置
[channel_selection]
# 默认通道类型
default_channel_type = "通道"
# 默认优先级（1-10）
default_priority = 5
# 点选容差（像素）
click_tolerance_pixels = 5

2.1.2.9. 数据结构

ChannelSelectionResult 结构

字段名	类型	说明
AppliedCount	int	成功应用的元素数量
FailedCount	int	失败的元素数量
FailedItems	List	失败的元素列表
ConflictCount	int	冲突的元素数量

SelectionChangedEventArgs 结构

字段名	类型	说明
SelectedItems	ModelItemCollection	当前选中的元素
SelectionCount	int	选中元素数量
SelectionBounds	BoundingBox3D	选中元素的包围盒

ChannelAppliedEventArgs 结构

字段名	类型	说明
AppliedCount	int	成功应用的元素数量
ChannelType	LogisticsElementType	应用的通道类型
ApplyTime	DateTime	应用时间