NavisworksTransport/doc/introduction/2.3.1_层级显示功能设计说明.md

2.3.1 层级显示功能设计说明

2.3.1.1. 模块描述

层级显示模块是层级创建功能的核心模块，负责支持自动隐藏或淡化非关键层，以便专注于物流路径相关的层级。该模块通过智能的可见性控制，帮助用户在复杂的BIM模型中聚焦于当前关注的楼层，提高路径规划的可视化效果和工作效率。

该模块与LayerManagementViewModel、VisibilityHelper和Navisworks API紧密集成，实现层级的显示、隐藏和淡化控制。

2.3.1.2. 功能

核心功能

1. 层级识别：自动识别模型的楼层结构
2. 智能隐藏：自动隐藏非关键楼层
3. 淡化显示：淡化显示相关但非当前关注的楼层
4. 快速切换：快速切换当前显示的楼层
5. 恢复显示：一键恢复所有楼层的显示

子功能

功能编号	功能名称	功能描述
2.3.1.F1	楼层检测	自动检测模型的楼层结构
2.3.1.F2	关键层标记	标记包含物流路径的关键楼层
2.3.1.F3	非关键层隐藏	自动隐藏非关键楼层
2.3.1.F4	相邻层淡化	淡化显示相邻楼层
2.3.1.F5	楼层切换	快速切换到指定楼层
2.3.1.F6	显示恢复	恢复所有楼层显示
2.3.1.F7	透明度设置	设置淡化层的透明度

2.3.1.3. 性能

性能指标

指标名称	目标值	说明
楼层切换响应	< 500ms	切换楼层的响应时间
批量隐藏时间	< 1秒	隐藏多个楼层的处理时间
渲染帧率	> 30FPS	层级操作后的渲染帧率
内存占用	< 50MB	层级管理的额外内存占用

性能优化策略

1. 批量可见性操作减少API调用
2. 延迟更新策略避免频繁重绘
3. 可见性状态缓存

2.3.1.4. 输入输出项

1. 字段输入输出

输入字段

字段名	类型	必填	说明
TargetFloor	int	是	目标楼层编号
HideNonKeyFloors	bool	否	是否隐藏非关键层，默认true
DimAdjacentFloors	bool	否	是否淡化相邻层，默认true
DimOpacity	double	否	淡化透明度（0-1），默认0.3

输出字段

字段名	类型	说明
VisibleFloors	List	当前可见的楼层列表
HiddenFloors	List	当前隐藏的楼层列表
DimmedFloors	List	当前淡化的楼层列表

2. 界面交互输入输出

界面输入

• 楼层选择下拉框
• 显示/隐藏/淡化选项勾选
• 透明度滑块调整

界面输出

• 楼层列表显示
• 当前可见状态指示
• 操作结果提示

2.3.1.5. 算法

楼层检测算法

算法：检测模型楼层结构
输入：模型元素集合
输出：楼层列表

1. 遍历所有模型元素
2. 提取元素的Z坐标范围
3. 使用聚类算法识别楼层
4. 为每个楼层分配编号
5. 返回楼层列表

层级显示控制算法

算法：控制楼层显示状态
输入：目标楼层，显示参数
输出：应用结果

1. 识别关键楼层（包含物流元素的楼层）
2. 对于每个楼层：
   3. 如果是目标楼层：
      4. 设置为完全可见
   5. 否则如果是相邻楼层且允许淡化：
      6. 设置为淡化显示
   7. 否则如果允许隐藏非关键层：
      8. 设置为隐藏
   9. 否则：
      10. 设置为淡化显示
11. 批量应用可见性设置

2.3.1.6. 流程逻辑

开始
  │
  ▼
┌─────────────────┐
│  检测楼层结构    │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  识别关键楼层    │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  选择目标楼层    │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  配置显示参数    │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  应用可见性设置  │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  更新视图显示    │
└────────┬────────┘
         │
         ▼
        结束

2.3.1.7. 接口

公共接口

/// <summary>
/// 层级管理视图模型
/// </summary>
public class LayerManagementViewModel
{
    /// <summary>
    /// 切换到指定楼层
    /// </summary>
    /// <param name="floorNumber">楼层编号</param>
    public void SwitchToFloor(int floorNumber);
    
    /// <summary>
    /// 设置楼层可见性
    /// </summary>
    /// <param name="floorNumber">楼层编号</param>
    /// <param name="isVisible">是否可见</param>
    public void SetFloorVisibility(int floorNumber, bool isVisible);
    
    /// <summary>
    /// 设置楼层透明度
    /// </summary>
    /// <param name="floorNumber">楼层编号</param>
    /// <param name="opacity">透明度（0-1）</param>
    public void SetFloorOpacity(int floorNumber, double opacity);
    
    /// <summary>
    /// 恢复所有楼层显示
    /// </summary>
    public void RestoreAllFloors();
    
    /// <summary>
    /// 自动配置层级显示
    /// </summary>
    /// <param name="targetFloor">目标楼层</param>
    public void AutoConfigureLayerVisibility(int targetFloor);
}

辅助接口

/// <summary>
/// 可见性辅助类
/// </summary>
public static class VisibilityHelper
{
    /// <summary>
    /// 隐藏元素集合
    /// </summary>
    public static void HideItems(ModelItemCollection items);
    
    /// <summary>
    /// 显示元素集合
    /// </summary>
    public static void ShowItems(ModelItemCollection items);
    
    /// <summary>
    /// 设置元素透明度
    /// </summary>
    public static void SetItemOpacity(ModelItemCollection items, double opacity);
}

2.3.1.8. 注释设计

代码注释规范

/// <summary>
/// 楼层信息
/// </summary>
public class FloorLayerInfo
{
    /// <summary>
    /// 楼层编号
    /// </summary>
    public int FloorNumber { get; set; }
    
    /// <summary>
    /// 楼层高度范围
    /// </summary>
    public Range HeightRange { get; set; }
    
    /// <summary>
    /// 是否为关键楼层（包含物流元素）
    /// </summary>
    public bool IsKeyFloor { get; set; }
    
    /// <summary>
    /// 当前可见性状态
    /// </summary>
    public VisibilityState Visibility { get; set; }
}

/// <summary>
/// 可见性状态
/// </summary>
public enum VisibilityState
{
    Hidden,     // 隐藏
    Dimmed,     // 淡化
    Visible     // 完全可见
}

2.3.1.9. 数据结构

FloorLayerInfo 结构

字段名	类型	说明
FloorNumber	int	楼层编号
HeightRange	Range	高度范围
IsKeyFloor	bool	是否关键楼层
Visibility	VisibilityState	可见性状态
Opacity	double	透明度（0-1）
ElementCount	int	元素数量

VisibilityState 枚举

值	说明
Hidden	完全隐藏
Dimmed	淡化显示
Visible	完全可见

LayerConfiguration 结构

字段名	类型	说明
HideNonKeyFloors	bool	是否隐藏非关键层
DimAdjacentFloors	bool	是否淡化相邻层
DimOpacity	double	淡化透明度
TargetFloor	int	目标楼层