diff --git a/doc/working/voxel_pathfinding_task_tracker.md b/doc/working/voxel_pathfinding_task_tracker.md new file mode 100644 index 0000000..208240a --- /dev/null +++ b/doc/working/voxel_pathfinding_task_tracker.md @@ -0,0 +1,1171 @@ +# 体素网格路径规划实施任务跟踪 + +**项目**: NavisworksTransport 体素网格 3D 路径规划 +**分支**: `feature/voxel-pathfinding` +**开始日期**: 2025-10-12 +**预计工期**: 17-25 天 +**负责人**: NavisworksTransport 开发团队 + +--- + +## 项目概述 + +从当前的 2.5D 网格 + 高度层方案迁移到完整的 3D 体素网格路径规划系统，使用 geometry4Sharp 作为体素化和距离场计算的基础库。 + +**目标**: +- ✅ 支持真正的 3D 路径规划（管道下方、桥梁下方、多层重叠） +- ✅ 更精确的障碍物表示（任意 3D 形状） +- ✅ 简化的路径算法（标准 3D A*） +- ✅ 性能可接受（网格生成 < 15 秒，路径规划 < 1 秒） + +--- + +## 分支管理 + +### Git 分支信息 + +``` +当前分支: feature/voxel-pathfinding +基于: 2026 (commit: dd991d3) +远程: origin/feature/voxel-pathfinding +状态: 活跃开发中 +``` + +### Pull Request + +待创建: http://10.0.0.99:4000/tian/NavisworksTransport/compare/main...feature/voxel-pathfinding + +### 提交规范 + +遵循约定式提交（Conventional Commits）： + +``` +feat(voxel): 添加体素网格生成器 +fix(voxel): 修复距离场计算错误 +perf(voxel): 优化 A* 搜索性能 +docs(voxel): 更新体素网格使用文档 +test(voxel): 添加体素化单元测试 +refactor(voxel): 重构 VoxelGrid 数据结构 +``` + +--- + +## 阶段 1：环境搭建与原型验证（3-5 天） + +**目标**: 验证 geometry4Sharp 可行性，创建简单原型 + +### 任务清单 + +#### 1.1 安装 geometry4Sharp NuGet 包 +- [ ] **状态**: 待开始 +- **工作量**: 0.5 天 +- **负责人**: TBD +- **开始日期**: TBD +- **完成日期**: TBD + +**详细任务**: +1. [ ] 在项目中添加 geometry4Sharp 1.0.0 NuGet 包 +2. [ ] 验证与 .NET Framework 4.8 的兼容性 +3. [ ] 运行简单的 geometry4Sharp 示例代码 +4. [ ] 验证所有依赖项正确加载 + +**交付物**: +- 更新后的 `packages.config` 或项目文件 +- geometry4Sharp DLL 正确引用 + +**验收标准**: +- ✅ 项目能够成功编译 +- ✅ 能够实例化 geometry4Sharp 的核心类（如 DMesh3） +- ✅ 无编译错误和警告 + +**阻塞问题**: 无 + +**备注**: +- NuGet 包地址: https://www.nuget.org/packages/geometry4Sharp/1.0.0 +- 如果 NuGet 安装失败，考虑手动下载 .nupkg 文件 + +--- + +#### 1.2 创建 VoxelGrid 基础数据结构 +- [ ] **状态**: 待开始 +- **工作量**: 1 天 +- **负责人**: TBD +- **开始日期**: TBD +- **完成日期**: TBD +- **依赖**: 1.1 完成 + +**详细任务**: +1. [ ] 创建 `VoxelCell` 类（体素单元） + - 类型、可通行性、距离、速度限制等属性 +2. [ ] 创建 `VoxelGrid` 类（3D 体素网格） + - 3D 数组存储体素 + - 坐标转换方法（世界 ↔ 体素） + - 邻居查询方法（6 邻域、26 邻域） +3. [ ] 编写单元测试 + - 坐标转换的正确性 + - 边界检查 + - 邻居查询逻辑 + +**交付物**: +- `src/PathPlanning/VoxelCell.cs` +- `src/PathPlanning/VoxelGrid.cs` +- 单元测试文件 + +**验收标准**: +- ✅ 能够创建指定尺寸的体素网格 +- ✅ 坐标转换准确无误（世界坐标 ↔ 体素索引） +- ✅ 邻居查询返回正确的相邻体素 +- ✅ 单元测试通过率 100% + +**阻塞问题**: 无 + +**备注**: +- 参考设计文档中的完整代码示例 +- 初始版本使用密集数组 `VoxelCell[,,]`，优化阶段再考虑稀疏网格 + +--- + +#### 1.3 实现简单体素化原型 +- [ ] **状态**: 待开始 +- **工作量**: 1 天 +- **负责人**: TBD +- **开始日期**: TBD +- **完成日期**: TBD +- **依赖**: 1.1, 1.2 完成 + +**详细任务**: +1. [ ] 从 Navisworks 提取简单几何体（如包围盒） +2. [ ] 将包围盒转换为简单的体素标记 +3. [ ] 实现基于包围盒的障碍物检测 + - 如果体素中心在障碍物包围盒内 → 标记为不可通行 +4. [ ] 测试简单场景（单个房间 + 几个障碍物） + +**交付物**: +- `VoxelGridGenerator` 类的初始实现（简化版） +- 测试场景的体素化结果 + +**验收标准**: +- ✅ 能够从 Navisworks 场景生成体素网格 +- ✅ 障碍物体素正确标记为不可通行 +- ✅ 自由空间体素正确标记为可通行 +- ✅ 体素化时间 < 10 秒（简单场景） + +**阻塞问题**: 无 + +**备注**: +- 本阶段不使用 geometry4Sharp 的 MeshSignedDistanceGrid +- 仅使用包围盒进行简单体素化 +- 为后续精确体素化打基础 + +--- + +#### 1.4 测试 MeshSignedDistanceGrid +- [ ] **状态**: 待开始 +- **工作量**: 1 天 +- **负责人**: TBD +- **开始日期**: TBD +- **完成日期**: TBD +- **依赖**: 1.1, 1.3 完成 + +**详细任务**: +1. [ ] 从 Navisworks 提取三角网格（使用现有 GeometryExtractor） +2. [ ] 将 Navisworks 网格转换为 geometry4Sharp 的 DMesh3 +3. [ ] 使用 MeshSignedDistanceGrid 计算签名距离场 +4. [ ] 验证距离场的正确性 + - 障碍物内部：负距离 + - 障碍物外部：正距离 + - 障碍物表面：距离 ≈ 0 +5. [ ] 测量性能（不同网格复杂度） + +**交付物**: +- Navisworks Geometry → DMesh3 转换代码 +- MeshSignedDistanceGrid 使用示例 +- 性能测试报告 + +**验收标准**: +- ✅ 能够成功提取 Navisworks 三角网格 +- ✅ 能够转换为 DMesh3 格式 +- ✅ 距离场计算正确（通过可视化验证） +- ✅ 性能可接受（中等网格 < 5 秒） + +**阻塞问题**: +- ⚠️ Navisworks Geometry API 的复杂性可能导致转换困难 +- **缓解**: 先使用简单几何体（如盒子）测试 + +**备注**: +- 这是核心技术验证任务 +- 如果转换困难，可以先使用包围盒代替精确网格 + +--- + +#### 1.5 体素可视化验证 +- [ ] **状态**: 待开始 +- **工作量**: 1 天 +- **负责人**: TBD +- **开始日期**: TBD +- **完成日期**: TBD +- **依赖**: 1.2, 1.3 完成 + +**详细任务**: +1. [ ] 在 Navisworks 3D 视图中显示体素网格 + - 使用 RenderPlugin 或 GeometryPrimitives + - 不同类型的体素使用不同颜色 + - 障碍物：红色 + - 通道：绿色 + - 门：蓝色 + - 楼梯：黄色 +2. [ ] 实现体素网格的开关控制 +3. [ ] 实现体素透明度调整 +4. [ ] 测试不同场景的可视化效果 + +**交付物**: +- `VoxelGridVisualizer` 类 +- 可视化控制 UI（或命令） +- 测试场景的可视化截图 + +**验收标准**: +- ✅ 体素网格能够在 Navisworks 中正确显示 +- ✅ 不同类型的体素颜色区分明确 +- ✅ 可视化不影响性能（帧率 > 20 FPS） +- ✅ 能够清晰观察体素网格与 BIM 模型的对应关系 + +**阻塞问题**: 无 + +**备注**: +- 参考现有的网格可视化代码（GridMapVisualizer） +- 可以使用小立方体或点云表示体素 + +--- + +### 阶段 1 总结与评估 + +#### 验收标准 + +- [ ] **所有任务完成**: 5/5 任务完成 +- [ ] **功能验证**: geometry4Sharp 能够满足体素化需求 +- [ ] **性能验证**: 简单场景体素化时间 < 5 秒 +- [ ] **可视化验证**: 体素网格显示正确，颜色区分清晰 +- [ ] **技术文档**: 完成阶段 1 的技术总结文档 + +#### 决策点 + +**是否继续阶段 2？** + +评估标准： +- ✅ geometry4Sharp 集成成功 +- ✅ 体素化效果满意 +- ✅ 性能可接受 +- ✅ 无重大技术障碍 + +如果评估不通过，考虑： +1. 调整体素大小（降低分辨率） +2. 使用更简单的体素化方法（包围盒） +3. 或放弃体素方案，保持 2.5D 网格 + +#### 阶段 1 提交 + +```bash +git add . +git commit -m "feat(voxel): 阶段1 - geometry4Sharp集成与原型验证 + +完成内容： +- ✅ 添加 geometry4Sharp 1.0.0 NuGet 包 +- ✅ 创建 VoxelGrid 基础数据结构 +- ✅ 实现简单体素化原型 +- ✅ 测试 MeshSignedDistanceGrid 距离场计算 +- ✅ 实现体素可视化 + +测试场景：简单房间模型（10m × 10m × 3m） +性能：体素化 < 5 秒，可视化流畅 +体素分辨率：0.5m + +下一步：阶段2 - 核心功能开发" + +git push +``` + +--- + +## 阶段 2：核心功能开发（7-10 天） + +**目标**: 实现完整的体素网格生成和 3D 路径规划功能 + +### 任务清单 + +#### 2.1 实现完整的 VoxelGrid 类 +- [ ] **状态**: 待开始 +- **工作量**: 2 天 +- **负责人**: TBD +- **开始日期**: TBD +- **完成日期**: TBD +- **依赖**: 阶段 1 完成 + +**详细任务**: +1. [ ] 扩展 VoxelCell 类 + - 添加距离场数据（来自 SDF） + - 添加关联的 ModelItem 引用 + - 添加成本计算逻辑 +2. [ ] 完善 VoxelGrid 类 + - 统计信息方法（体素数量、可通行比例等） + - 区域查询方法（获取指定范围内的体素） + - 序列化/反序列化（保存/加载体素网格） +3. [ ] 性能优化 + - 考虑使用稀疏网格（DSparseGrid3） + - 内存占用分析 +4. [ ] 完善单元测试 + +**交付物**: +- 完整的 `VoxelGrid` 类 +- 单元测试套件 +- 性能测试报告 + +**验收标准**: +- ✅ 支持大规模场景（100m × 100m × 20m） +- ✅ 内存占用 < 500 MB +- ✅ 查询性能 < 1ms（单次体素查询） +- ✅ 单元测试覆盖率 > 80% + +**阻塞问题**: 无 + +**备注**: +- 如果内存占用过大，切换到稀疏网格实现 +- 参考 geometry4Sharp 的 DSparseGrid3 或 BiGrid3 + +--- + +#### 2.2 实现 VoxelGridGenerator +- [ ] **状态**: 待开始 +- **工作量**: 3 天 +- **负责人**: TBD +- **开始日期**: TBD +- **完成日期**: TBD +- **依赖**: 2.1 完成 + +**详细任务**: +1. [ ] 完善 Navisworks Geometry 提取 + - 支持多种几何类型（三角网格、包围盒） + - 批量提取优化 +2. [ ] 实现精确体素化 + - 使用 MeshSignedDistanceGrid + - 距离场查询和体素标记 + - 考虑车辆半径和安全间隙 +3. [ ] 实现特殊元素处理 + - 门元素标记（可通行 + 速度限制） + - 通道元素标记 + - 楼梯元素标记 + - 电梯元素标记 +4. [ ] 多线程优化 + - 并行体素化 + - 进度报告 +5. [ ] 错误处理和日志 + +**交付物**: +- 完整的 `VoxelGridGenerator` 类 +- 支持多种场景类型 +- 详细的日志输出 + +**验收标准**: +- ✅ 能够处理复杂 BIM 模型（1000+ 元素） +- ✅ 体素化时间 < 15 秒（中等规模场景） +- ✅ 距离场计算准确（手动验证） +- ✅ 特殊元素正确标记 +- ✅ 日志详细清晰 + +**阻塞问题**: +- ⚠️ Navisworks Geometry 提取可能复杂 +- **缓解**: 分阶段实现（先包围盒，再精确网格） + +**备注**: +- 这是最复杂的任务，需要充足时间 +- 建议使用 Stopwatch 测量各阶段耗时 + +--- + +#### 2.3 实现 VoxelPathFinder (3D A*) +- [ ] **状态**: 待开始 +- **工作量**: 2 天 +- **负责人**: TBD +- **开始日期**: TBD +- **完成日期**: TBD +- **依赖**: 2.1 完成 + +**详细任务**: +1. [ ] 实现 3D A* 算法 + - 使用优先队列（PriorityQueue） + - 26 邻域搜索（或 6 邻域） + - 启发式函数（欧几里得距离） +2. [ ] 成本计算 + - 基础距离成本 + - 速度限制影响 + - 垂直移动额外成本 +3. [ ] 路径重建 + - 从目标回溯到起点 + - 体素坐标 → 世界坐标转换 +4. [ ] 性能优化 + - 双向 A*（可选） + - JPS-3D（可选，后期优化） +5. [ ] 错误处理 + - 起终点不可通行 + - 无路径情况 + +**交付物**: +- 完整的 `VoxelPathFinder` 类 +- 性能测试报告 +- 路径质量评估报告 + +**验收标准**: +- ✅ 能够找到 3D 路径（包括垂直移动） +- ✅ 路径避开障碍物 +- ✅ 路径规划时间 < 1 秒（中等规模场景） +- ✅ 路径长度接近最优（误差 < 10%） + +**阻塞问题**: 无 + +**备注**: +- 可以参考 Roy-T.AStar 的实现思路 +- 初始版本使用简单 A*，后期考虑高级算法 + +--- + +#### 2.4 集成到现有系统 +- [ ] **状态**: 待开始 +- **工作量**: 2 天 +- **负责人**: TBD +- **开始日期**: TBD +- **完成日期**: TBD +- **依赖**: 2.2, 2.3 完成 + +**详细任务**: +1. [ ] 替换 GridMapGenerator + - 创建 VoxelGridGenerator 的调用入口 + - 保留 2.5D 模式作为备选（配置开关） +2. [ ] 替换 AutoPathFinder + - 创建 VoxelPathFinder 的调用入口 + - 保持接口一致性 +3. [ ] 适配 PathOptimizer + - 确保 3D 路径优化正常工作 + - 测试高度变化保护 +4. [ ] 更新 UI + - 添加体素网格模式选择 + - 显示体素化进度 +5. [ ] 集成测试 + - 端到端路径规划流程 + - 不同场景测试 + +**交付物**: +- 集成后的系统 +- 配置文件更新 +- 集成测试报告 + +**验收标准**: +- ✅ 新旧系统切换无缝 +- ✅ 配置文件支持模式选择 +- ✅ 所有现有功能正常工作 +- ✅ 体素模式下路径规划成功 + +**阻塞问题**: 无 + +**备注**: +- 保持向后兼容非常重要 +- 2.5D 模式作为保险 + +--- + +### 阶段 2 总结与评估 + +#### 验收标准 + +- [ ] **所有任务完成**: 4/4 任务完成 +- [ ] **功能验证**: 完整的 3D 路径规划功能可用 +- [ ] **性能验证**: + - 网格生成 < 15 秒 + - 路径规划 < 1 秒 +- [ ] **集成验证**: 与现有系统无缝集成 +- [ ] **测试验证**: 多场景测试通过 + +#### 阶段 2 提交 + +```bash +git add . +git commit -m "feat(voxel): 阶段2 - 核心功能开发完成 + +完成内容： +- ✅ 实现完整的 VoxelGrid 类 +- ✅ 实现 VoxelGridGenerator（精确体素化 + SDF） +- ✅ 实现 VoxelPathFinder（3D A*） +- ✅ 集成到现有系统（双模式支持） + +测试场景： +- 简单场景：10m × 10m × 3m +- 中等场景：50m × 50m × 10m +- 复杂场景：100m × 100m × 20m（多层建筑） + +性能： +- 网格生成：5-12 秒（视场景复杂度） +- 路径规划：100-800 ms +- 内存占用：50-300 MB + +已知问题： +- 大规模场景内存占用较高，需优化 + +下一步：阶段3 - 性能优化与测试" + +git push +``` + +--- + +## 阶段 3：性能优化与测试（5-7 天） + +**目标**: 优化性能，进行全面测试 + +### 任务清单 + +#### 3.1 稀疏网格优化 +- [ ] **状态**: 待开始 +- **工作量**: 2 天 +- **负责人**: TBD +- **开始日期**: TBD +- **完成日期**: TBD +- **依赖**: 阶段 2 完成 + +**详细任务**: +1. [ ] 评估内存占用 + - 不同场景的内存使用情况 + - 识别内存瓶颈 +2. [ ] 实现稀疏网格 + - 使用 geometry4Sharp 的 DSparseGrid3 + - 或自定义 Dictionary-based 稀疏网格 +3. [ ] 对比测试 + - 密集网格 vs 稀疏网格 + - 内存占用对比 + - 性能对比 +4. [ ] 选择最优方案 + +**交付物**: +- 稀疏网格实现 +- 性能对比报告 +- 内存占用分析 + +**验收标准**: +- ✅ 大规模场景内存占用降低 50-70% +- ✅ 查询性能不显著下降（< 20% 慢） +- ✅ 体素化时间不增加 + +**阻塞问题**: 无 + +**备注**: +- 仅在内存占用成为问题时才实施 +- 优先考虑代码简洁性 + +--- + +#### 3.2 窄带 SDF 优化 +- [ ] **状态**: 待开始 +- **工作量**: 1 天 +- **负责人**: TBD +- **开始日期**: TBD +- **完成日期**: TBD +- **依赖**: 阶段 2 完成 + +**详细任务**: +1. [ ] 实现窄带距离场 + - 仅计算障碍物附近 N 米范围内的距离 + - 其他区域设为默认值（如 999） +2. [ ] 配置化窄带宽度 + - 添加配置选项 `narrow_band_width_meters` +3. [ ] 测试窄带效果 + - 体素化速度提升 + - 路径规划准确性验证 +4. [ ] 对比测试 + +**交付物**: +- 窄带 SDF 实现 +- 性能提升报告 + +**验收标准**: +- ✅ 体素化速度提升 30-50% +- ✅ 路径规划准确性不受影响 +- ✅ 配置灵活 + +**阻塞问题**: 无 + +**备注**: +- geometry4Sharp 的 MeshSignedDistanceGrid 支持窄带模式 +- 窄带宽度建议设为车辆半径的 3-5 倍 + +--- + +#### 3.3 A* 算法优化 +- [ ] **状态**: 待开始 +- **工作量**: 2 天 +- **负责人**: TBD +- **开始日期**: TBD +- **完成日期**: TBD +- **依赖**: 2.3 完成 + +**详细任务**: +1. [ ] 启发式函数优化 + - 加权 A*（权重 > 1.0 加速搜索） + - 考虑垂直移动的额外成本 +2. [ ] 邻域优化 + - 6 邻域 vs 26 邻域对比 + - 可配置邻域类型 +3. [ ] 算法改进（可选） + - 双向 A* + - JPS-3D（Jump Point Search） + - Theta*（路径更平滑） +4. [ ] 性能测试 + - 不同算法对比 + - 不同场景下的表现 + +**交付物**: +- 优化后的 VoxelPathFinder +- 算法对比报告 +- 配置选项 + +**验收标准**: +- ✅ 路径规划速度提升 20-50% +- ✅ 路径质量不降低 +- ✅ 支持多种算法配置 + +**阻塞问题**: 无 + +**备注**: +- 优先优化启发式函数和邻域 +- JPS-3D 和 Theta* 作为可选高级功能 + +--- + +#### 3.4 多场景性能测试 +- [ ] **状态**: 待开始 +- **工作量**: 2 天 +- **负责人**: TBD +- **开始日期**: TBD +- **完成日期**: TBD +- **依赖**: 3.1, 3.2, 3.3 完成 + +**详细任务**: +1. [ ] 准备测试场景 + - 简单场景：10m × 10m × 3m，10 个障碍物 + - 中等场景：50m × 50m × 10m，100 个障碍物 + - 复杂场景：100m × 100m × 20m，1000 个障碍物 + - 极限场景：200m × 200m × 30m，5000 个障碍物 +2. [ ] 性能基准测试 + - 网格生成时间 + - 路径规划时间 + - 内存占用 + - CPU 使用率 +3. [ ] 与 2.5D 方案对比 + - 性能对比 + - 路径质量对比 + - 内存对比 +4. [ ] 生成性能报告 + +**交付物**: +- 测试场景集 +- 详细的性能测试报告 +- 性能对比图表 +- 优化建议 + +**验收标准**: +- ✅ 所有场景测试通过 +- ✅ 性能达标（网格生成 < 15 秒，路径规划 < 1 秒） +- ✅ 内存占用 < 500 MB +- ✅ 路径质量优于 2.5D 方案 + +**阻塞问题**: 无 + +**备注**: +- 使用真实的 Navisworks 模型测试 +- 记录详细的性能数据用于优化决策 + +--- + +### 阶段 3 总结与评估 + +#### 验收标准 + +- [ ] **所有任务完成**: 4/4 任务完成 +- [ ] **性能达标**: + - 网格生成 < 10 秒 + - 路径规划 < 500 ms + - 内存占用 < 300 MB +- [ ] **测试覆盖**: 所有场景类型测试通过 +- [ ] **文档完善**: 性能优化文档和测试报告 + +#### 阶段 3 提交 + +```bash +git add . +git commit -m "perf(voxel): 阶段3 - 性能优化与测试完成 + +完成内容： +- ✅ 稀疏网格优化（内存占用降低 60%） +- ✅ 窄带 SDF 优化（体素化速度提升 40%） +- ✅ A* 算法优化（路径规划速度提升 35%） +- ✅ 多场景性能测试（4 种场景） + +性能测试结果： +┌───────────┬────────────┬────────────┬────────────┐ +│ 场景 │ 网格生成 │ 路径规划 │ 内存占用 │ +├───────────┼────────────┼────────────┼────────────┤ +│ 简单 │ 2.1s │ 50ms │ 25MB │ +│ 中等 │ 5.8s │ 180ms │ 95MB │ +│ 复杂 │ 9.5s │ 420ms │ 230MB │ +│ 极限 │ 18.2s │ 890ms │ 480MB │ +└───────────┴────────────┴────────────┴────────────┘ + +与 2.5D 方案对比： +- 路径质量：体素方案更精确（真 3D） +- 性能：体素方案略慢（10-20%），但可接受 +- 内存：体素方案更高（30-50%），已优化 + +下一步：阶段4 - 文档与集成" + +git push +``` + +--- + +## 阶段 4：文档与集成（2-3 天） + +**目标**: 完善文档，准备合并 + +### 任务清单 + +#### 4.1 完善代码文档（XML 注释） +- [ ] **状态**: 待开始 +- **工作量**: 1 天 +- **负责人**: TBD +- **开始日期**: TBD +- **完成日期**: TBD +- **依赖**: 阶段 3 完成 + +**详细任务**: +1. [ ] 为所有公共类添加 XML 注释 + - VoxelCell, VoxelGrid + - VoxelGridGenerator, VoxelPathFinder + - VoxelGridVisualizer +2. [ ] 为所有公共方法添加注释 + - 参数说明 + - 返回值说明 + - 异常说明 + - 使用示例 +3. [ ] 添加使用示例 + - 简单场景示例 + - 高级配置示例 +4. [ ] 生成 API 文档（可选） + +**交付物**: +- 完整的 XML 注释 +- API 使用示例代码 +- （可选）生成的 HTML 文档 + +**验收标准**: +- ✅ 所有公共 API 有完整注释 +- ✅ 注释清晰准确 +- ✅ 示例代码可运行 + +**阻塞问题**: 无 + +**备注**: +- 参考现有代码的注释风格 +- 使用中文注释 + +--- + +#### 4.2 添加单元测试 +- [ ] **状态**: 待开始 +- **工作量**: 1 天 +- **负责人**: TBD +- **开始日期**: TBD +- **完成日期**: TBD +- **依赖**: 阶段 3 完成 + +**详细任务**: +1. [ ] VoxelGrid 单元测试 + - 坐标转换测试 + - 邻居查询测试 + - 边界检查测试 +2. [ ] VoxelPathFinder 单元测试 + - 简单路径测试 + - 障碍物避开测试 + - 无路径情况测试 +3. [ ] VoxelGridGenerator 单元测试 + - 体素化正确性测试 + - 特殊元素处理测试 +4. [ ] 集成测试 + - 端到端路径规划测试 + +**交付物**: +- 单元测试套件 +- 测试覆盖率报告 + +**验收标准**: +- ✅ 单元测试覆盖率 > 70% +- ✅ 所有测试通过 +- ✅ 关键路径有集成测试 + +**阻塞问题**: 无 + +**备注**: +- 使用 MSTest 或 NUnit +- 参考现有测试代码 + +--- + +#### 4.3 更新用户文档 +- [ ] **状态**: 待开始 +- **工作量**: 0.5 天 +- **负责人**: TBD +- **开始日期**: TBD +- **完成日期**: TBD +- **依赖**: 阶段 3 完成 + +**详细任务**: +1. [ ] 更新设计文档 + - 实际实施情况 vs 原计划 + - 性能数据更新 + - 已知问题和限制 +2. [ ] 编写用户指南 + - 如何启用体素网格模式 + - 参数配置说明 + - 性能调优建议 + - 故障排查 +3. [ ] 更新 README（如果需要） + +**交付物**: +- 更新后的设计文档 +- 用户指南 +- README 更新（可选） + +**验收标准**: +- ✅ 文档准确完整 +- ✅ 用户能够根据文档配置和使用 +- ✅ 常见问题有解答 + +**阻塞问题**: 无 + +**备注**: +- 文档保存在 `doc/design/2026/` +- 使用中文编写 + +--- + +#### 4.4 配置文件扩展 +- [ ] **状态**: 待开始 +- **工作量**: 0.5 天 +- **负责人**: TBD +- **开始日期**: TBD +- **完成日期**: TBD +- **依赖**: 阶段 2 完成 + +**详细任务**: +1. [ ] 添加体素网格配置项到 config.toml + ```toml + [path_planning] + mode = "grid_2d5" # 或 "voxel_3d" + + [voxel_grid] + voxel_size_meters = 0.5 + use_sparse_grid = true + use_narrow_band = true + narrow_band_width_meters = 2.0 + neighbor_type = 26 + visualize_voxels = false + visualize_distance_field = false + + [path_planning_3d] + algorithm_type = "astar" + heuristic_weight = 1.0 + allow_diagonal = true + allow_vertical = true + vertical_cost_factor = 1.5 + ``` +2. [ ] 更新 ConfigManager 支持新配置项 +3. [ ] 添加配置验证 +4. [ ] 测试配置加载和保存 + +**交付物**: +- 更新后的 config.toml 模板 +- ConfigManager 代码更新 +- 配置验证逻辑 + +**验收标准**: +- ✅ 所有新配置项能够正确加载 +- ✅ 配置验证逻辑正确 +- ✅ 默认配置合理 + +**阻塞问题**: 无 + +**备注**: +- 保持向后兼容（默认使用 2.5D 模式） +- 参考现有配置结构 + +--- + +### 阶段 4 总结与评估 + +#### 验收标准 + +- [ ] **所有任务完成**: 4/4 任务完成 +- [ ] **代码质量**: + - XML 注释完整 + - 单元测试覆盖率 > 70% +- [ ] **文档完善**: + - 设计文档更新 + - 用户指南完整 +- [ ] **配置支持**: 配置文件扩展完成 + +#### 阶段 4 提交 + +```bash +git add . +git commit -m "docs(voxel): 阶段4 - 文档与集成完成 + +完成内容： +- ✅ 完善代码文档（XML 注释 100% 覆盖） +- ✅ 添加单元测试（覆盖率 75%） +- ✅ 更新用户文档（设计文档 + 用户指南） +- ✅ 配置文件扩展（支持体素网格配置） + +文档： +- doc/design/2026/体素网格路径规划方案.md（更新） +- doc/guide/体素网格使用指南.md（新增） + +测试： +- 单元测试：45 个测试用例，100% 通过 +- 覆盖率：VoxelGrid 85%, VoxelPathFinder 72%, 平均 75% + +配置： +- config.toml 新增 [voxel_grid] 和 [path_planning_3d] 配置段 +- 支持双模式切换（grid_2d5 / voxel_3d） + +准备合并到 2026 分支" + +git push +``` + +--- + +## 最终验证与决策 + +### 验证清单 + +#### 功能验证 +- [ ] 所有 4 个阶段的任务完成 +- [ ] 体素网格生成功能正常 +- [ ] 3D 路径规划功能正常 +- [ ] 与现有系统集成无缝 +- [ ] 双模式切换无问题 + +#### 性能验证 +- [ ] 网格生成时间达标（< 10 秒，中等场景） +- [ ] 路径规划时间达标（< 500 ms） +- [ ] 内存占用可接受（< 300 MB） +- [ ] CPU 使用率正常 + +#### 质量验证 +- [ ] 代码注释完整（XML 注释） +- [ ] 单元测试覆盖率 > 70% +- [ ] 所有测试通过 +- [ ] 无严重 bug + +#### 文档验证 +- [ ] 设计文档完整准确 +- [ ] 用户指南清晰易懂 +- [ ] 配置文档完整 +- [ ] API 文档完整 + +--- + +### 决策：是否合并到 2026 分支？ + +#### 决策标准 + +**✅ 建议合并，如果满足以下所有条件**： +1. ✅ 功能完整可用 +2. ✅ 性能达到目标 +3. ✅ 质量达标（测试 + 文档） +4. ✅ 无已知严重 bug +5. ✅ 团队一致同意 + +**⚠️ 考虑延期合并，如果存在以下情况**： +1. ⚠️ 性能不达标但有明确优化方案 +2. ⚠️ 存在已知 bug 但不影响主要功能 +3. ⚠️ 文档不完善但功能正常 + +**❌ 不建议合并，如果存在以下情况**： +1. ❌ 功能严重缺陷 +2. ❌ 性能严重不达标 +3. ❌ 存在严重 bug +4. ❌ 与现有系统冲突严重 + +--- + +### 合并流程 + +#### 方案 A：直接合并（推荐） + +```bash +# 1. 确保 feature 分支最新 +git checkout feature/voxel-pathfinding +git pull + +# 2. 切换到 2026 分支 +git checkout 2026 +git pull + +# 3. 合并 feature 分支 +git merge feature/voxel-pathfinding + +# 4. 解决冲突（如果有） +# 手动解决冲突文件 +git add . +git commit -m "merge: 合并体素网格路径规划功能" + +# 5. 推送到远程 +git push + +# 6. 删除 feature 分支（可选） +git branch -d feature/voxel-pathfinding +git push origin --delete feature/voxel-pathfinding +``` + +#### 方案 B：通过 Pull Request 合并（推荐用于代码审查） + +```bash +# 1. 在 GitLab/GitHub 创建 Pull Request +# URL: http://10.0.0.99:4000/tian/NavisworksTransport/compare/main...feature/voxel-pathfinding + +# 2. 团队审查代码 + +# 3. 通过 PR 合并 + +# 4. 删除 feature 分支 +``` + +--- + +### 放弃方案的流程 + +**如果决定不合并体素网格方案**： + +```bash +# 1. 切换回 2026 分支 +git checkout 2026 + +# 2. 删除本地 feature 分支 +git branch -D feature/voxel-pathfinding + +# 3. 删除远程 feature 分支 +git push origin --delete feature/voxel-pathfinding + +# 4. 更新文档记录放弃原因 +# 在 doc/design/2026/体素网格路径规划方案.md 添加"实施结果"章节 +``` + +**保留经验教训**： +- 在设计文档中记录： + - 为什么放弃 + - 遇到了什么问题 + - 学到了什么 + - 未来是否有可能重新考虑 + +--- + +## 项目进度跟踪 + +### 总体进度 + +``` +阶段 1: [ ] 0/5 任务完成 (0%) 预计: 3-5 天 实际: TBD +阶段 2: [ ] 0/4 任务完成 (0%) 预计: 7-10 天 实际: TBD +阶段 3: [ ] 0/4 任务完成 (0%) 预计: 5-7 天 实际: TBD +阶段 4: [ ] 0/4 任务完成 (0%) 预计: 2-3 天 实际: TBD +─────────────────────────────────────────────────────────────── +总计: [ ] 0/17 任务完成 (0%) 预计: 17-25 天 实际: TBD +``` + +### 里程碑 + +- [ ] **里程碑 1**: 阶段 1 完成 - 原型验证成功 + - **目标日期**: TBD + - **实际日期**: TBD + - **状态**: 待开始 + +- [ ] **里程碑 2**: 阶段 2 完成 - 核心功能可用 + - **目标日期**: TBD + - **实际日期**: TBD + - **状态**: 待开始 + +- [ ] **里程碑 3**: 阶段 3 完成 - 性能达标 + - **目标日期**: TBD + - **实际日期**: TBD + - **状态**: 待开始 + +- [ ] **里程碑 4**: 阶段 4 完成 - 文档完善 + - **目标日期**: TBD + - **实际日期**: TBD + - **状态**: 待开始 + +- [ ] **里程碑 5**: 合并到 2026 分支 + - **目标日期**: TBD + - **实际日期**: TBD + - **状态**: 待开始 + +--- + +## 风险与问题追踪 + +### 当前风险 + +| 风险ID | 风险描述 | 影响 | 概率 | 缓解措施 | 负责人 | 状态 | +|--------|----------|------|------|----------|--------|------| +| R1 | geometry4Sharp 维护停滞 | 中 | 低 | 代码可自行修改 | TBD | 监控中 | +| R2 | Navisworks Geometry 提取复杂 | 高 | 中 | 先用包围盒，再用精确网格 | TBD | 监控中 | +| R3 | 内存占用过高 | 高 | 中 | 使用稀疏网格 | TBD | 监控中 | +| R4 | 路径规划性能不达标 | 高 | 低 | 算法优化（JPS-3D） | TBD | 监控中 | +| R5 | 时间超期 | 中 | 中 | 分阶段验证，及时止损 | TBD | 监控中 | + +### 已知问题 + +| 问题ID | 问题描述 | 严重性 | 状态 | 解决方案 | 负责人 | 备注 | +|--------|----------|--------|------|----------|--------|------| +| - | 暂无已知问题 | - | - | - | - | - | + +--- + +## 参考资料 + +### 设计文档 + +- **主文档**: [doc/design/2026/体素网格路径规划方案.md](../design/2026/体素网格路径规划方案.md) +- **GPU 加速研究**: [doc/design/2026/GPU加速可行性研究.md](../design/2026/GPU加速可行性研究.md) + +### 技术资源 + +- **geometry4Sharp GitHub**: https://github.com/NewWheelTech/geometry4Sharp +- **geometry4Sharp NuGet**: https://www.nuget.org/packages/geometry4Sharp/1.0.0 +- **Roy-T.AStar GitHub**: https://github.com/roy-t/AStar + +### 相关工作文档 + +- **当前 2.5D 网格方案**: [doc/design/2026/PATHFINDING_DESIGN.md](../design/2026/PATHFINDING_DESIGN.md) +- **A* 改进方案**: [doc/design/2026/C# A_ 寻路优化_.md](../design/2026/C# A_ 寻路优化_.md) + +--- + +## 变更日志 + +### 2025-10-12 +- **创建文档**: 初始版本，定义 4 个阶段的详细任务 +- **创建分支**: `feature/voxel-pathfinding` +- **项目启动**: 准备开始阶段 1 + +--- + +**文档版本**: v1.0 +**最后更新**: 2025-10-12 +**维护者**: NavisworksTransport 开发团队