Sprites for helicopters, ground vehicles, stations and vessel types; history to live without an empty map; model parts in Cesium

Aircraft icons are one size; helicopters turn a three-frame rotor while
airborne or moving; ADS-B ground vehicles share one amber sprite and
stations/obstacles one mast; vessels get hull sprites by type and one buoy.
Going live keeps contacts until the first live answer and replaces them by
id; fast playback holds before the loaded positions end and prefetches
ahead. Cesium models move their parts from the optional model part state.
This commit is contained in:
Sameh Khamis committed 2026-11-17 15:09:54 -08:00
1 parent 624c229bc2
commit 7186f720df
97 files changed
+6586 -343

No files matched your search

+118 -24
View File
@@ -1,10 +1,33 @@
import { readSnapshotTimeline } from '../sources/live/contract.js';
import { TIMELINE_HELD_MS } from './timelineFixes.js';
import { fixesReachMs, 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;
/** How long a snapshot that failed to load waits before it is asked again. */
export const SNAPSHOT_RETRY_MS = 5_000;
/**
* How much play keeps of the loaded fixes after the newest snapshot: it holds
* this far short of their end (at most half of them), so a contact never
* reaches the end of its fixes while the next snapshot loads.
*/
export const SNAPSHOT_HOLD_MARGIN_MS = 60_000;
/**
* How far ahead, in real time at the clock's rate, play asks for snapshots:
* at a high rate it asks several steps before the time needs them.
*/
export const SNAPSHOT_PREFETCH_MS = 4_000;
/**
* What a layer's `load` answers once it applied `snapshot`: `{ reachMs }`,
* how far its records' fixes reach (fixesReachMs), when they carry fixes;
* else true.
* @param {{records?: Array<{fixes?: unknown}>}} snapshot
* @returns {true|{reachMs: number}}
*/
export function snapshotAnswer(snapshot) {
const reachMs = fixesReachMs(snapshot?.records);
return reachMs === null ? true : { reachMs };
}
/**
* Let a layer of live contacts (flights, military aircraft, vessels) follow
@@ -26,7 +49,10 @@ export const SNAPSHOT_RETRY_MS = 5_000;
* 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
* the layer places each contact on them by the clock. Playing on, it asks
* for the next step SNAPSHOT_PREFETCH_MS of play ahead (at least a step),
* and play holds only SNAPSHOT_HOLD_MARGIN_MS short of the end of the
* newest snapshot's fixes, not at the step still loading. 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
@@ -36,17 +62,23 @@ export const SNAPSHOT_RETRY_MS = 5_000;
* 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.
* - Back at live, `resumeLive()` polls at once and its snapshot takes the
* place of every contact: those it has move on from where they are drawn,
* and only those it lacks go. The contacts stay until it answers; when it
* answers anything but true (it could not be had), the layer is `clear()`ed.
* A rejection named AbortError (a newer poll took its place) clears nothing.
*
* `load` resolves true once the snapshot is applied and false (or rejects)
* when it could not be; it must not apply anything once `signal` aborts. A
* `load` resolves true once the snapshot is applied, or `{ reachMs }` when its
* records carry fixes, the newest of them (`fixesReachMs`), and false (or
* rejects) when it could not be; it must not apply anything once `signal` aborts. A
* rejection named AbortError is a request the source dropped for a newer
* one: it is not a failure, and nothing is cleared.
*
* @param {{id: string, clock: ReturnType<typeof import('./worldClock.js').createWorldClock>,
* source: () => object|null,
* load: (atMs: number, options: {signal: AbortSignal, replace: boolean}) => Promise<boolean>,
* clear: () => void, resumeLive: () => void,
* load: (atMs: number, options: {signal: AbortSignal, replace: boolean}) =>
* Promise<boolean|{reachMs: number}>,
* clear: () => void, resumeLive: () => boolean|Promise<boolean>,
* now?: () => number, setTimeout?: typeof globalThis.setTimeout,
* clearTimeout?: typeof globalThis.clearTimeout}} options `source`
* returns the layer's current source; it is read when the layer starts.
@@ -86,6 +118,10 @@ export function createSnapshotTimeline({
let gated;
let failedUntil = -Infinity;
let retryTimer = null;
// Each return to live; an answer to an older one is dropped.
let handovers = 0;
// How far the fixes of each snapshot applied since the last jump reach.
const reaches = new Map();
const span = () => {
let covered;
@@ -194,7 +230,7 @@ export function createSnapshotTimeline({
return;
}
inflight = null;
held(atMs, replace);
held(atMs, replace, applied?.reachMs);
empty = false;
capped = false;
stopWaiting();
@@ -218,24 +254,27 @@ export function createSnapshotTimeline({
// 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) {
function held(atMs, replace, reachMs) {
const reach = 2 * (timeline.spanMs || 0);
scrubbed = null;
if (
replace ||
lead === null ||
atMs > lead + reach ||
atMs < base - reach
) {
const afresh =
replace || lead === null || atMs > lead + reach || atMs < base - reach;
if (afresh) reaches.clear();
if (Number.isFinite(reachMs)) reaches.set(atMs, reachMs);
else reaches.delete(atMs);
if (afresh) {
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;
if (lead - base > TIMELINE_HELD_MS) {
if (atMs === lead) base = lead - TIMELINE_HELD_MS;
else lead = base + TIMELINE_HELD_MS;
}
for (const at of reaches.keys())
if (at < base || at > lead) reaches.delete(at);
}
// Ask again for what the time needs, after a failure or a dropped load:
@@ -316,8 +355,12 @@ export function createSnapshotTimeline({
clearOnce();
return;
}
const hold = lead === null ? null : holdAt(covered);
if (inflight) {
if (playsOn(state) && timeMs >= inflight.atMs && !inflight.quiet)
// With fixes past the newest snapshot, play waits only at their end.
const waitsAt =
timeline.spanMs > 0 && hold !== null ? hold : inflight.atMs;
if (playsOn(state) && timeMs >= waitsAt && !inflight.quiet)
startWaiting();
return;
}
@@ -331,8 +374,8 @@ export function createSnapshotTimeline({
return;
}
const step = timeline.stepMs;
if (lead - timeMs >= step) {
setGate(lead);
if (lead - timeMs >= prefetchMs(state)) {
setGate(hold);
return;
}
const next = Math.min(
@@ -343,13 +386,62 @@ export function createSnapshotTimeline({
setGate(null);
return;
}
setGate(capped ? null : next);
setGate(capped ? null : timeline.spanMs > 0 ? hold : next);
// 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);
}
// Where play holds while the next snapshot loads: the newest loaded,
// or, with fixes past it, SNAPSHOT_HOLD_MARGIN_MS short of where they
// end: as far as that snapshot's fixes reach, at most the declared span
// (never past the coverage).
function holdAt(covered) {
const reach = timeline.spanMs || 0;
if (reach <= 0) return lead;
const margin = Math.min(SNAPSHOT_HOLD_MARGIN_MS, reach / 2);
const carried = reaches.get(lead);
const end = Number.isFinite(carried)
? Math.min(lead + reach, carried)
: lead + reach;
return Math.max(lead, Math.min(covered.end, end - margin));
}
// How far ahead of the time play asks for the next step: a step, or with
// fixes past each snapshot, SNAPSHOT_PREFETCH_MS of play at the clock's
// rate, up to where play holds.
function prefetchMs(state) {
const step = timeline.stepMs;
const reach = timeline.spanMs || 0;
if (reach <= 0) return step;
const rate = Number.isFinite(state.rate) ? Math.abs(state.rate) : 1;
const margin = Math.min(SNAPSHOT_HOLD_MARGIN_MS, reach / 2);
return Math.max(
step,
Math.min(reach - margin, rate * SNAPSHOT_PREFETCH_MS),
);
}
// Back at live: the first live snapshot takes the place of every contact,
// which stay drawn until it does; one that cannot be had clears them.
function handOver() {
const mine = ++handovers;
const current = () => mine === handovers && started && clock.isLive();
Promise.resolve()
.then(() => resumeLive())
.then(
(applied) => {
if (current() && applied !== true) clear();
},
(error) => {
if (!current() || error?.name === 'AbortError') return;
console.warn(`Live snapshot failed: ${id}`, error);
clear();
},
);
}
function follow(state) {
if (!started) return;
if (state.live) {
@@ -363,10 +455,11 @@ export function createSnapshotTimeline({
base = null;
empty = false;
failedUntil = -Infinity;
clear();
resumeLive();
handOver();
return;
}
// Away from live, a return to it still answering no longer applies.
handovers += 1;
const timeMs = state.timeMs;
// Away from live already: a move may stay within the loaded fixes.
const wasFollowing = wasActive;
@@ -432,6 +525,7 @@ export function createSnapshotTimeline({
stop() {
if (!started) return;
started = false;
handovers += 1;
cancel();
setGate(null);
wasActive = false;
+197 -7
View File
@@ -3,14 +3,23 @@ import assert from 'node:assert/strict';
import { createWorldClock } from './worldClock.js';
import {
createSnapshotTimeline,
SNAPSHOT_HOLD_MARGIN_MS,
SNAPSHOT_PREFETCH_MS,
SNAPSHOT_RETRY_MS,
SNAPSHOT_WAIT_MS,
snapshotAnswer,
} from './snapshotTimeline.js';
const STEP = 10_000;
const WALL = Date.UTC(2026, 10, 1, 12);
function harness({ timeline = true, coverage, spanMs } = {}) {
function harness({
timeline = true,
coverage,
spanMs,
stepMs = STEP,
live = () => true,
} = {}) {
const t = {
wall: WALL,
mono: 1_000,
@@ -33,7 +42,7 @@ function harness({ timeline = true, coverage, spanMs } = {}) {
...(timeline && {
timeline: {
coverage: () => span,
stepMs: STEP,
stepMs,
...(spanMs && { spanMs }),
subscribe(listener) {
coverageListeners.add(listener);
@@ -62,7 +71,10 @@ function harness({ timeline = true, coverage, spanMs } = {}) {
pending.push({ atMs, replace, signal, resolve, reject });
}),
clear: () => calls.push({ type: 'clear' }),
resumeLive: () => calls.push({ type: 'live' }),
resumeLive: () => {
calls.push({ type: 'live' });
return live();
},
now: () => t.mono,
...timers,
});
@@ -248,7 +260,7 @@ test('outside coverage the layer is cleared and nothing loads; unknown coverage
assert.equal(h.coverageListeners.size, 0);
});
test('back at live the layer is cleared and polls at once', async () => {
test('back at live the layer polls at once and keeps its contacts for the live snapshot', async () => {
const h = harness();
h.follower.start();
h.clock.seek(WALL - 600_000);
@@ -257,11 +269,72 @@ test('back at live the layer is cleared and polls at once', async () => {
h.clock.goLive();
await flush();
assert.equal(inflight.signal.aborted, true);
assert.deepEqual(h.calls.slice(-2), [{ type: 'clear' }, { type: 'live' }]);
assert.deepEqual(h.calls.at(-1), { type: 'live' });
assert.equal(
h.calls.some((call) => call.type === 'clear'),
false,
'the live snapshot takes the place of the contacts; nothing is cleared',
);
assert.equal(h.follower.active(), false);
h.follower.stop();
});
test('back at live, a live snapshot that cannot be had clears the layer', async () => {
for (const answer of [
() => false,
() => Promise.resolve(false),
() => Promise.reject(new Error('down')),
]) {
const h = harness({ live: answer });
h.follower.start();
h.clock.seek(WALL - 600_000);
await flush();
await h.answer();
h.clock.goLive();
await flush();
assert.deepEqual(h.calls.slice(-2), [{ type: 'live' }, { type: 'clear' }]);
h.follower.stop();
}
});
test('back at live, a live poll dropped for a newer one, or answered after leaving live, clears nothing', async () => {
const dropped = harness({
live: () =>
Promise.reject(
Object.assign(new Error('dropped'), { name: 'AbortError' }),
),
});
dropped.follower.start();
dropped.clock.seek(WALL - 600_000);
await flush();
await dropped.answer();
dropped.clock.goLive();
await flush();
assert.deepEqual(dropped.calls.at(-1), { type: 'live' });
dropped.follower.stop();
let fail;
const late = harness({
live: () => new Promise((resolve) => (fail = () => resolve(false))),
});
late.follower.start();
late.clock.seek(WALL - 600_000);
await flush();
await late.answer();
late.clock.goLive();
await flush();
late.clock.seek(WALL - 1_200_000);
await flush();
fail();
await flush();
assert.equal(
late.calls.some((call) => call.type === 'clear'),
false,
'the time shown now is not cleared by the old live answer',
);
late.follower.stop();
});
test('a load the source drops for a newer one is no failure: nothing clears, it is asked again', async () => {
const h = harness();
h.follower.start();
@@ -450,8 +523,9 @@ test('a snapshot the loaded fixes do not reach starts the held stretch afresh',
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);
// The next step is slow: play holds near the end of the fixes, then goes
// on without it, far past them.
h.advance(SPAN);
h.clock.coverageChanged();
h.advance(SNAPSHOT_WAIT_MS);
h.advance(30 * STEP);
@@ -548,3 +622,119 @@ test('a step a move back asked for that fails clears nothing and is asked again
});
h.follower.stop();
});
test('with fixes past each snapshot, play holds near their end, not at the step still loading', async () => {
const SPAN = 600_000;
const h = harness({ spanMs: SPAN });
h.follower.start();
const at = WALL - 1_800_000;
h.clock.seek(at);
await flush();
await h.answer();
h.clock.play();
h.advance(100);
h.clock.coverageChanged();
await flush();
assert.deepEqual(loads(h.calls).at(-1), {
type: 'load',
atMs: at + STEP,
replace: false,
});
// Past the step still loading: the newest snapshot's fixes carry them.
h.advance(3 * STEP);
h.clock.coverageChanged();
assert.ok(h.clock.now() > at + 3 * STEP);
assert.equal(h.clock.getState().buffering, false);
// Play holds a margin short of the end of those fixes, and waits there.
h.advance(SPAN);
assert.equal(h.clock.now(), at + SPAN - SNAPSHOT_HOLD_MARGIN_MS);
h.clock.coverageChanged();
assert.equal(h.clock.getState().buffering, true);
await h.answer();
assert.equal(h.clock.getState().buffering, false);
h.follower.stop();
});
test('with fixes past each snapshot, a fast play asks for steps well ahead of the time', async () => {
const SPAN = 600_000;
const RATE = 60;
const h = harness({ spanMs: SPAN });
h.follower.start();
const at = WALL - 1_800_000;
h.clock.seek(at);
await flush();
await h.answer();
h.clock.setRate(RATE);
h.clock.play();
h.advance(100);
h.clock.coverageChanged();
await flush();
// Each step answered asks for the next until they reach far enough ahead.
while (h.pending.length) await h.answer();
const ahead = RATE * SNAPSHOT_PREFETCH_MS;
const newest = loads(h.calls).at(-1).atMs;
const time = h.clock.now();
assert.ok(newest - time >= ahead, 'steps asked for ahead of the time');
assert.ok(newest - time < ahead + STEP, 'and no further');
assert.ok(
loads(h.calls).every((call, k) => k === 0 || call.replace === false),
'each in step with the last, moving contacts on',
);
h.follower.stop();
});
test('without fixes past each snapshot, a fast play still asks a step at a time', async () => {
const h = harness();
h.follower.start();
const at = WALL - 1_800_000;
h.clock.seek(at);
await flush();
await h.answer();
h.clock.setRate(60);
h.clock.play();
h.advance(10);
h.clock.coverageChanged();
await flush();
assert.equal(loads(h.calls).at(-1).atMs, at + STEP);
await h.answer();
assert.equal(h.pending.length, 1);
assert.equal(loads(h.calls).at(-1).atMs, at + 2 * STEP);
h.follower.stop();
});
test('play holds short of where the applied snapshot’s fixes actually reach, when that is short of the span', async () => {
const SPAN = 600_000;
const h = harness({ spanMs: SPAN });
h.follower.start();
const at = WALL - 1_800_000;
h.clock.seek(at);
await flush();
// Its records' fixes end two minutes after its time, not ten.
await h.answer(0, { reachMs: at + 120_000 });
h.clock.play();
h.advance(100);
h.clock.coverageChanged();
await flush();
h.advance(SPAN);
assert.equal(h.clock.now(), at + 120_000 - SNAPSHOT_HOLD_MARGIN_MS);
h.follower.stop();
});
test('a layer answers how far an applied snapshot’s fixes reach', () => {
assert.equal(snapshotAnswer({ records: [{ id: 'a' }] }), true);
assert.deepEqual(
snapshotAnswer({
records: [
{ fixes: [{ atMs: 3 }, { atMs: 9 }] },
{ fixes: [{ atMs: 12 }, { atMs: 'x' }] },
{ id: 'b' },
],
}),
{ reachMs: 12 },
);
// One record reaching far ahead does not stand for the rest.
const records = Array.from({ length: 20 }, (_, k) => ({
fixes: [{ atMs: k === 0 ? 900 : 100 + k }],
}));
assert.deepEqual(snapshotAnswer({ records }), { reachMs: 118 });
});
+27
View File
@@ -59,6 +59,33 @@ export function readTimelineFixes(value) {
return fixes;
}
/** The share of records whose fixes reach no further than fixesReachMs. */
export const FIXES_REACH_SHARE = 0.9;
/**
* How far the fixes a snapshot's records carry reach: the time by which
* FIXES_REACH_SHARE of them have their newest fix, so a few reaching far
* ahead do not stand for the rest (those whose fixes end sooner left), or
* null when none carries fixes.
* @param {Array<{fixes?: unknown}>|undefined} records
* @returns {number|null}
*/
export function fixesReachMs(records) {
const reaches = [];
for (const record of records ?? []) {
if (!Array.isArray(record?.fixes)) continue;
let reach = -Infinity;
for (const fix of record.fixes) {
const atMs = Number(fix?.atMs);
if (Number.isFinite(atMs) && atMs > reach) reach = atMs;
}
if (reach > -Infinity) reaches.push(reach);
}
if (!reaches.length) return null;
reaches.sort((a, b) => a - b);
return reaches[Math.ceil(FIXES_REACH_SHARE * reaches.length) - 1];
}
/**
* 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