151 lines
7.1 KiB
Markdown
151 lines
7.1 KiB
Markdown
# NavisworksTransport 项目上下文 (QWEN.md)
|
||
|
||
## 项目概述
|
||
|
||
NavisworksTransport 是一个针对 Autodesk Navisworks Manage 2026 开发的插件。其核心目标是简化在 Navisworks 环境中进行物流路径规划、动画仿真和碰撞检测的工作流程。
|
||
|
||
该插件旨在通过自动化 Animator 动画创建、Clash Detective 碰撞测试配置与运行，并提供直观的图形化碰撞结果显示，大大提高工作效率，为用户提供一个快速验证施工物流和设备移动可行性的工具。
|
||
|
||
### 核心功能
|
||
|
||
1. **类别属性分配**：
|
||
* 为模型项目添加预定义的物流类别属性（门、电梯、楼梯、通道、障碍物、装卸区、停车位、检查点）。
|
||
* 支持批量处理和用户友好的界面（按钮式对话框）。
|
||
* 通过 Navisworks COM API 确保属性正确添加。
|
||
|
||
2. **路径规划与编辑**：
|
||
* 允许用户在3D视图中交互式地定义移动对象的路径点。
|
||
* 管理多条路径，支持路径的创建、编辑、删除、导入、导出和历史记录。
|
||
* 提供路径可视化（3D标记）和基础验证（如点数、长度）。
|
||
|
||
3. **动画仿真**：
|
||
* 集成 Navisworks Timeliner API，根据规划的路径自动创建对象动画。
|
||
* 提供动画控制界面，允许用户设置播放速度、持续时间、帧率、循环等参数。
|
||
|
||
4. **碰撞检测**：
|
||
* 集成 Navisworks Clash API，自动配置并运行基于路径动画的动态碰撞测试。
|
||
* 提供碰撞检测状态和摘要信息。
|
||
|
||
5. **可见性控制**：
|
||
* 提供模型分层拆分和仅显示物流相关元素的功能，以优化视图和性能。
|
||
|
||
6. **用户界面**：
|
||
* 通过 Navisworks 的 Ribbon 界面添加自定义按钮启动插件。
|
||
* 提供一个停靠窗格 (DockPane) 作为主控制面板，使用 WPF 构建。
|
||
* 控制面板包含多个 Tab 页：类别设置、路径编辑、检测动画、系统管理。
|
||
|
||
## 技术架构
|
||
|
||
### 编程语言与框架
|
||
|
||
* **语言**: C#
|
||
* **框架**: .NET Framework 4.8
|
||
* **UI框架**: Windows Forms (部分遗留) 和 Windows Presentation Foundation (WPF)
|
||
* **API**: Autodesk Navisworks API (包括 COM API, Timeliner API, Clash API)
|
||
|
||
### 项目结构
|
||
|
||
```
|
||
NavisworksTransportPlugin/
|
||
├── src/
|
||
│ ├── Core/ # 核心业务逻辑
|
||
│ │ ├── Animation/ # 动画管理 (LogisticsAnimationManager, TimeLinerIntegrationManager)
|
||
│ │ ├── Collision/ # 碰撞检测 (ClashDetectiveIntegration)
|
||
│ │ ├── Properties/ # 属性管理 (CategoryAttributeManager)
|
||
│ │ ├── MainPlugin.cs # 插件主入口和旧版UI
|
||
│ │ ├── PathPlanningManager.cs # 路径规划核心逻辑
|
||
│ │ ├── PathPlanningModels.cs # 路径数据模型
|
||
│ │ ├── VisibilityManager.cs # 可见性控制
|
||
│ │ └── ... # 其他核心组件
|
||
│ ├── UI/
|
||
│ │ ├── Forms/ # 旧版WinForms UI (逐渐被WPF替代)
|
||
│ │ └── WPF/ # 新版WPF UI
|
||
│ │ ├── ViewModels/ # MVVM ViewModels
|
||
│ │ ├── Views/ # MVVM Views (UserControls)
|
||
│ │ ├── LogisticsControlPanel.xaml # 主停靠面板
|
||
│ │ └── ...
|
||
│ ├── Utils/ # 工具类 (日志、几何、坐标转换等)
|
||
│ └── Legacy/ # 为兼容性保留的旧代码
|
||
├── Properties/
|
||
│ └── AssemblyInfo.cs
|
||
├── NavisworksTransportPlugin.csproj # 项目文件
|
||
└── ...
|
||
```
|
||
|
||
### 核心组件
|
||
|
||
1. **`MainPlugin` (`MainPlugin.cs`)**:
|
||
* 插件的入口点，继承自 `Autodesk.Navisworks.Api.Plugins.DockPanePlugin`。
|
||
* 负责初始化插件、创建和管理主停靠窗格。
|
||
* 包含旧版的 Windows Forms UI 逻辑（已部分迁移到 WPF）。
|
||
|
||
2. **`LogisticsControlPanel` (`LogisticsControlPanel.xaml`, `LogisticsControlPanel.xaml.cs`)**:
|
||
* WPF 用户控件，作为主停靠窗格的内容。
|
||
* 使用 MVVM 模式，通过 `DataContext` 绑定到 `LogisticsControlViewModel`。
|
||
|
||
3. **`LogisticsControlViewModel` (`LogisticsControlViewModel.cs`)**:
|
||
* WPF UI 的核心逻辑处理中心。
|
||
* 管理 UI 状态、数据绑定、用户命令（ICommand）。
|
||
* 与 Core 层（如 `PathPlanningManager`）交互，驱动业务逻辑。
|
||
|
||
4. **`PathPlanningManager` (`PathPlanningManager.cs`)**:
|
||
* 路径规划的核心业务逻辑。
|
||
* 管理路径 (`PathRoute`) 和路径点 (`PathPoint`) 的创建、编辑、验证。
|
||
* 管理路径编辑状态（查看、创建、编辑）。
|
||
* 处理与 Navisworks 模型的交互（选择、边界计算）。
|
||
* 提供事件供 UI 层订阅。
|
||
|
||
5. **`CategoryAttributeManager` (`CategoryAttributeManager.cs`)**:
|
||
* 负责通过 Navisworks COM API 为模型项添加、更新、删除自定义物流属性。
|
||
* 定义了物流类别 (`LogisticsCategories`) 和属性 (`LogisticsProperties`)。
|
||
* 提供了筛选模型项的方法。
|
||
|
||
6. **`LogisticsAnimationManager`, `TimeLinerIntegrationManager`**:
|
||
* 负责与 Navisworks Timeliner 集成，根据路径数据创建动画。
|
||
|
||
7. **`ClashDetectiveIntegration`**:
|
||
* 负责与 Navisworks Clash Detective 集成，配置和运行碰撞测试。
|
||
|
||
8. **`VisibilityManager`**:
|
||
* 管理模型元素的可见性，实现"仅显示物流元素"等功能。
|
||
|
||
9. **`LogManager`**:
|
||
* 统一日志管理工具。
|
||
|
||
## 开发与构建
|
||
|
||
### 系统要求
|
||
|
||
* Windows 10 或更高版本
|
||
* Navisworks Manage 2026
|
||
* .NET Framework 4.8
|
||
* Visual Studio (推荐)
|
||
|
||
### 构建过程
|
||
|
||
1. 使用 Visual Studio 打开 `NavisworksTransport.sln` 解决方案文件。
|
||
2. 确保项目引用指向正确的 Navisworks 2026 API DLL 文件（路径在 `.csproj` 文件中定义）。
|
||
3. 选择 "Debug" 或 "Release" 配置。
|
||
4. 构建项目 (`Ctrl+Shift+B`)。
|
||
5. 输出文件为 `NavisworksTransportPlugin.dll`，位于 `bin\Debug\` 或 `bin\Release\` 目录下。
|
||
|
||
### 部署与安装
|
||
|
||
1. 编译生成 `NavisworksTransportPlugin.dll`。
|
||
2. 插件会自动安装到 Navisworks 插件目录：
|
||
`[Navisworks安装路径]\Plugins\NavisworksTransportPlugin\`
|
||
3. 重启 Navisworks 即可在 "附加模块" 选项卡中找到插件。
|
||
|
||
### 运行与调试
|
||
|
||
* 在 Visual Studio 中可以直接调试插件，方法是设置 Navisworks 可执行文件（如 `NwAddinDev.exe` 或 `Navisworks.exe`）为启动外部程序。
|
||
* 插件运行时会在 `%AppData%\Autodesk Navisworks Manage 2026\PluginsData\NavisworksTransportPlugin` 目录下生成日志文件。
|
||
|
||
## 开发约定与实践
|
||
|
||
* **MVVM 模式**: 新的 UI 开发强烈推荐使用 WPF 和 MVVM 模式，将 UI 逻辑 (`ViewModel`) 与 UI 呈现 (`View`) 分离。
|
||
* **全局异常处理**: 使用 `GlobalExceptionHandler` 类来捕获和处理未处理的异常，提供用户友好的错误提示。
|
||
* **日志记录**: 使用 `LogManager` 进行统一的日志记录，便于调试和问题追踪。
|
||
* **安全执行**: 关键操作包装在 `GlobalExceptionHandler.SafeExecute` 方法中，以提高稳定性。
|
||
* **COM API 使用**: 在需要与 Navisworks 属性系统深度交互时，谨慎使用 COM API，并注意处理缓存和刷新问题。
|