全球机场跑道数据如何嵌入固件?ESP32-Plane-Radar数据构建脚本实战

原创2026-10-16 22:27:051,652 阅读

全球机场跑道数据如何嵌入固件?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),每帧刷新时的逻辑:

  1. 范围预检:按机场坐标计算与雷达中心的距离,超出取数半径(fetchRadiusKm())的机场整组跳过;
  2. 投影到屏幕:e7 值除以 1e7 还原角度,按"每纬度 ≈ 111 km + 经度乘 cos(纬度)修正"换算成屏幕像素,这就是小圆屏上近似平面投影;
  3. 圆形裁剪:跑道线段与雷达外圆求交(segmentIntersectsDisc),超出的部分截断,保证不画出圆外;
  4. 一次一标签:同一机场无论多少条跑道,最多打一个粗体 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)同样适用于任何需要在嵌入式设备里塞入大规模静态数据的场景。

登录后查看全文
ESP32-Plane-Radar