creep-flight-distance-calculation/当前开发程序项目文档.md

当前开发程序项目文档

一、项目概述

本项目是一个基于体素空间与三角网格几何的三维路径/距离计算程序，当前代码库可以完成零部件之间的飞行距离与几何路径计算

从当前 main.cpp 的实现看，现阶段主可执行程序主要用于调试和验证 CalculateFlightDistance 这套 C 接口流程，即：

• 读取体素空间尺寸、世界坐标偏移和体素尺寸
• 调用 voxel_distance_api 导出的飞行距离接口
• 输出起终点、距离、路径点数量
• 导出世界坐标路径到文本或 OBJ 文件，便于可视化分析

---

二、主要功能

2.1 飞行距离计算

程序当前的重点开发能力是飞行距离计算，主要包括：

• 计算两个部件之间在非障碍空间中的最短路径
• 支持体素级粗搜索与几何级路径修正
• 支持输出世界坐标路径
• 支持起终点几何投影与表面贴附
• 支持局部细化、障碍表面特征吸附、路径优化

2.2 调试与可视化输出

程序支持多种开发期辅助输出：

• 搜索日志输出
• OBJ 几何导出
• 路径文本导出
• 障碍物可视化工具

---

三、构建与编译

3.1 环境要求

• CMake >= 3.10
• C++14
• Windows + MSVC 为当前主要目标环境
• 代码中也兼容 GCC 的部分编译选项

3.2 编译运行方式

mkdir build
cd build
g++ -std=c++14 -DBUSBAR_ROUTER_STATIC -fpermissive *.cpp -I../include -o main.exe
.\main.exe flight_api 100 100 50 0.0 0.0 0.0 1.0 -1.0

3.3 当前构建特点

当前 CMakeLists.txt 的特点如下：

