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

## 联系方式

- **项目仓库**: <http://10.0.0.99:4000/tian/NavisworksTransport.git>
- **问题反馈**: 通过Git仓库Issue系统提交
- **开发文档**: 参考项目doc目录下的相关文档

---

**最后更新**: 2026年1月5日
