diff --git a/changelog.d/1753-course-from-fixes.md b/changelog.d/1753-course-from-fixes.md new file mode 100644 index 000000000..1c42498e3 --- /dev/null +++ b/changelog.d/1753-course-from-fixes.md @@ -0,0 +1,3 @@ +### Fixed + +- 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. diff --git a/docs/CURRENT-STATE.md b/docs/CURRENT-STATE.md index 53a0e6d94..7d6fc3698 100644 --- a/docs/CURRENT-STATE.md +++ b/docs/CURRENT-STATE.md @@ -1,5 +1,15 @@ # God's Eye View Current State +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. + While anything moves (a layer in motion, the camera, a followed contact), the globe draws at the display's own refresh rate; there is no fixed 60 FPS cap. The idle render governor (`src/renderGovernor.js`) caps a parked scene at diff --git a/scripts/package-boundaries.json b/scripts/package-boundaries.json index e400c97c7..ec76dd86f 100644 --- a/scripts/package-boundaries.json +++ b/scripts/package-boundaries.json @@ -1593,7 +1593,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"] }, @@ -1669,7 +1670,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"] }, @@ -3841,6 +3844,7 @@ "src/layers/vessels/photos.js", "src/layers/flights/placed.js", "src/data/placementProvider.js", + "src/data/courseFromFixes.js", "src/time/frameWait.js" ], "external": [ @@ -4568,6 +4572,7 @@ "src/data/openVesselPhoto.js", "src/layers/flights/placed.js", "src/data/placementProvider.js", + "src/data/courseFromFixes.js", "src/time/frameWait.js" ], "external": [ @@ -4854,7 +4859,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": [] }, @@ -4876,7 +4882,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": [] }, diff --git a/src/data/courseFromFixes.js b/src/data/courseFromFixes.js new file mode 100644 index 000000000..f82eb4d89 --- /dev/null +++ b/src/data/courseFromFixes.js @@ -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 } }; +} diff --git a/src/data/courseFromFixes.test.mjs b/src/data/courseFromFixes.test.mjs new file mode 100644 index 000000000..e12b1cdd4 --- /dev/null +++ b/src/data/courseFromFixes.test.mjs @@ -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); +}); diff --git a/src/layers/flights/records.js b/src/layers/flights/records.js index 02c50f3d8..9dbe08de6 100644 --- a/src/layers/flights/records.js +++ b/src/layers/flights/records.js @@ -1,4 +1,5 @@ import { stickyNumber, stickyText } from '../../data/aircraftMeta.js'; +import { courseFromFixes } from '../../data/courseFromFixes.js'; import { geoidSurfaceLastResortM, pickRenderAltitudeM, @@ -291,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(), @@ -309,7 +316,14 @@ export class FlightRecords { // applies to contacts that actually flew this session. wasAirborne: prevMeta?.wasAirborne === true || !onGround, velocity: stickyNumber(velocity, prevMeta?.velocity, 0), - true_track: stickyNumber(true_track, prevMeta?.true_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. + true_track: stickyNumber( + 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({ diff --git a/src/layers/flights/records.test.mjs b/src/layers/flights/records.test.mjs index cafe55cbf..1aaddcf5b 100644 --- a/src/layers/flights/records.test.mjs +++ b/src/layers/flights/records.test.mjs @@ -319,3 +319,49 @@ test('a ground vehicle or station with no altitude stands on the ground; an airc ).meta; assert.equal(unloaded.onGround, false); }); + +test('a contact reported with no course faces the way its newer fixes went', () => { + const store = records(); + 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', + ); + // A reported course always wins. + 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); +}); diff --git a/src/layers/military/records.js b/src/layers/military/records.js index 72ffd2677..8a040b97e 100644 --- a/src/layers/military/records.js +++ b/src/layers/military/records.js @@ -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, diff --git a/src/layers/military/records.test.mjs b/src/layers/military/records.test.mjs index 3d72aed21..bbea594d8 100644 --- a/src/layers/military/records.test.mjs +++ b/src/layers/military/records.test.mjs @@ -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', + ); +});