5.9 KiB
5.9 KiB
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 |
几何缓存管理 |
快速参考
对话框开发
// ❌ 错误：直接设置Owner，可能在Navisworks环境中失败
var dialog = new MyDialog();
dialog.Owner = Application.Current.MainWindow; // 可能抛出异常！
dialog.Show();
// ✅ 正确：使用 DialogHelper
var dialog = new MyDialog();
DialogHelper.SetOwnerSafely(dialog); // 自动处理Navisworks环境
dialog.Show();
单位转换
// ❌ 错误：硬编码转换因子
double meters = modelUnits * 0.001; // 错误！不同文档单位不同
// ✅ 正确：使用 UnitsConverter
double meters = UnitsConverter.ConvertToMeters(modelUnits);
double modelUnits = UnitsConverter.ConvertFromMeters(meters);
日志记录
// ❌ 错误：使用Console或直接输出
Console.WriteLine($"Error: {ex.Message}"); // 不可见！
// ✅ 正确：使用 LogManager
LogManager.Info("操作成功");
LogManager.Warning("警告信息");
LogManager.Error("错误信息", exception);
几何计算
// ❌ 错误：自己实现距离计算
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);
模型高亮
// ✅ 使用 ModelHighlightHelper 高亮对象
ModelHighlightHelper.HighlightItems("myCategory", modelItems);
ModelHighlightHelper.ClearCategory("myCategory");
ModelHighlightHelper.ClearAllHighlights();
视角调整
// ✅ 使用 ViewpointHelper 调整视角
ViewpointHelper.AdjustViewpointToPathCenter(path);
ViewpointHelper.FocusOnModelItem(modelItem, 45, 0.25);
Viewpoint saved = ViewpointHelper.SaveCurrentViewpoint();
ViewpointHelper.RestoreViewpoint(saved);
详细文档
- DialogHelper 使用指南 - 对话框Owner设置和置顶显示
- UnitsConverter 使用指南 - 单位转换（极其重要）
- LogManager 使用指南 - 日志记录
- GeometryHelper 使用指南 - 3D几何计算
- PathHelper 使用指南 - 文件路径工具
- CoordinateConverter 使用指南 - 2D/3D坐标转换
- ModelHighlightHelper 使用指南 - 模型高亮
- NavisworksSelectionHelper 使用指南 - 选择集操作
- ViewpointHelper 使用指南 - 视点操作
- SectionClipHelper 使用指南 - 剖切操作
- NavisworksApiHelper 使用指南 - API通用工具
- VisibilityHelper 使用指南 - 可见性管理
使用检查清单
在编写新功能前，请检查：
- 需要显示对话框？→ 使用 DialogHelper
- 涉及单位转换？→ 使用 UnitsConverter
- 需要记录日志？→ 使用 LogManager
- 需要几何计算？→ 使用 GeometryHelper
- 需要高亮模型？→ 使用 ModelHighlightHelper
- 需要处理选择集？→ 使用 NavisworksSelectionHelper
- 需要调整视角？→ 使用 ViewpointHelper
- 需要坐标转换？→ 使用 CoordinateConverter
- 需要文件路径操作？→ 使用 PathHelper
- 需要剖切优化？→ 使用 SectionClipHelper
- 需要显示/隐藏对象？→ 使用 VisibilityHelper
- 需要线程安全操作？→ 使用 NavisworksApiHelper
禁止行为
以下行为在项目中是禁止的：
- ❌ 直接设置
Window.Owner = Application.Current.MainWindow - ❌ 硬编码单位转换因子（如
* 0.001） - ❌ 使用
Console.WriteLine输出日志 - ❌ 自己实现距离/角度计算（已有 GeometryHelper）
- ❌ 自己实现集合的线程安全包装（使用 ThreadSafeObservableCollection）
- ❌ 自己实现缓存刷新逻辑（使用 NavisworksApiHelper.SafeCacheRefresh）
扩展阅读
- 项目规范：
AGENTS.md - UI开发规范：
doc/guide/design_principles.md - Navisworks API 使用：
SKILL.md(nw-api)