tian/NavisworksTransport
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
ea809277c3
NavisworksTransport/doc/design/Design_Plan.md

16 KiB
Raw Blame History

NavisworksTransport 正式设计方案（Design Plan）

版本：v1.0
作者：Agent Mode
日期：2025-08-29

本方案依据以下输入编制：

  • 需求文档：doc/requirement/user_requiement.md（以 Navisworks 2017/Windows 7 为基线）
  • 项目上下文与结构参考：QWEN.md（包含 Navisworks 2026 的说明，仅作补充参考）
  • 源代码：src 目录（核心模块：Core、PathPlanning、UI/WPF、Utils 等）

重要说明：如需求文档与 QWEN.md 在版本目标存在差异（2017 vs 2026），本方案默认以需求文档为准（Navisworks 2017）。若需面向 Navisworks 2026 的兼容性与增强功能，请在部署与验证环节中选配“2026 兼容模式”。

一、总体设计

1.1 背景与目标

  • 背景：在 Autodesk Navisworks 环境中进行物流路径规划、动画仿真与碰撞检查，需高效的交互式工具，支持路径点编辑、自动路径规划（复杂场景）、导航输出与结构化结果文件（XML/JSON/CSV）。
  • 目标：
    • 快速完成通道选择与路径点规划（起点/路径点/终点），支持多路径管理与编辑；
    • 支持模型切分与层级可见性管理，聚焦物流相关构件；
    • 支持物流“类别属性”批量设置、识别与筛选；
    • 集成动画和碰撞检测能力，支持结果导出和路径分析；
    • 支持结构化结果文件输出，并满足 DELMIA 导入（按需求文档约束）。

1.2 需求综述（与需求文档对应）

  • 通道选择及路径点规划：模型切分、通道选择、路径点规划、多路径管理、编辑保存与导入、路径点自动贴合；
  • 物流“类别”设置：新增物流属性类别、设置可通行性/速度/宽度/优先级等属性，筛选与清除；
  • 层级创建与显示：自动隐藏/淡化非关键层，物流元素筛选，路径时间标签；
  • 交互式导航：交互式导航控件、结果输出（视频或图片）、输出格式（XML/JSON/CSV，可导入 DELMIA）；
  • 碰撞检查：动画生成与播放、碰撞检查/记录导出、路径规划分析与最优路径建议。

1.3 设计原则

  • 实用优先：在 Navisworks 2017 环境中保证稳定运行与较好性能；
  • 解耦分层：UI（WPF+MVVM）与核心逻辑（Core、PathPlanning）分离，便于后续扩展；
  • 向后兼容：在自动规划/碰撞集成等关键能力上提供降级路径（如 BoundingBox 模式回退）；
  • 可观察性：统一日志 LogManager，异常采用 GlobalExceptionHandler；
  • 数据可移植：路径/结果提供 XML/JSON/CSV 序列化能力（JSON 加载简化，建议 XML 为主）。

1.4 核心用例流程概览

  • 路径编辑（手动）：
    1. 用户通道选择（手动/属性筛选/自动查找可通行），计算通道边界；
    2. 进入编辑模式，3D 点击添加“起点/路径点/终点”，路线渲染与校验；
    3. 保存/导入/导出路径文件，维护历史记录；
  • 自动路径规划：
    1. 依据通道与模型生成网格（优先 ChannelBased 2.5D，失败回退 BoundingBox）；
    2. A* 求解路径并高度修正（贴合通道表面），渲染与事件广播；
  • 动画与碰撞：
    1. 基于路径生成 TimeLiner 动画；
    2. 动画过程缓存碰撞，结束后统一生成 Clash 测试与报告，高亮冲突对象；
  • 导航输出：
    1. 导航控件交互产生路径；
    2. 输出视频/图片与结构化结果（XML/JSON/CSV），满足 DELMIA 导入约束。

二、系统架构

