Course from fixes only moves forward in time, from an anchor fix, and not for a standing contact; military contacts too

A fix that is not a second newer (a repeat, or an older position from another
feed) never gives a course, so a source switch cannot turn an aircraft
around. The course runs from an anchor fix that moves only when a course is
read, so frequent short steps add up, and a contact reported under 2 m/s
reads none. The helper moves to src/data/courseFromFixes.js and the military
records use it as well.
This commit is contained in:
Sameh Khamis committed 2026-11-15 11:19:58 -08:00
1 parent e08dcd0326
commit fc4db81d0b
9 files changed
+217 -92

No files matched your search

+1 -1
View File
@@ -1,3 +1,3 @@
### Fixed
- An aircraft whose feed sends neither a ground track nor a true heading now faces the way it moved since its last position, instead of north, so a taxiing aircraft no longer appears to move sideways or backwards.
- A civil or military aircraft whose feed sends neither a ground track nor a true heading now faces the way its newer positions went, instead of north, so a taxiing aircraft no longer appears to move sideways or backwards. An older position from another feed, or position noise on a parked aircraft, never turns it.
+9 -5
View File
@@ -1,10 +1,14 @@
# God's Eye View Current State
An aircraft faces its reported ground track, else its true heading (readsb
`true_heading`). With neither, it faces the way it moved since its last fix
when that is at least 30 m (`courseFromFixes`, `src/layers/flights/records.js`);
nearer fixes are position noise and keep its last course, and an aircraft with
no course at all faces north.
An aircraft (civil or military) faces its reported ground track, else its
true heading (readsb `true_heading`). With neither, it faces the way its own
fixes went (`courseFromFixes`, `src/data/courseFromFixes.js`): the course runs
from an anchor fix to the newest once they are 30 m apart, and the anchor then
moves on, so frequent fixes of a slow aircraft add up while position noise on
a parked one never makes a course. A fix that is not a second newer (a repeat,
or an older position from another feed) and one reported slower than 2 m/s
give no course and keep the last; an aircraft with no course at all faces
north.
Docker Compose mounts the checkout with the shared SELinux `:z` label so
containers can read it on enforcing SELinux hosts. The separate image-owned
+14 -6
View File
@@ -1592,7 +1592,8 @@
"src/time/worldClock.js",
"src/time/julian.js",
"src/data/planespottersPhoto.js",
"src/layers/flights/placed.js"
"src/layers/flights/placed.js",
"src/data/courseFromFixes.js"
],
"external": ["cesium"]
},
@@ -1668,7 +1669,9 @@
"src/ui/unitLabels.js",
"src/time/worldClock.js",
"src/time/julian.js",
"src/layers/flights/placed.js"
"src/layers/flights/placed.js",
"src/data/courseFromFixes.js",
"src/data/approxDistance.js"
],
"external": ["cesium"]
},
@@ -3839,7 +3842,8 @@
"src/data/openVesselPhoto.js",
"src/layers/vessels/photos.js",
"src/layers/flights/placed.js",
"src/data/placementProvider.js"
"src/data/placementProvider.js",
"src/data/courseFromFixes.js"
],
"external": [
"hls.js",
@@ -4565,7 +4569,8 @@
"src/layers/vessels/photos.js",
"src/data/openVesselPhoto.js",
"src/layers/flights/placed.js",
"src/data/placementProvider.js"
"src/data/placementProvider.js",
"src/data/courseFromFixes.js"
],
"external": [
"hls.js",
@@ -4851,7 +4856,8 @@
"src/data/aircraftEmergency.js",
"src/data/fleetModels.js",
"src/data/vesselTypes.js",
"src/data/fleetTrailAnchors.js"
"src/data/fleetTrailAnchors.js",
"src/data/courseFromFixes.js"
],
"external": []
},
@@ -4873,7 +4879,9 @@
"src/data/aircraftMeta.js",
"src/data/renderAltitude.js",
"src/data/aircraftClass.js",
"src/data/aircraftEmergency.js"
"src/data/aircraftEmergency.js",
"src/data/courseFromFixes.js",
"src/data/approxDistance.js"
],
"external": []
},
+61
View File
@@ -0,0 +1,61 @@
/**
* The course of a contact whose feed reports neither a ground track nor a
* true heading, read from its own fixes.
*
* The course runs from an anchor fix to the newest fix once they are at least
* COURSE_FROM_FIXES_MIN_M apart; the anchor then moves to the newest fix.
* Nearer fixes leave the anchor where it is, so frequent fixes of a slow
* aircraft still add up to a course, while position noise on a parked one
* never makes one. A fix that does not move time on by a second (a repeat, or
* an older position from another feed) never moves the anchor or gives a
* course, and neither does one reported slower than
* COURSE_FROM_FIXES_MIN_SPEED_MPS.
*/
import { approxDistanceKm } from './approxDistance.js';
/** Metres between fixes before a course is read from them. */
export const COURSE_FROM_FIXES_MIN_M = 30;
/** A contact reported slower than this (m/s) is standing: no course is read. */
export const COURSE_FROM_FIXES_MIN_SPEED_MPS = 2;
/**
* Initial great-circle bearing from one point to another, in degrees from
* true north (0–360), or null when either is missing or they are less than
* COURSE_FROM_FIXES_MIN_M apart.
*/
export function courseBetweenFixes(fromLat, fromLon, toLat, toLon) {
if (![fromLat, fromLon, toLat, toLon].every(Number.isFinite)) return null;
if (
approxDistanceKm(fromLat, fromLon, toLat, toLon) * 1000 <
COURSE_FROM_FIXES_MIN_M
)
return null;
const φ1 = (fromLat * Math.PI) / 180;
const φ2 = (toLat * Math.PI) / 180;
const Δλ = ((toLon - fromLon) * Math.PI) / 180;
const y = Math.sin(Δλ) * Math.cos(φ2);
const x =
Math.cos(φ1) * Math.sin(φ2) - Math.sin(φ1) * Math.cos(φ2) * Math.cos(Δλ);
return ((Math.atan2(y, x) * 180) / Math.PI + 360) % 360;
}
/**
* Read a course from a new fix.
* @param {{lat: number, lon: number, ms: number}|null|undefined} anchor The
* anchor fix kept from the last call (null at first).
* @param {{lat: number, lon: number, ms: number, speedMps?: number|null}} fix
* @returns {{courseDeg: number|null, anchor: {lat: number, lon: number, ms: number}|null}}
* The course, or null when none can be read, and the anchor to keep.
*/
export function courseFromFixes(anchor, { lat, lon, ms, speedMps = null }) {
const keep = anchor ?? null;
if (![lat, lon, ms].every(Number.isFinite))
return { courseDeg: null, anchor: keep };
if (!keep) return { courseDeg: null, anchor: { lat, lon, ms } };
if (ms < keep.ms + 1000) return { courseDeg: null, anchor: keep };
if (Number.isFinite(speedMps) && speedMps < COURSE_FROM_FIXES_MIN_SPEED_MPS)
return { courseDeg: null, anchor: keep };
const courseDeg = courseBetweenFixes(keep.lat, keep.lon, lat, lon);
if (courseDeg === null) return { courseDeg: null, anchor: keep };
return { courseDeg, anchor: { lat, lon, ms } };
}
+42
View File
@@ -0,0 +1,42 @@
import test from 'node:test';
import assert from 'node:assert/strict';
import { courseBetweenFixes, courseFromFixes } from './courseFromFixes.js';
test('course between fixes reads true bearings, across the antimeridian too', () => {
assert.ok(Math.abs(courseBetweenFixes(0, 0, 0, 0.01) - 90) < 1e-6);
assert.ok(Math.abs(courseBetweenFixes(0, 0, -0.01, 0) - 180) < 1e-6);
assert.ok(
Math.abs(courseBetweenFixes(0, 179.9997, 0, -179.9997) - 90) < 1e-6,
);
assert.equal(courseBetweenFixes(30, -97, 30.0001, -97), null, 'about 11 m');
assert.equal(courseBetweenFixes(null, 0, 0, 0.01), null);
});
test('the anchor moves only with a course, and only forward in time', () => {
let state = courseFromFixes(null, { lat: 0, lon: 0, ms: 0 });
assert.equal(state.courseDeg, null);
assert.deepEqual(state.anchor, { lat: 0, lon: 0, ms: 0 });
const first = state.anchor;
state = courseFromFixes(first, { lat: 0, lon: 0.0001, ms: 1000 });
assert.equal(state.courseDeg, null, '11 m: no course');
assert.equal(state.anchor, first, 'the anchor stays');
state = courseFromFixes(first, { lat: 0, lon: 0.0005, ms: 500 });
assert.equal(state.courseDeg, null, 'not a second newer');
state = courseFromFixes(first, {
lat: 0,
lon: 0.0005,
ms: 2000,
speedMps: 1,
});
assert.equal(state.courseDeg, null, 'standing');
state = courseFromFixes(first, {
lat: 0,
lon: 0.0005,
ms: 2000,
speedMps: 8,
});
assert.ok(Math.abs(state.courseDeg - 90) < 1e-6);
assert.deepEqual(state.anchor, { lat: 0, lon: 0.0005, ms: 2000 });
state = courseFromFixes(first, { lat: NaN, lon: 0, ms: 3000 });
assert.equal(state.anchor, first);
});
+10 -27
View File
@@ -1,4 +1,5 @@
import { stickyNumber, stickyText } from '../../data/aircraftMeta.js';
import { courseFromFixes } from '../../data/courseFromFixes.js';
import {
geoidSurfaceLastResortM,
pickRenderAltitudeM,
@@ -20,30 +21,6 @@ import {
} from './recordPolicy.js';
/** Source-independent aircraft metadata and bounded missing-poll retention. */
/** Metres a contact must move between fixes before its course is read from them. */
const COURSE_FROM_FIXES_MIN_M = 30;
/**
* The course from one fix to the next, in degrees from true north, or null
* when either is missing or they are less than COURSE_FROM_FIXES_MIN_M apart
* (position noise on a parked aircraft is not a course).
*/
export function courseFromFixes(fromLat, fromLon, toLat, toLon) {
if (![fromLat, fromLon, toLat, toLon].every(Number.isFinite)) return null;
if (
approxDistanceKm(fromLat, fromLon, toLat, toLon) * 1000 <
COURSE_FROM_FIXES_MIN_M
)
return null;
const φ1 = (fromLat * Math.PI) / 180;
const φ2 = (toLat * Math.PI) / 180;
const Δλ = ((toLon - fromLon) * Math.PI) / 180;
const y = Math.sin(Δλ) * Math.cos(φ2);
const x =
Math.cos(φ1) * Math.sin(φ2) - Math.sin(φ1) * Math.cos(φ2) * Math.cos(Δλ);
return ((Math.atan2(y, x) * 180) / Math.PI + 360) % 360;
}
export class FlightRecords {
constructor({
geoidHeight,
@@ -315,6 +292,12 @@ export class FlightRecords {
observation.positionTimeMs > 0
? observation.positionTimeMs
: this.now();
const course = courseFromFixes(prevMeta?.courseAnchor, {
lat,
lon,
ms: fixEpochMs,
speedMps: velocity,
});
const meta = {
sourceReference: observation.reference,
observedReceiptMs: this.now(),
@@ -334,13 +317,13 @@ export class FlightRecords {
wasAirborne: prevMeta?.wasAirborne === true || !onGround,
velocity: stickyNumber(velocity, prevMeta?.velocity, 0),
// With no reported track or true heading, a moving contact faces the
// way it moved since its last fix; a still one keeps its last course.
// way its fixes went (src/data/courseFromFixes.js); else the last one.
true_track: stickyNumber(
true_track,
courseFromFixes(prevMeta?.rawLat, prevMeta?.rawLon, lat, lon) ??
prevMeta?.true_track,
course.courseDeg ?? prevMeta?.true_track,
0,
),
courseAnchor: course.anchor,
category: cat,
// An adsbdb-enriched type code outranks the coarse OpenSky category.
klass: classifyAircraft({
+42 -52
View File
@@ -3,7 +3,7 @@ import assert from 'node:assert/strict';
import fs from 'node:fs';
import path from 'node:path';
import { fileURLToPath } from 'node:url';
import { FlightRecords, courseFromFixes } from './records.js';
import { FlightRecords } from './records.js';
const FLEET = path.resolve(
path.dirname(fileURLToPath(import.meta.url)),
@@ -320,58 +320,48 @@ test('a ground vehicle or station with no altitude stands on the ground; an airc
assert.equal(unloaded.onGround, false);
});
test('a contact reported with no course faces the way it moved since its last fix', () => {
test('a contact reported with no course faces the way its newer fixes went', () => {
const store = records();
// Taxiing south along a runway with no track or true heading reported.
store.receive(
observation({
latitude: 30.1908,
longitude: -97.6588,
courseDeg: null,
onGround: true,
speedMps: 8,
}),
view(),
const T = 1700000000000;
const taxi = (latitude, seconds, fields = {}) =>
store.receive(
observation({
latitude,
longitude: -97.6588,
courseDeg: null,
onGround: true,
speedMps: 8,
positionTimeMs: T + seconds * 1000,
...fields,
}),
view(),
);
const course = () => store.data.get('abc123').true_track;
taxi(30.1908, 0);
assert.equal(course(), 0, 'nothing known yet');
// Fixes a second apart, 8 m each: they add up until 30 m are covered.
taxi(30.19073, 1);
taxi(30.19066, 2);
assert.equal(course(), 0, 'under 30 m: still nothing');
taxi(30.19059, 3);
taxi(30.19052, 4);
assert.ok(Math.abs(course() - 180) < 0.1, 'southbound');
// An older fix from another feed, behind it: never turns it around.
taxi(30.1912, 2);
assert.ok(Math.abs(course() - 180) < 0.1, 'an older fix gives no course');
taxi(30.1901, 8);
assert.ok(Math.abs(course() - 180) < 0.1);
// Standing (reported under 2 m/s) with 40 m of position noise: kept.
taxi(30.18974, 12, { speedMps: 0.5, longitude: -97.6584 });
assert.ok(
Math.abs(course() - 180) < 0.1,
'a standing contact keeps its course',
);
assert.equal(store.data.get('abc123').true_track, 0, 'nothing known yet');
store.receive(
observation({
latitude: 30.1885,
longitude: -97.6588,
courseDeg: null,
onGround: true,
speedMps: 8,
}),
view(),
);
assert.ok(Math.abs(store.data.get('abc123').true_track - 180) < 0.1);
// Standing still (a metre of position noise): the last course is kept.
store.receive(
observation({
latitude: 30.18849,
longitude: -97.6588,
courseDeg: null,
onGround: true,
speedMps: 0,
}),
view(),
);
assert.ok(Math.abs(store.data.get('abc123').true_track - 180) < 0.1);
// A reported course always wins.
store.receive(
observation({
latitude: 30.188,
longitude: -97.6588,
courseDeg: 175,
onGround: true,
}),
view(),
);
assert.equal(store.data.get('abc123').true_track, 175);
});
test('course from fixes ignores position noise and reads east as 90', () => {
assert.equal(courseFromFixes(30, -97, 30.0001, -97), null, 'about 11 m');
assert.ok(Math.abs(courseFromFixes(0, 0, 0, 0.01) - 90) < 1e-6);
assert.equal(courseFromFixes(null, 0, 0, 0.01), null);
taxi(30.189, 16, { courseDeg: 175 });
assert.equal(course(), 175);
// A reset forgets where it was: it starts again from north.
store.reset();
taxi(30.188, 20);
assert.equal(course(), 0);
});
+15 -1
View File
@@ -1,5 +1,6 @@
import { pickRenderAltitudeM } from '../../data/renderAltitude.js';
import { stickyText, stickyNumber } from '../../data/aircraftMeta.js';
import { courseFromFixes } from '../../data/courseFromFixes.js';
import { classifyAircraft } from '../../data/aircraftClass.js';
import { aircraftEmergency } from '../../data/aircraftEmergency.js';
import {
@@ -175,6 +176,12 @@ export class MilitaryFlightRecords {
// last-known-good (bounded by the layer's eviction, which deletes the entry).
const stickyType = stickyText(type, prevMeta?.type);
const fixEpochMs = aircraft.positionTimeMs ?? observedAtMs;
const course = courseFromFixes(prevMeta?.courseAnchor, {
lat,
lon,
ms: fixEpochMs,
speedMps: aircraft.speedMps,
});
const meta = {
sourceReference: aircraft.reference,
observedReceiptMs: this.now(),
@@ -206,7 +213,14 @@ export class MilitaryFlightRecords {
onGround ? 0 : prevMeta?.speedMps,
0,
),
track: stickyNumber(aircraft.courseDeg, prevMeta?.track, 0),
// With no reported track or true heading, a moving contact faces the
// way its fixes went (src/data/courseFromFixes.js); else the last one.
track: stickyNumber(
aircraft.courseDeg,
course.courseDeg ?? prevMeta?.track,
0,
),
courseAnchor: course.anchor,
// Analyst seam (additive): sticky like the other kinematics.
verticalRateMps: stickyNumber(
verticalRateMps,
+23
View File
@@ -269,3 +269,26 @@ test('a repeated military fix time marks the contact as not updated; removal is
records.forget('aaa001');
assert.equal(records.fixRepeated.has('aaa001'), false);
});
test('a military contact reported with no course faces the way its newer fixes went', () => {
const records = store();
const T = 1700000000000;
const taxi = (latitude, seconds) =>
records.receive(
observation({
latitude,
onGround: true,
baroAltitudeM: null,
courseDeg: null,
speedMps: 8,
positionTimeMs: T + seconds * 1000,
}),
context({ observedAtMs: T + seconds * 1000 + 500 }),
);
assert.equal(taxi(39, 0).meta.track, 0);
assert.ok(Math.abs(taxi(38.9995, 5).meta.track - 180) < 0.1);
assert.ok(
Math.abs(taxi(39.002, 3).meta.track - 180) < 0.1,
'an older fix gives no course',
);
});