213 lines
5.3 KiB
Markdown
213 lines
5.3 KiB
Markdown
# CLAUDE.md
|
||
|
||
NavisworksTransport - Navisworks 2026 物流路径规划插件 (A* 算法、碰撞检测、动画)
|
||
|
||
**环境**: Windows 10+, .NET Framework 4.8, C# 7.3
|
||
|
||
**原则**: 专注 2026，不考虑向后兼容
|
||
|
||
## 编译与测试
|
||
|
||
```bash
|
||
./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 源于混淆单位。
|
||
|
||
### 转换原则
|
||
|
||
```csharp
|
||
// ✅ 函数入口一次性转换
|
||
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`
|
||
|
||
### 常见错误
|
||
|
||
```csharp
|
||
// ❌ 直接用米制常量
|
||
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 约定
|
||
|
||
```csharp
|
||
BoundingBox3D bbox = modelItem.BoundingBox(); // 模型单位
|
||
Point3D worldPos = gridMap.GridToWorld3D(gridPos); // 模型单位
|
||
|
||
double cellSize = 0.5; // 米，需转换
|
||
```
|
||
|
||
### 日志规范
|
||
|
||
```csharp
|
||
// ✅ 标注单位
|
||
LogManager.Info($"网格: {cellSize}米 → {cellSizeInModelUnits:F2}模型单位");
|
||
```
|
||
|
||
**违反导致**: 路径失败、碰撞错误、网格异常
|
||
|
||
### 其他关键点
|
||
|
||
- **网格坐标**: 网格单元**左下角**，非中心
|
||
- **坐标转换**: 多层系统支持 2D→3D
|
||
|
||
## Navisworks API
|
||
|
||
### 双 API 策略
|
||
|
||
- Native API (`Autodesk.Navisworks.Api`) - 核心功能
|
||
- COM API (`Autodesk.Navisworks.ComApi`) - 属性持久化、TimeLiner
|
||
|
||
### 插件注册
|
||
|
||
```csharp
|
||
[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 搜索策略
|
||
|
||
```bash
|
||
# 类成员列表入口
|
||
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\` 仅参考，不维护
|