# NavisworksTransport 插件项目概述 ## 项目简介 NavisworksTransport 是一个用于 Autodesk Navisworks Manage 2026 的插件,专为物流路径规划和动画仿真而设计。它能够帮助用户在复杂的建筑模型中定义物流通道、规划运输路径,并生成动画来模拟设备移动过程,同时进行动态碰撞检测。 **当前版本**: 0.14.0 ## 技术架构 - **编程语言**: C# 7.3 - **开发环境**: .NET Framework 4.8 - **目标平台**: x64 - **主要依赖**: - Autodesk Navisworks API (2026版本) - Roy-T.AStar 3.0.2 (路径规划算法) - System.Data.SQLite 1.0.118.0 (数据存储) - Tomlyn 0.19.0 (TOML配置文件解析) - geometry4Sharp 1.0.0 (3D几何计算) - MSTest.TestFramework 3.0.4 (单元测试) - NETStandard.Library 2.0.3 (.NET Standard支持) ## 核心功能模块 ### 1. 物流属性管理 - 为模型元素分配物流类别属性(如门、电梯、楼梯、通道、障碍物、无关项) - 批量处理多个选中项目 - COM API 集成确保属性正确添加 - 物流属性列表与3D视图选择同步 - 支持单个模型可见性控制和属性回填 - 严格的数据验证机制,确保数据一致性 ### 2. 路径规划 #### 手动路径编辑 - 路径点添加、编辑、删除 - 智能工具切换系统(十字光标导航) - 空格键快速切换工具状态 - 路径点高亮和可视化 #### 自动路径规划 - **A*算法集成**: 使用Roy-T.AStar库实现高性能路径查找 - **2.5D网格地图生成**: 基于包围盒的高效网格生成算法 - **高度计算系统**: - 通道地面高度精确检测 - 坡度分析和楼梯台阶高度处理 - 线性和非线性坡度支持 - **路径优化算法**: - 最短路径策略(Shortest) - 局部直线优先策略(Straightest) - 室内导航优化 - 基于中心距离的安全优先算法 - 斜线路径优化(台阶处保留2个路径点) - **多层网格系统**: 支持楼梯、楼面等复杂场景 - **网格缓存机制**: 大幅提升路径规划速度 - **楼层过滤系统**: 基于通道楼层属性的智能过滤 #### 路径分析 - SQLite数据库存储路径数据 - 路径信息统计和分析 - 路径参数持久化(车辆尺寸、安全间隙、网格尺寸等) ### 3. 动画与仿真 - **动画系统**: - 基于路径的动画生成 - WPF Timer机制实现流畅动画播放 - 媒体控制功能(播放、暂停、步进、快放、反向播放) - 动画性能优化(单步时间从5秒降至15毫秒) - **TimeLiner集成**: 动画播放时自动创建运输任务 - **动态碰撞检测**: - Clash Detective API集成 - 基于动画帧的碰撞检测 - 碰撞位置记录和恢复机制 - 碰撞报告生成和统计 ### 4. 可视化 - **3D路径点和路线渲染**: - 手动路径连线(黑色) - 自动路径连线(橙色) - 路径点高亮和选择反馈 - **网格地图可视化**: - 空洞、障碍物、通行网格的可视化 - 网格点大小自适应 - 多种形状类型(圆形、正方形、立方体、点) - Google Material Design配色标准 - **碰撞结果高亮显示** - **导航地图生成**: 导出当前路径场景为图片 ### 5. 分层管理 - **智能楼层分析**: 支持按楼层和自定义属性分层 - **分层预览功能**: - 1级、2级、3级、全部四种遍历深度 - 实时预览结果(名称、对象数量、估算大小) - 缓存机制优化性能 - **分层导出**: - 批量导出功能 - 智能文件命名(项目名_分层名_时间戳) - 支持NWD导出选项配置 - 线程安全导出机制 - **可视化控制**: - 单独显示功能 - 保存开关控制 - 智能可见性保护算法 - **自定义分层属性**: 支持任意Navisworks模型属性作为分层依据 ### 6. 数据管理 - **SQLite数据库**: 路径数据和碰撞报告存储 - **TOML配置文件**: 系统设置管理(default_config.toml) - **JSON路径文件导入**: 支持灵活的数据交换格式 - **几何体缓存**: 提高模型加载和渲染性能 ### 7. 系统管理 - **MSI安装包**: 自动化安装包生成,支持静默安装 - **日志系统**: 完整的日志记录和查看功能 - **配置编辑器**: 可视化配置文件编辑 - **帮助系统**: 内置帮助文档和关于对话框 ## 项目结构 ``` NavisworksTransport/ ├── src/ │ ├── Commands/ # 命令模式实现 │ │ ├── IPathPlanningCommand.cs │ │ ├── CommandBase.cs │ │ ├── CommandManager.cs │ │ ├── CommandExecutor.cs │ │ ├── AutoPathPlanningCommand.cs │ │ ├── DeletePathCommand.cs │ │ ├── ExportPathCommand.cs │ │ ├── ImportPathCommand.cs │ │ ├── SetLogisticsAttributeCommand.cs │ │ ├── StartAnimationCommand.cs │ │ ├── GenerateCollisionReportCommand.cs │ │ └── VoxelPathFindingTestCommand.cs │ ├── Core/ # 核心业务逻辑 │ │ ├── Animation/ # 动画管理 │ │ ├── Collision/ # 碰撞检测 │ │ ├── Config/ # 配置管理 │ │ ├── Properties/ # 属性管理 │ │ ├── Spatial/ # 空间索引 │ │ ├── UIUpdate/ # UI更新管理 │ │ ├── MainPlugin.cs # 插件入口 │ │ ├── PathPlanningManager.cs │ │ ├── PathDataManager.cs │ │ ├── PathDatabase.cs │ │ ├── PathAnalysisService.cs │ │ ├── PathCurveEngine.cs │ │ ├── UIStateManager.cs │ │ ├── IdleEventManager.cs │ │ ├── DocumentStateManager.cs │ │ ├── VirtualVehicleManager.cs │ │ ├── ModelSplitterManager.cs │ │ ├── NavigationMapGenerator.cs │ │ ├── PathPointRenderPlugin.cs │ │ └── FloorAttributeManager.cs │ ├── PathPlanning/ # 路径规划算法 │ │ ├── GridMap.cs │ │ ├── GridMapGenerator.cs │ │ ├── GridMapCache.cs │ │ ├── AutoPathFinder.cs │ │ ├── PathOptimizer.cs │ │ ├── ChannelHeightDetector.cs │ │ ├── SlopeAnalyzer.cs │ │ ├── OptimizedHeightCalculator.cs │ │ ├── ChannelBasedGridBuilder.cs │ │ ├── TimeMarkerCalculationService.cs │ │ ├── VoxelGrid.cs # 3D体素路径规划(实验性) │ │ ├── VoxelPathFinder.cs │ │ └── VoxelGridVisualizer.cs │ ├── UI/ # WPF用户界面 │ │ └── WPF/ │ │ ├── Views/ # 视图 │ │ ├── ViewModels/ # 视图模型 │ │ ├── Models/ # 数据模型 │ │ ├── Commands/ # WPF命令 │ │ ├── Converters/ # 值转换器 │ │ ├── Collections/ # 线程安全集合 │ │ ├── Services/ # UI服务 │ │ ├── Interfaces/ # 接口定义 │ │ └── Resources/ # 资源文件 │ ├── Utils/ # 工具类 │ │ ├── LogManager.cs │ │ ├── NavisworksApiHelper.cs │ │ ├── GeometryHelper.cs │ │ ├── BoundingBoxGeometryUtils.cs │ │ ├── CoordinateConverter.cs │ │ ├── UnitsConverter.cs │ │ ├── FloorDetector.cs │ │ ├── ModelItemAnalysisHelper.cs │ │ ├── VisibilityHelper.cs │ │ └── GeometryCacheManager.cs │ └── Resources/ # 资源文件 ├── UnitTests/ # 单元测试 │ ├── Collections/ │ ├── Commands/ │ ├── Core/ │ ├── Utils/ │ └── TestHelpers/ ├── doc/ # 文档 │ ├── architecture/ # 架构文档 │ ├── design/ # 设计文档 │ ├── guide/ # 使用指南 │ ├── migration/ # 迁移文档 │ ├── navisworks_api/ # API文档 │ ├── requirement/ # 需求文档 │ └── working/ # 工作文档 ├── packages/ # NuGet包 ├── resources/ # 资源文件 ├── bin/ # 编译输出 ├── obj/ # 中间文件 ├── TestResults/ # 测试结果 ├── NavisworksTransport.sln # 解决方案文件 ├── NavisworksTransportPlugin.csproj # 主项目文件 ├── NavisworksTransport.UnitTests.csproj # 测试项目文件 ├── packages.config # NuGet包配置 ├── default_config.toml # 默认配置文件 ├── compile.bat # 编译脚本 ├── run-unit-tests.bat # 运行单元测试脚本 ├── deploy-plugin.bat # 部署插件脚本 ├── VERSION.md # 版本信息 ├── CHANGELOG.md # 变更日志 └── README.md # 项目说明 ``` ## 构建与运行 ### 环境要求 - **操作系统**: Windows 10 或更高版本 - **Navisworks**: Navisworks Manage 2026 - **开发工具**: Visual Studio 2022 (Community或Professional) - **运行时**: .NET Framework 4.8 - **测试工具**: MSTest Test Platform ### 构建步骤 #### 使用Visual Studio 1. 使用 Visual Studio 2022 打开 `NavisworksTransport.sln` 2. 还原 NuGet 包(自动或手动) 3. 选择配置: Release / x64 4. 编译解决方案 #### 使用命令行 ```batch # 编译插件 compile.bat # 运行单元测试 run-unit-tests.bat ``` ### 部署 #### 自动部署 ```batch # 部署插件到Navisworks插件目录 deploy-plugin.bat ``` #### 手动部署 1. 编译生成 `NavisworksTransportPlugin.dll` 2. 将输出目录内容复制到Navisworks插件目录: `[Navisworks安装路径]\Plugins\NavisworksTransportPlugin\` 3. 重启Navisworks即可使用 ### 安装包生成 项目支持MSI安装包生成: - 使用Visual Studio Installer Projects扩展 - 支持自动化构建和静默安装 - 安装包位置: `bin\x64\Release\NavisworksTransport.Setup.msi` 静默安装命令: ```batch msiexec /i NavisworksTransport.Setup.msi /qn /l*v install.log ``` ## 开发约定 ### 架构模式 - **MVVM模式**: WPF UI开发使用MVVM架构 - **Command模式**: 业务逻辑通过Command模式封装 - **依赖注入**: 使用服务接口实现松耦合 ### 核心组件 - **MainPlugin**: 插件入口点,负责初始化和生命周期管理 - **PathPlanningManager**: 路径规划核心业务逻辑管理器 - **CategoryAttributeManager**: 物流属性管理 - **PathPointRenderPlugin**: 3D路径可视化渲染 - **ConfigManager**: 系统配置管理 - **UIStateManager**: UI状态和线程安全更新管理 - **IdleEventManager**: Idle事件管理,优化UI性能 - **DocumentStateManager**: 文档状态管理 - **VirtualVehicleManager**: 虚拟车辆管理 - **PathAnimationManager**: 动画管理 - **TimeLinerIntegrationManager**: TimeLiner集成 - **ClashDetectiveIntegration**: 碰撞检测集成 ### 代码规范 - **配置文件**: 使用TOML格式 - **日志记录**: 使用内置的LogManager - **异常处理**: 通过GlobalExceptionHandler统一管理,不掩盖问题 - **线程安全**: COM API调用必须在主UI线程(STA)执行 - **单位系统**: 统一使用米(m)为单位 - **向后兼容**: 不写回退和向后兼容代码,出错即抛异常 ### 测试 - **单元测试**: 使用MSTest框架 - **测试覆盖**: 核心组件和关键业务逻辑 - **测试运行**: `run-unit-tests.bat` - **测试结果**: 保存在TestResults目录 ### 性能优化 - **空间索引**: 使用SpatialHashGrid优化碰撞检测 - **网格缓存**: GridMapCache提升路径规划速度 - **几何缓存**: GeometryCacheManager优化模型加载 - **线程安全**: ThreadSafeObservableCollection确保UI更新安全 - **Idle事件**: 使用Idle机制替代Timer,优化UI响应 ## 快速开始 ### 1. 插件安装 1. 运行MSI安装包或手动部署 2. 启动Navisworks Manage 2026 3. 在"附加模块"选项卡中找到"Transport Plugin" ### 2. 基本使用流程 #### 物流属性设置 1. 在Navisworks中选择要设置属性的模型项目 2. 点击"Transport Plugin" → "物流属性管理" 3. 在弹出窗口中选择物流类别(门、电梯、楼梯、通道、障碍物) 4. 点击"应用"为选中项目添加属性 #### 路径规划 1. 点击"路径编辑"页签 2. 选择路径策略(最短路径或直线优先) 3. 在3D视图中点击添加路径点 4. 点击"自动规划"生成路径 5. 调整路径参数(车辆尺寸、网格大小等) #### 动画仿真 1. 点击"动画控制"页签 2. 选择要播放的路径 3. 设置动画参数(帧率、持续时间) 4. 点击"播放"开始动画 5. 查看碰撞检测结果 #### 分层管理 1. 点击"分层管理"页签 2. 选择分层属性(楼层、区域等) 3. 设置遍历深度 4. 点击"预览"查看分层结果 5. 选择要导出的分层,点击"导出" ### 3. 配置管理 编辑 `default_config.toml` 文件调整系统参数: ```toml [path_editing] cell_size_meters = 0.5 vehicle_length_meters = 1.0 vehicle_width_meters = 1.0 vehicle_height_meters = 2.0 safety_margin_meters = 0.05 [animation] frame_rate = 30 duration_seconds = 10.0 detection_gap_meters = 0.05 ``` ## 版本历史 ### v0.14.0 (2025-12-01) - MSI安装包制作 - JSON路径文件导入 - 网格点可视化系统重构 - 空间索引优化 - 几何体缓存优化 ### v0.13.0 (2025-10-11) - 3D路径规划系统 - 多层网格系统 - 路径策略算法增强 - SQLite数据库集成 - 网格生成优化 ### v0.12.0 (2025-09-16) - 路径规划算法优化 - 可视化系统统一 - 动画系统重构 - 碰撞检测系统完善 - UI架构现代化 - 物流属性管理系统完善 - 分层管理系统优化 - 内存管理与性能优化 ### v0.11.0 (2025-09-08) - 局部直线优先路径算法 - 路径策略选择系统 - 网格可视化系统 - Roy-T.AStar集成优化 - UI架构现代化升级 - 内存管理优化 ### v0.10.0 (2025-09-06) - 智能工具切换系统 - 工具状态管理重构 - ClashDetective API重构 ### v0.9.0 (2025-09-04) - SearchAPI性能优化 - 代码架构重构 - UI原型开发 - 算法优化 ### v0.8.0 (2025-08-27) - 自定义分层管理系统 - VisibilityManager重构 - 智能文件命名系统 ### v0.7.0 (2025-08-18) - 分层管理功能完整实现 - WPF架构重构 - 线程安全解决方案 ### v0.6.0 (2025-08-17) - UI架构重构 - 线程安全与稳定性提升 ### v0.5.0 (2025-08-15) - Z坐标高度计算系统 - 楼层过滤系统 ### v0.4.0 (2025-08-14) - 单位转换系统重构 - 2.5D路径规划实现 ### v0.3.0 (2025-08-13) - Navisworks2026迁移 - WPF界面实现 ### v0.2.0 (2025-07-21) - 动画碰撞检测集成 - Clash Detective集成 ### v0.1.12 (2025-07-18) - TimeLiner集成功能 ## 技术支持 ### 常见问题 1. **插件未加载**: 确保Navisworks Manage 2026已正确安装,插件目录路径正确 2. **崩溃问题**: 查看日志文件,检查Navisworks API调用线程安全性 3. **路径规划失败**: 检查物流属性是否正确设置,通道是否连续 4. **碰撞检测不准确**: 调整检测间隙参数,检查车辆尺寸配置 ### 日志位置 日志文件位于: `[Navisworks安装路径]\Plugins\NavisworksTransportPlugin\logs\debug.log` ### 文档资源 - **使用说明**: `doc/working/使用说明.md` - **开发文档**: `doc/working/` - **API文档**: `doc/navisworks_api/` - **迁移文档**: `doc/migration/` - **设计文档**: `doc/design/` - **需求文档**: `doc/requirement/` ## 许可与贡献 本项目为Navisworks插件开发项目,遵循Autodesk插件开发规范。 ## 联系方式 - **项目仓库**: - **问题反馈**: 通过Git仓库Issue系统提交 - **开发文档**: 参考项目doc目录下的相关文档 --- **最后更新**: 2026年1月5日