163 lines
6.2 KiB
Markdown
163 lines
6.2 KiB
Markdown
---
|
||
name: project-tools
|
||
description: Use when writing code that needs tool utilities (DialogHelper, UnitsConverter, LogManager, GeometryHelper, PathHelper, ModelHighlightHelper) in the NavisworksTransport project. Check this skill before writing new utility code to avoid reinventing existing tools.
|
||
---
|
||
|
||
# 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)
|