diff --git a/changelog.d/1749-smooth-rewind.md b/changelog.d/1749-smooth-rewind.md new file mode 100644 index 000000000..97ee20b69 --- /dev/null +++ b/changelog.d/1749-smooth-rewind.md @@ -0,0 +1,6 @@ +- Flights, military flights and vessels move back as smoothly as they move on. + A source whose snapshots at a time carry each contact's own fixes either + side of it (`timeline.spanMs`, record `fixes`) lets a seek or a drag back + within those fixes move every contact along its track, with no blank and no + wait; the step there then loads in place of every contact. A contact is not + drawn more than a minute before its first fix. diff --git a/docs/CURRENT-STATE.md b/docs/CURRENT-STATE.md index 194b10ebf..6b4c8252f 100644 --- a/docs/CURRENT-STATE.md +++ b/docs/CURRENT-STATE.md @@ -1983,7 +1983,7 @@ layer's existing lifecycle and selection guards continue to reject late work. ### Following the world clock A source may declare a timeline: it can answer a snapshot at a given time. -`source.timeline` is `{ coverage(), stepMs, subscribe? }`, validated by +`source.timeline` is `{ coverage(), stepMs, spanMs?, subscribe? }`, validated by `readSnapshotTimeline` (`src/sources/live/contract.js`): `coverage()` returns the span `{ start, end }` in epoch ms it can answer, or null while it does not know yet; `stepMs` is the spacing of its snapshots; the optional @@ -2017,6 +2017,20 @@ the older is aborted before a newer starts. Moving the view while vessels follow area at the same time. Back at live the contacts are cleared and the layer polls at once. +A timeline may also declare `spanMs`: each record of a snapshot at a time then +carries `fixes`, `{ atMs, lat, lon, altitudeM? }` in time order, its own track +from `spanMs` before the time to `spanMs` after it +(`src/time/timelineFixes.js`). The layer places each contact on its fixes at +the clock's time, so a seek or a move back that stays within the fixes the +loaded snapshots carry is no jump: nothing is cleared, play does not wait, +and contacts move to the time smoothly. The snapshot at a step before the +newest loaded is asked for once and then stands in for every contact: it +brings back any that had left after it and drops those not there yet, while +those it has keep their place, as their fixes put them. Paused, a time nearing +the end of the fixes after the newest asks for the snapshot there. A contact is not drawn more than a minute before its first +fix, as it was not there yet. Each contact keeps at most 240 fixes, at least +20 seconds apart, and the loaded snapshot times span at most 20 minutes. + A snapshot at `atMs` describes the world as it stood then: `observedAtMs` is at or before `atMs`, no record is observed later than `atMs`, freshness and staleness are judged against `atMs`, `atMs` is echoed back, and a vessel diff --git a/scripts/package-boundaries.json b/scripts/package-boundaries.json index bec87c9ba..577310fb7 100644 --- a/scripts/package-boundaries.json +++ b/scripts/package-boundaries.json @@ -1565,6 +1565,8 @@ "src/layers/flights/records.js", "src/layers/flights/clockFollow.js", "src/time/snapshotTimeline.js", + "src/data/timelineHistory.js", + "src/time/timelineFixes.js", "src/sources/live/contract.js", "src/layers/flights/recordPolicy.js", "src/layers/flights/snapshotRenderer.js", @@ -1631,6 +1633,8 @@ "src/layers/military/ingestion.js", "src/layers/military/clockFollow.js", "src/time/snapshotTimeline.js", + "src/data/timelineHistory.js", + "src/time/timelineFixes.js", "src/sources/live/contract.js", "src/layers/military/lifecycle.js", "src/layers/military/motion.js", @@ -1717,6 +1721,7 @@ "src/layers/vessels/ingestion.js", "src/layers/vessels/motion.js", "src/time/snapshotTimeline.js", + "src/time/timelineFixes.js", "src/time/worldClock.js", "src/sources/live/contract.js", "src/layers/vessels/cameraArea.js", @@ -2894,6 +2899,8 @@ "src/layers/flights/index.js", "src/layers/flights/clockFollow.js", "src/time/snapshotTimeline.js", + "src/data/timelineHistory.js", + "src/time/timelineFixes.js", "src/layers/flights/ingestion.js", "src/layers/flights/lifecycle.js", "src/layers/flights/motion.js", @@ -4083,6 +4090,8 @@ "src/layers/flights/index.js", "src/layers/flights/clockFollow.js", "src/time/snapshotTimeline.js", + "src/data/timelineHistory.js", + "src/time/timelineFixes.js", "src/sources/live/contract.js", "src/layers/flights/ingestion.js", "src/layers/flights/lifecycle.js", @@ -4878,7 +4887,8 @@ "exports": ["./layers/vessels/records"], "modules": [ "src/layers/vessels/records.js", - "src/layers/vessels/recordPolicy.js" + "src/layers/vessels/recordPolicy.js", + "src/time/timelineFixes.js" ], "external": [] }, diff --git a/src/data/timelineHistory.js b/src/data/timelineHistory.js new file mode 100644 index 000000000..d48c99d06 --- /dev/null +++ b/src/data/timelineHistory.js @@ -0,0 +1,171 @@ +import * as Cesium from 'cesium'; +import { + mergeTimelineRuns, + readTimelineFixes, + TIMELINE_UNSEEN_MS, +} from '../time/timelineFixes.js'; + +/** Fixes nearer than this are too close to read a course between. */ +const COURSE_MIN_M = 5; +const EARTH_RADIUS_M = 6_371_000; + +/** The initial great-circle course from one fix to another (degrees from + * north), or null when they are too close to tell. */ +function courseBetween(from, to) { + const lat1 = Cesium.Math.toRadians(from.lat); + const lat2 = Cesium.Math.toRadians(to.lat); + const dLon = Cesium.Math.toRadians(to.lon - from.lon); + const dLat = lat2 - lat1; + const a = + Math.sin(dLat / 2) ** 2 + + Math.cos(lat1) * Math.cos(lat2) * Math.sin(dLon / 2) ** 2; + if (2 * EARTH_RADIUS_M * Math.asin(Math.min(1, Math.sqrt(a))) < COURSE_MIN_M) + return null; + const y = Math.sin(dLon) * Math.cos(lat2); + const x = + Math.cos(lat1) * Math.sin(lat2) - + Math.sin(lat1) * Math.cos(lat2) * Math.cos(dLon); + return (Cesium.Math.toDegrees(Math.atan2(y, x)) + 360) % 360; +} + +/** + * An aircraft's motion history with the fixes its record carries at a time + * (`observation.fixes`, see src/time/timelineFixes.js) merged in, so the + * layer places it on its own track at any time they span; null when the + * record carries none. Each fix is drawn at the record's render height, + * moved by the fix's own barometric change from the record's, and heads + * where its track goes next (the last, where it came from). Entries are + * marked `timeline`. + * @param {object[]|undefined} history The contact's history entries. + * @param {object} observation The record, with `fixes` and `baroAltitudeM`. + * @param {{renderAltitudeM: number, renderAltitudeInvented?: boolean}} meta + * @param {number|null} velocity The record's ground speed (m/s). + * @param {number} centreMs The snapshot's time: the fixes kept are nearest it. + * @returns {object[]|null} + */ +export function mergeAircraftTimelineFixes( + history, + observation, + meta, + velocity, + centreMs, +) { + const fixes = readTimelineFixes(observation?.fixes); + if (!fixes) return null; + const baroM = Number.isFinite(observation.baroAltitudeM) + ? observation.baroAltitudeM + : null; + const entries = fixes.map((fix, index) => { + const course = + index + 1 < fixes.length + ? courseBetween(fix, fixes[index + 1]) + : courseBetween(fixes[index - 1], fix); + return { + time: Cesium.JulianDate.fromDate(new Date(fix.atMs)), + epochMs: fix.atMs, + position: Cesium.Cartesian3.fromDegrees( + fix.lon, + fix.lat, + baroM !== null && fix.altitudeM !== null + ? meta.renderAltitudeM + (fix.altitudeM - baroM) + : meta.renderAltitudeM, + ), + velocity, + // No reported track per fix: the course is read from the fixes. + track: course ?? undefined, + inventedHeight: meta.renderAltitudeInvented === true, + timeline: true, + }; + }); + return mergeTimelineRuns( + history ?? [], + entries, + (entry) => entry.epochMs, + centreMs, + ); +} + +/** + * The index of the first history entry at or after `renderTime` (the last + * entry when none is), by halving: a contact following the clock keeps up to + * TIMELINE_FIXES_LIMIT entries, and it is placed on every fleet tick. The + * bracketing pair is the entry before it and it. + * @param {Array<{time: Cesium.JulianDate}>} history In time order. + * @param {Cesium.JulianDate} renderTime + * @returns {number} + */ +export function historyBracketIndex(history, renderTime) { + let low = 0; + let high = history.length - 1; + while (low < high) { + const mid = (low + high) >> 1; + if (Cesium.JulianDate.lessThan(history[mid].time, renderTime)) + low = mid + 1; + else high = mid; + } + return low; +} + +/** + * Whether a contact following the clock is not to be drawn at `renderTime`: + * its history is its own fixes around the time (`timeline` entries), and the + * time is more than TIMELINE_UNSEEN_MS before the first, when it was not + * there yet. + * @param {Array<{time: Cesium.JulianDate, timeline?: boolean}>|undefined} history + * @param {Cesium.JulianDate} renderTime + * @returns {boolean} + */ +export function historyUnseenAt(history, renderTime) { + const first = history?.[0]; + return ( + first?.timeline === true && + Cesium.JulianDate.secondsDifference(first.time, renderTime) > + TIMELINE_UNSEEN_MS / 1000 + ); +} + +/** + * Lift a grounded contact's history onto the floor: its newest fix to + * `position`, or, when the history is its own fixes around the time + * (`timeline` entries, the newest of them later than the time drawn), every + * fix by the lift from `fromM` to `toM`, so it is not drawn rising to it. + * @param {object[]|undefined} history + * @param {Cesium.Cartesian3} position The newest fix lifted. + * @param {number|null} fromM The height it was drawn at. + * @param {number} toM The height it is lifted to. + */ +export function liftGroundedHistory(history, position, fromM, toM) { + const newest = history?.[history.length - 1]; + if (!newest) return; + if (history[0].timeline !== true || !Number.isFinite(fromM)) { + newest.position = Cesium.Cartesian3.clone(position, newest.position); + return; + } + for (const entry of history) { + const carto = Cesium.Cartographic.fromCartesian(entry.position); + if (!carto) continue; + entry.position = Cesium.Cartesian3.fromRadians( + carto.longitude, + carto.latitude, + carto.height + (toM - fromM), + undefined, + entry.position, + ); + } +} + +/** + * The history entries a tracked contact's trail has yet to take: those after + * its newest point (`trail` entries have `timeMs`) up to `untilMs`, the + * snapshot's time, so the trail grows as the snapshots bring fixes. + * @param {Array<{epochMs: number}>} history + * @param {Array<{timeMs: number}>} trail + * @param {number} untilMs + * @returns {object[]} + */ +export function historyAfterTrail(history, trail, untilMs) { + const lastMs = trail.length ? trail[trail.length - 1].timeMs : -Infinity; + return history.filter( + (entry) => entry.epochMs > lastMs && entry.epochMs <= untilMs, + ); +} diff --git a/src/data/timelineHistory.test.mjs b/src/data/timelineHistory.test.mjs new file mode 100644 index 000000000..e3689b582 --- /dev/null +++ b/src/data/timelineHistory.test.mjs @@ -0,0 +1,147 @@ +import test from 'node:test'; +import assert from 'node:assert/strict'; +import * as Cesium from 'cesium'; +import { + historyAfterTrail, + historyBracketIndex, + historyUnseenAt, + liftGroundedHistory, + mergeAircraftTimelineFixes, +} from './timelineHistory.js'; + +const META = { renderAltitudeM: 3_000 }; +const fix = (atMs, lat, altitudeM = null, lon = 0) => ({ + atMs, + lat, + lon, + altitudeM, +}); +const julian = (ms) => Cesium.JulianDate.fromDate(new Date(ms)); + +test('an aircraft with no fixes merges nothing', () => { + assert.equal( + mergeAircraftTimelineFixes([], { fixes: null }, META, 100, 0), + null, + ); +}); + +test("an aircraft's fixes join its history in order, each at the render height moved by its own climb", () => { + const history = mergeAircraftTimelineFixes( + [], + { + baroAltitudeM: 1_000, + fixes: [fix(120_000, 1, 1_200), fix(60_000, 0, 1_000), fix(180_000, 2)], + }, + META, + 100, + 120_000, + ); + assert.deepEqual( + history.map((entry) => entry.epochMs), + [60_000, 120_000, 180_000], + ); + const height = (entry) => + Cesium.Cartographic.fromCartesian(entry.position).height; + assert.ok(Math.abs(height(history[0]) - 3_000) < 1e-3); + assert.ok(Math.abs(height(history[1]) - 3_200) < 1e-3); + assert.ok( + Math.abs(height(history[2]) - 3_000) < 1e-3, + 'no altitude: the render height', + ); + // A later snapshot's fixes add to the earlier ones. + const more = mergeAircraftTimelineFixes( + history, + { baroAltitudeM: 1_000, fixes: [fix(180_000, 2), fix(240_000, 3)] }, + META, + 100, + 180_000, + ); + assert.deepEqual( + more.map((entry) => entry.epochMs), + [60_000, 120_000, 180_000, 240_000], + ); +}); + +test('the bracketing entry is the first at or after the time, else the last', () => { + const history = [1_000, 2_000, 3_000].map((ms) => ({ + time: Cesium.JulianDate.fromDate(new Date(ms)), + })); + const at = (ms) => + historyBracketIndex(history, Cesium.JulianDate.fromDate(new Date(ms))); + assert.equal(at(500), 0); + assert.equal(at(1_000), 0); + assert.equal(at(1_500), 1); + assert.equal(at(3_000), 2); + assert.equal(at(9_000), 2); +}); + +test('each fix heads where the track goes next, the last where it came from', () => { + const history = mergeAircraftTimelineFixes( + [], + { + fixes: [ + fix(0, 0, null, 0), + fix(60_000, 0, null, 0.01), + fix(120_000, 0.01, null, 0.01), + fix(180_000, 0.01, null, 0.01), + ], + }, + META, + 100, + 0, + ); + const tracks = history.map((entry) => entry.track); + assert.ok(Math.abs(tracks[0] - 90) < 0.5, 'east'); + assert.ok(Math.abs(tracks[1]) < 0.5, 'north'); + assert.equal(tracks[2], undefined, 'no move to read'); + assert.equal(tracks[3], undefined); + assert.ok(history.every((entry) => entry.timeline === true)); +}); + +test('a contact is unseen only well before the first of its own fixes', () => { + const history = mergeAircraftTimelineFixes( + [], + { fixes: [fix(600_000, 0), fix(660_000, 1)] }, + META, + 100, + 600_000, + ); + assert.equal(historyUnseenAt(history, julian(0)), true); + assert.equal(historyUnseenAt(history, julian(560_000)), false); + const live = [{ time: julian(600_000) }]; + assert.equal(historyUnseenAt(live, julian(0)), false, 'not on its fixes'); + assert.equal(historyUnseenAt(undefined, julian(0)), false); +}); + +test('a grounded contact on its own fixes is lifted whole; else its newest fix', () => { + const height = (entry) => + Cesium.Cartographic.fromCartesian(entry.position).height; + const history = mergeAircraftTimelineFixes( + [], + { fixes: [fix(0, 0), fix(60_000, 0.001)] }, + { renderAltitudeM: 5 }, + 0, + 0, + ); + const lifted = Cesium.Cartesian3.fromDegrees(0, 0.001, 30); + liftGroundedHistory(history, lifted, 5, 30); + assert.ok(history.every((entry) => Math.abs(height(entry) - 30) < 1e-3)); + const live = [ + { position: Cesium.Cartesian3.fromDegrees(0, 0, 5) }, + { position: Cesium.Cartesian3.fromDegrees(0, 0.001, 5) }, + ]; + liftGroundedHistory(live, lifted, 5, 30); + assert.ok(Math.abs(height(live[0]) - 5) < 1e-3); + assert.ok(Math.abs(height(live[1]) - 30) < 1e-3); +}); + +test("a tracked trail takes the fixes after its newest point, up to the snapshot's time", () => { + const history = [0, 60_000, 120_000, 180_000].map((epochMs) => ({ epochMs })); + assert.deepEqual( + historyAfterTrail(history, [{ timeMs: 60_000 }], 120_000).map( + (entry) => entry.epochMs, + ), + [120_000], + ); + assert.equal(historyAfterTrail(history, [], 120_000).length, 3); +}); diff --git a/src/layers/flights/motion.js b/src/layers/flights/motion.js index ccf2ca8c1..756fef1d2 100644 --- a/src/layers/flights/motion.js +++ b/src/layers/flights/motion.js @@ -1,4 +1,9 @@ import * as Cesium from 'cesium'; +import { + historyBracketIndex, + historyUnseenAt, + liftGroundedHistory, +} from '../../data/timelineHistory.js'; import { julianAt } from '../../time/julian.js'; import { COURSE_HOLD_SPEED_MPS, @@ -120,6 +125,7 @@ export function createMotion({ info.renderAltitudeM >= floor - 1 ) continue; + const drawnM = info.renderAltitudeM; info.renderAltitudeM = lifted; flightState._cullPositions.delete(icao24); // above the ellipsoid now (or floors say otherwise next poll) const position = Cesium.Cartesian3.fromDegrees( @@ -127,10 +133,12 @@ export function createMotion({ info.rawLat, lifted, ); - const history = flightState._positionHistory.get(icao24); - const newest = history?.[history.length - 1]; - if (newest) - newest.position = Cesium.Cartesian3.clone(position, newest.position); + liftGroundedHistory( + flightState._positionHistory.get(icao24), + position, + drawnM, + lifted, + ); const bb = flightState._billboards.get(icao24); if (bb) bb.position = position; } @@ -153,6 +161,7 @@ export function createMotion({ function _deadReckon(icao24, result, sampledRenderTime) { const info = flightState.records.data.get(icao24); + flightState._drUnseen = false; if (FOCUS_EVIDENCE_DEV && flightState._focusEvidenceIds.has(icao24)) { const position = flightState._billboards.get(icao24)?.position; flightState._drCourseDeg = info?.true_track || 0; @@ -198,7 +207,15 @@ export function createMotion({ ); // Bracketing pair: interpolate — no extrapolation error, no snap-back. - for (let i = history.length - 1; i >= 1; i--) { + // The pair around the render time (and the one before it, for a fix at + // exactly that time), found by halving: a contact following the clock + // keeps a long history. + for ( + let i = historyBracketIndex(history, renderTime), + stop = Math.max(1, i - 1); + i >= stop; + i-- + ) { const a = history[i - 1]; const b = history[i]; if ( @@ -254,6 +271,9 @@ export function createMotion({ // the oldest fix froze the icon; extrapolating the NEWEST fix to wall-clock now made // the icon jump back ~one poll interval the instant interpolation took over.) const oldest = history[0]; + // Following the clock, a time well before its first fix is before it + // was there: the fleet pass hides it. + flightState._drUnseen = historyUnseenAt(history, renderTime); const lookbackSec = Cesium.JulianDate.secondsDifference( oldest.time, renderTime, diff --git a/src/layers/flights/rendering.js b/src/layers/flights/rendering.js index 64d9064ff..ec4846ac1 100644 --- a/src/layers/flights/rendering.js +++ b/src/layers/flights/rendering.js @@ -1032,6 +1032,7 @@ export function createRendering({ flightState._scratchFleetPos, renderTime, ); + const unseen = flightState._drUnseen; // The dead-reckoned point drifts away from the fix whose cell supplied the // height, so a grounded contact's sprite ends up under the mesh it taxied // (or coasted) over. Re-floor at the DISPLAYED coordinate — read-only, and @@ -1057,9 +1058,12 @@ export function createRendering({ // sub-ellipsoid point near the limb "beyond the horizon" and the fleet // pass would hide a plane that is really just low over high-N terrain // waiting for its floor to warm (ATL grounded contacts at geoid −31 m). - const beyondHorizon = !occluder.isPointVisible( - flightState._cullPositions.get(icao24) || bb.position, - ); + // A contact not there yet at the time drawn is hidden as one beyond it. + const beyondHorizon = + unseen || + !occluder.isPointVisible( + flightState._cullPositions.get(icao24) || bb.position, + ); // A billboard flipping INTO view (horizon reveal while the camera idles) // gets its rotation refreshed THIS tick even without a pose change — // otherwise it reappears wearing its stale (often creation-north) nose for diff --git a/src/layers/flights/snapshotRenderer.js b/src/layers/flights/snapshotRenderer.js index 0306e85de..48a8b931d 100644 --- a/src/layers/flights/snapshotRenderer.js +++ b/src/layers/flights/snapshotRenderer.js @@ -10,6 +10,10 @@ import { aircraftIcon } from '../../data/aircraftIcons.js'; import { POSITION_HISTORY_LIMIT } from './recordPolicy.js'; import { followsClock } from './policy.js'; import { observeLiveAircraft } from './placed.js'; +import { + historyAfterTrail, + mergeAircraftTimelineFixes, +} from '../../data/timelineHistory.js'; /** Apply reconciled aircraft records to Cesium resources and follow state. */ export function createFlightSnapshotRenderer({ @@ -101,6 +105,18 @@ export function createFlightSnapshotRenderer({ ); const isTracked = icao24 === flightState._trackedIcao; + // Following the clock, a record may carry its own track around the + // time: the contact is placed on it, so the clock can move within it, + // back as well as on, without another snapshot. + const timelineHistory = followsClock(flightState) + ? mergeAircraftTimelineFixes( + flightState._positionHistory.get(icao24), + observation, + meta, + meta.velocity, + snapshot.observedAtMs ?? fixEpochMs, + ) + : null; // A host-supplied placement, if any, is told every fix as taken. observeLiveAircraft( flightState, @@ -111,80 +127,94 @@ export function createFlightSnapshotRenderer({ meta.velocity, meta.true_track, ); - - // Append to position history stamped with the FEED's fix epoch - // (time_position), not client receipt time — OpenSky positions arrive - // 5-15s stale and receipt-time stamping is what caused the - // back/forward oscillation. Only append when the fix actually - // advances, so stale repeats don't create zero-dt segments. - const fixTime = Cesium.JulianDate.fromDate(new Date(fixEpochMs)); - if (!flightState._positionHistory.has(icao24)) { - flightState._positionHistory.set(icao24, []); - } - const history = flightState._positionHistory.get(icao24); - const newest = history[history.length - 1]; - if (!newest || Cesium.JulianDate.greaterThan(fixTime, newest.time)) { - // Per-fix kinematics: the fix's own velocity/track ride along so the - // extrapolation paths use the values that BELONG to the fix they - // extend, not whatever the latest poll reported. - history.push({ - time: fixTime, - epochMs: fixEpochMs, - position: position.clone(), - velocity: meta.velocity, - track: meta.true_track, - // Drawn at an invented height: a trail seeded from history keeps no - // position for it. - inventedHeight: meta.renderAltitudeInvented === true, - }); - if (history.length > POSITION_HISTORY_LIMIT) { - history.shift(); - } - // Turn rate from the fix-track history — computed once per new fix - // (≤5 samples), consumed by the extrapolation paths at tick rate. - meta.turnRateDps = turnRateFromFixHistory(history); - // Trail accumulation is separate from the 5-fix DR history (PRD F1) - // so the visible trail keeps growing while tracked. Ground traffic - // appends nothing — a touchdown freezes the existing trail. - // Round 2 (owner): ground traffic appends too — taxi history stays - // live after touchdown (grounded flights positions are already - // surface-clamped via the surfaceM chain, so the ground leg drapes). + if (timelineHistory) { if (isTracked) - tracking._appendTrailFix(position.clone(), fixEpochMs, { - nullAltitude: meta.renderAltitudeInvented === true, - }); + for (const entry of historyAfterTrail( + timelineHistory, + flightState._trailFixes, + snapshot.observedAtMs ?? fixEpochMs, + )) + tracking._appendTrailFix(entry.position.clone(), entry.epochMs, { + nullAltitude: entry.inventedHeight, + }); + flightState._positionHistory.set(icao24, timelineHistory); + meta.turnRateDps = 0; } else { - const modelOwnsGroundVisual = rendering._modelOwnsVisual(icao24); - if (!modelOwnsGroundVisual) { - liftRepeatedGroundFix(newest, position, meta.onGround); + // Append to position history stamped with the FEED's fix epoch + // (time_position), not client receipt time — OpenSky positions arrive + // 5-15s stale and receipt-time stamping is what caused the + // back/forward oscillation. Only append when the fix actually + // advances, so stale repeats don't create zero-dt segments. + const fixTime = Cesium.JulianDate.fromDate(new Date(fixEpochMs)); + if (!flightState._positionHistory.has(icao24)) { + flightState._positionHistory.set(icao24, []); } - // Apply fresh kinematics only from a forward synthetic fix. Mutating - // the historical fix reprojects the entire stale interval and snaps - // the rendered aircraft when course or speed changes late. The stale - // rules apply: none for a contact that holds at its report, a coast - // capped from the real report, never below the ground. It is a motion - // aid, not a report, so it never joins the trail. - const kinematicsChanged = - newest.velocity !== meta.velocity || newest.track !== meta.true_track; - const holds = staleHoldsForFix(newest, { - onGround: meta.onGround, - cachedGroundFloor, - }); - if (kinematicsChanged && !holds) { - const synthetic = synthesizeForwardKinematicsFix(newest, { - // Following the clock, the snapshot's time is the moment it moves on from. - epochMs: followsClock(flightState) - ? snapshot.observedAtMs - : Date.now(), + const history = flightState._positionHistory.get(icao24); + const newest = history[history.length - 1]; + if (!newest || Cesium.JulianDate.greaterThan(fixTime, newest.time)) { + // Per-fix kinematics: the fix's own velocity/track ride along so the + // extrapolation paths use the values that BELONG to the fix they + // extend, not whatever the latest poll reported. + history.push({ + time: fixTime, + epochMs: fixEpochMs, + position: position.clone(), velocity: meta.velocity, track: meta.true_track, - turnRateDps: meta.turnRateDps, + // Drawn at an invented height: a trail seeded from history keeps no + // position for it. + inventedHeight: meta.renderAltitudeInvented === true, + }); + if (history.length > POSITION_HISTORY_LIMIT) { + history.shift(); + } + // Turn rate from the fix-track history — computed once per new fix + // (≤5 samples), consumed by the extrapolation paths at tick rate. + meta.turnRateDps = turnRateFromFixHistory(history); + // Trail accumulation is separate from the 5-fix DR history (PRD F1) + // so the visible trail keeps growing while tracked. Ground traffic + // appends nothing — a touchdown freezes the existing trail. + // Round 2 (owner): ground traffic appends too — taxi history stays + // live after touchdown (grounded flights positions are already + // surface-clamped via the surfaceM chain, so the ground leg drapes). + if (isTracked) + tracking._appendTrailFix(position.clone(), fixEpochMs, { + nullAltitude: meta.renderAltitudeInvented === true, + }); + } else { + const modelOwnsGroundVisual = rendering._modelOwnsVisual(icao24); + if (!modelOwnsGroundVisual) { + liftRepeatedGroundFix(newest, position, meta.onGround); + } + // Apply fresh kinematics only from a forward synthetic fix. Mutating + // the historical fix reprojects the entire stale interval and snaps + // the rendered aircraft when course or speed changes late. The stale + // rules apply: none for a contact that holds at its report, a coast + // capped from the real report, never below the ground. It is a motion + // aid, not a report, so it never joins the trail. + const kinematicsChanged = + newest.velocity !== meta.velocity || + newest.track !== meta.true_track; + const holds = staleHoldsForFix(newest, { + onGround: meta.onGround, cachedGroundFloor, }); - if (synthetic) { - history.push(synthetic); - if (history.length > POSITION_HISTORY_LIMIT) history.shift(); - meta.turnRateDps = turnRateFromFixHistory(history); + if (kinematicsChanged && !holds) { + const synthetic = synthesizeForwardKinematicsFix(newest, { + // Following the clock, the snapshot's time is the moment it moves on from. + epochMs: followsClock(flightState) + ? snapshot.observedAtMs + : Date.now(), + velocity: meta.velocity, + track: meta.true_track, + turnRateDps: meta.turnRateDps, + cachedGroundFloor, + }); + if (synthetic) { + history.push(synthetic); + if (history.length > POSITION_HISTORY_LIMIT) history.shift(); + meta.turnRateDps = turnRateFromFixHistory(history); + } } } } @@ -228,6 +258,7 @@ export function createFlightSnapshotRenderer({ // the raw fix drew it ahead until the next fleet tick snapped it back; // skipping the floor started a taxiing contact low and then raised it. const delayed = motion._deadReckon(icao24, new Cesium.Cartesian3()); + const unseenAtStart = flightState._drUnseen; const displayed = (delayed && motion._floorGroundedDisplayPosition( @@ -256,7 +287,9 @@ export function createFlightSnapshotRenderer({ // close (_groundDepthDistance). disableDepthTestDistance: rendering._groundDepthDistance(), id: icao24, - show: !isTracked, // hidden if currently tracked (entity replaces it) + // Hidden if currently tracked (entity replaces it), or not there yet + // at the time drawn (see historyUnseenAt). + show: !isTracked && !unseenAtStart, }); flightState._billboards.set(icao24, bb); rendering._applyFleetBillboardPresentation(icao24, bb); diff --git a/src/layers/flights/state.js b/src/layers/flights/state.js index 17bf8b560..1e7c87bd5 100644 --- a/src/layers/flights/state.js +++ b/src/layers/flights/state.js @@ -321,6 +321,11 @@ export function createFlightState({ source, services }) { flightState._drExtrapolating = false; + /** Set by `_deadReckon`: following the clock, the time drawn is well + * before the contact's first fix, so the fleet pass does not draw it. */ + + flightState._drUnseen = false; + /** Frame-cached course for the tracked aircraft (sibling of _cachedDRPosition). */ flightState._cachedDRCourse = null; diff --git a/src/layers/military/motion.js b/src/layers/military/motion.js index 0073937b2..4b009ce93 100644 --- a/src/layers/military/motion.js +++ b/src/layers/military/motion.js @@ -1,4 +1,8 @@ import * as Cesium from 'cesium'; +import { + historyBracketIndex, + historyUnseenAt, +} from '../../data/timelineHistory.js'; import { julianAt } from '../../time/julian.js'; import { lerpAngleDeg, @@ -61,6 +65,7 @@ export function createMotion({ */ function _deadReckon(icao24, result) { + flightState._drUnseen = false; const history = flightState._positionHistory.get(icao24); const info = flightState.records.data.get(icao24); if (!history || history.length === 0) { @@ -93,7 +98,15 @@ export function createMotion({ ); // Bracketing pair: interpolate — no extrapolation error, no snap-back. - for (let i = history.length - 1; i >= 1; i--) { + // The pair around the render time (and the one before it, for a fix at + // exactly that time), found by halving: a contact following the clock + // keeps a long history. + for ( + let i = historyBracketIndex(history, renderTime), + stop = Math.max(1, i - 1); + i >= stop; + i-- + ) { const a = history[i - 1]; const b = history[i]; if ( @@ -147,6 +160,9 @@ export function createMotion({ // the bracketing interpolation above with NO freeze and NO backward snap. (Holding // the oldest fix froze the icon until enough history accrued, then jumped.) const oldest = history[0]; + // Following the clock, a time well before its first fix is before it + // was there: the fleet pass hides it. + flightState._drUnseen = historyUnseenAt(history, renderTime); const lookbackSec = Cesium.JulianDate.secondsDifference( oldest.time, renderTime, diff --git a/src/layers/military/rendering.js b/src/layers/military/rendering.js index 7e19b4567..9dd1707ac 100644 --- a/src/layers/military/rendering.js +++ b/src/layers/military/rendering.js @@ -917,6 +917,7 @@ export function createRendering({ if (icao24 === flightState._trackedIcao) continue; // tracked entity owns its own motion const dr = parts.motion._deadReckon(icao24, flightState._scratchFleetPos); + const unseen = flightState._drUnseen; // Gate the write — assigning Billboard.position dirties the whole // collection's vertex buffer, so skip sub-meter moves. if (dr && Cesium.Cartesian3.distanceSquared(dr, bb.position) > 1.0) { @@ -926,9 +927,12 @@ export function createRendering({ // Round 6: occlusion-test a LIFTED point for contacts at/below the // ellipsoid (mirror of flights.js — sub-ellipsoid points near the limb // read "beyond the horizon" and would hide low contacts awaiting floors). - const beyondHorizon = !occluder.isPointVisible( - flightState.records.data.get(icao24)?.cullPosition || bb.position, - ); + // A contact not there yet at the time drawn is hidden as one beyond it. + const beyondHorizon = + unseen || + !occluder.isPointVisible( + flightState.records.data.get(icao24)?.cullPosition || bb.position, + ); // A billboard flipping INTO view (horizon reveal while the camera idles) // gets its rotation refreshed THIS tick even without a pose change — // otherwise it reappears wearing its stale (often creation-north) nose for diff --git a/src/layers/military/snapshotRenderer.js b/src/layers/military/snapshotRenderer.js index e70cd242f..56c135185 100644 --- a/src/layers/military/snapshotRenderer.js +++ b/src/layers/military/snapshotRenderer.js @@ -8,6 +8,11 @@ import { synthesizeForwardKinematicsFix, } from '../../data/motionModel.js'; import { aircraftIcon } from '../../data/aircraftIcons.js'; +import { + historyAfterTrail, + liftGroundedHistory, + mergeAircraftTimelineFixes, +} from '../../data/timelineHistory.js'; import { POSITION_HISTORY_LIMIT } from './recordPolicy.js'; import { BILLBOARD_SCALE, @@ -75,6 +80,18 @@ export function createMilitarySnapshotRenderer({ ); const isTracked = icao24 === flightState._trackedIcao; + // Following the clock, a record may carry its own track around the + // time: the contact is placed on it, so the clock can move within it, + // back as well as on, without another snapshot. + const timelineHistory = followsClock(flightState) + ? mergeAircraftTimelineFixes( + flightState._positionHistory.get(icao24), + aircraft, + meta, + meta.speedMps, + snapshot.observedAtMs ?? fixEpochMs, + ) + : null; // A host-supplied placement, if any, is told every fix as taken. observeLiveAircraft( flightState, @@ -85,76 +102,89 @@ export function createMilitarySnapshotRenderer({ meta.speedMps, meta.track, ); - - // Append to position history stamped with the FEED's fix epoch. - // adsb.lol's seen_pos is the AGE in seconds of the last position - // report, so the fix epoch is receipt time minus that age. Only - // append when the fix actually advances, so stale repeats don't - // create zero-dt segments. - const fixTime = Cesium.JulianDate.fromDate(new Date(fixEpochMs)); - if (!flightState._positionHistory.has(icao24)) { - flightState._positionHistory.set(icao24, []); - } - const history = flightState._positionHistory.get(icao24); - const newest = history[history.length - 1]; - if (!newest || Cesium.JulianDate.greaterThan(fixTime, newest.time)) { - // Per-fix kinematics: the fix's own velocity/track ride along so the - // extrapolation paths use the values that BELONG to the fix they - // extend, not whatever the latest poll reported. - history.push({ - time: fixTime, - epochMs: fixEpochMs, - position: position.clone(), - velocity: meta.speedMps, - track: meta.track, - // Drawn at an invented height: a trail seeded from history keeps no - // position for it. - inventedHeight: meta.renderAltitudeInvented === true, - }); - if (history.length > POSITION_HISTORY_LIMIT) { - history.shift(); - } - // Turn rate from the fix-track history — computed once per new fix - // (≤5 samples), consumed by the extrapolation paths at tick rate. - meta.turnRateDps = turnRateFromFixHistory(history); - // Trail accumulation is separate from the 5-fix DR history (PRD F2) - // so the visible trail keeps growing while tracked. Round 2 - // (owner): ground traffic appends too — taxi history stays live - // after touchdown; _appendTrailFix floors grounded positions at - // the surface so the ground leg drapes instead of diving. + if (timelineHistory) { if (isTracked) - tracking._appendTrailFix(position.clone(), fixEpochMs, { - nullAltitude: meta.renderAltitudeInvented === true, - }); + for (const entry of historyAfterTrail( + timelineHistory, + flightState._trailFixes, + snapshot.observedAtMs ?? fixEpochMs, + )) + tracking._appendTrailFix(entry.position.clone(), entry.epochMs, { + nullAltitude: entry.inventedHeight, + }); + flightState._positionHistory.set(icao24, timelineHistory); + meta.turnRateDps = 0; } else { - const modelOwnsGroundVisual = rendering._modelOwnsVisual(icao24); - if (!modelOwnsGroundVisual) { - liftRepeatedGroundFix(newest, position, meta.onGround); + // Append to position history stamped with the FEED's fix epoch. + // adsb.lol's seen_pos is the AGE in seconds of the last position + // report, so the fix epoch is receipt time minus that age. Only + // append when the fix actually advances, so stale repeats don't + // create zero-dt segments. + const fixTime = Cesium.JulianDate.fromDate(new Date(fixEpochMs)); + if (!flightState._positionHistory.has(icao24)) { + flightState._positionHistory.set(icao24, []); } - // A forward synthetic fix follows the stale rules (none while the - // contact holds at its report, a coast capped from the real report, - // never below the ground) and is a motion aid, never a trail report. - const kinematicsChanged = - newest.velocity !== meta.speedMps || newest.track !== meta.track; - const holds = staleHoldsForFix(newest, { - onGround: meta.onGround, - cachedGroundFloor, - }); - if (kinematicsChanged && !holds) { - const synthetic = synthesizeForwardKinematicsFix(newest, { - // Following the clock, the snapshot's time is the moment it moves on from. - epochMs: followsClock(flightState) - ? snapshot.observedAtMs - : Date.now(), + const history = flightState._positionHistory.get(icao24); + const newest = history[history.length - 1]; + if (!newest || Cesium.JulianDate.greaterThan(fixTime, newest.time)) { + // Per-fix kinematics: the fix's own velocity/track ride along so the + // extrapolation paths use the values that BELONG to the fix they + // extend, not whatever the latest poll reported. + history.push({ + time: fixTime, + epochMs: fixEpochMs, + position: position.clone(), velocity: meta.speedMps, track: meta.track, - turnRateDps: meta.turnRateDps, + // Drawn at an invented height: a trail seeded from history keeps no + // position for it. + inventedHeight: meta.renderAltitudeInvented === true, + }); + if (history.length > POSITION_HISTORY_LIMIT) { + history.shift(); + } + // Turn rate from the fix-track history — computed once per new fix + // (≤5 samples), consumed by the extrapolation paths at tick rate. + meta.turnRateDps = turnRateFromFixHistory(history); + // Trail accumulation is separate from the 5-fix DR history (PRD F2) + // so the visible trail keeps growing while tracked. Round 2 + // (owner): ground traffic appends too — taxi history stays live + // after touchdown; _appendTrailFix floors grounded positions at + // the surface so the ground leg drapes instead of diving. + if (isTracked) + tracking._appendTrailFix(position.clone(), fixEpochMs, { + nullAltitude: meta.renderAltitudeInvented === true, + }); + } else { + const modelOwnsGroundVisual = rendering._modelOwnsVisual(icao24); + if (!modelOwnsGroundVisual) { + liftRepeatedGroundFix(newest, position, meta.onGround); + } + // A forward synthetic fix follows the stale rules (none while the + // contact holds at its report, a coast capped from the real report, + // never below the ground) and is a motion aid, never a trail report. + const kinematicsChanged = + newest.velocity !== meta.speedMps || newest.track !== meta.track; + const holds = staleHoldsForFix(newest, { + onGround: meta.onGround, cachedGroundFloor, }); - if (synthetic) { - history.push(synthetic); - if (history.length > POSITION_HISTORY_LIMIT) history.shift(); - meta.turnRateDps = turnRateFromFixHistory(history); + if (kinematicsChanged && !holds) { + const synthetic = synthesizeForwardKinematicsFix(newest, { + // Following the clock, the snapshot's time is the moment it moves on from. + epochMs: followsClock(flightState) + ? snapshot.observedAtMs + : Date.now(), + velocity: meta.speedMps, + track: meta.track, + turnRateDps: meta.turnRateDps, + cachedGroundFloor, + }); + if (synthetic) { + history.push(synthetic); + if (history.length > POSITION_HISTORY_LIMIT) history.shift(); + meta.turnRateDps = turnRateFromFixHistory(history); + } } } } @@ -195,6 +225,7 @@ export function createMilitarySnapshotRenderer({ // it ahead until the next fleet tick snapped it back. const displayed = motion._deadReckon(icao24, new Cesium.Cartesian3()) || position; + const unseenAtStart = flightState._drUnseen; const bb = flightState._billboardCollection.add({ position: displayed, image: aircraftIcon(rendering._iconKind(icao24, meta.klass)), @@ -217,7 +248,9 @@ export function createMilitarySnapshotRenderer({ // close (_groundDepthDistance). disableDepthTestDistance: rendering._groundDepthDistance(), id: icao24, - show: !isTracked, // hidden if currently tracked (entity replaces it) + // Hidden if currently tracked (entity replaces it), or not there yet + // at the time drawn (see historyUnseenAt). + show: !isTracked && !unseenAtStart, }); flightState._billboards.set(icao24, bb); rendering._applyFleetBillboardPresentation(icao24, bb); @@ -259,6 +292,7 @@ export function createMilitarySnapshotRenderer({ info.renderAltitudeM >= floor - 1 ) continue; + const drawnM = info.renderAltitudeM; info.renderAltitudeM = lifted; flightState._cullPositions.delete(icao24); const liftedPos = Cesium.Cartesian3.fromDegrees( @@ -266,10 +300,12 @@ export function createMilitarySnapshotRenderer({ info.rawLat, lifted, ); - const hist = flightState._positionHistory.get(icao24); - const newest = hist?.[hist.length - 1]; - if (newest) - newest.position = Cesium.Cartesian3.clone(liftedPos, newest.position); + liftGroundedHistory( + flightState._positionHistory.get(icao24), + liftedPos, + drawnM, + lifted, + ); const bbStale = flightState._billboards.get(icao24); if (bbStale) bbStale.position = liftedPos; } diff --git a/src/layers/military/state.js b/src/layers/military/state.js index 9bdf2684c..0bccf9e84 100644 --- a/src/layers/military/state.js +++ b/src/layers/military/state.js @@ -282,6 +282,11 @@ export function createFlightState({ source, services }) { flightState._drCourseHold = false; + /** Set by `_deadReckon`: following the clock, the time drawn is well + * before the contact's first fix, so the fleet pass does not draw it. */ + + flightState._drUnseen = false; + /** Frame-cached course for the tracked aircraft (sibling of _cachedDRPosition). */ flightState._cachedDRCourse = null; diff --git a/src/layers/vessels/cockpitSubject.test.mjs b/src/layers/vessels/cockpitSubject.test.mjs index 784749b37..ebbc3c858 100644 --- a/src/layers/vessels/cockpitSubject.test.mjs +++ b/src/layers/vessels/cockpitSubject.test.mjs @@ -101,7 +101,10 @@ test('the subject says whether its track is the heading or the course', () => { test('a vessel without identity or position is not a subject', () => { assert.equal(vesselCockpitInfo(null), null); assert.equal(vesselCockpitInfo({ lat: 1, lon: 1 }), null); - assert.equal(vesselCockpitInfo({ id: '1', mmsi: '1', lat: 'x', lon: 1 }), null); + assert.equal( + vesselCockpitInfo({ id: '1', mmsi: '1', lat: 'x', lon: 1 }), + null, + ); }); test('a vessel missing from recent refreshes reads as stale', () => { diff --git a/src/layers/vessels/ingestion.js b/src/layers/vessels/ingestion.js index 2eb2d34f0..008507d01 100644 --- a/src/layers/vessels/ingestion.js +++ b/src/layers/vessels/ingestion.js @@ -39,8 +39,9 @@ export function createIngestion({ * @returns {Promise} */ async function loadAt(atMs, { signal = null, replace = false } = {}) { - // Whatever polls or loads for another time no longer applies. - if (replace && feed.loading) { + // Whatever polls or loads for another time no longer applies: the + // timeline asks for one time at a time. + if (feed.loading) { feed.abort?.abort(); feed.loading = false; feed.abort = null; @@ -209,6 +210,7 @@ export function createIngestion({ reference: record.reference, lat: record.latitude, lon: record.longitude, + fixes: record.fixes, name: record.name, imo: record.imo, type: record.type, diff --git a/src/layers/vessels/motion.js b/src/layers/vessels/motion.js index f4efb7d18..83e463ffc 100644 --- a/src/layers/vessels/motion.js +++ b/src/layers/vessels/motion.js @@ -1,14 +1,39 @@ /** * Where a vessel is at world time `tMs` while the layer follows the world - * clock: between the fix it moved from and the fix it moved to, along the - * great circle; at the earlier fix before it, at the newer fix after it. A - * vessel is never projected past its newest fix. + * clock: on its own fixes around the time when its record carries them + * (`fixes`, see src/time/timelineFixes.js), else between the fix it moved + * from and the fix it moved to; along the great circle between two fixes, at + * the first before them and at the last after them. A vessel is never + * projected past its newest fix. * @param {{lat: number, lon: number, motion?: {fromLat: number, fromLon: number, * fromMs: number, toLat: number, toLon: number, toMs: number}|null}} record * @param {number} tMs * @returns {{lat: number, lon: number}} */ export function vesselPositionAt(record, tMs) { + const fixes = record?.fixes; + if (fixes?.length >= 2 && Number.isFinite(tMs)) { + const first = fixes[0]; + const last = fixes[fixes.length - 1]; + if (tMs <= first.atMs) return { lat: first.lat, lon: first.lon }; + if (tMs >= last.atMs) return { lat: last.lat, lon: last.lon }; + let low = 1; + let high = fixes.length - 1; + while (low < high) { + const mid = (low + high) >> 1; + if (fixes[mid].atMs < tMs) low = mid + 1; + else high = mid; + } + const a = fixes[low - 1]; + const b = fixes[low]; + return greatCircleAt( + a.lat, + a.lon, + b.lat, + b.lon, + b.atMs > a.atMs ? (tMs - a.atMs) / (b.atMs - a.atMs) : 1, + ); + } const motion = record?.motion; if ( !motion || @@ -60,3 +85,28 @@ function unit(lat, lon) { Math.sin(phi), ]; } + +// Whether each fixes array moves, read once per array: records keep theirs +// until a snapshot brings new ones. +const moving = new WeakMap(); + +/** + * Whether a vessel's fixes (`record.fixes`) put it in more than one place, + * so following the clock moves it; a moored vessel's do not. + * @param {Array<{lat: number, lon: number}>|null|undefined} fixes + * @returns {boolean} + */ +export function fixesMove(fixes) { + if (!fixes?.length) return false; + let moves = moving.get(fixes); + if (moves === undefined) { + const [first] = fixes; + moves = fixes.some( + (fix) => + Math.abs(fix.lat - first.lat) > 1e-6 || + Math.abs(fix.lon - first.lon) > 1e-6, + ); + moving.set(fixes, moves); + } + return moves; +} diff --git a/src/layers/vessels/motion.test.mjs b/src/layers/vessels/motion.test.mjs index f5370ae85..79378853f 100644 --- a/src/layers/vessels/motion.test.mjs +++ b/src/layers/vessels/motion.test.mjs @@ -1,6 +1,6 @@ import test from 'node:test'; import assert from 'node:assert/strict'; -import { vesselPositionAt } from './motion.js'; +import { fixesMove, vesselPositionAt } from './motion.js'; const record = { lat: 1, @@ -29,3 +29,35 @@ test('a vessel with no move is at its record', () => { assert.equal(vesselPositionAt(still, 2_000), still); assert.equal(vesselPositionAt({ ...still, motion: null }, 2_000).lat, 4); }); + +test('a vessel with fixes around the time is placed on them, held at either end', () => { + const tracked = { + lat: 9, + lon: 9, + motion: record.motion, + fixes: [ + { atMs: 1_000, lat: 0, lon: 0, altitudeM: null }, + { atMs: 2_000, lat: 1, lon: 0, altitudeM: null }, + { atMs: 4_000, lat: 1, lon: 2, altitudeM: null }, + ], + }; + assert.deepEqual(vesselPositionAt(tracked, 0), { lat: 0, lon: 0 }); + assert.deepEqual(vesselPositionAt(tracked, 9_000), { lat: 1, lon: 2 }); + const back = vesselPositionAt(tracked, 1_500); + assert.ok(Math.abs(back.lat - 0.5) < 1e-3 && Math.abs(back.lon) < 1e-6); + const on = vesselPositionAt(tracked, 3_000); + assert.ok(Math.abs(on.lat - 1) < 1e-3 && Math.abs(on.lon - 1) < 1e-3); +}); + +test('fixes that stay in one place do not move a vessel', () => { + const still = [ + { atMs: 0, lat: 1, lon: 2 }, + { atMs: 60_000, lat: 1, lon: 2 }, + ]; + assert.equal(fixesMove(still), false); + assert.equal( + fixesMove([...still, { atMs: 90_000, lat: 1.001, lon: 2 }]), + true, + ); + assert.equal(fixesMove(null), false); +}); diff --git a/src/layers/vessels/records.js b/src/layers/vessels/records.js index a076368d4..c0ad357e8 100644 --- a/src/layers/vessels/records.js +++ b/src/layers/vessels/records.js @@ -1,3 +1,7 @@ +import { + mergeTimelineRuns, + readTimelineFixes, +} from '../../time/timelineFixes.js'; import { PARTIAL_RETENTION_MS, SELECTED_PIN_REFRESHES, @@ -35,6 +39,9 @@ export function normalizeVessel(row) { virtual: row.virtual === true, lastPositionUtc: String(row.last_position_UTC || ''), lastPositionEpoch: finiteNumber(row.last_position_epoch), + // Its own track around the time, from a snapshot at a time (see + // src/time/timelineFixes.js); null when the row carries none. + fixes: readTimelineFixes(row.fixes), missedRefreshes: 0, }; } @@ -146,8 +153,22 @@ export class VesselRecords { record.fixReceivedAtMs = next.fixReceivedAtMs; record.fixFeedEpoch = next.fixFeedEpoch; } - if (replace) record.motion = null; - else if (follow) record.motion = motionBetween(record, next); + if (replace) { + record.motion = null; + record.fixes = next.fixes; + } else if (follow) { + record.motion = motionBetween(record, next); + // Without fixes now, it is placed by its record, not by fixes + // that end before it. + record.fixes = next.fixes + ? mergeTimelineRuns( + record.fixes ?? [], + next.fixes, + (fix) => fix.atMs, + (next.lastPositionEpoch ?? 0) * 1000, + ) + : null; + } else record.fixes = null; record.reference = next.reference; record.mmsi = next.mmsi; record.receivedAtMs = next.receivedAtMs; diff --git a/src/layers/vessels/records.test.mjs b/src/layers/vessels/records.test.mjs index d531ff532..3fba36944 100644 --- a/src/layers/vessels/records.test.mjs +++ b/src/layers/vessels/records.test.mjs @@ -181,3 +181,15 @@ test('an AIS row with no id is keyed by its MMSI; one with neither is unkeyed', assert.equal(probe.store.byId.size, 0); assert.equal(probe.store.unkeyed.length, 2); }); + +const fixes = (...pairs) => + pairs.map(([atMs, lat]) => ({ atMs, lat, lon: 4.05, altitudeM: null })); + +test('following the clock, a vessel whose next record carries no fixes is placed by the record', () => { + const probe = setup(); + probe.reconcile([row('111', { fixes: fixes([0, 1], [60_000, 2]) })], { + replace: true, + }); + probe.reconcile([row('111', { lat: 3 })], { follow: true }); + assert.equal(probe.store.byId.get('111').fixes, null); +}); diff --git a/src/layers/vessels/renderGovernor.test.mjs b/src/layers/vessels/renderGovernor.test.mjs index c5ce2e855..90ee46993 100644 --- a/src/layers/vessels/renderGovernor.test.mjs +++ b/src/layers/vessels/renderGovernor.test.mjs @@ -124,6 +124,26 @@ test('a camera that stops inside the cadence gets exactly one trailing frame', ( assert.equal(timers.size, 0); }); +test('following the clock, a time moved inside the cadence gets one trailing frame', () => { + const { layer, requests, timers, advance, frame } = setup(); + layer.testing._followClockForTest(1_000_000); + frame(); + advance(100); + // A seek while paused: the camera is still, the time drawn is not. + layer.testing._followClockForTest(940_000); + frame(); + assert.equal(timers.size, 1); + advance(VISIBILITY_UPDATE_MS); + assert.deepEqual(requests, ['ais-vessels-visibility']); + frame(); + for (let i = 0; i < 20; i += 1) { + advance(100); + frame(); + } + assert.deepEqual(requests, ['ais-vessels-visibility']); + assert.equal(timers.size, 0); +}); + test('a forced pass requests its own frame', () => { const { layer, requests } = setup(); layer.testing._runVisibilityPassForTest(true); diff --git a/src/layers/vessels/rendering.js b/src/layers/vessels/rendering.js index ec123cc8f..e9d2ada62 100644 --- a/src/layers/vessels/rendering.js +++ b/src/layers/vessels/rendering.js @@ -22,7 +22,8 @@ import { CARD_MIN_SEP_PX, followsClock, } from './policy.js'; -import { vesselPositionAt } from './motion.js'; +import { fixesMove, vesselPositionAt } from './motion.js'; +import { TIMELINE_UNSEEN_MS } from '../../time/timelineFixes.js'; import { fleetModelSet, loadFleetModelSet, @@ -190,7 +191,7 @@ export function createRendering({ function addRecordPrimitives(record, occluder) { const visible = state.feed.enabled && - isVisible(getVisual(record).surfacePosition, occluder); + isVisible(getVisual(record).surfacePosition, occluder, record); getVisual(record).billboard = state.billboardCollection.add({ position: getVisual(record).position, show: visible, @@ -319,7 +320,7 @@ export function createRendering({ function billboardShown(record, occluder) { const visual = getVisual(record); return ( - isVisible(visual.surfacePosition, occluder) && + isVisible(visual.surfacePosition, occluder, record) && record.id !== state.cockpitSubjectId && !visual.modelOwnsVisual ); @@ -343,7 +344,7 @@ export function createRendering({ item.position = getVisual(record).waterline; // An aid to navigation is a fixed mark: it does not turn to a heading. item.headingDeg = item.spec?.fixed ? 0 : vesselCourseDeg(record); - item.show = record.id !== state.cockpitSubjectId; + item.show = record.id !== state.cockpitSubjectId && seenYet(record); return item; } @@ -461,7 +462,7 @@ export function createRendering({ motion.wallMs - hiddenFollowedAtWallMs >= HIDDEN_FOLLOW_MS; if (moveHidden) hiddenFollowedAtWallMs = motion.wallMs; for (const record of state.records.all) { - if (!record.motion) continue; + if (!record.motion && !fixesMove(record.fixes)) continue; let visual = visualRecords.get(record); if (!visual?.position) { visual = prepareRecordVisual(record); @@ -623,14 +624,23 @@ export function createRendering({ const focusPass = focusPassIsNeeded(focusTarget, state.activeFocusCount) && (force || now - state.lastFocusUpdate >= FOCUS_UPDATE_MS); + // Following the clock, the time drawn decides which vessels are there + // yet: a time that moved since the last pass (a seek while paused) gets + // its pass too. + const worldMs = followsClock(vesselState) ? vesselState.worldNow() : null; if ( !regularPass && - state.viewer?.camera && - cameraPoseSignature(state.viewer.camera) !== vesselState._lastCamPoseSig + ((state.viewer?.camera && + cameraPoseSignature(state.viewer.camera) !== + vesselState._lastCamPoseSig) || + worldMs !== state.visibilityWorldMs) ) scheduleTrailingVisibilityPass(now); if (!regularPass && !focusPass) return; - if (regularPass) state.lastVisibilityUpdate = now; + if (regularPass) { + state.lastVisibilityUpdate = now; + state.visibilityWorldMs = worldMs; + } if (focusPass) state.lastFocusUpdate = now; if (!state.records.all.length) { // No records — flush any lingering card entries (vanished-feed case). @@ -662,7 +672,7 @@ export function createRendering({ const labelCandidates = []; for (const record of state.records.all) { const visual = getVisual(record); - const visible = isVisible(visual.surfacePosition, occluder); + const visible = isVisible(visual.surfacePosition, occluder, record); if (visual.billboard) { // The bridge camera sits on this sprite; showing it would fill the view. // The same rule as billboardShown, its horizon test already made. @@ -786,11 +796,23 @@ export function createRendering({ ); } - function isVisible(surfacePosition, occluder) { + function isVisible(surfacePosition, occluder, record) { + if (record && !seenYet(record)) return false; if (!surfacePosition || !occluder) return true; return occluder.isPointVisible(surfacePosition); } + /** Whether a vessel is there at the time drawn: following the clock, not + * more than TIMELINE_UNSEEN_MS before its first fix. */ + function seenYet(record) { + const first = record.fixes?.[0]; + return ( + !first || + !followsClock(vesselState) || + vesselState.worldNow() >= first.atMs - TIMELINE_UNSEEN_MS + ); + } + /** * Source selector for the shared world-overlay pipeline: the * grid declutter picks which vessels get cards — one winner per screen-space diff --git a/src/layers/vessels/state.js b/src/layers/vessels/state.js index 8875d706e..3ed51e88d 100644 --- a/src/layers/vessels/state.js +++ b/src/layers/vessels/state.js @@ -81,6 +81,8 @@ export function createVesselState({ source, services }) { /** Pending timer that renders one frame after a cadence-skipped pass. */ trailingVisibilityTimer: null, lastVisibilityUpdate: 0, + /** Following the clock, the world time the last visibility pass drew. */ + visibilityWorldMs: null, lastFocusUpdate: 0, /** Sprites whose animated emphasis remains outside the 1.0 deadband. */ activeFocusCount: 0, diff --git a/src/layers/vessels/testing.js b/src/layers/vessels/testing.js index 197d41b5e..c0268494b 100644 --- a/src/layers/vessels/testing.js +++ b/src/layers/vessels/testing.js @@ -181,6 +181,13 @@ export function createTesting({ components.rendering.followClockPositions(); } + /** Follow the world clock, standing at world time `atMs`. Test-only seam. */ + + function _followClockForTest(atMs) { + vesselState.timeline = { active: () => true }; + vesselState.worldNow = () => atMs; + } + /** True while a trailing visibility frame is scheduled. Test-only seam. */ function _hasTrailingVisibilityPassForTest() { @@ -203,6 +210,7 @@ export function createTesting({ return { _bindVesselInteractionForTest, _setVesselStateForTest, + _followClockForTest, _setVesselOverlayHostForTest, _updateVesselCardsForTest, _reconcileVesselsForTest, diff --git a/src/sources/live/contract.js b/src/sources/live/contract.js index e201fc8de..718d1faf2 100644 --- a/src/sources/live/contract.js +++ b/src/sources/live/contract.js @@ -24,6 +24,13 @@ * freshness and staleness judged against `atMs`, and `atMs` echoed back. A * vessel snapshot at a time reports `transportStatus: 'live'`. getTrack then * receives `{ signal, atMs }` and returns only points at or before `atMs`. + * + * A timeline that declares `spanMs` lets each record of a snapshot at a time + * carry `fixes`: `{atMs, lat, lon, altitudeM?}` in time order, its own track + * from `spanMs` before the time to `spanMs` after it (see + * src/time/timelineFixes.js). The layer places the contact on them at any + * time they span, earlier ones too, so the clock can move within them, + * forwards or back, without a new snapshot. */ // Messages are English data (AI tools read them too); the Layers panel shows // them translated by their shape (translateFeedError in src/ui/statusText.js), @@ -164,10 +171,13 @@ export function httpError(response, source) { * null while it does not know yet; `stepMs` is the spacing of its snapshots; * the optional `subscribe(listener)` tells of a change in coverage, or of a * better answer for a time already answered (a paused layer then loads the - * time shown again), and returns the unsubscribe. + * time shown again), and returns the unsubscribe. The optional `spanMs` is + * how far either side of its time a snapshot's records carry their `fixes` + * (0 when they carry none). * @param {object|null|undefined} source * @returns {{coverage: () => ({start: number, end: number}|null), - * stepMs: number, subscribe: ((listener: () => void) => () => void)|null}|null} + * stepMs: number, spanMs: number, + * subscribe: ((listener: () => void) => () => void)|null}|null} */ export function readSnapshotTimeline(source) { const timeline = source?.timeline; @@ -177,9 +187,14 @@ export function readSnapshotTimeline(source) { if (!Number.isFinite(stepMs) || stepMs <= 0) return null; if (timeline.subscribe != null && typeof timeline.subscribe !== 'function') return null; + const spanMs = + Number.isFinite(timeline.spanMs) && timeline.spanMs > 0 + ? timeline.spanMs + : 0; return { coverage: () => timeline.coverage(), stepMs, + spanMs, subscribe: timeline.subscribe ? (listener) => timeline.subscribe(listener) : null, diff --git a/src/time/snapshotTimeline.js b/src/time/snapshotTimeline.js index f270e49e7..98f360c97 100644 --- a/src/time/snapshotTimeline.js +++ b/src/time/snapshotTimeline.js @@ -1,4 +1,5 @@ import { readSnapshotTimeline } from '../sources/live/contract.js'; +import { TIMELINE_HELD_MS } from './timelineFixes.js'; /** The longest play waits on a snapshot before it goes on without it. */ export const SNAPSHOT_WAIT_MS = 8_000; @@ -23,6 +24,16 @@ export const SNAPSHOT_RETRY_MS = 5_000; * step as the clock nears the newest it has, and play does not pass a * snapshot still loading (for at most SNAPSHOT_WAIT_MS). Those snapshots * are applied as polls are (`replace: false`), so contacts move on smoothly. + * - When the source's timeline declares `spanMs`, its records carry their + * fixes from `spanMs` before a snapshot's time to `spanMs` after it, and + * the layer places each contact on them by the clock. A seek or a move + * back that stays within the fixes the loaded snapshots carry is then no + * jump: nothing is cleared, play does not wait, and contacts move to the + * time smoothly. A move to a step before the newest loaded asks for that + * step once (`replace: true`): it brings back the contacts that left + * after it and drops those not there yet, while those it has keep their + * place, as their fixes put them. Paused, a time nearing the end of the + * fixes after the newest asks for the snapshot there (`replace: false`). * - Outside the source's coverage the layer is `clear()`ed and nothing loads; * while the coverage is not known yet nothing loads and nothing is cleared. * - Back at live, the layer is `clear()`ed and `resumeLive()` polls at once. @@ -61,8 +72,11 @@ export function createSnapshotTimeline({ // Each request's number; an answer to an older one is dropped. let sequence = 0; let inflight = null; - // The time of the newest snapshot applied since the last jump. + // The times of the newest and oldest snapshots applied since the last jump. let lead = null; + let base = null; + // The step a move back last asked for, until a newer snapshot applies. + let scrubbed = null; // Cleared for a time outside coverage, so it is not cleared again. let empty = false; let waiting = null; @@ -135,23 +149,27 @@ export function createSnapshotTimeline({ clear(); }; - function request(atMs, replace) { + // `quiet`: a move within the loaded fixes, which shows the contacts + // already: play does not wait for it, and its failure clears nothing. + function request(atMs, replace, quiet = false) { // One load at a time: an older one is dropped before a newer starts. inflight?.controller.abort(); const mine = ++sequence; const controller = new AbortController(); - inflight = { atMs, controller }; + inflight = { atMs, controller, quiet }; const failed = () => { inflight = null; // A time that could not be shown shows nothing, not another time. - if (replace) clearOnce(); + if (replace && !quiet) clearOnce(); + // Asked again once the retry is due. + if (quiet) scrubbed = null; capped = false; stopWaiting(); failedUntil = now() + SNAPSHOT_RETRY_MS; stopRetry(); retryTimer = setTimeout(() => { retryTimer = null; - if (started) follow(clock.getState()); + resume(); }, SNAPSHOT_RETRY_MS); }; // The source dropped this request for a newer one of its own: nothing @@ -159,10 +177,11 @@ export function createSnapshotTimeline({ // as the clock next moves, or shortly. const superseded = () => { inflight = null; + if (quiet) scrubbed = null; stopRetry(); retryTimer = setTimeout(() => { retryTimer = null; - if (started) follow(clock.getState()); + resume(); }, SNAPSHOT_RETRY_MS); }; Promise.resolve() @@ -175,7 +194,7 @@ export function createSnapshotTimeline({ return; } inflight = null; - lead = atMs; + held(atMs, replace); empty = false; capped = false; stopWaiting(); @@ -193,10 +212,87 @@ export function createSnapshotTimeline({ ); } + // The snapshot at `atMs` is applied: the stretch of snapshot times loaded + // (`base` to `lead`) takes it in. One the stretch does not reach with its + // fixes (play went on without waiting, far past the newest) starts it + // afresh: the contacts have no fixes for the time between. The stretch is + // kept to TIMELINE_HELD_MS, from the end just loaded, which every + // contact's fixes still cover. + function held(atMs, replace) { + const reach = 2 * (timeline.spanMs || 0); + scrubbed = null; + if ( + replace || + lead === null || + atMs > lead + reach || + atMs < base - reach + ) { + lead = atMs; + base = atMs; + return; + } + lead = Math.max(lead, atMs); + base = Math.min(base, atMs); + if (lead - base <= TIMELINE_HELD_MS) return; + if (atMs === lead) base = lead - TIMELINE_HELD_MS; + else lead = base + TIMELINE_HELD_MS; + } + + // Ask again for what the time needs, after a failure or a dropped load: + // a time within the loaded fixes may still need a snapshot near their end. + function resume() { + if (!started) return; + const state = clock.getState(); + if (!state.live && wasActive && heldAt(state.timeMs)) + scrubTo(state.timeMs, state); + else follow(state); + } + + // Whether the fixes of the snapshots loaded since the last jump span the + // time, so contacts can be placed there without a jump. + const heldAt = (timeMs) => + timeline.spanMs > 0 && + lead !== null && + base !== null && + timeMs >= base - timeline.spanMs && + timeMs <= lead + timeline.spanMs; + + // The clock moved to a time the loaded fixes span: contacts move there as + // they are. A step before the newest loaded is asked for once, in place + // of every contact; paused, a time in the outer half of the fixes after + // the newest asks for the snapshot at its step, which brings those beyond. + function scrubTo(timeMs, state) { + const covered = span(); + if (!covered) return; + if (!within(timeMs, covered)) { + cancel(); + lead = null; + base = null; + setGate(null); + clearOnce(); + return; + } + const half = timeline.spanMs / 2; + const step = Math.max(covered.start, stepAtOrBefore(timeMs)); + if (step < lead) { + if (step !== scrubbed && now() >= failedUntil) { + scrubbed = step; + if (inflight?.atMs !== step) request(step, true, true); + } + return; + } + if (!playsOn(state) && timeMs > lead + half && step > lead) { + if (inflight?.atMs !== step && now() >= failedUntil) request(step, false); + return; + } + keepUp(timeMs, state); + } + // Show the time afresh: the snapshot at its step replaces every contact. function jumpTo(timeMs) { cancel(); lead = null; + base = null; setGate(null); const covered = span(); if (!covered) return; @@ -215,12 +311,14 @@ export function createSnapshotTimeline({ if (!within(timeMs, covered)) { cancel(); lead = null; + base = null; setGate(null); clearOnce(); return; } if (inflight) { - if (playsOn(state) && timeMs >= inflight.atMs) startWaiting(); + if (playsOn(state) && timeMs >= inflight.atMs && !inflight.quiet) + startWaiting(); return; } if (now() < failedUntil) return; @@ -246,7 +344,10 @@ export function createSnapshotTimeline({ return; } setGate(capped ? null : next); - request(next, false); + // Past what the loaded fixes reach (play went on without waiting), the + // contacts have no fixes for the time between: the step stands in for + // them all. + request(next, timeline.spanMs > 0 && next > lead + 2 * timeline.spanMs); } function follow(state) { @@ -259,6 +360,7 @@ export function createSnapshotTimeline({ cancel(); setGate(null); lead = null; + base = null; empty = false; failedUntil = -Infinity; clear(); @@ -266,6 +368,8 @@ export function createSnapshotTimeline({ return; } const timeMs = state.timeMs; + // Away from live already: a move may stay within the loaded fixes. + const wasFollowing = wasActive; const jumped = !wasActive || state.jumps !== lastJumps || @@ -273,7 +377,8 @@ export function createSnapshotTimeline({ wasActive = true; lastJumps = state.jumps; lastTimeMs = timeMs; - if (jumped) { + if (jumped && wasFollowing && heldAt(timeMs)) scrubTo(timeMs, state); + else if (jumped) { failedUntil = -Infinity; jumpTo(timeMs); } else keepUp(timeMs, state); @@ -303,6 +408,7 @@ export function createSnapshotTimeline({ lastJumps = null; lastTimeMs = null; lead = null; + base = null; empty = false; failedUntil = -Infinity; gated = undefined; @@ -330,6 +436,7 @@ export function createSnapshotTimeline({ setGate(null); wasActive = false; lead = null; + base = null; for (const release of releases.splice(0).reverse()) release(); timeline = null; }, diff --git a/src/time/snapshotTimeline.test.mjs b/src/time/snapshotTimeline.test.mjs index 6e053b611..026c17414 100644 --- a/src/time/snapshotTimeline.test.mjs +++ b/src/time/snapshotTimeline.test.mjs @@ -10,7 +10,7 @@ import { const STEP = 10_000; const WALL = Date.UTC(2026, 10, 1, 12); -function harness({ timeline = true, coverage } = {}) { +function harness({ timeline = true, coverage, spanMs } = {}) { const t = { wall: WALL, mono: 1_000, @@ -34,6 +34,7 @@ function harness({ timeline = true, coverage } = {}) { timeline: { coverage: () => span, stepMs: STEP, + ...(spanMs && { spanMs }), subscribe(listener) { coverageListeners.add(listener); return () => coverageListeners.delete(listener); @@ -335,3 +336,215 @@ test('a source that tells of a better answer has the paused time loaded again, n assert.equal(loads(h.calls).length, live, 'live, nothing is loaded'); h.follower.stop(); }); + +test('with fixes either side, a move back within them asks for its step once, clearing nothing and holding nothing', async () => { + const SPAN = 5 * STEP; + const h = harness({ spanMs: SPAN }); + h.follower.start(); + const at = WALL - 600_000; + h.clock.seek(at); + await flush(); + await h.answer(); + assert.equal(loads(h.calls).length, 1); + // Within the step loaded: the contacts move along their fixes. + h.clock.seek(at + STEP / 2); + h.clock.seek(at + 1_000); + await flush(); + assert.equal(loads(h.calls).length, 1); + // Back two steps: the contacts move along their fixes, and the step there + // stands in for every contact once it loads, bringing back any that left + // after it. Nothing is cleared and play does not wait. + const before = h.calls.length; + h.clock.seek(at - 2 * STEP); + await flush(); + assert.deepEqual(h.calls.slice(before), [ + { type: 'load', atMs: at - 2 * STEP, replace: true }, + ]); + assert.equal(h.clock.getState().buffering, false); + // Moving within that step while it loads asks for nothing more. + h.clock.seek(at - 2 * STEP + 1_000); + await flush(); + assert.equal(loads(h.calls).length, 2); + await h.answer(); + h.clock.seek(at - 2 * STEP + 2_000); + await flush(); + assert.equal(loads(h.calls).length, 2); + // Playing on from there asks for the next step, as play does. + h.clock.play(); + h.advance(STEP - 2_000); + h.clock.coverageChanged(); + await flush(); + assert.deepEqual(loads(h.calls).at(-1), { + type: 'load', + atMs: at - STEP, + replace: false, + }); + await h.answer(); + h.clock.pause(); + // Paused past the outer half after the newest: the step there. + const newest = loads(h.calls).at(-1).atMs; + h.clock.seek(newest + 3 * STEP + 1_000); + await flush(); + assert.deepEqual(loads(h.calls).at(-1), { + type: 'load', + atMs: newest + 3 * STEP, + replace: false, + }); + await h.answer(); + // Beyond the fixes is a jump: the time is shown afresh, play held. + h.clock.seek(at - 60 * STEP); + await flush(); + assert.deepEqual(loads(h.calls).at(-1), { + type: 'load', + atMs: at - 60 * STEP, + replace: true, + }); + h.follower.stop(); +}); + +test('playing, a seek back within the fixes does not hold play on its step', async () => { + const SPAN = 5 * STEP; + const h = harness({ spanMs: SPAN }); + h.follower.start(); + const at = WALL - 600_000; + h.clock.seek(at); + await flush(); + await h.answer(); + h.clock.play(); + h.clock.seek(at - 2 * STEP + 1_000); + await flush(); + assert.equal(loads(h.calls).at(-1).atMs, at - 2 * STEP); + h.advance(STEP / 4); + h.clock.coverageChanged(); + await flush(); + assert.equal(h.clock.getState().buffering, false); + h.follower.stop(); +}); + +test('without a span every move back is a jump', async () => { + const h = harness(); + h.follower.start(); + const at = WALL - 600_000; + h.clock.seek(at); + await flush(); + await h.answer(); + h.clock.seek(at - STEP); + await flush(); + assert.deepEqual(loads(h.calls).at(-1), { + type: 'load', + atMs: at - STEP, + replace: true, + }); + h.follower.stop(); +}); + +test('a snapshot the loaded fixes do not reach starts the held stretch afresh', async () => { + const SPAN = 5 * STEP; + const h = harness({ spanMs: SPAN }); + h.follower.start(); + const at = WALL - 1_200_000; + h.clock.seek(at); + await flush(); + await h.answer(); + h.clock.play(); + h.advance(100); + h.clock.coverageChanged(); + await flush(); + // The next step is slow: play goes on without it, far past the fixes. + h.advance(2 * STEP); + h.clock.coverageChanged(); + h.advance(SNAPSHOT_WAIT_MS); + h.advance(30 * STEP); + h.clock.coverageChanged(); + await h.answer(); + const far = loads(h.calls).at(-1).atMs; + assert.ok(far > at + STEP + 2 * SPAN, 'asked for a step past the fixes'); + assert.equal( + loads(h.calls).at(-1).replace, + true, + 'in place of every contact', + ); + await h.answer(); + h.clock.pause(); + // Back between the two: no snapshot's fixes cover it, so it is a jump. + h.clock.seek(at + SPAN + 2 * STEP); + await flush(); + assert.equal(loads(h.calls).at(-1).replace, true); + h.follower.stop(); +}); + +test('the held stretch is kept to the newest stretch every contact covers', async () => { + const SPAN = 5 * STEP; + const h = harness({ + spanMs: SPAN, + coverage: { start: WALL - 6 * 3_600_000, end: WALL }, + }); + h.follower.start(); + const at = WALL - 3 * 3_600_000; + h.clock.seek(at); + await flush(); + await h.answer(); + h.clock.play(); + // Playing on for well over TIMELINE_HELD_MS, a step at a time. + for (let k = 0; k < 160; k++) { + h.advance(STEP); + h.clock.coverageChanged(); + await flush(); + while (h.pending.length) await h.answer(h.pending.length - 1); + } + h.clock.pause(); + // Back to the first snapshot's time: past what is held, so a jump. + h.clock.seek(at); + await flush(); + assert.equal(loads(h.calls).at(-1).replace, true); + h.follower.stop(); +}); + +test('a step a move back asked for that the source drops is asked again', async () => { + const SPAN = 5 * STEP; + const h = harness({ spanMs: SPAN }); + h.follower.start(); + const at = WALL - 600_000; + h.clock.seek(at); + await flush(); + await h.answer(); + h.clock.seek(at - 2 * STEP); + await flush(); + const asked = loads(h.calls).length; + h.pending + .shift() + .reject(Object.assign(new Error('dropped'), { name: 'AbortError' })); + await flush(); + h.advance(SNAPSHOT_RETRY_MS); + await flush(); + assert.equal(loads(h.calls).length, asked + 1); + assert.equal(loads(h.calls).at(-1).atMs, at - 2 * STEP); + h.follower.stop(); +}); + +test('a step a move back asked for that fails clears nothing and is asked again while paused', async () => { + const SPAN = 5 * STEP; + const h = harness({ spanMs: SPAN }); + h.follower.start(); + const at = WALL - 600_000; + h.clock.seek(at); + await flush(); + await h.answer(); + h.clock.seek(at - 3 * STEP - 1_000); + await flush(); + const asked = loads(h.calls).length; + await h.answer(0, false); + assert.equal( + h.calls.some((call) => call.type === 'clear'), + false, + ); + h.advance(SNAPSHOT_RETRY_MS); + await flush(); + assert.equal(loads(h.calls).length, asked + 1); + assert.deepEqual(loads(h.calls).at(-1), { + type: 'load', + atMs: at - 4 * STEP, + replace: true, + }); + h.follower.stop(); +}); diff --git a/src/time/timelineFixes.js b/src/time/timelineFixes.js new file mode 100644 index 000000000..e8b078cc3 --- /dev/null +++ b/src/time/timelineFixes.js @@ -0,0 +1,125 @@ +/** + * The fixes a snapshot at a time may carry for each contact (a record's + * `fixes`, see readSnapshotTimeline in src/sources/live/contract.js): where + * it was in the minutes around the time, so a layer following the world + * clock places it at nearby times, earlier ones too, without asking again. + */ + +/** Most fixes a contact keeps across the snapshots that brought them. */ +export const TIMELINE_FIXES_LIMIT = 240; +/** Kept fixes are at least this far apart, so the limit spans well over an + * hour around the newest snapshot's time however dense the fixes come. */ +export const TIMELINE_FIX_SPACING_MS = 20_000; +/** + * The longest stretch of snapshot times a layer treats as loaded at once + * (see src/time/snapshotTimeline.js). With each snapshot's fixes reaching a + * span either side, it stays within what every contact keeps around the + * newest snapshot's time. + */ +export const TIMELINE_HELD_MS = 20 * 60_000; +/** + * A contact following the clock is not drawn at a time more than this + * before its first fix: it was not there yet. Within it, it is drawn + * reaching its first fix, as a contact first seen is. + */ +export const TIMELINE_UNSEEN_MS = 60_000; + +/** + * A record's fixes in time order, those with a time and a position only, + * or null when it carries fewer than two. + * @param {unknown} value + * @returns {Array<{atMs: number, lat: number, lon: number, + * altitudeM: number|null}>|null} + */ +export function readTimelineFixes(value) { + if (!Array.isArray(value)) return null; + const fixes = []; + for (const fix of value) { + const atMs = Number(fix?.atMs); + const lat = Number(fix?.lat); + const lon = Number(fix?.lon); + if ( + !Number.isFinite(atMs) || + !Number.isFinite(lat) || + !Number.isFinite(lon) || + Math.abs(lat) > 90 + ) + continue; + const altitudeM = Number(fix?.altitudeM); + fixes.push({ + atMs, + lat, + lon, + altitudeM: + fix?.altitudeM != null && Number.isFinite(altitudeM) ? altitudeM : null, + }); + } + if (fixes.length < 2) return null; + fixes.sort((a, b) => a.atMs - b.atMs); + return fixes; +} + +/** + * Two runs of entries in time order (`timeOf` reads an entry's epoch ms) as + * one: `newer` stands in for the entries of `older` within the time it + * spans, the rest of `older` is kept, and an entry closer than + * TIMELINE_FIX_SPACING_MS to the one kept before it is left out, but for + * the newest of `newer`, which is always kept. Only the `limit` entries nearest + * `centreMs` are kept, so the fixes kept span at least `limit` times that + * spacing. + * @template T + * @param {T[]} older + * @param {T[]} newer + * @param {(entry: T) => number} timeOf + * @param {number} centreMs + * @param {number} [limit] + * @returns {T[]} + */ +export function mergeTimelineRuns( + older, + newer, + timeOf, + centreMs, + limit = TIMELINE_FIXES_LIMIT, +) { + const first = newer.length ? timeOf(newer[0]) : Infinity; + const last = newer.length ? timeOf(newer[newer.length - 1]) : -Infinity; + const newest = newer[newer.length - 1]; + // Both runs in order, the older entries within the newer run's time left + // out, thinned to the spacing. + const merged = []; + const take = (entry) => { + const k = merged.length - 1; + if (k < 0 || timeOf(entry) - timeOf(merged[k]) >= TIMELINE_FIX_SPACING_MS) { + merged.push(entry); + } else if (entry === newest) { + merged[k] = entry; + } + }; + let i = 0; + let j = 0; + while (i < older.length || j < newer.length) { + if (i < older.length) { + const t = timeOf(older[i]); + if (t >= first && t <= last) { + i++; + continue; + } + if (j >= newer.length || t < timeOf(newer[j])) { + take(older[i++]); + continue; + } + } + take(newer[j++]); + } + if (merged.length <= limit) return merged; + // The window of `limit` entries nearest the centre. + let start = 0; + while ( + start + limit < merged.length && + Math.abs(timeOf(merged[start + limit]) - centreMs) < + Math.abs(timeOf(merged[start]) - centreMs) + ) + start++; + return merged.slice(start, start + limit); +} diff --git a/src/time/timelineFixes.test.mjs b/src/time/timelineFixes.test.mjs new file mode 100644 index 000000000..9ab47c184 --- /dev/null +++ b/src/time/timelineFixes.test.mjs @@ -0,0 +1,98 @@ +import test from 'node:test'; +import assert from 'node:assert/strict'; +import { mergeTimelineRuns, readTimelineFixes } from './timelineFixes.js'; + +test('fixes are read in time order, the malformed left out, and fewer than two are none', () => { + assert.equal(readTimelineFixes(undefined), null); + assert.equal(readTimelineFixes([{ atMs: 1, lat: 1, lon: 1 }]), null); + assert.deepEqual( + readTimelineFixes([ + { atMs: 3_000, lat: 3, lon: 3, altitudeM: 30 }, + { atMs: 'x', lat: 0, lon: 0 }, + { atMs: 2_000, lat: 95, lon: 2 }, + { atMs: 1_000, lat: 1, lon: 1, altitudeM: null }, + ]), + [ + { atMs: 1_000, lat: 1, lon: 1, altitudeM: null }, + { atMs: 3_000, lat: 3, lon: 3, altitudeM: 30 }, + ], + ); +}); + +test('two runs merge in order, the newer standing in for the older within its time, thinned to the spacing', () => { + const at = (atMs, from) => ({ atMs, from }); + const merged = mergeTimelineRuns( + [at(0, 'old'), at(30_000, 'old'), at(105_000, 'old'), at(160_000, 'old')], + [ + at(40_000, 'new'), + at(80_000, 'new'), + at(90_000, 'new'), + at(150_000, 'new'), + ], + (fix) => fix.atMs, + 60_000, + ); + // 40 s is too near 30 s; 90 s too near 80 s; 105 s is within the newer + // run; 160 s too near 150 s, the newest of the newer run, kept. + assert.deepEqual(merged, [ + at(0, 'old'), + at(30_000, 'old'), + at(80_000, 'new'), + at(150_000, 'new'), + ]); + const ends = mergeTimelineRuns( + [at(0, 'old')], + [at(5_000, 'new'), at(10_000, 'new')], + (fix) => fix.atMs, + 0, + ); + assert.deepEqual(ends, [at(10_000, 'new')]); +}); + +test("runs a step apart, however dense, keep a contact's fixes back over every step", () => { + const spanMs = 5 * 60_000; + for (const [stepMs, spacingMs] of [ + [10_000, 5_000], + [60_000, 5_000], + [60_000, 30_000], + ]) { + let fixes = []; + for (let t = 0; t <= 20 * 60_000; t += stepMs) { + const run = []; + for ( + let f = Math.ceil((t - spanMs) / spacingMs) * spacingMs; + f <= t + spanMs; + f += spacingMs + ) + run.push({ atMs: f }); + fixes = mergeTimelineRuns(fixes, run, (fix) => fix.atMs, t); + } + assert.equal(fixes[0].atMs, -spanMs, `${stepMs}/${spacingMs}`); + assert.equal(fixes.at(-1).atMs, 25 * 60_000); + for (let k = 1; k < fixes.length - 1; k++) + assert.ok(fixes[k].atMs - fixes[k - 1].atMs >= 20_000); + } +}); + +test('past the limit only the fixes nearest the centre are kept', () => { + const run = (from, to) => + Array.from({ length: to - from }, (_, k) => ({ + atMs: (from + k) * 60_000, + })); + const kept = mergeTimelineRuns( + run(0, 10), + run(10, 20), + (f) => f.atMs, + 15 * 60_000, + 6, + ); + assert.deepEqual( + kept.map((f) => f.atMs / 60_000), + [12, 13, 14, 15, 16, 17], + ); + const early = mergeTimelineRuns(run(0, 10), run(10, 20), (f) => f.atMs, 0, 4); + assert.deepEqual( + early.map((f) => f.atMs / 60_000), + [0, 1, 2, 3], + ); +});