全球机场跑道数据如何嵌入固件?ESP32-Plane-Radar数据构建脚本实战
全球机场跑道数据如何嵌入固件?ESP32-Plane-Radar数据构建脚本实战
ESP32-Plane-Radar 是一个开源的 ESP32 固件项目,在 1.28 英寸圆形屏幕上用声呐风格显示 ADS-B 实时航班雷达。它的亮点之一,是把全球 1166 座大型机场的 1706 条跑道数据直接烧进固件:雷达画面里能实时画出发射范围内的机场跑道和 ICAO 代码(如 KJFK),而这一切都不依赖在线地图服务。本文将带你读懂这个数据构建脚本的完整工作流程。
一、为什么要把跑道数据"焊"进固件?
ESP32 没有 GPS 芯片、内存也很紧张,更不可能跑一个地图引擎。ESP32-Plane-Radar 的思路是:
- 离线数据:机场和跑道是静态数据,一次生成、永久可用,雷达画面不依赖网络请求地图瓦片;
- 极致压缩:经纬度不用
float,而是乘以 10⁷ 后的 32 位整数(业内称 e7 编码),跑道只用 6 个字段就能描述; - 按需绘制:固件运行时只画当前雷达量程内的跑道,内存占用几乎为零(仅两个布尔状态数组)。
最终效果就是 README.md 中描述的功能:Major airports from OurAirports (large_airport); all open runway strips in range (helipads excluded)。
二、数据构建脚本工作流程总览
整个"数据入库"只靠一个 Python 脚本:scripts/build_large_airports.py。流程分三步:
| 步骤 | 做什么 | 关键函数 |
|---|---|---|
| 1. 下载 | 拉取 OurAirports 开源数据仓库的 airports.csv 和 runways.csv |
fetch_csv() |
| 2. 清洗 | 只保留 large_airport 类型机场,剔除关闭跑道和直升机坪 |
build_dataset() |
| 3. 生成 | 渲染出 C++ 头文件 + 数据源文件,直接可参与编译 | render_header() / render_cpp() |
入口函数 main() 只有寥寥十几行:build_large_airports.py#L193-L206,执行完会打印生成了多少机场、多少条跑道。
1. 数据源:OurAirports 两张表
脚本从 OurAirports 公开数据集拉取两个 CSV:
airports.csv:全球机场,含 ICAO 代码、类型、经纬度;runways.csv:每条跑道的两端坐标(LE/HE)、长度(英尺)、关闭状态。
脚本只筛选 type == "large_airport" 且 ICAO 代码为 4 位的机场(build_large_airports.py#L68-L79),这就是"大型机场"名单的来源。
2. 清洗规则:e7 编码与直升机坪过滤
坐标编码——经纬度浮点数统一乘 10⁷ 转整数,省内存还避免浮点误差:
int32_t e7 = int(round(float(lat) * 1e7));
对应源码见 build_large_airports.py#L30-L33。
剔除直升机坪——is_helipad() 通过跑道两端代码(以 H 开头的标识)和长度双重判断,短于 2500 英尺的"跑道"基本判定为停机坪,避免雷达上出现密密麻麻的短线:build_large_airports.py#L47-L58。
长度换算——跑道长度从英尺转成米(× 0.3048),存入 16 位无符号整数,足够覆盖最长跑道(约 14 km)。
三、脚本产出的两个 C++ 文件
运行脚本后,会生成两个"只读"文件(文件头都标注 Generated — do not edit):
头文件:include/data/large_airports.h
定义了两个紧凑的 C 结构体和数组声明,结构体布局是理解整个方案的关键:
struct Airport {
char ident[5]; // ICAO 代码,如 "KJFK"
int32_t lat_e7; // 纬度 × 1e7
int32_t lon_e7; // 经度 × 1e7
};
struct Runway {
uint16_t airport_idx; // 指向 kAirports 的索引
int32_t le_lat_e7, le_lon_e7; // 跑道一端
int32_t he_lat_e7, he_lon_e7; // 跑道另一端
uint16_t length_m; // 跑道长度(米)
}
文件末尾的常量记录了数据集规模:large_airports.h#L24-L25
constexpr size_t kAirportCount = 1166;
constexpr size_t kRunwayCount = 1706;
设计巧思:Runway 不存机场代码字符串,只存一个 2 字节的数组索引 airport_idx,把重复的 ICAO 字符串压缩掉了——这是典型的"字典表 + 索引"省内存手法。
数据文件:src/data/large_airports_data.cpp
约 2900 行,全部是编译期确定的常量数组。前几条机场数据长这样:
const Airport kAirports[] = {
{"AGGH", -94280000, 1600549930},
{"AYNZ", -65679950, 1467265440},
...
以第一条为例:-94280000 ÷ 1e7 = -9.428°,1600549930 ÷ 1e7 ≈ 160.055°——这正是新西兰南岛的基督城机场。跑道数组则通过索引关联:
const Runway kRunways[] = {
{0, -94317398, 1600449982, -94242601, 1600639954, 2200},
索引 0 指向 AGGH,最后一段 2200 表示这条跑道长 2200 米。
四、如何更新机场跑道数据集?
机场数据会随时间小幅变化(新跑道、旧跑道关闭)。更新只需一条命令(README.md#L75):
python3 scripts/build_large_airports.py
⚠️ 注意:脚本需要联网从 OurAirports 拉取最新 CSV;生成的两个文件会整体覆盖仓库中现有的 include/data/large_airports.h 和 src/data/large_airports_data.cpp,所以这两个文件永远不要手改。
脚本运行后输出类似:
wrote large_airports.h + large_airports_data.cpp (1706 segments, 1166 airports)
随后正常 pio run -t upload 烧录,雷达里的跑道图层即为最新数据。
五、固件如何把这些数据画到雷达上?
消费端实现在 src/ui/runway_overlay.cpp 的 drawLargeAirportRunways()(runway_overlay.cpp#L251-L299),每帧刷新时的逻辑:
- 范围预检:按机场坐标计算与雷达中心的距离,超出取数半径(
fetchRadiusKm())的机场整组跳过; - 投影到屏幕:e7 值除以 1e7 还原角度,按"每纬度 ≈ 111 km + 经度乘 cos(纬度)修正"换算成屏幕像素,这就是小圆屏上近似平面投影;
- 圆形裁剪:跑道线段与雷达外圆求交(
segmentIntersectsDisc),超出的部分截断,保证不画出圆外; - 一次一标签:同一机场无论多少条跑道,最多打一个粗体 ICAO 代码标签(最多 32 个,防止小屏幕文字打架)。
开关在 WiFi 配置门户(plane-radar.local)的 Show airport runways 选项里,数据存于 NVS,重启后依然生效。
六、相关文件路径速查
| 文件 | 作用 |
|---|---|
| scripts/build_large_airports.py | 数据构建脚本(本文主角) |
| include/data/large_airports.h | 结构体定义 + 数据集常量(生成物) |
| src/data/large_airports_data.cpp | 机场/跑道常量数组(生成物) |
| src/ui/runway_overlay.cpp | 跑道渲染:投影、裁剪、标签 |
| include/ui/runway_overlay.h | 渲染接口声明 |
| include/config.h | 雷达默认位置等全局配置 |
小结
ESP32-Plane-Radar 用不到 250 行 Python,把全球机场跑道数据从"网络上的 CSV"变成了"固件里的两个 C++ 文件",核心经验有三点:静态数据预编译嵌入、e7 整数坐标压缩、索引代替字符串引用。这套"生成代码"的套路(generate, don't write)同样适用于任何需要在嵌入式设备里塞入大规模静态数据的场景。