NavisworksTransport/.agents/skills/project-tools/SKILL.md

name	description
project-tools	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	几何缓存管理

快速参考

对话框开发

// ❌ 错误：直接设置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

禁止行为

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

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)