# VisibilityHelper 使用指南

## 文件位置

`src/Utils/VisibilityHelper.cs`

## 用途

可见性管理器，负责 ModelItem 可见性控制的核心业务逻辑，包括显示全部、隔离显示、设置可见性等。

## 核心方法

### 显示所有项目

```csharp
// 显示所有模型项目（重置所有隐藏状态）
bool success = VisibilityHelper.ShowAllItems();
```

### 隔离显示

```csharp
// 仅显示指定的模型项集合，隐藏其他所有项
bool success = VisibilityHelper.IsolateSpecificItems(itemsToShow);

// 示例：隔离显示路径相关的对象
var pathItems = GetPathRelatedItems();
VisibilityHelper.IsolateSpecificItems(pathItems);
```

### 设置可见性

```csharp
// 设置指定模型项集合的可见性
bool success = VisibilityHelper.SetItemsVisibility(items, isHidden: true);   // 隐藏
bool success = VisibilityHelper.SetItemsVisibility(items, isHidden: false);  // 显示
```

## 使用示例

### 示例1：隔离显示碰撞对象

```csharp
// 收集所有碰撞涉及的对象
var collisionItems = new ModelItemCollection();
foreach (var collision in collisionResults)
{
    if (collision.Item1 != null) collisionItems.Add(collision.Item1);
    if (collision.Item2 != null) collisionItems.Add(collision.Item2);
}

// 只显示碰撞对象
VisibilityHelper.IsolateSpecificItems(collisionItems);

// 高亮碰撞对象
ModelHighlightHelper.HighlightItems("collisions", collisionItems);
```

### 示例2：分步显示/隐藏

```csharp
// 隐藏所有障碍物
var obstacles = GetObstacleItems();
VisibilityHelper.SetItemsVisibility(obstacles, isHidden: true);

// 后续操作...

// 重新显示障碍物
VisibilityHelper.SetItemsVisibility(obstacles, isHidden: false);
```

### 示例3：完整的显示重置流程

```csharp
// 清除所有高亮
ModelHighlightHelper.ClearAllHighlights();

// 显示所有项目
VisibilityHelper.ShowAllItems();

// 清除剖面盒
SectionClipHelper.ClearClipBox();

LogManager.Info("视图已重置");
```

### 示例4：通道可视化

```csharp
// 只显示通道相关的对象
var channelItems = GetChannelItems();
VisibilityHelper.IsolateSpecificItems(channelItems);

// 调整视角到通道
ViewpointHelper.AdjustViewpointToPathCenter(channelPath);

// 生成通道预览图
string screenshot = PathHelper.GenerateSceneScreenshot(
    "channel_view", 1920, 1080, ImageFormat.Png
);

// 恢复显示所有
VisibilityHelper.ShowAllItems();
```

## 注意事项

1. **隔离显示原理**：`IsolateSpecificItems` 会先显示所有，然后隐藏不需要的项目
2. **祖先节点处理**：隔离显示会自动包含选中项的所有祖先节点，确保路径完整
3. **性能考虑**：大量项目的可见性操作可能影响性能，建议批量处理
4. **与剖面盒配合**：可以与 `SectionClipHelper` 配合使用，进一步减少可见对象
5. **错误处理**：所有方法都返回 `bool` 表示成功/失败，内部已处理异常