# 当前开发程序项目文档 ## 一、项目概述 本项目是一个基于体素空间与三角网格几何的三维路径/距离计算程序，当前代码库可以完成零部件之间的飞行距离与几何路径计算 从当前 `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 编译运行方式 ```bash 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`，当前按静态方式处理导出宏 --- ## 四、项目目录结构 ```text 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 核心算法子系统 #### 距离与几何路径计算 核心流程为： ```text 输入两个部件与场景数据 → 提取体素边界/障碍区域 → 粗级最短路搜索 → 必要时局部细化 → 世界坐标路径重建 → 端点几何投影/吸附/优化 → 输出距离与几何路径 ``` --- ## 六、关键模块说明 ### 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 调试模式： ```bash program flight_api xsize ysize zsize offset_x offset_y offset_z voxel_size [threshold] ``` 但由于当前 `main()` 中已经直接调用： ```cpp runFlightViaApi(argc - 1, argv + 1); ``` 因此实际上外部传参时可以理解为： ```bash 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](/abs/path/c:/Users/tangyd/Desktop/newcode/include/CommonStructs.hpp:1) 主要用于描述三角面片数据，包含： - 三个顶点坐标 - 三个顶点索引 - 面法向 它通常用于构造零件网格或全局场景网格输入。 ### 8.2 `DistanceResult` 定义于 [include/voxel_distance_calculator.hpp](/abs/path/c:/Users/tangyd/Desktop/newcode/include/voxel_distance_calculator.hpp:1) 主要字段包括： - `success` - `distance` - `start_point` - `end_point` - `path` - `geom_start` - `geom_end` - `geom_path` - `exceeded_threshold` 这个结构同时承载了体素级与几何级结果。 ### 8.3 `BusbarPlanResult` 定义于 [include/busbar_planner.hpp](/abs/path/c:/Users/tangyd/Desktop/newcode/include/busbar_planner.hpp:1) 主要字段包括： - `success` - `segments` - `merged_segments` - `raw_segments` - `total_cost` - `states_explored/generated/pruned` - `coarse_path` - `coarse_waypoints` 用于表达母线规划过程与最终结果。 --- ## 九、当前开发状态判断 结合代码现状，可以判断当前工程处于“算法研发与验证阶段”，主要特征如下： - 可执行程序以调试飞行距离接口为主 - 代码中保留了完整的母线规划系统，但没有在当前入口完全打通 - `voxel_distance_calculator.cpp` 承担了大量细化、吸附、投影和优化逻辑 - 输出以日志、文本和 OBJ 为主，便于人工排查算法行为 - CMake 仍偏简单，没有把不同功能拆成独立 target --- ## 十、建议的后续整理方向 - 继续收敛端点吸附与几何投影逻辑 - 将粗搜索、细化、端点修正拆分成更小函数 - 为关键路径增加固定测试样例与日志开关