# ModelHighlightHelper 使用指南

## 文件位置

`src/Utils/ModelHighlightHelper.cs`

## 用途

统一管理 Navisworks 临时高亮，支持按类别高亮与清除。使用不同颜色区分不同类型的对象（碰撞结果、通道预览、动画物体等）。

## 颜色定义

| 类别 | 颜色 | RGB | 用途 |
|------|------|-----|------|
| `PrecomputeCollisionResultsCategory` | Material Purple | (156, 39, 176) | 预计算碰撞结果 |
| `ManualTargetsCategory` | 橙色 | (255, 170, 0) | 手工指定对象 |
| `AnimatedObjectCategory` | Amber/Yellow | (255, 193, 7) | 动画物体 |
| `ClashDetectiveResultsCategory` | 红色 | Color.Red | ClashDetective碰撞结果 |
| `ChannelPreviewCategory` | 绿色 | Color.Green | 通道预览 |
| `excludedObjects` | Material Green | (76, 175, 80) | 排除对象 |

## 核心方法

### 基础高亮操作

```csharp
// 高亮指定对象集合（使用类别默认颜色）
ModelHighlightHelper.HighlightItems("myCategory", modelItems);

// 清除指定类别的高亮
ModelHighlightHelper.ClearCategory("myCategory");

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

// 清除碰撞相关高亮
ModelHighlightHelper.ClearCollisionHighlights();
```

### 碰撞结果高亮

```csharp
// 按类别管理碰撞高亮
ModelHighlightHelper.ManageCollisionHighlightsByCategory(
    "collisionResults", 
    collisionResultsList,
    clearOtherCategories: false
);

// 高亮ClashDetective结果
ModelHighlightHelper.HighlightClashDetectiveResults(
    testName,
    getResultsFunc
);

// 清除ClashDetective高亮
ModelHighlightHelper.ClearClashDetectiveHighlights();
```

### 获取高亮状态

```csharp
// 获取当前高亮快照
var highlights = ModelHighlightHelper.GetActiveHighlightSnapshot();
foreach (var info in highlights)
{
    LogManager.Info($"类别: {info.Category}, 颜色: {info.Color}, 数量: {info.Count}");
}

// 获取类别颜色
Color color = ModelHighlightHelper.GetCategoryColor("myCategory");
```

## 使用示例

### 示例1：高亮碰撞检测结果

```csharp
// 获取碰撞结果
var collisions = collisionDetector.DetectCollisions();

// 高亮显示碰撞对象（使用预计算碰撞类别）
var collidingItems = collisions.Select(c => c.Item2).ToList();
ModelHighlightHelper.HighlightItems(
    ModelHighlightHelper.PrecomputeCollisionResultsCategory, 
    collidingItems
);

// 操作完成后清除高亮
ModelHighlightHelper.ClearCategory(ModelHighlightHelper.PrecomputeCollisionResultsCategory);
```

### 示例2：高亮通道预览

```csharp
// 高亮显示通道对象
var channelItems = GetChannelItems();
ModelHighlightHelper.HighlightItems(
    ModelHighlightHelper.ChannelPreviewCategory,
    channelItems
);

// 清除时只清除通道预览，不影响其他高亮
ModelHighlightHelper.ClearCategory(ModelHighlightHelper.ChannelPreviewCategory);
```

### 示例3：多类别管理

```csharp
// 同时高亮不同类型对象
ModelHighlightHelper.HighlightItems("doors", doorItems);
ModelHighlightHelper.HighlightItems("elevators", elevatorItems);
ModelHighlightHelper.HighlightItems("stairs", stairItems);

// 只清除门的高亮
ModelHighlightHelper.ClearCategory("doors");

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

## 注意事项

1. **类别颜色自动管理**：每个类别有预定义颜色，也可以使用自定义类别（默认白色）
2. **自动去重**：同一对象在不同类别中可能被多次高亮，后设置的会覆盖先前的
3. **线程安全**：内部使用锁保护，可从多线程调用
4. **清除策略**：
   - 清除单个类别：`ClearCategory()`
   - 清除所有碰撞相关：`ClearCollisionHighlights()`
   - 清除全部：`ClearAllHighlights()`