2.1 分层架构与模块

  • UI 层（WPF + MVVM，少量 WinForms 遗留）：
    • Views: UI/WPF/Views/*（含 PathEditingView、AnimationControlView 等）
    • ViewModels: UI/WPF/ViewModels/*（LogisticsControlViewModel、PathEditingViewModel 等）
    • 主控面板：UI/WPF/LogisticsControlPanel.xaml
  • Core 业务层：
    • PathPlanningManager：路径规划主控（事件驱动、状态机、路径可视化）
    • CategoryAttributeManager：物流属性管理（COM API + .NET API）
    • VisibilityManager：可见性与层级控制
    • Animation：TimeLinerIntegrationManager、PathAnimationManager（动画控制）
    • Collision：ClashDetectiveIntegration（碰撞集成，动画期缓存 + 结束时统一测试）
    • ModelSplitterManager：模型切分（含简化实现）
  • PathPlanning 算法层：
    • GridMapGenerator：网格生成（ChannelBased 2.5D/BoundingBox），车辆膨胀优化
    • AutoPathFinder：A* 路径搜索、路径优化/插值、高度贴合
    • ChannelBasedGridBuilder、VerticalScanProcessor、TriangleSpatialHash 等支撑
  • Utils：日志、坐标/单位转换、Navisworks API 辅助

2.2 系统架构图（截图占位）

  • [截图占位] 系统架构图
    • 要求：体现 UI（WPF+MVVM）/Core/PathPlanning/Utils 分层，以及 TimeLiner、Clash 的集成位置与事件流（PathPlanningManager 事件：StatusChanged、EditStateChanged、RouteGenerated 等）。

2.3 模块关系与数据流

  • UI 通过 ViewModel 调用 PathPlanningManager 与其他 Core 服务；
  • PathPlanningManager 根据通道选择与编辑状态，驱动网格生成与 A* 求解，并渲染路径标记；
  • Animation/Collision 订阅路径与动画状态，按批次创建 TimeLiner 任务与 Clash 测试；
  • CategoryAttributeManager 负责属性新增/更新/移除与筛选；
  • VisibilityManager 提供“仅显示物流元素/隔离显示”等能力。

2.4 技术路线与选型

  • 语言/框架：C#，.NET Framework 4.8；
  • UI：WPF + MVVM（WinForms 仅用于部分对话框/遗留界面）；
  • 外部 API：Autodesk Navisworks API（2017 目标），COM API（属性写入）、TimeLiner API、Clash API；
  • 路径算法：RoyT.AStar（格网 A*），自研 2.5D 高度约束与车辆膨胀优化；
  • 序列化：XML（主）、JSON（简化加载）/CSV（结果）；
  • 日志/异常：LogManager、GlobalExceptionHandler。

2.5 关键数据模型（摘自源码）

  • PathPoint、PathRoute：路径点/路径集合，支持类型（Start/End/WayPoint）、长度/时间统计、XML/JSON 序列化；
  • ChannelBounds：通道边界与 2D 投影；
  • PathHistoryEntry/Manager：路径历史；
  • 事件模型：PathPlanningStatusChangedEventArgs、PathEditStateChangedEventArgs、RouteGeneratedEventArgs 等。

三、功能设计方案（逐模块）

3.1 模型切分

  • 目标：对大型模型按楼层/属性进行切分，提升性能与操作体验；
  • UI：ModelSplitterDialog（WinForms）；
  • Core：ModelSplitterManager、SimplifiedModelSplitterManager；
  • 设计：
    • 基于模型层级与属性枚举进行分层导出；
    • 提供环境检查与测试导出入口；
    • 与可见性/筛选配合以限定工作区域。

3.2 通道选择

  • 能力：
    • 手动选择：基于 Navisworks 选择；
    • 属性筛选：通过 CategoryAttributeManager.FilterByLogisticsType(FilterTraversableItems)；
    • 自动选择：Search API 扫描“可通行”物流元素；
  • PathPlanningManager.SelectChannels：计算组合边界 CombinedChannelBounds 并事件广播。

3.3 路径点规划（手动 + 自动）

  • 手动规划：
    • 工具：PathClickToolPlugin（精确拾取），PathPointRenderPlugin（3D 渲染）；
    • 流程：切换到 Creating/Editing 状态 -> 添加点 -> 渲染 -> 校验；
    • 路径点自动贴合：高度修正在 AutoPathFinder.ApplyPreciseHeightCorrection 中贴合通道表面（有通道数据时）；
  • 自动规划（复杂环境）：
    • 网格生成：GridMapGenerator.GenerateFromBIM
      • First 尝试 ChannelBased2_5D（通道优先、垂直扫描高度区间、车辆高度校验）；
      • Fallback 到 BoundingBox 模式（保持向后兼容）；
    • A*：AutoPathFinder.FindPath/ExecuteAStarAlgorithm
      • 路径优化（去冗余点、直线可达校验）、2.5D 高度插值与起终点原位修正；

3.4 路径管理、编辑、保存与导入

  • 编辑：创建/编辑/取消/完成编辑（FinishEditing 自动将末点设为终点并触发渲染与事件）；
  • 文件：PathFileSerializer（XML 主，JSON 简化，不建议作为主格式），支持多路径容器；
  • 历史：PathHistoryManager（Created/Edited/ManualSave 等），提供查看历史 UI；
  • 导入：DetectFileFormat -> LoadFromXml/LoadFromJson（JSON 加载简化，优先 XML）。

3.5 物流“类别”设置

  • 类别：为模型添加“物流属性”类别（类型、可通行、优先级、车辆尺寸、速度限制、宽度限制等）；
  • 批量处理：Add/Update/Remove，使用 COM API 正确索引方式避免覆盖错误；
  • 识别筛选：FilterTraversableItems/FilterByLogisticsType/FilterPassableAreas，供通道选择与可见性使用。

3.6 层级创建与显示

  • 隐藏/淡化非关键层：VisibilityManager.HideNonLogisticsItems/ShowAllItems/IsolateSpecificItems；
  • 物流元素筛选：ShowLogisticsItemsOnly；
  • 路径时间标签：在 PathPlanningManager.CalculateEstimatedTime（当前简单估算，后续可接入速度限制）。

3.7 交互式导航

  • 交互控件：UI/WPF 侧的主面板与路径/起终点选择；
  • 导出：支持视频/图片占位（由用户录屏或快照）、结构化文件（XML/JSON/CSV）；
  • DELMIA 导入：以 XML/CSV 为主，JSON 仅作参考（需要与 DELMIA 侧字段约定）。

3.8 动画生成与播放

  • TimeLinerIntegrationManager：创建运输任务（将路径关联到对象）、更新进度与状态文本、清理任务；
  • PathAnimationManager：具体的路径关键帧/移动输出（见 Core/Animation）；
  • 设计要点：
    • 以 TimelinerTask 为主线（Navisworks 2017 可用 API 能力有限，使用显示名/选择集传递状态）。

3.9 碰撞检查

  • ClashDetectiveIntegration：
    • 动画过程“实时缓存”碰撞（包围盒快速判定 + 去重 + 位置快照）；
    • 动画结束“统一创建并运行”测试（避免过程频繁创建）；
    • 高亮冲突对象、刷新 UI、导出报告；
  • 兼容性：优先 .NET Clash API，必要时绕过繁重的 COM 插件枚举。

3.10 路径规划分析

  • 汇总多条路径的碰撞结果，统计次数/距离/受影响对象；
  • 以“最小碰撞/最短距离/最小转弯次数”等指标推荐最优路径；
  • 输出分析报告（可选 CSV/XML）。

3.11 结果输出

  • 地图/路径可视化：3D 渲染 + 可截屏；
  • 结构化结果：XML/JSON/CSV（建议 XML/CSV 作为主导入格式到 DELMIA）。

四、系统部署方案

4.1 部署环境要求

  • 操作系统：Windows 7（需求文档基准），建议 Windows 10 及以上（更佳兼容性与性能）；
  • Autodesk Navisworks：Manage 2017（需求基线）。如需 2026，请切换引用与验证用例（见下文兼容模式）；
  • .NET Framework：4.8；
  • 开发工具：Visual Studio（建议 2019/2022）。

4.2 构建与产物

  • 解决方案：NavisworksTransport.sln；
  • 项目：NavisworksTransportPlugin.csproj；
  • 产物：NavisworksTransportPlugin.dll（bin/Debug 或 bin/Release）。

4.3 安装与部署流程

  • 自动安装（一键安装）：
    1. 识别 Navisworks 安装目录；
    2. 将插件 DLL 与必要资源复制到 [Navisworks安装路径]\Plugins\NavisworksTransportPlugin\；
    3. 注册菜单/配置（如需）；
  • 手动安装：
    1. 复制 NavisworksTransportPlugin.dll 至上述目录；
    2. 重启 Navisworks，在“附加模块”中查看“物流路径规划”。

4.4 运行配置

  • 日志输出：%AppData%\Autodesk Navisworks Manage 2017\PluginsData\NavisworksTransportPlugin（按 QWEN 中 2026 路径作适配）；
  • 配置切换：
    • 自动路径规划模式网格参数（cellSize、vehicleSize、safetyMargin、vehicleHeight）；
    • 2.5D/BoundingBox 模式选择（自动/强制选项）。

4.5 验证计划

  • 功能验证（最小可行用例）：
    • 通道选择（手动/自动），边界计算；
    • 路径编辑：起点/若干路径点/终点，渲染正确；
    • 路径保存/导入/导出（XML 主）、历史记录查看；
    • 物流属性设置：批量标注、筛选/清除、颜色高亮检查；
    • 层级显示：仅显示物流元素/隔离显示/恢复显示；
    • 自动规划：A* 成功求解、路径高度贴合、优化去冗余；
    • 动画：任务创建、播放/停止、进度状态变更；
    • 碰撞：动画期缓存、结束后创建测试与高亮、导出记录；
    • 导航输出：视频/图片占位与结构化结果（XML/CSV）；
  • 性能验证：
    • 大模型下网格生成耗时（ChannelBased 2.5D 与 BoundingBox 比对）；
    • 车辆膨胀优化（距离变换算法）前后对比；
    • PathPoint 渲染与状态事件对 UI 延迟的影响；
  • 兼容性验证：
    • Navisworks NWD/NWF/NWC 模型；
    • 不同单位（mm/cm/m/ft/in）下的单位换算正确性；
    • 如需 Navisworks 2026，切换引用并复测 TimeLiner/Clash API 行为差异。

4.6 2026 兼容模式（可选）

  • 若目标为 Navisworks 2026：
    • 切换引用到 2026 API；
    • 复核 QWEN.md 所述运行路径与日志输出位置；
    • 回归 TimeLiner 与 Clash API 可用性和接口差异；
    • 扩展安装器适配多版本并行安装。

五、非功能与质量保证

5.1 日志与异常处理

  • GlobalExceptionHandler：应用级异常捕获（线程/任务/未处理），尝试恢复组件，提供用户友好提示；
  • LogManager：Info/Warning/Error/Debug 统一记录，关键路径设充分日志（网格生成、A*、碰撞快照）。

5.2 性能优化要点

  • 网格生成：
    • ChannelBased 2.5D 优先（垂直扫描、空间哈希、通道优先），失败回退 BoundingBox；
    • 车辆膨胀：距离变换 O(n*m) 优化，跳过无障碍场景；
  • UI：
    • UIStateManager/QueueUIUpdate 降低 UI 阻塞；
    • WPF 绑定优化与虚拟化集合；
  • 搜索：
    • Search API 替代全量遍历，尤其在通道/楼层检索时。

5.3 可维护性

  • 分层清晰，事件驱动，保留向后兼容事件（_Legacy）；
  • 路径文件以 XML 为主，便于第三方集成；
  • 关键类职责单一（PathPlanningManager/CategoryAttributeManager/GridMapGenerator 等）。

六、风险与边界

  • Navisworks 版本差异：2017 与 2026 API 行为差异需要回归验证；
  • JSON 加载功能简化：建议以 XML 为主格式；
  • 大场景极大网格：需调大 cellSize 或范围裁剪以避免内存/耗时过大；
  • COM 属性写入：需严格使用相对索引覆盖逻辑（源码已修复），防止属性覆盖错乱；
  • 动画碰撞“位置恢复”：测试期间会短暂移动对象做验证，并在结束后恢复。

七、里程碑建议（示例）

  • M1（1 周）：路径编辑闭环（手动）、物流属性标注、可见性隔离；
  • M2（1-2 周）：自动路径（2.5D/回退）、XML 存取、历史；
  • M3（1 周）：动画与碰撞缓存 + 结束测试、报告与高亮；
  • M4（1 周）：导航输出与 DELMIA 结果结构；
  • M5（1 周）：性能与兼容性回归（2017 基线，若选 2026 追加一轮）。

八、截图占位与要求

  • [截图占位] 系统架构图：
    • 要求：展示 UI/Core/PathPlanning/Utils 分层与 TimeLiner/Clash 集成及事件流；
  • [截图占位] 主停靠面板（WPF）：
    • 要求：展示“类别设置/路径编辑/检测动画/系统管理”四个页签；
  • [截图占位] 路径编辑过程：
    • 要求：3D 视图中路径点（起点/路径点/终点）与线段渲染、状态提示；
  • [截图占位] 自动路径规划网格示意：
    • 要求：对比 ChannelBased 2.5D 与 BoundingBox 的可通行网格差异；
  • [截图占位] TimeLiner 任务与播放控制：
    • 要求：任务创建、播放、进度显示；
  • [截图占位] 碰撞检查结果：
    • 要求：高亮冲突对象、Clash 测试列表与数量统计；
  • [截图占位] 结果文件样例：
    • 要求：XML/CSV 字段示意，可用于 DELMIA 导入对齐。

附录 A：代码与模块清单（节选）

  • Core/MainPlugin、UI/WPF/LogisticsControlPanel.xaml：主入口与面板；
  • Core/PathPlanningManager：路径规划主控（状态、事件、可视化、导入导出）
  • PathPlanning/GridMapGenerator、AutoPathFinder：网格生成与 A* 路径；
  • Core/Properties/CategoryAttributeManager：物流属性管理（COM API 正确索引覆盖）；
  • Core/Animation/TimeLinerIntegrationManager：TimeLiner 任务集成；
  • Core/Collision/ClashDetectiveIntegration：动画期缓存 + 结束创建测试；
  • Core/VisibilityManager：可见性隔离与统计；
  • UI/WPF/ViewModels/*：MVVM 视图模型与命令绑定。