Ultrafeeder GPS 移动检测底层:distance-in-meters.c 球面距离算法源码解读
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,容器就能持续读到最新的经纬度。一旦检测到你搬家了(移动超过阈值),它会做两件事:
- 杀掉正在运行的 mlat-client 实例(它们还绑着旧坐标);
- 等你停稳一段时间(默认 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 秒)跑一轮:
- 取新坐标:
check_gpsd函数(第 59-79 行)用jq从/run/readsb/gpsd.json读出lat、lon、altMSL,任一为 null 就视为"暂无定位"; - 算距离:
distance="$(distance "$old_lat" "$old_lon" "$new_lat" "$new_lon")"(第 348 行); - 判移动:脚本用 bash 的
${distance%%.*}截掉小数部分取整米数,与GPSD_MIN_DISTANCE比较。超过阈值则判定"接收机移动了":- 打印
Receiver moved X meters; pkill掉所有 mlat-client 实例(第 357 行);- 把新坐标写入
old_lat/old_lon,并把"稳定计时器"清零;
- 打印
- 判停稳:没超阈值就累加
no_movement计数器,直到达到GPSD_MLAT_WAIT(最小 90 秒),才打印Receiver stationary - starting all mlat-clients with new location,持久化位置并重启(第 380-383 行); - 换坐标重启:重启时并不重发完整配置,而是用
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 章节。