158 lines
5.9 KiB
Markdown
158 lines
5.9 KiB
Markdown
# 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)
|