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 编译运行方式

```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

---

## 十、建议的后续整理方向

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