diff --git a/changelog.d/1795-trail-follows-placed-aircraft.md b/changelog.d/1795-trail-follows-placed-aircraft.md new file mode 100644 index 0000000000..3e0d89cc13 --- /dev/null +++ b/changelog.d/1795-trail-follows-placed-aircraft.md @@ -0,0 +1,3 @@ +- The followed aircraft's trail runs to where the aircraft is drawn when an + application places live contacts, instead of ending far behind it, and its + head no longer drops out after the page loads (Sameh Khamis, @samehkhamis, #1795). diff --git a/docs/CURRENT-STATE.md b/docs/CURRENT-STATE.md index ea080d4c94..3ef01208a3 100644 --- a/docs/CURRENT-STATE.md +++ b/docs/CURRENT-STATE.md @@ -408,7 +408,11 @@ ground state) and draws a contact where `place` puts it: position, height (the layer's own when none is given), course and speed. A null answer, a provider that throws, a kind it leaves out, or no provider at all keeps the layer's own motion, unchanged; following the world clock, the layers never -ask it. Transit and rail vehicles a provider places are advanced every frame +ask it. A tracked aircraft or military aircraft the provider places keeps its +trail joined to it: the trail runs up to the time read off its own reports +where the aircraft is drawn, not the layer's display delay, so it neither +stops short of the aircraft nor runs on ahead of it, and it is drawn from the +first report behind the aircraft. Transit and rail vehicles a provider places are advanced every frame in view while their placed position changes; one it holds still lets the render loop idle and is asked again each second, moving on once its placement does. A placed transit vehicle is drawn at its placed point, and a placed diff --git a/src/data/trailContinuity.js b/src/data/trailContinuity.js index d50c503cc4..a18a4e32b3 100644 --- a/src/data/trailContinuity.js +++ b/src/data/trailContinuity.js @@ -293,6 +293,68 @@ export function trailHeadCurvePoints(fixes, count, displayMs) { return curvePoints(curve, last.timeMs, displayMs); } +/** @constant {number} How far back from the newest report `trailTimeAt` looks for the aircraft (ms). */ +export const TRAIL_TIME_AT_SEARCH_MS = 15 * 60_000; + +/** + * The time on the trail at which `position` lies: the pair of consecutive + * reports, one path, whose straight line passes closest to it (the newest + * pair when two are as close), and the time that far along between them. + * Past the newest report the time runs on at that pair's pace; before the + * oldest pair it runs back the same way. Only pairs ending within + * TRAIL_TIME_AT_SEARCH_MS of the newest report are looked at, so a loop + * flown earlier is not mistaken for where the aircraft is now. + * + * This is how the trail finds the time an aircraft placed by someone else + * (a host-supplied placement) is drawn at: whatever delay that placement + * draws with, the trail then ends where the aircraft is drawn. + * @param {object[]} fixes - The trail, chronological. + * @param {{x: number, y: number, z: number}|null|undefined} position - Where the aircraft is drawn. + * @returns {number} Epoch ms; NaN when no pair of reports is one path. + */ +export function trailTimeAt(fixes, position) { + if (!position || fixes.length < 2) return NaN; + const newestMs = fixes[fixes.length - 1].timeMs; + let bestM = Infinity; + let bestMs = NaN; + for (let i = fixes.length - 1; i > 0; i--) { + const b = fixes[i]; + if (newestMs - b.timeMs > TRAIL_TIME_AT_SEARCH_MS) break; + const a = fixes[i - 1]; + if (!a.position || !b.position || b.breakBefore) continue; + const spanMs = b.timeMs - a.timeMs; + if (!(spanMs > 0)) continue; + const dx = b.position.x - a.position.x; + const dy = b.position.y - a.position.y; + const dz = b.position.z - a.position.z; + const lengthSq = dx * dx + dy * dy + dz * dz; + let u = + lengthSq > 0 + ? ((position.x - a.position.x) * dx + + (position.y - a.position.y) * dy + + (position.z - a.position.z) * dz) / + lengthSq + : 0; + // Only the newest pair runs on past its end, only the oldest looked at + // back past its start; the rest are their own segment. + const newest = i === fixes.length - 1; + const oldest = + i === 1 || newestMs - fixes[i - 1].timeMs > TRAIL_TIME_AT_SEARCH_MS; + const along = Math.min(Math.max(u, 0), 1); + const offM = Math.hypot( + position.x - (a.position.x + along * dx), + position.y - (a.position.y + along * dy), + position.z - (a.position.z + along * dz), + ); + if (!(offM < bestM)) continue; + if (!(u > 1 && newest)) u = Math.min(u, 1); + if (!(u < 0 && oldest)) u = Math.max(u, 0); + bestM = offM; + bestMs = a.timeMs + u * spanMs; + } + return bestMs; +} + /** * Draw body segments. A trail without breaks support draws only the newest * segment, never a line across a break. diff --git a/src/layers/flights/motion.js b/src/layers/flights/motion.js index 6094e9c07c..a429d0237e 100644 --- a/src/layers/flights/motion.js +++ b/src/layers/flights/motion.js @@ -452,6 +452,8 @@ export function createMotion({ const sameTrack = flightState._drReconcileValid && flightState._drReconcileIcao === icao24; const raw = _deadReckon(icao24, flightState._scratchDrRaw); + flightState._cachedDRPlaced = + Boolean(raw) && flightState._drSpeedPlaced === true; flightState._cachedDRCourse = flightState._drCourseDeg; flightState._cachedDRSpeedMps = flightState._drSpeedMps; flightState._cachedDRHold = flightState._drCourseHold; @@ -597,6 +599,16 @@ export function createMotion({ * against the now-stable plane (the model's jitter fix, resurfacing in the labels). Returns null when * there's no valid fix for the tracked aircraft, so callers fall back to the icon position. */ + /** Whether a host-supplied placement placed the tracked aircraft where + * `_trackedDisplayCached` holds it this frame, rather than this layer's + * own motion at its display delay. */ + + function _trackedPlaced() { + return ( + _trackedDisplayCached() !== null && flightState._cachedDRPlaced === true + ); + } + function _trackedDisplayCached() { return flightState._drReconcileValid && flightState._drReconcileIcao === flightState._trackedIcao @@ -1217,6 +1229,7 @@ export function createMotion({ _trackedFocusSizePx, _trackedDisplayPosition, _trackedDisplayCached, + _trackedPlaced, _trackedVisualCached, _trackedModelCenterWorld, _trackedModelEnvelopeM, diff --git a/src/layers/flights/state.js b/src/layers/flights/state.js index e0e8d7ec0d..c0e23de720 100644 --- a/src/layers/flights/state.js +++ b/src/layers/flights/state.js @@ -272,6 +272,12 @@ export function createFlightState({ source, services }) { flightState._drSpeedPlaced = false; + /** Sibling of `_cachedDRPosition`: whether a host-supplied placement placed + * it (`_drSpeedPlaced` as the tracked aircraft was drawn), so its trail + * ends where it is drawn rather than at the layer's display delay. */ + + flightState._cachedDRPlaced = false; + flightState._drCourseHold = false; /** Sibling scratch: whether the position `_deadReckon` just returned came from diff --git a/src/layers/flights/tracking.js b/src/layers/flights/tracking.js index 1d775c2166..5d371ec77e 100644 --- a/src/layers/flights/tracking.js +++ b/src/layers/flights/tracking.js @@ -50,6 +50,7 @@ import { trailBodySegments, trailHeadCurvePoints, trailHeadStartFix, + trailTimeAt, } from '../../data/trailContinuity.js'; import { roundHeadingDegrees } from '../../data/headingDegrees.js'; import { entityRecord } from '../../data/entityRecords.js'; @@ -396,12 +397,46 @@ export function createTracking({ ); } - /** Reports at or before the time the aircraft is drawn (now − the display delay). */ + /** Reports at or before the time the aircraft is drawn (`_trailDisplayMs`). */ function _trailBodyCountNow() { - return trailBodyCount( + return trailBodyCount(flightState._trailFixes, _trailDisplayMs()); + } + + /** + * The time on its trail at which a host-supplied placement draws the + * aircraft, read off the trail where it is drawn (`trailTimeAt`): such a + * placement draws at a delay of its own, not this layer's. NaN when this + * layer's own motion draws it, or the trail has no pair to read. + * @returns {number} Epoch ms or NaN. + */ + function _placedTrailMs() { + if (!parts.motion._trackedPlaced?.()) return NaN; + return trailTimeAt( flightState._trailFixes, - flightState.now() - displayDelayMs(flightState), + parts.motion._trackedDisplayCached(), + ); + } + + /** + * The time the trail runs up to: the time the aircraft is drawn at, now − + * the display delay, or where a placement draws it. Otherwise the trail + * ends short of a placed aircraft, or runs on ahead of it. + * @returns {number} Epoch ms. + */ + function _trailDisplayMs() { + const placedMs = _placedTrailMs(); + return Number.isFinite(placedMs) + ? placedMs + : flightState.now() - displayDelayMs(flightState); + } + + /** Whether the trail holds no report behind the aircraft yet: this + * layer's own motion draws it before its oldest fix. Never for an + * aircraft a placement draws: its trail is read where it is drawn. */ + function _trailWarmingUp() { + return ( + !Number.isFinite(_placedTrailMs()) && parts.motion._isTrackWarmingUp() ); } @@ -418,7 +453,7 @@ export function createTracking({ if ( !flightState._trackedIcao || !flightState._trailFixes.length || - parts.motion._isTrackWarmingUp() + _trailWarmingUp() ) return []; const head = @@ -441,7 +476,7 @@ export function createTracking({ trailHeadCurvePoints( flightState._trailFixes, flightState._trailBodyCount, - flightState.now() - displayDelayMs(flightState), + _trailDisplayMs(), ), head, parts.motion._trackedModelCenterWorld(), diff --git a/src/layers/flights/trail.test.mjs b/src/layers/flights/trail.test.mjs index ad3cf8e46a..d091431024 100644 --- a/src/layers/flights/trail.test.mjs +++ b/src/layers/flights/trail.test.mjs @@ -4,7 +4,12 @@ import * as Cesium from 'cesium'; import { createFlightState } from './state.js'; import { createTracking } from './tracking.js'; import { TRAIL_MAX_POINTS } from './policy.js'; -import { trailHeadJoins, trailPairBreaks } from '../../data/trailContinuity.js'; +import { + insertTrailFix, + trailHeadJoins, + trailPairBreaks, + trailTimeAt, +} from '../../data/trailContinuity.js'; const MINUTE = 60_000; const HOUR = 60 * MINUTE; @@ -92,6 +97,8 @@ function trackedHarness({ nowMs, floor, head = null, + placed = false, + warmingUp = false, } = {}) { const trail = recordingTrail(); const svc = services({ trails: trail, floor }); @@ -122,7 +129,9 @@ function trackedHarness({ services: svc, parts: { motion: { - _isTrackWarmingUp: () => false, + _isTrackWarmingUp: () => warmingUp, + _trackedPlaced: () => placed, + _trackedDisplayCached: () => head, _trackedTrailCached: () => head, _trackedDisplayPosition: () => head, _trackedModelCenterWorld: () => null, @@ -410,3 +419,136 @@ test('every waypoint of a 24 h history survives, and the trail stays within TRAI // The oldest go first: the newest live fix is still the last point. assert.equal(fixes[fixes.length - 1].timeMs, liveStart); }); + +/** A trail of `count` reports one minute apart flying east from (50, 1). */ +function eastTrail(t0, count) { + const fixes = []; + for (let i = 0; i < count; i++) + insertTrailFix( + fixes, + Cesium.Cartesian3.fromDegrees(1 + i * 0.12, 50, 10_000), + t0 + i * MINUTE, + TRAIL_MAX_POINTS, + ); + return fixes; +} + +test('the time on the trail is read where the aircraft is drawn', () => { + const t0 = Date.UTC(2026, 10, 8, 0, 0); + const fixes = eastTrail(t0, 4); + const at = (lon) => + trailTimeAt(fixes, Cesium.Cartesian3.fromDegrees(lon, 50, 10_000)); + // Halfway between the second and third reports. + assert.ok(Math.abs(at(1.18) - (t0 + 1.5 * MINUTE)) < 2_000); + // On a report. + assert.ok(Math.abs(at(1.24) - (t0 + 2 * MINUTE)) < 2_000); + // Past the newest report the time runs on; before the oldest it runs back. + assert.ok(Math.abs(at(1.42) - (t0 + 3.5 * MINUTE)) < 2_000); + assert.ok(Math.abs(at(0.94) - (t0 - 0.5 * MINUTE)) < 2_000); + // Nothing to read without a pair of reports, or without a position. + assert.ok(Number.isNaN(trailTimeAt(fixes.slice(0, 1), fixes[0].position))); + assert.ok(Number.isNaN(trailTimeAt(fixes, null))); +}); + +test('the time on the trail is never read across a break', () => { + const t0 = Date.UTC(2026, 10, 8, 0, 0); + const fixes = eastTrail(t0, 2); + // An hour later, far on: a new segment. + insertTrailFix( + fixes, + Cesium.Cartesian3.fromDegrees(20, 50, 10_000), + t0 + HOUR, + TRAIL_MAX_POINTS, + ); + insertTrailFix( + fixes, + Cesium.Cartesian3.fromDegrees(20.12, 50, 10_000), + t0 + HOUR + MINUTE, + TRAIL_MAX_POINTS, + ); + assert.equal(fixes[2].breakBefore, true); + // Halfway along the gap is not on the trail: it is read on the newest pair. + const at = trailTimeAt(fixes, Cesium.Cartesian3.fromDegrees(10, 50, 10_000)); + assert.ok(at <= t0 + HOUR, `read ${at - t0} ms in, across the break`); +}); + +test('a placed aircraft drawn ahead of the display delay keeps its trail joined to it', () => { + const t0 = Date.UTC(2026, 10, 8, 0, 0); + const liveFixes = [0, 1, 2, 3].map((i) => ({ + timeMs: t0 + i * MINUTE, + lat: 50, + lon: 1 + i * 0.12, + })); + // The layer's own delay puts the aircraft before its first fix (warming + // up), but the placement draws it between the third and fourth reports. + const near = Cesium.Cartesian3.fromDegrees(1.3, 50, 10_000); + const placed = trackedHarness({ + liveFixes, + nowMs: t0 + 3.5 * MINUTE, + head: near, + placed: true, + warmingUp: true, + }); + placed.flightState._displayDelay = { currentMs: 10 * MINUTE }; + placed.tracking._startTrail('abc123'); + // The body runs to the last report behind the aircraft, none ahead of it. + assert.deepEqual( + placed.trail.last().map((segment) => segment.length > 0), + [true], + ); + const body = placed.trail.last()[0]; + assert.ok( + Cesium.Cartesian3.distance( + body[body.length - 1], + Cesium.Cartesian3.fromDegrees(1.24, 50, 10_000), + ) < 1, + ); + // The head joins it to the aircraft. + const drawn = headPositions(placed); + assert.ok(drawn.length >= 2); + assert.ok(Cesium.Cartesian3.distance(drawn[0], body[body.length - 1]) < 1); + assert.ok(Cesium.Cartesian3.distance(drawn[drawn.length - 1], near) < 1e-6); + + // The layer's own motion, warming up, draws no head and no body. + const own = trackedHarness({ + liveFixes, + nowMs: t0 + 3.5 * MINUTE, + head: near, + warmingUp: true, + }); + own.flightState._displayDelay = { currentMs: 10 * MINUTE }; + own.tracking._startTrail('abc123'); + assert.deepEqual(own.trail.last(), []); + assert.deepEqual(headPositions(own), []); +}); + +test('a placed aircraft drawn behind the display delay has no trail ahead of it', () => { + const t0 = Date.UTC(2026, 10, 8, 0, 0); + const liveFixes = [0, 1, 2, 3].map((i) => ({ + timeMs: t0 + i * MINUTE, + lat: 50, + lon: 1 + i * 0.12, + })); + // The layer's delay would draw every report; the placement holds the + // aircraft between the first and second. + const behind = Cesium.Cartesian3.fromDegrees(1.06, 50, 10_000); + const { trail, tracking, flightState } = trackedHarness({ + liveFixes, + nowMs: t0 + 4 * MINUTE, + head: behind, + placed: true, + }); + flightState._displayDelay = { currentMs: 0 }; + tracking._startTrail('abc123'); + // One report behind it: no line yet, and nothing ahead of the aircraft. + assert.deepEqual(trail.last(), []); + const drawn = headPositions({ tracking }); + assert.equal(drawn.length, 2); + assert.ok( + Cesium.Cartesian3.distance( + drawn[0], + Cesium.Cartesian3.fromDegrees(1, 50, 10_000), + ) < 1, + ); + assert.ok(Cesium.Cartesian3.distance(drawn[1], behind) < 1e-6); +}); diff --git a/src/layers/military/motion.js b/src/layers/military/motion.js index bd9385c6bc..170d7e4db2 100644 --- a/src/layers/military/motion.js +++ b/src/layers/military/motion.js @@ -349,6 +349,8 @@ export function createMotion({ const sameTrack = flightState._drReconcileValid && flightState._drReconcileIcao === icao24; const raw = _deadReckon(icao24, flightState._scratchDrRaw); + flightState._cachedDRPlaced = + Boolean(raw) && flightState._drSpeedPlaced === true; flightState._cachedDRCourse = flightState._drCourseDeg; flightState._cachedDRSpeedMps = flightState._drSpeedMps; flightState._cachedDRHold = flightState._drCourseHold; @@ -475,6 +477,16 @@ export function createMotion({ * later in the frame, so recomputing _trackedDisplayPosition there jitters the label against the * now-stable plane. Null when no valid fix (callers fall back to the icon position). */ + /** Whether a host-supplied placement placed the tracked aircraft where + * `_trackedDisplayCached` holds it this frame, rather than this layer's + * own motion at its display delay. */ + + function _trackedPlaced() { + return ( + _trackedDisplayCached() !== null && flightState._cachedDRPlaced === true + ); + } + function _trackedDisplayCached() { return flightState._drReconcileValid && flightState._drReconcileIcao === flightState._trackedIcao @@ -697,6 +709,7 @@ export function createMotion({ _trackedFocusSizePx, _trackedDisplayPosition, _trackedDisplayCached, + _trackedPlaced, _trackedVisualCached, _trackedModelCenterWorld, _trackedModelEnvelopeM, diff --git a/src/layers/military/state.js b/src/layers/military/state.js index 27d2530c78..d0c41c4ca1 100644 --- a/src/layers/military/state.js +++ b/src/layers/military/state.js @@ -236,6 +236,12 @@ export function createFlightState({ source, services }) { flightState._drSpeedPlaced = false; + /** Sibling of `_cachedDRPosition`: whether a host-supplied placement placed + * it (`_drSpeedPlaced` as the tracked aircraft was drawn), so its trail + * ends where it is drawn rather than at the layer's display delay. */ + + flightState._cachedDRPlaced = false; + flightState._drCourseHold = false; /** Set by `_deadReckon`: following the clock, the time drawn is well diff --git a/src/layers/military/tracking.js b/src/layers/military/tracking.js index e276def613..0f6a4ecc67 100644 --- a/src/layers/military/tracking.js +++ b/src/layers/military/tracking.js @@ -49,6 +49,7 @@ import { trailBodySegments, trailHeadCurvePoints, trailHeadStartFix, + trailTimeAt, } from '../../data/trailContinuity.js'; import { roundHeadingDegrees } from '../../data/headingDegrees.js'; import { entityRecord } from '../../data/entityRecords.js'; @@ -614,12 +615,46 @@ export function createTracking({ ); } - /** Reports at or before the time the aircraft is drawn (now − the display delay). */ + /** Reports at or before the time the aircraft is drawn (`_trailDisplayMs`). */ function _trailBodyCountNow() { - return trailBodyCount( + return trailBodyCount(flightState._trailFixes, _trailDisplayMs()); + } + + /** + * The time on its trail at which a host-supplied placement draws the + * aircraft, read off the trail where it is drawn (`trailTimeAt`): such a + * placement draws at a delay of its own, not this layer's. NaN when this + * layer's own motion draws it, or the trail has no pair to read. + * @returns {number} Epoch ms or NaN. + */ + function _placedTrailMs() { + if (!parts.motion._trackedPlaced?.()) return NaN; + return trailTimeAt( flightState._trailFixes, - flightState.now() - displayDelayMs(flightState), + parts.motion._trackedDisplayCached(), + ); + } + + /** + * The time the trail runs up to: the time the aircraft is drawn at, now − + * the display delay, or where a placement draws it. Otherwise the trail + * ends short of a placed aircraft, or runs on ahead of it. + * @returns {number} Epoch ms. + */ + function _trailDisplayMs() { + const placedMs = _placedTrailMs(); + return Number.isFinite(placedMs) + ? placedMs + : flightState.now() - displayDelayMs(flightState); + } + + /** Whether the trail holds no report behind the aircraft yet: this + * layer's own motion draws it before its oldest fix. Never for an + * aircraft a placement draws: its trail is read where it is drawn. */ + function _trailWarmingUp() { + return ( + !Number.isFinite(_placedTrailMs()) && parts.motion._isTrackWarmingUp() ); } @@ -636,7 +671,7 @@ export function createTracking({ if ( !flightState._trackedIcao || !flightState._trailFixes.length || - parts.motion._isTrackWarmingUp() + _trailWarmingUp() ) return []; const head = @@ -664,7 +699,7 @@ export function createTracking({ trailHeadCurvePoints( flightState._trailFixes, flightState._trailBodyCount, - flightState.now() - displayDelayMs(flightState), + _trailDisplayMs(), ), end, parts.motion._trackedModelCenterWorld(), diff --git a/src/layers/military/trail.test.mjs b/src/layers/military/trail.test.mjs index daa954ea9b..b4d97074f8 100644 --- a/src/layers/military/trail.test.mjs +++ b/src/layers/military/trail.test.mjs @@ -65,7 +65,15 @@ function recordingTrail() { }; } -function trackedHarness({ liveFixes = [], trace = null, nowMs, floor, head }) { +function trackedHarness({ + liveFixes = [], + trace = null, + nowMs, + floor, + head, + placed = false, + warmingUp = false, +}) { const trail = recordingTrail(); const svc = services({ trails: trail, floor }); const flightState = createFlightState({ @@ -104,7 +112,9 @@ function trackedHarness({ liveFixes = [], trace = null, nowMs, floor, head }) { services: svc, parts: { motion: { - _isTrackWarmingUp: () => false, + _isTrackWarmingUp: () => warmingUp, + _trackedPlaced: () => placed, + _trackedDisplayCached: () => head ?? null, _trackedTrailCached: () => head ?? null, _trackedDisplayPosition: () => head ?? null, _trackedModelCenterWorld: () => null, @@ -256,3 +266,36 @@ test('a full 24 h military trace fits within TRAIL_MAX_POINTS without thinning', assert.ok(TRAIL_MAX_POINTS >= day + 500); assert.equal(flightState._trailFixes.length, day + 1); }); + +test('a placed military aircraft drawn ahead of the display delay keeps its trail joined to it', () => { + const t0 = Date.UTC(2026, 10, 8, 0, 0); + const liveFixes = [0, 1, 2, 3].map((i) => ({ + timeMs: t0 + i * MINUTE, + lat: 50, + lon: 1 + i * 0.12, + })); + // Warming up by the layer's own delay; the placement draws it between the + // third and fourth reports. + const near = Cesium.Cartesian3.fromDegrees(1.3, 50, 9_000); + const harness = trackedHarness({ + liveFixes, + nowMs: t0 + 3.5 * MINUTE, + head: near, + placed: true, + warmingUp: true, + }); + harness.flightState._displayDelay = { currentMs: 10 * MINUTE }; + harness.tracking._startTrail('ae0001'); + const body = harness.trail.last()[0]; + assert.equal(harness.trail.last().length, 1); + assert.ok( + Cesium.Cartesian3.distance( + body[body.length - 1], + Cesium.Cartesian3.fromDegrees(1.24, 50, 9_000), + ) < 1, + ); + const drawn = harness.headPositions(); + assert.ok(drawn.length >= 2); + assert.ok(Cesium.Cartesian3.distance(drawn[0], body[body.length - 1]) < 1); + assert.ok(Cesium.Cartesian3.distance(drawn[drawn.length - 1], near) < 1); +});