tian/NavisworksTransport

Fork 0

tian 4069668a2a 修复批处理未加载待处理项，并修复空中路径创建

2026-01-29 13:27:43 +08:00

14 KiB

Raw Blame History

AGENTS.md

本文件为AI编码助手提供 NavisworksTransport 项目的完整开发指南。阅读本文件前，请确保你已经了解项目的基本结构和目标。

项目概述

NavisworksTransport 是专为 Autodesk Navisworks Manage 2026 开发的物流路径规划插件，用于BIM模型中的运输冲突检测和路径规划。

核心功能

物流属性管理: 为模型分配类别属性（门、电梯、楼梯、通道、障碍物）
自动路径规划: 基于A*算法的2.5D网格路径规划，支持通道优先策略
碰撞检测: 与Navisworks ClashDetective集成，实现动态碰撞检测
动画仿真: TimeLiner集成，支持路径动画播放和仿真
吊装路径: 支持空中吊装路径规划（两次点击模式）
数据导出: 支持XML、JSON、CSV格式的路径数据导出，以及DELMIA数据格式

技术栈

组件	版本/说明
目标平台	Navisworks Manage 2026
框架	.NET Framework 4.8
语言	C# 7.3
架构	x64
UI框架	WPF (MVVM模式) + Windows Forms集成

项目文件

文件	说明
`NavisworksTransportPlugin.csproj`	主插件项目（旧式csproj格式）
`NavisworksTransport.UnitTests.csproj`	单元测试项目
`NavisworksTransport.sln`	Visual Studio 解决方案
`packages.config`	NuGet包配置（旧式包管理）
`default_config.toml`	默认配置文件模板
`compile.bat`	构建脚本
`run-unit-tests.bat`	测试脚本
`deploy-plugin.bat`	部署脚本

构建命令

环境要求

Windows 10 或更高版本
Visual Studio 2022（Community/Professional）
Navisworks Manage 2026（已安装）
.NET Framework 4.8 Developer Pack

主要构建

./compile.bat

自动检测 Visual Studio 2022 的 MSBuild
构建 Release 配置的 x64 平台
输出目录: bin\x64\Release\

手动构建

# 设置MSBuild路径
set MSBUILD_PATH="C:\Program Files\Microsoft Visual Studio\2022\Community\MSBuild\Current\Bin\MSBuild.exe"

# 构建主项目
%MSBUILD_PATH% "NavisworksTransportPlugin.csproj" /p:Configuration=Release /p:Platform=x64

# 构建测试项目
%MSBUILD_PATH% "NavisworksTransport.UnitTests.csproj" /p:Configuration=Release /p:Platform=x64

运行测试

./run-unit-tests.bat

该脚本将：

构建主项目
构建测试项目
使用 VSTest.Console 运行单元测试

部署插件

./deploy-plugin.bat

自动复制插件文件到 Navisworks 插件目录： C:\ProgramData\Autodesk\Navisworks Manage 2026\plugins\NavisworksTransportPlugin\

项目架构

目录结构

src/
├── Core/                          # 核心插件和业务逻辑
│   ├── MainPlugin.cs              # DockPanePlugin - Ribbon UI + 停靠面板
│   ├── PathClickToolPlugin.cs     # ToolPlugin - 3D鼠标交互工具
│   ├── PathPointRenderPlugin.cs   # RenderPlugin - 3D可视化渲染
│   ├── PathPlanningManager.cs     # 路径规划管理器（与UI解耦）
│   ├── PathDataManager.cs         # 路径数据管理
│   ├── PathDatabase.cs            # SQLite数据库操作
│   ├── PathCurveEngine.cs         # 路径曲线化引擎
│   ├── UIStateManager.cs          # 线程安全的UI状态管理
│   ├── Animation/                 # 动画系统
│   │   ├── PathAnimationManager.cs
│   │   └── TimeLinerIntegrationManager.cs
│   ├── Collision/                 # 碰撞检测
│   │   ├── ClashDetectiveIntegration.cs
│   │   └── BatchCollisionProcessor.cs
│   ├── Spatial/                   # 空间索引
│   │   ├── SpatialHashGrid.cs
│   │   └── SpatialIndexManager.cs
│   ├── Properties/                # 属性管理
│   │   ├── CategoryAttributeManager.cs
│   │   └── NavisworksComPropertyManager.cs
│   └── Config/                    # 配置管理
│       ├── SystemConfig.cs
│       └── ConfigManager.cs
├── Commands/                      # 命令模式实现
│   ├── CommandBase.cs
│   ├── CommandManager.cs
│   ├── AutoPathPlanningCommand.cs
│   └── ...
├── PathPlanning/                  # A*算法和网格地图
│   ├── GridMap.cs                 # 网格地图定义
│   ├── GridMapGenerator.cs        # 网格生成器
│   ├── AutoPathFinder.cs          # A*寻路实现
│   ├── ChannelBasedGridBuilder.cs # 通道优先网格构建
│   ├── VoxelGrid.cs               # 3D体素网格（实验性）
│   └── PathOptimizer.cs           # 路径优化
├── UI/WPF/                        # WPF用户界面
│   ├── Views/                     # XAML视图
│   ├── ViewModels/                # MVVM视图模型
│   ├── Models/                    # 数据模型
│   ├── Converters/                # 值转换器
│   ├── Commands/                  # WPF命令
│   └── Services/                  # UI服务
└── Utils/                         # 工具类
    ├── UnitsConverter.cs          # 单位转换（关键！）
    ├── LogManager.cs              # 日志管理
    ├── GeometryHelper.cs          # 几何计算
    └── ...