• 工程名为 BusbarFlightDistance
• 使用 file(GLOB ...) 收集 src/*.cpp
• 统一编译为一个可执行程序 main
• 定义了 BUSBAR_ROUTER_STATIC，当前按静态方式处理导出宏

---

四、项目目录结构

newcode/
├── CMakeLists.txt
├── readme
├── include/
│   ├── busbar_config.hpp              # 母线规划配置
│   ├── busbar_planner.hpp             # 母线主规划器
│   ├── busbar_planner_api.hpp         # 母线规划 C 接口
│   ├── busbar_segment.hpp             # 路径段定义
│   ├── busbar_types.hpp               # 基础类型与状态
│   ├── coarse_planner.hpp             # 粗规划器
│   ├── CommonStructs.hpp              # 几何输入输出结构
│   ├── debug_export.hpp               # OBJ 等调试导出
│   ├── debug_logger.hpp               # 日志工具
│   ├── geometry_utils.hpp             # 网格几何工具函数
│   ├── point.hpp                      # 体素点/整数点
│   ├── segment_generator.hpp          # 路径段候选生成
│   ├── space_analyzer.hpp             # 体素空间查询
│   ├── vector3.hpp                    # 三维向量类
│   ├── voxel_distance_api.hpp         # 距离计算 C 接口
│   └── voxel_distance_calculator.hpp  # 飞行/爬电距离核心算法
├── src/
│   ├── busbar_planner.cpp
│   ├── busbar_planner_api.cpp
│   ├── busbar_segment.cpp
│   ├── coarse_planner.cpp
│   ├── debug_export.cpp
│   ├── debug_logger.cpp
│   ├── geometry_utils.cpp
│   ├── main.cpp                       # 当前开发主入口
│   ├── segment_generator.cpp
│   ├── space_analyzer.cpp
│   ├── test_busbar_api.cpp
│   ├── vector3.cpp
│   ├── visualize_obstacles.cpp
│   ├── voxel_distance_api.cpp
│   └── voxel_distance_calculator.cpp
├── data/                              # 测试数据目录
├── build/                             # 编译输出目录
└── busbar_router_dll.dll              # 现有 DLL 产物

---

五、核心架构

5.1 整体分层

当前工程可以分为四层：

1. 基础数据层
   包含 Vector3、Point、Voxel、IniInPutStruct 等基础几何和体素数据结构。

2. 空间与几何工具层
   包含 space_analyzer、geometry_utils、debug_export、debug_logger 等基础支撑模块。

3. 算法层
   包含母线规划算法和距离计算算法两大子系统。

4. 接口与入口层
   包含 busbar_planner_api、voxel_distance_api 和当前 main.cpp 调试入口。

5.2 核心算法子系统

距离与几何路径计算

核心流程为：

输入两个部件与场景数据
→ 提取体素边界/障碍区域
→ 粗级最短路搜索
→ 必要时局部细化
→ 世界坐标路径重建
→ 端点几何投影/吸附/优化
→ 输出距离与几何路径

---

六、关键模块说明

6.1 main.cpp

当前开发程序的主入口文件，主要职责是：

• 解析命令行参数
• 调用 CalculateFlightDistance
• 输出距离、起终点和路径点
• 导出 flight_path_world.txt
• 导出 debug_output/flight_path_world.obj

当前代码中虽然保留了模式判断骨架，但实际上主入口已经固定调用 CalculateFlightDistance()`，说明当前版本主要是为飞行距离功能服务。

6.2 voxel_distance_api.*

对外提供纯 C 接口，便于 DLL 调用或跨语言集成。

当前主要接口包括：

• CalculateFlightDistance
• VoxelGetLastError

其中 CalculateFlightDistance 是当前开发程序的实际调用入口。

6.3 voxel_distance_calculator.*

这是当前工程最核心、也最复杂的算法模块之一，主要负责：

• 体素集合提取与边界识别
• 飞行距离搜索
• 爬电距离搜索
• 粗路径与几何路径重建
• 世界坐标端点修正
• 网格表面投影
• 路径折线优化与障碍特征吸附

从当前迭代情况看，这个文件也是近期主要调试与修改的热点文件。

6.4 geometry_utils.*

提供三角网格与几何判定相关工具，例如：

• 点到网格距离
• 最近点投影
• 线段与网格碰撞检测
• 端点合法性与几何贴附辅助函数

它是体素路径过渡到几何路径的关键依赖。

6.5 busbar_planner.*

母线规划主控制器，负责：

• 维护规划配置与空间分析器
• 启发式搜索
• 粗路径引导
• 初始段候选生成
• 终点直连尝试
• 路径重建、合并与拉直

虽然当前主程序不直接走这条链路，但这套能力仍然保留在工程中。

6.6 coarse_planner.*

用于生成体素级粗路径，为细化搜索和后续启发式提供引导。

6.7 segment_generator.*

负责生成可行的后继段、做路径段级碰撞检测，并为母线规划提供候选动作。

6.8 space_analyzer.*

负责体素地图上的障碍、间隙、可达性和边界合法性判断，是两类算法的基础依赖模块。

---

七、当前主程序的输入输出

7.1 当前命令行形式

根据 main.cpp，当前程序实际使用的是飞行距离 API 调试模式：

program flight_api xsize ysize zsize offset_x offset_y offset_z voxel_size [threshold]

但由于当前 main() 中已经直接调用：

runFlightViaApi(argc - 1, argv + 1);

因此实际上外部传参时可以理解为：

main xsize ysize zsize offset_x offset_y offset_z voxel_size [threshold]

这是一种“开发期硬接线”状态，后续如果要恢复多模式入口，需要把 mode 分支重新打开。

7.2 主要输入参数

• 体素地图尺寸 xsize/y size/zsize
• 世界坐标偏移 offset_x/offset_y/offset_z
• 体素边长 voxel_size
• 距离阈值 threshold

7.3 主要输出内容

程序执行后会输出：

• 接口是否调用成功
• 运行耗时
• 世界坐标距离
• 起点体素坐标
• 终点体素坐标
• 路径点数量
• 每个路径点的世界坐标

并生成：

• flight_path_world.txt
• debug_output/flight_path_world.obj

---

八、数据结构与接口说明

8.1 IniInPutStruct

定义于 include/CommonStructs.hpp

主要用于描述三角面片数据，包含：

• 三个顶点坐标
• 三个顶点索引
• 面法向

它通常用于构造零件网格或全局场景网格输入。

8.2 DistanceResult

定义于 include/voxel_distance_calculator.hpp

主要字段包括：

• success
• distance
• start_point
• end_point
• path
• geom_start
• geom_end
• geom_path
• exceeded_threshold

这个结构同时承载了体素级与几何级结果。

8.3 BusbarPlanResult

定义于 include/busbar_planner.hpp

主要字段包括：

• success
• segments
• merged_segments
• raw_segments
• total_cost
• states_explored/generated/pruned
• coarse_path
• coarse_waypoints

用于表达母线规划过程与最终结果。

---

九、当前开发状态判断

结合代码现状，可以判断当前工程处于“算法研发与验证阶段”，主要特征如下：

• 可执行程序以调试飞行距离接口为主
• 代码中保留了完整的母线规划系统，但没有在当前入口完全打通
• voxel_distance_calculator.cpp 承担了大量细化、吸附、投影和优化逻辑
• 输出以日志、文本和 OBJ 为主，便于人工排查算法行为
• CMake 仍偏简单，没有把不同功能拆成独立 target

---

十、建议的后续整理方向

• 继续收敛端点吸附与几何投影逻辑
• 将粗搜索、细化、端点修正拆分成更小函数
• 为关键路径增加固定测试样例与日志开关