Contacts move back as smoothly as they move on

A snapshot timeline may declare spanMs: each record of a snapshot at a
time then carries its own fixes from spanMs before the time to spanMs
after it. Flights, military flights and vessels following the clock are
placed on those fixes, so a seek or a move back within the fixes loaded
is no jump: nothing is cleared and play does not wait. The step there is
asked for once and stands in for every contact; those it has keep their
place. Fixes are merged across snapshots at least 20 s apart, at most
240 a contact, and a contact is not drawn more than a minute before its
first fix.
This commit is contained in:
Sameh Khamis committed 2026-11-15 09:27:31 -08:00
1 parent b8a320edce
commit 2b5fb51684
27 files changed
+1377 -182

No files matched your search

+15 -1
View File
@@ -1983,7 +1983,7 @@ layer's existing lifecycle and selection guards continue to reject late work.
### Following the world clock ### Following the world clock
A source may declare a timeline: it can answer a snapshot at a given time. 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 `readSnapshotTimeline` (`src/sources/live/contract.js`): `coverage()` returns
the span `{ start, end }` in epoch ms it can answer, or null while it does not 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 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 area at the same time. Back at live the contacts are cleared and the layer
polls at once. 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 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 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 staleness are judged against `atMs`, `atMs` is echoed back, and a vessel
+11 -1
View File
@@ -1563,6 +1563,8 @@
"src/layers/flights/records.js", "src/layers/flights/records.js",
"src/layers/flights/clockFollow.js", "src/layers/flights/clockFollow.js",
"src/time/snapshotTimeline.js", "src/time/snapshotTimeline.js",
"src/data/timelineHistory.js",
"src/time/timelineFixes.js",
"src/sources/live/contract.js", "src/sources/live/contract.js",
"src/layers/flights/recordPolicy.js", "src/layers/flights/recordPolicy.js",
"src/layers/flights/snapshotRenderer.js", "src/layers/flights/snapshotRenderer.js",
@@ -1629,6 +1631,8 @@
"src/layers/military/ingestion.js", "src/layers/military/ingestion.js",
"src/layers/military/clockFollow.js", "src/layers/military/clockFollow.js",
"src/time/snapshotTimeline.js", "src/time/snapshotTimeline.js",
"src/data/timelineHistory.js",
"src/time/timelineFixes.js",
"src/sources/live/contract.js", "src/sources/live/contract.js",
"src/layers/military/lifecycle.js", "src/layers/military/lifecycle.js",
"src/layers/military/motion.js", "src/layers/military/motion.js",
@@ -1715,6 +1719,7 @@
"src/layers/vessels/ingestion.js", "src/layers/vessels/ingestion.js",
"src/layers/vessels/motion.js", "src/layers/vessels/motion.js",
"src/time/snapshotTimeline.js", "src/time/snapshotTimeline.js",
"src/time/timelineFixes.js",
"src/time/worldClock.js", "src/time/worldClock.js",
"src/sources/live/contract.js", "src/sources/live/contract.js",
"src/layers/vessels/cameraArea.js", "src/layers/vessels/cameraArea.js",
@@ -2892,6 +2897,8 @@
"src/layers/flights/index.js", "src/layers/flights/index.js",
"src/layers/flights/clockFollow.js", "src/layers/flights/clockFollow.js",
"src/time/snapshotTimeline.js", "src/time/snapshotTimeline.js",
"src/data/timelineHistory.js",
"src/time/timelineFixes.js",
"src/layers/flights/ingestion.js", "src/layers/flights/ingestion.js",
"src/layers/flights/lifecycle.js", "src/layers/flights/lifecycle.js",
"src/layers/flights/motion.js", "src/layers/flights/motion.js",
@@ -4079,6 +4086,8 @@
"src/layers/flights/index.js", "src/layers/flights/index.js",
"src/layers/flights/clockFollow.js", "src/layers/flights/clockFollow.js",
"src/time/snapshotTimeline.js", "src/time/snapshotTimeline.js",
"src/data/timelineHistory.js",
"src/time/timelineFixes.js",
"src/sources/live/contract.js", "src/sources/live/contract.js",
"src/layers/flights/ingestion.js", "src/layers/flights/ingestion.js",
"src/layers/flights/lifecycle.js", "src/layers/flights/lifecycle.js",
@@ -4870,7 +4879,8 @@
"exports": ["./layers/vessels/records"], "exports": ["./layers/vessels/records"],
"modules": [ "modules": [
"src/layers/vessels/records.js", "src/layers/vessels/records.js",
"src/layers/vessels/recordPolicy.js" "src/layers/vessels/recordPolicy.js",
"src/time/timelineFixes.js"
], ],
"external": [] "external": []
}, },
+171
View File
@@ -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,
);
}
+147
View File
@@ -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);
});
+25 -5
View File
@@ -1,4 +1,9 @@
import * as Cesium from 'cesium'; import * as Cesium from 'cesium';
import {
historyBracketIndex,
historyUnseenAt,
liftGroundedHistory,
} from '../../data/timelineHistory.js';
import { julianAt } from '../../time/julian.js'; import { julianAt } from '../../time/julian.js';
import { import {
COURSE_HOLD_SPEED_MPS, COURSE_HOLD_SPEED_MPS,
@@ -120,6 +125,7 @@ export function createMotion({
info.renderAltitudeM >= floor - 1 info.renderAltitudeM >= floor - 1
) )
continue; continue;
const drawnM = info.renderAltitudeM;
info.renderAltitudeM = lifted; info.renderAltitudeM = lifted;
flightState._cullPositions.delete(icao24); // above the ellipsoid now (or floors say otherwise next poll) flightState._cullPositions.delete(icao24); // above the ellipsoid now (or floors say otherwise next poll)
const position = Cesium.Cartesian3.fromDegrees( const position = Cesium.Cartesian3.fromDegrees(
@@ -127,10 +133,12 @@ export function createMotion({
info.rawLat, info.rawLat,
lifted, lifted,
); );
const history = flightState._positionHistory.get(icao24); liftGroundedHistory(
const newest = history?.[history.length - 1]; flightState._positionHistory.get(icao24),
if (newest) position,
newest.position = Cesium.Cartesian3.clone(position, newest.position); drawnM,
lifted,
);
const bb = flightState._billboards.get(icao24); const bb = flightState._billboards.get(icao24);
if (bb) bb.position = position; if (bb) bb.position = position;
} }
@@ -153,6 +161,7 @@ export function createMotion({
function _deadReckon(icao24, result, sampledRenderTime) { function _deadReckon(icao24, result, sampledRenderTime) {
const info = flightState.records.data.get(icao24); const info = flightState.records.data.get(icao24);
flightState._drUnseen = false;
if (FOCUS_EVIDENCE_DEV && flightState._focusEvidenceIds.has(icao24)) { if (FOCUS_EVIDENCE_DEV && flightState._focusEvidenceIds.has(icao24)) {
const position = flightState._billboards.get(icao24)?.position; const position = flightState._billboards.get(icao24)?.position;
flightState._drCourseDeg = info?.true_track || 0; flightState._drCourseDeg = info?.true_track || 0;
@@ -198,7 +207,15 @@ export function createMotion({
); );
// Bracketing pair: interpolate — no extrapolation error, no snap-back. // 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 a = history[i - 1];
const b = history[i]; const b = history[i];
if ( if (
@@ -254,6 +271,9 @@ export function createMotion({
// the oldest fix froze the icon; extrapolating the NEWEST fix to wall-clock now made // 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.) // the icon jump back ~one poll interval the instant interpolation took over.)
const oldest = history[0]; 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( const lookbackSec = Cesium.JulianDate.secondsDifference(
oldest.time, oldest.time,
renderTime, renderTime,
+7 -3
View File
@@ -1032,6 +1032,7 @@ export function createRendering({
flightState._scratchFleetPos, flightState._scratchFleetPos,
renderTime, renderTime,
); );
const unseen = flightState._drUnseen;
// The dead-reckoned point drifts away from the fix whose cell supplied the // 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 // 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 // (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 // 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 // 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). // waiting for its floor to warm (ATL grounded contacts at geoid −31 m).
const beyondHorizon = !occluder.isPointVisible( // A contact not there yet at the time drawn is hidden as one beyond it.
flightState._cullPositions.get(icao24) || bb.position, const beyondHorizon =
); unseen ||
!occluder.isPointVisible(
flightState._cullPositions.get(icao24) || bb.position,
);
// A billboard flipping INTO view (horizon reveal while the camera idles) // A billboard flipping INTO view (horizon reveal while the camera idles)
// gets its rotation refreshed THIS tick even without a pose change — // gets its rotation refreshed THIS tick even without a pose change —
// otherwise it reappears wearing its stale (often creation-north) nose for // otherwise it reappears wearing its stale (often creation-north) nose for
+101 -68
View File
@@ -10,6 +10,10 @@ import { aircraftIcon } from '../../data/aircraftIcons.js';
import { POSITION_HISTORY_LIMIT } from './recordPolicy.js'; import { POSITION_HISTORY_LIMIT } from './recordPolicy.js';
import { followsClock } from './policy.js'; import { followsClock } from './policy.js';
import { observeLiveAircraft } from './placed.js'; import { observeLiveAircraft } from './placed.js';
import {
historyAfterTrail,
mergeAircraftTimelineFixes,
} from '../../data/timelineHistory.js';
/** Apply reconciled aircraft records to Cesium resources and follow state. */ /** Apply reconciled aircraft records to Cesium resources and follow state. */
export function createFlightSnapshotRenderer({ export function createFlightSnapshotRenderer({
@@ -101,6 +105,18 @@ export function createFlightSnapshotRenderer({
); );
const isTracked = icao24 === flightState._trackedIcao; 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. // A host-supplied placement, if any, is told every fix as taken.
observeLiveAircraft( observeLiveAircraft(
flightState, flightState,
@@ -111,80 +127,94 @@ export function createFlightSnapshotRenderer({
meta.velocity, meta.velocity,
meta.true_track, meta.true_track,
); );
if (timelineHistory) {
// 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 (isTracked) if (isTracked)
tracking._appendTrailFix(position.clone(), fixEpochMs, { for (const entry of historyAfterTrail(
nullAltitude: meta.renderAltitudeInvented === true, 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 { } else {
const modelOwnsGroundVisual = rendering._modelOwnsVisual(icao24); // Append to position history stamped with the FEED's fix epoch
if (!modelOwnsGroundVisual) { // (time_position), not client receipt time — OpenSky positions arrive
liftRepeatedGroundFix(newest, position, meta.onGround); // 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 const history = flightState._positionHistory.get(icao24);
// the historical fix reprojects the entire stale interval and snaps const newest = history[history.length - 1];
// the rendered aircraft when course or speed changes late. The stale if (!newest || Cesium.JulianDate.greaterThan(fixTime, newest.time)) {
// rules apply: none for a contact that holds at its report, a coast // Per-fix kinematics: the fix's own velocity/track ride along so the
// capped from the real report, never below the ground. It is a motion // extrapolation paths use the values that BELONG to the fix they
// aid, not a report, so it never joins the trail. // extend, not whatever the latest poll reported.
const kinematicsChanged = history.push({
newest.velocity !== meta.velocity || newest.track !== meta.true_track; time: fixTime,
const holds = staleHoldsForFix(newest, { epochMs: fixEpochMs,
onGround: meta.onGround, position: position.clone(),
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(),
velocity: meta.velocity, velocity: meta.velocity,
track: meta.true_track, 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, cachedGroundFloor,
}); });
if (synthetic) { if (kinematicsChanged && !holds) {
history.push(synthetic); const synthetic = synthesizeForwardKinematicsFix(newest, {
if (history.length > POSITION_HISTORY_LIMIT) history.shift(); // Following the clock, the snapshot's time is the moment it moves on from.
meta.turnRateDps = turnRateFromFixHistory(history); 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; // 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. // skipping the floor started a taxiing contact low and then raised it.
const delayed = motion._deadReckon(icao24, new Cesium.Cartesian3()); const delayed = motion._deadReckon(icao24, new Cesium.Cartesian3());
const unseenAtStart = flightState._drUnseen;
const displayed = const displayed =
(delayed && (delayed &&
motion._floorGroundedDisplayPosition( motion._floorGroundedDisplayPosition(
@@ -256,7 +287,9 @@ export function createFlightSnapshotRenderer({
// close (_groundDepthDistance). // close (_groundDepthDistance).
disableDepthTestDistance: rendering._groundDepthDistance(), disableDepthTestDistance: rendering._groundDepthDistance(),
id: icao24, 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); flightState._billboards.set(icao24, bb);
rendering._applyFleetBillboardPresentation(icao24, bb); rendering._applyFleetBillboardPresentation(icao24, bb);
+5
View File
@@ -321,6 +321,11 @@ export function createFlightState({ source, services }) {
flightState._drExtrapolating = false; 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). */ /** Frame-cached course for the tracked aircraft (sibling of _cachedDRPosition). */
flightState._cachedDRCourse = null; flightState._cachedDRCourse = null;
+17 -1
View File
@@ -1,4 +1,8 @@
import * as Cesium from 'cesium'; import * as Cesium from 'cesium';
import {
historyBracketIndex,
historyUnseenAt,
} from '../../data/timelineHistory.js';
import { julianAt } from '../../time/julian.js'; import { julianAt } from '../../time/julian.js';
import { import {
lerpAngleDeg, lerpAngleDeg,
@@ -61,6 +65,7 @@ export function createMotion({
*/ */
function _deadReckon(icao24, result) { function _deadReckon(icao24, result) {
flightState._drUnseen = false;
const history = flightState._positionHistory.get(icao24); const history = flightState._positionHistory.get(icao24);
const info = flightState.records.data.get(icao24); const info = flightState.records.data.get(icao24);
if (!history || history.length === 0) { if (!history || history.length === 0) {
@@ -93,7 +98,15 @@ export function createMotion({
); );
// Bracketing pair: interpolate — no extrapolation error, no snap-back. // 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 a = history[i - 1];
const b = history[i]; const b = history[i];
if ( if (
@@ -147,6 +160,9 @@ export function createMotion({
// the bracketing interpolation above with NO freeze and NO backward snap. (Holding // the bracketing interpolation above with NO freeze and NO backward snap. (Holding
// the oldest fix froze the icon until enough history accrued, then jumped.) // the oldest fix froze the icon until enough history accrued, then jumped.)
const oldest = history[0]; 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( const lookbackSec = Cesium.JulianDate.secondsDifference(
oldest.time, oldest.time,
renderTime, renderTime,
+7 -3
View File
@@ -917,6 +917,7 @@ export function createRendering({
if (icao24 === flightState._trackedIcao) continue; // tracked entity owns its own motion if (icao24 === flightState._trackedIcao) continue; // tracked entity owns its own motion
const dr = parts.motion._deadReckon(icao24, flightState._scratchFleetPos); const dr = parts.motion._deadReckon(icao24, flightState._scratchFleetPos);
const unseen = flightState._drUnseen;
// Gate the write — assigning Billboard.position dirties the whole // Gate the write — assigning Billboard.position dirties the whole
// collection's vertex buffer, so skip sub-meter moves. // collection's vertex buffer, so skip sub-meter moves.
if (dr && Cesium.Cartesian3.distanceSquared(dr, bb.position) > 1.0) { 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 // Round 6: occlusion-test a LIFTED point for contacts at/below the
// ellipsoid (mirror of flights.js — sub-ellipsoid points near the limb // ellipsoid (mirror of flights.js — sub-ellipsoid points near the limb
// read "beyond the horizon" and would hide low contacts awaiting floors). // read "beyond the horizon" and would hide low contacts awaiting floors).
const beyondHorizon = !occluder.isPointVisible( // A contact not there yet at the time drawn is hidden as one beyond it.
flightState.records.data.get(icao24)?.cullPosition || bb.position, const beyondHorizon =
); unseen ||
!occluder.isPointVisible(
flightState.records.data.get(icao24)?.cullPosition || bb.position,
);
// A billboard flipping INTO view (horizon reveal while the camera idles) // A billboard flipping INTO view (horizon reveal while the camera idles)
// gets its rotation refreshed THIS tick even without a pose change — // gets its rotation refreshed THIS tick even without a pose change —
// otherwise it reappears wearing its stale (often creation-north) nose for // otherwise it reappears wearing its stale (often creation-north) nose for
+104 -68
View File
@@ -8,6 +8,11 @@ import {
synthesizeForwardKinematicsFix, synthesizeForwardKinematicsFix,
} from '../../data/motionModel.js'; } from '../../data/motionModel.js';
import { aircraftIcon } from '../../data/aircraftIcons.js'; import { aircraftIcon } from '../../data/aircraftIcons.js';
import {
historyAfterTrail,
liftGroundedHistory,
mergeAircraftTimelineFixes,
} from '../../data/timelineHistory.js';
import { POSITION_HISTORY_LIMIT } from './recordPolicy.js'; import { POSITION_HISTORY_LIMIT } from './recordPolicy.js';
import { import {
BILLBOARD_SCALE, BILLBOARD_SCALE,
@@ -75,6 +80,18 @@ export function createMilitarySnapshotRenderer({
); );
const isTracked = icao24 === flightState._trackedIcao; 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. // A host-supplied placement, if any, is told every fix as taken.
observeLiveAircraft( observeLiveAircraft(
flightState, flightState,
@@ -85,76 +102,89 @@ export function createMilitarySnapshotRenderer({
meta.speedMps, meta.speedMps,
meta.track, meta.track,
); );
if (timelineHistory) {
// 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 (isTracked) if (isTracked)
tracking._appendTrailFix(position.clone(), fixEpochMs, { for (const entry of historyAfterTrail(
nullAltitude: meta.renderAltitudeInvented === true, 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 { } else {
const modelOwnsGroundVisual = rendering._modelOwnsVisual(icao24); // Append to position history stamped with the FEED's fix epoch.
if (!modelOwnsGroundVisual) { // adsb.lol's seen_pos is the AGE in seconds of the last position
liftRepeatedGroundFix(newest, position, meta.onGround); // 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 const history = flightState._positionHistory.get(icao24);
// contact holds at its report, a coast capped from the real report, const newest = history[history.length - 1];
// never below the ground) and is a motion aid, never a trail report. if (!newest || Cesium.JulianDate.greaterThan(fixTime, newest.time)) {
const kinematicsChanged = // Per-fix kinematics: the fix's own velocity/track ride along so the
newest.velocity !== meta.speedMps || newest.track !== meta.track; // extrapolation paths use the values that BELONG to the fix they
const holds = staleHoldsForFix(newest, { // extend, not whatever the latest poll reported.
onGround: meta.onGround, history.push({
cachedGroundFloor, time: fixTime,
}); epochMs: fixEpochMs,
if (kinematicsChanged && !holds) { position: position.clone(),
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, velocity: meta.speedMps,
track: meta.track, 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, cachedGroundFloor,
}); });
if (synthetic) { if (kinematicsChanged && !holds) {
history.push(synthetic); const synthetic = synthesizeForwardKinematicsFix(newest, {
if (history.length > POSITION_HISTORY_LIMIT) history.shift(); // Following the clock, the snapshot's time is the moment it moves on from.
meta.turnRateDps = turnRateFromFixHistory(history); 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. // it ahead until the next fleet tick snapped it back.
const displayed = const displayed =
motion._deadReckon(icao24, new Cesium.Cartesian3()) || position; motion._deadReckon(icao24, new Cesium.Cartesian3()) || position;
const unseenAtStart = flightState._drUnseen;
const bb = flightState._billboardCollection.add({ const bb = flightState._billboardCollection.add({
position: displayed, position: displayed,
image: aircraftIcon(rendering._iconKind(icao24, meta.klass)), image: aircraftIcon(rendering._iconKind(icao24, meta.klass)),
@@ -217,7 +248,9 @@ export function createMilitarySnapshotRenderer({
// close (_groundDepthDistance). // close (_groundDepthDistance).
disableDepthTestDistance: rendering._groundDepthDistance(), disableDepthTestDistance: rendering._groundDepthDistance(),
id: icao24, 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); flightState._billboards.set(icao24, bb);
rendering._applyFleetBillboardPresentation(icao24, bb); rendering._applyFleetBillboardPresentation(icao24, bb);
@@ -259,6 +292,7 @@ export function createMilitarySnapshotRenderer({
info.renderAltitudeM >= floor - 1 info.renderAltitudeM >= floor - 1
) )
continue; continue;
const drawnM = info.renderAltitudeM;
info.renderAltitudeM = lifted; info.renderAltitudeM = lifted;
flightState._cullPositions.delete(icao24); flightState._cullPositions.delete(icao24);
const liftedPos = Cesium.Cartesian3.fromDegrees( const liftedPos = Cesium.Cartesian3.fromDegrees(
@@ -266,10 +300,12 @@ export function createMilitarySnapshotRenderer({
info.rawLat, info.rawLat,
lifted, lifted,
); );
const hist = flightState._positionHistory.get(icao24); liftGroundedHistory(
const newest = hist?.[hist.length - 1]; flightState._positionHistory.get(icao24),
if (newest) liftedPos,
newest.position = Cesium.Cartesian3.clone(liftedPos, newest.position); drawnM,
lifted,
);
const bbStale = flightState._billboards.get(icao24); const bbStale = flightState._billboards.get(icao24);
if (bbStale) bbStale.position = liftedPos; if (bbStale) bbStale.position = liftedPos;
} }
+5
View File
@@ -282,6 +282,11 @@ export function createFlightState({ source, services }) {
flightState._drCourseHold = false; 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). */ /** Frame-cached course for the tracked aircraft (sibling of _cachedDRPosition). */
flightState._cachedDRCourse = null; flightState._cachedDRCourse = null;
+4 -1
View File
@@ -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', () => { test('a vessel without identity or position is not a subject', () => {
assert.equal(vesselCockpitInfo(null), null); assert.equal(vesselCockpitInfo(null), null);
assert.equal(vesselCockpitInfo({ lat: 1, lon: 1 }), 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', () => { test('a vessel missing from recent refreshes reads as stale', () => {
+4 -2
View File
@@ -39,8 +39,9 @@ export function createIngestion({
* @returns {Promise<boolean>} * @returns {Promise<boolean>}
*/ */
async function loadAt(atMs, { signal = null, replace = false } = {}) { async function loadAt(atMs, { signal = null, replace = false } = {}) {
// Whatever polls or loads for another time no longer applies. // Whatever polls or loads for another time no longer applies: the
if (replace && feed.loading) { // timeline asks for one time at a time.
if (feed.loading) {
feed.abort?.abort(); feed.abort?.abort();
feed.loading = false; feed.loading = false;
feed.abort = null; feed.abort = null;
@@ -209,6 +210,7 @@ export function createIngestion({
reference: record.reference, reference: record.reference,
lat: record.latitude, lat: record.latitude,
lon: record.longitude, lon: record.longitude,
fixes: record.fixes,
name: record.name, name: record.name,
imo: record.imo, imo: record.imo,
type: record.type, type: record.type,
+53 -3
View File
@@ -1,14 +1,39 @@
/** /**
* Where a vessel is at world time `tMs` while the layer follows the world * 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 * clock: on its own fixes around the time when its record carries them
* great circle; at the earlier fix before it, at the newer fix after it. A * (`fixes`, see src/time/timelineFixes.js), else between the fix it moved
* vessel is never projected past its newest fix. * 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, * @param {{lat: number, lon: number, motion?: {fromLat: number, fromLon: number,
* fromMs: number, toLat: number, toLon: number, toMs: number}|null}} record * fromMs: number, toLat: number, toLon: number, toMs: number}|null}} record
* @param {number} tMs * @param {number} tMs
* @returns {{lat: number, lon: number}} * @returns {{lat: number, lon: number}}
*/ */
export function vesselPositionAt(record, tMs) { 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; const motion = record?.motion;
if ( if (
!motion || !motion ||
@@ -60,3 +85,28 @@ function unit(lat, lon) {
Math.sin(phi), 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;
}
+33 -1
View File
@@ -1,6 +1,6 @@
import test from 'node:test'; import test from 'node:test';
import assert from 'node:assert/strict'; import assert from 'node:assert/strict';
import { vesselPositionAt } from './motion.js'; import { fixesMove, vesselPositionAt } from './motion.js';
const record = { const record = {
lat: 1, 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, 2_000), still);
assert.equal(vesselPositionAt({ ...still, motion: null }, 2_000).lat, 4); 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);
});
+23 -2
View File
@@ -1,3 +1,7 @@
import {
mergeTimelineRuns,
readTimelineFixes,
} from '../../time/timelineFixes.js';
import { import {
PARTIAL_RETENTION_MS, PARTIAL_RETENTION_MS,
SELECTED_PIN_REFRESHES, SELECTED_PIN_REFRESHES,
@@ -35,6 +39,9 @@ export function normalizeVessel(row) {
virtual: row.virtual === true, virtual: row.virtual === true,
lastPositionUtc: String(row.last_position_UTC || ''), lastPositionUtc: String(row.last_position_UTC || ''),
lastPositionEpoch: finiteNumber(row.last_position_epoch), 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, missedRefreshes: 0,
}; };
} }
@@ -146,8 +153,22 @@ export class VesselRecords {
record.fixReceivedAtMs = next.fixReceivedAtMs; record.fixReceivedAtMs = next.fixReceivedAtMs;
record.fixFeedEpoch = next.fixFeedEpoch; record.fixFeedEpoch = next.fixFeedEpoch;
} }
if (replace) record.motion = null; if (replace) {
else if (follow) record.motion = motionBetween(record, next); 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.reference = next.reference;
record.mmsi = next.mmsi; record.mmsi = next.mmsi;
record.receivedAtMs = next.receivedAtMs; record.receivedAtMs = next.receivedAtMs;
+12
View File
@@ -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.byId.size, 0);
assert.equal(probe.store.unkeyed.length, 2); 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);
});
@@ -124,6 +124,26 @@ test('a camera that stops inside the cadence gets exactly one trailing frame', (
assert.equal(timers.size, 0); 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', () => { test('a forced pass requests its own frame', () => {
const { layer, requests } = setup(); const { layer, requests } = setup();
layer.testing._runVisibilityPassForTest(true); layer.testing._runVisibilityPassForTest(true);
+32 -10
View File
@@ -22,7 +22,8 @@ import {
CARD_MIN_SEP_PX, CARD_MIN_SEP_PX,
followsClock, followsClock,
} from './policy.js'; } from './policy.js';
import { vesselPositionAt } from './motion.js'; import { fixesMove, vesselPositionAt } from './motion.js';
import { TIMELINE_UNSEEN_MS } from '../../time/timelineFixes.js';
import { import {
fleetModelSet, fleetModelSet,
loadFleetModelSet, loadFleetModelSet,
@@ -190,7 +191,7 @@ export function createRendering({
function addRecordPrimitives(record, occluder) { function addRecordPrimitives(record, occluder) {
const visible = const visible =
state.feed.enabled && state.feed.enabled &&
isVisible(getVisual(record).surfacePosition, occluder); isVisible(getVisual(record).surfacePosition, occluder, record);
getVisual(record).billboard = state.billboardCollection.add({ getVisual(record).billboard = state.billboardCollection.add({
position: getVisual(record).position, position: getVisual(record).position,
show: visible, show: visible,
@@ -319,7 +320,7 @@ export function createRendering({
function billboardShown(record, occluder) { function billboardShown(record, occluder) {
const visual = getVisual(record); const visual = getVisual(record);
return ( return (
isVisible(visual.surfacePosition, occluder) && isVisible(visual.surfacePosition, occluder, record) &&
record.id !== state.cockpitSubjectId && record.id !== state.cockpitSubjectId &&
!visual.modelOwnsVisual !visual.modelOwnsVisual
); );
@@ -343,7 +344,7 @@ export function createRendering({
item.position = getVisual(record).waterline; item.position = getVisual(record).waterline;
// An aid to navigation is a fixed mark: it does not turn to a heading. // An aid to navigation is a fixed mark: it does not turn to a heading.
item.headingDeg = item.spec?.fixed ? 0 : vesselCourseDeg(record); item.headingDeg = item.spec?.fixed ? 0 : vesselCourseDeg(record);
item.show = record.id !== state.cockpitSubjectId; item.show = record.id !== state.cockpitSubjectId && seenYet(record);
return item; return item;
} }
@@ -461,7 +462,7 @@ export function createRendering({
motion.wallMs - hiddenFollowedAtWallMs >= HIDDEN_FOLLOW_MS; motion.wallMs - hiddenFollowedAtWallMs >= HIDDEN_FOLLOW_MS;
if (moveHidden) hiddenFollowedAtWallMs = motion.wallMs; if (moveHidden) hiddenFollowedAtWallMs = motion.wallMs;
for (const record of state.records.all) { for (const record of state.records.all) {
if (!record.motion) continue; if (!record.motion && !fixesMove(record.fixes)) continue;
let visual = visualRecords.get(record); let visual = visualRecords.get(record);
if (!visual?.position) { if (!visual?.position) {
visual = prepareRecordVisual(record); visual = prepareRecordVisual(record);
@@ -623,14 +624,23 @@ export function createRendering({
const focusPass = const focusPass =
focusPassIsNeeded(focusTarget, state.activeFocusCount) && focusPassIsNeeded(focusTarget, state.activeFocusCount) &&
(force || now - state.lastFocusUpdate >= FOCUS_UPDATE_MS); (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 ( if (
!regularPass && !regularPass &&
state.viewer?.camera && ((state.viewer?.camera &&
cameraPoseSignature(state.viewer.camera) !== vesselState._lastCamPoseSig cameraPoseSignature(state.viewer.camera) !==
vesselState._lastCamPoseSig) ||
worldMs !== state.visibilityWorldMs)
) )
scheduleTrailingVisibilityPass(now); scheduleTrailingVisibilityPass(now);
if (!regularPass && !focusPass) return; if (!regularPass && !focusPass) return;
if (regularPass) state.lastVisibilityUpdate = now; if (regularPass) {
state.lastVisibilityUpdate = now;
state.visibilityWorldMs = worldMs;
}
if (focusPass) state.lastFocusUpdate = now; if (focusPass) state.lastFocusUpdate = now;
if (!state.records.all.length) { if (!state.records.all.length) {
// No records — flush any lingering card entries (vanished-feed case). // No records — flush any lingering card entries (vanished-feed case).
@@ -662,7 +672,7 @@ export function createRendering({
const labelCandidates = []; const labelCandidates = [];
for (const record of state.records.all) { for (const record of state.records.all) {
const visual = getVisual(record); const visual = getVisual(record);
const visible = isVisible(visual.surfacePosition, occluder); const visible = isVisible(visual.surfacePosition, occluder, record);
if (visual.billboard) { if (visual.billboard) {
// The bridge camera sits on this sprite; showing it would fill the view. // The bridge camera sits on this sprite; showing it would fill the view.
// The same rule as billboardShown, its horizon test already made. // 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; if (!surfacePosition || !occluder) return true;
return occluder.isPointVisible(surfacePosition); 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 * Source selector for the shared world-overlay pipeline: the
* grid declutter picks which vessels get cards — one winner per screen-space * grid declutter picks which vessels get cards — one winner per screen-space
+2
View File
@@ -81,6 +81,8 @@ export function createVesselState({ source, services }) {
/** Pending timer that renders one frame after a cadence-skipped pass. */ /** Pending timer that renders one frame after a cadence-skipped pass. */
trailingVisibilityTimer: null, trailingVisibilityTimer: null,
lastVisibilityUpdate: 0, lastVisibilityUpdate: 0,
/** Following the clock, the world time the last visibility pass drew. */
visibilityWorldMs: null,
lastFocusUpdate: 0, lastFocusUpdate: 0,
/** Sprites whose animated emphasis remains outside the 1.0 deadband. */ /** Sprites whose animated emphasis remains outside the 1.0 deadband. */
activeFocusCount: 0, activeFocusCount: 0,
+8
View File
@@ -181,6 +181,13 @@ export function createTesting({
components.rendering.followClockPositions(); 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. */ /** True while a trailing visibility frame is scheduled. Test-only seam. */
function _hasTrailingVisibilityPassForTest() { function _hasTrailingVisibilityPassForTest() {
@@ -203,6 +210,7 @@ export function createTesting({
return { return {
_bindVesselInteractionForTest, _bindVesselInteractionForTest,
_setVesselStateForTest, _setVesselStateForTest,
_followClockForTest,
_setVesselOverlayHostForTest, _setVesselOverlayHostForTest,
_updateVesselCardsForTest, _updateVesselCardsForTest,
_reconcileVesselsForTest, _reconcileVesselsForTest,
+17 -2
View File
@@ -24,6 +24,13 @@
* freshness and staleness judged against `atMs`, and `atMs` echoed back. A * freshness and staleness judged against `atMs`, and `atMs` echoed back. A
* vessel snapshot at a time reports `transportStatus: 'live'`. getTrack then * vessel snapshot at a time reports `transportStatus: 'live'`. getTrack then
* receives `{ signal, atMs }` and returns only points at or before `atMs`. * 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 // Messages are English data (AI tools read them too); the Layers panel shows
// them translated by their shape (translateFeedError in src/ui/statusText.js), // 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; * 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 * 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 * 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 * @param {object|null|undefined} source
* @returns {{coverage: () => ({start: number, end: number}|null), * @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) { export function readSnapshotTimeline(source) {
const timeline = source?.timeline; const timeline = source?.timeline;
@@ -177,9 +187,14 @@ export function readSnapshotTimeline(source) {
if (!Number.isFinite(stepMs) || stepMs <= 0) return null; if (!Number.isFinite(stepMs) || stepMs <= 0) return null;
if (timeline.subscribe != null && typeof timeline.subscribe !== 'function') if (timeline.subscribe != null && typeof timeline.subscribe !== 'function')
return null; return null;
const spanMs =
Number.isFinite(timeline.spanMs) && timeline.spanMs > 0
? timeline.spanMs
: 0;
return { return {
coverage: () => timeline.coverage(), coverage: () => timeline.coverage(),
stepMs, stepMs,
spanMs,
subscribe: timeline.subscribe subscribe: timeline.subscribe
? (listener) => timeline.subscribe(listener) ? (listener) => timeline.subscribe(listener)
: null, : null,
+117 -10
View File
@@ -1,4 +1,5 @@
import { readSnapshotTimeline } from '../sources/live/contract.js'; 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. */ /** The longest play waits on a snapshot before it goes on without it. */
export const SNAPSHOT_WAIT_MS = 8_000; 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 * 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 * snapshot still loading (for at most SNAPSHOT_WAIT_MS). Those snapshots
* are applied as polls are (`replace: false`), so contacts move on smoothly. * 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; * - 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. * 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. * - 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. // Each request's number; an answer to an older one is dropped.
let sequence = 0; let sequence = 0;
let inflight = null; 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 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. // Cleared for a time outside coverage, so it is not cleared again.
let empty = false; let empty = false;
let waiting = null; let waiting = null;
@@ -135,23 +149,27 @@ export function createSnapshotTimeline({
clear(); 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. // One load at a time: an older one is dropped before a newer starts.
inflight?.controller.abort(); inflight?.controller.abort();
const mine = ++sequence; const mine = ++sequence;
const controller = new AbortController(); const controller = new AbortController();
inflight = { atMs, controller }; inflight = { atMs, controller, quiet };
const failed = () => { const failed = () => {
inflight = null; inflight = null;
// A time that could not be shown shows nothing, not another time. // 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; capped = false;
stopWaiting(); stopWaiting();
failedUntil = now() + SNAPSHOT_RETRY_MS; failedUntil = now() + SNAPSHOT_RETRY_MS;
stopRetry(); stopRetry();
retryTimer = setTimeout(() => { retryTimer = setTimeout(() => {
retryTimer = null; retryTimer = null;
if (started) follow(clock.getState()); resume();
}, SNAPSHOT_RETRY_MS); }, SNAPSHOT_RETRY_MS);
}; };
// The source dropped this request for a newer one of its own: nothing // 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. // as the clock next moves, or shortly.
const superseded = () => { const superseded = () => {
inflight = null; inflight = null;
if (quiet) scrubbed = null;
stopRetry(); stopRetry();
retryTimer = setTimeout(() => { retryTimer = setTimeout(() => {
retryTimer = null; retryTimer = null;
if (started) follow(clock.getState()); resume();
}, SNAPSHOT_RETRY_MS); }, SNAPSHOT_RETRY_MS);
}; };
Promise.resolve() Promise.resolve()
@@ -175,7 +194,7 @@ export function createSnapshotTimeline({
return; return;
} }
inflight = null; inflight = null;
lead = atMs; held(atMs, replace);
empty = false; empty = false;
capped = false; capped = false;
stopWaiting(); 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. // Show the time afresh: the snapshot at its step replaces every contact.
function jumpTo(timeMs) { function jumpTo(timeMs) {
cancel(); cancel();
lead = null; lead = null;
base = null;
setGate(null); setGate(null);
const covered = span(); const covered = span();
if (!covered) return; if (!covered) return;
@@ -215,12 +311,14 @@ export function createSnapshotTimeline({
if (!within(timeMs, covered)) { if (!within(timeMs, covered)) {
cancel(); cancel();
lead = null; lead = null;
base = null;
setGate(null); setGate(null);
clearOnce(); clearOnce();
return; return;
} }
if (inflight) { if (inflight) {
if (playsOn(state) && timeMs >= inflight.atMs) startWaiting(); if (playsOn(state) && timeMs >= inflight.atMs && !inflight.quiet)
startWaiting();
return; return;
} }
if (now() < failedUntil) return; if (now() < failedUntil) return;
@@ -246,7 +344,10 @@ export function createSnapshotTimeline({
return; return;
} }
setGate(capped ? null : next); 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) { function follow(state) {
@@ -259,6 +360,7 @@ export function createSnapshotTimeline({
cancel(); cancel();
setGate(null); setGate(null);
lead = null; lead = null;
base = null;
empty = false; empty = false;
failedUntil = -Infinity; failedUntil = -Infinity;
clear(); clear();
@@ -266,6 +368,8 @@ export function createSnapshotTimeline({
return; return;
} }
const timeMs = state.timeMs; const timeMs = state.timeMs;
// Away from live already: a move may stay within the loaded fixes.
const wasFollowing = wasActive;
const jumped = const jumped =
!wasActive || !wasActive ||
state.jumps !== lastJumps || state.jumps !== lastJumps ||
@@ -273,7 +377,8 @@ export function createSnapshotTimeline({
wasActive = true; wasActive = true;
lastJumps = state.jumps; lastJumps = state.jumps;
lastTimeMs = timeMs; lastTimeMs = timeMs;
if (jumped) { if (jumped && wasFollowing && heldAt(timeMs)) scrubTo(timeMs, state);
else if (jumped) {
failedUntil = -Infinity; failedUntil = -Infinity;
jumpTo(timeMs); jumpTo(timeMs);
} else keepUp(timeMs, state); } else keepUp(timeMs, state);
@@ -303,6 +408,7 @@ export function createSnapshotTimeline({
lastJumps = null; lastJumps = null;
lastTimeMs = null; lastTimeMs = null;
lead = null; lead = null;
base = null;
empty = false; empty = false;
failedUntil = -Infinity; failedUntil = -Infinity;
gated = undefined; gated = undefined;
@@ -330,6 +436,7 @@ export function createSnapshotTimeline({
setGate(null); setGate(null);
wasActive = false; wasActive = false;
lead = null; lead = null;
base = null;
for (const release of releases.splice(0).reverse()) release(); for (const release of releases.splice(0).reverse()) release();
timeline = null; timeline = null;
}, },
+214 -1
View File
@@ -10,7 +10,7 @@ import {
const STEP = 10_000; const STEP = 10_000;
const WALL = Date.UTC(2026, 10, 1, 12); const WALL = Date.UTC(2026, 10, 1, 12);
function harness({ timeline = true, coverage } = {}) { function harness({ timeline = true, coverage, spanMs } = {}) {
const t = { const t = {
wall: WALL, wall: WALL,
mono: 1_000, mono: 1_000,
@@ -34,6 +34,7 @@ function harness({ timeline = true, coverage } = {}) {
timeline: { timeline: {
coverage: () => span, coverage: () => span,
stepMs: STEP, stepMs: STEP,
...(spanMs && { spanMs }),
subscribe(listener) { subscribe(listener) {
coverageListeners.add(listener); coverageListeners.add(listener);
return () => coverageListeners.delete(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'); assert.equal(loads(h.calls).length, live, 'live, nothing is loaded');
h.follower.stop(); 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();
});
+125
View File
@@ -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);
}
+98
View File
@@ -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],
);
});