UnitTests/                         # 单元测试
├── Core/                          # 核心功能测试
├── Commands/                      # 命令测试
└── Utils/                         # 工具类测试

插件类型说明

插件类	类型	功能
`MainPlugin.cs`	DockPanePlugin	主UI面板，包含WPF控件宿主
`PathClickToolPlugin.cs`	ToolPlugin	鼠标点击工具，获取精确的3D坐标
`PathPointRenderPlugin.cs`	RenderPlugin	3D渲染，显示路径点和连线

关键依赖

Navisworks API（必须安装Navisworks 2026）：

Autodesk.Navisworks.Api.dll
Autodesk.Navisworks.ComApi.dll
Autodesk.Navisworks.Interop.ComApi.dll
Autodesk.Navisworks.Timeliner.dll
Autodesk.Navisworks.Clash.dll
Autodesk.Navisworks.Controls.dll

NuGet包：

RoyT.AStar 3.0.2 - A*寻路算法
geometry4Sharp 1.0.0 - 3D几何计算（体素路径规划）
System.Data.SQLite.Core 1.0.118.0 - SQLite数据库
Tomlyn 0.19.0 - TOML配置文件解析
MSTest.TestFramework 3.0.4 - 单元测试框架

代码规范

导入顺序

// 1. System命名空间
using System;
using System.Collections.Generic;
using System.Linq;

// 2. 第三方库
using RoyT.AStar;

// 3. Navisworks API
using Autodesk.Navisworks.Api;
using Autodesk.Navisworks.ComApi;
using Autodesk.Navisworks.Api.Plugins;

// 4. 项目命名空间（按字母顺序）
using NavisworksTransport.Commands;
using NavisworksTransport.Core;
using NavisworksTransport.PathPlanning;
using NavisworksTransport.UI.WPF.ViewModels;
using NavisworksTransport.Utils;

命名约定

类型	命名规则	示例
类	PascalCase	`PathPlanningManager`
接口	PascalCase + 'I'前缀	`IPathPlanningCommand`
方法	PascalCase	`GenerateGridMap`
属性	PascalCase	`CellSize`
字段	camelCase + 下划线前缀	`_uiStateManager`
常量	PascalCase	`MaxHeightDiff`
枚举	PascalCase	`GridGenerationMode`

单位系统 - 极其重要

所有网格地图和路径规划计算必须使用模型单位，严禁混用米制单位。

// ✅ 正确：在函数入口统一转换
public GridMap GenerateFromBIM(BoundingBox3D bounds, double cellSizeMeters, ...)
{
    double factor = UnitsConverter.GetMetersToUnitsConversionFactor(Application.ActiveDocument.Units);
    double cellSizeInModelUnits = cellSizeMeters * factor;
    // 后续所有计算使用 cellSizeInModelUnits
}

// ❌ 错误：混用单位
private const double MAX_HEIGHT_DIFF = 0.35; // 这是米！
if (heightDiff > MAX_HEIGHT_DIFF) // 单位不匹配，严重Bug！

UnitsConverter 提供以下方法：

GetUnitsToMetersConversionFactor() - 文档单位转米
GetMetersToUnitsConversionFactor() - 米转文档单位
ConvertToMeters(distance) - 转换距离为米
ConvertFromMeters(distanceInMeters) - 从米转换距离

错误处理

// ✅ 正确：记录并适当处理异常
try
{
    var result = SomeOperation();
    return result;
}
catch (Exception ex)
{
    LogManager.Error($"Operation failed: {ex.Message}");
    throw; // 或适当处理
}

// ❌ 错误：静默吞掉异常
try
{
    var result = SomeOperation();
    return result;
}
catch
{
    return null; // 隐藏了问题！
}

线程安全和UI更新

所有UI操作必须编组到主线程：

// ✅ 正确：使用UIStateManager进行线程安全更新
_uiStateManager.UpdateStatus("正在处理...");

