# 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<int> | 当前可见的楼层列表 |
| HiddenFloors | List<int> | 当前隐藏的楼层列表 |
| DimmedFloors | List<int> | 当前淡化的楼层列表 |

### 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. 接口

### 公共接口
```csharp
/// <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);
}
```

### 辅助接口
```csharp
/// <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. 注释设计

### 代码注释规范
```csharp
/// <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 | 目标楼层 |