tian/NavisworksTransport
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
98c55045ad
NavisworksTransport/IFLOW.md

20 KiB
Raw Blame History

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. 编译解决方案

使用命令行

# 编译插件
compile.bat

# 运行单元测试
run-unit-tests.bat

部署

自动部署

# 部署插件到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

静默安装命令:

msiexec /i NavisworksTransport.Setup.msi /qn /l*v install.log

开发约定

代码分析方法

重要教训：分析可视化功能时的错误思考方式

在分析"通行空间可视化"功能时，犯了以下错误：

  1. 错误：只看方法名，不看实现

    • 搜索到 UpdateGridVisualizationSettings() 等方法名中包含"Grid"，就误以为需要生成网格地图
    • 实际上这里的"网格"指的是路径规划用的网格地图，而通行空间可视化只是改变路径的渲染风格

  2. 错误：没有深入查看渲染代码

    • 虽然找到了 PathPointRenderPlugin.cs，但没有仔细看它的渲染逻辑
    • 应该先看渲染插件如何渲染路径，发现 PathVisualizationMode.VehicleSpace 模式

  3. 错误：被表面信息误导

    • 日志显示"[网格可视化] 无缓存网格地图"，就以为需要生成网格地图
    • 实际上通行空间可视化不是生成新的可视化内容，而是改变现有路径的渲染方式（从圆柱体改为高高度长方体）

正确的分析方法应该是：

  1. 先看渲染代码：对于可视化功能，应该先看渲染插件的代码（如 PathPointRenderPlugin.cs）
  2. 理解本质：问自己"这个功能是什么"，而不是"怎么做"。通行空间可视化是"改变渲染风格"，而不是"生成网格地图"
  3. 查看现有实现：如果日志中已经有相关提示（如"路径可视化模式已更改: 车辆通行空间"），说明功能已经存在，只需要在合适的时机调用
  4. 不要只看方法名：方法名可能误导，要看实际实现代码
  5. 深入查看核心代码：对于可视化、动画等功能，应该先看对应的渲染/动画管理器的代码

架构模式

  • 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)单位(用户界面、日志、数据库存储等)
    • 单位转换: 使用 UnitsConverter.ConvertToMeters() 和 UnitsConverter.ConvertFromMeters() 进行转换
  • 向后兼容: 不写回退和向后兼容代码,出错即抛异常
  • 代码复用: 优先使用现有的辅助方法和工具类,避免重复代码。例如:
    • 查找物流属性模型时,使用 CategoryAttributeManager.GetLogisticsItemsByType() 而不是手动创建 Search 对象
    • 提取几何数据时,使用 GeometryHelper 中的现有方法
    • 计算距离时,使用 GeometryHelper.CalculatePointDistance() 等工具方法
  • 车辆尺寸与XYZ轴关系 (关键约定):
    • X轴: 长度方向（车辆前进方向，车头到车尾）
    • Y轴: 宽度方向（车辆侧面，左右两侧）
    • Z轴: 高度方向（垂直方向）
    • 朝向规则: 车辆沿路径移动时，X轴（长度方向）指向路径前进方向
    • 尺寸参数: VehicleLength = X轴尺寸，VehicleWidth = Y轴尺寸，VehicleHeight = Z轴尺寸
    • 通行空间计算（路径周围的可通行区域，沿路径延伸的"管道"）:
      • passageAlongPath: 沿路径方向的长度 = 路径本身的长度（渲染时使用）
      • passageAcrossPath: 垂直于路径方向的截面尺寸1
      • passageNormalToPath: 垂直于路径方向的截面尺寸2
      • 水平路径（地面、空轨）截面：使用车辆的宽度和高度
        • passageAcrossPath = 车辆宽度（Y轴）+ 2×间隙
        • passageNormalToPath = 车辆高度（Z轴）+ 间隙
      • 垂直路径（吊装）截面：使用车辆的宽度和长度
        • passageAcrossPath = 车辆宽度（Y轴）+ 2×间隙
        • passageNormalToPath = 车辆长度（X轴）+ 2×间隙
  • 单位系统:
    • 内部计算: 统一使用模型单位(避免频繁转换,提高性能)
    • 对外输出: 转换为米(m)单位(用户界面、日志、数据库存储等)
    • 单位转换: 使用 UnitsConverter.ConvertToMeters() 和 UnitsConverter.ConvertFromMeters() 进行转换
  • 向后兼容: 不写回退和向后兼容代码,出错即抛异常
  • 代码复用: 优先使用现有的辅助方法和工具类,避免重复代码。例如:
    • 查找物流属性模型时,使用 CategoryAttributeManager.GetLogisticsItemsByType() 而不是手动创建 Search 对象
    • 提取几何数据时,使用 GeometryHelper 中的现有方法
    • 计算距离时,使用 GeometryHelper.CalculatePointDistance() 等工具方法

测试

  • 单元测试: 使用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 文件调整系统参数:

[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插件开发规范。

联系方式

最后更新: 2026年1月5日