// ✅ 正确：异步事件触发避免死锁
private void OnStatusChanged(string status)
{
    Task.Run(() =>
    {
        try
        {
            StatusChanged?.Invoke(this, status);
        }
        catch (Exception ex)
        {
            LogManager.Error($"StatusChanged事件失败: {ex.Message}");
        }
    });
}

配置系统

配置文件使用 TOML 格式，默认配置位于 default_config.toml：

[path_editing]
cell_size_meters = 0.5              # 网格单元大小（米）
max_height_diff_meters = 0.35       # 最大高度差（米）
vehicle_length_meters = 1.5         # 车辆长度
vehicle_width_meters = 1.0          # 车辆宽度
vehicle_height_meters = 2.0         # 车辆高度
safety_margin_meters = 0.1          # 安全间隙
default_path_turn_radius = 2.5      # 默认转弯半径
arc_sampling_step = 0.05            # 圆弧采样步长

[visualization]
margin_ratio = 0.1                  # 地图边距比例

[animation]
frame_rate = 30                     # 动画帧率
duration_seconds = 10.0             # 动画持续时间
detection_tolerance_meters = 0.05   # 检测容差
spatial_index_cell_size = 1.0       # 空间索引格子大小

[logistics]
traversable = true                  # 默认可通行性
priority = 5                        # 优先级（1-5）
height_limit_meters = 3.0           # 高度限制
speed_limit_meters_per_second = 0.8 # 速度限制
width_limit_meters = 3.0            # 宽度限制

运行时通过 ConfigManager.Instance.Current 访问配置。

测试策略

测试项目结构

UnitTests/
├── Core/
│   ├── PathCurveEngineTests.cs
│   └── UIStateManagerBasicTests.cs
├── Commands/
│   └── CommandBaseTests.cs
├── Collections/
│   └── ThreadSafeObservableCollectionBasicTests.cs
└── Utils/
    └── UnitsConverterTests.cs

测试框架

框架: MSTest 3.0.4
运行器: VSTest.Console.exe
目标框架: .NET Framework 4.8

编写测试

using Microsoft.VisualStudio.TestTools.UnitTesting;

namespace NavisworksTransport.UnitTests
{
    [TestClass]
    public class ExampleTests
    {
        [TestMethod]
        public void TestMethod_ShouldDoSomething()
        {
            // Arrange
            var input = "test";
            
            // Act
            var result = SomeMethod(input);
            
            // Assert
            Assert.AreEqual("expected", result);
        }
    }
}

注意事项

独立测试：不依赖Navisworks环境，测试核心算法逻辑
集成测试：需要完整的Navisworks 2026环境
日志位置: C:\ProgramData\Autodesk\Navisworks Manage 2026\plugins\NavisworksTransportPlugin\logs\debug.log

开发工作流

添加新功能的标准流程

定义接口（如果需要）
- 在 src/Commands/ 或 src/Core/ 中定义接口
实现核心逻辑
- 业务逻辑放在 src/Core/ 或 src/PathPlanning/
- 确保单位转换正确
添加命令封装（如果需要）
- 在 src/Commands/ 中实现命令类
- 继承 CommandBase 或实现 IPathPlanningCommand
更新UI
- ViewModel 在 src/UI/WPF/ViewModels/
- View 在 src/UI/WPF/Views/
注册到主插件
- 在 MainPlugin.cs 或相关管理器中集成
添加测试
- 在 UnitTests/ 对应目录添加测试

调试技巧

查看日志: 日志文件位于 C:\ProgramData\Autodesk\Navisworks Manage 2026\plugins\NavisworksTransportPlugin\logs\
使用 LogManager: 所有重要操作都应记录日志
Navisworks插件调试:
- 附加到 Roamer.exe 进程
- 使用 LogManager.Debug() 输出调试信息

常见问题

构建失败

错误: "MSBuild not found"
- 解决: 安装 Visual Studio 2022 或 Build Tools
错误: "无法找到 Autodesk.Navisworks.Api"
- 解决: 安装 Navisworks Manage 2026

运行时错误

错误: "单位不匹配导致的计算错误"
- 解决: 检查 UnitsConverter 使用是否正确
错误: "跨线程UI操作异常"
- 解决: 使用 UIStateManager 或 Dispatcher.Invoke
错误: "插件未加载"
- 解决: 检查插件是否部署到正确目录，检查依赖项是否存在

文档资源

API文档: doc/navisworks_api/NET/documentation/NET API.chm
COM API文档: doc/navisworks_api/COM/documentation/NavisWorksCOM.chm
设计文档: doc/design/2026/
架构设计: doc/architecture/
迁移指南: doc/migration/（2017到2026的API变更）

版本信息

当前版本: 2.0.0.0
程序集: NavisworksTransportPlugin
作者: Tian

注意: 本插件专门针对 Navisworks 2026 开发，不考虑向后兼容。

14 KiB Raw Blame History Unescape Escape