diff --git a/doc/design/2026/GPU加速可行性研究.md b/doc/design/2026/GPU加速可行性研究.md new file mode 100644 index 0000000..9c636cb --- /dev/null +++ b/doc/design/2026/GPU加速可行性研究.md @@ -0,0 +1,837 @@ +# Navisworks 插件 GPU 加速可行性研究 + +## 1. 研究背景与目标 + +### 1.1 背景 + +NavisworksTransport 插件当前实现了基于 A* 算法的路径规划和碰撞检测功能。随着模型规模的增长和实时性要求的提高，需要评估 GPU 加速技术在本项目中的可行性和必要性。 + +### 1.2 研究目标 + +- 调研 Navisworks API 是否提供 GPU 加速能力 +- 评估第三方 .NET GPU 计算库的适用性 +- 分析项目中哪些模块可以从 GPU 加速中受益 +- 给出实施建议和优先级排序 + +### 1.3 当前性能瓶颈 + +根据现有代码分析，主要性能瓶颈包括： + +1. **网格地图生成**（GridMapGenerator） + - BIM 模型几何扫描 + - 障碍物边界膨胀算法 + - 高度层识别和合并 + +2. **A* 路径规划**（AutoPathFinder） + - 3D 图构建（多层网格连接） + - A* 搜索算法执行 + - 路径后处理优化 + +3. **碰撞检测**（ClashDetectiveIntegration） + - 动画过程中的实时碰撞检测 + - 多对象间的碰撞测试 + +## 2. Navisworks API GPU 能力调研 + +### 2.1 调研方法 + +- 网络搜索：Navisworks API 官方文档、开发者社区 +- 本地文档：检索 Navisworks 2026 .NET API 文档 +- 关键词：GPU、hardware acceleration、parallel、multi-thread、compute shader + +### 2.2 调研结果 + +#### 2.2.1 Navisworks API 线程模型 + +根据 Autodesk 官方论坛的讨论： + +> "Navisworks C# API is basically, as far as I understand, single-threaded/not thread safe" + +**结论**：Navisworks .NET API 是**单线程的**，不支持多线程并发访问。 + +#### 2.2.2 硬件加速支持情况 + +Navisworks 支持通过用户界面启用硬件加速： + +- **位置**：Interface > Display > Hardware Acceleration +- **用途**：仅用于图形渲染加速 +- **限制**：不是 API 层面的计算加速，插件无法直接调用 + +#### 2.2.3 GPU 系统要求 + +Navisworks 2026 的 GPU 要求： + +- **基本要求**：2 GB GPU，29 GB/s 带宽，DirectX 11 兼容 +- **推荐配置**：8 GB GPU，106 GB/s 带宽，DirectX 12 兼容 + +#### 2.2.4 API 文档搜索结果 + +在本地 Navisworks API 文档中搜索以下关键词： + +```bash +GPU|hardware.*acceleration|parallel|multi.*thread|compute.*shader +``` + +**结果**：未找到任何相关 API 文档。 + +### 2.3 结论 + +**Navisworks API 本身不提供 GPU 加速接口**。所有 GPU 相关的功能仅限于内部渲染引擎，不对插件开发者开放。 + +## 3. 第三方 .NET GPU 计算库 + +### 3.1 可用方案概览 + +虽然 Navisworks API 不提供 GPU 接口，但可以通过集成第三方 .NET GPU 计算库来实现 GPU 加速。 + +### 3.2 ILGPU（推荐） + +#### 基本信息 + +- **官网**：https://ilgpu.net/ +- **许可证**：MIT License +- **支持平台**：.NET Framework 4.8, .NET Core, .NET 5+ + +#### 主要特点 + +1. **多厂商支持** + - NVIDIA CUDA + - AMD ROCm + - Intel 集成显卡 + - CPU 回退模式（无 GPU 时自动使用 CPU） + +2. **C# 原生编程** + ```csharp + // 示例：GPU 并行计算 + var accelerator = new CudaAccelerator(new CudaAcceleratorId(0)); + var kernel = accelerator.LoadAutoGroupedStreamKernel>(MyKernel); + + static void MyKernel(Index1 index, ArrayView data) + { + data[index] = index * 2; // GPU 上执行 + } + ``` + +3. **高层抽象** + - 无需编写 CUDA C++ 代码 + - 自动内存管理 + - 类型安全 + +4. **性能** + - 接近手写 CUDA 的性能（90-95%） + - 支持 Shared Memory、Atomic 操作 + - 内置性能分析工具 + +#### 适用场景 + +- ✅ 大规模并行计算（数组操作、矩阵运算） +- ✅ 需要跨 GPU 厂商支持的项目 +- ✅ 希望纯 C# 开发的团队 + +### 3.3 ManagedCUDA + +#### 基本信息 + +- **GitHub**：https://github.com/kunzmi/managedCuda +- **许可证**：LGPL / 商业许可 +- **支持平台**：.NET Framework, .NET Core + +#### 主要特点 + +1. **CUDA 工具包的 .NET 包装器** + - 直接映射 CUDA C API + - 完整的 CUDA 功能访问 + - 需要安装 NVIDIA CUDA Toolkit + +2. **性能** + - 接近原生 CUDA 性能（98-100%） + - 直接控制内存分配和传输 + - 支持 CUDA Streams、Events + +3. **限制** + - **仅支持 NVIDIA GPU** + - 学习曲线较陡（需要理解 CUDA 编程模型） + - 需要手动管理内存和资源 + +#### 适用场景 + +- ✅ 仅面向 NVIDIA GPU 用户 +- ✅ 需要最大化 GPU 性能 +- ✅ 团队有 CUDA 编程经验 + +### 3.4 DirectCompute + +#### 基本信息 + +- **提供商**：Microsoft +- **API**：DirectX 11/12 Compute Shader +- **支持平台**：Windows + +#### 主要特点 + +1. **跨厂商支持** + - 所有支持 DirectX 11+ 的 GPU + - 与图形管线集成 + +2. **限制** + - .NET 集成复杂（需要 P/Invoke 或 SharpDX） + - 需要编写 HLSL Compute Shader + - 文档和社区支持相对较少 + +#### 适用场景 + +- ⚠️ 需要与 DirectX 图形深度集成 +- ⚠️ 不推荐作为首选方案（开发复杂度高） + +### 3.5 方案对比 + +| 特性 | ILGPU | ManagedCUDA | DirectCompute | +|------|-------|-------------|---------------| +| **GPU 支持** | NVIDIA + AMD + Intel | 仅 NVIDIA | 所有 DX11+ GPU | +| **开发语言** | 纯 C# | C# + CUDA C | C# + HLSL | +| **学习曲线** | 低-中 | 中-高 | 高 | +| **性能** | 90-95% | 98-100% | 85-95% | +| **社区支持** | 活跃 | 中等 | 较少 | +| **推荐度** | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐ | ⭐⭐ | + +**推荐**：对于 NavisworksTransport 项目，**ILGPU 是最佳选择**，原因： + +1. 跨厂商支持（用户可能使用 AMD 或 Intel GPU） +2. 纯 C# 开发，与现有代码库一致 +3. 降低技术门槛，易于团队掌握 +4. CPU 回退模式，无 GPU 时仍可运行 + +## 4. 应用场景分析 + +### 4.1 方案 A：A* 路径规划 GPU 加速 + +#### 4.1.1 数据流设计 + +``` +┌─────────────────────┐ +│ Navisworks API │ +│ 提取 BIM 模型数据 │ +└──────────┬──────────┘ + │ + ▼ +┌─────────────────────┐ +│ GridMapGenerator │ +│ 生成网格地图 (CPU) │ +└──────────┬──────────┘ + │ + ▼ +┌─────────────────────┐ +│ 数据传输到 GPU │ +│ - 网格数据 │ +│ - 障碍物信息 │ +│ - 起终点列表 │ +└──────────┬──────────┘ + │ + ▼ +┌─────────────────────┐ +│ GPU Kernel │ +│ 并行 A* 搜索 │ +│ - 多起终点同时计算 │ +│ - 共享网格数据 │ +└──────────┬──────────┘ + │ + ▼ +┌─────────────────────┐ +│ 结果传回 CPU │ +│ - 路径点列表 │ +│ - 路径成本 │ +└──────────┬──────────┘ + │ + ▼ +┌─────────────────────┐ +│ PathOptimizer │ +│ 路径后处理 (CPU) │ +└─────────────────────┘ +``` + +#### 4.1.2 关键技术点 + +1. **网格数据结构 GPU 化** + ```csharp + // CPU 端（当前） + public class GridCell + { + public List HeightLayers { get; set; } + public bool IsInChannel { get; set; } + // ... + } + + // GPU 端（需要转换为平面数组） + struct GPUGridCell + { + public int LayerCount; + public int LayerStartIndex; // 指向 HeightLayer 数组的索引 + public bool IsInChannel; + } + + struct GPUHeightLayer + { + public float Z; + public float MinPassableZ; + public float MaxPassableZ; + public bool IsWalkable; + public float SpeedLimit; + } + ``` + +2. **并行 A* 算法实现** + - 每个 GPU 线程处理一个起终点对 + - 使用 GPU Shared Memory 存储 Open/Close 集合 + - 需要处理原子操作（更新最优路径） + +3. **数据传输优化** + - 使用 Pinned Memory 减少传输延迟 + - 批量处理多个路径请求 + - 缓存不变的网格数据 + +#### 4.1.3 适用场景判断 + +**适合 GPU 加速的情况**： + +- ✅ 网格规模 > 100m × 100m（> 40,000 单元格） +- ✅ 同时计算 10+ 条路径 +- ✅ 实时路径重规划（动态障碍物） +- ✅ 多楼层复杂场景（3D 图节点数 > 100,000） + +**不适合 GPU 加速的情况**： + +- ❌ 小规模网格 < 50m × 50m（< 10,000 单元格） +- ❌ 单次路径计算 +- ❌ 简单平面场景（2D A*） +- ❌ 数据传输时间 > 计算时间 + +#### 4.1.4 性能预估 + +假设场景：100m × 100m 网格，0.5m 单元格，3 层楼 + +| 指标 | CPU (RoyT.AStar) | GPU (ILGPU 估算) | 加速比 | +|------|------------------|------------------|--------| +| 单次路径 | 50-100 ms | 80-120 ms | **0.6-0.8×** ❌ | +| 10 条路径 | 500-1000 ms | 100-150 ms | **5-8×** ✅ | +| 100 条路径 | 5-10 秒 | 300-500 ms | **15-25×** ✅ | + +**结论**：仅在批量路径计算时才有显著收益。 + +### 4.2 方案 B：碰撞检测 GPU 加速 + +#### 4.2.1 数据流设计 + +``` +┌─────────────────────┐ +│ Navisworks API │ +│ 提取模型几何 │ +└──────────┬──────────┘ + │ + ▼ +┌─────────────────────┐ +│ GeometryExtractor │ +│ 获取 BoundingBox │ +└──────────┬──────────┘ + │ + ▼ +┌─────────────────────┐ +│ 数据传输到 GPU │ +│ - 对象包围盒 │ +│ - 对象位置/旋转 │ +│ - 碰撞检测对列表 │ +└──────────┬──────────┘ + │ + ▼ +┌─────────────────────┐ +│ GPU Kernel │ +│ 并行碰撞检测 │ +│ - AABB 相交测试 │ +│ - OBB 相交测试 │ +└──────────┬──────────┘ + │ + ▼ +┌─────────────────────┐ +│ 结果传回 CPU │ +│ - 碰撞对列表 │ +│ - 碰撞时间戳 │ +└─────────────────────┘ +``` + +#### 4.2.2 关键技术点 + +1. **包围盒数据结构** + ```csharp + struct GPUAABB + { + public Vector3 Min; + public Vector3 Max; + } + + struct GPUCollisionPair + { + public int ObjectA; + public int ObjectB; + public bool IsColliding; + public float PenetrationDepth; + } + ``` + +2. **并行碰撞检测算法** + - 每个 GPU 线程处理一对对象 + - N 个对象 = N×(N-1)/2 个线程 + - 使用空间分区（Grid-based）减少检测对数 + +3. **动画过程集成** + - 每帧更新对象位置到 GPU + - 实时返回碰撞结果 + - 与 Navisworks TimeLiner 同步 + +#### 4.2.3 适用场景判断 + +**适合 GPU 加速的情况**： + +- ✅ 对象数量 > 100 +- ✅ 实时动画碰撞检测（30+ FPS） +- ✅ 动态场景（频繁更新位置） +- ✅ 全对全检测（N² 复杂度） + +**不适合 GPU 加速的情况**： + +- ❌ 对象数量 < 50 +- ❌ 静态场景（预计算即可） +- ❌ 已有空间索引优化（如八叉树） + +#### 4.2.4 性能预估 + +假设场景：200 个动态物体 + +| 指标 | CPU (Navisworks API) | GPU (ILGPU 估算) | 加速比 | +|------|----------------------|------------------|--------| +| 单帧碰撞检测 | 50-100 ms | 5-10 ms | **8-15×** ✅ | +| 30 FPS 动画 | 无法实时 | 实时 | **显著改善** ✅ | + +**结论**：碰撞检测是最适合 GPU 加速的场景。 + +## 5. 实施评估 + +### 5.1 工作量估算 + +| 任务 | 工作量 | 复杂度 | 依赖 | +|------|--------|--------|------| +| ILGPU 库集成与环境搭建 | 1-2 天 | 低 | - | +| 网格数据结构 GPU 化 | 2-3 天 | 中 | GridMapGenerator | +| GPU A* 内核实现 | 5-7 天 | 高 | 并行算法设计 | +| GPU 碰撞检测内核实现 | 3-5 天 | 中-高 | GeometryExtractor | +| CPU-GPU 数据传输优化 | 2-3 天 | 中 | 内存管理 | +| 性能测试与调优 | 3-5 天 | 中 | 测试场景 | +| 错误处理与回退机制 | 2-3 天 | 中 | 异常处理 | +| **总计** | **18-28 天** | **高** | - | + +### 5.2 技术风险 + +1. **GPU 内存限制** + - 风险：大规模网格数据可能超出 GPU 显存 + - 缓解：分块处理、数据压缩 + +2. **用户硬件支持** + - 风险：部分用户无独立 GPU + - 缓解：ILGPU CPU 回退模式 + +3. **数据传输开销** + - 风险：频繁传输抵消 GPU 加速收益 + - 缓解：数据缓存、批量处理 + +4. **Navisworks API 线程安全** + - 风险：GPU 计算结果需要回 UI 线程 + - 缓解：使用 Dispatcher.Invoke + +### 5.3 维护成本 + +- **代码复杂度增加**：需要维护 CPU 和 GPU 两套代码路径 +- **测试覆盖**：需要覆盖不同 GPU 厂商和型号 +- **用户支持**：增加 GPU 驱动相关的技术支持成本 + +## 6. 优化建议与优先级 + +### 6.1 当前项目性能分析 + +基于现有代码分析： + +- **网格生成**：50-200 ms（取决于模型规模） +- **A* 搜索**：20-100 ms（单次路径） +- **路径优化**：10-30 ms +- **总耗时**：80-330 ms + +**主要瓶颈**：网格生成（BIM 几何扫描），而非 A* 搜索。 + +### 6.2 优化优先级排序 + +#### 🔥 第一优先级：CPU 层面优化（高投入产出比） + +**1. 网格生成优化** + +```csharp +// 当前实现：逐个网格扫描 +for (int x = 0; x < gridMap.Width; x++) +{ + for (int y = 0; y < gridMap.Height; y++) + { + // 扫描所有模型元素 + foreach (var item in allItems) + { + if (Intersects(x, y, item)) { ... } + } + } +} + +// 优化方案：空间索引（八叉树/R-树） +var spatialIndex = BuildRTree(allItems); // 预处理一次 +for (int x = 0; x < gridMap.Width; x++) +{ + for (int y = 0; y < gridMap.Height; y++) + { + var nearbyItems = spatialIndex.Query(gridCell); // O(log n) + // 仅检查附近元素 + } +} +``` + +**预期收益**：网格生成速度提升 **5-10×** + +**工作量**：3-5 天 + +--- + +**2. A* 启发式函数优化** + +```csharp +// 当前：简单欧几里得距离 +public float Heuristic(Position a, Position b) +{ + return Vector3.Distance(a, b); +} + +// 优化：考虑高度变化成本 +public float Heuristic(Position a, Position b) +{ + float horizontalDist = Vector2.Distance(a.XY, b.XY); + float verticalDist = Math.Abs(a.Z - b.Z); + // 垂直移动成本更高（楼梯/电梯） + return horizontalDist + verticalDist * 2.0f; +} +``` + +**预期收益**：搜索节点数减少 **20-40%** + +**工作量**：1-2 天 + +--- + +**3. 路径缓存机制** + +```csharp +// 缓存常用路径 +public class PathCache +{ + private Dictionary<(Point3D, Point3D), List> cache; + + public List GetPath(Point3D start, Point3D end) + { + var key = (start, end); + if (cache.ContainsKey(key)) + { + return cache[key]; // 命中缓存 + } + + var path = ComputePath(start, end); + cache[key] = path; + return path; + } +} +``` + +**预期收益**：重复路径计算速度提升 **100×** + +**工作量**：2-3 天 + +--- + +**4. CPU 多线程优化** + +```csharp +// 网格生成并行化 +Parallel.For(0, gridMap.Height, y => +{ + for (int x = 0; x < gridMap.Width; x++) + { + ProcessGridCell(x, y); + } +}); + +// 多路径并行计算 +var paths = Parallel.ForEach(pathRequests, request => +{ + return ComputePath(request.Start, request.End); +}); +``` + +**预期收益**：网格生成和多路径计算速度提升 **2-4×**（取决于 CPU 核心数） + +**工作量**：3-5 天 + +**注意**：需要处理 Navisworks API 线程安全问题（数据提取在主线程，计算在工作线程） + +--- + +#### ⚠️ 第二优先级：数据结构与缓存优化（中投入产出比） + +**1. 网格数据结构优化** + +```csharp +// 当前：List（动态分配） +public class GridCell +{ + public List HeightLayers { get; set; } // 堆分配 +} + +// 优化：固定大小数组或栈分配 +public struct GridCell +{ + public const int MaxLayers = 8; + public HeightLayer Layer0, Layer1, ..., Layer7; // 栈分配 + public int LayerCount; +} +``` + +**预期收益**：内存分配减少 **50-80%**，GC 压力降低 + +**工作量**：5-7 天（涉及大量代码修改） + +--- + +**2. 增量式网格更新** + +```csharp +// 当前：每次全量重建网格 +public void UpdateGrid() +{ + gridMap = new GridMap(); // 全量重建 + GenerateFromBIM(...); +} + +// 优化：仅更新变化区域 +public void UpdateGrid(IEnumerable changedItems) +{ + foreach (var item in changedItems) + { + var affectedCells = GetAffectedCells(item); + foreach (var cell in affectedCells) + { + RegenerateCell(cell); // 局部更新 + } + } +} +``` + +**预期收益**：动态场景更新速度提升 **10-50×** + +**工作量**：4-6 天 + +--- + +#### 🚀 第三优先级：GPU 加速（高投入，场景受限） + +**实施条件**（必须同时满足）： + +1. ✅ 已完成 CPU 层面所有优化 +2. ✅ CPU 优化后仍存在性能瓶颈 +3. ✅ 存在批量计算需求（多路径/多碰撞） +4. ✅ 目标用户群体有独立 GPU +5. ✅ 团队有足够的开发和维护资源 + +**推荐实施顺序**： + +1. **先实施**：碰撞检测 GPU 加速（收益最明显） +2. **后实施**：A* 路径规划 GPU 加速（仅在批量场景） + +**工作量**：18-28 天 + +--- + +### 6.3 综合建议 + +#### 短期（1-2 周） + +1. ✅ 实施空间索引优化（R-树/八叉树） +2. ✅ 实施路径缓存机制 +3. ✅ 优化 A* 启发式函数 + +**预期效果**：整体性能提升 **3-5×**，工作量 **6-10 天** + +#### 中期（1-2 月） + +1. ✅ CPU 多线程优化（网格生成、多路径计算） +2. ✅ 数据结构优化（减少堆分配） +3. ✅ 增量式网格更新 + +**预期效果**：再提升 **2-3×**，工作量 **12-18 天** + +#### 长期（3-6 月） + +1. ⚠️ **评估是否需要 GPU 加速** + - 如果 CPU 优化后仍不满足需求 → 实施碰撞检测 GPU 加速 + - 如果存在大批量路径计算需求 → 实施 A* GPU 加速 + +2. ⚠️ **GPU 加速实施** + - 优先：碰撞检测（工作量 8-12 天） + - 次要：A* 路径规划（工作量 10-16 天） + +**预期效果**：特定场景下再提升 **5-15×**，工作量 **18-28 天** + +--- + +### 6.4 投入产出比对比 + +| 优化方向 | 工作量 | 复杂度 | 性能提升 | 通用性 | 投入产出比 | +|---------|--------|--------|---------|--------|------------| +| 空间索引 | 3-5 天 | 中 | 5-10× | 高 | ⭐⭐⭐⭐⭐ | +| 路径缓存 | 2-3 天 | 低 | 100× (重复路径) | 高 | ⭐⭐⭐⭐⭐ | +| 启发式优化 | 1-2 天 | 低 | 1.2-1.5× | 高 | ⭐⭐⭐⭐ | +| CPU 多线程 | 3-5 天 | 中-高 | 2-4× | 中 | ⭐⭐⭐⭐ | +| 数据结构优化 | 5-7 天 | 高 | 1.2-1.5× | 高 | ⭐⭐⭐ | +| 增量更新 | 4-6 天 | 高 | 10-50× (动态场景) | 中 | ⭐⭐⭐ | +| GPU 碰撞检测 | 8-12 天 | 高 | 8-15× | 低 | ⭐⭐ | +| GPU A* | 10-16 天 | 极高 | 5-25× (批量) | 极低 | ⭐ | + +--- + +## 7. 技术选型建议 + +### 7.1 如果决定实施 GPU 加速 + +**推荐技术栈**： + +- **GPU 计算库**：ILGPU（跨厂商支持，纯 C# 开发） +- **首选场景**：碰撞检测（收益最明显） +- **次选场景**：A* 路径规划（仅在批量计算时） + +**架构设计**： + +``` +┌─────────────────────────────────────────┐ +│ NavisworksTransport 插件 │ +├─────────────────────────────────────────┤ +│ ┌─────────────┐ ┌─────────────┐ │ +│ │ CPU Path │ │ GPU Path │ │ +│ │ (默认) │ ←→ │ (可选) │ │ +│ └─────────────┘ └─────────────┘ │ +│ ↑ ↑ │ +│ └───────┬───────────┘ │ +│ ↓ │ +│ ┌─────────────┐ │ +│ │ Accelerator │ │ +│ │ Selector │ │ +│ └─────────────┘ │ +│ ↓ │ +│ 检测 GPU 可用性 │ +│ - 有 GPU → GPU Path │ +│ - 无 GPU → CPU Path (回退) │ +└─────────────────────────────────────────┘ +``` + +**配置选项**（添加到 `config.toml`）： + +```toml +[performance] +# 性能优化选项 +enable_gpu_acceleration = true # 是否启用 GPU 加速 +gpu_fallback_to_cpu = true # GPU 不可用时回退到 CPU +spatial_index_type = "rtree" # 空间索引类型：rtree, octree, none +enable_path_cache = true # 是否启用路径缓存 +max_cached_paths = 1000 # 最大缓存路径数 +``` + +--- + +### 7.2 如果不实施 GPU 加速 + +**推荐优化路线**（按优先级）： + +1. ✅ **第一阶段**（1 周）：空间索引 + 路径缓存 + 启发式优化 +2. ✅ **第二阶段**（2 周）：CPU 多线程优化 +3. ✅ **第三阶段**（2-3 周）：数据结构优化 + 增量更新 + +**预期效果**：整体性能提升 **5-15×**，无需 GPU 硬件要求。 + +--- + +## 8. 参考资料 + +### 8.1 技术文档 + +- [ILGPU 官方文档](https://ilgpu.net/) +- [ManagedCUDA GitHub](https://github.com/kunzmi/managedCuda) +- [Navisworks .NET API 开发者指南](doc/navisworks_api/NET/documentation/) + +### 8.2 研究来源 + +- Autodesk Navisworks 开发者社区 +- Navisworks API 2026 本地文档 +- NVIDIA CUDA 编程指南 +- Microsoft DirectCompute 文档 + +### 8.3 相关设计文档 + +- [A* 寻路优化方案](C# A_ 寻路优化_.md) +- [自动路径规划设计方案](PATHFINDING_DESIGN.md) +- [A* 库的使用方法](AStar库的使用方法.md) + +--- + +## 9. 结论 + +### 9.1 核心发现 + +1. **Navisworks API 不提供 GPU 加速接口**，但可通过第三方库实现。 +2. **当前项目的主要瓶颈在网格生成，而非 A* 搜索**。 +3. **CPU 层面优化的投入产出比远高于 GPU 加速**。 +4. **GPU 加速仅在特定场景（批量计算、大规模数据）下有显著收益**。 + +### 9.2 最终建议 + +**不建议立即实施 GPU 加速**，理由： + +1. ✅ CPU 层面有大量优化空间未开发 +2. ✅ 投入产出比更高的优化方案可优先实施 +3. ✅ GPU 加速适用场景有限（批量计算） +4. ✅ 增加维护成本和技术复杂度 + +**建议优化路线**： + +``` +短期 (1-2周) → 空间索引 + 路径缓存 + 启发式优化 + ↓ (性能提升 3-5×) +中期 (1-2月) → CPU 多线程 + 数据结构优化 + ↓ (再提升 2-3×) +长期 (3-6月) → 评估是否需要 GPU 加速 + ↓ (如需要) + → 优先碰撞检测 GPU 加速 + → 次要 A* GPU 加速 +``` + +### 9.3 重新评估触发条件 + +建议在以下情况下重新评估 GPU 加速方案： + +1. ✅ CPU 层面所有优化已完成 +2. ✅ 性能仍不满足需求（如单次路径计算 > 500ms） +3. ✅ 出现批量路径计算需求（10+ 条同时计算） +4. ✅ 用户群体确认有独立 GPU 硬件 +5. ✅ 团队有足够资源进行开发和维护 + +--- + +**文档版本**：v1.0 +**创建日期**：2025-10-12 +**最后更新**：2025-10-12 +**作者**：NavisworksTransport 开发团队 diff --git a/doc/design/2026/体素网格路径规划方案.md b/doc/design/2026/体素网格路径规划方案.md new file mode 100644 index 0000000..f817093 --- /dev/null +++ b/doc/design/2026/体素网格路径规划方案.md @@ -0,0 +1,1440 @@ +# 体素网格 3D 路径规划方案 + +## 1. 背景与动机 + +### 1.1 当前方案的局限性 + +当前 NavisworksTransport 插件采用 **2.5D 网格 + 高度层** 的路径规划方案： + +**数据结构**： + +```csharp +public class GridCell +{ + public List HeightLayers { get; set; } // 多个高度层 + // (X, Y) 网格坐标 + 离散的 Z 高度层 +} +``` + +**局限性**： + +1. **高度层离散化** + - 只能表示有限数量的通行高度 + - 相邻高度层之间的连接需要特殊处理 + - 难以精确表示连续变化的高度 + +2. **复杂空间的表达受限** + - 管道、桥梁下方的多层通道难以准确建模 + - 斜坡、楼梯的连续高度变化需要大量高度层 + - 悬空结构（如天桥）的下方空间处理复杂 + +3. **路径规划的限制** + - 垂直方向的移动需要显式的"层间连接" + - 真正的 3D 路径（如无人机、爬楼机器人）无法支持 + - 算法复杂度高（需要处理层间跳转逻辑） + +4. **可扩展性问题** + - 增加高度层数会显著增加内存消耗 + - 多层网格的生成和维护成本高 + - 难以支持动态障碍物的实时更新 + +### 1.2 体素网格的优势 + +采用 **真正的 3D 体素网格**（Voxel Grid）可以解决上述问题： + +**统一的 3D 表示**： + +```csharp +public class VoxelGrid +{ + private VoxelCell[,,] cells; // 统一的 3D 数组 (X, Y, Z) +} +``` + +**优势**： + +1. ✅ **连续的 3D 空间**：任意高度都可以表示 +2. ✅ **简化的路径算法**：标准 3D A* 算法，无需特殊层间逻辑 +3. ✅ **精确的障碍物表示**：管道、横梁等任意 3D 形状 +4. ✅ **更好的可视化**：直观的 3D 体素显示 +5. ✅ **支持真 3D 路径**：无人机、飞行器、爬楼设备 + +--- + +## 2. 技术调研：C# 体素网格库 + +### 2.1 候选库对比 + +经过深入的 GitHub 和 NuGet 调研，找到以下候选库： + +| 库名 | Stars | 许可证 | 平台 | 活跃度 | 适用性 | +|------|-------|--------|------|--------|--------| +| **geometry4Sharp** | 273 | Boost | .NET Std 2.0 | 中等 | ⭐⭐⭐⭐⭐ | +| geometry3Sharp (原版) | 1400+ | Boost | .NET Std 2.0 | 低 | ⭐⭐⭐⭐ | +| Unity PathFinding3D | ~100 | MIT | Unity | 高 | ⭐⭐ (Unity 依赖) | +| UnityOctree | ~900 | MIT | Unity | 中 | ⭐⭐ (Unity 依赖) | +| 自行实现 | N/A | N/A | 任意 | N/A | ⭐⭐⭐ (工作量大) | + +### 2.2 推荐方案：geometry4Sharp + +**GitHub**: + +**NuGet**: `geometry4Sharp` 1.0.0 + +#### 基本信息 + +- **许可证**: Boost Software License（商业友好，无需开源衍生作品） +- **维护者**: New Wheel Technology +- **代码来源**: Fork from geometry3Sharp，底层算法来自 WildMagic5/GTEngine (David Eberly) +- **支持平台**: .NET Standard 2.0, .NET 6.0, .NET Framework 4.8 +- **语言**: 纯 C#，无 C++ 互操作 + +#### 核心功能模块 + +**1. 体素化与距离场** + +```csharp +// 核心类 +MeshSignedDistanceGrid // 网格签名距离场 +MeshScalarSamplingGrid // 标量采样网格 +Bitmap3 // 3D 位图（密集体素） +DSparseGrid3 // 稀疏 3D 网格（按需分配） +BiGrid3 // 两层稀疏网格（优化大规模场景） +``` + +**功能说明**： + +- **MeshSignedDistanceGrid**: + - 从三角网格生成签名距离场 (SDF) + - 使用快速行进法 (Fast Marching Method) + - 支持窄带构建（仅计算障碍物附近区域，节省内存） + - 基于 Christopher Batty 的 SDFGen C++ 代码移植 + +- **Bitmap3**: + - 密集 3D 布尔数组 + - 高效的内存布局 + - 适合小到中等规模网格（< 1000³） + +- **DSparseGrid3**: + - 稀疏 3D 网格，按需分配内存 + - 适合大规模场景（仅存储非空体素） + - 基于字典或哈希表实现 + +**2. 空间查询与距离计算** + +```csharp +// 距离查询 +bool IsInside(Point3d point) // 点包含测试 +double WindingNumber(Point3d point) // 绕组数（判断内外） +double FastWindingNumber(Point3d point) // 快速绕组数 +double Distance(Point3d point) // 到最近表面的距离 + +// 空间索引 +DMeshAABBTree3 // 三角网格 AABB 树（加速相交测试） +PointHashGrid3d // 3D 点哈希网格 +PointAABBTree3 // 点云 AABB 树 +``` + +**3. 网格操作与处理** + +```csharp +// 等值面提取 +MarchingCubes // 从体素生成三角网格 +MarchingCubesPro // 延续法行进立方体（更高效） + +// 网格简化与重新网格化 +Remesher // 边分裂/翻转/坍缩网格 +Reducer // 基于 QEM 的网格简化 + +// 几何计算 +DMesh3 // 动态三角网格类 +BoundsUtil // 包围盒计算 +MeshMeasurements // 体积、质心、惯性张量 +``` + +**4. 数学与几何工具** + +```csharp +// 向量数学（完整的 struct 实现） +Vector2d/3d/4d, Vector2f/3f/4f +Matrix2d/3d, Matrix2f/3f +Quaterniond/f +Frame3f // 位置+方向表示 + +// 几何形状 +AxisAlignedBox3d/3f // 轴对齐包围盒 +Box3d/3f // 有向包围盒 +Triangle3d/3f, Segment3d/3f, Ray3d/3f, Plane3d/3f + +// 距离与相交查询 +DistPoint3Triangle3, DistLine3Triangle3 +IntrRay3Triangle3, IntrTriangle3Triangle3 +``` + +#### 为什么选择 geometry4Sharp？ + +✅ **功能完整**： + +- 提供完整的网格→体素→距离场工具链 +- 丰富的空间查询和距离计算 +- 优化的空间数据结构（AABB 树、哈希网格） + +✅ **代码质量高**： + +- 源自 David Eberly 的 WildMagic5/GTEngine（几何计算领域的经典库） +- 经过多年实战验证 +- 纯 C# 实现，类型安全 + +✅ **商业友好**： + +- Boost License 允许商业使用 +- 无需开源衍生代码 +- 无专利限制 + +✅ **平台兼容**： + +- 支持 .NET Framework 4.8（Navisworks 2026 要求） +- 无 Unity 依赖，纯 .NET 库 +- 可与 Navisworks API 无缝集成 + +✅ **性能优化**： + +- 多线程支持（Marching Cubes 等） +- 内存高效（稀疏网格、窄带 SDF） +- 空间索引加速查询 + +⚠️ **不足之处**： + +- 不包含路径规划算法（需结合 Roy-T.AStar） +- 文档以 README 为主，缺少专门的 API 文档网站 +- 活跃度中等（原项目 2019 年后维护减少） + +#### 与 Roy-T.AStar 的集成策略 + +geometry4Sharp 提供**空间表示**，Roy-T.AStar 提供**路径算法**： + +``` +┌────────────────────────────────────────┐ +│ Navisworks BIM 模型 │ +│ (三角网格、包围盒) │ +└──────────────┬─────────────────────────┘ + │ + ▼ +┌────────────────────────────────────────┐ +│ geometry4Sharp │ +│ - MeshSignedDistanceGrid (体素化) │ +│ - Distance Field (距离计算) │ +│ - IsInside (可通行性判断) │ +└──────────────┬─────────────────────────┘ + │ + ▼ +┌────────────────────────────────────────┐ +│ VoxelGrid 适配层 │ +│ - 转换为 Roy-T.AStar Grid │ +│ - 或构建自定义 3D Graph │ +└──────────────┬─────────────────────────┘ + │ + ▼ +┌────────────────────────────────────────┐ +│ Roy-T.AStar │ +│ - A* 路径规划算法 │ +│ - PathFinder.FindPath() │ +└──────────────┬─────────────────────────┘ + │ + ▼ +┌────────────────────────────────────────┐ +│ PathOptimizer │ +│ - 路径平滑、简化 │ +└────────────────────────────────────────┘ +``` + +--- + +## 3. 架构设计 + +### 3.1 整体架构 + +``` +┌──────────────────────────────────────────────────────────┐ +│ Navisworks API │ +│ (ModelItem, BoundingBox, Geometry) │ +└────────────────────────┬─────────────────────────────────┘ + │ + ▼ +┌──────────────────────────────────────────────────────────┐ +│ NavisworksGeometryExtractor │ +│ - ExtractTriangleMesh(): DMesh3 │ +│ - ExtractBoundingBoxes(): List │ +└────────────────────────┬─────────────────────────────────┘ + │ + ▼ +┌──────────────────────────────────────────────────────────┐ +│ VoxelGridGenerator (新) │ +│ - GenerateFromBIM() │ +│ ├── MeshSignedDistanceGrid (geometry4Sharp) │ +│ ├── 体素标记 (Obstacle/Free/Door/...) │ +│ └── 生成 VoxelGrid │ +└────────────────────────┬─────────────────────────────────┘ + │ + ▼ +┌──────────────────────────────────────────────────────────┐ +│ VoxelGrid (新) │ +│ - cells: VoxelCell[X, Y, Z] │ +│ - IsPassable(x, y, z): bool │ +│ - GetDistance(x, y, z): double │ +│ - GetNeighbors(x, y, z): List<(int,int,int)> │ +└────────────────────────┬─────────────────────────────────┘ + │ + ▼ +┌──────────────────────────────────────────────────────────┐ +│ VoxelPathFinder (新，替代 AutoPathFinder) │ +│ - BuildGraph3D(): 构建 3D 节点图 │ +│ - FindPath(): 使用 Roy-T.AStar 进行 3D A* 搜索 │ +│ - ConvertToWorldPath(): 体素坐标 → 世界坐标 │ +└────────────────────────┬─────────────────────────────────┘ + │ + ▼ +┌──────────────────────────────────────────────────────────┐ +│ PathOptimizer │ +│ - SimplifyPath() (保留，适配 3D 路径) │ +└────────────────────────┬─────────────────────────────────┘ + │ + ▼ +┌──────────────────────────────────────────────────────────┐ +│ LogisticsAnimationManager │ +│ - AnimatePath() (无需修改) │ +└──────────────────────────────────────────────────────────┘ +``` + +### 3.2 核心类设计 + +#### 3.2.1 VoxelCell - 体素单元 + +```csharp +/// +/// 3D 体素单元，表示空间中的一个立方体区域 +/// +public class VoxelCell +{ + /// + /// 体素类型（障碍物、通道、门、楼梯等） + /// + public LogisticsElementType Type { get; set; } + + /// + /// 是否可通行 + /// + public bool IsPassable { get; set; } + + /// + /// 到最近障碍物表面的距离（来自 SDF） + /// + public double Distance { get; set; } + + /// + /// 速度限制（米/秒），用于门、楼梯等特殊区域 + /// + public double SpeedLimit { get; set; } + + /// + /// 关联的 Navisworks 模型元素（可选） + /// + public ModelItem SourceItem { get; set; } + + /// + /// 通行成本（基于距离、类型、速度限制计算） + /// + public double Cost { get; set; } +} +``` + +#### 3.2.2 VoxelGrid - 3D 体素网格 + +```csharp +/// +/// 3D 体素网格，表示整个路径规划空间 +/// +public class VoxelGrid +{ + #region 字段 + + /// + /// 体素数组 [X, Y, Z] + /// + private VoxelCell[,,] cells; + + /// + /// 世界坐标原点（网格左下后角） + /// + public Point3D Origin { get; private set; } + + /// + /// 体素大小（米） + /// + public double VoxelSize { get; private set; } + + /// + /// 网格尺寸（体素数量） + /// + public int SizeX { get; private set; } + public int SizeY { get; private set; } + public int SizeZ { get; private set; } + + #endregion + + #region 构造函数 + + public VoxelGrid(Point3D origin, double voxelSize, int sizeX, int sizeY, int sizeZ) + { + Origin = origin; + VoxelSize = voxelSize; + SizeX = sizeX; + SizeY = sizeY; + SizeZ = sizeZ; + cells = new VoxelCell[sizeX, sizeY, sizeZ]; + + // 初始化所有体素为空 + for (int x = 0; x < sizeX; x++) + { + for (int y = 0; y < sizeY; y++) + { + for (int z = 0; z < sizeZ; z++) + { + cells[x, y, z] = new VoxelCell + { + IsPassable = true, + Distance = double.MaxValue, + Type = LogisticsElementType.通道 + }; + } + } + } + } + + #endregion + + #region 坐标转换 + + /// + /// 世界坐标 → 体素索引 + /// + public (int x, int y, int z) WorldToVoxel(Point3D worldPos) + { + int x = (int)Math.Floor((worldPos.X - Origin.X) / VoxelSize); + int y = (int)Math.Floor((worldPos.Y - Origin.Y) / VoxelSize); + int z = (int)Math.Floor((worldPos.Z - Origin.Z) / VoxelSize); + return (x, y, z); + } + + /// + /// 体素索引 → 世界坐标（体素中心） + /// + public Point3D VoxelToWorld(int x, int y, int z) + { + double worldX = Origin.X + (x + 0.5) * VoxelSize; + double worldY = Origin.Y + (y + 0.5) * VoxelSize; + double worldZ = Origin.Z + (z + 0.5) * VoxelSize; + return new Point3D(worldX, worldY, worldZ); + } + + #endregion + + #region 体素访问 + + /// + /// 检查索引是否在网格范围内 + /// + public bool IsValidIndex(int x, int y, int z) + { + return x >= 0 && x < SizeX && + y >= 0 && y < SizeY && + z >= 0 && z < SizeZ; + } + + /// + /// 获取体素（安全访问） + /// + public VoxelCell GetVoxel(int x, int y, int z) + { + if (!IsValidIndex(x, y, z)) + return null; + return cells[x, y, z]; + } + + /// + /// 设置体素 + /// + public void SetVoxel(int x, int y, int z, VoxelCell voxel) + { + if (IsValidIndex(x, y, z)) + cells[x, y, z] = voxel; + } + + /// + /// 检查体素是否可通行 + /// + public bool IsPassable(int x, int y, int z) + { + var voxel = GetVoxel(x, y, z); + return voxel != null && voxel.IsPassable; + } + + #endregion + + #region 邻居查询 + + /// + /// 获取 26 邻域体素（6 面 + 12 边 + 8 角） + /// + public List<(int x, int y, int z)> GetNeighbors26(int x, int y, int z) + { + var neighbors = new List<(int, int, int)>(); + + for (int dx = -1; dx <= 1; dx++) + { + for (int dy = -1; dy <= 1; dy++) + { + for (int dz = -1; dz <= 1; dz++) + { + if (dx == 0 && dy == 0 && dz == 0) + continue; // 跳过自己 + + int nx = x + dx; + int ny = y + dy; + int nz = z + dz; + + if (IsValidIndex(nx, ny, nz) && IsPassable(nx, ny, nz)) + { + neighbors.Add((nx, ny, nz)); + } + } + } + } + + return neighbors; + } + + /// + /// 获取 6 邻域体素（仅面相邻） + /// + public List<(int x, int y, int z)> GetNeighbors6(int x, int y, int z) + { + var neighbors = new List<(int, int, int)>(); + var directions = new[] + { + (1, 0, 0), (-1, 0, 0), // X 轴 + (0, 1, 0), (0, -1, 0), // Y 轴 + (0, 0, 1), (0, 0, -1) // Z 轴 + }; + + foreach (var (dx, dy, dz) in directions) + { + int nx = x + dx; + int ny = y + dy; + int nz = z + dz; + + if (IsValidIndex(nx, ny, nz) && IsPassable(nx, ny, nz)) + { + neighbors.Add((nx, ny, nz)); + } + } + + return neighbors; + } + + #endregion + + #region 统计信息 + + /// + /// 统计可通行体素数量 + /// + public int CountPassableVoxels() + { + int count = 0; + for (int x = 0; x < SizeX; x++) + { + for (int y = 0; y < SizeY; y++) + { + for (int z = 0; z < SizeZ; z++) + { + if (cells[x, y, z].IsPassable) + count++; + } + } + } + return count; + } + + #endregion +} +``` + +#### 3.2.3 VoxelGridGenerator - 体素网格生成器 + +```csharp +/// +/// 从 Navisworks BIM 模型生成体素网格 +/// +public class VoxelGridGenerator +{ + #region 配置参数 + + private readonly double voxelSize; // 体素大小（米） + private readonly double vehicleRadius; // 车辆半径（米） + private readonly double vehicleHeight; // 车辆高度（米） + private readonly double safetyMargin; // 安全间隙（米） + + #endregion + + #region 构造函数 + + public VoxelGridGenerator( + double voxelSizeMeters, + double vehicleRadiusMeters, + double vehicleHeightMeters, + double safetyMarginMeters) + { + this.voxelSize = voxelSizeMeters; + this.vehicleRadius = vehicleRadiusMeters; + this.vehicleHeight = vehicleHeightMeters; + this.safetyMargin = safetyMarginMeters; + } + + #endregion + + #region 主生成方法 + + /// + /// 从 BIM 模型生成体素网格 + /// + public VoxelGrid GenerateFromBIM( + BoundingBox3D worldBounds, + IEnumerable obstacles, + IEnumerable channels, + IEnumerable doors) + { + LogManager.Info("[体素网格生成] 开始生成..."); + var sw = Stopwatch.StartNew(); + + // 1. 创建空网格 + VoxelGrid grid = CreateEmptyGrid(worldBounds); + LogManager.Info($"[体素网格生成] 网格尺寸: {grid.SizeX} × {grid.SizeY} × {grid.SizeZ}"); + + // 2. 使用 geometry4Sharp 生成距离场 + MeshSignedDistanceGrid sdf = GenerateDistanceField(obstacles); + LogManager.Info($"[体素网格生成] 距离场计算完成"); + + // 3. 标记体素类型 + MarkVoxels(grid, sdf); + LogManager.Info($"[体素网格生成] 体素标记完成"); + + // 4. 处理特殊元素（门、通道等） + ProcessSpecialElements(grid, doors, channels); + + sw.Stop(); + LogManager.Info($"[体素网格生成] 完成，耗时: {sw.ElapsedMilliseconds}ms"); + LogManager.Info($"[体素网格生成] 可通行体素: {grid.CountPassableVoxels()}"); + + return grid; + } + + #endregion + + #region 辅助方法 + + /// + /// 创建空的体素网格 + /// + private VoxelGrid CreateEmptyGrid(BoundingBox3D bounds) + { + Point3D origin = bounds.Min; + + int sizeX = (int)Math.Ceiling((bounds.Max.X - bounds.Min.X) / voxelSize); + int sizeY = (int)Math.Ceiling((bounds.Max.Y - bounds.Min.Y) / voxelSize); + int sizeZ = (int)Math.Ceiling((bounds.Max.Z - bounds.Min.Z) / voxelSize); + + return new VoxelGrid(origin, voxelSize, sizeX, sizeY, sizeZ); + } + + /// + /// 使用 geometry4Sharp 生成距离场 + /// + private MeshSignedDistanceGrid GenerateDistanceField(IEnumerable obstacles) + { + // 1. 提取障碍物三角网格 + DMesh3 obstacleMesh = ExtractTriangleMesh(obstacles); + + // 2. 计算网格包围盒 + AxisAlignedBox3d meshBounds = obstacleMesh.GetBounds(); + + // 3. 创建距离场网格 + int numCells = (int)Math.Ceiling(meshBounds.MaxDim / voxelSize); + MeshSignedDistanceGrid sdf = new MeshSignedDistanceGrid( + obstacleMesh, + cellSize: voxelSize, + numCells: numCells + ); + + // 4. 计算距离场（可能耗时） + sdf.Compute(); + + return sdf; + } + + /// + /// 从 Navisworks ModelItem 提取三角网格 + /// + private DMesh3 ExtractTriangleMesh(IEnumerable items) + { + DMesh3 mesh = new DMesh3(); + + foreach (var item in items) + { + // 使用 Navisworks API 获取几何体 + // 转换为 geometry4Sharp 的 DMesh3 格式 + // 这部分需要实现 Navisworks Geometry → DMesh3 的转换 + + // 伪代码示例： + // var navisGeometry = item.Geometry; + // foreach (var triangle in navisGeometry.Triangles) + // { + // var v1 = mesh.AppendVertex(triangle.V1); + // var v2 = mesh.AppendVertex(triangle.V2); + // var v3 = mesh.AppendVertex(triangle.V3); + // mesh.AppendTriangle(v1, v2, v3); + // } + } + + return mesh; + } + + /// + /// 根据距离场标记体素 + /// + private void MarkVoxels(VoxelGrid grid, MeshSignedDistanceGrid sdf) + { + double minPassableDistance = vehicleRadius + safetyMargin; + + for (int x = 0; x < grid.SizeX; x++) + { + for (int y = 0; y < grid.SizeY; y++) + { + for (int z = 0; z < grid.SizeZ; z++) + { + // 体素中心的世界坐标 + Point3D worldPos = grid.VoxelToWorld(x, y, z); + + // 查询距离场 + Vector3d point = new Vector3d(worldPos.X, worldPos.Y, worldPos.Z); + double distance = sdf[point]; + + // 判断可通行性 + var voxel = grid.GetVoxel(x, y, z); + voxel.Distance = distance; + voxel.IsPassable = distance >= minPassableDistance; + voxel.Type = voxel.IsPassable + ? LogisticsElementType.通道 + : LogisticsElementType.障碍物; + } + } + } + } + + /// + /// 处理特殊元素（门、楼梯等） + /// + private void ProcessSpecialElements( + VoxelGrid grid, + IEnumerable doors, + IEnumerable channels) + { + // 处理门元素 + foreach (var door in doors) + { + BoundingBox3D doorBBox = door.BoundingBox(); + MarkRegion(grid, doorBBox, LogisticsElementType.门, + speedLimit: 0.5, isPassable: true); + } + + // 处理通道元素 + foreach (var channel in channels) + { + BoundingBox3D channelBBox = channel.BoundingBox(); + MarkRegion(grid, channelBBox, LogisticsElementType.通道, + speedLimit: 1.0, isPassable: true); + } + } + + /// + /// 标记指定区域的体素 + /// + private void MarkRegion( + VoxelGrid grid, + BoundingBox3D bounds, + LogisticsElementType type, + double speedLimit, + bool isPassable) + { + var (minX, minY, minZ) = grid.WorldToVoxel(bounds.Min); + var (maxX, maxY, maxZ) = grid.WorldToVoxel(bounds.Max); + + for (int x = minX; x <= maxX; x++) + { + for (int y = minY; y <= maxY; y++) + { + for (int z = minZ; z <= maxZ; z++) + { + var voxel = grid.GetVoxel(x, y, z); + if (voxel != null) + { + voxel.Type = type; + voxel.IsPassable = isPassable; + voxel.SpeedLimit = speedLimit; + } + } + } + } + } + + #endregion +} +``` + +#### 3.2.4 VoxelPathFinder - 体素路径规划器 + +```csharp +/// +/// 基于体素网格的 3D 路径规划 +/// +public class VoxelPathFinder +{ + private readonly VoxelGrid voxelGrid; + + public VoxelPathFinder(VoxelGrid voxelGrid) + { + this.voxelGrid = voxelGrid; + } + + #region 路径规划 + + /// + /// 查找 3D 路径 + /// + public List FindPath(Point3D start, Point3D end) + { + LogManager.Info($"[体素路径规划] 开始: {start} → {end}"); + var sw = Stopwatch.StartNew(); + + // 1. 世界坐标 → 体素索引 + var startVoxel = voxelGrid.WorldToVoxel(start); + var endVoxel = voxelGrid.WorldToVoxel(end); + + // 2. 检查起终点是否可通行 + if (!voxelGrid.IsPassable(startVoxel.x, startVoxel.y, startVoxel.z)) + { + LogManager.Error($"[体素路径规划] 起点不可通行: {startVoxel}"); + return null; + } + if (!voxelGrid.IsPassable(endVoxel.x, endVoxel.y, endVoxel.z)) + { + LogManager.Error($"[体素路径规划] 终点不可通行: {endVoxel}"); + return null; + } + + // 3. 构建 3D 图（如果使用 Roy-T.AStar 的 Graph 模式） + // 或者直接使用自定义 A* 实现 + + // 方案 A：使用 Roy-T.AStar Grid 模式（需扩展到 3D） + // 方案 B：自定义 3D A* 实现 + var voxelPath = FindPathAStar(startVoxel, endVoxel); + + if (voxelPath == null || voxelPath.Count == 0) + { + LogManager.Error($"[体素路径规划] 未找到路径"); + return null; + } + + // 4. 体素坐标 → 世界坐标 + var worldPath = ConvertToWorldPath(voxelPath); + + sw.Stop(); + LogManager.Info($"[体素路径规划] 完成，耗时: {sw.ElapsedMilliseconds}ms，路径点: {worldPath.Count}"); + + return worldPath; + } + + #endregion + + #region A* 实现 + + /// + /// 3D A* 路径搜索（简化实现） + /// + private List<(int x, int y, int z)> FindPathAStar( + (int x, int y, int z) start, + (int x, int y, int z) goal) + { + // 使用优先队列实现 A* + var openSet = new PriorityQueue<(int, int, int), double>(); + var cameFrom = new Dictionary<(int, int, int), (int, int, int)>(); + var gScore = new Dictionary<(int, int, int), double>(); + var fScore = new Dictionary<(int, int, int), double>(); + + openSet.Enqueue(start, 0); + gScore[start] = 0; + fScore[start] = Heuristic(start, goal); + + while (openSet.Count > 0) + { + var current = openSet.Dequeue(); + + // 找到目标 + if (current.Equals(goal)) + { + return ReconstructPath(cameFrom, current); + } + + // 遍历邻居（26 邻域） + foreach (var neighbor in voxelGrid.GetNeighbors26(current.x, current.y, current.z)) + { + double tentativeGScore = gScore[current] + MoveCost(current, neighbor); + + if (!gScore.ContainsKey(neighbor) || tentativeGScore < gScore[neighbor]) + { + cameFrom[neighbor] = current; + gScore[neighbor] = tentativeGScore; + fScore[neighbor] = gScore[neighbor] + Heuristic(neighbor, goal); + + if (!openSet.Contains(neighbor)) + { + openSet.Enqueue(neighbor, fScore[neighbor]); + } + } + } + } + + return null; // 未找到路径 + } + + /// + /// A* 启发式函数（欧几里得距离） + /// + private double Heuristic((int x, int y, int z) a, (int x, int y, int z) b) + { + int dx = a.x - b.x; + int dy = a.y - b.y; + int dz = a.z - b.z; + return Math.Sqrt(dx * dx + dy * dy + dz * dz) * voxelGrid.VoxelSize; + } + + /// + /// 移动成本（考虑距离、类型、速度限制） + /// + private double MoveCost((int x, int y, int z) from, (int x, int y, int z) to) + { + // 欧几里得距离 + int dx = to.x - from.x; + int dy = to.y - from.y; + int dz = to.z - from.z; + double distance = Math.Sqrt(dx * dx + dy * dy + dz * dz) * voxelGrid.VoxelSize; + + // 考虑目标体素的速度限制 + var voxel = voxelGrid.GetVoxel(to.x, to.y, to.z); + double speedFactor = 1.0; + if (voxel != null && voxel.SpeedLimit > 0) + { + speedFactor = 1.0 / voxel.SpeedLimit; // 速度越慢，成本越高 + } + + return distance * speedFactor; + } + + /// + /// 重建路径 + /// + private List<(int x, int y, int z)> ReconstructPath( + Dictionary<(int, int, int), (int, int, int)> cameFrom, + (int x, int y, int z) current) + { + var path = new List<(int, int, int)> { current }; + + while (cameFrom.ContainsKey(current)) + { + current = cameFrom[current]; + path.Insert(0, current); + } + + return path; + } + + #endregion + + #region 路径转换 + + /// + /// 体素路径 → 世界坐标路径 + /// + private List ConvertToWorldPath(List<(int x, int y, int z)> voxelPath) + { + var worldPath = new List(); + + foreach (var (x, y, z) in voxelPath) + { + Point3D worldPos = voxelGrid.VoxelToWorld(x, y, z); + worldPath.Add(worldPos); + } + + return worldPath; + } + + #endregion +} +``` + +--- + +## 4. 实施计划 + +### 4.1 阶段划分 + +#### 阶段 1：环境搭建与原型验证（3-5 天） + +**任务**： + +1. **安装 geometry4Sharp** + - NuGet 添加 `geometry4Sharp` 1.0.0 + - 验证与 .NET Framework 4.8 兼容性 + - 运行示例代码测试 + +2. **创建简单原型** + - 从 Navisworks 提取简单场景（如单个房间） + - 生成体素网格（使用 `Bitmap3` 或 `DSparseGrid3`） + - 可视化体素网格（在 Navisworks 中显示为小方块） + +3. **距离场测试** + - 提取障碍物网格转为 `DMesh3` + - 使用 `MeshSignedDistanceGrid` 计算 SDF + - 验证距离场的正确性 + +**验收标准**： + +- ✅ geometry4Sharp 成功集成 +- ✅ 能从 Navisworks 模型生成简单体素网格 +- ✅ 能在 Navisworks 3D 视图中可视化体素 + +--- + +#### 阶段 2：核心功能开发（7-10 天） + +**任务**： + +1. **实现 VoxelGrid 类** + - 完整的体素网格数据结构 + - 坐标转换方法 + - 邻居查询（6 邻域、26 邻域） + - 统计和查询方法 + +2. **实现 VoxelGridGenerator** + - Navisworks Geometry → geometry4Sharp DMesh3 转换 + - 距离场计算集成 + - 体素标记逻辑（障碍物、通道、门等） + - 特殊元素处理（门、楼梯） + +3. **实现 VoxelPathFinder** + - 3D A* 算法实现 + - 或集成 Roy-T.AStar 的 Graph 模式 + - 路径坐标转换 + - 成本计算（距离 + 速度限制） + +4. **集成到现有系统** + - 替换 `GridMapGenerator` 为 `VoxelGridGenerator` + - 替换 `AutoPathFinder` 为 `VoxelPathFinder` + - 保持 `PathOptimizer` 不变（适配 3D 路径） + +**验收标准**： + +- ✅ 能从复杂 BIM 模型生成体素网格 +- ✅ 能找到 3D 路径（包括垂直移动） +- ✅ 路径避开障碍物并穿过门/通道 +- ✅ 性能可接受（中等规模场景 < 5 秒） + +--- + +#### 阶段 3：优化与测试（5-7 天） + +**任务**： + +1. **性能优化** + - 使用 `BiGrid3` 稀疏网格减少内存 + - 窄带 SDF（仅计算障碍物附近区域） + - A*算法优化（JPS-3D、Theta* 等） + - 多线程并行化（网格生成、路径规划） + +2. **内存优化** + - 大规模场景的内存占用评估 + - 分块生成和加载 + - 按需计算距离场 + +3. **测试场景** + - 简单场景（单层房间） + - 中等场景（多层建筑） + - 复杂场景（大型工厂、管道密集） + - 边界测试（超大规模、极小体素） + +4. **可视化增强** + - 体素网格的 3D 渲染（彩色方块） + - 路径的 3D 动画展示 + - 距离场的热图可视化 + +**验收标准**： + +- ✅ 大规模场景（> 100m³）可在合理时间内生成（< 30 秒） +- ✅ 内存占用可控（< 2GB） +- ✅ 所有测试场景路径规划成功 +- ✅ 可视化效果直观 + +--- + +#### 阶段 4：文档与集成（2-3 天） + +**任务**： + +1. **代码文档** + - XML 注释完善 + - 关键类和方法的使用说明 + - 示例代码 + +2. **用户文档** + - 体素网格参数配置说明 + - 与 2.5D 方案的对比 + - 性能调优建议 + +3. **配置文件更新** + - 添加体素网格相关配置项 + - 向后兼容 2.5D 模式（可选） + +4. **单元测试** + - VoxelGrid 测试 + - VoxelPathFinder 测试 + - 性能基准测试 + +**验收标准**： + +- ✅ 完整的代码和用户文档 +- ✅ 配置文件支持体素网格参数 +- ✅ 单元测试覆盖率 > 70% + +--- + +### 4.2 时间与资源估算 + +| 阶段 | 任务 | 工作量 | 依赖 | +|------|------|--------|------| +| 阶段 1 | 环境搭建与原型 | 3-5 天 | geometry4Sharp | +| 阶段 2 | 核心功能开发 | 7-10 天 | 阶段 1 | +| 阶段 3 | 优化与测试 | 5-7 天 | 阶段 2 | +| 阶段 4 | 文档与集成 | 2-3 天 | 阶段 3 | +| **总计** | | **17-25 天** | | + +**资源需求**： + +- 1 名全职开发人员 +- Navisworks 2026 开发环境 +- 测试 BIM 模型（不同规模和复杂度） +- 性能测试硬件（推荐 16GB+ RAM） + +--- + +## 5. 风险与缓解 + +### 5.1 技术风险 + +#### 风险 1：geometry4Sharp 维护状况 + +**描述**：geometry4Sharp 原项目活跃度中等，可能缺少最新功能或 bug 修复。 + +**影响**：可能遇到无法解决的 bug 或性能问题。 + +**缓解措施**： + +- ✅ geometry4Sharp 是 fork，源代码可访问，可自行修复 +- ✅ 代码基于成熟的 WildMagic5/GTEngine，质量高 +- ✅ Boost License 允许自由修改 +- ✅ 如需要可 fork 自己维护版本 + +--- + +#### 风险 2：Navisworks Geometry 提取复杂性 + +**描述**：Navisworks API 的几何体提取可能复杂，转换为 DMesh3 可能困难。 + +**影响**：体素化可能不准确，或性能不佳。 + +**缓解措施**： + +- ✅ 可使用包围盒代替精确网格（降低精度但简化实现） +- ✅ 分阶段实现：先包围盒体素化，再精确网格体素化 +- ✅ 参考现有 GeometryExtractor 代码 + +--- + +#### 风险 3：内存占用 + +**描述**：大规模场景的体素网格可能占用大量内存（如 1000³ 体素 = 10亿个单元格）。 + +**影响**：内存不足导致程序崩溃。 + +**缓解措施**： + +- ✅ 使用 `DSparseGrid3` 稀疏网格（仅存储非空体素） +- ✅ 窄带 SDF（仅计算障碍物附近区域） +- ✅ 分块加载和生成 +- ✅ 限制体素网格的最大尺寸 + +--- + +#### 风险 4：路径规划性能 + +**描述**：3D A* 搜索空间比 2D 大得多（N³ vs N²），可能导致性能下降。 + +**影响**：路径规划耗时过长（> 5 秒），用户体验差。 + +**缓解措施**： + +- ✅ 使用更高效的算法（JPS-3D、Theta*、Lazy Theta*） +- ✅ 启发式函数优化（加权 A*） +- ✅ 多线程并行搜索（多个起终点） +- ✅ 路径缓存（重复路径查询） +- ✅ 使用更大的体素（降低分辨率） + +--- + +### 5.2 项目风险 + +#### 风险 5：时间超期 + +**描述**：实施过程中遇到意外困难，导致时间超出预期。 + +**影响**：延迟其他功能开发，影响项目进度。 + +**缓解措施**： + +- ✅ 分阶段实施，每个阶段有明确的验收标准 +- ✅ 阶段 1 完成后评估，决定是否继续 +- ✅ 保留 2.5D 方案作为备选（双模式切换） + +--- + +#### 风险 6：与现有代码冲突 + +**描述**：新体素系统与现有代码不兼容，需要大量重构。 + +**影响**：工作量增加，可能引入新 bug。 + +**缓解措施**： + +- ✅ 新旧系统并存（配置开关） +- ✅ 保持接口一致性（PathFinder、PathOptimizer） +- ✅ 充分测试确保向后兼容 + +--- + +## 6. 配置文件扩展 + +### 6.1 新增配置项 + +在 `config.toml` 中添加体素网格相关配置： + +```toml +[path_planning] +# 路径规划模式：grid_2d5（当前 2.5D 网格）、voxel_3d（新体素网格） +mode = "grid_2d5" # 默认保持向后兼容 + +[voxel_grid] +# 体素大小（米），越小越精确但内存和计算量越大 +voxel_size_meters = 0.5 + +# 是否使用稀疏网格（推荐大规模场景） +use_sparse_grid = true + +# 是否使用窄带距离场（仅计算障碍物附近区域） +use_narrow_band = true +narrow_band_width_meters = 2.0 # 窄带宽度（米） + +# 邻域类型：6（面相邻）、26（面+边+角相邻） +neighbor_type = 26 + +# 是否可视化体素网格 +visualize_voxels = false + +# 是否可视化距离场（热图） +visualize_distance_field = false + +[path_planning_3d] +# 3D A* 算法类型：astar、jps3d、theta_star +algorithm_type = "astar" + +# 启发式权重（> 1.0 加速但可能不是最优路径） +heuristic_weight = 1.0 + +# 是否允许对角线移动 +allow_diagonal = true + +# 是否允许垂直移动 +allow_vertical = true + +# 垂直移动的额外成本系数（> 1.0 表示更倾向于水平移动） +vertical_cost_factor = 1.5 +``` + +--- + +## 7. 性能预期 + +### 7.1 性能对比（预估） + +基于类似规模的 3D 体素路径规划系统经验： + +| 指标 | 2.5D 网格（当前） | 3D 体素网格（预期） | 说明 | +|------|-------------------|---------------------|------| +| **网格生成** | 1-3 秒 | 3-10 秒 | 体素化和 SDF 计算耗时 | +| **路径规划** | 50-200 ms | 100-500 ms | 3D 搜索空间更大 | +| **内存占用** | 50-200 MB | 100-500 MB | 体素数据 + SDF | +| **路径精度** | 中等 | 高 | 真 3D 路径更精确 | +| **复杂场景支持** | 有限 | 优秀 | 管道、桥梁等复杂结构 | + +**场景假设**： + +- 建筑规模：100m × 100m × 20m +- 体素大小：0.5m +- 体素数量：200 × 200 × 40 = 160 万个 +- 稀疏网格实际占用：20-30% = 32-48 万个 + +### 7.2 优化目标 + +**短期目标**（阶段 2 完成后）： + +- ✅ 网格生成 < 15 秒（中等规模场景） +- ✅ 路径规划 < 1 秒（单次查询） +- ✅ 内存占用 < 500 MB + +**长期目标**（阶段 3 优化后）： + +- ✅ 网格生成 < 10 秒 +- ✅ 路径规划 < 500 ms +- ✅ 内存占用 < 300 MB + +--- + +## 8. 替代方案评估 + +### 8.1 方案对比 + +| 方案 | 优点 | 缺点 | 推荐度 | +|------|------|------|--------| +| **geometry4Sharp** | 功能完整、代码质量高、商业友好 | 活跃度中等、文档一般 | ⭐⭐⭐⭐⭐ | +| **自行实现** | 完全控制、轻量级 | 工作量大、需实现 SDF | ⭐⭐⭐ | +| **Unity 相关库** | 活跃、文档好 | Unity 依赖、难以剥离 | ⭐⭐ | +| **保持 2.5D** | 无开发成本、稳定 | 功能受限、无法真 3D | ⭐⭐ | + +### 8.2 决策建议 + +**推荐方案**：**geometry4Sharp** + +**理由**： + +1. ✅ 功能完整，提供完整的体素化和距离场工具链 +2. ✅ 代码质量高，源自经典几何库 WildMagic5/GTEngine +3. ✅ 商业友好的 Boost License +4. ✅ 纯 C#，与 Navisworks 完美兼容 +5. ✅ 即使维护减少，代码仍可用且可自行修改 + +**备选方案**：如果 geometry4Sharp 不满足需求，可考虑： + +- 轻量级自行实现（基于简单的 3D 数组 + 基础距离计算） +- Fork geometry4Sharp 自行维护 + +--- + +## 9. 总结与建议 + +### 9.1 核心结论 + +1. **体素网格是 3D 路径规划的理想方案** + - 统一的 3D 空间表示 + - 简化的路径算法 + - 更精确的障碍物表示 + +2. **geometry4Sharp 是最佳的 C# 体素库** + - 功能完整、代码质量高 + - 商业友好、平台兼容 + - 可满足项目需求 + +3. **实施是可行的** + - 清晰的技术路线 + - 合理的时间估算（17-25 天） + - 风险可控 + +### 9.2 建议行动 + +**立即行动**： + +1. ✅ 安装 geometry4Sharp NuGet 包 +2. ✅ 创建原型验证可行性（阶段 1） +3. ✅ 评估性能和内存占用 + +**后续行动**： + +- 根据原型结果决定是否全面实施 +- 如果可行，按阶段 2-4 计划推进 +- 保持 2.5D 方案作为备选（双模式） + +### 9.3 成功标准 + +项目成功的标志： + +- ✅ 能处理真正的 3D 路径（管道下方、桥梁下方、多层重叠） +- ✅ 路径精度优于 2.5D 方案 +- ✅ 性能可接受（网格生成 < 15 秒，路径规划 < 1 秒） +- ✅ 内存占用可控（< 500 MB） +- ✅ 代码质量高、可维护性好 + +--- + +## 10. 参考资料 + +### 10.1 geometry4Sharp 资源 + +- **GitHub**: +- **NuGet**: +- **原版文档**: (geometry3Sharp) +- **原作者**: Ryan Schmidt (@rms80) +- **Fork 维护者**: New Wheel Technology + +### 10.2 理论基础 + +- **Signed Distance Field (SDF)**: + - SDFGen (Christopher Batty, Robert Bridson) + - "Signed Distance Field Tutorial" - gradientspace.com + +- **Marching Cubes**: + - "Marching Cubes: A High Resolution 3D Surface Construction Algorithm" (Lorensen & Cline, 1987) + +- **3D Pathfinding**: + - "3D Flight Navigation Using Sparse Voxel Octrees" (Daniel Brewer, Game AI Pro 3) + - "Pathfinding in 3D Space: A*, Theta*, Lazy Theta*" (ASCANE) + +### 10.3 相关项目 + +- **WildMagic5**: (David Eberly) +- **Roy-T.AStar**: +- **Unity PathFinding3D**: +- **Nav3D (UE5)**: + +--- + +**文档版本**: v1.0 +**创建日期**: 2025-10-12 +**最后更新**: 2025-10-12 +**作者**: NavisworksTransport 开发团队