Ultrafeeder GPS 移动检测底层:distance-in-meters.c 球面距离算法源码解读

原创2026-11-16 16:52:131,612 阅读

Ultrafeeder GPS 移动检测底层:distance-in-meters.c 球面距离算法源码解读

docker-adsb-ultrafeeder 是一款把 readsb、tar1090、graphs1090、mlat-hub 等整合在一起的 ADS-B 一体化容器。它的 GPS 移动检测功能背后,是一个不到 70 行的 C 小程序 distance-in-meters.c——用经典的 Haversine 球面距离公式,判断天线接收机是否真的"移动了",并据此自动重启 mlat-client。本文带你完整解读这段源码及其调用链路。

一、这个小工具在 Ultrafeeder 里扮演什么角色 📡

Ultrafeeder 支持"带着设备移动"的场景:只要主机上运行了 gpsd,容器就能持续读到最新的经纬度。一旦检测到你搬家了(移动超过阈值),它会做两件事:

  1. 杀掉正在运行的 mlat-client 实例(它们还绑着旧坐标);
  2. 等你停稳一段时间(默认 90 秒),再用新坐标把所有 mlat-client 拉起来。

而"移动了多少米"这个判断,就交给 distance 命令——它由 distance-in-meters.c 编译而来。整个流程是:

gpsd(主机) → readsb 写出 /run/readsb/gpsd.json
           → mlat-client 脚本周期性读取新旧坐标
           → 调用 distance 旧纬度 旧经度 新纬度 新经度
           → 输出米数,与 GPSD_MIN_DISTANCE 比较 → 决定是否重启

二、编译与打包:一个零依赖的静态二进制 📦

在 Dockerfile 第 10 行,构建阶段用一条命令把它编译出来:

gcc -static /app/downloads/distance-in-meters.c -o /distance -lm -O2

几个细节值得注意:

  • -static:静态链接,不依赖镜像里任何动态库。基础镜像是精简的 tar1090 镜像,静态二进制放进去"开箱即用";
  • -lm:链接数学库(sin、cos、atan2、sqrt 都在里面);
  • -O2:开启常规优化,对这种纯计算程序效果显著。

随后 Dockerfile 第 41 行将产物拷贝到 /usr/local/bin/distance,成为容器内的系统命令。整个小程序的"一生"就体现在这两行里,非常典型地展示了"小工具进容器"的最佳实践。

三、源码逐段解读:Haversine 球面距离公式

3.1 经纬度差值与弧度转换

球面三角计算一律用弧度,所以 distance() 函数 一上来就做了四步换算(第 41-44 行):

  • 起点纬度 lat_a、终点纬度 lat_b 各自乘以 PI / 180 转为弧度;
  • 同时算出纬度差 lat_delta 与经度差 lon_delta(也转弧度)。

PI 定义在 第 35 行,精度取到 8 位小数,对米级距离计算绰绰有余。

3.2 核心:Haversine 公式的 3 行实现

真正的球面距离计算只有三行(第 46-49 行):

double a = sin(lat_delta / 2.0) * sin(lat_delta / 2.0)
         + cos(lat_a_scaled) * cos(lat_b_scaled)
         * sin(lon_delta / 2.0) * sin(lon_delta / 2.0);
double c = 2.0 * atan2(sqrt(a), sqrt(1.0 - a));
return 6372797.56085 * c;

这正是大名鼎鼎的 Haversine(半正矢)公式,拆开看:

步骤 代码 含义
① a = sin²(Δφ/2) + cos φ₁·cos φ₂·sin²(Δλ/2) 计算两点的 Haversine 中间值 a
② c = 2·atan2(√a, √(1−a)) 求出球心角(弧长对应的角,弧度制)
③ 6372797.56085 × c 乘以地球半径,得到大圆距离(米)

三个小巧思:

  • atan2 而非 asin:数值上更稳定,避免 a 因浮点误差越界导致 asin 出错;
  • 半径取 6372797.56085 米:这是 IUGG 推荐的地球平均半径(约 6372.8 km),而非更常见的 6371 km,精度更贴合"经纬网格上的平均球";
  • 只测"大圆距离":即球面上两点间的最短路径。与严格的 WGS-84 椭球模型相比误差在 0.3% 左右——对于"判断是否移动了 20 米"这种用途完全足够,而且计算成本极低,只需几次三角函数。

