NavisworksTransport/CLAUDE.md

CLAUDE.md

NavisworksTransport - Navisworks 2026 物流路径规划插件 (A* 算法、碰撞检测、动画)

环境: Windows 10+, .NET Framework 4.8, C# 7.3

原则: 专注 2026，不考虑向后兼容

编译与测试

./compile.bat  # 必须用 ./ 前缀

# 单元测试
powershell -Command "& 'C:\...\MSBuild.exe' AStarTestRunner.csproj /p:Configuration=Debug /p:Platform=AnyCPU"
bin\Debug\AStarTestRunner.exe

调试: 日志在 "C:\ProgramData\Autodesk\Navisworks Manage 2026\plugins\NavisworksTransportPlugin\logs\debug.log"

架构

插件类型

• MainPlugin.cs: AddInPlugin - Ribbon UI + 停靠面板
• PathClickToolPlugin.cs: ToolPlugin - 3D 鼠标交互
• PathPointRenderPlugin.cs: RenderPlugin - 3D 可视化

核心管理器

• PathPlanningManager - A* 路径规划
• LogisticsAnimationManager - 动画系统
• TimeLinerIntegrationManager - TimeLiner 集成
• CategoryAttributeManager - COM API 属性持久化
• VisibilityManager - 图层控制
• ModelSplitterManager - 模型导出

数据层

• PathPlanningModels - 事件驱动状态管理
• PathDataManager - JSON 序列化
• CoordinateConverter - 2D↔3D 坐标转换
• GeometryExtractor - 空间分析
• FloorDetector - 楼层检测

UI

• WPF (MVVM): src\UI\WPF\ - LogisticsControlPanel
• WinForms: 遗留对话框
• ElementHost 嵌入

⚠️ 模型单位系统 - 极其重要

核心: 网格地图和路径规划统一使用模型单位，不用米制。大量 bug 源于混淆单位。

转换原则

// ✅ 函数入口一次性转换
public GridMap GenerateFromBIM(BoundingBox3D bounds, double cellSize, ...)
{
    double factor = UnitsConverter.GetMetersToUnitsConversionFactor(Application.ActiveDocument.Units);
    double cellSizeInModelUnits = cellSize * factor;
    // 之后全用模型单位
}

// ❌ 计算中混用单位

必须使用模型单位

GridMapGenerator 和 AutoPathFinder 中所有参数：CellSize, VehicleRadius, SafetyMargin, VehicleHeight, ScanHeight, InflationRadius, MaxHeightDiff

命名约定

• 米制: xxxMeters (如 cellSizeMeters)
• 模型单位: xxxInModelUnits (如 cellSizeInModelUnits)
• 转换系数: metersToModelUnitsConversionFactor

常见错误

// ❌ 直接用米制常量
private const double MAX_HEIGHT_DIFF = 0.35; // 米！
if (heightDiff > MAX_HEIGHT_DIFF) // Bug!

// ✅ 转换后用
private const double MAX_HEIGHT_DIFF_METERS = 0.35;
double maxHeightDiffInModelUnits = MAX_HEIGHT_DIFF_METERS * factor;

// ❌ 循环中重复转换
for (...) { double v = x * UnitsConverter.Get...(); }

// ✅ 提前转换
double factor = UnitsConverter.Get...();
double v = x * factor;
for (...) { /* 用 v */ }

API 约定

BoundingBox3D bbox = modelItem.BoundingBox(); // 模型单位
Point3D worldPos = gridMap.GridToWorld3D(gridPos); // 模型单位

double cellSize = 0.5; // 米，需转换

日志规范

// ✅ 标注单位
LogManager.Info($"网格: {cellSize}米 → {cellSizeInModelUnits:F2}模型单位");

违反导致: 路径失败、碰撞错误、网格异常

其他关键点

• 网格坐标: 网格单元左下角，非中心
• 坐标转换: 多层系统支持 2D→3D

Navisworks API

双 API 策略

• Native API (Autodesk.Navisworks.Api) - 核心功能
• COM API (Autodesk.Navisworks.ComApi) - 属性持久化、TimeLiner

插件注册

[Plugin("NavisworksTransport.MainPlugin", "YourDeveloperID")]
[AddInPlugin(AddInLocation.AddIn)]
public class MainPlugin : AddInPlugin { }

关键点

• GlobalExceptionHandler - MainPlugin 构造函数初始化
• UI 操作必须编组到主线程
• 实现前查阅 doc\navisworks_api\

核心系统

路径规划

• A*: RoyT.AStar 库
• 动画: Transform + 碰撞检测
• TimeLiner: 自定义动画同步
• 实时碰撞: ClashDetectiveIntegration

状态管理

• PathEditState: None, AddingPoints, EditingPath
• JSON 持久化 + LogisticsAttributeChangedEventArgs

物流分类

门、电梯、楼梯、通道、障碍物、装卸区、停车区、检查点

包管理

• 旧式 csproj: <Reference Include> + HintPath
• packages.config 手动管理 (不用 dotnet add package)
• 路径: packages\{PackageId}.{Version}\lib\{TargetFramework}\{Assembly}.dll

开发原则

防御性编程

• ✅ 检测异常报错，让问题暴露
• ❌ 默认值掩盖问题

容错处理

• ✅ 错误日志 + 中断流程
• ❌ 自动"修复"继续执行

核心优先级

1. 快速暴露 > 看起来正常
2. 报错 > 静默失败
3. 数据一致性 > 宽松验证
4. 最小化修改 > 复杂逻辑

API 文档查询

CHM 搜索策略

# 类成员列表入口
AllMembers_T_Autodesk_Navisworks_Api_ClassName.htm

# 精确搜索
find . -name "*ClassName*" -o -name "*MethodName*"
grep -r "SaveFile\|Export.*nwd" --include="*.htm" doc/navisworks_api/

常用路径:

• Document: AllMembers_T_Autodesk_Navisworks_Api_Document.htm
• TimeLiner: AllMembers_T_Autodesk_Navisworks_Api_Timeliner_*.htm
• 插件基类: AllMembers_T_Autodesk_Navisworks_Api_Plugins_*.htm

避免: HTML 内容模糊搜索、GUID 文件名、宽泛搜索词

工作流程

• 使用中文交流和注释
• Agent 任务前 Plan 模式设计方案
• src\Legacy\ 仅参考，不维护