tian/NavisworksTransport
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

编写管理员手册

Browse Source
This commit is contained in:
tian 2026-02-26 00:44:11 +08:00
parent 2b151ebee5
commit 759a41fb7e
4 changed files with 282 additions and 362 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

211
CLAUDE.md
View File

@ -1,211 +0,0 @@
# CLAUDE.md
NavisworksTransport - Navisworks 2026 物流路径规划插件 (A* 算法、碰撞检测、动画)
**环境**: Windows 10+, .NET Framework 4.8, C# 7.3
**原则**: 专注 2026，不考虑向后兼容
## 编译与测试
```bash
./compile.bat # 必须用 ./ 前缀
# 单元测试
powershell -Command "& 'C:\...\MSBuild.exe' AStarTestRunner.csproj /p:Configuration=Debug /p:Platform=AnyCPU"
bin\Debug\AStarTestRunner.exe
```
**调试**: 日志在 `"C:\ProgramData\Autodesk\Navisworks Manage 2026\plugins\TransportPlugin\logs\debug.log"`
## 架构
### 插件类型
- **MainPlugin.cs**: AddInPlugin - Ribbon UI + 停靠面板
- **PathClickToolPlugin.cs**: ToolPlugin - 3D 鼠标交互
- **PathPointRenderPlugin.cs**: RenderPlugin - 3D 可视化
### 核心管理器
- PathPlanningManager - A* 路径规划
- LogisticsAnimationManager - 动画系统
- TimeLinerIntegrationManager - TimeLiner 集成
- CategoryAttributeManager - COM API 属性持久化
- VisibilityManager - 图层控制
- ModelSplitterManager - 模型导出
### 数据层
- PathPlanningModels - 事件驱动状态管理
- PathDataManager - JSON 序列化
- CoordinateConverter - 2D↔3D 坐标转换
- GeometryExtractor - 空间分析
- FloorDetector - 楼层检测
### UI
- WPF (MVVM): `src\UI\WPF\` - LogisticsControlPanel
- WinForms: 遗留对话框
- ElementHost 嵌入
## ⚠️ 模型单位系统 - 极其重要
**核心**: 网格地图和路径规划**统一使用模型单位**，不用米制。大量 bug 源于混淆单位。
### 转换原则
```csharp
// ✅ 函数入口一次性转换
public GridMap GenerateFromBIM(BoundingBox3D bounds, double cellSize, ...)
{
double factor = UnitsConverter.GetMetersToUnitsConversionFactor(Application.ActiveDocument.Units);
double cellSizeInModelUnits = cellSize * factor;
// 之后全用模型单位
}
// ❌ 计算中混用单位
```
### 必须使用模型单位
GridMapGenerator 和 AutoPathFinder 中所有参数：CellSize, ObjectRadius, SafetyMargin, ObjectHeight, ScanHeight, InflationRadius, MaxHeightDiff
### 命名约定
- 米制: `xxxMeters` (如 `cellSizeMeters`)
- 模型单位: `xxxInModelUnits` (如 `cellSizeInModelUnits`)
- 转换系数: `metersToModelUnitsConversionFactor`
### 常见错误
```csharp
// ❌ 直接用米制常量
private const double MAX_HEIGHT_DIFF = 0.35; // 米！
if (heightDiff > MAX_HEIGHT_DIFF) // Bug!
// ✅ 转换后用
private const double MAX_HEIGHT_DIFF_METERS = 0.35;
double maxHeightDiffInModelUnits = MAX_HEIGHT_DIFF_METERS * factor;
// ❌ 循环中重复转换
for (...) { double v = x * UnitsConverter.Get...(); }
// ✅ 提前转换
double factor = UnitsConverter.Get...();
double v = x * factor;
for (...) { /* 用 v */ }
```
### API 约定
```csharp
BoundingBox3D bbox = modelItem.BoundingBox(); // 模型单位
Point3D worldPos = gridMap.GridToWorld3D(gridPos); // 模型单位
double cellSize = 0.5; // 米，需转换
```
### 日志规范
```csharp
// ✅ 标注单位
LogManager.Info($"网格: {cellSize}米 → {cellSizeInModelUnits:F2}模型单位");
```
**违反导致**: 路径失败、碰撞错误、网格异常
### 其他关键点
- **网格坐标**: 网格单元**左下角**，非中心
- **坐标转换**: 多层系统支持 2D→3D
## Navisworks API
### 双 API 策略
- Native API (`Autodesk.Navisworks.Api`) - 核心功能
- COM API (`Autodesk.Navisworks.ComApi`) - 属性持久化、TimeLiner
### 插件注册
```csharp
[Plugin("NavisworksTransport.MainPlugin", "YourDeveloperID")]
[AddInPlugin(AddInLocation.AddIn)]
public class MainPlugin : AddInPlugin { }
```
### 关键点
- GlobalExceptionHandler - MainPlugin 构造函数初始化
- UI 操作必须编组到主线程
- 实现前查阅 `doc\navisworks_api\`
## 核心系统
### 路径规划
- A*: RoyT.AStar 库
- 动画: Transform + 碰撞检测
- TimeLiner: 自定义动画同步
- 实时碰撞: ClashDetectiveIntegration
### 状态管理
- PathEditState: None, AddingPoints, EditingPath
- JSON 持久化 + LogisticsAttributeChangedEventArgs
### 物流分类
门、电梯、楼梯、通道、障碍物、装卸区、停车区、检查点
### 包管理
- 旧式 csproj: `<Reference Include>` + HintPath
- packages.config 手动管理 (**不用** `dotnet add package`)
- 路径: `packages\{PackageId}.{Version}\lib\{TargetFramework}\{Assembly}.dll`
## 开发原则
### 防御性编程
- ✅ 检测异常报错，让问题暴露
- ❌ 默认值掩盖问题
### 容错处理
- ✅ 错误日志 + 中断流程
- ❌ 自动"修复"继续执行
### 核心优先级
1. 快速暴露 > 看起来正常
2. 报错 > 静默失败
3. 数据一致性 > 宽松验证
4. 最小化修改 > 复杂逻辑
## API 文档查询
### CHM 搜索策略
```bash
# 类成员列表入口
AllMembers_T_Autodesk_Navisworks_Api_ClassName.htm
# 精确搜索
find . -name "*ClassName*" -o -name "*MethodName*"
grep -r "SaveFile\|Export.*nwd" --include="*.htm" doc/navisworks_api/
```
**常用路径**:
- Document: `AllMembers_T_Autodesk_Navisworks_Api_Document.htm`
- TimeLiner: `AllMembers_T_Autodesk_Navisworks_Api_Timeliner_*.htm`
- 插件基类: `AllMembers_T_Autodesk_Navisworks_Api_Plugins_*.htm`
**避免**: HTML 内容模糊搜索、GUID 文件名、宽泛搜索词
## 工作流程
- 使用中文交流和注释
- Agent 任务前 Plan 模式设计方案

149
QWEN.md
View File

@ -1,149 +0,0 @@
# 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)
### 项目结构
```
TransportPlugin/
├── src/
│ ├── Core/ # 核心业务逻辑
│ │ ├── Animation/ # 动画管理 (LogisticsAnimationManager, TimeLinerIntegrationManager)
│ │ ├── Collision/ # 碰撞检测 (ClashDetectiveIntegration)
│ │ ├── Properties/ # 属性管理 (CategoryAttributeManager)
│ │ ├── MainPlugin.cs # 插件主入口和旧版UI
│ │ ├── PathPlanningManager.cs # 路径规划核心逻辑
│ │ ├── PathPlanningModels.cs # 路径数据模型
│ │ ├── VisibilityManager.cs # 可见性控制
│ │ └── ... # 其他核心组件
│ ├── UI/
│ │ └── WPF/ # 新版WPF UI
│ │ ├── ViewModels/ # MVVM ViewModels
│ │ ├── Views/ # MVVM Views (UserControls)
│ │ ├── LogisticsControlPanel.xaml # 主停靠面板
│ │ └── ...
│ ├── Utils/ # 工具类 (日志、几何、坐标转换等)
│ └── Legacy/ # 为兼容性保留的旧代码
├── Properties/
│ └── AssemblyInfo.cs
├── TransportPlugin.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. 输出文件为 `TransportPlugin.dll`，位于 `bin\Debug\` 或 `bin\Release\` 目录下。
### 部署与安装
1. 编译生成 `TransportPlugin.dll`。
2. 插件会自动安装到 Navisworks 插件目录：
`[Navisworks安装路径]\Plugins\TransportPlugin\`
3. 重启 Navisworks 即可在 "附加模块" 选项卡中找到插件。
### 运行与调试
* 在 Visual Studio 中可以直接调试插件，方法是设置 Navisworks 可执行文件（如 `NwAddinDev.exe` 或 `Navisworks.exe`）为启动外部程序。
* 插件运行时会在 `%AppData%\Autodesk Navisworks Manage 2026\PluginsData\TransportPlugin` 目录下生成日志文件。
## 开发约定与实践
* **MVVM 模式**: 新的 UI 开发强烈推荐使用 WPF 和 MVVM 模式，将 UI 逻辑 (`ViewModel`) 与 UI 呈现 (`View`) 分离。
* **全局异常处理**: 使用 `GlobalExceptionHandler` 类来捕获和处理未处理的异常，提供用户友好的错误提示。
* **日志记录**: 使用 `LogManager` 进行统一的日志记录，便于调试和问题追踪。
* **安全执行**: 关键操作包装在 `GlobalExceptionHandler.SafeExecute` 方法中，以提高稳定性。
* **COM API 使用**: 在需要与 Navisworks 属性系统深度交互时，谨慎使用 COM API，并注意处理缓存和刷新问题。

280
doc/guide/administrator_manual.md Normal file
View File

@ -0,0 +1,280 @@
# NavisworksTransport 插件管理员手册
本手册面向系统管理员，介绍 NavisworksTransport 物流路径规划插件的部署、升级、数据管理和维护操作。
---
## 目录
1. [系统要求](#系统要求)
2. [插件安装](#插件安装)
3. [插件升级](#插件升级)
4. [路径数据导出与导入](#路径数据导出与导入)
5. [数据库管理](#数据库管理)
6. [日志与故障排查](#日志与故障排查)
7. [常见问题](#常见问题)
---
## 系统要求
### 软件环境
| 组件 | 版本要求 |
|------|---------|
| 操作系统 | Windows 10/11 64位 |
| Autodesk Navisworks | Manage 2026 |
| .NET Framework | 4.8 或更高 |
### 权限要求
- **安装插件**: 需要管理员权限（写入 `C:\ProgramData\Autodesk\`）
- **运行插件**: 普通用户权限即可
- **数据库操作**: 对模型文件所在目录有读写权限
---
## 插件安装
### 安装前准备
1. 确认已安装 Navisworks Manage 2026
2. 关闭 Navisworks
3. 准备好安装包（包含 `TransportPlugin.dll` 和 `resources` 文件夹）
### 安装步骤
1. **创建插件目录**
创建目录：`C:\ProgramData\Autodesk\Navisworks Manage 2026\plugins\TransportPlugin\`
2. **复制文件**
将以下文件复制到插件目录：
- `TransportPlugin.dll`
- `resources` 文件夹（如有）
3. **验证安装**
启动 Navisworks，检查菜单栏是否出现 **"物流路径"** 选项卡。
---
## 插件升级
### 升级前准备
1. **备份数据**（详见[数据库管理](#数据库管理)）
2. **关闭 Navisworks**
3. **记录当前版本**（查看 `TransportPlugin.dll` 文件属性）
### 升级步骤
1. **备份旧版本**（可选）
复制 `TransportPlugin.dll` 为 `TransportPlugin_backup.dll`
2. **替换文件**
将新版本的 `TransportPlugin.dll` 复制到插件目录，覆盖旧文件。
3. **验证升级**
启动 Navisworks，检查插件是否正常加载，验证现有数据是否完整。
### 版本回滚
如升级后出现问题：
1. 关闭 Navisworks
2. 将备份的 `TransportPlugin_backup.dll` 重命名为 `TransportPlugin.dll`
3. 重新启动 Navisworks
---
## 路径数据导出与导入
### 导出路径数据
#### 支持的格式
| 格式 | 扩展名 | 用途 |
|------|-------|------|
| XML | `.xml` | 标准格式，推荐用于备份 |
| JSON | `.json` | 数据交换 |
| CSV | `.csv` | Excel 查看分析 |
#### 导出步骤
1. 在 **"路径编辑"** 面板中找到 **"路径文件管理"** 区域
2. 选择导出方式：
- **"导出全部"**：导出所有路径
- **"导出选中路径"**：导出当前选中的路径
3. 选择保存位置和格式
4. 点击"保存"
**命名建议**: `项目名_日期.xml`
### 导入路径数据
#### 导入步骤
1. 在 **"路径文件管理"** 区域点击 **"导入"** 按钮
2. 选择要导入的文件（XML 或 JSON）
3. 点击"确定"
导入的路径将自动合并到现有路径列表中。如遇重名路径，系统会自动重命名。
---
## 数据库管理
### 数据库概述
- **位置**: 与模型文件（`.nwd`）同目录
- **文件名**: 与模型文件同名，扩展名为 `.db`
- **示例**: `Project.nwd` → `Project.db`
### 数据备份
#### 通过插件界面备份
1. 打开 **"系统管理"** 选项卡
2. 在 **"数据管理"** 区域点击 **"备份数据"** 按钮
3. 选择保存位置
4. 系统自动导出所有路径、检测记录和截图
#### 自动备份设置
1. 在 **"数据管理"** 区域勾选 **"启用自动备份"**
2. 设置保留备份数量（默认保留最近若干个）
#### 手动备份数据库文件
1. **关闭 Navisworks**（必须）
2. 复制模型文件同目录的 `.db` 文件到备份位置
### 数据恢复
1. 在 **"系统管理"** 选项卡的 **"数据管理"** 区域
2. 点击 **"恢复数据"** 按钮
3. 选择备份文件
4. 点击"确定"
或手动恢复：关闭 Navisworks 后，用备份的 `.db` 文件覆盖原文件。
### 数据库维护
- **修复数据库**: 在 **"数据管理"** 区域点击 **"修复数据库"** 按钮，检查并修复完整性
- **清空数据**: 点击 **"清空数据"** 按钮清空所有路径和检测记录（谨慎使用）
---
## 日志与故障排查
### 日志查看
1. 打开 **"系统管理"** 选项卡
2. 在 **"日志管理"** 区域点击 **"查看日志"** 按钮
### 日志文件位置
```
C:\ProgramData\Autodesk\Navisworks Manage 2026\plugins\TransportPlugin\logs\
```
### 日志级别设置
在 **"日志管理"** 区域选择日志级别：
- Debug：详细调试信息
- Info：一般信息
- Warning：警告信息
- Error：仅错误信息
### 常见问题
#### 插件未加载（无"物流路径"选项卡）
**检查项**:
- 插件目录是否存在 `TransportPlugin.dll`
- Navisworks 版本是否为 Manage 2026
- .NET Framework 4.8 是否已安装
**查看 Windows 事件查看器**:
- 运行 `eventvwr.msc`
- 查看 "Windows 日志" → "应用程序"
- 查找 Navisworks 或 .NET 相关错误
#### 无法保存路径
**检查项**:
- 磁盘剩余空间
- 模型文件目录的写入权限
- 是否有其他 Navisworks 实例占用该模型
#### 导出/导入失败
**检查项**:
- 目标目录写入权限
- 磁盘空间是否充足
- 导入文件格式是否正确
### 联系技术支持
收集以下信息：
1. **日志文件**: `debug.log`
2. **插件版本**: 在 **"系统管理"** 选项卡的 **"系统信息"** 区域查看
3. **系统信息**: 运行 `msinfo32` 导出
4. **问题描述**: 操作步骤、错误提示
---
## 常见问题
### Q: 如何查看插件版本？
**A**: 在 **"系统管理"** 选项卡的 **"系统信息"** 区域查看"插件版本"。
### Q: 可以在多台机器上使用吗？
**A**: 可以。在每台机器安装插件即可。路径数据随 `.db` 文件与模型一起共享。
### Q: 卸载插件会删除数据吗？
**A**: 不会。数据存储在模型目录的 `.db` 文件中。
### Q: 如何彻底卸载插件？
**A**: 删除插件目录：`C:\ProgramData\Autodesk\Navisworks Manage 2026\plugins\TransportPlugin\`
### Q: 升级后数据还能用吗？
**A**: 同主版本升级（如 2.1 → 2.2）完全兼容。跨主版本升级查看版本说明。
### Q: 如何迁移到新电脑？
**A**:
1. 在原电脑使用"备份数据"功能
2. 在新电脑安装插件
3. 使用"恢复数据"功能
---
## 附录
### 常用路径
| 用途 | 路径 |
|------|------|
| 插件目录 | `C:\ProgramData\Autodesk\Navisworks Manage 2026\plugins\TransportPlugin\` |
| 日志目录 | `C:\ProgramData\Autodesk\Navisworks Manage 2026\plugins\TransportPlugin\logs\` |
**文档版本**: 1.0
**适用插件版本**: 2.0.0.0 及更高版本

4
doc/requirement/todo_features.md
View File

@ -4,8 +4,8 @@
### [2026/2/24] ### [2026/2/24]
1. [x] （优化）吊装路径支持 1. [x] （优化）吊装路径支持多个水平层
2. [x] （功能） 2. [x] （文档）增加管理员使用手册
### [2026/2/14] ### [2026/2/14]