这段算法移植自 Chris Veness 的经典 JavaScript 实现(MIT 许可,见 文件头注释),由 JohnEx 和 kx1t 改写为 C 语言,方便在容器内零依赖运行。

3.3 命令行入口:4 个参数,输出一个米数

main 函数 简洁到只有 16 行:

  • 用法:distance lat1 lon1 lat2 lon2,参数不足时打印 Usage: distance lat1 lon1 lat2 lon2 并以状态码 1 退出;
  • 用 atof() 把 4 个参数字符串转成浮点数;
  • 调用 distance() 后,通过 printf("%f\n", d) 把以米为单位的距离打到标准输出。

没有单位后缀、没有多余格式——这是刻意设计:输出就是给 shell 脚本"吃"的纯数字。

四、脚本侧:distance 命令如何驱动移动检测 🔄

调用方在 rootfs/etc/s6-overlay/scripts/mlat-client 脚本中,核心循环(第 341-385 行)每 GPSD_CHECK_INTERVAL(默认 30 秒)跑一轮:

  1. 取新坐标:check_gpsd 函数(第 59-79 行)用 jq 从 /run/readsb/gpsd.json 读出 lat、lon、altMSL,任一为 null 就视为"暂无定位";
  2. 算距离:distance="$(distance "$old_lat" "$old_lon" "$new_lat" "$new_lon")"(第 348 行);
  3. 判移动:脚本用 bash 的 ${distance%%.*} 截掉小数部分取整米数,与 GPSD_MIN_DISTANCE 比较。超过阈值则判定"接收机移动了":
    • 打印 Receiver moved X meters;
    • pkill 掉所有 mlat-client 实例(第 357 行);
    • 把新坐标写入 old_lat/old_lon,并把"稳定计时器"清零;
  4. 判停稳:没超阈值就累加 no_movement 计数器,直到达到 GPSD_MLAT_WAIT(最小 90 秒),才打印 Receiver stationary - starting all mlat-clients with new location,持久化位置并重启(第 380-383 行);
  5. 换坐标重启:重启时并不重发完整配置,而是用 sed 把命令串里的 --lat、--lon、--alt 数值原地替换成新 GPS 值(第 404-407 行),非常轻量。

另外,启动时脚本会尝试从 /var/globe_history/gpsd_last_location 恢复上次的坐标作为 old_lat/old_lon 初值(第 84-91 行),避免重启容器后把"原地"误判成"从 (0,0) 移动了几万公里"。

五、关键参数速查表 ⚙️

这三个环境变量均可在 docker-compose.yml 的 environment 中设置(详见 README.md):

环境变量 作用 默认值 / 限制
GPSD_MIN_DISTANCE 判定"移动了"的最小距离(米) 20,最大 40 米(强制封顶)
GPSD_MLAT_WAIT 停稳多久后重启 mlat-client(秒) 90,最小 90 秒
GPSD_CHECK_INTERVAL 位置检测周期(秒) 30,最小 5 秒

之所以给 GPSD_MIN_DISTANCE 设置 40 米上限,正是 Haversine 精度与 GPS 定位误差共同决定的:普通消费级 GPS 的抖动就有几米到十几米,阈值过大无意义,过小则会天天"误判搬家"。

六、小结

distance-in-meters.c 是典型的"小代码大作用":

  • 69 行源码,实现教科书级的 Haversine 球面距离算法,用 atan2 与 IUGG 平均半径保证了稳定与精度;
  • 静态编译成零依赖二进制,随镜像分发,运行成本几乎为零;
  • 与 mlat-client 脚本的状态机式轮询配合,构成了完整、防抖、可持久化的 GPS 移动检测闭环。

如果你想深入阅读,建议按这个顺序:downloads/distance-in-meters.c → Dockerfile → rootfs/etc/s6-overlay/scripts/mlat-client → README.md 的 GPSD 章节。

登录后查看全文
docker-adsb-ultrafeeder