# NavisworksTransport 项目工具类使用指南

## 概述

本skill记录 NavisworksTransport 项目中的所有工具类及其使用方法。在编写代码前，请务必查看此文档，**优先使用现有工具类，避免重复造轮子**。

## 工具类总览

### 核心工具类（⭐⭐⭐ 必须）

| 工具类 | 文件 | 用途 |
|--------|------|------|
| **DialogHelper** | `src/Utils/DialogHelper.cs` | 对话框Owner设置和置顶显示 |
| **UnitsConverter** | `src/Utils/UnitsConverter.cs` | 单位转换（米↔模型单位） |
| **LogManager** | `src/Utils/LogManager.cs` | 日志记录 |
| **GeometryHelper** | `src/Utils/GeometryHelper.cs` | 3D几何计算 |
| **PathHelper** | `src/Utils/PathHelper.cs` | 文件路径相关工具 |

### 重要工具类（⭐⭐ 推荐）

| 工具类 | 文件 | 用途 |
|--------|------|------|
| **CoordinateConverter** | `src/Utils/CoordinateConverter.cs` | 2D地图↔3D世界坐标转换 |
| **ModelHighlightHelper** | `src/Utils/ModelHighlightHelper.cs` | 模型高亮显示 |
| **NavisworksSelectionHelper** | `src/Utils/NavisworksSelectionHelper.cs` | 选择集操作 |
| **ViewpointHelper** | `src/Utils/ViewpointHelper.cs` | 视点操作 |
| **NavisworksApiHelper** | `src/Utils/NavisworksApiHelper.cs` | API通用工具 |
| **VisibilityHelper** | `src/Utils/VisibilityHelper.cs` | 可见性管理 |

### 专项工具类（⭐ 按需使用）

| 工具类 | 文件 | 用途 |
|--------|------|------|
| **SectionClipHelper** | `src/Utils/SectionClipHelper.cs` | 剖切操作（性能优化） |
| **BoundingBoxGeometryUtils** | `src/Utils/BoundingBoxGeometryUtils.cs` | 包围盒几何计算 |
| **FloorDetector** | `src/Utils/FloorDetector.cs` | 楼层检测 |
| **GeometryCacheManager** | `src/Utils/GeometryCacheManager.cs` | 几何缓存管理 |

## 快速参考

### 对话框开发

```csharp
// ❌ 错误：直接设置Owner，可能在Navisworks环境中失败
var dialog = new MyDialog();
dialog.Owner = Application.Current.MainWindow;  // 可能抛出异常！
dialog.Show();

// ✅ 正确：使用 DialogHelper
var dialog = new MyDialog();
DialogHelper.SetOwnerSafely(dialog);  // 自动处理Navisworks环境
dialog.Show();
```

### 单位转换

```csharp
// ❌ 错误：硬编码转换因子
double meters = modelUnits * 0.001;  // 错误！不同文档单位不同

// ✅ 正确：使用 UnitsConverter
double meters = UnitsConverter.ConvertToMeters(modelUnits);
double modelUnits = UnitsConverter.ConvertFromMeters(meters);
```

### 日志记录

```csharp
// ❌ 错误：使用Console或直接输出
Console.WriteLine($"Error: {ex.Message}");  // 不可见！

// ✅ 正确：使用 LogManager
LogManager.Info("操作成功");
LogManager.Warning("警告信息");
LogManager.Error("错误信息", exception);
```

### 几何计算

```csharp
// ❌ 错误：自己实现距离计算
double dx = p2.X - p1.X;
double dy = p2.Y - p1.Y;
double distance = Math.Sqrt(dx*dx + dy*dy);

// ✅ 正确：使用 GeometryHelper
double distance = GeometryHelper.Distance(p1, p2);
double angle = GeometryHelper.AngleBetweenDegrees(v1, v2);
```

### 模型高亮

```csharp
// ✅ 使用 ModelHighlightHelper 高亮对象
ModelHighlightHelper.HighlightItems("myCategory", modelItems);
ModelHighlightHelper.ClearCategory("myCategory");
ModelHighlightHelper.ClearAllHighlights();
```

### 视角调整

```csharp
// ✅ 使用 ViewpointHelper 调整视角
ViewpointHelper.AdjustViewpointToPathCenter(path);
ViewpointHelper.FocusOnModelItem(modelItem, 45, 0.25);
Viewpoint saved = ViewpointHelper.SaveCurrentViewpoint();
ViewpointHelper.RestoreViewpoint(saved);
```

## 详细文档

- [DialogHelper 使用指南](utils/DialogHelper.md) - 对话框Owner设置和置顶显示
- [UnitsConverter 使用指南](utils/UnitsConverter.md) - 单位转换（极其重要）
- [LogManager 使用指南](utils/LogManager.md) - 日志记录
- [GeometryHelper 使用指南](utils/GeometryHelper.md) - 3D几何计算
- [PathHelper 使用指南](utils/PathHelper.md) - 文件路径工具
- [CoordinateConverter 使用指南](utils/CoordinateConverter.md) - 2D/3D坐标转换
- [ModelHighlightHelper 使用指南](utils/ModelHighlightHelper.md) - 模型高亮
- [NavisworksSelectionHelper 使用指南](utils/NavisworksSelectionHelper.md) - 选择集操作
- [ViewpointHelper 使用指南](utils/ViewpointHelper.md) - 视点操作
- [SectionClipHelper 使用指南](utils/SectionClipHelper.md) - 剖切操作
- [NavisworksApiHelper 使用指南](utils/NavisworksApiHelper.md) - API通用工具
- [VisibilityHelper 使用指南](utils/VisibilityHelper.md) - 可见性管理

## 使用检查清单

在编写新功能前，请检查：

- [ ] 需要显示对话框？→ 使用 **DialogHelper**
- [ ] 涉及单位转换？→ 使用 **UnitsConverter**
- [ ] 需要记录日志？→ 使用 **LogManager**
- [ ] 需要几何计算？→ 使用 **GeometryHelper**
- [ ] 需要高亮模型？→ 使用 **ModelHighlightHelper**
- [ ] 需要处理选择集？→ 使用 **NavisworksSelectionHelper**
- [ ] 需要调整视角？→ 使用 **ViewpointHelper**
- [ ] 需要坐标转换？→ 使用 **CoordinateConverter**
- [ ] 需要文件路径操作？→ 使用 **PathHelper**
- [ ] 需要剖切优化？→ 使用 **SectionClipHelper**
- [ ] 需要显示/隐藏对象？→ 使用 **VisibilityHelper**
- [ ] 需要线程安全操作？→ 使用 **NavisworksApiHelper**

## 禁止行为

以下行为在项目中是**禁止**的：

1. ❌ 直接设置 `Window.Owner = Application.Current.MainWindow`
2. ❌ 硬编码单位转换因子（如 `* 0.001`）
3. ❌ 使用 `Console.WriteLine` 输出日志
4. ❌ 自己实现距离/角度计算（已有 GeometryHelper）
5. ❌ 自己实现集合的线程安全包装（使用 ThreadSafeObservableCollection）
6. ❌ 自己实现缓存刷新逻辑（使用 NavisworksApiHelper.SafeCacheRefresh）

## 扩展阅读

- 项目规范：`AGENTS.md`
- UI开发规范：`doc/guide/design_principles.md`
- Navisworks API 使用：`SKILL.md` (nw-api)