Merge origin/main: shipwrecks, news, transit fronts, signal-lost trails and uncredited photos on the renderer's ports

Upstream's layers and changes are carried onto the ports, with no Cesium
outside src/render and no reach into the viewer:

- Shipwrecks draw as one icon set, clicked through the input dispatcher.
- News draws through draw sets, the camera port and the input dispatcher;
  its beacons pulse each frame through the frame port.
- The scene occlusion probe moves into src/render/cesium and reaches
  detection through a new application hook, createOcclusionProbe; its
  private Cesium reads go through internals.js.
- Flight and military trails, the stale and SIGNAL LOST cue, coasting and
  following the world clock run on the draw and frame ports. GPU icons
  follow the scene clock while the world clock is followed, and fade when
  stale. A report that holds is not planned again every tick.
- Vessels are keyed by their record id.

The stub boot now enables military, shipwrecks and news as well.
This commit is contained in:
Sameh Khamis committed 2026-11-10 20:03:28 -08:00
commit a755f63638
331 files changed
+40654 -1666

No files matched your search

+35 -5
View File
@@ -226,6 +226,10 @@ let instances = 0;
* @param {object} options.parts The layer's parts (`motion`, `rendering`).
* @param {string} options.layerId Pick and focus owner id.
* @param {number} options.renderDelaySec How far behind real time contacts draw.
* @param {() => boolean} [options.followsClock] True while the layer follows
* the world clock: contacts draw at the world's time (`state.now()`, the
* scene's time) with no delay.
* @param {number} [options.staleAlpha] A contact's alpha after a missed update.
* @param {number} options.courseMaxDps The fleet's course slew cap.
* @param {number} options.cockpitContactSizePx Cockpit far-contact pip size.
* @param {(icao24: string) => boolean} [options.holdsPlan] True while something
@@ -242,6 +246,8 @@ export function createAircraftIcons({
parts,
layerId,
renderDelaySec,
followsClock = () => false,
staleAlpha = 0.45,
courseMaxDps,
cockpitContactSizePx,
holdsPlan = () => false,
@@ -255,7 +261,26 @@ export function createAircraftIcons({
let switchPx = nearImageSwitchPx(1);
/** The delayed instant (epoch ms) every untracked contact is drawn at. */
const _displayMs = () => Date.now() - delayMs;
const _displayMs = () =>
followsClock() ? state.now() : Date.now() - delayMs;
/** The live draw set, and whether its motion clock is the scene's. */
let liveSet = null;
let sceneClock = false;
/** The motion clock for whether the layer follows the world clock. */
const motionClock = (scene) =>
scene ? { kind: 'scene' } : { kind: 'live', delayMs };
/**
* Put the set's motion on the scene's clock (the world's time) while the
* layer follows the world clock, on the delayed live clock otherwise.
*/
function _syncMotionClock() {
const scene = followsClock();
if (!liveSet || scene === sceneClock) return;
sceneClock = scene;
liveSet.setOptions({ motionClock: motionClock(scene) });
}
/**
* Create the draw set for one layer lifetime, drawn over depth and culled
@@ -266,12 +291,14 @@ export function createAircraftIcons({
const set = drawOf(viewer).icons({
id: `${layerId}-icons:${++instances}`,
horizonCull: true,
motionClock: { kind: 'live', delayMs },
motionClock: motionClock(followsClock()),
drawOrder: services.sprites?.spriteDrawOrder?.(layerId) ?? 0,
});
// Columns of no rows put the set's host in the scene now, rather than
// with its first contact.
set.setColumns?.({ ids: [] });
liveSet = set;
sceneClock = followsClock();
switchPx = _imageSwitchPx(viewer);
state._icons = createContactIcons(set, {
capabilities: rendererOf(viewer)?.capabilities ?? null,
@@ -283,6 +310,7 @@ export function createAircraftIcons({
function _disposeIcons() {
state._icons?.dispose();
state._icons = null;
liveSet = null;
}
/** The near-image switch in CSS px for the scene's pixel ratio. */
@@ -405,8 +433,9 @@ export function createAircraftIcons({
trackDeg: heading,
turnRateDps: regime.turnRateDps,
};
// A warm-up's arc ends at its fix; a coast's runs to its limit.
if (regime.maxDt === 0) expiresAt = t0;
// A warm-up's arc ends at its fix, still ahead; a coast's runs to its
// limit, and a report that holds stays put until the next one.
if (regime.maxDt === 0 && t0 > t) expiresAt = t0;
}
// Below hover speed the nose holds what is on screen (or, for a new row,
// where this motion starts); above it, it glides on at the slew cap.
@@ -523,7 +552,7 @@ export function createAircraftIcons({
color: rgba(rendering._fleetBillboardColor(icao24, info)),
rotationMode: 'course',
};
look.alpha = state.records.missingPolls.get(icao24) ? 0.45 : 1;
look.alpha = state.records.missingPolls.get(icao24) ? staleAlpha : 1;
icons.update(icao24, look);
}
@@ -575,6 +604,7 @@ export function createAircraftIcons({
return {
_displayMs,
_syncMotionClock,
_createIcons,
_disposeIcons,
_syncImageSwitch,
+40
View File
@@ -0,0 +1,40 @@
import test from 'node:test';
import assert from 'node:assert/strict';
import { createAircraftIcons } from './aircraftIconLayer.js';
import { bindFakeDraw } from '../testSupport/fakeDrawPort.mjs';
const WORLD_MS = Date.UTC(2026, 10, 1, 12, 0);
test('following the world clock, contacts draw at the world’s time on the scene clock', (t) => {
t.mock.timers.enable({ apis: ['Date'], now: WORLD_MS + 86_400_000 });
const viewer = {};
const { draw } = bindFakeDraw(viewer);
let following = false;
const state = {
_viewer: viewer,
now: () => (following ? WORLD_MS : Date.now()),
};
const icons = createAircraftIcons({
state,
services: { focus: { focusPassIsNeeded: () => false } },
parts: {},
layerId: 'flights',
renderDelaySec: 30,
followsClock: () => following,
courseMaxDps: 3,
cockpitContactSizePx: 8,
});
icons._createIcons(viewer);
const set = draw.find('flights-icons:');
// Live: a poll interval behind real time, on the delayed live clock.
assert.deepEqual(set.spec.motionClock, { kind: 'live', delayMs: 30_000 });
assert.equal(icons._displayMs(), Date.now() - 30_000);
following = true;
assert.equal(icons._displayMs(), WORLD_MS, 'the world’s time, no delay');
icons._syncMotionClock();
assert.deepEqual(set.spec.motionClock, { kind: 'scene' });
following = false;
icons._syncMotionClock();
assert.deepEqual(set.spec.motionClock, { kind: 'live', delayMs: 30_000 });
icons._disposeIcons();
});
+14 -3
View File
@@ -723,9 +723,15 @@ export function createAircraftModels({
}
const record = state._trackedModel;
// The tracked aircraft uses the same dominant light tint as the fleet;
// the IR boost removes the remaining diffuse hint with flat white.
if (!record.tint)
record.tint = state._irBoost ? WHITE : rgba(_modelColor(icao24));
// the IR boost removes the remaining diffuse hint with flat white. It
// fades like the tracked billboard while the plane is stale.
const base = state._irBoost ? WHITE : rgba(_modelColor(icao24));
_treat(record, {
base,
alpha: parts.tracking._trackedStaleCue?.(icao24)?.dimmed
? policy.STALE_ALPHA
: base[3],
});
// Placed while it loads too: its first drawn frame is at this placement.
const displayPos = _modelDisplayPosition(icao24, pos);
if (!displayPos) {
@@ -764,6 +770,9 @@ export function createAircraftModels({
*/
function _fleetTick() {
// Every frame, shown or not: the tracked label's stale cue follows the
// clock. (The tracked trail moves on in its own pass before each frame.)
if (state._viewer) parts.tracking._staleCueTick?.();
try {
_fleetPass();
} finally {
@@ -796,6 +805,8 @@ export function createAircraftModels({
function _fleetPass() {
const icons = state._icons;
if (!state._viewer || !icons || !icons.show) return;
// Following the world clock, the icons move on its time.
parts.icons._syncMotionClock?.();
const nowMs = focusNowMs(Date.now());
if (nowMs - state._lastFleetTickMs < policy.FLEET_DR_INTERVAL_MS) return;
+48 -21
View File
@@ -8,9 +8,12 @@ import {
} from '../geo/julian.js';
import { clone, distance } from '../geo/vector.js';
import {
COAST_MAX_SPEED_MPS,
courseBetweenCartesians,
speedRamp,
STALE_COAST_MAX_SEC,
staleCoastLimitSeconds,
staleHoldsForFix,
} from './motionModel.js';
/**
@@ -19,11 +22,14 @@ import {
* @typedef {{speed: string, track: string}} AircraftRecordFields
*/
/** A fix's own ground speed, else the record's. */
/** A fix's own ground speed, else the record's; never over COAST_MAX_SPEED_MPS. */
export function fixSpeedMps(fix, info, fields) {
return Number.isFinite(fix.velocity)
? fix.velocity
: (info && info[fields.speed]) || 0;
return Math.min(
Number.isFinite(fix.velocity)
? fix.velocity
: (info && info[fields.speed]) || 0,
COAST_MAX_SPEED_MPS,
);
}
/** A fix's own track, else the record's. */
@@ -108,17 +114,19 @@ export function createMotionRegime() {
* glides FORWARD into interpolation with no freeze and no backward snap
* (holding the oldest fix froze the icon; extrapolating the newest to
* wall-clock made it jump back a poll interval when interpolation took
* over). Otherwise the newest fix coasts. A feed can still be receiving
* fresh contact messages for that aircraft; freezing 60 s after the
* position produced a stop → catch-up → stop cadence, so it coasts through
* the latest real contact plus a bounded grace, with an absolute cap so a
* stale cached feed cannot drift forever.
* over). Otherwise the newest fix coasts on its last speed and heading for
* five minutes past it, then stops (SIGNAL LOST). A contact last heard on
* or near the ground holds there instead (`staleHoldsForFix`, decided once
* per report), and a chain of synthetic fixes never coasts further than
* the real report they were built from would.
*
* @param {Array<object>} history Non-empty, oldest first.
* @param {object|undefined} info The contact's record.
* @param {{dayNumber: number, secondsOfDay: number}} renderTime A Julian date (geo/julian).
* @param {AircraftRecordFields} fields
* @param {object} result From `createMotionRegime`; returned filled in.
* @param {{cachedGroundFloor?: (latDeg: number, lonDeg: number) => number|null}} [options]
* The ground under a report, where known, for the hold decision.
*/
export function aircraftMotionRegime(
history,
@@ -126,6 +134,7 @@ export function aircraftMotionRegime(
renderTime,
fields,
result,
{ cachedGroundFloor } = {},
) {
for (let i = history.length - 1; i >= 1; i--) {
const a = history[i - 1];
@@ -167,17 +176,35 @@ export function aircraftMotionRegime(
result.maxDt =
warming && history.length > 1
? 0
: staleCoastLimitSeconds({
// `epochMs` is captured once when the poll is normalized. Avoid
// allocating a Date per aircraft on every 12 Hz fleet tick.
fixEpochMs: Number.isFinite(newest.epochMs)
? newest.epochMs
: julianToEpochMs(newest.time),
lastContactEpochMs: info?.lastContactEpochMs,
// Permit one minute of contact grace but cap any cached-feed drift
// at five minutes. Source backoff is exposed separately as a STALE cue.
minimumSec: 60,
maximumSec: 300,
});
: staleCoastSeconds(newest, info, cachedGroundFloor);
return result;
}
/**
* How long `newest` coasts at most: five minutes, less what a synthetic
* fix's chain already coasted since its real report (`reportEpochMs`); none
* for a report that holds (judged once per report, from its ground flag and
* the ground under it where `cachedGroundFloor` knows it).
* @param {object} newest
* @param {object|undefined} info
* @param {Function} [cachedGroundFloor]
* @returns {number}
*/
export function staleCoastSeconds(newest, info, cachedGroundFloor) {
const newestMs = fixEpochMs(newest);
const limitSec = staleCoastLimitSeconds({
fixEpochMs: newestMs,
lastContactEpochMs: info?.lastContactEpochMs,
// A plane that stops reporting keeps flying for five minutes, whatever
// its contact time, then stops dimmed as SIGNAL LOST. A missed update
// shows STALE throughout.
minimumSec: 300,
maximumSec: 300,
});
if (staleHoldsForFix(newest, { onGround: info?.onGround, cachedGroundFloor }))
return 0;
const alreadySec = Number.isFinite(newest.reportEpochMs)
? Math.max(0, (newestMs - newest.reportEpochMs) / 1000)
: 0;
return Math.max(0, Math.min(limitSec, STALE_COAST_MAX_SEC - alreadySec));
}
+12
View File
@@ -6,6 +6,7 @@ import assert from 'node:assert/strict';
import { mapAnalystRecord } from './aisLiveVessels.js';
const FULL_RECORD = {
id: '353136000',
mmsi: '353136000',
name: 'EVER GIVEN',
lat: 29.55,
@@ -20,6 +21,7 @@ test('ais analyst record: full record maps every contract field', () => {
const r = mapAnalystRecord(FULL_RECORD);
assert.deepEqual(r, {
id: 'EVER GIVEN',
vesselId: '353136000',
mmsi: '353136000',
name: 'EVER GIVEN',
lat: 29.55,
@@ -38,6 +40,16 @@ test('ais analyst record: nameless vessel falls back to mmsi id', () => {
assert.equal(r.name, null);
});
test('ais analyst record: the key is the source id; the MMSI rides along when known', () => {
const shared = mapAnalystRecord({ ...FULL_RECORD, id: 'provider-a' });
assert.equal(shared.vesselId, 'provider-a');
assert.equal(shared.mmsi, '353136000');
const noMmsi = mapAnalystRecord({ ...FULL_RECORD, id: 'provider-b', mmsi: '', name: '' });
assert.equal(noMmsi.vesselId, 'provider-b');
assert.equal(noMmsi.mmsi, null);
assert.equal(noMmsi.id, 'provider-b', 'a nameless vessel with no MMSI is labelled by its id');
});
test('ais analyst record: empty strings and NaN become null, never undefined', () => {
const r = mapAnalystRecord({ mmsi: '', name: 'TUG', speed: NaN, type: '', destination: '' });
assert.equal(r.mmsi, null);
+106 -44
View File
@@ -340,7 +340,7 @@ test('zero accepted rows preserve warm vessel selection, trail, and freshness ti
records: [record],
selectedRecord: record,
trail,
trailMmsi: record.mmsi,
trailId: record.mmsi,
trailPositions: [POS],
loaded: true,
lastUpdate: 456,
@@ -370,8 +370,8 @@ test('zero accepted rows preserve warm vessel selection, trail, and freshness ti
lastMessageAt: 789,
rawRowCount: 1,
acceptedRowCount: 0,
selectedMmsi: record.mmsi,
trailMmsi: record.mmsi,
selectedId: record.mmsi,
trailId: record.mmsi,
trailPositionCount: 1,
sessionId: _getVesselFeedStateForTest().sessionId,
firstConnectPhase: 'idle',
@@ -651,7 +651,7 @@ test('superseded AIS response cannot mutate or finalize a replacement request',
records: [replacement],
selectedRecord: replacement,
trail: replacementTrail,
trailMmsi: replacement.mmsi,
trailId: replacement.mmsi,
trailPositions: [POS],
loaded: true,
lastUpdate: 200,
@@ -669,17 +669,9 @@ test('superseded AIS response cannot mutate or finalize a replacement request',
);
await oldLoad;
let feed = _getVesselFeedStateForTest();
assert.equal(
feed.loading,
true,
'old finally must not clear replacement loading ownership',
);
assert.equal(
feed.lastUpdate,
200,
'old response must not advance replacement freshness',
);
assert.equal(feed.selectedMmsi, replacement.mmsi);
assert.equal(feed.loading, true, 'old finally must not clear replacement loading ownership');
assert.equal(feed.lastUpdate, 200, 'old response must not advance replacement freshness');
assert.equal(feed.selectedId, replacement.mmsi);
second.resolve(
jsonResponse({ status: 'open', lastMessageAt: null, rows: [] }),
@@ -690,8 +682,8 @@ test('superseded AIS response cannot mutate or finalize a replacement request',
assert.equal(feed.lastUpdate, 200);
assert.equal(feed.error, 'awaiting first AIS message…');
assert.equal(feed.stale, true);
assert.equal(feed.selectedMmsi, replacement.mmsi);
assert.equal(feed.trailMmsi, replacement.mmsi);
assert.equal(feed.selectedId, replacement.mmsi);
assert.equal(feed.trailId, replacement.mmsi);
assert.equal(replacementTrail.clearCalls, 0);
} finally {
globalThis.fetch = priorFetch;
@@ -920,25 +912,21 @@ test('vessel focus wire restores a hidden sprite before releasing the active pas
test('vessel selection: empty-space click requests deselection', () => {
assert.deepEqual(
reduceVesselSelection({ selectedMmsi: '353136000', gesture: 'click' }),
reduceVesselSelection({ selectedId: '353136000', gesture: 'click' }),
{ action: 'deselect' },
);
});
test('vessel selection: no selection plus empty-space click is a no-op', () => {
assert.deepEqual(
reduceVesselSelection({
selectedMmsi: null,
pickedMmsi: null,
gesture: 'click',
}),
reduceVesselSelection({ selectedId: null, pickedId: null, gesture: 'click' }),
{ action: 'none' },
);
});
test('vessel selection: Escape deselects only when this layer owns a selection', () => {
assert.deepEqual(
reduceVesselSelection({ selectedMmsi: 353136000, gesture: 'escape' }),
reduceVesselSelection({ selectedId: 353136000, gesture: 'escape' }),
{ action: 'deselect' },
);
assert.deepEqual(reduceVesselSelection({ gesture: 'escape' }), {
@@ -949,16 +937,16 @@ test('vessel selection: Escape deselects only when this layer owns a selection',
test('vessel selection: another vessel replaces selection; same vessel is a no-op', () => {
assert.deepEqual(
reduceVesselSelection({
selectedMmsi: '353136000',
pickedMmsi: '367123450',
selectedId: '353136000',
pickedId: '367123450',
gesture: 'click',
}),
{ action: 'select' },
);
assert.deepEqual(
reduceVesselSelection({
selectedMmsi: '353136000',
pickedMmsi: '353136000',
selectedId: '353136000',
pickedId: '353136000',
gesture: 'click',
}),
{ action: 'none' },
@@ -973,8 +961,9 @@ test('vessel selection: another vessel replaces selection; same vessel is a no-o
const POS = Cesium.Cartesian3.fromDegrees(4.05, 51.93, 3);
// Like the layer's records, a vessel with no id of its own is keyed by its MMSI.
function makeRecord(overrides = {}) {
return {
const record = {
name: 'EVER GIVEN',
mmsi: '353136000',
type: 'Container Ship',
@@ -987,6 +976,8 @@ function makeRecord(overrides = {}) {
position: POS,
...overrides,
};
if (!Object.hasOwn(overrides, 'id')) record.id = record.mmsi;
return record;
}
function makeTrailSpy() {
@@ -1093,7 +1084,7 @@ function installWireHarness(picked, stateOverrides = {}) {
records: [record],
selectedRecord: record,
trail,
trailMmsi: record.mmsi,
trailId: record.mmsi,
trailPositions: [POS],
interactionKeyTarget: keyTarget,
...stateOverrides,
@@ -1132,7 +1123,7 @@ test('vessel interaction wire: trail pick does not deselect', () => {
harness.record.mmsi,
);
assert.equal(harness.trail.clearCalls, 0);
assert.equal(_getVesselStateForTest().trailMmsi, harness.record.mmsi);
assert.equal(_getVesselStateForTest().trailId, harness.record.mmsi);
} finally {
harness.cleanup();
}
@@ -1392,7 +1383,7 @@ test('vessel interaction lifecycle: disable detaches input and enable reinstalls
selectedRecord: harness.record,
enabled: false,
trail: harness.trail,
trailMmsi: harness.record.mmsi,
trailId: harness.record.mmsi,
trailPositions: [POS],
interactionKeyTarget: harness.keyTarget,
});
@@ -1476,7 +1467,7 @@ test('vessel trail lifecycle: deselect clears the selected-vessel trail', () =>
aisLiveVesselsLayer.clearSelection();
assert.equal(harness.trail.clearCalls, 1);
assert.deepEqual(_getVesselStateForTest(), {
trailMmsi: null,
trailId: null,
trailPositionCount: 0,
vesselCount: 1,
});
@@ -1491,14 +1482,14 @@ test('vessel trail lifecycle: reconciliation eviction clears an orphaned trail',
_setVesselStateForTest({
records: [record],
trail,
trailMmsi: record.mmsi,
trailId: record.mmsi,
trailPositions: [POS],
});
try {
_reconcileVesselsForTest({}, []);
assert.equal(trail.clearCalls, 1);
assert.deepEqual(_getVesselStateForTest(), {
trailMmsi: null,
trailId: null,
trailPositionCount: 0,
vesselCount: 0,
});
@@ -1829,6 +1820,28 @@ test('vessel interaction wire: selecting a vessel by click requests a camera tra
}
});
test('vessel interaction wire: a vessel with an id and no MMSI is selected by click', () => {
const idOnly = makeRecord({ id: 'provider-7', mmsi: '', name: 'NO MMSI' });
const harness = installWireHarness(
{ id: idOnly },
{ records: [idOnly], selectedRecord: null, trailId: null },
);
const requests = [];
harness.windowTarget.addEventListener(
WORLD_FOCUS_REQUEST_EVENT,
(event) => requests.push(event.detail),
);
try {
harness.handler.click({ position: { x: 10, y: 20 } });
assert.equal(aisLiveVesselsLayer.getSelectedInfo()?.id, 'provider-7');
assert.equal(aisLiveVesselsLayer.getSelectedInfo()?.mmsi, '');
assert.equal(requests[0]?.id, 'provider-7');
assert.match(harness.hud.readout.text, /MMSI: -- /);
} finally {
harness.cleanup();
}
});
/**
* Overlay-host recorder whose hitTest answers with one card id. The real host
* only publishes rects for `interactive` entries, so a stub returning a hit is
@@ -1993,17 +2006,27 @@ for (const card of ['live', 'stale', 'absent', 'covered']) {
});
}
test('vessel card policy: only MMSI-keyed cards publish a hit rect', () => {
test('vessel card policy: only keyed cards publish a hit rect', () => {
const keyed = applyVesselOverlayPolicy(buildVesselCard(makeRecord()));
assert.equal(keyed.interactive, true);
const unkeyed = applyVesselOverlayPolicy(
buildVesselCard(makeRecord({ mmsi: '' })),
);
assert.equal(
unkeyed.interactive,
false,
'an unkeyed card has no record to select',
const unkeyed = applyVesselOverlayPolicy(buildVesselCard(makeRecord({ mmsi: '' })));
assert.equal(unkeyed.interactive, false, 'an unkeyed card has no record to select');
const idOnly = buildVesselCard(makeRecord({ id: 'provider-7', mmsi: '' }));
assert.equal(applyVesselOverlayPolicy(idOnly).interactive, true, 'a source id is a key');
assert.equal(idOnly.id, 'vessel:provider-7');
});
test('vessel cards are keyed by id and show the MMSI only when known', () => {
const shared = buildSelectedVesselCard(makeRecord({ id: 'hull-b' }));
assert.equal(shared.id, 'vessel:hull-b');
assert.equal(shared.actionable, true);
assert.match(shared.details.at(-1), /^MMSI 353136000 · /);
const unknown = buildSelectedVesselCard(
makeRecord({ id: 'provider-7', mmsi: '', name: 'provider-7' }),
);
assert.equal(unknown.actionable, true);
assert.match(unknown.details.at(-1), /^MMSI -- · /);
assert.equal(unknown.title, 'VESSEL', 'a name that is only the id is no name');
});
test('vessel interaction wire: deselecting never moves the camera', () => {
@@ -2064,7 +2087,7 @@ test('vessel selection passes the opaque source reference to optional history',
});
const harness = installWireHarness(undefined, {
selectedRecord: null,
trailMmsi: null,
trailId: null,
});
try {
harness.record.reference = 'opaque:test-reference';
@@ -2123,3 +2146,42 @@ test('vessel focus wire skips hidden sprites at rest while a target is tracked',
assert.equal(result.activeCount, 1);
for (const record of records.slice(1)) assert.equal(focus(record), 1);
});
test('detection objects name the vessel card their callout gives way to', () => {
const vessel = (mmsi, name) => ({
name,
mmsi,
type: 'Cargo',
destination: '',
speed: 9.5,
course: 80,
heading: 80,
lastPositionUtc: '',
missedRefreshes: 0,
position: POS,
// Drawn and on screen (a record with no visual of its own is its own).
visible: true,
});
const keyed = vessel('200', 'GOLDEN BEAR');
const unkeyed = { ...vessel('', 'NO MMSI'), lat: 37.8, lon: -122.4 };
_setVesselStateForTest({
viewer: {},
records: [keyed, unkeyed],
});
try {
const objects = Object.fromEntries(
aisLiveVesselsLayer
.getDetectableObjects()
.map((object) => [object.id, object]),
);
assert.equal(objects['GOLDEN BEAR'].cardSourceId, 'ais-live-vessels');
assert.equal(objects['GOLDEN BEAR'].cardEntryId, 'vessel:200');
assert.equal(
objects['NO MMSI'].cardEntryId,
'vessel:unkeyed:NO MMSI:37.80000:-122.40000',
'the same identity the vessel card is published under',
);
} finally {
_setVesselStateForTest({ enabled: false });
}
});
+21
View File
@@ -1526,3 +1526,24 @@ test('a repeated move inside an outstanding query keeps the displayed marker set
h.restore();
}
});
test('ALPR display tags collapse controls and cap final text without erasing Unicode', () => {
const record = normalizeAlprNode({
type: 'node',
id: 1,
lat: 30,
lon: -97,
tags: {
'surveillance:type': 'ALPR',
operator: ' Şehir\n\u0000 PD ',
manufacturer: '😀'.repeat(200),
'camera:type': null,
'surveillance:zone': '\t traffic zone ',
},
});
assert.equal(record.operator, 'Şehir PD');
assert.equal(record.manufacturer.length, 180);
assert.equal(record.manufacturer, '😀'.repeat(90));
assert.equal(record.cameraType, null);
assert.equal(record.zone, 'traffic zone');
});
+48
View File
@@ -139,6 +139,13 @@ export const DATA_CREDITS = [
'copied, published, or incorporated into other databases without the ' +
'explicit permission of David J Taylor, Edinburgh',
},
{
key: 'planespotters',
html:
'Aircraft photos: ' +
'<a href="https://www.planespotters.net" target="_blank" rel="noopener">Planespotters.net</a> ' +
'· each photo is © its photographer, credited beside it',
},
{
key: 'aisstream',
html:
@@ -571,6 +578,38 @@ export const DATA_CREDITS = [
'licensed under <a href="https://creativecommons.org/licenses/by-nc-sa/4.0/" target="_blank" rel="noopener">CC BY-NC-SA 4.0</a>. ' +
'Shown as published; reports are S2 assessments, not verified fact.',
},
{
key: 'news',
html:
'News: every report is credited to its own publisher and links to the original article; ' +
'pictures are the publishers’ own, shown from their sites with the publisher named. ' +
'Places, categories, severity and English headlines are derived automatically, by ' +
'bundled rules, the news provider or the configured news server, and can be wrong.',
},
{
// GDELT's terms ask for a citation and a link.
key: 'gdelt-news',
html:
'News, Conflicts without a news server: events and page titles from the ' +
'<a href="https://www.gdeltproject.org/" target="_blank" rel="noopener">GDELT Project</a> ' +
'(GDELT 2.0 events and GKG; places and categories are machine-coded)',
},
{
// World News API's free plan asks for a visible "World News API" link to
// its site; always listed, so a free-plan key is never shown without it.
key: 'worldnewsapi',
html:
'News, Local without a news server: headlines from ' +
'<a href="https://worldnewsapi.com/" target="_blank" rel="noopener">World News API</a>',
},
{
key: 'shipwrecks',
html:
'Shipwrecks (Europe): <a href="https://emodnet.ec.europa.eu/en/human-activities" target="_blank" rel="noopener">EMODnet Human Activities</a> ' +
'(data originator AND-International, compiled from SHOM, Ireland&rsquo;s National Monuments Service, Historic England and the Oxford Roman Economy Project), ' +
'licensed under <a href="https://creativecommons.org/licenses/by/4.0/" target="_blank" rel="noopener">CC BY 4.0</a>' +
' · Shipwrecks (worldwide): <a href="https://www.wikidata.org/" target="_blank" rel="noopener">Wikidata</a> (CC0)',
},
{
key: 'drivebc-cctv',
html:
@@ -637,6 +676,15 @@ export const TOMTOM_CREDIT = {
'<a href="https://www.tomtom.com" target="_blank" rel="noopener">TomTom</a>',
};
/** Registered when the News layer shows a Liveuamap report (only with
* LIVEUAMAP_API_KEY set and no news server). */
export const LIVEUAMAP_CREDIT = {
key: 'liveuamap',
html:
'News, Conflicts: mapped reports from ' +
'<a href="https://liveuamap.com/" target="_blank" rel="noopener">Liveuamap</a>',
};
/** Registered when the first Natural Earth region or state/province outline
* resolves (public domain — no attribution required; credited as a courtesy). */
export const NATURAL_EARTH_CREDIT = {
+28
View File
@@ -2,6 +2,7 @@ import { test } from 'node:test';
import assert from 'node:assert/strict';
import {
DATA_CREDITS,
LIVEUAMAP_CREDIT,
NYC_DOT_DISCLAIMER,
transitFeedCredit,
} from './dataCredits.js';
@@ -44,6 +45,13 @@ test('adsbdb is credited and carries its published route-data restriction', () =
assert.match(credit.html, /href="https:\/\/www\.adsbdb\.com"/);
});
test('Planespotters is credited with a plain followable link', () => {
const credit = DATA_CREDITS.find((entry) => entry.key === 'planespotters');
assert.ok(credit, 'the tracked aircraft photos come from Planespotters');
assert.match(credit.html, /href="https:\/\/www\.planespotters\.net"/);
assert.doesNotMatch(credit.html, /nofollow/);
});
test('the UCS Satellite Database is acknowledged with its version and webpage', () => {
// UCS database manual, section 3: references name the version (the Excel
// file's name) and link www.ucsusa.org/satellite_database.
@@ -285,6 +293,26 @@ test('data credits go through the renderer to the attribution list', async () =>
assert.equal(registerDynamicCredit({}, { key: 'none', html: 'x' }), false);
});
test('the News layer credits its built-in sources', () => {
const credit = (key) => DATA_CREDITS.find((entry) => entry.key === key);
// GDELT's terms ask for a citation and a link.
assert.match(
credit('gdelt-news').html,
/href="https:\/\/www\.gdeltproject\.org\/"[^>]*>GDELT Project</,
);
// World News API's free plan asks for this exact link.
assert.match(
credit('worldnewsapi').html,
/<a href="https:\/\/worldnewsapi\.com\/"[^>]*>World News API<\/a>/,
);
assert.match(LIVEUAMAP_CREDIT.html, />Liveuamap</);
assert.ok(
!DATA_CREDITS.some((entry) => entry.key === LIVEUAMAP_CREDIT.key),
'Liveuamap is credited only once its key is in use',
);
assert.doesNotMatch(credit('news').html, /No single provider/);
});
test('the PR #1506 camera packs are credited with their sources and terms', () => {
const html = (key) => DATA_CREDITS.find((entry) => entry.key === key)?.html;
assert.match(html('ottawa-cctv') || '', /traffic\.ottawa\.ca/);
+142 -7
View File
@@ -20,7 +20,10 @@ import {
getKeyholeFadeTuning,
keyholeLabelAlphaFromGeometry,
} from '../celestialRing.js';
import { registerWorldOverlayPaintLane } from '../overlays/worldOverlay.js';
import {
getQueuedOverlayEntryAlpha,
registerWorldOverlayPaintLane,
} from '../overlays/worldOverlay.js';
import {
DETECTION_STYLE,
DETECTION_THEME_MAP,
@@ -46,6 +49,9 @@ import {
viewScaleForAltitude,
} from './detectionPolicy.js';
import { detectionBracketOpacity } from './detectionPresentation.js';
import { SurfaceOcclusion } from './detectionOcclusion.js';
import { rendererOf } from '../render/rendererOf.js';
import { applicationHooksOf } from '../render/applicationHooks.js';
import {
createCyberSonarSampler,
cyberSonarFrameDelay,
@@ -106,6 +112,8 @@ const THEME_MAP = DETECTION_THEME_MAP;
const SPARSE_ZONE_FRACTION = 0.5;
/** Solve cadence for membership/collision; accepted identities still reproject every frame. */
const LABEL_SOLVE_INTERVAL_MS = 125;
/** Own-card opacity that fully hides a callout; below it the callout fades in. */
const CARD_ALPHA_HIDING_CALLOUT = 0.5;
/** Alpha bands retain bracket batching while approximating a continuous radial fade. */
const BRACKET_ALPHA_STEPS = 4;
/** Finer bands for Global Context echo brackets, whose fade is animated. */
@@ -260,6 +268,49 @@ let _allocationStrategy = ALLOCATION_ELASTIC;
let _lastNonOffMode = MODE_BALANCED;
/** @type {LabelArbiter} Shared stable callout selector. */
const _labelArbiter = new LabelArbiter();
/**
* A probe that tests nothing: a renderer without an occlusion probe of its
* own draws every depth-tested contact's bracket and callout.
*/
const NO_OCCLUSION_PROBE = Object.freeze({
mode: 'off',
maxPerFrame: 0,
lastFrameMs: 0,
lastFrameTests: 0,
beginFrame() {},
add: () => false,
endFrame() {},
reset() {},
destroy() {},
});
/**
* Hides the bracket and callout of a depth-tested contact (a street vehicle)
* that the scene drew something in front of. `_occlusionProbe` asks the GPU
* about each such contact without waiting for the answer (the renderer's
* `createOcclusionProbe` application hook, `render/applicationHooks.js`);
* `_surfaceOcclusion` remembers the answers and decides, every frame, who is
* drawn.
*/
let _occlusionProbe = NO_OCCLUSION_PROBE;
const _surfaceOcclusion = new SurfaceOcclusion(_occlusionProbe);
/** Use the occlusion probe of `viewer`'s renderer, or none. */
function _useOcclusionProbe(viewer) {
_occlusionProbe.destroy();
_occlusionProbe =
applicationHooksOf(rendererOf(viewer)).createOcclusionProbe?.() ??
NO_OCCLUSION_PROBE;
_surfaceOcclusion.clear();
_surfaceOcclusion.probe = _occlusionProbe;
}
/**
* Keys of callouts the label arbiter still holds for contacts last seen
* hidden. A key stays here until its contact is seen drawn again or the
* arbiter lets the callout go, so the callout cannot come back at its old
* place just because its contact has since left the view.
*/
const _surfaceSuppressedKeys = new Set();
let _surfaceDepthFallbackReported = false;
let _lastLabelSolveAt = 0;
let _labelSolveDirty = true;
let _lastDiagnostics = null;
@@ -285,12 +336,13 @@ let _cockpitModeListener = null;
/**
* Initializes detection inside the shared world-overlay host and stores
* references to data layers. The host owns the canvas and render listener.
* @param {object} _viewer - The host the renderer is bound to. Unused: the
* world-overlay host hands each paint its camera.
* @param {object} viewer - The host the renderer is bound to. The
* world-overlay host hands each paint its camera; the renderer's occlusion
* probe, where it has one, tests depth-tested contacts.
* @param {Array} layers - Data layer modules that may implement getDetectableObjects().
* @param {Function} onModeChange - Callback invoked with the new mode label string on mode changes.
*/
export function initDetection(_viewer, layers, onModeChange) {
export function initDetection(viewer, layers, onModeChange) {
if (_cockpitModeListener && typeof window !== 'undefined') {
window.removeEventListener(
'gev:cockpit-mode-changed',
@@ -301,6 +353,7 @@ export function initDetection(_viewer, layers, onModeChange) {
_calloutLane?.unregister?.();
_layers = layers;
_onModeChange = onModeChange;
_useOcclusionProbe(viewer);
_debugBanner = detectionDebugRequested(
typeof window !== 'undefined' ? window.location?.search : '',
);
@@ -363,6 +416,9 @@ export function destroyDetection() {
_suspended = false;
_suspendReason = '';
_labelArbiter.clear();
_surfaceOcclusion.clear();
_surfaceSuppressedKeys.clear();
_useOcclusionProbe(null);
_lastLabelSolveAt = 0;
_labelSolveDirty = true;
_lastDiagnostics = null;
@@ -572,7 +628,8 @@ export function getDetectionDiagnostics() {
// sprites/strokes. Nothing is copied on the production paint path.
result.calloutRects = _calloutPool
.slice(0, _calloutCount)
.map(({ x, y, w, h, alpha }) => ({ x, y, w, h, alpha }));
.filter((row) => row.paintAlpha > 0.001)
.map(({ x, y, w, h, paintAlpha }) => ({ x, y, w, h, alpha: paintAlpha }));
return result;
}
@@ -687,6 +744,9 @@ function _applyModeState() {
_syncSurfaceVisibility();
_setLanesActive(false);
_labelArbiter.clear();
_surfaceOcclusion.clear();
_surfaceSuppressedKeys.clear();
_occlusionProbe.reset();
_lastLabelSolveAt = 0;
_labelSolveDirty = true;
_lastSolveSnapshot = {
@@ -1073,6 +1133,9 @@ function _stashCallout(entry, acquireFade, keyhole) {
font: FONT,
microFont: MICRO_FONT,
alpha: 1,
cardSourceId: '',
cardEntryId: '',
paintAlpha: 1,
};
_calloutPool[_calloutCount] = row;
}
@@ -1099,6 +1162,8 @@ function _stashCallout(entry, acquireFade, keyhole) {
row.font = FONT;
row.microFont = MICRO_FONT;
row.alpha = alpha;
row.cardSourceId = candidate.cardSourceId;
row.cardEntryId = candidate.cardEntryId;
_calloutCount++;
}
@@ -1130,7 +1195,15 @@ function _paintCalloutLane(frame) {
ctx.textBaseline = 'alphabetic';
for (let i = 0; i < _calloutCount; i++) {
const row = _calloutPool[i];
paintDetectionCallout(ctx, row, row.alpha);
// The callout would show through its contact's own card: fade it by the
// opacity that card paints with this frame.
const cardAlpha =
row.cardEntryId === ''
? 0
: getQueuedOverlayEntryAlpha(row.cardSourceId, row.cardEntryId);
row.paintAlpha =
row.alpha * Math.max(0, 1 - cardAlpha / CARD_ALPHA_HIDING_CALLOUT);
if (row.paintAlpha > 0.001) paintDetectionCallout(ctx, row, row.paintAlpha);
}
ctx.globalAlpha = 1;
}
@@ -1216,6 +1289,8 @@ function _materializeCandidate(
primary,
micro,
hasMicro: card.hasMicro,
cardSourceId: obj.cardSourceId ? String(obj.cardSourceId) : '',
cardEntryId: obj.cardEntryId ? String(obj.cardEntryId) : '',
};
}
@@ -1319,6 +1394,9 @@ function _drawOverlay(frame) {
// every host lane. Detection retains the manual scalar projection below.
const occluder = frame.occluder;
const camPos = frame.cameraPosition;
// Answers to the occlusion tests started on earlier frames land here.
_surfaceOcclusion.beginFrame(now);
_occlusionProbe.beginFrame(_surfaceOcclusion.now);
const keyhole = frame.keyhole;
// Read the OUTSIDE setting ONCE per paint, from the same module state the
// host's own keyhole alpha comes from, so a bracket and its callout can never
@@ -1432,6 +1510,29 @@ function _drawOverlay(frame) {
// The bracket follows the same linear radial keyhole fade as its callout.
const color = colorFor(resolveTier(obj));
const keyholeAlpha = keyholeLabelAlphaFromGeometry(sx, sy, keyhole);
// Something the scene drew in front of a depth-tested contact hides its
// bracket and callout too, on every frame, not only on solves.
if (obj.depthTested === true) {
const testedLayerId = obj._layerId || 'unknown';
const testedSourceId = obj.sourceId ?? obj.id ?? i;
const hidden = _surfaceOcclusion.isHidden(
testedLayerId,
testedSourceId,
obj.position,
);
// If the arbiter holds a callout for this contact it would keep painting
// it until the next solve, and then fade it out where it last stood;
// see `_surfaceSuppressedKeys`. Only held contacts cost a key.
if (
(hidden || _surfaceSuppressedKeys.size > 0) &&
renderIdentities.get(testedLayerId)?.has(testedSourceId)
) {
const key = _detectionKey(testedLayerId, testedSourceId);
if (hidden) _surfaceSuppressedKeys.add(key);
else _surfaceSuppressedKeys.delete(key);
}
if (hidden) continue;
}
const sonarFactor =
sonarActive && !obj.skipLabel ? sonarSampler.at(sx, sy) : 1;
const sonarLabelFactor = sonarSampler.label(sonarFactor);
@@ -1532,6 +1633,8 @@ function _drawOverlay(frame) {
candidateMap.set(candidate.key, candidate);
}
}
// Start this frame's occlusion tests; nothing here waits for them.
_occlusionProbe.endFrame();
const altitude = _eyeHeight(frame) ?? 1e9;
const collectiveBudget = labelBudgetFor(altitude, _densityPct);
@@ -1542,6 +1645,13 @@ function _drawOverlay(frame) {
let didSolve = false;
let solveMs = 0;
if (shouldSolve) {
_surfaceOcclusion.prune();
if (_occlusionProbe.mode === 'sync' && !_surfaceDepthFallbackReported) {
_surfaceDepthFallbackReported = true;
console.info(
'[detection] No occlusion queries here (WebGL 1); street-vehicle label occlusion reads the frame depth back synchronously, about 8 times a second.',
);
}
const quotas = allocateLayerQuotas(
demandByLayer,
ambientBudget,
@@ -1628,7 +1738,25 @@ function _drawOverlay(frame) {
_ctx.lineWidth = bracketWidth;
}
const renderEntries = _labelArbiter.renderEntries(candidateMap, now);
let renderEntries = _labelArbiter.renderEntries(candidateMap, now);
// A callout whose contact has gone behind something goes with it at once:
// no carry-over to the next solve and no fade painted on the facade.
if (_surfaceSuppressedKeys.size > 0) {
const allEntries = renderEntries;
renderEntries = allEntries.filter(
(entry) => !_surfaceSuppressedKeys.has(entry.candidate.key),
);
// The arbiter has let some of them go: forget those.
if (
allEntries.length - renderEntries.length !==
_surfaceSuppressedKeys.size
) {
const held = new Set();
for (const entry of allEntries) held.add(entry.candidate.key);
for (const key of _surfaceSuppressedKeys)
if (!held.has(key)) _surfaceSuppressedKeys.delete(key);
}
}
const fadingCount = countFadingRenderEntries(renderEntries);
// Demand counts fades in BOTH directions; `fadingCount` above stays the
// fade-OUT tail because that is what the published diagnostics have always
@@ -1683,6 +1811,13 @@ function _drawOverlay(frame) {
keyholeRadius: keyhole.radius,
keyholeFeatherPx: keyhole.featherPx,
calloutOcclusionCount: calloutOcclusionRects.length,
surfaceTestedCount: _surfaceOcclusion.testedCount,
surfaceHiddenCount: _surfaceOcclusion.hiddenCount,
surfaceDepthMode: _occlusionProbe.mode,
// Tests started on the last frame, and what collecting answers and
// drawing them cost it.
surfaceProbeTests: _occlusionProbe.lastFrameTests,
surfaceProbeMs: _occlusionProbe.lastFrameMs,
};
} else {
const selectedCount = _labelArbiter.selectedKeys.size;
+478
View File
@@ -21,15 +21,31 @@ import {
} from './detection.js';
import {
destroyWorldOverlay,
getOverlayPaintRect,
initWorldOverlay,
setOverlayEntries,
} from '../overlays/worldOverlay.js';
import { applyVesselOverlayPolicy } from './vesselLabels.js';
import {
getKeyholeFadeTuning,
getKeyholeGeometry,
keyholeLabelAlphaFromGeometry,
} from '../celestialRing.js';
import { DETECTION_THEME_MAP } from '../overlays/worldOverlayTokens.js';
import {
clearAwarenessEchoField,
setAwarenessEchoField,
} from '../awarenessEcho.js';
import { composeLabel, resolveTier } from './detectionDraw.js';
import {
createFakeDepthScene,
createFakeGl,
depthImage,
viewDistanceToDepth,
} from '../render/cesium/fixtures/fakeDepthScene.mjs';
import { createViewerOcclusionProbe } from '../render/cesium/sceneOcclusionProbe.js';
import { provideApplicationHooks } from '../render/applicationHooks.js';
import { rendererOf } from '../render/rendererOf.js';
test('detection diagnostics count rendered fading rows instead of absent selected identities', () => {
assert.equal(countFadingRenderEntries([
@@ -600,6 +616,178 @@ test('every style paints its OWN plate token through the production callout path
}
});
/** A vessel detection contact that names its ambient card, like the AIS layer does. */
function shipWithCard(mmsi, position) {
return {
position,
sourceId: mmsi,
id: `SHIP-${mmsi}`,
metric: '6 kn',
type: 'SEA',
cardSourceId: 'ais-live-vessels',
cardEntryId: `vessel:${mmsi}`,
};
}
/** The production ambient vessel card (not protected: it goes through the arbiter). */
function ambientVesselCard(mmsi, position) {
return applyVesselOverlayPolicy({
id: `vessel:${mmsi}`,
position,
title: `CARD-${mmsi}`,
details: ['CARGO · 6KT · 80°'],
gapPx: 10,
});
}
test('a callout stays readable when its own card is faded out at the keyhole rim', () => {
// Default keyhole tuning: 7% feather, 1% outside opacity.
assert.deepEqual(getKeyholeFadeTuning(), { fadeRatio: 0.07, outsideOpacity: 0.01 });
const width = 1600;
const height = 900;
const keyhole = getKeyholeGeometry(width, height);
const env = installEnvironment({ width, height, dpr: 1 });
// Just outside the keyhole's left rim: the card sits above or below the
// anchor (outside, 1% alpha), the callout to its right (inside the feather).
const position = new Cesium.Cartesian3(270 / (width / 2) - 1, 1 - 460 / (height / 2), 6_356_752);
const ship = shipWithCard('200', position);
try {
initWorldOverlay(env.viewer);
initDetection(env.viewer, [{ id: 'ais-live-vessels', getDetectableObjects: () => [ship] }], () => {});
setMode('DENSE');
for (let i = 0; i < 4; i++) settleFrame(env);
const [alone] = getDetectionDiagnostics().calloutRects;
assert.ok(alone && alone.alpha >= 0.5, 'without a card the callout is clearly visible');
setOverlayEntries('ais-live-vessels', [ambientVesselCard('200', position)]);
for (let i = 0; i < 4; i++) settleFrame(env);
const rect = getOverlayPaintRect('ais-live-vessels', 'vessel:200');
assert.ok(rect, 'the host paints the card (at the outside opacity)');
const cardAlpha = keyholeLabelAlphaFromGeometry(rect.x + rect.w / 2, rect.y + rect.h / 2, keyhole);
assert.ok(cardAlpha <= 0.05, `the card is invisible at the rim (keyhole alpha ${cardAlpha})`);
const callouts = getDetectionDiagnostics().calloutRects;
assert.equal(callouts.length, 1, 'the callout keeps painting while its card is faded out');
assert.ok(callouts[0].alpha >= 0.4, 'and stays readable');
} finally {
destroyDetection();
destroyWorldOverlay();
env.cleanup();
}
});
test('a callout stays hidden while its card fades out after leaving the published cohort', () => {
const env = installEnvironment({ width: 1600, height: 900, dpr: 1 });
const at = (x, y) => new Cesium.Cartesian3(x, y, 6_356_752);
const ship = shipWithCard('200', at(0.1, 0.1));
const painted = (text) => env.ctx.calls.some(([name, value]) => name === 'fillText' && value === text);
const frame = (ms) => {
env.ctx.calls.length = 0;
env.advance(ms);
env.postRender.raise();
};
try {
initWorldOverlay(env.viewer);
initDetection(env.viewer, [{ id: 'ais-live-vessels', getDetectableObjects: () => [ship] }], () => {});
setMode('DENSE');
setOverlayEntries('ais-live-vessels', [ambientVesselCard('200', ship.position)]);
for (let i = 0; i < 6; i++) frame(250);
frame(16);
assert.ok(painted('CARD-200') && !painted('SHIP-200'), 'steady state: card only');
// The vessel layer republishes its screen-grid cohort after a camera move:
// this vessel's card is replaced by another one, the vessel stays detectable.
setOverlayEntries('ais-live-vessels', [ambientVesselCard('300', at(-0.5, -0.4))]);
frame(16);
assert.ok(getOverlayPaintRect('ais-live-vessels', 'vessel:200'), 'the dropped card is still fading out');
assert.ok(painted('CARD-200'), 'and its text still paints');
assert.ok(!painted('SHIP-200'), 'no full callout under the fading card');
for (let i = 0; i < 4; i++) frame(250);
assert.ok(!painted('CARD-200'), 'the card has faded out');
assert.ok(painted('SHIP-200'), 'and the callout is back');
} finally {
destroyDetection();
destroyWorldOverlay();
env.cleanup();
}
});
test('a vessel whose ambient card loses the collision keeps its callout', () => {
const env = installEnvironment({ width: 900, height: 600, dpr: 1 });
// Four vessels a few pixels apart: their cards collide (a card goes only
// above or below its anchor), so the arbiter paints only some of them.
const ships = [0, 1, 2, 3].map((i) =>
shipWithCard(String(100 + i), new Cesium.Cartesian3(-0.2 + i * 0.005, i * 0.005, 6_356_752)),
);
const painted = (text) => env.ctx.calls.some(([name, value]) => name === 'fillText' && value === text);
try {
initWorldOverlay(env.viewer);
initDetection(env.viewer, [{ id: 'ais-live-vessels', getDetectableObjects: () => ships }], () => {});
setOverlayEntries(
'ais-live-vessels',
ships.map((ship) => ambientVesselCard(ship.sourceId, ship.position)),
);
setMode('DENSE');
for (let i = 0; i < 4; i++) settleFrame(env);
env.ctx.calls.length = 0;
settleFrame(env);
const winners = ships.filter((ship) => getOverlayPaintRect('ais-live-vessels', ship.cardEntryId));
assert.ok(
winners.length >= 1 && winners.length < ships.length,
`the colliding cards leave some unpainted (${winners.length} of ${ships.length} painted)`,
);
for (const ship of ships) {
const carded = winners.includes(ship);
assert.equal(
painted(ship.id),
!carded,
carded ? `${ship.id} draws no callout under its card` : `${ship.id} keeps its callout`,
);
}
assert.equal(
getDetectionDiagnostics().calloutRects.length,
ships.length - winners.length,
'only the callouts that painted are reported',
);
} finally {
destroyDetection();
destroyWorldOverlay();
env.cleanup();
}
});
test('a callout fades out while its card fades in instead of vanishing at once', () => {
const env = installEnvironment({ width: 1600, height: 900, dpr: 1 });
const ship = shipWithCard('200', new Cesium.Cartesian3(0.1, 0.1, 6_356_752));
try {
initWorldOverlay(env.viewer);
initDetection(env.viewer, [{ id: 'ais-live-vessels', getDetectableObjects: () => [ship] }], () => {});
setMode('DENSE');
for (let i = 0; i < 4; i++) settleFrame(env);
const [alone] = getDetectionDiagnostics().calloutRects;
assert.ok(alone.alpha >= 0.9, 'the callout starts fully visible');
setOverlayEntries('ais-live-vessels', [ambientVesselCard('200', ship.position)]);
const alphas = [];
for (let i = 0; i < 30; i++) {
env.advance(16);
env.postRender.raise();
alphas.push(getDetectionDiagnostics().calloutRects[0]?.alpha ?? 0);
}
assert.ok(
alphas.some((alpha) => alpha > 0.1 && alpha < alone.alpha - 0.1),
`the callout passes through partial opacity: ${alphas.map((a) => a.toFixed(2)).join(' ')}`,
);
assert.equal(alphas.at(-1), 0, 'and is gone once the card is fully in');
} finally {
destroyDetection();
destroyWorldOverlay();
env.cleanup();
}
});
test('space-tier callouts take the heavier plate while air contacts keep the light one', () => {
// Satellites sit over the high-albedo lit Earth disc far more often than
// aircraft do, so the space tier carries the heavier backing. Losing the
@@ -1211,3 +1399,293 @@ test('transit contacts take the vehicle tier, not the civil-air one', () => {
assert.equal(resolveTier({ type: 'AIR' }), 'civil');
assert.equal(resolveTier({ type: 'SEA' }), 'sea');
});
/**
* Give the host environment a scene that keeps frame depth: the camera 10,000
* km up the +Z axis looking down it, and one depth range in which the whole
* frame is a surface `surfaceDistance()` metres in front of the camera.
*/
function installDepthScene(env, surfaceDistance, { webgl2 = true } = {}) {
const near = 1;
const far = 100_000_000;
const gl = createFakeGl({ webgl2 });
const camera = env.viewer.camera;
camera.viewMatrix = Cesium.Matrix4.fromTranslation(new Cesium.Cartesian3(0, 0, -10_000_000));
camera.frustum.fovy = Math.PI / 2;
camera.frustum.aspectRatio = 800 / 600;
const paint = () =>
depthImage(8, 6, () => viewDistanceToDepth(surfaceDistance(), near, far, true));
const image = paint();
const scene = createFakeDepthScene({ gl, ranges: [{ near, far, image }] });
Object.assign(env.viewer.scene, scene, { camera });
// The renderer's occlusion probe, as the Cesium renderer hands it over.
provideApplicationHooks(rendererOf(env.viewer), {
createOcclusionProbe: () => createViewerOcclusionProbe(env.viewer),
});
return {
gl,
/** Draw the next frame's depth. */
redraw() {
image.data.set(paint().data);
},
};
}
/** Street contacts 3,643 km and 2,000 km below the camera, and a flight. */
function occlusionLayers() {
return [
{
id: 'traffic',
getDetectableObjects: () => [
{ position: new Cesium.Cartesian3(-0.4, 0, 6_356_752), id: 'VEH-0001', type: 'VEH', depthTested: true },
{ position: new Cesium.Cartesian3(0.4, 0, 8_000_000), id: 'VEH-0002', type: 'VEH', depthTested: true },
],
},
{
id: 'flights',
// The same nearer surface is in front of it, but it is not depth-tested.
getDetectableObjects: () => [
{ position: new Cesium.Cartesian3(-0.4, 0.3, 6_356_752), sourceId: 'f1', id: 'AIR1', metric: 'FL300', type: 'AIR' },
],
},
];
}
function paintedText(env) {
return env.ctx.calls.filter(([name]) => name === 'fillText').map(([, text]) => text);
}
/** One rendered frame 16 ms on; `settleFrame` is one 250 ms on (a solve). */
function nextFrame(env) {
env.advance(16);
env.postRender.raise();
}
test('a depth-tested contact behind drawn geometry loses its bracket and callout, tested on the GPU without anything read back', () => {
const env = installEnvironment();
// A roof 3,000 km below the camera: in front of VEH-0001, behind VEH-0002.
let surface = 3_000_000;
const depth = installDepthScene(env, () => surface);
try {
initWorldOverlay(env.viewer);
initDetection(env.viewer, occlusionLayers(), () => {});
setMode('DENSE');
settleFrame(env);
let diagnostics = getDetectionDiagnostics();
assert.equal(diagnostics.surfaceDepthMode, 'async');
assert.equal(diagnostics.surfaceTestedCount, 2, 'only the depth-tested contacts');
assert.equal(diagnostics.surfaceProbeTests, 2);
// New to the view, so held back for the frame or two the first answer
// takes: neither is drawn yet. The flight is.
assert.equal(diagnostics.surfaceHiddenCount, 2, 'no answer has arrived yet');
assert.equal(diagnostics.visibleCount, 1);
assert.equal(depth.gl.counts.queries, 3, 'a control point and one query per contact');
// Frames before the GPU answers start nothing new and wait for nothing.
nextFrame(env);
nextFrame(env);
assert.equal(depth.gl.counts.queries, 3);
assert.equal(depth.gl.counts.resultReads, 0);
// The answers land. The contact above the roof is drawn from then on; the
// one under it never is.
depth.gl.finishGpu();
nextFrame(env);
depth.gl.finishGpu();
settleFrame(env);
env.ctx.calls.length = 0;
nextFrame(env);
assert.ok(!paintedText(env).includes('VEH-0001'));
assert.ok(paintedText(env).includes('VEH-0002'));
// It stays gone, frame after frame and solve after solve.
for (let i = 0; i < 40; i++) {
depth.gl.finishGpu();
env.ctx.calls.length = 0;
nextFrame(env);
assert.ok(!paintedText(env).includes('VEH-0001'), `frame ${i}`);
}
depth.gl.finishGpu();
settleFrame(env);
diagnostics = getDetectionDiagnostics();
assert.equal(diagnostics.surfaceHiddenCount, 1);
assert.equal(diagnostics.visibleCount, 2, 'the hidden contact has no bracket');
assert.ok(diagnostics.labeledKeys.includes('traffic:VEH-0002'));
assert.ok(!diagnostics.labeledKeys.includes('traffic:VEH-0001'));
assert.ok(diagnostics.labeledKeys.includes('flights:f1'));
assert.ok(paintedText(env).includes('AIR1'));
assert.equal(depth.gl.counts.readPixels, 0, 'depth never left the GPU');
// The roof goes away: the bracket returns once visible answers have kept
// coming for the reappear time, and the callout once a solve re-admits it.
surface = 5_000_000;
depth.redraw();
for (let i = 0; i < 80; i++) {
depth.gl.finishGpu();
nextFrame(env);
}
for (let i = 0; i < 8; i++) {
depth.gl.finishGpu();
settleFrame(env);
}
diagnostics = getDetectionDiagnostics();
assert.equal(diagnostics.surfaceHiddenCount, 0);
assert.equal(diagnostics.visibleCount, 3);
assert.ok(diagnostics.labeledKeys.includes('traffic:VEH-0001'));
} finally {
env.cleanup();
}
});
test('a labelled contact that goes behind something loses its callout at once, and does not get it back by leaving the view', () => {
const env = installEnvironment();
// To begin with the drawn surface is below both vehicles.
let surface = 5_000_000;
const depth = installDepthScene(env, () => surface);
const layers = occlusionLayers();
const everyVehicle = layers[0].getDetectableObjects;
const answerAndSolve = (count) => {
for (let i = 0; i < count; i++) {
depth.gl.finishGpu();
settleFrame(env);
}
};
try {
initWorldOverlay(env.viewer);
initDetection(env.viewer, layers, () => {});
setMode('DENSE');
answerAndSolve(6);
assert.ok(getDetectionDiagnostics().labeledKeys.includes('traffic:VEH-0001'));
env.ctx.calls.length = 0;
nextFrame(env);
assert.ok(paintedText(env).includes('VEH-0001'));
// A roof is drawn over VEH-0001. Its callout goes on the frame the answer
// lands, which is not a solve: no carry-over, no fade.
surface = 3_000_000;
depth.redraw();
let gone = -1;
for (let i = 0; i < 30 && gone < 0; i++) {
depth.gl.finishGpu();
env.ctx.calls.length = 0;
nextFrame(env);
if (!paintedText(env).includes('VEH-0001')) gone = i;
}
assert.ok(gone >= 0, 'the callout went');
// The layer stops reporting it (it drove out of view). The arbiter still
// remembers where its callout was; it must not paint it there again.
layers[0].getDetectableObjects = () => everyVehicle().slice(1);
for (let i = 0; i < 12; i++) {
depth.gl.finishGpu();
env.ctx.calls.length = 0;
nextFrame(env);
assert.ok(!paintedText(env).includes('VEH-0001'), `frame ${i}`);
}
} finally {
env.cleanup();
}
});
test('without scene depth every contact keeps its bracket and callout', () => {
const env = installEnvironment();
try {
initWorldOverlay(env.viewer);
initDetection(env.viewer, occlusionLayers(), () => {});
setMode('DENSE');
settleFrame(env);
settleFrame(env);
const diagnostics = getDetectionDiagnostics();
assert.equal(diagnostics.surfaceDepthMode, 'off');
assert.equal(diagnostics.surfaceTestedCount, 2);
assert.equal(diagnostics.surfaceProbeTests, 0);
assert.equal(diagnostics.surfaceHiddenCount, 0);
assert.equal(diagnostics.visibleCount, 3);
assert.ok(diagnostics.labeledKeys.includes('traffic:VEH-0001'));
} finally {
env.cleanup();
}
});
test('scene depth that goes away puts hidden contacts back', () => {
const env = installEnvironment();
const depth = installDepthScene(env, () => 3_000_000);
try {
initWorldOverlay(env.viewer);
initDetection(env.viewer, occlusionLayers(), () => {});
setMode('DENSE');
settleFrame(env);
depth.gl.finishGpu();
settleFrame(env);
assert.equal(getDetectionDiagnostics().surfaceHiddenCount, 1);
// The scene stops keeping pick depth (a 2D view, depth picking turned off).
depth.gl.finishGpu();
env.viewer.scene.useDepthPicking = false;
// The hidden time runs on painted frames, so paint a second's worth.
for (let i = 0; i < 70; i++) nextFrame(env);
settleFrame(env);
const diagnostics = getDetectionDiagnostics();
assert.equal(diagnostics.surfaceDepthMode, 'off');
assert.equal(diagnostics.surfaceHiddenCount, 0);
assert.equal(diagnostics.visibleCount, 3);
} finally {
env.cleanup();
}
});
test('turning detection off drops every test in flight; tearing it down frees the GPU objects', () => {
const env = installEnvironment();
const depth = installDepthScene(env, () => 3_000_000);
try {
initWorldOverlay(env.viewer);
initDetection(env.viewer, occlusionLayers(), () => {});
setMode('DENSE');
settleFrame(env);
assert.equal(depth.gl.liveQueries.size, 3);
// Off keeps the GPU objects (the shader is not compiled again on the next
// on) but the answers in flight are no longer wanted.
setMode('OFF');
assert.equal(depth.gl.counts.deleted, 0);
depth.gl.finishGpu();
setMode('DENSE');
settleFrame(env);
assert.equal(depth.gl.counts.queries, 6, 'both contacts are tested afresh');
assert.equal(depth.gl.liveQueries.size, 3, 'on the same queries, reused');
depth.gl.finishGpu();
nextFrame(env);
settleFrame(env);
assert.equal(getDetectionDiagnostics().surfaceHiddenCount, 1);
assert.equal(getDetectionDiagnostics().visibleCount, 2);
} finally {
env.cleanup();
}
// Tearing detection down releases everything.
assert.equal(depth.gl.liveQueries.size, 0);
assert.equal(depth.gl.counts.deleted, 5);
});
test('a WebGL 1 scene reads depth synchronously and reports it once', () => {
const env = installEnvironment();
const depth = installDepthScene(env, () => 3_000_000, { webgl2: false });
const originalInfo = console.info;
const reported = [];
console.info = (...args) => reported.push(args.join(' '));
try {
initWorldOverlay(env.viewer);
initDetection(env.viewer, occlusionLayers(), () => {});
setMode('DENSE');
for (let i = 0; i < 30; i++) nextFrame(env);
settleFrame(env);
const diagnostics = getDetectionDiagnostics();
assert.equal(diagnostics.surfaceDepthMode, 'sync');
assert.equal(diagnostics.surfaceHiddenCount, 1);
assert.equal(diagnostics.visibleCount, 2);
// Half a second of frames: a read about every eighth of one, not one per
// frame and not one per contact.
assert.ok(depth.gl.counts.readPixels >= 3 && depth.gl.counts.readPixels <= 6, `${depth.gl.counts.readPixels} reads`);
assert.equal(reported.length, 1);
assert.match(reported[0], /synchronously/);
} finally {
console.info = originalInfo;
env.cleanup();
}
});
+467
View File
@@ -0,0 +1,467 @@
/**
* Scene-geometry occlusion for detection contacts.
*
* The overlay's own horizon test only knows about the Earth's curve. A contact
* whose marker the scene depth-tests (a street vehicle's dot) can still sit
* behind a building, a 3D tile or a hill, and painting its bracket and callout
* there puts a label on the facade in front of it.
*
* The fix compares each such contact with what the renderer actually drew: if
* the drawn surface along the contact's ray is nearer than the contact by more
* than a small margin, something stands in front of it and its bracket and
* callout are not drawn. The renderer's occlusion probe (an application hook;
* the Cesium renderer's is `src/render/cesium/sceneOcclusionProbe.js`) runs
* that comparison on the GPU, against the frame's own depth, and hands back a yes or no per contact a
* frame or two later without ever waiting on the GPU. This file holds the
* arithmetic both sides share and the per-contact memory of the answers.
*
* Only contacts that opt in with `depthTested: true` are tested: the ones whose
* marker the scene itself hides behind geometry. Everything else keeps its
* label exactly as before, which covers contacts high above the ground
* (aircraft, satellites): their markers are drawn on top of the scene by
* design, their 3D models can be scaled up to a minimum pixel size and so fill
* the very pixel being read, and a label that hid while its marker stayed on
* screen would be the worse mismatch.
*
* This file is plain arithmetic; it never touches the renderer.
*/
/** Never less than this: covers a dot drawn a little above or into its road. */
export const SURFACE_OCCLUSION_MIN_MARGIN_M = 3;
/** The most the margin grows with range: 2% of it. */
export const SURFACE_OCCLUSION_MARGIN_FRACTION = 0.02;
/**
* How far above a contact a drawn surface on its line of sight must stand to
* count as in front of it, when the camera looks down on the contact.
*/
export const SURFACE_OCCLUSION_RISE_M = 2;
/**
* How much nearer than the contact the drawn surface must be before it counts
* as standing in front of it.
*
* The margin absorbs a contact placed a little above or below the drawn
* ground: a vehicle's position and the scene's road surface are not the same
* height to the metre. Looking down at the contact, a point on its line of
* sight `s` metres in front of it stands `s * sinElevation` metres above it,
* so a surface there only hides the contact once `s` passes
* `SURFACE_OCCLUSION_RISE_M / sinElevation`. That keeps the margin to a few
* metres from above, where a fixed share of the range would let a wall,
* awning or tree 10 to 20 m in front of a street at 1 km pass as "the road".
* At grazing angles, or looking up, the margin is 2% of the range at most
* (never under 3 m); depth precision is far finer than that at every range
* the overlay labels.
*
* @param {number} contactDistance Camera-to-contact distance in metres.
* @param {number} [sinElevation] Sine of the camera's elevation seen from the
* contact (1 straight overhead, 0 level, negative below); unknown when
* omitted.
* @returns {number} Margin in metres.
*/
export function surfaceOcclusionMargin(contactDistance, sinElevation = 0) {
const distance = Number(contactDistance);
if (!(distance > 0)) return SURFACE_OCCLUSION_MIN_MARGIN_M;
let margin = distance * SURFACE_OCCLUSION_MARGIN_FRACTION;
const rise = Number(sinElevation);
if (rise > 0) margin = Math.min(margin, SURFACE_OCCLUSION_RISE_M / rise);
return Math.max(SURFACE_OCCLUSION_MIN_MARGIN_M, margin);
}
/**
* Whether a drawn surface hides a contact.
* @param {number} contactDistance Camera-to-contact distance in metres.
* @param {number|undefined} surfaceDistance Camera-to-drawn-surface distance
* along the contact's ray; undefined or non-finite when nothing was drawn.
* @param {number} [sinElevation] See `surfaceOcclusionMargin`.
* @returns {boolean}
*/
export function surfaceHidesContact(
contactDistance,
surfaceDistance,
sinElevation = 0,
) {
if (!Number.isFinite(contactDistance) || !Number.isFinite(surfaceDistance))
return false;
return (
surfaceDistance <
contactDistance - surfaceOcclusionMargin(contactDistance, sinElevation)
);
}
/**
* Unpack a depth the renderer stored across the four bytes of an RGBA8 texel
* (most significant byte first, each byte a base-255 digit).
* @param {ArrayLike<number>} bytes
* @param {number} offset Index of the texel's red byte.
* @returns {number} Window-space depth in [0, 1].
*/
export function unpackDepth(bytes, offset) {
return (
bytes[offset] / 255 +
bytes[offset + 1] / 65025 +
bytes[offset + 2] / 16581375 +
bytes[offset + 3] / 4228250625
);
}
/**
* Convert a window-space depth to the distance in front of the camera, measured
* along the view direction, for one depth range ("frustum") of the frame.
*
* Logarithmic depth stores `log2(z - near + 1) / log2(far - near + 1)`.
* Standard perspective depth stores `far * (z - near) / (z * (far - near))`.
*
* @param {number} depth Window-space depth in [0, 1].
* @param {number} near Near plane of the range, metres.
* @param {number} far Far plane of the range, metres.
* @param {boolean} logDepth Whether the frame was drawn with logarithmic depth.
* @returns {number} Metres along the view direction, or NaN where the range
* drew nothing (depth at or outside the ends of [0, 1]).
*/
export function depthToViewDistance(depth, near, far, logDepth) {
if (!(depth > 0) || !(depth < 1)) return Number.NaN;
if (!(near > 0) || !(far > near)) return Number.NaN;
if (logDepth)
return near + Math.pow(2, depth * Math.log2(far - near + 1)) - 1;
return (near * far) / (far - depth * (far - near));
}
/**
* Where a world position falls in a frame, and how near a drawn surface has to
* be there to hide it.
*
* A surface hides the contact when its distance along the contact's ray is
* under the contact's own distance less the margin. Along one ray, distance
* and view distance (depth in front of the camera) are in a fixed ratio, so
* the same rule reads: the surface's view distance is under
* `viewDistance * (1 - margin / contactDistance)`. That number is `threshold`,
* and comparing a decoded depth with it is all the GPU has to do.
*
* The margin depends on how steeply the camera looks down on the contact
* (see `surfaceOcclusionMargin`). "Up" at the contact is taken as the
* direction from the world origin to it, which is the Earth's centre in the
* Earth-fixed frame the scene is drawn in; it differs from the true vertical
* by a fraction of a degree at most.
*
* @param {ArrayLike<number>} view World-to-camera matrix, column-major, the
* camera looking down its own -Z axis.
* @param {number} tanHalfFovX
* @param {number} tanHalfFovY
* @param {{x: number, y: number, z: number}} position
* @param {{u: number, v: number, threshold: number}} out `u`, `v` in [0, 1)
* from the bottom-left corner of the frame.
* @returns {boolean} False when the position is behind the camera or outside
* the frame; `out` is then untouched.
*/
export function projectContact(view, tanHalfFovX, tanHalfFovY, position, out) {
const { x, y, z } = position;
const viewDistance = -(view[2] * x + view[6] * y + view[10] * z + view[14]);
if (!(viewDistance > 0)) return false;
const ex = view[0] * x + view[4] * y + view[8] * z + view[12];
const ey = view[1] * x + view[5] * y + view[9] * z + view[13];
const u = (ex / (viewDistance * tanHalfFovX)) * 0.5 + 0.5;
const v = (ey / (viewDistance * tanHalfFovY)) * 0.5 + 0.5;
if (!(u >= 0 && u < 1 && v >= 0 && v < 1)) return false;
const contactDistance = Math.sqrt(
ex * ex + ey * ey + viewDistance * viewDistance,
);
// Up at the contact, turned into camera axes, against the direction from
// the contact to the camera (-ex, -ey, viewDistance in camera axes).
const radius = Math.sqrt(x * x + y * y + z * z);
let sinElevation = 0;
if (radius > 0) {
const ux = (view[0] * x + view[4] * y + view[8] * z) / radius;
const uy = (view[1] * x + view[5] * y + view[9] * z) / radius;
const uz = (view[2] * x + view[6] * y + view[10] * z) / radius;
sinElevation = (-ux * ex - uy * ey + uz * viewDistance) / contactDistance;
}
out.u = u;
out.v = v;
out.threshold =
viewDistance *
(1 -
surfaceOcclusionMargin(contactDistance, sinElevation) / contactDistance);
return true;
}
/**
* One frame of depth read back to memory, with the camera it was drawn from.
* Only the synchronous fallback uses this (see `src/render/cesium/sceneOcclusionProbe.js`); the
* normal path never copies depth off the GPU.
*
* `bytes` holds `frustums.length` stacked images of `width` x `height` RGBA8
* texels, nearest depth range first, rows bottom to top (the order the
* graphics API reads them back in).
*/
export class DepthSnapshot {
/**
* @param {{
* width: number, height: number, bytes: Uint8Array,
* frustums: Array<{near: number, far: number}>, logDepth: boolean,
* view: ArrayLike<number>, tanHalfFovX: number, tanHalfFovY: number,
* }} fields
*/
constructor(fields) {
this.width = fields.width;
this.height = fields.height;
this.bytes = fields.bytes;
this.frustums = fields.frustums;
this.logDepth = fields.logDepth === true;
this.view = fields.view;
this.tanHalfFovX = fields.tanHalfFovX;
this.tanHalfFovY = fields.tanHalfFovY;
this._projected = { u: 0, v: 0, threshold: 0 };
}
/**
* Distance along the view direction to the nearest surface drawn at a texel.
* @param {number} column
* @param {number} row Counted from the bottom of the frame.
* @returns {number} Metres, or NaN where nothing was drawn.
*/
surfaceViewDistance(column, row) {
const { width, height, bytes, frustums, logDepth } = this;
const texel = (row * width + column) * 4;
const layer = width * height * 4;
for (let i = 0; i < frustums.length; i++) {
const distance = depthToViewDistance(
unpackDepth(bytes, i * layer + texel),
frustums[i].near,
frustums[i].far,
logDepth,
);
if (distance === distance) return distance;
}
return Number.NaN;
}
/**
* Whether the frame drew something in front of a world position.
* @param {{x: number, y: number, z: number}} position
* @returns {boolean|null} Null when the position is outside the frame.
*/
hides(position) {
const projected = this._projected;
if (
!projectContact(
this.view,
this.tanHalfFovX,
this.tanHalfFovY,
position,
projected,
)
)
return null;
return (
this.surfaceViewDistance(
Math.floor(projected.u * this.width),
Math.floor(projected.v * this.height),
) < projected.threshold
);
}
}
/**
* A contact is tested again at most this long, and at least half this long,
* after its last test was started, so a view full of contacts spreads its
* tests over about ten frames instead of repeating all of them on every one.
* With more contacts in view than the probe's per-frame budget can serve at
* that pace, the interval stretches (see `SurfaceOcclusion.beginFrame`).
*/
export const SURFACE_RETEST_MS = 200;
/**
* A contact stays hidden at least this long after the last test that found it
* hidden, and never less than three retest intervals.
*
* Going behind something takes effect as soon as the answer arrives. Coming
* back takes several visible answers in a row, so a contact on a silhouette
* edge, which tests either way from one frame to the next while the camera
* orbits, stays off instead of blinking. It is also the clean failure: when
* answers stop arriving (no depth to test against) every contact is drawn
* again within this time, exactly as before this test existed.
*/
export const SURFACE_REAPPEAR_MS = 600;
/**
* A contact that has never had an answer is held back this long, at most,
* while a working probe gets it one.
*
* A contact new to the view would otherwise be drawn for the frame or two its
* first test takes, and then vanish if it turned out to be behind something:
* a camera orbiting a city would flash a bracket for every vehicle that
* swings into the frame behind a building. With no working probe nothing is
* held back, and past this time the contact is drawn whatever happens.
*/
export const SURFACE_FIRST_ANSWER_MS = 400;
/**
* The most one frame advances the occlusion clock.
*
* Every interval above is measured on a clock that only runs while the
* overlay is painting: each painted frame moves it on by the time since the
* last one, but never by more than this. Answers only arrive while frames are
* painted, so on a wall clock a pause (a hidden tab, a scene with nothing to
* redraw) would run out every "hidden" at once and the first frame afterwards
* would paint every label over the buildings again until fresh answers came.
* On this clock a pause of any length counts as one slow frame.
*/
export const SURFACE_MAX_FRAME_STEP_MS = 50;
/** A contact not drawn for this long is forgotten. */
export const SURFACE_FORGET_MS = 2000;
/**
* What is remembered about one contact.
* @typedef {{lastHiddenAt: number, hiddenUntil: number, appliedHiddenAt: number,
* queuedAt: number, pending: boolean, answered: boolean, firstSeenAt: number,
* seenAt: number}} SurfaceContact Times are on the occlusion clock.
*/
/**
* Per-contact occlusion answers, and the schedule that keeps them fresh.
*
* `probe` is whatever tests a contact against the drawn scene. It has
* `add(contact, position)`, which starts a test (setting `contact.pending`)
* and returns false when it cannot take one now, and it reports back by
* clearing `contact.pending`, setting `contact.answered` and, when the
* contact was hidden, setting `contact.lastHiddenAt`. `probe.maxPerFrame`, if
* set, is how many tests it takes in one frame; `probe.mode` reads `'async'`
* while answers come a frame or two after the test.
*/
export class SurfaceOcclusion {
/**
* @param {{add: (contact: SurfaceContact, position: object) => boolean}} probe
*/
constructor(probe) {
this.probe = probe;
/** @type {Map<string, Map<*, SurfaceContact>>} Layer id -> source id. */
this.contacts = new Map();
/**
* The occlusion clock, in milliseconds of painted time (see
* `SURFACE_MAX_FRAME_STEP_MS`). The probe must date its answers by it.
*/
this.now = 0;
this._wall = Number.NEGATIVE_INFINITY;
/** Depth-tested contacts drawn or hidden this frame. */
this.testedCount = 0;
this.hiddenCount = 0;
this.retestMs = SURFACE_RETEST_MS;
this.reappearMs = SURFACE_REAPPEAR_MS;
this.firstAnswerMs = SURFACE_FIRST_ANSWER_MS;
this._phase = 0;
}
/**
* Open a frame and move the occlusion clock on.
* @param {number} wallNow Monotonic milliseconds.
*/
beginFrame(wallNow) {
// Contacts arrive in the same order every frame and the probe takes only
// so many, so if more fell due per frame than it takes, the ones at the
// end of the order would never be tested. Pace the retests to what the
// last frame showed the probe can keep up with: all of the contacts, once
// per interval, with a third of the budget to spare.
const elapsed = wallNow - this._wall;
const frameMs =
elapsed > 0 ? Math.min(SURFACE_MAX_FRAME_STEP_MS, elapsed) : 0;
this._wall = wallNow;
const budget = Number(this.probe.maxPerFrame) || Number.POSITIVE_INFINITY;
this.retestMs = Math.max(
SURFACE_RETEST_MS,
(this.testedCount / budget) * frameMs * 2,
);
this.reappearMs = Math.max(SURFACE_REAPPEAR_MS, this.retestMs * 3);
// At a stretched pace a crowd of new contacts takes longer to get its
// first answers; the hold-back stretches with it.
this.firstAnswerMs = Math.max(SURFACE_FIRST_ANSWER_MS, this.retestMs * 2);
this.now += frameMs;
this.testedCount = 0;
this.hiddenCount = 0;
}
/**
* Whether a contact's bracket and callout should be left out of this frame.
* Starts a fresh test of the contact when one is due.
* @param {string} layerId
* @param {*} sourceId
* @param {{x: number, y: number, z: number}} position
* @returns {boolean}
*/
isHidden(layerId, sourceId, position) {
const now = this.now;
let layer = this.contacts.get(layerId);
if (!layer) {
layer = new Map();
this.contacts.set(layerId, layer);
}
let contact = layer.get(sourceId);
if (!contact || now - contact.seenAt > this.retestMs) {
// New, or back in view after longer than a retest interval. A returning
// contact's last answer is older than any contact that stayed in view
// runs on, and the view has probably turned since: it is held back
// like a new one until a fresh answer comes, or orbiting flashes it
// behind the building it went behind while out of view. It gets a new
// record, so a test still in flight from before answers the old one
// and cannot end the hold-back with what the previous view showed. A
// "hidden" it already had keeps running.
contact = {
lastHiddenAt: contact?.lastHiddenAt ?? Number.NEGATIVE_INFINITY,
hiddenUntil: contact?.hiddenUntil ?? Number.NEGATIVE_INFINITY,
appliedHiddenAt: contact?.appliedHiddenAt ?? Number.NEGATIVE_INFINITY,
queuedAt: Number.NEGATIVE_INFINITY,
pending: false,
answered: false,
firstSeenAt: now,
seenAt: now,
};
layer.set(sourceId, contact);
}
contact.seenAt = now;
this.testedCount++;
if (
!contact.pending &&
now - contact.queuedAt >= this.retestMs &&
this.probe.add(contact, position)
) {
// Contacts that came into view together would otherwise all fall due on
// the same frames for ever. Each test backdates itself by a different
// part of half the interval, which spreads them out within a second.
contact.queuedAt = now - this.retestMs * 0.5 * this._phase;
this._phase = (this._phase + 0.618034) % 1;
}
// A new "hidden" answer sets when the contact may come back, once, with
// the pace in force now. A later change of pace must not bring back a
// "hidden" that has already run out.
if (contact.lastHiddenAt !== contact.appliedHiddenAt) {
contact.appliedHiddenAt = contact.lastHiddenAt;
contact.hiddenUntil = contact.lastHiddenAt + this.reappearMs;
}
const hidden =
now < contact.hiddenUntil ||
// Not yet answered: held back while a working probe finds out.
(!contact.answered &&
this.probe.mode === 'async' &&
now - contact.firstSeenAt < this.firstAnswerMs);
if (hidden) this.hiddenCount++;
return hidden;
}
/** Forget contacts that are no longer drawn. */
prune() {
for (const [layerId, layer] of this.contacts) {
for (const [sourceId, contact] of layer) {
if (this.now - contact.seenAt > SURFACE_FORGET_MS)
layer.delete(sourceId);
}
if (layer.size === 0) this.contacts.delete(layerId);
}
}
/** Forget every contact (mode off, viewer swap). */
clear() {
this.contacts.clear();
this.testedCount = 0;
this.hiddenCount = 0;
}
}
+851
View File
@@ -0,0 +1,851 @@
import test from 'node:test';
import assert from 'node:assert/strict';
import {
DepthSnapshot,
SURFACE_FIRST_ANSWER_MS,
SURFACE_FORGET_MS,
SURFACE_MAX_FRAME_STEP_MS,
SURFACE_OCCLUSION_MIN_MARGIN_M,
SURFACE_REAPPEAR_MS,
SURFACE_RETEST_MS,
SurfaceOcclusion,
depthToViewDistance,
projectContact,
surfaceHidesContact,
surfaceOcclusionMargin,
unpackDepth,
} from './detectionOcclusion.js';
import {
depthImage,
packDepth,
viewDistanceToDepth,
} from '../render/cesium/fixtures/fakeDepthScene.mjs';
test('the margin is 3 m near the camera and 2% of the range beyond 150 m', () => {
assert.equal(surfaceOcclusionMargin(10), SURFACE_OCCLUSION_MIN_MARGIN_M);
assert.equal(surfaceOcclusionMargin(150), 3);
assert.equal(surfaceOcclusionMargin(500), 10);
assert.equal(surfaceOcclusionMargin(5000), 100);
assert.equal(surfaceOcclusionMargin(0), 3);
assert.equal(surfaceOcclusionMargin(Number.NaN), 3);
});
test('looking down on a contact, the margin is what a 2 m rise on its line of sight takes', () => {
// 1 km away, seen from 30 degrees up: 2 m of rise is 4 m along the ray.
assert.ok(Math.abs(surfaceOcclusionMargin(1000, 0.5) - 4) < 1e-9);
// Straight down: the 3 m floor.
assert.equal(surfaceOcclusionMargin(1000, 1), SURFACE_OCCLUSION_MIN_MARGIN_M);
// Grazing, level or from below: never more than 2% of the range.
assert.equal(surfaceOcclusionMargin(1000, 0.01), 20);
assert.equal(surfaceOcclusionMargin(1000, 0), 20);
assert.equal(surfaceOcclusionMargin(1000, -0.3), 20);
assert.equal(surfaceOcclusionMargin(1000, Number.NaN), 20);
assert.equal(surfaceOcclusionMargin(100, 0.05), 3);
// A low wall 15 m in front of a street 1 km off, seen from 25 degrees up,
// stands about 6 m above the vehicle's line of sight: it hides it.
const sin25 = Math.sin((25 * Math.PI) / 180);
assert.equal(surfaceHidesContact(1000, 985, sin25), true);
assert.equal(surfaceHidesContact(1000, 985), false, 'unknown angle: 2%');
assert.equal(surfaceHidesContact(1000, 996, sin25), false, 'its own road');
});
test('a surface hides a contact only when nearer by more than the margin', () => {
// 500 m away: margin 10 m.
assert.equal(surfaceHidesContact(500, 489), true, 'a facade 11 m in front');
assert.equal(surfaceHidesContact(500, 491), false, 'its own road or dot');
assert.equal(surfaceHidesContact(500, 500), false);
assert.equal(surfaceHidesContact(500, 520), false, 'the ground behind it');
// Close range keeps the 3 m floor.
assert.equal(surfaceHidesContact(60, 56), true);
assert.equal(surfaceHidesContact(60, 58), false);
});
test('nothing drawn, or no distance, never hides a contact', () => {
assert.equal(surfaceHidesContact(500, undefined), false);
assert.equal(surfaceHidesContact(500, Number.NaN), false);
assert.equal(surfaceHidesContact(Number.NaN, 10), false);
});
test('packed depth unpacks most significant byte first', () => {
assert.equal(unpackDepth([0, 0, 0, 0], 0), 0);
assert.equal(unpackDepth([255, 0, 0, 0], 0), 1);
assert.equal(unpackDepth([9, 9, 51, 0, 0, 0], 2), 0.2);
for (const depth of [0.000123, 0.25, 0.5, 0.987654321]) {
const round = unpackDepth(packDepth(depth), 0);
assert.ok(Math.abs(round - depth) < 1e-9, `${depth} -> ${round}`);
}
});
test('logarithmic depth decodes to metres in front of the camera', () => {
const near = 0.1;
const far = 10_000_000;
// depth = log2(z - near + 1) / log2(far - near + 1)
for (const z of [0.5, 12, 480, 25_000, 3_000_000]) {
const depth = Math.log2(z - near + 1) / Math.log2(far - near + 1);
const decoded = depthToViewDistance(depth, near, far, true);
assert.ok(Math.abs(decoded - z) / z < 1e-9, `${z} -> ${decoded}`);
}
});
test('standard perspective depth decodes to metres in front of the camera', () => {
const near = 1;
const far = 5000;
// depth = far * (z - near) / (z * (far - near))
for (const z of [1.5, 40, 900, 4999]) {
const depth = (far * (z - near)) / (z * (far - near));
const decoded = depthToViewDistance(depth, near, far, false);
assert.ok(Math.abs(decoded - z) / z < 1e-9, `${z} -> ${decoded}`);
}
assert.ok(
Math.abs(depthToViewDistance(0.5, 1, 5000, false) - 10000 / 5001) < 1e-9,
'half depth sits just past twice the near plane',
);
});
test('the ends of the depth range, and a bad range, mean nothing was drawn', () => {
for (const log of [true, false]) {
assert.ok(Number.isNaN(depthToViewDistance(0, 1, 100, log)));
assert.ok(Number.isNaN(depthToViewDistance(1, 1, 100, log)));
assert.ok(Number.isNaN(depthToViewDistance(Number.NaN, 1, 100, log)));
assert.ok(Number.isNaN(depthToViewDistance(0.5, 0, 100, log)));
assert.ok(Number.isNaN(depthToViewDistance(0.5, 100, 100, log)));
}
});
const IDENTITY = [1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1];
/** A point `distance` metres ahead, `side` of the way to the frame edge. */
const ahead = (distance, side = 0, up = 0) => ({
x: side * distance,
y: up * distance,
z: -distance,
});
test('a contact projects to its place in the frame, from the bottom-left corner', () => {
const out = { u: -1, v: -1, threshold: -1 };
// 90 degree field of view: the frame edge is as far out as the point is ahead.
assert.equal(projectContact(IDENTITY, 1, 1, ahead(500), out), true);
assert.deepEqual([out.u, out.v], [0.5, 0.5]);
assert.equal(
projectContact(IDENTITY, 1, 1, ahead(500, -0.5, 0.5), out),
true,
);
assert.deepEqual([out.u, out.v], [0.25, 0.75]);
// A wider horizontal field of view pulls the same point towards the middle.
assert.equal(
projectContact(IDENTITY, 2, 1, ahead(500, -0.5, 0.5), out),
true,
);
assert.deepEqual([out.u, out.v], [0.375, 0.75]);
});
test('the threshold is the margin rule restated as a view distance', () => {
const out = { u: 0, v: 0, threshold: 0 };
// Straight ahead, distance and view distance are the same thing.
projectContact(IDENTITY, 1, 1, ahead(500), out);
assert.ok(Math.abs(out.threshold - 490) < 1e-9, '500 m less 2%');
projectContact(IDENTITY, 1, 1, ahead(60), out);
assert.ok(Math.abs(out.threshold - 57) < 1e-9, '60 m less the 3 m floor');
// Off axis the ray is longer than the view distance; the rule holds along
// the ray, so a surface at view distance d sits d * range / viewDistance out.
const corner = ahead(400, -0.9, 0.9);
const range = Math.hypot(corner.x, corner.y, corner.z);
projectContact(IDENTITY, 1, 1, corner, out);
for (const surfaceView of [out.threshold - 0.01, out.threshold + 0.01]) {
const alongRay = (surfaceView * range) / 400;
assert.equal(
surfaceHidesContact(range, alongRay),
surfaceView < out.threshold,
);
}
assert.ok(Math.abs(out.threshold - 400 * 0.98) < 1e-9);
});
test('the threshold uses how steeply the camera looks down on the contact', () => {
// A street on a sphere the size of the Earth, under a camera 1 km up and
// 1 km back along the surface, looking straight at it: 45 degrees down.
const R = 6_371_000;
const street = { x: 0, y: 0, z: R };
const camera = { x: 0, y: -1000, z: R + 1000 };
// Camera axes: x along world x, looking along (0, 1, -1) / sqrt 2.
const s = Math.SQRT1_2;
const forward = [0, s, -s];
const up = [0, s, s];
const right = [1, 0, 0];
const t = (axis) =>
-(axis[0] * camera.x + axis[1] * camera.y + axis[2] * camera.z);
// Rows: right, up, -forward (the camera looks down its -Z).
const back = forward.map((c) => -c);
const view = [
right[0],
up[0],
back[0],
0,
right[1],
up[1],
back[1],
0,
right[2],
up[2],
back[2],
0,
t(right),
t(up),
t(back),
1,
];
const out = { u: 0, v: 0, threshold: 0 };
assert.equal(projectContact(view, 1, 1, street, out), true);
assert.ok(Math.abs(out.u - 0.5) < 1e-9 && Math.abs(out.v - 0.5) < 1e-9);
const range = Math.SQRT2 * 1000;
// 2 m of rise at 45 degrees is 2.83 m along the ray: the 3 m floor, not
// 2% of 1414 m (28 m).
assert.ok(Math.abs(out.threshold - (range - 3)) < 1e-6, `${out.threshold}`);
});
test('off the middle of the frame, with the camera turned, the threshold matches the world-space rule', () => {
// Rotations about the three axes, then a camera placed and turned freely;
// the threshold must equal the margin rule worked out in world space.
const rot = (ax, ay, az) => {
const [cx, sx, cy, sy, cz, sz] = [
Math.cos(ax),
Math.sin(ax),
Math.cos(ay),
Math.sin(ay),
Math.cos(az),
Math.sin(az),
];
// Rows of Rz * Ry * Rx.
return [
[cz * cy, cz * sy * sx - sz * cx, cz * sy * cx + sz * sx],
[sz * cy, sz * sy * sx + cz * cx, sz * sy * cx - cz * sx],
[-sy, cy * sx, cy * cx],
];
};
const R = 6_371_000;
let checked = 0;
for (let k = 0; k < 200; k++) {
// A deterministic spread of poses.
const a = (n) => Math.sin(k * 12.9898 + n * 78.233) * 3;
const m = rot(a(1), a(2), a(3)); // world-to-camera rotation
const lat = a(4) / 3;
const lon = a(5);
const contact = {
x: R * Math.cos(lat) * Math.cos(lon),
y: R * Math.cos(lat) * Math.sin(lon),
z: R * Math.sin(lat),
};
// Camera 300 to 2300 m from the contact, in a direction above or below it.
const d = [a(6), a(7), a(8)];
const dl = Math.hypot(...d) || 1;
const dist = 1300 + 1000 * Math.sin(k);
const cam = {
x: contact.x + (d[0] / dl) * dist,
y: contact.y + (d[1] / dl) * dist,
z: contact.z + (d[2] / dl) * dist,
};
const t = m.map(
(row) => -(row[0] * cam.x + row[1] * cam.y + row[2] * cam.z),
);
const view = [
m[0][0],
m[1][0],
m[2][0],
0,
m[0][1],
m[1][1],
m[2][1],
0,
m[0][2],
m[1][2],
m[2][2],
0,
t[0],
t[1],
t[2],
1,
];
const out = { u: 0, v: 0, threshold: 0 };
if (!projectContact(view, 2, 2, contact, out)) continue;
checked++;
const toCam = [cam.x - contact.x, cam.y - contact.y, cam.z - contact.z];
const range = Math.hypot(...toCam);
const sinElevation =
(toCam[0] * contact.x + toCam[1] * contact.y + toCam[2] * contact.z) /
(range * R);
const viewDistance = -(
m[2][0] * contact.x +
m[2][1] * contact.y +
m[2][2] * contact.z +
t[2]
);
const expected =
viewDistance * (1 - surfaceOcclusionMargin(range, sinElevation) / range);
assert.ok(
Math.abs(out.threshold - expected) < 1e-6,
`pose ${k}: ${out.threshold} vs ${expected}`,
);
}
assert.ok(checked > 20, `${checked} poses in frame`);
});
test('behind the camera or outside the frame there is nothing to test', () => {
const out = { u: 7, v: 7, threshold: 7 };
assert.equal(
projectContact(IDENTITY, 1, 1, { x: 0, y: 0, z: 500 }, out),
false,
);
assert.equal(
projectContact(IDENTITY, 1, 1, { x: 0, y: 0, z: 0 }, out),
false,
);
assert.equal(projectContact(IDENTITY, 1, 1, ahead(500, -1.2), out), false);
assert.equal(projectContact(IDENTITY, 1, 1, ahead(500, 0, 1.01), out), false);
assert.equal(
projectContact(IDENTITY, 1, 1, ahead(500, 1), out),
false,
'u = 1',
);
assert.deepEqual(out, { u: 7, v: 7, threshold: 7 }, 'left untouched');
});
test('a contact is projected with the camera it is given', () => {
// Camera 1000 m up the +Z axis looking down -Z: view = translate(0, 0, -1000).
const view = [1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, -1000, 1];
const out = { u: 0, v: 0, threshold: 0 };
assert.equal(
projectContact(view, 1, 1, { x: -250, y: 0, z: 500 }, out),
true,
);
assert.equal(out.u, 0.25);
assert.equal(projectContact(view, 1, 1, { x: 0, y: 0, z: 1500 }, out), false);
});
/**
* A snapshot from a camera at the origin looking down -Z with a 90 degree
* field of view. By default one depth range in which the left half of the
* frame is a wall `wall` metres away and the right half is ground `ground`
* metres away.
*/
function snapshotWithWall({
wall = 400,
ground = 500,
logDepth = true,
size = 8,
frustums,
images,
} = {}) {
const ranges = frustums || [{ near: 1, far: 100_000 }];
const layers = images || [
depthImage(size, size, (column) =>
viewDistanceToDepth(
column < size / 2 ? wall : ground,
ranges[0].near,
ranges[0].far,
logDepth,
),
),
];
const bytes = new Uint8Array(size * size * 4 * layers.length);
layers.forEach((image, i) => bytes.set(image.data, i * size * size * 4));
return new DepthSnapshot({
width: size,
height: size,
bytes,
frustums: ranges,
logDepth,
view: IDENTITY,
tanHalfFovX: 1,
tanHalfFovY: 1,
});
}
test('a contact behind a drawn wall is hidden; one on drawn ground, or in front of the wall, is not', () => {
for (const logDepth of [true, false]) {
const snapshot = snapshotWithWall({ logDepth });
assert.equal(snapshot.hides(ahead(500, -0.5)), true);
assert.equal(snapshot.hides(ahead(500, 0.5)), false);
assert.equal(snapshot.hides(ahead(300, -0.5)), false);
// 2% of 405 m is 8.1 m: 5 m behind the wall is still the wall's own face.
assert.equal(snapshot.hides(ahead(405, -0.5)), false);
assert.equal(snapshot.hides(ahead(412, -0.5)), true);
assert.equal(snapshot.hides(ahead(500, -1.5)), null, 'outside the frame');
}
});
test('rows are read bottom to top', () => {
const size = 8;
const image = depthImage(size, size, (_column, row) =>
viewDistanceToDepth(row < size / 2 ? 400 : 500, 1, 100_000, true),
);
const snapshot = snapshotWithWall({ images: [image] });
assert.equal(snapshot.hides(ahead(500, 0, -0.5)), true, 'below centre');
assert.equal(snapshot.hides(ahead(500, 0, 0.5)), false, 'above centre');
});
test('the nearest depth range that drew something answers', () => {
const size = 4;
const frustums = [
{ near: 1, far: 1000 },
{ near: 999, far: 1_000_000 },
];
// Near range: a wall 400 m away on the left, nothing on the right.
const nearImage = depthImage(size, size, (column) =>
column < 2 ? viewDistanceToDepth(400, 1, 1000, true) : 1,
);
// Far range: ground 20 km away everywhere.
const farImage = depthImage(size, size, () =>
viewDistanceToDepth(20_000, 999, 1_000_000, true),
);
const snapshot = snapshotWithWall({
size,
frustums,
images: [nearImage, farImage],
});
assert.ok(Math.abs(snapshot.surfaceViewDistance(0, 0) - 400) < 0.01);
assert.ok(Math.abs(snapshot.surfaceViewDistance(3, 0) - 20_000) < 1);
assert.equal(snapshot.hides(ahead(15_000, -0.5)), true);
assert.equal(snapshot.hides(ahead(15_000, 0.5)), false);
assert.equal(snapshot.hides(ahead(30_000, 0.5)), true);
});
test('where nothing was drawn a contact is visible', () => {
const size = 4;
const snapshot = snapshotWithWall({
size,
images: [depthImage(size, size, () => 1)],
});
assert.ok(Number.isNaN(snapshot.surfaceViewDistance(1, 1)));
assert.equal(snapshot.hides(ahead(500)), false);
});
/**
* A probe that answers when told to. `hidden` decides each test's answer at
* the time it is resolved.
*/
function manualProbe() {
const inFlight = [];
return {
accepting: true,
started: 0,
inFlight,
add(contact) {
if (!this.accepting) return false;
this.started++;
contact.pending = true;
inFlight.push(contact);
return true;
},
/** Deliver every answer in flight. */
answer(hidden, now) {
for (const contact of inFlight.splice(0)) {
contact.pending = false;
contact.answered = true;
if (hidden) contact.lastHiddenAt = now;
}
},
};
}
const anywhere = { x: 0, y: 0, z: -500 };
test('a contact is drawn until an answer says it is hidden, then hidden at once', () => {
const probe = manualProbe();
const occlusion = new SurfaceOcclusion(probe);
occlusion.beginFrame(1000);
assert.equal(occlusion.isHidden('traffic', 'a', anywhere), false);
assert.equal(probe.started, 1, 'a new contact is tested straight away');
occlusion.beginFrame(1016);
assert.equal(occlusion.isHidden('traffic', 'a', anywhere), false);
assert.equal(probe.started, 1, 'one test in flight per contact');
probe.answer(true, occlusion.now);
occlusion.beginFrame(1032);
assert.equal(occlusion.isHidden('traffic', 'a', anywhere), true);
assert.equal(occlusion.testedCount, 1);
assert.equal(occlusion.hiddenCount, 1);
// The same source id on another layer is another contact.
assert.equal(occlusion.isHidden('transit', 'a', anywhere), false);
});
test('with a working probe a new contact is held back until its first answer, and no longer than the limit', () => {
const probe = manualProbe();
probe.mode = 'async';
const occlusion = new SurfaceOcclusion(probe);
occlusion.beginFrame(0);
// New to the view: tested at once, and not drawn while the answer is out.
assert.equal(occlusion.isHidden('traffic', 'street', anywhere), true);
assert.equal(occlusion.isHidden('traffic', 'roofed', anywhere), true);
assert.equal(occlusion.isHidden('traffic', 'unanswered', anywhere), true);
assert.equal(probe.started, 3);
const [street, roofed] = probe.inFlight.splice(0, 2);
street.pending = false;
street.answered = true;
roofed.pending = false;
roofed.answered = true;
roofed.lastHiddenAt = occlusion.now;
occlusion.beginFrame(16);
assert.equal(
occlusion.isHidden('traffic', 'street', anywhere),
false,
'drawn from its first answer',
);
assert.equal(
occlusion.isHidden('traffic', 'roofed', anywhere),
true,
'never drawn at all',
);
// The third answer never comes. It is drawn once the limit has passed.
const firstSeen = occlusion.now - 16;
const drawn = [];
for (let wall = 32; wall < 1000; wall += 16) {
occlusion.beginFrame(wall);
drawn.push([
occlusion.now - firstSeen,
!occlusion.isHidden('traffic', 'unanswered', anywhere),
]);
}
for (const [age, shown] of drawn)
assert.equal(shown, age >= SURFACE_FIRST_ANSWER_MS, `at ${age} ms`);
// No working probe: a new contact is drawn at once, as before.
for (const mode of ['off', 'sync', undefined]) {
const idle = manualProbe();
idle.mode = mode;
const plain = new SurfaceOcclusion(idle);
plain.beginFrame(0);
assert.equal(plain.isHidden('traffic', 'a', anywhere), false, String(mode));
}
});
test('a contact is retested at most every retest interval and at least every half of it', () => {
const probe = manualProbe();
const occlusion = new SurfaceOcclusion(probe);
const starts = [];
let before = 0;
for (let now = 0; now <= 2000; now += 4) {
probe.answer(false, now);
occlusion.beginFrame(now);
occlusion.isHidden('traffic', 'a', anywhere);
if (probe.started !== before) {
starts.push(now);
before = probe.started;
}
}
const gaps = starts.slice(1).map((at, i) => at - starts[i]);
assert.ok(gaps.length >= 9);
assert.ok(
gaps.every((gap) => gap <= SURFACE_RETEST_MS),
`${gaps}`,
);
assert.ok(
gaps.every((gap) => gap >= SURFACE_RETEST_MS / 2),
`${gaps}`,
);
assert.ok(new Set(gaps).size > 3, 'not all on the same beat');
});
test('contacts that appear together drift apart instead of all testing on the same frames', () => {
const probe = manualProbe();
const occlusion = new SurfaceOcclusion(probe);
const perFrame = [];
for (let frame = 0; frame < 240; frame++) {
const now = frame * 16;
probe.answer(false, now);
occlusion.beginFrame(now);
const before = probe.started;
for (let id = 0; id < 600; id++)
occlusion.isHidden('traffic', id, anywhere);
perFrame.push(probe.started - before);
}
assert.equal(perFrame[0], 600, 'every new contact is tested at once');
const settled = perFrame.slice(120);
assert.ok(Math.max(...settled) < 200, `peak ${Math.max(...settled)}`);
assert.ok(Math.min(...settled) > 0);
});
test('with more contacts than the probe takes per frame, the retests slow down and none is starved', () => {
// A probe that takes 256 tests a frame, 2,400 contacts in view, 30 fps.
const inFlight = [];
let taken = 0;
const probe = {
maxPerFrame: 256,
add(contact) {
if (taken >= 256) return false;
taken++;
contact.pending = true;
inFlight.push(contact);
return true;
},
};
const occlusion = new SurfaceOcclusion(probe);
const tests = new Array(2400).fill(0);
const lastStart = new Array(2400).fill(0);
let longestGap = 0;
for (let frame = 0; frame < 300; frame++) {
const now = frame * 33;
for (const contact of inFlight.splice(0)) contact.pending = false;
taken = 0;
occlusion.beginFrame(now);
for (let id = 0; id < 2400; id++) {
const before = taken;
occlusion.isHidden('traffic', id, anywhere);
if (taken !== before) {
tests[id]++;
if (frame > 60) longestGap = Math.max(longestGap, now - lastStart[id]);
lastStart[id] = now;
}
}
}
assert.ok(
Math.min(...tests) >= 8,
`fewest tests for one contact: ${Math.min(...tests)}`,
);
assert.ok(occlusion.retestMs > SURFACE_RETEST_MS);
assert.ok(longestGap <= occlusion.retestMs + 33, `longest gap ${longestGap}`);
assert.ok(occlusion.reappearMs >= 3 * occlusion.retestMs);
// A view the budget covers easily keeps the normal pace.
const few = new SurfaceOcclusion(probe);
for (let frame = 0; frame < 10; frame++) {
taken = 0;
few.beginFrame(frame * 16);
for (let id = 0; id < 300; id++) few.isHidden('traffic', id, anywhere);
}
assert.equal(few.retestMs, SURFACE_RETEST_MS);
assert.equal(few.reappearMs, SURFACE_REAPPEAR_MS);
});
test('a hidden contact comes back only after the reappear time without a hidden answer', () => {
const probe = manualProbe();
const occlusion = new SurfaceOcclusion(probe);
occlusion.beginFrame(0);
occlusion.isHidden('traffic', 'a', anywhere);
const hiddenAt = occlusion.now;
probe.answer(true, hiddenAt);
// Visible answers from now on; the contact still waits out the time.
let reappeared = null;
for (let wall = 16; wall < 2000 && reappeared === null; wall += 16) {
probe.answer(false, occlusion.now);
occlusion.beginFrame(wall);
if (!occlusion.isHidden('traffic', 'a', anywhere))
reappeared = occlusion.now;
}
assert.ok(reappeared - hiddenAt >= SURFACE_REAPPEAR_MS);
assert.ok(reappeared - hiddenAt < SURFACE_REAPPEAR_MS + 17);
});
test('a contact on an edge, answering either way in turn, stays hidden', () => {
const probe = manualProbe();
const occlusion = new SurfaceOcclusion(probe);
const drawn = [];
let answers = 0;
for (let wall = 0; wall < 4000; wall += 16) {
if (probe.inFlight.length > 0)
probe.answer(answers++ % 2 === 0, occlusion.now);
occlusion.beginFrame(wall);
drawn.push(!occlusion.isHidden('traffic', 'a', anywhere));
}
// Drawn only until the first answer arrives.
assert.equal(drawn.lastIndexOf(true), 0);
});
test('when the probe stops answering, hidden contacts are drawn again and stay drawn', () => {
const probe = manualProbe();
const occlusion = new SurfaceOcclusion(probe);
occlusion.beginFrame(0);
occlusion.isHidden('traffic', 'a', anywhere);
const hiddenAt = occlusion.now;
probe.answer(true, hiddenAt);
// No depth any more: the probe takes no tests and answers nothing.
probe.accepting = false;
const drawn = [];
for (let wall = 16; wall < 3000; wall += 16) {
occlusion.beginFrame(wall);
drawn.push([
occlusion.now - hiddenAt,
!occlusion.isHidden('traffic', 'a', anywhere),
]);
}
for (const [age, shown] of drawn)
assert.equal(shown, age >= SURFACE_REAPPEAR_MS, `at ${age} ms`);
// A probe that never accepted anything hides nothing.
const dead = new SurfaceOcclusion({ add: () => false });
dead.beginFrame(0);
assert.equal(dead.isHidden('traffic', 'a', anywhere), false);
});
test('a change of pace does not bring back a hidden that has run out', () => {
// 2,400 contacts with a 256-a-frame probe: the hide time is longer at 33 ms
// frames than at 16 ms ones.
const inFlight = [];
let taken = 0;
const probe = {
maxPerFrame: 256,
add(contact) {
if (taken >= 256) return false;
taken++;
contact.pending = true;
inFlight.push(contact);
return true;
},
};
const occlusion = new SurfaceOcclusion(probe);
let wall = 0;
const paint = (step) => {
wall += step;
for (const contact of inFlight.splice(0)) contact.pending = false;
taken = 0;
occlusion.beginFrame(wall);
let watched = false;
for (let id = 0; id < 2400; id++) {
const hidden = occlusion.isHidden('traffic', id, anywhere);
if (id === 0) watched = hidden;
}
return watched;
};
for (let i = 0; i < 30; i++) paint(16);
// One hidden answer for contact 0, then visible answers only.
occlusion.contacts.get('traffic').get(0).lastHiddenAt = occlusion.now;
const states = [];
for (let i = 0; i < 80; i++) states.push(paint(16));
assert.equal(states[0], true);
assert.equal(states.at(-1), false, 'ran out at the fast pace');
// The frames slow down, which lengthens the hide time for new answers.
const slow = [];
for (let i = 0; i < 40; i++) slow.push(paint(33));
assert.ok(occlusion.reappearMs > SURFACE_REAPPEAR_MS);
assert.ok(
slow.every((hidden) => hidden === false),
'and stays out',
);
});
test('a pause in painting does not run the hidden time out', () => {
const probe = manualProbe();
const occlusion = new SurfaceOcclusion(probe);
occlusion.beginFrame(0);
occlusion.isHidden('traffic', 'a', anywhere);
probe.answer(true, occlusion.now);
occlusion.beginFrame(16);
assert.equal(occlusion.isHidden('traffic', 'a', anywhere), true);
// Nothing is painted for a minute (a hidden tab, an idle scene). On the
// first frame back the contact is still hidden: no answer could have come.
const before = occlusion.now;
occlusion.beginFrame(60_016);
assert.equal(occlusion.now - before, SURFACE_MAX_FRAME_STEP_MS);
assert.equal(occlusion.isHidden('traffic', 'a', anywhere), true);
// A clock that jumps backwards moves nothing.
occlusion.beginFrame(100);
assert.equal(occlusion.now - before, SURFACE_MAX_FRAME_STEP_MS);
});
test('prune forgets contacts that are no longer drawn; clear forgets everything', () => {
const probe = manualProbe();
const occlusion = new SurfaceOcclusion(probe);
let wall = 0;
/** Paint frames for `ms` of painted time, drawing the given contacts. */
const paint = (ms, ids) => {
for (const end = occlusion.now + ms; occlusion.now < end;) {
wall += 50;
occlusion.beginFrame(wall);
for (const id of ids) occlusion.isHidden('traffic', id, anywhere);
}
};
paint(100, ['gone', 'here']);
paint(SURFACE_FORGET_MS + 50, ['here']);
occlusion.prune();
assert.deepEqual([...occlusion.contacts.get('traffic').keys()], ['here']);
paint(SURFACE_FORGET_MS + 50, []);
occlusion.prune();
assert.equal(occlusion.contacts.size, 0);
occlusion.isHidden('traffic', 'again', anywhere);
occlusion.clear();
assert.equal(occlusion.contacts.size, 0);
assert.equal(occlusion.testedCount, 0);
});
test('a contact back in view after a while waits for a fresh answer, like a new one', () => {
const probe = manualProbe();
probe.mode = 'async';
const occlusion = new SurfaceOcclusion(probe);
let wall = 0;
const step = () => occlusion.beginFrame((wall += 16));
step();
occlusion.isHidden('traffic', 'a', anywhere);
probe.answer(false, occlusion.now);
step();
assert.equal(occlusion.isHidden('traffic', 'a', anywhere), false);
// Out of view for a moment shorter than a retest: drawn straight away.
for (let i = 0; i < 5; i++) step();
assert.equal(occlusion.isHidden('traffic', 'a', anywhere), false);
// Out of view for longer (the camera swung away and back): the old
// "visible" may now be behind a building. Held back, and tested at once.
const started = probe.started;
for (let i = 0; i < 30; i++) step();
assert.equal(occlusion.isHidden('traffic', 'a', anywhere), true);
assert.equal(probe.started, started + 1);
probe.answer(true, occlusion.now);
step();
assert.equal(occlusion.isHidden('traffic', 'a', anywhere), true);
// It leaves with a test in flight, and comes back. That test's answer was
// about the previous view: when it lands, it must not end the hold-back.
const other = new SurfaceOcclusion(probe);
probe.answer(false, 0);
other.beginFrame((wall += 16));
other.isHidden('traffic', 'b', anywhere);
assert.equal(probe.inFlight.length, 1, 'tested, unanswered');
for (let i = 0; i < 30; i++) other.beginFrame((wall += 16));
const before = probe.started;
assert.equal(other.isHidden('traffic', 'b', anywhere), true);
assert.equal(probe.started, before + 1, 'tested afresh at once');
const [stale] = probe.inFlight.splice(0, 1);
stale.pending = false;
stale.answered = true;
other.beginFrame((wall += 16));
assert.equal(
other.isHidden('traffic', 'b', anywhere),
true,
'the old answer did not end the hold-back',
);
probe.answer(false, other.now);
other.beginFrame((wall += 16));
assert.equal(other.isHidden('traffic', 'b', anywhere), false);
});
test('at a stretched retest pace, new contacts are held back longer for their first answer', () => {
const probe = manualProbe();
probe.mode = 'async';
probe.maxPerFrame = 100;
const occlusion = new SurfaceOcclusion(probe);
occlusion.beginFrame(0);
for (let id = 0; id < 2000; id++) occlusion.isHidden('traffic', id, anywhere);
occlusion.beginFrame(33);
// 2000 contacts at 100 a frame and 33 ms frames: a retest every 1.3 s.
assert.ok(occlusion.retestMs > 1000, `${occlusion.retestMs}`);
assert.equal(occlusion.firstAnswerMs, occlusion.retestMs * 2);
assert.ok(occlusion.firstAnswerMs > SURFACE_FIRST_ANSWER_MS);
// A contact the probe has not reached yet is still held back past the
// usual limit, and drawn once the stretched one has run out.
probe.accepting = false;
let wall = 33;
const ages = [];
const firstSeen = occlusion.now;
occlusion.isHidden('traffic', 'late', anywhere);
while (occlusion.now - firstSeen < occlusion.firstAnswerMs + 100) {
occlusion.beginFrame((wall += 33));
for (let id = 0; id < 2000; id++)
occlusion.isHidden('traffic', id, anywhere);
ages.push([
occlusion.now - firstSeen,
occlusion.isHidden('traffic', 'late', anywhere),
]);
}
const limit = occlusion.firstAnswerMs;
assert.ok(
ages.some(([age, hidden]) => age > SURFACE_FIRST_ANSWER_MS + 50 && hidden),
'held past 400 ms',
);
for (const [age, hidden] of ages)
if (age >= limit) assert.equal(hidden, false, `at ${age} ms`);
});
+11
View File
@@ -0,0 +1,11 @@
/** One-line text capped at `maxLength` without splitting a surrogate pair. Still untrusted. */
export function normalizeDisplayText(value, maxLength = 180) {
if (value == null || typeof value === 'object') return '';
return String(value)
.replace(/[\u0000-\u001f\u007f-\u009f]/g, ' ')
.replace(/\s+/g, ' ')
.trim()
.slice(0, maxLength)
.replace(/[\uD800-\uDBFF]$/, '')
.trim();
}
+2
View File
@@ -46,5 +46,7 @@ export const _iconForTest = flightsLayer.testing._iconForTest;
export const _setIconForTest = flightsLayer.testing._setIconForTest;
export const _floorGroundedIconsForTest =
flightsLayer.testing._floorGroundedIconsForTest;
export const _resetEnrichmentForTest =
flightsLayer.testing._resetEnrichmentForTest;
export const mapAnalystRecord = flightsLayer.mapAnalystRecord;
export default flightsLayer;
+295 -11
View File
@@ -1,7 +1,7 @@
// src/data/flights.test.mjs
// Focused tests for the pure analyst-record mapper (analyst query engine seam).
// Pure function — no viewer/DOM needed; imported directly.
import { test } from 'node:test';
import { after, afterEach, before, test } from 'node:test';
import assert from 'node:assert/strict';
import { followedOf } from './followed.js';
import { bindFakeCesiumCamera } from '../testSupport/fakeCameraPort.mjs';
@@ -18,9 +18,14 @@ import flightsLayer, {
_clearDisplayFloorStateForTest,
_iconForTest,
_floorGroundedIconsForTest,
_resetEnrichmentForTest,
mapAnalystRecord,
} from './flights.js';
import { setMilitaryLayerActive } from './militaryRegistry.js';
import {
isMilitaryLayerActive,
registerMilitaryIcaos,
setMilitaryLayerActive,
} from './militaryRegistry.js';
import {
GROUND_FLOOR_LIFT_M,
reportMeshFloorCell,
@@ -36,6 +41,31 @@ import {
} from './trackedReadout.js';
import { readEntityRecord, withEntityRecord } from './entityRecords.js';
// Unit tests never reach the network. A test that tracks a plane queues its
// enrichment (type, route, photo), so every test ends on an empty queue, and a
// fetch of any absolute URL fails the test it happened in. A test that needs
// answers installs its own fetch and restores this one.
const nodeFetch = globalThis.fetch;
const networkRequests = [];
before(() => {
globalThis.fetch = async (url) => {
const href = String(url?.url ?? url);
if (/^https?:\/\//i.test(href)) networkRequests.push(href);
throw new TypeError(`Failed to parse URL from ${href}`);
};
});
afterEach(() => {
_resetEnrichmentForTest();
assert.deepEqual(
networkRequests.splice(0),
[],
'no test reaches the network',
);
});
after(() => {
globalThis.fetch = nodeFetch;
});
test('share-Follow absence requires an accepted OpenSky snapshot', async () => {
_setFlightTrackingRefreshOutcomeForTest({ status: 'source-unavailable' });
assert.equal(
@@ -191,7 +221,10 @@ test('flights first update forwards caller cancellation into the feed request',
test('nonempty OpenSky payload with zero usable rows cannot prove share target absence', async () => {
_setTrackedFlightRefreshStateForTest({
icao24: 'abc123',
entity: withEntityRecord({}, { labelModel: { title: 'WARM', details: [] } }),
entity: withEntityRecord(
{},
{ labelModel: { title: 'WARM', details: [] } },
),
icon: { show: false },
iconLayer: { show: true, remove() {} },
viewer: { camera: { positionCartographic: null }, scene: {} },
@@ -315,7 +348,10 @@ test('a newly seen aircraft appears at its delayed position, not ahead of it', a
test('flights poll refreshes tracked callsign/FL/kts and marks a missed poll STALE', async () => {
const icao24 = 'a1b2c3';
const entity = withEntityRecord({}, { labelModel: { title: 'OLD', details: [] } });
const entity = withEntityRecord(
{},
{ labelModel: { title: 'OLD', details: [] } },
);
const billboard = {
position: Cesium.Cartesian3.fromDegrees(-97.7, 30.2, 9_000),
color: Cesium.Color.WHITE,
@@ -387,12 +423,21 @@ test('flights poll refreshes tracked callsign/FL/kts and marks a missed poll STA
try {
await flightsLayer.update(viewer);
assert.equal(readEntityRecord(entity)?.labelModel.title, 'DAL123');
assert.match(readEntityRecord(entity)?.labelModel.details.join(' · '), /FL350/);
assert.match(readEntityRecord(entity)?.labelModel.details.join(' · '), /486 kts/);
assert.match(
readEntityRecord(entity)?.labelModel.details.join(' · '),
/FL350/,
);
assert.match(
readEntityRecord(entity)?.labelModel.details.join(' · '),
/486 kts/,
);
await flightsLayer.update(viewer);
assert.match(
[readEntityRecord(entity)?.labelModel.title, ...readEntityRecord(entity)?.labelModel.details].join(' · '),
[
readEntityRecord(entity)?.labelModel.title,
...readEntityRecord(entity)?.labelModel.details,
].join(' · '),
/STALE/,
);
} finally {
@@ -400,6 +445,232 @@ test('flights poll refreshes tracked callsign/FL/kts and marks a missed poll STA
}
});
test('a tracked plane whose photo lookup failed asks again on the first poll after the cool-down', async (t) => {
const icao24 = 'b2c3d4';
const realNow = Date.now.bind(Date);
let offsetMs = 0;
t.mock.method(Date, 'now', () => realNow() + offsetMs);
const entity = { gevLabelModel: { title: 'OLD', details: [] } };
const viewer = { camera: { positionCartographic: null }, scene: {} };
_setTrackedFlightRefreshStateForTest({
icao24,
entity,
billboard: {
position: Cesium.Cartesian3.fromDegrees(-97.7, 30.2, 9_000),
color: Cesium.Color.WHITE,
show: false,
},
billboardCollection: { show: false, remove() {} },
viewer,
meta: {
callsign: 'UAL9',
altitude: 9_000,
renderAltitudeM: 9_050,
velocity: 180,
true_track: 80,
klass: 'airliner',
onGround: false,
wasAirborne: true,
turnRateDps: 0,
rawLat: 30.2,
rawLon: -97.7,
},
});
let callsign = 'UAL9 ';
const photoRequests = [];
const routeRequests = [];
const guardFetch = globalThis.fetch;
globalThis.fetch = async (url) => {
url = String(url);
if (url.startsWith('https://api.planespotters.net/')) {
photoRequests.push(url);
return { ok: false, status: 503, json: async () => ({}) };
}
if (url.startsWith('/api/adsbdb/route/UAL')) routeRequests.push(url);
if (!url.startsWith('/api/flights'))
return { ok: true, status: 200, json: async () => ({ found: false }) };
const nowSec = Math.floor(Date.now() / 1000);
return {
ok: true,
status: 200,
headers: { get: () => null },
json: async () => ({
time: nowSec,
states: [
[
icao24,
callsign,
'United States',
nowSec,
nowSec,
-97.6,
30.3,
10_668,
false,
250,
95,
5,
null,
10_700,
null,
null,
null,
5,
],
],
}),
};
};
// Lookups drip out one per 200 ms. Wait for what must arrive (with a
// generous deadline, so a loaded machine cannot fail it), then a little
// longer so anything that must NOT arrive would have.
const until = async (ready) => {
const deadline = realNow() + 5_000;
while (!ready() && realNow() < deadline)
await new Promise((done) => setTimeout(done, 20));
await new Promise((done) => setTimeout(done, 450));
};
try {
await flightsLayer.update(viewer);
await until(() => photoRequests.length >= 1 && routeRequests.length >= 1);
assert.equal(photoRequests.length, 1, 'the first poll asks for the photo');
assert.deepEqual(routeRequests, ['/api/adsbdb/route/UAL9']);
// Well inside the 60 s cool-down, and well past it below, so real time
// spent between polls cannot move either side across the line.
offsetMs += 30_000;
callsign = 'UAL10 ';
await flightsLayer.update(viewer);
await until(() => routeRequests.length >= 2);
assert.equal(photoRequests.length, 1, 'not within the cool-down');
assert.deepEqual(
routeRequests,
['/api/adsbdb/route/UAL9', '/api/adsbdb/route/UAL10'],
'the route follows the callsign the poll just recorded',
);
offsetMs += 60_000;
await flightsLayer.update(viewer);
await until(() => photoRequests.length >= 2);
assert.deepEqual(
photoRequests,
[
'https://api.planespotters.net/pub/photos/hex/b2c3d4',
'https://api.planespotters.net/pub/photos/hex/b2c3d4',
],
'asked again on the first poll after the cool-down',
);
} finally {
globalThis.fetch = guardFetch;
// The moved clock dated this layer's dispatch and cool-downs into the
// future; reset before the real clock comes back.
_resetEnrichmentForTest();
t.mock.restoreAll();
}
});
test('a known-military aircraft tracked in the flights layer is never looked up and shows no photo', async () => {
const icao24 = 'ae5e01';
// The registry has no way to forget one hex (only a whole-registry reset,
// which would also drop its source), so the test uses a hex no other test
// reads and restores the layer-active flag it changes.
const militaryWasActive = isMilitaryLayerActive();
registerMilitaryIcaos([icao24]);
setMilitaryLayerActive(false);
const viewer = { camera: { positionCartographic: null }, scene: {} };
_setTrackedFlightRefreshStateForTest({
icao24,
entity: { gevLabelModel: { title: 'OLD', details: [] } },
billboard: {
position: Cesium.Cartesian3.fromDegrees(-97.7, 30.2, 9_000),
color: Cesium.Color.WHITE,
show: false,
},
billboardCollection: { show: false, remove() {} },
viewer,
meta: {
callsign: 'RCH123',
altitude: 9_000,
renderAltitudeM: 9_050,
velocity: 180,
true_track: 80,
klass: 'airliner',
onGround: false,
wasAirborne: true,
turnRateDps: 0,
rawLat: 30.2,
rawLon: -97.7,
// Even a photo already on the record is never shown.
photo: {
src: 'https://t.plnspttrs.net/1/ae5e01_280.jpg',
width: 280,
height: 186,
photographer: 'Jane Doe',
link: 'https://www.planespotters.net/photo/1/x',
},
},
});
const photoRequests = [];
const routeRequests = [];
const guardFetch = globalThis.fetch;
globalThis.fetch = async (url) => {
url = String(url);
if (url.startsWith('https://api.planespotters.net/')) {
photoRequests.push(url);
return { ok: false, status: 503, json: async () => ({}) };
}
if (url.startsWith('/api/adsbdb/route/')) routeRequests.push(url);
if (!url.startsWith('/api/flights'))
return { ok: true, status: 200, json: async () => ({ found: false }) };
const nowSec = Math.floor(Date.now() / 1000);
return {
ok: true,
status: 200,
headers: { get: () => null },
json: async () => ({
time: nowSec,
states: [
[
icao24,
'RCH123 ',
'United States',
nowSec,
nowSec,
-97.6,
30.3,
10_668,
false,
250,
95,
5,
null,
10_700,
null,
null,
null,
5,
],
],
}),
};
};
try {
await flightsLayer.update(viewer);
// A photo lookup would go out ahead of the route; wait for the route.
const deadline = Date.now() + 5_000;
while (!routeRequests.length && Date.now() < deadline)
await new Promise((done) => setTimeout(done, 20));
assert.deepEqual(routeRequests, ['/api/adsbdb/route/RCH123']);
assert.deepEqual(photoRequests, [], 'no photo lookup for a military hex');
assert.equal(flightsLayer.getTrackedInfo()?.icao24, icao24);
assert.equal(flightsLayer.getTrackedInfo()?.photo, null);
assert.equal(flightsLayer.getTrackedSubject()?.photo, null);
} finally {
globalThis.fetch = guardFetch;
setMilitaryLayerActive(militaryWasActive);
}
});
test('real civil track path creates no native label and publishes every cached host line', async () => {
const icao24 = 'civ001';
const position = Cesium.Cartesian3.fromDegrees(-97.6699, 30.1945, 10_668);
@@ -590,7 +861,10 @@ test('real civil track path creates no native label and publishes every cached h
assert.equal(entry.protected, true);
assert.equal(entry.paintLane, 'tracked');
assert.equal(entry.title, readEntityRecord(entity)?.labelModel.title);
assert.deepEqual(entry.details, readEntityRecord(entity)?.labelModel.details);
assert.deepEqual(
entry.details,
readEntityRecord(entity)?.labelModel.details,
);
const display = followedOf(viewer)?.position(Date.now());
assert.ok(display, 'the follow target must seed the frame cache');
@@ -951,7 +1225,10 @@ test('civil label chain: the awareness selection EVENT uses the canonical chain'
});
test('civil tracked readout: a callsign-less enriched contact reads as its registration', async () => {
const entity = withEntityRecord({}, { labelModel: { title: 'OLD', details: [] } });
const entity = withEntityRecord(
{},
{ labelModel: { title: 'OLD', details: [] } },
);
seedLabelContact({ callsign: ' ', registration: ' N123AB ', tracked: true });
_setTrackedFlightRefreshStateForTest({
icao24: LABEL_ICAO,
@@ -993,7 +1270,10 @@ test('civil tracked readout: a callsign-less enriched contact reads as its regis
});
assert.match(readEntityRecord(entity)?.labelModel.title, /^N123AB\b/);
assert.doesNotMatch(
[readEntityRecord(entity)?.labelModel.title, ...readEntityRecord(entity)?.labelModel.details].join(' · '),
[
readEntityRecord(entity)?.labelModel.title,
...readEntityRecord(entity)?.labelModel.details,
].join(' · '),
/ae1fa4/,
);
} finally {
@@ -1224,7 +1504,11 @@ test('far grounded contacts take turns on the floor; near ones refloor every tic
};
try {
await flightsLayer.update(viewer);
const start = Cesium.JulianDate.now();
// A grounded report holds once its time is past, so the ticks run in
// the 40 s before it, while the contact still taxis toward its fix.
const start = Cesium.JulianDate.fromDate(
new Date((nowSec - 2 - 40) * 1000),
);
const at = (s) =>
Cesium.JulianDate.addSeconds(start, s, new Cesium.JulianDate());
const far = Cesium.Cartesian3.fromDegrees(fixLon, fixLat, 3_000_000);
+2
View File
@@ -693,6 +693,7 @@ export const LAYER_STATE_REGISTRY = Object.freeze([
token: 'i',
disposition: 'enabled-only',
}),
Object.freeze({ id: 'news', token: '00', disposition: 'enabled-only' }),
Object.freeze({
id: 'radio',
token: 'r',
@@ -722,6 +723,7 @@ export const LAYER_STATE_REGISTRY = Object.freeze([
optionOwner: 'satellites',
}),
Object.freeze({ id: 'sea-marks', token: '6', disposition: 'enabled-only' }),
Object.freeze({ id: 'shipwrecks', token: '01', disposition: 'enabled-only' }),
Object.freeze({ id: 'ski-pistes', token: '7', disposition: 'enabled-only' }),
Object.freeze({
id: 'street-level',
+18 -12
View File
@@ -203,8 +203,8 @@ function encode(state) {
test('production registry is exact, canonical, and rejects incomplete contracts', async () => {
assert.equal(validateLayerStateRegistry(), true);
assert.equal(REGISTERED_LAYER_IDS.length, 36);
assert.equal(new Set(REGISTERED_LAYER_IDS).size, 36);
assert.equal(REGISTERED_LAYER_IDS.length, 38);
assert.equal(new Set(REGISTERED_LAYER_IDS).size, 38);
assert.ok(REGISTERED_LAYER_IDS.includes('transit'));
assert.deepEqual(REGISTERED_LAYER_IDS, [...REGISTERED_LAYER_IDS].sort());
assert.deepEqual(LEGACY_LAYER_STATE_TOKENS, {
@@ -243,17 +243,23 @@ test('production registry is exact, canonical, and rejects incomplete contracts'
for (const [id, token] of Object.entries(LEGACY_LAYER_STATE_TOKENS)) {
assert.equal(LAYER_STATE_TOKEN_RESERVATIONS[id], token);
}
assert.equal(nextLayerStateToken(), '00');
// News holds 00 and Shipwrecks 01, the first pairs: the next token is 02.
assert.equal(nextLayerStateToken(), '02');
// The allocation rules below read the ledger before either took a pair.
const beforeNews = { ...LAYER_STATE_TOKEN_RESERVATIONS };
delete beforeNews.news;
delete beforeNews.shipwrecks;
assert.equal(nextLayerStateToken(beforeNews), '00');
assert.equal(
nextLayerStateToken({
...LAYER_STATE_TOKEN_RESERVATIONS,
...beforeNews,
alpha: '9',
bravo: '00',
}),
'01',
);
const digitsExhausted = {
...LAYER_STATE_TOKEN_RESERVATIONS,
...beforeNews,
...Object.fromEntries([...'9'].map((digit) => [`prior-${digit}`, digit])),
};
assert.equal(nextLayerStateToken(digitsExhausted), '00');
@@ -304,8 +310,8 @@ test('production registry is exact, canonical, and rejects incomplete contracts'
true,
);
assert.equal(
validateLayerStateAllocations(LAYER_STATE_TOKEN_RESERVATIONS, {
...LAYER_STATE_TOKEN_RESERVATIONS,
validateLayerStateAllocations(beforeNews, {
...beforeNews,
future: '00',
next: '01',
}),
@@ -313,8 +319,8 @@ test('production registry is exact, canonical, and rejects incomplete contracts'
);
assert.throws(
() =>
validateLayerStateAllocations(LAYER_STATE_TOKEN_RESERVATIONS, {
...LAYER_STATE_TOKEN_RESERVATIONS,
validateLayerStateAllocations(beforeNews, {
...beforeNews,
future: '01',
}),
/next free token 00/,
@@ -341,8 +347,8 @@ test('production registry is exact, canonical, and rejects incomplete contracts'
assert.throws(
() =>
validateLayerStateAllocations(
{ ...LAYER_STATE_TOKEN_RESERVATIONS, merged: '9' },
{ ...LAYER_STATE_TOKEN_RESERVATIONS, merged: '9', competing: '9' },
{ ...beforeNews, merged: '9' },
{ ...beforeNews, merged: '9', competing: '9' },
),
/next free token 00/,
);
@@ -500,7 +506,7 @@ test('unknown enabled-layer tokens reject the payload instead of becoming an emp
});
test('malformed enabled-layer lists reject the entire payload', () => {
for (const value of ['.c', 'c.', 'c..e', 'c.c', '00', 'c.00']) {
for (const value of ['.c', 'c.', 'c..e', 'c.c', 'zz', 'c.zz']) {
assert.equal(
decodeLayerStateParams(new URLSearchParams(`v=2&l=${value}`)),
null,
+104 -81
View File
@@ -97,8 +97,10 @@ function withPublishedBase(
}
}
const preWildlifeRows = reservationRows.filter(
([id]) => id !== 'wildlife-sightings',
// The ledger before Wildlife Sightings took the last digit and News and
// Shipwrecks the first pairs, for the allocation rules written against it.
const beforeLastDigitRows = reservationRows.filter(
([id]) => !['wildlife-sightings', 'news', 'shipwrecks'].includes(id),
);
function writeCodecFixture(cwd, rows, entries) {
@@ -115,6 +117,16 @@ function writeCodecFixture(cwd, rows, entries) {
/ Object\.freeze\(\{\s*id: 'wildlife-sightings',[\s\S]*?\}\),\n/,
'',
);
if (!rows.some(([id]) => id === 'news'))
source = source.replace(
/ Object\.freeze\(\{\s*id: 'news',[\s\S]*?\}\),\n/,
'',
);
if (!rows.some(([id]) => id === 'shipwrecks'))
source = source.replace(
/ Object\.freeze\(\{\s*id: 'shipwrecks',[\s\S]*?\}\),\n/,
'',
);
const registryEnd = ']);\n\nexport const REGISTERED_LAYER_IDS';
assert.equal(source.split(registryEnd).length, 2);
const additions = entries
@@ -138,7 +150,7 @@ test('reservation ledger is complete, pinned, and rejects duplicate or malformed
{ ...parseLayerStateTokenReservations(reservationRows) },
{ ...LAYER_STATE_TOKEN_RESERVATIONS },
);
assert.equal(Object.keys(LAYER_STATE_TOKEN_RESERVATIONS).length, 36);
assert.equal(Object.keys(LAYER_STATE_TOKEN_RESERVATIONS).length, 38);
assert.deepEqual(
{ ...LAYER_STATE_TOKEN_RESERVATIONS },
{
@@ -151,6 +163,8 @@ test('reservation ledger is complete, pinned, and rejects duplicate or malformed
'ski-pistes': '7',
'drone-airspace': '8',
'wildlife-sightings': '9',
news: '00',
shipwrecks: '01',
},
);
assert.throws(
@@ -176,9 +190,9 @@ test('reservation ledger is complete, pinned, and rejects duplicate or malformed
/Duplicate layer-state token reservation/,
);
assert.equal(
parseLayerStateTokenReservations([...reservationRows, ['future', '00']])
parseLayerStateTokenReservations([...reservationRows, ['future', '02']])
.future,
'00',
'02',
);
assert.throws(
() =>
@@ -196,7 +210,7 @@ test('reservation ledger is complete, pinned, and rejects duplicate or malformed
test('published retired digits and competing PRs advance the merge-time allocation', () => {
withPublishedBase(
{ rows: [...preWildlifeRows, ['retired-layer', '9']] },
{ rows: [...beforeLastDigitRows, ['retired-layer', '9']] },
(cwd) => {
const published = readPublishedLayerStateReservations('HEAD', cwd);
assert.equal(nextLayerStateToken(published), '00');
@@ -228,80 +242,86 @@ test('published retired digits and competing PRs advance the merge-time allocati
});
test('PR B manually replaces provisional 9 with 00 after PR A publishes 9', () => {
withPublishedBase({ rows: [...preWildlifeRows, ['pr-a', '9']] }, (cwd) => {
mkdirSync(path.join(cwd, 'scripts'));
const fixtureChecker = path.join(
cwd,
'scripts/check-layer-state-tokens.mjs',
);
writeFileSync(fixtureChecker, readFileSync(CHECKER_PATH, 'utf8'));
const fixtureNext = path.join(cwd, 'scripts/next-layer-state-token.mjs');
writeFileSync(fixtureNext, readFileSync(NEXT_PATH, 'utf8'));
const runCheck = () =>
spawnSync(
process.execPath,
[realpathSync(fixtureChecker), '--base-ref', 'HEAD'],
{
cwd,
encoding: 'utf8',
},
withPublishedBase(
{ rows: [...beforeLastDigitRows, ['pr-a', '9']] },
(cwd) => {
mkdirSync(path.join(cwd, 'scripts'));
const fixtureChecker = path.join(
cwd,
'scripts/check-layer-state-tokens.mjs',
);
writeFileSync(fixtureChecker, readFileSync(CHECKER_PATH, 'utf8'));
const fixtureNext = path.join(cwd, 'scripts/next-layer-state-token.mjs');
writeFileSync(fixtureNext, readFileSync(NEXT_PATH, 'utf8'));
const runCheck = () =>
spawnSync(
process.execPath,
[realpathSync(fixtureChecker), '--base-ref', 'HEAD'],
{
cwd,
encoding: 'utf8',
},
);
writeCodecFixture(
cwd,
[...beforeLastDigitRows, ['pr-b', '9']],
[{ id: 'pr-b', token: '9' }],
);
const beforeRebase = runCheck();
assert.equal(beforeRebase.status, 1);
assert.match(beforeRebase.stderr, /changed or removed: pr-a/);
writeCodecFixture(
cwd,
[...beforeLastDigitRows, ['pr-a', '9'], ['pr-b', '9']],
[
{ id: 'pr-a', token: '9' },
{ id: 'pr-b', token: '9' },
],
);
const staleRebase = runCheck();
assert.equal(staleRebase.status, 1);
assert.match(
staleRebase.stderr,
/Duplicate layer-state token reservation/,
);
writeCodecFixture(
cwd,
[...preWildlifeRows, ['pr-b', '9']],
[{ id: 'pr-b', token: '9' }],
);
const beforeRebase = runCheck();
assert.equal(beforeRebase.status, 1);
assert.match(beforeRebase.stderr, /changed or removed: pr-a/);
writeCodecFixture(
cwd,
[...preWildlifeRows, ['pr-a', '9'], ['pr-b', '9']],
[
{ id: 'pr-a', token: '9' },
{ id: 'pr-b', token: '9' },
],
);
const staleRebase = runCheck();
assert.equal(staleRebase.status, 1);
assert.match(staleRebase.stderr, /Duplicate layer-state token reservation/);
const published = readPublishedLayerStateReservations('HEAD', cwd);
assert.equal(nextLayerStateToken(published), '00');
const validBaselineRows = [...preWildlifeRows, ['pr-a', '9']];
writeCodecFixture(cwd, validBaselineRows, [{ id: 'pr-a', token: '9' }]);
const helper = spawnSync(
process.execPath,
[realpathSync(fixtureNext), 'pr-b'],
{ cwd, encoding: 'utf8' },
);
assert.equal(helper.status, 0, helper.stderr);
assert.match(helper.stdout, /pr-b: 00/);
assert.deepEqual(
JSON.parse(readFileSync(path.join(cwd, LEDGER_PATH), 'utf8')),
validBaselineRows,
'the helper reports a token without rewriting the ledger',
);
writeCodecFixture(
cwd,
[...preWildlifeRows, ['pr-a', '9'], ['pr-b', '00']],
[
{ id: 'pr-a', token: '9' },
{ id: 'pr-b', token: '00' },
],
);
const corrected = runCheck();
assert.equal(corrected.status, 0, corrected.stderr);
assert.match(corrected.stdout, /36 published, 1 new/);
});
const published = readPublishedLayerStateReservations('HEAD', cwd);
assert.equal(nextLayerStateToken(published), '00');
const validBaselineRows = [...beforeLastDigitRows, ['pr-a', '9']];
writeCodecFixture(cwd, validBaselineRows, [{ id: 'pr-a', token: '9' }]);
const helper = spawnSync(
process.execPath,
[realpathSync(fixtureNext), 'pr-b'],
{ cwd, encoding: 'utf8' },
);
assert.equal(helper.status, 0, helper.stderr);
assert.match(helper.stdout, /pr-b: 00/);
assert.deepEqual(
JSON.parse(readFileSync(path.join(cwd, LEDGER_PATH), 'utf8')),
validBaselineRows,
'the helper reports a token without rewriting the ledger',
);
writeCodecFixture(
cwd,
[...beforeLastDigitRows, ['pr-a', '9'], ['pr-b', '00']],
[
{ id: 'pr-a', token: '9' },
{ id: 'pr-b', token: '00' },
],
);
const corrected = runCheck();
assert.equal(corrected.status, 0, corrected.stderr);
assert.match(corrected.stdout, /36 published, 1 new/);
},
);
});
test('allocation batches cross the last digit and base-36 pair boundaries in order', () => {
const digitRows = [...'9'].map((digit) => [`retired-${digit}`, digit]);
const allDigits = parseLayerStateTokenReservations([
...preWildlifeRows,
...beforeLastDigitRows,
...digitRows,
]);
const beforeNine = { ...allDigits };
@@ -360,7 +380,7 @@ test('an isolated valid two-character fixture round-trips an l field beyond the
token,
}));
const fixtureRows = [
...preWildlifeRows,
...beforeLastDigitRows,
...priorDigits,
...fixtureLayers.map(({ id, token }) => [id, token]),
];
@@ -369,13 +389,16 @@ test('an isolated valid two-character fixture round-trips an l field beyond the
assert.equal(codec.validateLayerStateRegistry(), true);
assert.equal(
nextLayerStateToken(
parseLayerStateTokenReservations([...preWildlifeRows, ...priorDigits]),
parseLayerStateTokenReservations([
...beforeLastDigitRows,
...priorDigits,
]),
),
'00',
);
assert.equal(
validateLayerStateAllocations(
parseLayerStateTokenReservations(preWildlifeRows),
parseLayerStateTokenReservations(beforeLastDigitRows),
codec.LAYER_STATE_TOKEN_RESERVATIONS,
),
true,
@@ -400,19 +423,19 @@ test('an isolated valid two-character fixture round-trips an l field beyond the
test('checker reads a complete future base ledger and rejects retired-token reuse', () => {
withPublishedBase(
{
rows: [...reservationRows, ['retired-layer', '00']],
rows: [...reservationRows, ['retired-layer', '02']],
source:
'export const LAYER_STATE_TOKEN_RESERVATIONS = Object.freeze({ ["retired-layer"]: "00" });\n',
'export const LAYER_STATE_TOKEN_RESERVATIONS = Object.freeze({ ["retired-layer"]: "02" });\n',
},
(cwd) => {
const published = readPublishedLayerStateReservations('HEAD', cwd);
assert.equal(Object.keys(published).length, 37);
assert.equal(published['retired-layer'], '00');
assert.equal(Object.keys(published).length, 39);
assert.equal(published['retired-layer'], '02');
assert.throws(
() =>
validateLayerStateAllocations(published, {
...LAYER_STATE_TOKEN_RESERVATIONS,
newcomer: '00',
newcomer: '02',
}),
/changed or removed/,
);
@@ -18,12 +18,14 @@
["military", "m"],
["military-awareness", "g"],
["military-installations", "i"],
["news", "00"],
["radio", "r"],
["recent-imagery", "1"],
["rocket-launches", "x"],
["s2-ghostmaps", "5"],
["satellites", "s"],
["sea-marks", "6"],
["shipwrecks", "01"],
["ski-pistes", "7"],
["street-level", "0"],
["telegeography-submarine-cables", "u"],
+45 -3
View File
@@ -1,8 +1,11 @@
# Natural Earth packs
Offline named-region polygons for the voice-annotation resolver
(`src/data/naturalEarthRegions.js`) — "outline the Alps" resolves to the real
range geometry with no network dependency.
Offline polygons with no network dependency. The voice-annotation resolver
(`src/data/naturalEarthRegions.js`) reads the named regions, so "outline the
Alps" resolves to the real range geometry; area annotations read the
countries, states and provinces (`src/data/adminBoundaries.js`); and the News
layer reads the countries and the disputed areas
(`server/providers/news/areas.js`).
| File | Source dataset | Features |
|------|----------------|----------|
@@ -10,6 +13,7 @@ range geometry with no network dependency.
| `marine.json` | `ne_10m_geography_marine_polys` (seas, gulfs, straits, bays, …) | 292 named |
| `countries.json` | `ne_10m_admin_0_countries` (countries) | 256 |
| `states_provinces.json` | `ne_10m_admin_1_states_provinces` (states, provinces and other first-level units) | 4,587 named |
| `disputed_areas.json` | `ne_10m_admin_0_disputed_areas` (disputed, breakaway and UN-patrolled areas; a hand-picked set, see below) | 11 of 99 |
| `populated_places.json` | `ne_10m_populated_places_simple` (cities and towns, as points) | 7,342 |
**Source:** Natural Earth 10m physical vectors, via the canonical
@@ -105,6 +109,44 @@ Includes England, Scotland, Wales and Northern Ireland from
`57da82be755f4afccd8f3b14251bb2752f5df1395f47d2d86f817470c4a48862`).
Result: 945,843 bytes; 260 features, 2,088 parts, 122,788 vertices.
## Disputed areas (`disputed_areas.json`)
The News layer's areas that no one country's name may stand for
(`server/providers/news/areas.js`): a place inside one is named with the
area ("Crimea"), and Local there reads no country's outlets.
**Source:** `geojson/ne_10m_admin_0_disputed_areas.geojson` at the same pinned
commit (SHA-256
`9cafef8b7dfb6b164dc58f218f981f4ace9f716f6c03795d4c62d1ac9f3d50f5`), fetched
2026-11-05. Public domain, as above.
**Selection:** a hand-picked 11 of the source's 99 features. No rule picks
them; this is the list:
| Area | Natural Earth's note (`NOTE_BRK`) |
|------|-----------------------------------|
| Golan Heights | Admin. By Israel; Claimed by Syria |
| UNDOF Zone | UN Patrolled Zone in Syria |
| Transnistria | Self admin.; Claimed by Moldova |
| Abyei | Admin. by Sudan; Claimed by South Sudan |
| Crimea | Admin. by Russia; Claimed by Ukraine |
| Shebaa Farms | Admin. By Israel; Claimed by Lebanon |
| Bir Tawil | Between Egypt and Sudan |
| Halayib Triangle | Admin. by Egypt; Claimed by Sudan |
| East Jerusalem | Admin. By Israel; Claimed by Palestine |
| Abu Musa I. | Admin. by Iran; Claimed by UAE |
| Doumera Island | Admin. By Eritrea; Claimed by Djibouti |
The source names three of these by a country ("Moldova", "Sudan", "Iran");
the pack names them as the area. The 2014 Donetsk and Luhansk lines are left
out as out of date. Every other feature is left out too, so a place there is
named by its country in `countries.json`.
**Curation:** `kind` (`held`, `self`, `un`, `unclaimed`), `heldBy` and
`claimedBy` are read from `NOTE_BRK`, and `note` keeps it as published. Every
part is kept; each ring is Douglas-Peucker simplified at 0.003°, coordinates
are rounded to 3 decimals and rings are stored open. Provenance is in the
pack's `meta`. Result: 14,504 bytes.
## Populated places (`populated_places.json`)
The orbital view's "near <city>" (`src/data/placeBelow.js`): from 8x it
@@ -0,0 +1 @@
{"meta":{"title":"Natural Earth admin-0 disputed areas, for the News layer","source":"ne_10m_admin_0_disputed_areas","url":"https://raw.githubusercontent.com/nvkelso/natural-earth-vector/ca96624a56bd078437bca8184e78163e5039ad19/geojson/ne_10m_admin_0_disputed_areas.geojson","sha256":"9cafef8b7dfb6b164dc58f218f981f4ace9f716f6c03795d4c62d1ac9f3d50f5","fetched":"2026-11-05","license":"Public domain (https://www.naturalearthdata.com/about/terms-of-use/)","curation":"A hand-picked 11 of the source's 99 features: Golan Heights, UNDOF Zone, Transnistria, Abyei, Crimea, Shebaa Farms, Bir Tawil, Halayib Triangle, East Jerusalem, Abu Musa I. and Doumera Island. The source names three of them by a country (Moldova, Sudan, Iran); they are named here as the area. kind, heldBy and claimedBy are read from NOTE_BRK; note is NOTE_BRK as published. The 2014 Donetsk and Luhansk lines are left out as out of date. Every part kept; each ring Douglas-Peucker simplified at 0.003 degrees, coordinates rounded to 3 decimals, rings stored open."},"areas":[{"name":"Golan Heights","kind":"held","heldBy":"IL","claimedBy":"SY","note":"Admin. By Israel; Claimed by Syria","rings":[[[35.821,33.407],[35.81,33.36],[35.786,33.343],[35.764,33.334],[35.802,33.312],[35.769,33.273],[35.804,33.248],[35.808,33.202],[35.83,33.19],[35.833,33.161],[35.811,33.127],[35.811,33.112],[35.849,33.099],[35.846,33.085],[35.859,32.99],[35.888,32.945],[35.85,32.896],[35.838,32.866],[35.842,32.854],[35.834,32.828],[35.784,32.778],[35.758,32.744],[35.74,32.741],[35.685,32.711],[35.636,32.679],[35.612,32.682],[35.595,32.707],[35.6,32.717],[35.634,32.752],[35.635,32.769],[35.641,32.772],[35.635,32.794],[35.641,32.82],[35.638,32.832],[35.641,32.865],[35.638,32.875],[35.602,32.909],[35.615,32.921],[35.62,32.984],[35.588,33.018],[35.621,33.05],[35.634,33.052],[35.637,33.077],[35.656,33.125],[35.672,33.15],[35.661,33.213],[35.66,33.236],[35.666,33.247],[35.635,33.249],[35.608,33.239],[35.605,33.244],[35.618,33.256],[35.62,33.27],[35.631,33.275],[35.654,33.262],[35.712,33.307],[35.718,33.317],[35.716,33.327],[35.744,33.331],[35.769,33.343],[35.786,33.358],[35.806,33.391]]]},{"name":"UNDOF Zone","kind":"un","note":"UN Patrolled Zone in Syria","rings":[[[35.758,32.744],[35.784,32.778],[35.834,32.828],[35.842,32.854],[35.838,32.866],[35.85,32.896],[35.888,32.945],[35.859,32.99],[35.846,33.085],[35.849,33.099],[35.811,33.112],[35.811,33.127],[35.833,33.161],[35.83,33.19],[35.808,33.202],[35.804,33.248],[35.769,33.273],[35.802,33.312],[35.764,33.334],[35.786,33.343],[35.81,33.36],[35.821,33.407],[35.87,33.431],[35.873,33.416],[35.87,33.407],[35.845,33.389],[35.83,33.365],[35.83,33.351],[35.843,33.322],[35.845,33.304],[35.84,33.295],[35.819,33.284],[35.82,33.281],[35.851,33.276],[35.866,33.226],[35.889,33.199],[35.882,33.189],[35.885,33.179],[35.9,33.18],[35.911,33.166],[35.911,33.135],[35.892,33.124],[35.897,33.117],[35.903,33.117],[35.903,33.11],[35.868,33.107],[35.865,33.082],[35.877,32.993],[35.898,32.986],[35.924,32.968],[35.912,32.947],[35.89,32.929],[35.861,32.88],[35.843,32.822],[35.815,32.787],[35.791,32.774],[35.77,32.748],[35.764,32.747]]]},{"name":"Transnistria","kind":"self","claimedBy":"MD","note":"Self admin.; Claimed by Moldova","rings":[[[29.899,46.553],[29.868,46.58],[29.84,46.582],[29.831,46.588],[29.824,46.601],[29.776,46.58],[29.728,46.594],[29.748,46.617],[29.776,46.629],[29.759,46.658],[29.749,46.665],[29.728,46.67],[29.703,46.665],[29.696,46.676],[29.667,46.676],[29.69,46.707],[29.698,46.728],[29.665,46.801],[29.652,46.813],[29.62,46.815],[29.611,46.827],[29.619,46.832],[29.615,46.841],[29.59,46.824],[29.563,46.787],[29.549,46.793],[29.543,46.793],[29.531,46.783],[29.512,46.787],[29.498,46.801],[29.502,46.821],[29.495,46.828],[29.494,46.862],[29.477,46.889],[29.471,46.941],[29.46,46.953],[29.436,46.957],[29.376,46.935],[29.35,46.937],[29.316,46.958],[29.296,46.992],[29.325,46.988],[29.371,47.003],[29.378,47.012],[29.374,47.011],[29.364,47.033],[29.381,47.029],[29.383,47.042],[29.378,47.071],[29.372,47.078],[29.33,47.108],[29.296,47.122],[29.291,47.14],[29.237,47.162],[29.227,47.149],[29.221,47.149],[29.213,47.158],[29.188,47.162],[29.179,47.156],[29.18,47.145],[29.194,47.124],[29.19,47.111],[29.157,47.113],[29.148,47.096],[29.125,47.074],[29.099,47.092],[29.07,47.101],[29.095,47.135],[29.112,47.15],[29.145,47.163],[29.164,47.192],[29.179,47.197],[29.164,47.231],[29.094,47.31],[29.08,47.332],[29.079,47.348],[29.089,47.351],[29.123,47.329],[29.14,47.329],[29.154,47.336],[29.165,47.348],[29.139,47.376],[29.083,47.406],[29.091,47.437],[29.108,47.454],[29.111,47.464],[29.104,47.478],[29.093,47.487],[29.049,47.506],[29.034,47.518],[29.025,47.533],[29.016,47.582],[28.993,47.605],[28.987,47.622],[28.996,47.651],[28.988,47.661],[28.981,47.687],[28.976,47.743],[28.981,47.765],[29.018,47.827],[29.019,47.853],[28.981,47.875],[28.861,47.899],[28.829,47.917],[28.831,47.941],[28.813,47.965],[28.785,47.983],[28.754,47.979],[28.719,47.999],[28.698,48.022],[28.682,48.031]Line truncated
+91 -3
View File
@@ -91,7 +91,6 @@ test('Contacts moves a distance that rounds to 1,000 m into kilometres', () => {
assert.equal(presentAwarenessDistance(9960), '10\u00a0km');
});
/**
* Give `viewer`'s bound camera port a follow of its own, as the renderer's
* is: `follow(target)` sets `followed` and raises `followChanged`.
@@ -479,7 +478,7 @@ test('a dependency the user adopts stays on when Contacts turns off', async () =
assert.deepEqual(
released,
AWARENESS_DEPENDENCIES.filter((layerId) => layerId !== 'flights').sort(),
'the adopted layer is the user\'s now; the rest are still released',
"the adopted layer is the user's now; the rest are still released",
);
} finally {
runtime.restore();
@@ -1179,6 +1178,95 @@ test('production military tracked-subject label falls back to registration befor
}
});
test('the tracked airliner’s photo reaches the Contacts panel when it lands after selection', async () => {
const id = 'a1f2c3';
const position = Cesium.Cartesian3.fromDegrees(-97.71, 30.21, 10_668);
const sourceViewer = { scene: { primitives: { remove() {} } } };
const runtime = installAwarenessRuntime();
const restores = [];
const meta = {
callsign: 'AAL100',
altitude: 10_668,
renderAltitudeM: 10_700,
velocity: 250,
true_track: 95,
klass: 'airliner',
onGround: false,
wasAirborne: true,
turnRateDps: 0,
rawLat: 30.21,
rawLon: -97.71,
photo: null,
};
try {
_setTrackedFlightRefreshStateForTest({
icao24: id,
entity: null,
icon: { position, show: true },
iconLayer: { show: true, remove() {} },
viewer: sourceViewer,
meta,
});
followIn(
runtime.viewer,
withEntityRecord({}, { trackedId: `flights:${id}` }),
);
replaceMethod(
militaryFlightsLayer,
'getTrackedSubject',
() => null,
restores,
);
replaceMethod(flightsLayer, 'trackById', () => true, restores);
replaceMethod(militaryFlightsLayer, 'trackById', () => true, restores);
militaryAwarenessLayer.setParams({ passive: false });
await nextTurn();
assert.equal(runtime.panel().view?.kind, 'results');
assert.equal(runtime.panel().view.photo, null, 'no photo before it lands');
// An unchanged refresh stays quiet.
const settledPublishes = runtime.panel().publishes;
await militaryAwarenessLayer.update();
assert.equal(runtime.panel().publishes, settledPublishes);
// The photo lands while the plane holds still: render-worthy on its own.
meta.photo = {
src: 'https://t.plnspttrs.net/1/a1f2c3_280.jpg',
width: 280,
height: 186,
photographer: 'Jane Doe',
link: 'https://www.planespotters.net/photo/1/n100aa',
};
await militaryAwarenessLayer.update();
assert.deepEqual(runtime.panel().view.photo, {
src: 'https://t.plnspttrs.net/1/a1f2c3_280.jpg',
width: 280,
height: 186,
link: 'https://www.planespotters.net/photo/1/n100aa',
credit: 'Photo © Jane Doe',
});
// And it repaints once, not on every refresh.
const shownPublishes = runtime.panel().publishes;
await militaryAwarenessLayer.update();
assert.equal(runtime.panel().publishes, shownPublishes);
} finally {
restores.reverse().forEach((restore) => restore());
_setTrackedFlightRefreshStateForTest({
icao24: id,
entity: null,
icon: { position, show: true },
iconLayer: { show: false, remove() {} },
viewer: sourceViewer,
meta: {},
tracked: false,
});
runtime.restore();
}
});
test('a cached Context subject re-reads its label when enrichment lands after selection', async () => {
// The subject snapshot is captured once at selection. Selecting a
// callsign-less aircraft BEFORE adsbdb enrichment answers used to freeze the
@@ -1797,7 +1885,7 @@ test('hasContact declines while a layer is disabled, whatever its maps still hol
[
'aisLiveVessels',
readLayerSource(new URL('./aisLiveVessels.js', import.meta.url)),
/hasContact\(\s*mmsi,?\s*\)\s*\{\s*\n\s*if\s*\(\s*!state\.feed\.enabled\s*\|\|\s*!state\.records\.byMmsi\s*\|\|\s*state\.records\.byMmsi\.size\s*===\s*0,?\s*\)\s*return\s*null;/,
/hasContact\(\s*id,?\s*\)\s*\{\s*\n\s*if\s*\(\s*!state\.feed\.enabled\s*\|\|\s*!state\.records\.byId\s*\|\|\s*state\.records\.byId\.size\s*===\s*0,?\s*\)\s*return\s*null;/,
],
]) {
assert.match(
+2 -2
View File
@@ -61,9 +61,9 @@ export function formatAwarenessLabel(value) {
value.callsign,
value.name,
value.label,
value.mmsi,
value.id,
value.icao24,
value.mmsi,
]) {
const label = formatAwarenessLabel(candidate);
if (label !== '—') return label;
@@ -154,7 +154,7 @@ export function getAwarenessNavigationTargets(
? cohort.summary.nearest
: [];
for (const item of sourceItems) {
const id = item?.icao24 || item?.mmsi || item?.id;
const id = item?.icao24 || item?.id || item?.mmsi;
if (!id) continue;
const key = `${layerId}:${id}`;
if (key === `${subject?.layerId}:${subject?.id}`) continue;
+160 -8
View File
@@ -13,7 +13,7 @@ import {
julianToEpochMs,
secondsDifference,
} from '../geo/julian.js';
import { copyInto, norm180, norm360, vec } from '../geo/vector.js';
import { copyInto, norm180, norm360, toDegrees, vec } from '../geo/vector.js';
const DEG = Math.PI / 180;
@@ -181,6 +181,136 @@ export function staleCoastLimitSeconds({
return Math.min(ceiling, Math.max(floor, contactLeadSec + grace));
}
/** @constant {number} Dead reckoning never moves a contact faster than this
* (1,500 kt, the trail's continuity limit), so a corrupt reported speed
* cannot fly a coasting plane hundreds of kilometres. */
export const COAST_MAX_SPEED_MPS = (1_500 * 1852) / 3600;
/** @constant {number} A contact with no fresh report coasts at most this long past it, whatever its source limit; there is no distance cap. */
export const STALE_COAST_MAX_SEC = 300;
/** @constant {number} A report this close to a known ground height holds
* instead of coasting. */
export const STALE_HOLD_MAX_HEIGHT_M = 150;
/**
* Whether a contact whose reports have stopped holds at its last reported
* position instead of coasting: it reported on the ground, or a known ground
* floor puts it within STALE_HOLD_MAX_HEIGHT_M of the ground (landing or
* taking off). A plane that low has no evidence of being anywhere but where
* it was last heard. Where the ground is unknown, barometric altitude is not
* read as height above it; the contact coasts under the stale cap.
* @param {object} report
* @param {boolean} [report.onGround]
* @param {number} [report.heightM] - Render height (ellipsoidal metres).
* @param {number} [report.groundM] - Ellipsoidal ground under the report, if known.
* @returns {boolean}
*/
export function staleHoldsAtLastReport({ onGround, heightM, groundM } = {}) {
if (onGround === true) return true;
return (
Number.isFinite(heightM) &&
Number.isFinite(groundM) &&
heightM - groundM < STALE_HOLD_MAX_HEIGHT_M
);
}
/**
* The hold-or-coast decision for a report, made once and kept on the report,
* so a ground floor that resolves while the contact coasts cannot flip it and
* snap the icon back. Height and position come from the report itself.
* @param {{position: {x: number, y: number, z: number}, staleHolds?: boolean}} fix - History
* fix; `staleHolds` is stored on it.
* @param {object} args
* @param {boolean} [args.onGround] - The contact's ground flag.
* @param {(latDeg: number, lonDeg: number) => number|null} [args.cachedGroundFloor]
* @returns {boolean}
*/
export function staleHoldsForFix(fix, { onGround, cachedGroundFloor } = {}) {
if (typeof fix.staleHolds === 'boolean') return fix.staleHolds;
const carto = toCartographicRadians(fix.position);
const groundM =
carto && typeof cachedGroundFloor === 'function'
? cachedGroundFloor(toDegrees(carto.lat), toDegrees(carto.lon))
: null;
fix.staleHolds = staleHoldsAtLastReport({
onGround,
heightM: carto?.height,
groundM,
});
return fix.staleHolds;
}
/**
* Seconds a contact coasts past `newest` at a display time `elapsedSec`
* after it, counting any coast a synthetic fix already took since the real
* report it was built from (`reportEpochMs`), so a chain of synthetic fixes
* never coasts further than one report would.
* @param {object} args
* @param {{epochMs: number, reportEpochMs?: number, velocity?: number}} args.newest
* @param {number} args.elapsedSec - Display time past `newest`.
* @param {number} args.coastLimitSec - Source limit past `newest`.
* @param {boolean} args.holds
* @returns {number}
*/
export function staleCoastSecondsFrom({
newest,
elapsedSec,
coastLimitSec,
holds,
}) {
const alreadySec = Number.isFinite(newest?.reportEpochMs)
? Math.max(0, (newest.epochMs - newest.reportEpochMs) / 1000)
: 0;
return Math.max(
0,
staleCoastSeconds({
elapsedSec: elapsedSec + alreadySec,
coastLimitSec: coastLimitSec + alreadySec,
holds,
}) - alreadySec,
);
}
/** @constant {number} A coasted position sits at least this far (m) above the ground. */
export const COAST_FLOOR_LIFT_M = 1.5;
/**
* Lift a coasted position to COAST_FLOOR_LIFT_M above the ground where the
* ground is known; a coast runs level from the report and terrain may rise
* under it.
* @param {{x: number, y: number, z: number}} position - Mutated in place.
* @param {(latDeg: number, lonDeg: number) => number|null} [cachedGroundFloor]
* @returns {{x: number, y: number, z: number}}
*/
export function floorCoastedPosition(position, cachedGroundFloor) {
if (typeof cachedGroundFloor !== 'function') return position;
const carto = toCartographicRadians(position);
if (!carto) return position;
const ground = cachedGroundFloor(toDegrees(carto.lat), toDegrees(carto.lon));
if (!Number.isFinite(ground) || carto.height >= ground + COAST_FLOOR_LIFT_M)
return position;
return copyInto(
fromRadians(carto.lon, carto.lat, ground + COAST_FLOOR_LIFT_M),
position,
);
}
/**
* Seconds to coast past the last report: the elapsed time, bounded by the
* source's coast limit and STALE_COAST_MAX_SEC; none for a contact that
* holds.
* @param {object} args
* @param {number} args.elapsedSec - Display time past the last report.
* @param {number} args.coastLimitSec - From `staleCoastLimitSeconds`.
* @param {boolean} args.holds - From `staleHoldsAtLastReport`.
* @returns {number}
*/
export function staleCoastSeconds({ elapsedSec, coastLimitSec, holds }) {
if (holds || !(elapsedSec > 0)) return 0;
return Math.max(0, Math.min(elapsedSec, coastLimitSec, STALE_COAST_MAX_SEC));
}
/**
* Shortest-arc rate limiter: step `prevDeg` toward `targetDeg` by at most
* `maxDegPerSec * dtSec`. Seeds directly on the target when prev is null.
@@ -427,12 +557,21 @@ const _forwardFixArc = { east: 0, north: 0, endCourseDeg: 0 };
* kinematics. This prevents a late course change from reprojecting the entire
* stale interval and snapping the rendered contact by kilometres.
*
* The same stale rules as the display apply: no fix for a contact that holds
* at its report (`staleHoldsForFix`, decided before calling), a coast of at
* most STALE_COAST_MAX_SEC counted from the real report
* (`reportEpochMs` carries it along a chain), and never below known ground.
* The result is a motion fix only, never a report for the trail.
*
* @param {{time: object, epochMs?: number, position: {x: number, y: number, z: number},
* velocity?: number, track?: number}} newest Existing immutable history fix.
* @param {{epochMs: number, velocity: number, track: number, turnRateDps?: number}} next
* velocity?: number, track?: number, staleHolds?: boolean, reportEpochMs?: number}} newest
* Existing immutable history fix.
* @param {{epochMs: number, velocity: number, track: number, turnRateDps?: number,
* cachedGroundFloor?: Function}} next
* New kinematics and the wall/source epoch at which they become authoritative.
* @returns {{time: object, epochMs: number, position: {x: number, y: number, z: number},
* velocity: number, track: number}|null} Forward synthetic fix, or null.
* velocity: number, track: number, staleHolds?: boolean, reportEpochMs: number}|null}
* Forward synthetic fix, or null.
*/
export function synthesizeForwardKinematicsFix(newest, next = {}) {
if (!newest?.position || !newest?.time || !Number.isFinite(next.epochMs))
@@ -442,12 +581,18 @@ export function synthesizeForwardKinematicsFix(newest, next = {}) {
: julianToEpochMs(newest.time);
if (!Number.isFinite(startEpochMs) || next.epochMs <= startEpochMs)
return null;
if (newest.staleHolds === true) return null;
const previousVelocity = Number.isFinite(newest.velocity)
? Math.max(0, newest.velocity)
: 0;
const previousTrack = Number.isFinite(newest.track) ? newest.track : 0;
const dtSec = (next.epochMs - startEpochMs) / 1000;
const dtSec = staleCoastSecondsFrom({
newest: { epochMs: startEpochMs, reportEpochMs: newest.reportEpochMs },
elapsedSec: (next.epochMs - startEpochMs) / 1000,
coastLimitSec: Infinity,
holds: false,
});
arcOffsetEnu(
previousVelocity,
previousTrack,
@@ -455,13 +600,20 @@ export function synthesizeForwardKinematicsFix(newest, next = {}) {
dtSec,
_forwardFixArc,
);
const position = framePoint(
eastNorthUp(newest.position),
vec(_forwardFixArc.east, _forwardFixArc.north, 0),
const position = floorCoastedPosition(
framePoint(
eastNorthUp(newest.position),
vec(_forwardFixArc.east, _forwardFixArc.north, 0),
),
next.cachedGroundFloor,
);
return {
time: julianFromEpochMs(next.epochMs),
epochMs: next.epochMs,
reportEpochMs: Number.isFinite(newest.reportEpochMs)
? newest.reportEpochMs
: startEpochMs,
staleHolds: newest.staleHolds,
position,
velocity: Number.isFinite(next.velocity)
? Math.max(0, next.velocity)
+2 -2
View File
@@ -50,7 +50,7 @@ test('resolvePickId: the map and nothing → null', () => {
test('ownership: sibling layers recognize each other via String-coerced ids', () => {
const points = new Map([[25544, {}], [43013, {}]]); // satellites: numeric keys
const vessels = new Map([['367123450', {}]]); // AIS: string mmsi keys
const vessels = new Map([['367123450', {}]]); // AIS: string id keys
registerPickOwner('satellites', (pickedId) => {
const norad = Number(pickedId);
return Number.isFinite(norad) && points.has(norad);
@@ -59,7 +59,7 @@ test('ownership: sibling layers recognize each other via String-coerced ids', ()
try {
// Flights asking about a satellite pick (raw numeric id → String upstream)
assert.equal(isOwnedByOtherLayer('flights', resolvePickId(item('sat:1', '25544'))), true);
// Flights asking about a vessel pick (an icon row id: the mmsi)
// Flights asking about a vessel pick (an icon row id: the vessel's id)
assert.equal(isOwnedByOtherLayer('flights', resolvePickId(item('ais:1', '367123450'))), true);
// A layer never owns its own pick via the sibling scan
assert.equal(isOwnedByOtherLayer('satellites', '25544'), false);
+2 -2
View File
@@ -57,8 +57,8 @@ function contextCarrierRecord(hit, dataManager) {
function fromRecord(record) {
const layerId = record.layerId || null;
const id =
layerId === 'ais-live-vessels' && record.properties?.mmsi
? String(record.properties.mmsi)
layerId === 'ais-live-vessels' && record.properties?.vesselId
? String(record.properties.vesselId)
: String(record.id);
return {
layerId,
+122
View File
@@ -0,0 +1,122 @@
/**
* @module planespottersPhoto
* @description Reads a Planespotters photo answer into the one thumbnail
* every surface shows. Planespotters lets the thumbnail be hotlinked on the
* condition that the photographer is credited next to it and the image links
* back to the photo's page. A photo whose answer names no photographer is
* still shown, linked to its page, with no credit line; a photo whose image or
* page is not on Planespotters' own hosts is "no photo": nothing arbitrary is
* ever shown or linked.
*
* Accepts the upstream answer (`GET https://api.planespotters.net/pub/photos/hex/{hex}`,
* `{photos: [...]}`), the cached server shape
* (`{found, thumbnail_large?, thumbnail: {src, width, height}, photographer,
* link}`), and an
* already-read photo (`{found, src, width, height, photographer, link}`).
* Pure: no fetch, no DOM.
*/
/** The image host: Planespotters' thumbnail CDN and its subdomains. */
const IMAGE_HOST = 'plnspttrs.net';
/** The only page host a photo may link to. */
const PAGE_HOST = 'www.planespotters.net';
const NO_PHOTO = Object.freeze({ found: false });
const isObject = (value) => Boolean(value) && typeof value === 'object';
/** The parsed `https:` URL, or null for anything else or with userinfo/port. */
function httpsUrl(value) {
if (typeof value !== 'string' || !value) return null;
let url;
try {
url = new URL(value);
} catch {
return null;
}
if (url.protocol !== 'https:' || url.username || url.password || url.port)
return null;
return url;
}
function imageSrc(value) {
const url = httpsUrl(value);
return url &&
(url.hostname === IMAGE_HOST || url.hostname.endsWith(`.${IMAGE_HOST}`))
? url.href
: null;
}
function pageLink(value) {
const url = httpsUrl(value);
return url && url.hostname === PAGE_HOST ? url.href : null;
}
function dimension(value) {
const number = Number(value);
return value != null && Number.isFinite(number) && number > 0
? Math.round(number)
: null;
}
/** One candidate `{src, width, height, photographer, link}`, checked. */
function checked({ src, width, height, photographer, link }) {
const credit = typeof photographer === 'string' ? photographer.trim() : '';
const image = imageSrc(src);
const page = pageLink(link);
if (!image || !page) return null;
return {
found: true,
src: image,
width: dimension(width),
height: dimension(height),
photographer: credit,
link: page,
};
}
/** The upstream photo's candidates, large thumbnail first. */
function upstreamCandidates(photo) {
if (!photo || typeof photo !== 'object') return [];
return [photo.thumbnail_large, photo.thumbnail]
.filter((thumb) => thumb && typeof thumb === 'object')
.map((thumb) => ({
src: thumb.src,
width: thumb.size?.width,
height: thumb.size?.height,
photographer: photo.photographer,
link: photo.link,
}));
}
/**
* Read a Planespotters answer into the first photo that passes the checks.
* @param {*} payload Upstream, cached-server, or already-read photo.
* @returns {{found: true, src: string, width: ?number, height: ?number,
* photographer: string, link: string} | {found: false}}
*/
export function parsePlanespottersPhoto(payload) {
if (!payload || typeof payload !== 'object') return NO_PHOTO;
let candidates;
if (Array.isArray(payload.photos)) {
candidates = payload.photos.flatMap(upstreamCandidates);
} else if (payload.found !== true) {
return NO_PHOTO;
} else if (isObject(payload.thumbnail) || isObject(payload.thumbnail_large)) {
// Large first, as for the upstream answer; each must pass the checks.
candidates = [payload.thumbnail_large, payload.thumbnail]
.filter(isObject)
.map((thumb) => ({
...thumb,
photographer: payload.photographer,
link: payload.link,
}));
} else {
candidates = [payload];
}
for (const candidate of candidates) {
const photo = checked(candidate);
if (photo) return photo;
}
return NO_PHOTO;
}
+207
View File
@@ -0,0 +1,207 @@
// src/data/planespottersPhoto.test.mjs — the Planespotters photo answer is read
// into one credited thumbnail, and nothing outside Planespotters' own hosts is
// ever shown or linked.
import test from 'node:test';
import assert from 'node:assert/strict';
import { parsePlanespottersPhoto } from './planespottersPhoto.js';
const UPSTREAM = Object.freeze({
photos: [
{
id: '1745410',
thumbnail: {
src: 'https://t.plnspttrs.net/33043/1745410_822dfe330c_t.jpg',
size: { width: 200, height: 133 },
},
thumbnail_large: {
src: 'https://t.plnspttrs.net/33043/1745410_822dfe330c_280.jpg',
size: { width: 420, height: 280 },
},
link: 'https://www.planespotters.net/photo/1745410/n160an-american-airlines-airbus-a321-231-wl?utm_source=api',
photographer: 'Jan Seler',
},
],
});
const PHOTO = Object.freeze({
found: true,
src: 'https://t.plnspttrs.net/33043/1745410_822dfe330c_280.jpg',
width: 420,
height: 280,
photographer: 'Jan Seler',
link: 'https://www.planespotters.net/photo/1745410/n160an-american-airlines-airbus-a321-231-wl?utm_source=api',
});
const photo = (overrides) => ({
photos: [{ ...UPSTREAM.photos[0], ...overrides }],
});
test('the upstream answer maps to the large thumbnail, its size, credit and link', () => {
assert.deepEqual(parsePlanespottersPhoto(UPSTREAM), PHOTO);
});
test('the small thumbnail stands in when the large one is missing', () => {
assert.deepEqual(parsePlanespottersPhoto(photo({ thumbnail_large: null })), {
...PHOTO,
src: 'https://t.plnspttrs.net/33043/1745410_822dfe330c_t.jpg',
width: 200,
height: 133,
});
});
test('a server’s cached shape reads the same way', () => {
assert.deepEqual(
parsePlanespottersPhoto({
found: true,
thumbnail: { src: PHOTO.src, width: 420, height: 280 },
photographer: 'Jan Seler',
link: PHOTO.link,
}),
PHOTO,
);
assert.deepEqual(parsePlanespottersPhoto({ found: false }), {
found: false,
});
});
test('a server’s cached shape prefers its large thumbnail', () => {
assert.deepEqual(
parsePlanespottersPhoto({
found: true,
thumbnail: {
src: 'https://t.plnspttrs.net/33043/1745410_822dfe330c_t.jpg',
width: 200,
height: 133,
},
thumbnail_large: { src: PHOTO.src, width: 420, height: 280 },
photographer: 'Jan Seler',
link: PHOTO.link,
}),
PHOTO,
);
});
test('a server’s cached shape falls back to its small thumbnail when the large one fails the checks', () => {
const small = {
src: 'https://t.plnspttrs.net/33043/1745410_822dfe330c_t.jpg',
width: 200,
height: 133,
};
for (const thumbnail_large of [
{ src: 'https://evil.example/a.jpg', width: 420, height: 280 },
null,
]) {
assert.deepEqual(
parsePlanespottersPhoto({
found: true,
thumbnail: small,
thumbnail_large,
photographer: 'Jan Seler',
link: PHOTO.link,
}),
{ ...PHOTO, ...small },
JSON.stringify(thumbnail_large),
);
}
});
test('a photo that names no photographer is still a photo, uncredited', () => {
for (const photographer of ['', ' ', 42, undefined]) {
assert.deepEqual(
parsePlanespottersPhoto(photo({ photographer })),
{ ...PHOTO, photographer: '' },
String(photographer),
);
}
});
test('no photo, junk, and missing fields are "no photo"', () => {
for (const payload of [
{ photos: [] },
{},
null,
undefined,
'nope',
{ photos: 'nope' },
{ photos: [null] },
photo({ link: '' }),
photo({ thumbnail: null, thumbnail_large: null }),
]) {
assert.deepEqual(
parsePlanespottersPhoto(payload),
{ found: false },
JSON.stringify(payload),
);
}
});
test('a src outside https *.plnspttrs.net is dropped', () => {
for (const src of [
'http://t.plnspttrs.net/a.jpg',
'https://plnspttrs.net.evil.example/a.jpg',
'https://evil.example/t.plnspttrs.net/a.jpg',
'https://t.plnspttrs.net.evil.example/a.jpg',
'https://[email protected]/a.jpg',
'https://t.plnspttrs.net:8443/a.jpg',
'javascript:alert(1)',
'//t.plnspttrs.net/a.jpg',
'not a url',
]) {
assert.deepEqual(
parsePlanespottersPhoto(
photo({
thumbnail_large: { src, size: { width: 420, height: 280 } },
thumbnail: { src, size: { width: 200, height: 133 } },
}),
),
{ found: false },
src,
);
}
});
test('a link anywhere but https://www.planespotters.net is dropped', () => {
for (const link of [
'http://www.planespotters.net/photo/1',
'https://planespotters.net/photo/1',
'https://www.planespotters.net.evil.example/photo/1',
'https://evil.example/?u=https://www.planespotters.net/',
'https://user:[email protected]/photo/1',
'https://www.planespotters.net:444/photo/1',
'javascript:alert(1)',
]) {
assert.deepEqual(
parsePlanespottersPhoto(photo({ link })),
{ found: false },
link,
);
}
});
test('the first photo that passes the checks is the one shown', () => {
const second = {
...UPSTREAM.photos[0],
photographer: 'Second Spotter',
};
assert.deepEqual(
parsePlanespottersPhoto({
photos: [
{ ...UPSTREAM.photos[0], link: 'https://evil.example/' },
second,
],
}),
{ ...PHOTO, photographer: 'Second Spotter' },
);
});
test('a missing size is null and the credit is trimmed', () => {
assert.deepEqual(
parsePlanespottersPhoto(
photo({
photographer: ' Jan Seler ',
thumbnail_large: { src: PHOTO.src },
}),
),
{ ...PHOTO, width: null, height: null },
);
});
+38
View File
@@ -1,7 +1,11 @@
import test from 'node:test';
import assert from 'node:assert/strict';
import {
REGIONAL_NEWS_WINDOW_HOURS,
googleNewsWindowOperator,
normalizeRegionalArticles,
recentRegionalArticles,
regionalNewsWindowHours,
normalizeRegionalPlace,
normalizeRegionalWeather,
regionalDistanceM,
@@ -61,3 +65,37 @@ test('regional distance handles nearby movement and missing positions', () => {
assert.ok(distance > 11000 && distance < 11200);
assert.equal(regionalDistanceM(null, null), Infinity);
});
test('regional news is held to one 24-hour window, newest first, undated dropped', () => {
assert.equal(REGIONAL_NEWS_WINDOW_HOURS, 24);
assert.equal(googleNewsWindowOperator(), 'when:1d');
assert.equal(googleNewsWindowOperator(6), 'when:6h');
assert.equal(regionalNewsWindowHours('12'), 12);
assert.equal(regionalNewsWindowHours(0), 24);
assert.equal(regionalNewsWindowHours(undefined), 24);
const now = Date.parse('2026-11-04T12:00:00Z');
const at = (hours) => new Date(now - hours * 3_600_000).toISOString();
const rows = [
{ title: 'a', publishedAt: at(23) },
{ title: 'stale', publishedAt: at(25) },
{ title: 'undated', publishedAt: null },
{ title: 'garbled', publishedAt: 'not a date' },
{ title: 'b', publishedAt: at(1) },
{ title: 'future', publishedAt: at(-2) },
{ title: 'c', publishedAt: at(5) },
];
assert.deepEqual(
recentRegionalArticles(rows, { now }).map((row) => row.title),
['b', 'c', 'a'],
);
assert.deepEqual(
recentRegionalArticles(rows, { now, limit: 2 }).map((row) => row.title),
['b', 'c'],
);
assert.deepEqual(
recentRegionalArticles(rows, { now, windowHours: 4 }).map((row) => row.title),
['b'],
);
assert.deepEqual(recentRegionalArticles([], { now }), []);
assert.deepEqual(recentRegionalArticles(undefined, { now }), []);
});
+7
View File
@@ -55,6 +55,13 @@ export function normalizeRegionalPlace(payload) {
};
}
export {
REGIONAL_NEWS_WINDOW_HOURS,
googleNewsWindowOperator,
recentRegionalArticles,
regionalNewsWindowHours,
} from './regionalNewsWindow.js';
/** Normalize and deduplicate GDELT ArticleList output without trusting article HTML. */
export function normalizeRegionalArticles(payload, limit = MAX_ARTICLES) {
const rows = Array.isArray(payload?.articles) ? payload.articles : [];
+66
View File
@@ -0,0 +1,66 @@
/** The regional-news freshness window, shared by the servers and the Cockpit. */
/** At most this many articles answer a regional brief. */
export const REGIONAL_NEWS_ROWS = 5;
/**
* The regional-news freshness window, in hours. The servers ask upstream for
* this window, drop anything older and report it as `newsWindowHours`; the
* Cockpit labels its list with it.
*/
export const REGIONAL_NEWS_WINDOW_HOURS = 24;
// A publish time this far ahead of the clock is skew, not a future story.
const REGIONAL_NEWS_CLOCK_SKEW_MS = 15 * 60_000;
/**
* A served window in hours, or the default when it is missing or out of range.
* @param {unknown} value
* @returns {number}
*/
export function regionalNewsWindowHours(value) {
const hours = Number(value);
return Number.isInteger(hours) && hours >= 1 && hours <= 168
? hours
: REGIONAL_NEWS_WINDOW_HOURS;
}
/**
* The Google News search operator asking for the window: `when:1d` for 24 h.
* @param {number} [hours]
* @returns {string}
*/
export function googleNewsWindowOperator(hours = REGIONAL_NEWS_WINDOW_HOURS) {
const span = regionalNewsWindowHours(hours);
return span % 24 === 0 ? `when:${span / 24}d` : `when:${span}h`;
}
/**
* The articles published inside the window, newest first, at most `limit`.
* An article without a parseable publish time is dropped: nothing shows it is
* recent. One dated more than 15 minutes ahead of `now` is dropped too.
* @param {Array<{publishedAt?: string|null}>} articles
* @param {{now?: number, windowHours?: number, limit?: number}} [options]
* @returns {Array<object>}
*/
export function recentRegionalArticles(
articles,
{
now = Date.now(),
windowHours = REGIONAL_NEWS_WINDOW_HOURS,
limit = REGIONAL_NEWS_ROWS,
} = {},
) {
const oldest = now - regionalNewsWindowHours(windowHours) * 3_600_000;
return (Array.isArray(articles) ? articles : [])
.map((article) => ({ article, at: Date.parse(article?.publishedAt) }))
.filter(
({ at }) =>
Number.isFinite(at) &&
at >= oldest &&
at <= now + REGIONAL_NEWS_CLOCK_SKEW_MS,
)
.sort((a, b) => b.at - a.at)
.slice(0, Math.max(0, limit))
.map(({ article }) => article);
}
+48
View File
@@ -11,6 +11,7 @@ import createViteConfig, {
validMilitaryInstallationBox,
validRegionalPoint,
} from '../../vite.config.js';
import { fetchRegionalNews } from '../../server/providers/regional/news.js';
test('missing Google place context is a quiet keyless capability, not a 503', () => {
assert.deepEqual(keylessGooglePlacesResponse(undefined), {
@@ -113,3 +114,50 @@ test('regional brief treats an all-source outage as total failure', () => {
news: { status: 'unavailable' },
}), true);
});
test('local regional news asks for the last day, drops old and undated items, newest first', async (t) => {
const realFetch = globalThis.fetch;
t.after(() => { globalThis.fetch = realFetch; });
const urls = [];
let rss;
let gdelt;
globalThis.fetch = async (url) => {
urls.push(new URL(String(url)));
const answer = String(url).includes('news.google') ? rss : gdelt;
return typeof answer === 'function' ? answer() : answer.clone();
};
const at = (hours) => new Date(Date.now() - hours * 3_600_000).toUTCString();
const item = (title, date) =>
`<item><title>${title}</title><link>https://news.example/${title}</link>${date ? `<pubDate>${date}</pubDate>` : ''}</item>`;
rss = new Response(`<rss><channel>${[
item('old', at(4 * 24)),
item('undated', null),
item('day', at(20)),
item('hour', at(1)),
].join('')}</channel></rss>`);
const place = { locality: 'Austin' };
const ready = await fetchRegionalNews(place);
assert.equal(urls[0].searchParams.get('q'), 'Austin when:1d');
assert.equal(ready.status, 'ready');
assert.deepEqual(ready.articles.map((row) => row.title), ['hour', 'day']);
// Nothing recent in RSS: GDELT is asked for the same 24 h window.
rss = new Response(`<rss><channel>${item('old', at(30))}</channel></rss>`);
gdelt = Response.json({ articles: [] });
urls.length = 0;
const empty = await fetchRegionalNews(place);
assert.equal(urls[1].searchParams.get('timespan'), '24h');
assert.deepEqual(empty, { status: 'empty', query: 'Austin', articles: [], source: 'GDELT fallback' });
// RSS answered with nothing recent and GDELT failed: still a true empty.
rss = new Response('<rss><channel></channel></rss>');
gdelt = () => Promise.reject(new TypeError('network'));
assert.equal((await fetchRegionalNews(place)).status, 'empty');
// Neither source answered, or no place: unavailable.
rss = () => Promise.resolve(new Response('busy', { status: 503 }));
const failed = await fetchRegionalNews(place);
assert.equal(failed.status, 'unavailable');
assert.deepEqual(failed.articles, []);
assert.equal((await fetchRegionalNews(null)).status, 'unavailable');
});
+10 -1
View File
@@ -46,7 +46,13 @@ function alongTrackKm(position, origin, destination) {
}
const NEAR_ENDPOINT_KM = 130;
/** Least allowed distance off the great circle, and how far past either
* endpoint the plane may be along it. */
const CROSS_TRACK_KM = 200;
/** On a long route the allowed distance off the great circle grows to this
* share of its length: airways and winds take a coast-to-coast flight several
* hundred kilometres off it (JFK–SFO: 623 km). */
const CROSS_TRACK_ROUTE_FRACTION = 0.15;
const LOW_ALT_M = 3700; // ~12 000 ft
const VERT_TREND_MPS = 2; // ~400 fpm
const LOCAL_AIRPORT_KM = 150;
@@ -90,6 +96,9 @@ export function routePlausible({
// existing loose check when the segment cannot be judged reliably.
const segmentKnown =
routeKm > 0.001 && routeKm < Math.PI * EARTH_RADIUS_KM - 0.001;
const corridorKm = segmentKnown
? Math.max(CROSS_TRACK_KM, CROSS_TRACK_ROUTE_FRACTION * routeKm)
: CROSS_TRACK_KM;
geomOk =
Math.abs(
crossTrackKm(
@@ -100,7 +109,7 @@ export function routePlausible({
destination.lat,
destination.lon,
),
) < CROSS_TRACK_KM &&
) < corridorKm &&
(!segmentKnown ||
(segmentAlongKm >= -CROSS_TRACK_KM &&
segmentAlongKm <= routeKm + CROSS_TRACK_KM));
+18
View File
@@ -27,6 +27,24 @@ test('plane in London with an SFO→LAX route: implausible', () => {
}), false);
});
test('a long route allows a wider corridor; a short one does not', () => {
// JFK→SFO over Kansas, 384 km south of the great circle.
assert.equal(routePlausible({
latDeg: 38.21, lonDeg: -99.69, altitudeM: 10370, verticalRateMps: 0,
origin: JFK, destination: SFO,
}), true);
// 516 km off the 543 km SFO→LAX route is still the wrong route.
assert.equal(routePlausible({
latDeg: 37.9, lonDeg: -115.0, altitudeM: 10000, verticalRateMps: 0,
origin: SFO, destination: LAX,
}), false);
// 960 km off, past 15 % of the 4,152 km JFK→SFO route, is still wrong.
assert.equal(routePlausible({
latDeg: 33.0, lonDeg: -99.69, altitudeM: 10000, verticalRateMps: 0,
origin: JFK, destination: SFO,
}), false);
});
test('vertical trend: low climbing plane near SFO — origin must be local', () => {
const nearSfo = { latDeg: 37.7, lonDeg: -122.4, altitudeM: 2500 };
// JFK→SFO passes geometry (near destination), but a CLIMBING plane here just
+1
View File
@@ -142,6 +142,7 @@ test('the actual native tracked label hides the wrong leg and keeps a healthy ro
const parts = {
queries: { _contactLabel: (_, info) => info.callsign },
icons: { _iconPosition: (id) => drawn.get(id) ?? null },
motion: { _signalLost: () => null },
};
const tracking = createTracking({ flightState, services, parts });
for (const [position, expected] of [
+332
View File
@@ -0,0 +1,332 @@
import test from 'node:test';
import assert from 'node:assert/strict';
import { shipwrecksProxy } from '../../server/providers/shipwrecks.js';
const EMODNET = {
type: 'FeatureCollection',
features: [
{
type: 'Feature',
id: 'heritageshipwrecks.1',
geometry: { type: 'Point', coordinates: [-0.92, 50.74] },
properties: { name: 'HMS/m A1', sink_yr: '1911', country: 'UK' },
},
],
};
const WIKIDATA = {
results: {
bindings: [
{
item: { value: 'http://www.wikidata.org/entity/Q25173' },
itemLabel: { value: 'Titanic' },
coord: { value: 'Point(-49.9469 41.7325)' },
},
],
},
};
/**
* Upstream fake. Each source answers 'ok', 'down' (HTTP 503) or 'malformed'
* (HTTP 200 with a body that is not that source's data); change `state` to
* switch between requests.
*/
function fakeFetch({ wikidataFails = false, emodnetFails = false } = {}) {
const calls = [];
const state = {
emodnet: emodnetFails ? 'down' : 'ok',
wikidata: wikidataFails ? 'down' : 'ok',
};
const fetchImpl = async (url, options) => {
calls.push({ url: String(url), options });
const href = String(url);
const name = href.includes('query.wikidata.org')
? 'wikidata'
: href.includes('ows.emodnet-humanactivities.eu')
? 'emodnet'
: null;
if (!name) return new Response('', { status: 404 });
if (state[name] === 'down') return new Response('', { status: 503 });
if (state[name] === 'malformed') return Response.json({});
return Response.json(name === 'wikidata' ? WIKIDATA : EMODNET);
};
const callsTo = (name) =>
calls.filter(({ url }) =>
url.includes(
name === 'wikidata'
? 'query.wikidata.org'
: 'ows.emodnet-humanactivities',
),
).length;
return { fetchImpl, calls, state, callsTo };
}
const HOUR = 60 * 60 * 1000;
function handlerOf(plugin) {
let handler;
plugin.configureServer({
middlewares: { use: (_path, fn) => (handler = fn) },
});
return handler;
}
function request(handler, { method = 'GET', url = '/' } = {}) {
return new Promise((resolve) => {
const res = {
destroyed: false,
writeHead(status, headers) {
this.status = status;
this.headers = headers;
},
end(body) {
resolve({
status: this.status,
headers: this.headers,
body: JSON.parse(body),
});
},
};
handler(
{ method, url, headers: {}, socket: { remoteAddress: '127.0.0.1' } },
res,
);
});
}
test('serves one cached snapshot from fixed upstreams', async () => {
const { fetchImpl, calls } = fakeFetch();
const handler = handlerOf(shipwrecksProxy({ fetchImpl }));
const first = await request(handler);
assert.equal(first.status, 200);
assert.equal(first.body.records.length, 2);
const a1 = first.body.records.find((record) => record.name === 'HMS/m A1');
assert.equal(a1.year, 1911);
assert.deepEqual(first.body.sources, { emodnet: true, wikidata: true });
for (const { url } of calls)
assert.match(
url,
/^https:\/\/(ows\.emodnet-humanactivities\.eu\/wfs\?|query\.wikidata\.org\/sparql\?)/,
);
const count = calls.length;
await request(handler);
assert.equal(calls.length, count, 'second request is served from cache');
});
test('one failing source still serves the other; both failing is a 502', async () => {
const partial = handlerOf(
shipwrecksProxy({
fetchImpl: fakeFetch({ wikidataFails: true }).fetchImpl,
}),
);
const ok = await request(partial);
assert.equal(ok.status, 200);
assert.deepEqual(ok.body.sources, { emodnet: true, wikidata: false });
const down = handlerOf(
shipwrecksProxy({
fetchImpl: fakeFetch({ wikidataFails: true, emodnetFails: true })
.fetchImpl,
}),
);
assert.equal((await request(down)).status, 502);
});
test('a failed refresh serves the last snapshot as stale', async () => {
let clock = 0;
let fail = false;
const { fetchImpl: good } = fakeFetch();
const { fetchImpl: bad } = fakeFetch({
wikidataFails: true,
emodnetFails: true,
});
const handler = handlerOf(
shipwrecksProxy({
fetchImpl: (...args) => (fail ? bad : good)(...args),
now: () => clock,
}),
);
await request(handler);
fail = true;
clock = 25 * 60 * 60 * 1000;
const stale = await request(handler);
assert.equal(stale.status, 200);
assert.equal(stale.body.stale, true);
assert.equal(stale.headers['X-Data-Stale'], 'true');
});
test('rejects other methods and routes', async () => {
const handler = handlerOf(
shipwrecksProxy({ fetchImpl: fakeFetch().fetchImpl }),
);
assert.equal((await request(handler, { method: 'POST' })).status, 405);
assert.equal((await request(handler, { url: '/x' })).status, 404);
});
test("a refresh that gets nothing usable keeps every source's last good wrecks", async () => {
let clock = 0;
const upstream = fakeFetch();
const handler = handlerOf(
shipwrecksProxy({ fetchImpl: upstream.fetchImpl, now: () => clock }),
);
const first = await request(handler);
assert.equal(first.body.records.length, 2);
// A day later EMODnet is down and Wikidata answers 200 with no results.
upstream.state.emodnet = 'down';
upstream.state.wikidata = 'malformed';
clock = 25 * HOUR;
const later = await request(handler);
assert.equal(later.status, 200);
assert.equal(later.body.records.length, 2, 'no wreck is lost');
assert.deepEqual(later.body.sources, { emodnet: true, wikidata: true });
assert.equal(later.body.stale, true);
assert.equal(later.body.fetchedAt, 0, 'the age of the oldest data served');
});
test('one source failing keeps its own last records while the other refreshes', async () => {
let clock = 0;
const upstream = fakeFetch();
const handler = handlerOf(
shipwrecksProxy({ fetchImpl: upstream.fetchImpl, now: () => clock }),
);
const first = await request(handler);
assert.equal((await request(handler)).body.version, first.body.version);
upstream.state.wikidata = 'down';
clock = 25 * HOUR;
const later = await request(handler);
assert.notEqual(later.body.version, first.body.version, 'new EMODnet data');
assert.equal(later.body.records.length, 2);
assert.deepEqual(later.body.sources, { emodnet: true, wikidata: true });
assert.equal(later.body.stale, true);
assert.equal(upstream.callsTo('emodnet'), 2, 'EMODnet was refreshed');
assert.deepEqual(later.body.ages, { emodnet: 0, wikidata: 25 * HOUR });
assert.equal(later.body.maxAgeMs, 7 * 24 * HOUR);
});
test('a failed source waits before it is asked again', async () => {
let clock = 0;
const upstream = fakeFetch();
const handler = handlerOf(
shipwrecksProxy({ fetchImpl: upstream.fetchImpl, now: () => clock }),
);
await request(handler);
upstream.state.emodnet = 'down';
upstream.state.wikidata = 'down';
clock = 25 * HOUR;
await request(handler);
const asked = upstream.calls.length;
for (let i = 0; i < 10; i += 1) {
clock += 60 * 1000;
const res = await request(handler);
assert.equal(res.status, 200);
assert.equal(res.body.stale, true);
}
assert.equal(upstream.calls.length, asked, 'no upstream call while waiting');
clock = 25 * HOUR + 16 * 60 * 1000;
upstream.state.emodnet = 'ok';
upstream.state.wikidata = 'ok';
const back = await request(handler);
assert.equal(
upstream.calls.length,
asked + 2,
'both are retried after the wait',
);
assert.equal(back.body.stale, undefined);
});
test('with no data yet, failures are retried only after the wait', async () => {
let clock = 0;
const upstream = fakeFetch({ emodnetFails: true, wikidataFails: true });
const handler = handlerOf(
shipwrecksProxy({ fetchImpl: upstream.fetchImpl, now: () => clock }),
);
assert.equal((await request(handler)).status, 502);
const asked = upstream.calls.length;
clock += 5 * 60 * 1000;
assert.equal((await request(handler)).status, 502);
assert.equal(upstream.calls.length, asked);
clock += 11 * 60 * 1000;
assert.equal((await request(handler)).status, 502);
assert.equal(upstream.calls.length, asked * 2);
});
test('a source older than seven days is no longer served', async () => {
let clock = 0;
const upstream = fakeFetch();
const handler = handlerOf(
shipwrecksProxy({ fetchImpl: upstream.fetchImpl, now: () => clock }),
);
await request(handler);
upstream.state.emodnet = 'down';
upstream.state.wikidata = 'down';
clock = 7 * 24 * HOUR;
assert.equal((await request(handler)).status, 200, 'seven days is served');
clock = 7 * 24 * HOUR + 16 * 60 * 1000;
assert.equal((await request(handler)).status, 502, 'older is dropped');
});
test('an upstream body over its cap is a failed source, read only to the cap', async () => {
const MIB = 1024 * 1024;
const chunk = new Uint8Array(MIB).fill(0x20);
let sent = 0;
let cancelled = false;
const endless = () =>
new ReadableStream({
pull(controller) {
sent += chunk.byteLength;
controller.enqueue(chunk);
},
cancel() {
cancelled = true;
},
});
const handler = handlerOf(
shipwrecksProxy({
fetchImpl: async (url) =>
String(url).includes('query.wikidata.org')
? Response.json(WIKIDATA)
: new Response(endless()),
}),
);
const res = await request(handler);
assert.equal(res.status, 200);
assert.deepEqual(res.body.sources, { emodnet: false, wikidata: true });
assert.ok(cancelled, 'the oversized body is cancelled');
assert.ok(sent <= 34 * MIB, `read ${sent / MIB} MiB of a 32 MiB cap`);
});
test('a refresh far smaller than the last good set is refused until it expires', async () => {
let clock = 0;
const many = {
results: {
bindings: Array.from({ length: 10 }, (_, i) => ({
item: { value: `http://www.wikidata.org/entity/Q${100 + i}` },
itemLabel: { value: `Wreck ${i}` },
coord: { value: `Point(${i} 40)` },
})),
},
};
let wikidata = many;
const handler = handlerOf(
shipwrecksProxy({
fetchImpl: async (url) =>
Response.json(
String(url).includes('query.wikidata.org') ? wikidata : EMODNET,
),
now: () => clock,
}),
);
assert.equal((await request(handler)).body.records.length, 11);
wikidata = WIKIDATA;
clock = 25 * HOUR;
const refused = await request(handler);
assert.equal(refused.body.records.length, 11, 'one wreck is not ten');
assert.equal(refused.body.stale, true);
clock = 8 * 24 * HOUR;
const accepted = await request(handler);
assert.equal(
accepted.body.records.length,
2,
'taken once the old set expired',
);
});
+1
View File
@@ -1,5 +1,6 @@
/** Bottom-to-top order of the sprite layers' icon and dot sets. */
export const SPRITE_LAYER_ORDER = Object.freeze([
'shipwrecks',
'cctv',
'firms',
'wildlife-sightings',
+597
View File
@@ -0,0 +1,597 @@
/**
* @module trailContinuity
* @description Where a tracked aircraft's trail lifts the pen.
*
* A trail is a chronological list of fixes `{position, timeMs, nullAltitude,
* breakBefore, drawn}`: reports, and (`drawn`) points where the tracked icon
* was drawn between them. Between two consecutive fixes that are not one path, a new
* segment starts and nothing is drawn between them: no dashes, no arcs.
* Nothing is dropped except the oldest fixes past the layer's point limit.
*
* Two points are not one path when time does not advance, when the gap is
* longer than 48 minutes (a coverage hole or a separate flight), when the
* implied great-circle speed is over 1,500 kt, or when either point has no
* reported altitude. A parked aircraft is the exception: a pair under three
* hours apart within 0.1 nm stays one path.
*
* Civil and military flight tracking share these rules.
*/
import { julianToEpochMs } from '../geo/julian.js';
import {
cross,
distance,
dot,
magnitude,
normalize,
scale,
sub,
toRadians,
} from '../geo/vector.js';
/** @constant {number} A gap longer than this is a coverage hole or a separate flight. */
export const TRAIL_CONTINUITY_MAX_GAP_MS = 48 * 60_000;
/** @constant {number} A pair implying more than this great-circle speed is not one path. */
export const TRAIL_CONTINUITY_MAX_SPEED_KT = 1_500;
/** @constant {number} A parked aircraft may stop reporting this long and stay one path. */
export const TRAIL_STATIONARY_HOLD_MAX_GAP_MS = 3 * 60 * 60_000;
/** @constant {number} How close (nautical miles) two points must be to count as parked. */
export const TRAIL_STATIONARY_HOLD_MAX_DISTANCE_NM = 0.1;
/** @constant {number} The head never joins a body point farther than this from the aircraft. */
export const TRAIL_HEAD_JOIN_MAX_M = 150_000;
const METRES_PER_NM = 1852;
/** @constant {number} Mean Earth radius (m) for great-circle trail distances. */
const EARTH_MEAN_RADIUS_M = 6_371_008.8;
/**
* Whether two consecutive trail points belong to different paths. Time that
* does not advance, a gap over TRAIL_CONTINUITY_MAX_GAP_MS or an implied
* speed over TRAIL_CONTINUITY_MAX_SPEED_KT breaks the line, except for a
* parked aircraft: a pair under three hours apart within 0.1 nm.
* @param {number} deltaMs - Later point's time minus the earlier one's.
* @param {number} distanceM - Great-circle distance between the points.
* @returns {boolean}
*/
export function trailPairBreaks(deltaMs, distanceM) {
if (!(deltaMs > 0) || !Number.isFinite(distanceM)) return true;
const distanceNm = distanceM / METRES_PER_NM;
if (
deltaMs <= TRAIL_STATIONARY_HOLD_MAX_GAP_MS &&
distanceNm <= TRAIL_STATIONARY_HOLD_MAX_DISTANCE_NM
)
return false;
return (
deltaMs > TRAIL_CONTINUITY_MAX_GAP_MS ||
distanceNm / (deltaMs / 3_600_000) > TRAIL_CONTINUITY_MAX_SPEED_KT
);
}
/**
* Whether the head segment may join the last body point to the aircraft:
* within TRAIL_HEAD_JOIN_MAX_M and not broken under `trailPairBreaks`.
* @param {number} deltaMs - Current time minus the body point's time.
* @param {number} distanceM - Distance from the body point to the aircraft.
* @returns {boolean}
*/
export function trailHeadJoins(deltaMs, distanceM) {
return (
distanceM <= TRAIL_HEAD_JOIN_MAX_M && !trailPairBreaks(deltaMs, distanceM)
);
}
/**
* Great-circle distance between two trail positions, in metres.
* @param {{x: number, y: number, z: number}} a
* @param {{x: number, y: number, z: number}} b
* @returns {number}
*/
export function trailDistanceM(a, b) {
const unitA = normalize(a);
const unitB = normalize(b);
const angle = Math.atan2(magnitude(cross(unitA, unitB)), dot(unitA, unitB));
return angle * EARTH_MEAN_RADIUS_M;
}
/**
* Whether the pen lifts between two consecutive fixes.
* @param {object|undefined} prev - Earlier fix, if any.
* @param {object} next - Later fix.
* @returns {boolean}
*/
export function trailFixBreaks(prev, next) {
if (!prev || prev.nullAltitude || next.nullAltitude) return true;
// A recorded point is where the icon was drawn; the speed between it and a
// report it was eased onto is not a flight speed, so only the gap counts.
if (prev.drawn || next.drawn)
return Math.abs(next.timeMs - prev.timeMs) > TRAIL_CONTINUITY_MAX_GAP_MS;
return trailPairBreaks(
next.timeMs - prev.timeMs,
trailDistanceM(prev.position, next.position),
);
}
/**
* Build backfill fixes from chronological waypoints. Every waypoint with a
* position is kept. A waypoint without one (no altitude and no known ground)
* is skipped, and the line still breaks there.
* @param {{position: {x: number, y: number, z: number}|null, timeMs: number, nullAltitude: boolean}[]} waypoints
* @returns {{fixes: object[], breakAfter: boolean}} The fixes, and whether the
* line breaks after the last one because trailing waypoints were skipped.
*/
export function trailBackfillFixes(waypoints) {
const fixes = [];
let skipped = false;
for (const { position, timeMs, nullAltitude } of waypoints) {
if (!position) {
skipped = true;
continue;
}
const fix = { position, timeMs, nullAltitude: !!nullAltitude };
fix.breakBefore = skipped || trailFixBreaks(fixes[fixes.length - 1], fix);
skipped = false;
fixes.push(fix);
}
return { fixes, breakAfter: skipped };
}
/**
* Put backfill fixes ahead of the live trail. The join follows the same
* rule, so a distant history tail never connects to the first live fix.
* Past `maxPoints` the oldest recorded points go first, then the oldest
* reports.
* @param {{fixes: object[], breakAfter: boolean}} backfill
* @param {object[]} live - Live fixes; the first one's break is recomputed.
* @param {number} maxPoints - Point limit across all segments.
* @returns {object[]} The joined trail.
*/
export function joinTrailBackfill({ fixes, breakAfter }, live, maxPoints) {
if (!fixes.length) return live;
if (live.length)
live[0].breakBefore =
breakAfter || trailFixBreaks(fixes[fixes.length - 1], live[0]);
return keepTrailLimit(fixes.concat(live), maxPoints);
}
/**
* How many fixes the drawn body holds: every fix at or before the display
* time, where the aircraft is drawn. Fixes ahead of it (reports newer than
* the delayed display) are reached by the head segment instead, so the trail
* never runs past the aircraft, and once the display passes the newest
* report the body ends there.
* @param {object[]} fixes
* @param {number} displayMs - Time the aircraft is drawn at.
* @returns {number}
*/
export function trailBodyCount(fixes, displayMs) {
let count = fixes.length;
while (count > 0 && fixes[count - 1].timeMs > displayMs) count -= 1;
return count;
}
/**
* Leave out the newest recorded points that lie inside the aircraft's 3D
* model, so the body never runs through the fuselage; the head then runs
* from the newest point outside the model to the plane. Reports are kept.
* @param {object[]} fixes
* @param {number} count - From `trailBodyCount`.
* @param {{x: number, y: number, z: number}|null} modelCenter - The model's centre, or null
* when no model is the visual.
* @param {number|null} envelopeM - The model's radius (m).
* @returns {number}
*/
export function trailBodyCountOutsideModel(
fixes,
count,
modelCenter,
envelopeM,
) {
if (!modelCenter || !(envelopeM > 0)) return count;
while (
count > 0 &&
fixes[count - 1].drawn &&
distance(fixes[count - 1].position, modelCenter) < envelopeM
)
count -= 1;
return count;
}
/**
* The drawn trail body, split at breaks: the first `count` fixes.
* @param {object[]} fixes
* @param {number} count - From `trailBodyCount`.
* @returns {{x: number, y: number, z: number}[][]}
*/
export function trailBodySegments(fixes, count) {
const segments = [];
for (let i = 0; i < count; i++) {
const fix = fixes[i];
// A live report with no altitude keeps no position; it only breaks the line.
if (!fix.position) continue;
if (fix.breakBefore || !segments.length) segments.push([]);
segments[segments.length - 1].push(fix.position);
}
return segments;
}
/**
* Draw body segments. A trail without breaks support draws only the newest
* segment, never a line across a break.
* @param {{setSegments?: Function, setPositions: Function}} trail
* @param {{x: number, y: number, z: number}[][]} segments
*/
export function drawTrailSegments(trail, segments) {
if (typeof trail.setSegments === 'function') trail.setSegments(segments);
else trail.setPositions(segments[segments.length - 1] ?? []);
}
/** @constant {number} A head shorter than this (m) is not drawn: the aircraft is holding at its last report. */
const TRAIL_HEAD_MIN_M = 0.5;
/**
* The body fix the head segment starts from, or null when the head is not
* drawn: no body yet, the aircraft holding at that fix, a body point more
* than 150 km from the aircraft, or one too long ago or too far away to be
* one path.
* @param {object[]} fixes
* @param {{x: number, y: number, z: number}} head - Displayed aircraft position.
* @param {number} nowMs - Current time.
* @param {number} count - Body fixes, from `trailBodyCount`.
* @returns {object|null}
*/
export function trailHeadStartFix(fixes, head, nowMs, count) {
if (count < 1 || !head) return null;
const last = fixes[count - 1];
if (!last.position) return null;
if (distance(last.position, head) < TRAIL_HEAD_MIN_M) return null;
return trailHeadJoins(
nowMs - last.timeMs,
trailDistanceM(last.position, head),
)
? last
: null;
}
/**
* Epoch ms of a position-history fix (`{epochMs?, time}`).
* @param {object|undefined} fix
* @returns {number} NaN when unknown.
*/
export function historyFixEpochMs(fix) {
if (Number.isFinite(fix?.epochMs)) return fix.epochMs;
return fix?.time ? julianToEpochMs(fix.time) : NaN;
}
/** @constant {number} The tracked icon's drawn position is recorded at least this often (ms of display time)... */
export const TRAIL_RECORD_STEP_MS = 1_000;
/** @constant {number} ...or whenever it has moved this far (m), whichever comes first. */
export const TRAIL_RECORD_STEP_M = 150;
/** @constant {number} A recorded point is kept only where dropping it would move the line by more than this (m) across the track or in height. */
export const TRAIL_THIN_TOLERANCE_M = 30;
/** @constant {number} A recorded point is kept where dropping it would leave a straight piece longer than this (m), so a long leg still has vertices. */
export const TRAIL_THIN_MAX_SPAN_M = 10_000;
/** @constant {number} A kept point stands in for at most this many dropped positions; past it the point is kept. */
const TRAIL_THIN_MAX_ABSORBED = 512;
/** @constant {number} A recorded point is dropped where the line turns back sharper than this (degrees)... */
export const TRAIL_SPUR_TURN_DEG = 120;
/** @constant {number} ...over a step shorter than this (m). */
export const TRAIL_SPUR_MAX_STEP_M = 500;
/** @constant {number} A recorded point closer than this (m) to the previous one is not kept: the aircraft is holding. */
const TRAIL_RECORD_MIN_STEP_M = 1;
/** Cosine of the turn at `b` on the way a → b → c, or NaN for a zero step. */
function turnCos(a, b, c) {
const u = sub(b, a);
const v = sub(c, b);
const lu = magnitude(u);
const lv = magnitude(v);
if (!(lu > 0 && lv > 0)) return NaN;
return dot(u, v) / (lu * lv);
}
const SPUR_COS = Math.cos(toRadians(TRAIL_SPUR_TURN_DEG));
/** Whether entry `i` and its neighbours are one drawn piece of line. */
function joinedAt(fixes, i) {
const a = fixes[i - 1];
const b = fixes[i];
const c = fixes[i + 1];
return (
a?.position &&
b?.position &&
c?.position &&
!b.breakBefore &&
!c.breakBefore
);
}
/** Whether the line turns back on itself at entry `i` over a short step. */
function spurAt(fixes, i) {
if (!joinedAt(fixes, i)) return false;
const a = fixes[i - 1].position;
const b = fixes[i].position;
const c = fixes[i + 1].position;
if (Math.min(distance(a, b), distance(b, c)) > TRAIL_SPUR_MAX_STEP_M)
return false;
return turnCos(a, b, c) < SPUR_COS;
}
/** Remove entry `i` and re-judge the break before the entry that takes its place. */
function removeAt(fixes, i) {
fixes.splice(i, 1);
if (i < fixes.length)
fixes[i].breakBefore = trailFixBreaks(fixes[i - 1], fixes[i]);
}
/**
* Keep the point limit: drop the oldest recorded point first, and the oldest
* report only when no recorded point is left.
* @param {object[]} fixes - The trail, mutated.
* @param {number} maxPoints
* @returns {object[]} `fixes`.
*/
function keepTrailLimit(fixes, maxPoints) {
let excess = fixes.length - maxPoints;
if (excess <= 0) return fixes;
for (let i = 0; i < fixes.length && excess > 0;) {
if (fixes[i].drawn) {
removeAt(fixes, i);
excess -= 1;
} else i += 1;
}
if (excess > 0) fixes.splice(0, excess);
return fixes;
}
/** Whether `p` lies within the thinning tolerance of segment a → b, across the track and in height. */
function nearSegment(p, a, b) {
const ab = sub(b, a);
const ap = sub(p, a);
const len2 = dot(ab, ab);
const t = len2 > 0 ? Math.max(0, Math.min(1, dot(ap, ab) / len2)) : 0;
const off = sub(ap, scale(ab, t));
const vertical = dot(off, normalize(p));
const across = Math.sqrt(Math.max(0, dot(off, off) - vertical * vertical));
return (
Math.abs(vertical) <= TRAIL_THIN_TOLERANCE_M &&
across <= TRAIL_THIN_TOLERANCE_M
);
}
/**
* Drop recorded point `i` when the line without it stays within the
* tolerance of every position it stood for, and the straight piece left is
* no longer than TRAIL_THIN_MAX_SPAN_M. The positions it stood for go on to
* the next entry. Reports are never dropped.
* @returns {boolean} Whether it was dropped.
*/
function thinAt(fixes, i) {
const entry = fixes[i];
if (!entry?.drawn || entry.sealed || !joinedAt(fixes, i)) return false;
const a = fixes[i - 1].position;
const next = fixes[i + 1];
if (next.sealed) return false;
const b = next.position;
if (distance(a, b) > TRAIL_THIN_MAX_SPAN_M) return false;
const stood = entry.absorbed ?? [];
const nextStood = next.absorbed ?? [];
if (stood.length + nextStood.length + 1 > TRAIL_THIN_MAX_ABSORBED)
return false;
if (!nearSegment(entry.position, a, b)) return false;
for (const p of stood) if (!nearSegment(p.position, a, b)) return false;
for (const p of nextStood) if (!nearSegment(p.position, a, b)) return false;
next.absorbed = stood.concat(
[{ position: entry.position, timeMs: entry.timeMs }],
nextStood,
);
removeAt(fixes, i);
return true;
}
/**
* Thin the recorded points either side of entry `i`, reaching past a
* neighbouring report: the point recorded just before a report is only
* judged once the line goes on beyond it.
*/
function thinAround(fixes, i) {
if (!thinAt(fixes, i + 1) && fixes[i + 1] && !fixes[i + 1].drawn)
thinAt(fixes, i + 2);
if (thinAt(fixes, i - 1)) i -= 1;
else if (fixes[i - 1] && !fixes[i - 1].drawn) thinAt(fixes, i - 2);
}
/**
* Drop recorded points that make a spur next to entry `i`. Reports are never
* dropped; at a report the recorded neighbour is dropped instead.
* @returns {number} The index entry `i` ends up at.
*/
function removeSpursAround(fixes, i) {
for (let guard = 0; guard < 64; guard++) {
let changed = false;
for (const j of [i - 1, i, i + 1]) {
if (!spurAt(fixes, j)) continue;
let drop = -1;
if (fixes[j].drawn) drop = j;
else if (fixes[j + 1]?.drawn) drop = j + 1;
else if (fixes[j - 1]?.drawn) drop = j - 1;
if (drop < 0) continue;
removeAt(fixes, drop);
if (drop < i) i -= 1;
changed = true;
break;
}
if (!changed) break;
}
return i;
}
/** Index a fix at `timeMs` goes in at: after every entry at or before it. */
function insertionIndex(fixes, timeMs) {
let i = fixes.length;
while (i > 0 && fixes[i - 1].timeMs > timeMs) i -= 1;
return i;
}
/**
* Insert an entry at `i`, judge both breaks, remove spurs, thin the recorded
* points either side and keep the limit.
*/
function insertAt(fixes, i, entry, maxPoints) {
fixes.splice(i, 0, entry);
entry.breakBefore = trailFixBreaks(fixes[i - 1], entry);
const after = fixes[i + 1];
if (after) {
after.breakBefore = trailFixBreaks(entry, after);
// Positions the next entry stood for that come before this one are now
// on this entry's side.
if (after.absorbed?.length) {
const mine = after.absorbed.filter((p) => p.timeMs < entry.timeMs);
if (mine.length) {
entry.absorbed = mine;
after.absorbed = after.absorbed.filter((p) => p.timeMs >= entry.timeMs);
}
}
}
i = removeSpursAround(fixes, i);
thinAround(fixes, i);
keepTrailLimit(fixes, maxPoints);
}
/** Index of the newest report before entry `i`, or -1. */
function reportBefore(fixes, i) {
let j = i - 1;
while (j >= 0 && fixes[j].drawn) j -= 1;
return j;
}
/** Index of the oldest report at or after `i`, or `fixes.length`. */
function reportFrom(fixes, i) {
let j = i;
while (j < fixes.length && fixes[j].drawn) j += 1;
return j;
}
/**
* Put a report into the trail in time order. Reports are the record: they
* are kept as anchors among the recorded points.
*
* - A report the display has already passed replaces the guess drawn after
* it: the recorded points timed after it go, and nothing is recorded until
* the icon has eased onto the correction (`displayMs` + `settleMs`), so the
* line reads arc, report, corrected path.
* - Recorded points never join two reports that break under
* `trailPairBreaks` (too long or too fast apart to be one flight): the
* points between them go and the line breaks.
* - A live report with no altitude keeps no position and only breaks the
* line.
* @param {object[]} fixes - The trail, mutated.
* @param {{x: number, y: number, z: number}} position - Owned position.
* @param {number} timeMs - The report's epoch ms.
* @param {number} maxPoints - Point limit across all segments.
* @param {{nullAltitude?: boolean, displayMs?: number, settleMs?: number}} [options]
* `displayMs`: the time the aircraft is drawn at as the report arrives;
* `settleMs`: how long the icon takes to ease onto a correction.
* @returns {object[]} `fixes`.
*/
export function insertTrailFix(
fixes,
position,
timeMs,
maxPoints,
{ nullAltitude = false, displayMs = NaN, settleMs = 0 } = {},
) {
const entry = {
position: nullAltitude ? null : position,
timeMs,
nullAltitude,
drawn: false,
breakBefore: false,
};
let i = insertionIndex(fixes, timeMs);
// The guess drawn after a report the display already passed.
fixes.splice(i, reportFrom(fixes, i) - i);
if (displayMs > timeMs) entry.settleUntilMs = displayMs + settleMs;
// Recorded points across a pair of reports that are not one flight.
const before = reportBefore(fixes, i);
if (before >= 0 && trailFixBreaks(fixes[before], entry)) {
fixes.splice(before + 1, i - before - 1);
i = before + 1;
}
insertAt(fixes, i, entry, maxPoints);
return fixes;
}
/**
* Record where the tracked aircraft was drawn at a display time. Between
* reports this recorded path is the trail, so the line follows every turn
* the icon made instead of a straight chord between two reports. Points are
* thinned by shape: one stays only where dropping it would move the line by
* more than TRAIL_THIN_TOLERANCE_M across the track or in height, or leave a
* straight piece longer than TRAIL_THIN_MAX_SPAN_M. Nothing is recorded
* while the aircraft holds.
* @param {object[]} fixes - The trail, mutated.
* @param {{x: number, y: number, z: number}} position - Owned drawn position.
* @param {number} timeMs - Display time it was drawn for.
* @param {number} maxPoints - Point limit across all segments.
* @returns {boolean} Whether the trail changed.
*/
export function recordTrailPoint(fixes, position, timeMs, maxPoints) {
const i = insertionIndex(fixes, timeMs);
const prev = fixes[i - 1];
if (
prev?.position &&
distance(prev.position, position) < TRAIL_RECORD_MIN_STEP_M
)
return false;
const entry = {
position,
timeMs,
nullAltitude: false,
drawn: true,
breakBefore: false,
};
insertAt(fixes, i, entry, maxPoints);
// Entries before the second report behind this point can never be thinned
// again, so they let go of the positions they stood for.
const passed = reportBefore(fixes, fixes.lastIndexOf(entry));
if (passed >= 0) sealThrough(fixes, reportBefore(fixes, passed));
return true;
}
/** Release the absorbed positions of entry `i` and everything before it. */
function sealThrough(fixes, i) {
for (let j = i; j >= 0 && !fixes[j].sealed; j--) {
fixes[j].sealed = true;
delete fixes[j].absorbed;
}
}
/**
* Whether the icon's drawn position must not be recorded at a display time:
* a report on either side of it has no altitude (the icon is drawn at an
* invented height), the reports on either side are not one flight
* (`trailPairBreaks`), or the icon is still easing onto a report that
* arrived after the display had passed it.
* @param {object[]} fixes
* @param {number} displayMs
* @returns {boolean}
*/
export function trailRecordingBlocked(fixes, displayMs) {
const i = insertionIndex(fixes, displayMs);
const before = fixes[reportBefore(fixes, i)];
const after = fixes[reportFrom(fixes, i)];
if (before?.nullAltitude || after?.nullAltitude) return true;
if (before?.settleUntilMs > displayMs) return true;
return !!(before && after && trailFixBreaks(before, after));
}
+139 -16
View File
@@ -15,6 +15,16 @@
* The history changes at poll cadence (~15-60 s) plus once on backfill; the
* head may change every frame. Either is rebuilt alone, under the same pick
* id, without rebuilding the other.
*
* A history with breaks (`setSegments`) draws each segment separately and
* nothing between them. Every segment is cut into lines of up to
* CHUNK_POINTS points; adjacent lines share their boundary point, so the
* trail has no seam. A line is identified by its position objects, so it is
* never rewritten by an update that keeps those points: appends, a backfill
* prepended ahead of it, or the oldest points dropping off the front (which
* rewrites only the first line). Only the newest line of the newest segment
* changes as the trail grows, and the draw port lets lines that stop
* changing settle into static geometry.
*/
import { cssColor } from '../render/color.js';
import { findDraw } from '../render/rendererOf.js';
@@ -43,6 +53,8 @@ const HEAD_ALPHA = 0.9;
const HEAD_OCCLUDED_ALPHA = 0.45;
/** @constant {number} Squared distance (m^2) below which consecutive points are merged. */
const MIN_SEGMENT_DISTANCE_SQ = 0.01;
/** @constant {number} Points per history line; adjacent lines share one point. */
export const CHUNK_POINTS = 128;
/** `css` (any CSS colour) at `alpha`, as a renderer colour. */
function colorAt(css, alpha) {
@@ -69,14 +81,38 @@ function trailPositions(given) {
return positions.length >= 2 ? positions : [];
}
/** `trailPositions`, keeping the given position objects (a line's identity). */
function keptPositions(given) {
const positions = [];
for (const position of Array.isArray(given) ? given : []) {
if (!position) continue;
const last = positions[positions.length - 1];
if (last && distanceSq(last, position) < MIN_SEGMENT_DISTANCE_SQ) continue;
positions.push(position);
}
return positions.length >= 2 ? positions : [];
}
const plain = ({ x, y, z }) => ({ x, y, z });
/** Whether `chunk` holds exactly the same position objects as `seg` from `start`. */
function sameRun(chunk, seg, start) {
const positions = chunk.positions;
if (start + positions.length > seg.length) return false;
for (let k = 0; k < positions.length; k++)
if (positions[k] !== seg[start + k]) return false;
return true;
}
/**
* Create an always-visible polyline trail bound to a viewer.
* @param {object} viewer - Viewer whose renderer draws the trail.
* @param {object} options - Trail options.
* @param {string} options.color - CSS colour of the trail.
* @param {number} [options.width=2.5] - Line width in pixels.
* @returns {{setPositions: function(Array<{x: number, y: number, z: number}>): void, setHead: function(Array<{x: number, y: number, z: number}>|null): void, setVisible: function(boolean): void, clear: function(): void, destroy: function(): void}}
* Trail handle: setPositions replaces the history, setHead the live head
* @returns {{setPositions: function(Array<{x: number, y: number, z: number}>): void, setSegments: function(Array<Array<{x: number, y: number, z: number}>>): void, setHead: function(Array<{x: number, y: number, z: number}>|null): void, setVisible: function(boolean): void, clear: function(): void, destroy: function(): void}}
* Trail handle: setPositions replaces the history with one line,
* setSegments with one per segment, setHead the live head
* (null or fewer than 2 positions: none), setVisible temporarily hides
* both without discarding them, clear empties both, and destroy removes
* the trail permanently.
@@ -93,6 +129,10 @@ export function createTrail(viewer, { color, width = 2.5 }) {
const drawn = new Map();
/** The head given while the trail is hidden, drawn once it shows. */
let pendingHead = null;
/** History lines before the newest one, oldest first: each line's id and
* the position objects it was drawn from, which never change. */
let chunks = [];
let chunkSeq = 0;
function ensureSet() {
if (set || destroyed || !viewer || viewer.isDestroyed?.()) return set;
@@ -118,7 +158,13 @@ export function createTrail(viewer, { color, width = 2.5 }) {
lines.upsert([hidden]);
return;
}
const item = {
const item = lineItem(id, positions, alpha, occludedAlpha, mode);
drawn.set(id, { key, item });
lines.upsert([item]);
}
function lineItem(id, positions, alpha, occludedAlpha, mode = 'geodesic') {
return {
id,
positions,
widthPx: width,
@@ -128,8 +174,77 @@ export function createTrail(viewer, { color, width = 2.5 }) {
// mesh renders dimmed — it must never disappear into the ground.
depthFail: { kind: 'solid', color: colorAt(color, occludedAlpha) },
};
drawn.set(id, { key, item });
lines.upsert([item]);
}
/**
* Cut the history's segments into lines, keeping every line whose points
* are still drawn in the same order. New lines end where a kept one
* begins, so dropping the oldest point rewrites only the first line. The
* newest line of the newest segment is the body line, the one that grows.
* @param {Array<Array<{x: number, y: number, z: number}>>} list
*/
function setSegments(list) {
if (destroyed || !viewer || viewer.isDestroyed?.()) return;
const lines = ensureSet();
if (!lines) return;
const segments = (Array.isArray(list) ? list : [])
.map(keptPositions)
.filter((positions) => positions.length >= 2);
const byStart = new Map();
for (const chunk of chunks) byStart.set(chunk.positions[0], chunk);
const kept = new Set();
const reusable = (seg, j) => {
const chunk = byStart.get(seg[j]);
return chunk && !kept.has(chunk) && sameRun(chunk, seg, j) ? chunk : null;
};
const next = [];
const added = [];
let tail = [];
segments.forEach((seg, s) => {
const newest = s === segments.length - 1;
let i = 0;
while (i < seg.length - 1) {
const existing = reusable(seg, i);
if (existing) {
kept.add(existing);
next.push(existing);
i += existing.positions.length - 1;
continue;
}
if (newest && seg.length - i <= CHUNK_POINTS) {
tail = seg.slice(i);
break;
}
let end = Math.min(seg.length - 1, i + CHUNK_POINTS - 1);
for (let j = i + 1; j < end; j++) {
if (reusable(seg, j)) {
end = j;
break;
}
}
const positions = seg.slice(i, end + 1);
const chunk = { id: `${bodyId}:${++chunkSeq}`, positions };
next.push(chunk);
added.push(
lineItem(
chunk.id,
positions.map(plain),
TRAIL_ALPHA,
TRAIL_OCCLUDED_ALPHA,
),
);
i = end;
}
});
const gone = chunks.filter((chunk) => !kept.has(chunk));
chunks = next;
if (gone.length) lines.remove(gone.map((chunk) => chunk.id));
if (added.length) lines.upsert(added);
// Round 8 (owner: UAL1104's Pacific trail "cutting through the
// globe"): straight 3D chords between sparse trans-oceanic
// waypoints tunnel through the planet; a geodesic line follows the
// curved surface (heights interpolated) instead.
draw(bodyId, tail.map(plain), TRAIL_ALPHA, TRAIL_OCCLUDED_ALPHA);
}
/**
@@ -163,18 +278,19 @@ export function createTrail(viewer, { color, width = 2.5 }) {
* ECEF positions, oldest -> newest.
*/
setPositions(cartesians) {
// Round 8 (owner: UAL1104's Pacific trail "cutting through the
// globe"): straight 3D chords between sparse trans-oceanic
// waypoints tunnel through the planet; a geodesic line follows the
// curved surface (heights interpolated) instead.
draw(
bodyId,
trailPositions(cartesians),
TRAIL_ALPHA,
TRAIL_OCCLUDED_ALPHA,
);
setSegments([cartesians]);
},
/**
* Replace the trail geometry with chronological segments (oldest
* first), nothing drawn between them. A segment with fewer than 2
* distinct positions draws nothing. Pass the same position objects on
* every update: a line whose points are unchanged is never rewritten.
* @param {Array<Array<{x: number, y: number, z: number}>>} list
* Segments, each oldest -> newest.
*/
setSegments,
setHead,
/** Temporarily hide/show the trail without discarding accumulated history. */
@@ -187,8 +303,14 @@ export function createTrail(viewer, { color, width = 2.5 }) {
/** Empty the trail, keeping its set (cheap re-arm). */
clear() {
pendingHead = null;
if (!destroyed && set && !viewer?.isDestroyed?.() && drawn.size) {
if (
!destroyed &&
set &&
!viewer?.isDestroyed?.() &&
(drawn.size || chunks.length)
) {
drawn.clear();
chunks = [];
set.clear();
}
},
@@ -203,6 +325,7 @@ export function createTrail(viewer, { color, width = 2.5 }) {
}
set = null;
drawn.clear();
chunks = [];
},
};
}
+78 -1
View File
@@ -1,7 +1,7 @@
import test from 'node:test';
import assert from 'node:assert/strict';
import { bindFakeDraw } from '../testSupport/fakeDrawPort.mjs';
import { createTrail } from './trailRenderer.js';
import { CHUNK_POINTS, createTrail } from './trailRenderer.js';
import { findPickOwner } from './pickRegistry.js';
function viewerWithDraw(t) {
@@ -152,3 +152,80 @@ test('a viewer with nothing to draw with draws no trail', () => {
);
trail.destroy();
});
const points = (n, from = 0) =>
Array.from({ length: n }, (_, i) => ({ x: (from + i) * 10, y: 0, z: 0 }));
/** The set's history lines (the head left out), oldest first. */
const historyLines = (set) =>
[...set.items.values()]
.filter((line) => !line.id.endsWith(':head') && line.show !== false)
.sort((a, b) => a.positions[0].x - b.positions[0].x);
test('a trail with breaks draws each segment and nothing between them', (t) => {
const { viewer, draw } = viewerWithDraw(t);
const trail = createTrail(viewer, { color: '#00d4ff' });
trail.setSegments([points(3), points(1, 50), points(4, 100)]);
const lines = historyLines(draw.find('trail:'));
assert.deepEqual(
lines.map((line) => line.positions.map((p) => p.x)),
[
[0, 10, 20],
[1000, 1010, 1020, 1030],
],
'a one-point segment draws nothing, and no line joins the others',
);
});
test('long segments are cut into lines that share their boundary points', (t) => {
const { viewer, draw } = viewerWithDraw(t);
const trail = createTrail(viewer, { color: '#00d4ff' });
const seg = points(CHUNK_POINTS * 2 + 10);
trail.setSegments([seg]);
const lines = historyLines(draw.find('trail:'));
assert.equal(lines.length, 3);
for (let i = 1; i < lines.length; i++)
assert.deepEqual(lines[i].positions[0], lines[i - 1].positions.at(-1));
assert.equal(
lines.reduce((sum, line) => sum + line.positions.length - 1, 0),
seg.length - 1,
'every point drawn once, past the shared ones',
);
});
test('an update that keeps a line’s points never rewrites it', (t) => {
const { viewer, draw } = viewerWithDraw(t);
const trail = createTrail(viewer, { color: '#00d4ff' });
const seg = points(CHUNK_POINTS * 2 + 10);
trail.setSegments([seg]);
const set = draw.find('trail:');
const [first, second] = historyLines(set);
// Appending only moves the newest line on.
trail.setSegments([[...seg, ...points(5, seg.length)]]);
let lines = historyLines(set);
assert.equal(lines[0], first);
assert.equal(lines[1], second);
// A backfill prepended ahead keeps them, joining at a shared point.
const older = points(20, -20);
trail.setSegments([[...older, ...seg]]);
lines = historyLines(set);
assert.ok(lines.includes(first) && lines.includes(second));
assert.deepEqual(lines[0].positions.at(-1), first.positions[0]);
// Dropping the oldest point rewrites only the first line.
trail.setSegments([seg.slice(1)]);
lines = historyLines(set);
assert.notEqual(lines[0], first);
assert.equal(lines[1], second);
assert.deepEqual(lines[0].positions.at(-1), second.positions[0]);
});
test('clearing a segmented trail lets every line go', (t) => {
const { viewer, draw } = viewerWithDraw(t);
const trail = createTrail(viewer, { color: '#00d4ff' });
trail.setSegments([points(CHUNK_POINTS * 3)]);
const set = draw.find('trail:');
trail.clear();
assert.equal(set.items.size, 0);
trail.setSegments([points(4)]);
assert.equal(historyLines(set).length, 1, 'drawn again after a clear');
});
+165
View File
@@ -0,0 +1,165 @@
import test from 'node:test';
import assert from 'node:assert/strict';
import * as Cesium from 'cesium';
import {
insertTrailFix,
recordTrailPoint,
trailBodySegments,
trailPairBreaks,
trailDistanceM,
trailRecordingBlocked,
} from './trailContinuity.js';
// Reports decide where the line may run: recorded points never join two
// reports too far apart to be one flight, a report the display has already
// passed replaces the guess drawn after it, and old entries let go of the
// positions they stood for.
const SEC = 1000;
const LIMIT = 2_000;
const enu = Cesium.Transforms.eastNorthUpToFixedFrame(
Cesium.Cartesian3.fromDegrees(-100, 40, 0),
);
const at = (e, n, u = 10) =>
Cesium.Matrix4.multiplyByPoint(
enu,
new Cesium.Cartesian3(e, n, u),
new Cesium.Cartesian3(),
);
/** No two neighbours in one drawn segment are too far apart to be one flight. */
function assertNoBrokenJoin(fixes) {
const reports = fixes.filter((fix) => !fix.drawn && fix.position);
for (const segment of trailBodySegments(fixes, fixes.length)) {
const inSegment = reports.filter((r) =>
segment.some((p) => Cesium.Cartesian3.distance(p, r.position) < 0.01),
);
for (let i = 1; i < inSegment.length; i++)
assert.equal(
trailPairBreaks(
inSegment[i].timeMs - inSegment[i - 1].timeMs,
trailDistanceM(inSegment[i - 1].position, inSegment[i].position),
),
false,
`one segment joins reports at ${inSegment[i - 1].timeMs / SEC} s and ${
inSegment[i].timeMs / SEC
} s`,
);
}
}
test('two reports 60 s and 51 km apart are not joined, even by recorded points', () => {
const A = Cesium.Cartesian3.fromDegrees(-100, 40, 9_000);
const B = Cesium.Cartesian3.fromDegrees(-99.4, 40, 9_000);
const fixes = [];
insertTrailFix(fixes, A, 0, LIMIT);
insertTrailFix(fixes, B, 60 * SEC, LIMIT); // ahead of the display
for (let t = 1; t < 60; t++) {
// Nothing is recorded across the pair.
assert.equal(trailRecordingBlocked(fixes, t * SEC), true);
}
assert.equal(trailBodySegments(fixes, fixes.length).length, 2);
// Points recorded before the far report was known are dropped.
const late = [];
insertTrailFix(late, A, 0, LIMIT);
for (let t = 1; t < 60; t++)
recordTrailPoint(
late,
Cesium.Cartesian3.lerp(A, B, t / 60, new Cesium.Cartesian3()),
t * SEC,
LIMIT,
);
insertTrailFix(late, B, 60 * SEC, LIMIT);
assert.equal(late.filter((fix) => fix.drawn).length, 0);
assert.equal(trailBodySegments(late, late.length).length, 2);
assertNoBrokenJoin(late);
});
test('a coast, a hold and then a far report: nothing is drawn across', () => {
const A = at(0, 0, 9_000);
const fixes = [];
insertTrailFix(fixes, A, 0, LIMIT);
// The icon coasts east for 90 s at 230 m/s, then holds.
for (let t = 1; t <= 200; t++)
recordTrailPoint(
fixes,
at(230 * Math.min(t, 90), 0, 9_000),
t * SEC,
LIMIT,
);
assert.ok(fixes.filter((fix) => fix.drawn).length > 0);
// The next report is 150 km away two minutes later: over 1,500 kt.
const B = at(0, 150_000, 9_000);
insertTrailFix(fixes, B, 120 * SEC, LIMIT);
assertNoBrokenJoin(fixes);
const segments = trailBodySegments(fixes, fixes.length);
const segmentOf = (p) =>
segments.findIndex((s) =>
s.some((q) => Cesium.Cartesian3.distance(p, q) < 0.01),
);
assert.notEqual(segmentOf(A), segmentOf(B));
// No recorded point between the two reports remains.
assert.equal(
fixes.filter((fix) => fix.drawn && fix.timeMs < 120 * SEC).length,
0,
);
});
for (const off of [200, 400, 600, 1_000]) {
test(`a report the display already passed, ${off} m off a 2 km turn, leaves no spike`, () => {
const R = 2_000;
const w = 100 / R;
const pos = (t, r = R) =>
at(r * Math.sin(w * t), R - r * Math.cos(w * t), 3_000);
const fixes = [];
insertTrailFix(fixes, pos(0), 0, LIMIT);
for (let t = 1; t <= 60; t++)
recordTrailPoint(fixes, pos(t), t * SEC, LIMIT);
const report = pos(50, R - off);
// It arrives with the display at 60 s; the ease takes 900 ms.
insertTrailFix(fixes, report, 50 * SEC, LIMIT, {
displayMs: 60 * SEC,
settleMs: 900,
});
// The guess drawn after the report is gone...
assert.deepEqual(
fixes.filter((fix) => fix.drawn && fix.timeMs > 50 * SEC),
[],
);
// ...nothing is recorded while the icon eases onto the correction...
assert.equal(trailRecordingBlocked(fixes, 60.5 * SEC), true);
assert.equal(trailRecordingBlocked(fixes, 61 * SEC), false);
// ...and the line reads arc, report, corrected path.
for (let t = 61; t <= 70; t++)
recordTrailPoint(fixes, pos(t, R - off), t * SEC, LIMIT);
const line = trailBodySegments(fixes, fixes.length).flat();
const r = line.findIndex(
(p) => Cesium.Cartesian3.distance(p, report) < 0.01,
);
assert.ok(r > 0);
for (const p of line.slice(0, r))
assert.ok(
Math.abs(Cesium.Cartesian3.distance(p, at(0, R, 3_000)) - R) < 31,
'a point before the report is off the arc',
);
for (const p of line.slice(r + 1))
assert.ok(
Math.abs(Cesium.Cartesian3.distance(p, at(0, R, 3_000)) - (R - off)) <
31,
'a point after the report is off the corrected path',
);
});
}
test('entries behind the report before the display let go of the positions they stood for', () => {
const fixes = [];
for (let s = 0; s <= 2 * 3_600; s++) {
const p = at(230 * s, 0, 10_000);
if (s % 15 === 0) insertTrailFix(fixes, p, s * SEC, LIMIT);
else recordTrailPoint(fixes, p, s * SEC, LIMIT);
}
let held = 0;
for (const fix of fixes) held += fix.absorbed?.length ?? 0;
// Only the newest stretch, up to two reports back, keeps what it stood for.
assert.ok(held <= 30, `${held} positions still held`);
});
+180
View File
@@ -0,0 +1,180 @@
import test from 'node:test';
import assert from 'node:assert/strict';
import * as Cesium from 'cesium';
import {
insertTrailFix,
joinTrailBackfill,
recordTrailPoint,
TRAIL_THIN_MAX_SPAN_M,
TRAIL_THIN_TOLERANCE_M,
} from './trailContinuity.js';
// Recorded points are thinned by shape: a point stays only where the line
// would move without it. Reports always stay.
const SEC = 1000;
const LIMIT = 2_000;
const LAT0 = 40;
const LON0 = -100;
const M_PER_DEG_LAT = 111_320;
const mPerDegLon = (lat) => M_PER_DEG_LAT * Math.cos((lat * Math.PI) / 180);
/** Straight and level east at `speed` m/s, `tSec` after the start. */
const eastbound = (speed, tSec, heightM = 10_000) =>
Cesium.Cartesian3.fromDegrees(
LON0 + (speed * tSec) / mPerDegLon(LAT0),
LAT0,
heightM,
);
/** A standard-rate (3°/s) left turn from north, radius v / ω, `tSec` in. */
function turning(speed, tSec, heightM = 10_000) {
const omega = (3 * Math.PI) / 180;
const radius = speed / omega;
// Centre west of the start; heading north, turning left (towards west).
const angle = omega * tSec;
const east = -radius + radius * Math.cos(angle);
const north = radius * Math.sin(angle);
return Cesium.Cartesian3.fromDegrees(
LON0 + east / mPerDegLon(LAT0),
LAT0 + north / M_PER_DEG_LAT,
heightM,
);
}
/** Distance from p to the nearest point of a polyline. */
function distanceToPath(p, path) {
let best = Infinity;
const ab = new Cesium.Cartesian3();
const ap = new Cesium.Cartesian3();
const closest = new Cesium.Cartesian3();
for (let i = 1; i < path.length; i++) {
Cesium.Cartesian3.subtract(path[i], path[i - 1], ab);
Cesium.Cartesian3.subtract(p, path[i - 1], ap);
const len2 = Cesium.Cartesian3.magnitudeSquared(ab);
const t =
len2 > 0
? Math.max(0, Math.min(1, Cesium.Cartesian3.dot(ap, ab) / len2))
: 0;
Cesium.Cartesian3.add(
path[i - 1],
Cesium.Cartesian3.multiplyByScalar(ab, t, closest),
closest,
);
best = Math.min(best, Cesium.Cartesian3.distance(p, closest));
}
return best;
}
const drawnCount = (fixes) => fixes.filter((fix) => fix.drawn).length;
test('one hour straight and level with a report every 15 s adds under 60 recorded points', () => {
const speed = 230;
const fixes = [];
for (const t of [0, 15, 30])
insertTrailFix(fixes, eastbound(speed, t), t * SEC, LIMIT);
// Live order: a report arrives 30 s before the display reaches it, and the
// drawn icon is recorded once a second.
for (let t = 1; t <= 3_600; t++) {
const reportAt = t + 30;
if (reportAt % 15 === 0 && reportAt <= 3_600)
insertTrailFix(fixes, eastbound(speed, reportAt), reportAt * SEC, LIMIT);
recordTrailPoint(fixes, eastbound(speed, t), t * SEC, LIMIT);
}
assert.ok(
drawnCount(fixes) < 60,
`${drawnCount(fixes)} recorded points kept`,
);
assert.equal(fixes.filter((fix) => !fix.drawn).length, 241);
});
test('with no report at all, a straight leg keeps one point per 10 km and no more', () => {
const speed = 230;
const fixes = [];
insertTrailFix(fixes, eastbound(speed, 0), 0, LIMIT);
for (let t = 1; t <= 3_600; t++)
recordTrailPoint(fixes, eastbound(speed, t), t * SEC, LIMIT);
const legKm = (speed * 3_600) / 1_000;
assert.equal(TRAIL_THIN_MAX_SPAN_M, 10_000);
assert.ok(
drawnCount(fixes) <= Math.ceil(legKm / 10) + 1,
`${drawnCount(fixes)} points over ${legKm} km`,
);
for (let i = 1; i < fixes.length; i++)
assert.ok(
Cesium.Cartesian3.distance(fixes[i - 1].position, fixes[i].position) <=
TRAIL_THIN_MAX_SPAN_M + speed,
);
});
test('a standard-rate 180° turn keeps its curve: every recorded position stays within 30 m of the kept line', () => {
const speed = 230;
const fixes = [];
const recorded = [];
insertTrailFix(fixes, turning(speed, 0), 0, LIMIT);
for (let t = 1; t <= 60; t++) {
const position = turning(speed, t);
recorded.push(position);
recordTrailPoint(fixes, position, t * SEC, LIMIT);
}
const line = fixes.map((fix) => fix.position);
assert.equal(TRAIL_THIN_TOLERANCE_M, 30);
for (const position of recorded) {
const off = distanceToPath(position, line);
assert.ok(off <= TRAIL_THIN_TOLERANCE_M + 1, `${off.toFixed(1)} m off`);
}
assert.ok(drawnCount(fixes) < recorded.length, 'nothing was thinned');
assert.ok(drawnCount(fixes) >= 6, 'the curve was flattened');
});
test('a climb off the straight line keeps its vertices', () => {
const fixes = [];
insertTrailFix(fixes, eastbound(200, 0, 1_000), 0, LIMIT);
// 30 s level, then a 60 s climb of 20 m/s, then level again.
const height = (t) => 1_000 + 20 * Math.min(60, Math.max(0, t - 30));
const recorded = [];
for (let t = 1; t <= 150; t++) {
const position = eastbound(200, t, height(t));
recorded.push(position);
recordTrailPoint(fixes, position, t * SEC, LIMIT);
}
const line = fixes.map((fix) => fix.position);
for (const position of recorded)
assert.ok(distanceToPath(position, line) <= TRAIL_THIN_TOLERANCE_M + 1);
});
test('at the limit, old recorded points go before any report from the backfill', () => {
const max = 300;
const backfill = [];
for (let i = 0; i < 100; i++)
backfill.push({
position: eastbound(200, i * 60 - 20_000),
timeMs: (i * 60 - 20_000) * SEC,
nullAltitude: false,
});
let fixes = [];
insertTrailFix(fixes, turning(150, 0), 0, max);
// A long series of turns keeps many recorded points.
for (let t = 1; t <= 2_000; t++)
recordTrailPoint(fixes, turning(150, t), t * SEC, max);
assert.ok(drawnCount(fixes) > 150);
fixes = joinTrailBackfill(
{
fixes: backfill.map((b) => ({ ...b, breakBefore: false })),
breakAfter: false,
},
fixes,
max,
);
assert.ok(fixes.length <= max);
const reports = fixes.filter((fix) => !fix.drawn);
assert.equal(reports.length, 101, 'a report was dropped');
// More recording at the limit drops recorded points, never reports.
for (let t = 2_001; t <= 2_400; t++)
recordTrailPoint(fixes, turning(150, t), t * SEC, max);
assert.ok(fixes.length <= max);
assert.equal(fixes.filter((fix) => !fix.drawn).length, 101);
// The recorded points that remain are the newest.
const drawnTimes = fixes.filter((fix) => fix.drawn).map((fix) => fix.timeMs);
assert.ok(Math.min(...drawnTimes) > 1_000 * SEC);
});
+83 -24
View File
@@ -41,33 +41,46 @@ const DETAIL =
/**
* Each body is drawn in a centred frame (origin 0,0 = glyph centre), front
* toward -Y, in the 96-unit space (half-extent up to ~45).
*
* Two sets. `HEADING_BODIES` is what a vehicle with a known course wears: every
* outline has a front that cannot be mistaken for its back at fleet size — a
* nose, a bow or a chamfered cab — because at twenty pixels a bus drawn as a
* near-symmetric box gives no hint which way it is going, and a hairline
* windscreen is far below one pixel. The front is part of the OUTLINE, not
* interior ink, so it survives the tint, the halo (which strokes the outline)
* and the sensor profiles (which keep only the outline).
*
* `NEUTRAL_BODIES` is what a vehicle with NO known course wears. Its billboard
* sits at rotation 0, so a pointed glyph would claim it is heading north; these
* outlines are the same footprint, symmetric end to end, and claim nothing.
*/
const BODIES = {
// ── Bus: short, blunt, square-shouldered. The shape everything else reads
// against, and the one most people will see most often.
const HEADING_BODIES = {
// ── Bus: short, broad, square-shouldered behind an arrow-like nose. The
// shape everything else reads against, and the one most people will see
// most often, so it carries the boldest front.
bus: `
<path d="M-17,-28 C-17,-32 -14,-34 0,-34 C14,-34 17,-32 17,-28
L17,28 C17,32 14,34 0,34 C-14,34 -17,32 -17,28 Z"
<path d="M0,-41 L17,-25 L17,28 C17,32 14,34 0,34 C-14,34 -17,32 -17,28
L-17,-25 Z"
fill="white" ${STROKE}/>
<path d="M-11,-24 L11,-24" ${DETAIL}/>
<path d="M-11,-21 L11,-21" ${DETAIL}/>
<path d="M-11,20 L11,20" ${DETAIL}/>`,
// ── Tram / light rail: longer and slimmer than a bus, with the two
// articulation joints that make a modern low-floor tram unmistakable.
// ── Tram / light rail: longer and slimmer than a bus, a short pointed cab
// and the two articulation joints of a modern low-floor tram.
tram: `
<path d="M-10,-38 C-10,-41 -8,-42.5 0,-42.5 C8,-42.5 10,-41 10,-38
L10,38 C10,41 8,42.5 0,42.5 C-8,42.5 -10,41 -10,38 Z"
<path d="M0,-44 L10,-33 L10,38 C10,41 8,42.5 0,42.5 C-8,42.5 -10,41 -10,38
L-10,-33 Z"
fill="white" ${STROKE}/>
<path d="M-10,-13 L10,-13" ${DETAIL}/>
<path d="M-10,13 L10,13" ${DETAIL}/>
<path d="M-8,-34 L8,-34" ${DETAIL}/>`,
<path d="M-8,-29 L8,-29" ${DETAIL}/>`,
// ── Metro / subway: squared off at both ends, wider than a tram, a single
// cab line at the front. Reads as rolling stock, not a road vehicle.
// ── Metro / subway: squared off and wider than a tram, the cab end
// chamfered to a narrow flat face; the rear stays square.
subway: `
<path d="M-11.5,-40 L11.5,-40 L11.5,40 L-11.5,40 Z"
<path d="M-4,-40 L4,-40 L11.5,-30 L11.5,40 L-11.5,40 L-11.5,-30 Z"
fill="white" ${STROKE}/>
<path d="M-11.5,-32 L11.5,-32" ${DETAIL}/>
<path d="M-11.5,-26 L11.5,-26" ${DETAIL}/>
<path d="M-11.5,0 L11.5,0" ${DETAIL}/>
<path d="M-11.5,32 L11.5,32" ${DETAIL}/>`,
@@ -90,8 +103,49 @@ const BODIES = {
fill="white" ${STROKE}/>
<path d="M-7.5,-6 L7.5,-6 L7.5,20 L-7.5,20 Z" ${DETAIL}/>`,
// ── Unknown: a plain rounded marker. Deliberately featureless, so an
// ── Unknown: a plain marker with a nose and nothing else, so an
// unclassified vehicle never pretends to be a mode it is not.
unknown: `
<path d="M0,-38 L10,-24 L10,26 C10,30 7,32 0,32 C-7,32 -10,30 -10,26
L-10,-24 Z"
fill="white" ${STROKE}/>`,
};
const NEUTRAL_BODIES = {
bus: `
<path d="M-17,-28 C-17,-32 -14,-34 0,-34 C14,-34 17,-32 17,-28
L17,28 C17,32 14,34 0,34 C-14,34 -17,32 -17,28 Z"
fill="white" ${STROKE}/>
<path d="M-11,-20 L11,-20" ${DETAIL}/>
<path d="M-11,20 L11,20" ${DETAIL}/>`,
tram: `
<path d="M-10,-38 C-10,-41 -8,-42.5 0,-42.5 C8,-42.5 10,-41 10,-38
L10,38 C10,41 8,42.5 0,42.5 C-8,42.5 -10,41 -10,38 Z"
fill="white" ${STROKE}/>
<path d="M-10,-13 L10,-13" ${DETAIL}/>
<path d="M-10,13 L10,13" ${DETAIL}/>`,
subway: `
<path d="M-11.5,-40 L11.5,-40 L11.5,40 L-11.5,40 Z"
fill="white" ${STROKE}/>
<path d="M-11.5,-32 L11.5,-32" ${DETAIL}/>
<path d="M-11.5,0 L11.5,0" ${DETAIL}/>
<path d="M-11.5,32 L11.5,32" ${DETAIL}/>`,
rail: `
<path d="M-10.5,-40 C-10.5,-43 -8.5,-44.5 0,-44.5 C8.5,-44.5 10.5,-43 10.5,-40
L10.5,40 C10.5,43 8.5,44.5 0,44.5 C-8.5,44.5 -10.5,43 -10.5,40 Z"
fill="white" ${STROKE}/>
<path d="M-10.5,-6 L10.5,-6" ${DETAIL}/>
<path d="M-10.5,6 L10.5,6" ${DETAIL}/>`,
ferry: `
<path d="M-12.5,-30 C-12.5,-36 -8,-38 0,-38 C8,-38 12.5,-36 12.5,-30
L12.5,30 C12.5,36 8,38 0,38 C-8,38 -12.5,36 -12.5,30 Z"
fill="white" ${STROKE}/>
<path d="M-7.5,-13 L7.5,-13 L7.5,13 L-7.5,13 Z" ${DETAIL}/>`,
unknown: `
<path d="M-10,-26 C-10,-30 -7,-32 0,-32 C7,-32 10,-30 10,-26
L10,26 C10,30 7,32 0,32 C-7,32 -10,30 -10,26 Z"
@@ -99,7 +153,7 @@ const BODIES = {
};
/** The modes this module can draw. */
export const TRANSIT_ICON_KINDS = Object.freeze(Object.keys(BODIES));
export const TRANSIT_ICON_KINDS = Object.freeze(Object.keys(HEADING_BODIES));
const _iconCache = new Map();
@@ -155,8 +209,8 @@ export function transitIconCacheSize() {
}
/**
* Data URI for one mode's silhouette, lazily built and cached per kind, size
* and halo.
* Data URI for one mode's silhouette, lazily built and cached per kind, size,
* halo and whether the vehicle has a known course.
*
* With a halo, the body is drawn twice: first as a wide dark stroke, then as
* the shipped white fill with its hairline edge on top, so the ring sits
@@ -166,11 +220,14 @@ export function transitIconCacheSize() {
*
* @param {string} kind One of TRANSIT_ICON_KINDS; anything else draws `unknown`.
* @param {number} [px] Raster size.
* @param {{haloScreenPx?: number, screenPx?: number}} [options]
* @param {{haloScreenPx?: number, screenPx?: number, style?: string,
* heading?: boolean}} [options] `heading: false` draws the symmetric outline
* for a vehicle whose course is unknown (its billboard is not rotated, so a
* front would point north for no reason).
* @returns {string} `data:image/svg+xml;base64,...`
*/
export function transitIcon(kind, px = FLEET_RASTER_PX, options = {}) {
const k = BODIES[kind] ? kind : 'unknown';
const k = HEADING_BODIES[kind] ? kind : 'unknown';
const selected = px > FLEET_RASTER_PX;
px = selected ? SELECTED_ICON_PX : FLEET_RASTER_PX;
const profile = transitStyleProfile(
@@ -185,16 +242,18 @@ export function transitIcon(kind, px = FLEET_RASTER_PX, options = {}) {
profile === 'mono' ? 'thermal' : profile === 'crt' ? 'retro' : 'normal';
const displayPx = (selected ? 30 : 20) * presetSpriteScale(style, selected);
const frame = haloFrame(presetSpriteOutlinePx(style, selected), displayPx);
const key = `${k}:${selected ? 1 : 0}:${profile}`;
const heading = options.heading !== false;
const bodies = heading ? HEADING_BODIES : NEUTRAL_BODIES;
const key = `${k}:${selected ? 1 : 0}:${profile}:${heading ? 'h' : 'n'}`;
let uri = _iconCache.get(key);
if (!uri) {
const size = VIEW + 2 * frame.pad;
// Reuse the exact outer path. Sensors fill its interior without panel ink.
const silhouette = BODIES[k].match(/<path d="([^"]+)"/)[1];
const silhouette = bodies[k].match(/<path d="([^"]+)"/)[1];
const body =
profile === 'mono'
? `<path d="${silhouette}" fill="white" />`
: BODIES[k];
: bodies[k];
const halo =
frame.units > 0
? profile === 'mono'
+128 -64
View File
@@ -62,39 +62,42 @@ test('the raster cache is bounded by kind, size and halo — never by call count
assert.ok(transitIconCacheSize() <= before + 3 + TRANSIT_ICON_KINDS.length);
});
test('all 36 variants retain the specified final halo at both display sizes', async () => {
test('all 72 variants retain the specified final halo at both display sizes', async () => {
const { presetSpriteScale, presetSpriteOutlinePx } =
await import('./transitPresetStyle.js');
for (const kind of TRANSIT_ICON_KINDS) {
for (const selected of [false, true]) {
for (const style of ['normal', 'thermal', 'retro']) {
const display =
(selected ? 30 : 20) * presetSpriteScale(style, selected);
const svg = decode(transitIcon(kind, selected ? 96 : 48, { style }));
const units = Number(
svg.match(/stroke-opacity="(?:0.95|1)" stroke-width="([\d.]+)"/)[1],
);
assert.ok(
Math.abs(
(units * display) / 192 - presetSpriteOutlinePx(style, selected),
) < 0.001,
);
const frame = haloFrame(
presetSpriteOutlinePx(style, selected),
display,
);
assert.match(
svg,
new RegExp(
`width="${Math.round((selected ? 96 : 48) * frame.ratio)}"`,
),
);
}
for (const style of ['normal', 'thermal', 'retro'])
for (const heading of [true, false]) {
const display =
(selected ? 30 : 20) * presetSpriteScale(style, selected);
const svg = decode(
transitIcon(kind, selected ? 96 : 48, { style, heading }),
);
const units = Number(
svg.match(/stroke-opacity="(?:0.95|1)" stroke-width="([\d.]+)"/)[1],
);
assert.ok(
Math.abs(
(units * display) / 192 - presetSpriteOutlinePx(style, selected),
) < 0.001,
);
const frame = haloFrame(
presetSpriteOutlinePx(style, selected),
display,
);
assert.match(
svg,
new RegExp(
`width="${Math.round((selected ? 96 : 48) * frame.ratio)}"`,
),
);
}
}
}
for (let i = 0; i < 100; i++)
transitIcon('invalid', i, { haloScreenPx: i, screenPx: i });
assert.equal(transitIconCacheSize(), 36);
assert.equal(transitIconCacheSize(), 72);
});
test('every mono raster preserves the normal silhouette mask and aspect at CRT display size', async () => {
@@ -133,47 +136,53 @@ test('every mono raster preserves the normal silhouette mask and aspect at CRT d
return { mask, aspect: (maxX - minX + 1) / (maxY - minY + 1) };
};
for (const selected of [false, true])
for (const kind of TRANSIT_ICON_KINDS) {
const normal = await rasterBody(
decode(transitIcon(kind, selected ? 96 : 48, { style: 'normal' })),
);
for (const style of ['surveillance', 'thermal', 'noir', 'nvg']) {
const svg = decode(transitIcon(kind, selected ? 96 : 48, { style }));
const mono = await rasterBody(svg);
assert.deepEqual(
mono.mask,
normal.mask,
`${kind}/${style}: no envelope`,
for (const heading of [true, false])
for (const kind of TRANSIT_ICON_KINDS) {
const normal = await rasterBody(
decode(
transitIcon(kind, selected ? 96 : 48, { style: 'normal', heading }),
),
);
assert.ok(
Math.abs(mono.aspect / normal.aspect - 1) <= 0.05,
`${kind}/${style}: aspect`,
);
const display =
(selected ? 30 : 20) * presetSpriteScale(style, selected);
const crt = (selected ? 30 : 20) * presetSpriteScale('retro', selected);
assert.equal(display, crt);
const frame = haloFrame(
presetSpriteOutlinePx(style, selected),
display,
);
const crtFrame = haloFrame(
presetSpriteOutlinePx('retro', selected),
crt,
);
assert.equal(
(display * frame.ratio) / frame.ratio,
(crt * crtFrame.ratio) / crtFrame.ratio,
'unpadded silhouette matches CRT; only external halo padding grows',
);
assert.equal(
(svg.match(/<path /g) || []).length,
2,
'only outer halo and opaque silhouette',
);
assert.match(svg, /fill="white" \/>/);
for (const style of ['surveillance', 'thermal', 'noir', 'nvg']) {
const svg = decode(
transitIcon(kind, selected ? 96 : 48, { style, heading }),
);
const mono = await rasterBody(svg);
assert.deepEqual(
mono.mask,
normal.mask,
`${kind}/${style}: no envelope`,
);
assert.ok(
Math.abs(mono.aspect / normal.aspect - 1) <= 0.05,
`${kind}/${style}: aspect`,
);
const display =
(selected ? 30 : 20) * presetSpriteScale(style, selected);
const crt =
(selected ? 30 : 20) * presetSpriteScale('retro', selected);
assert.equal(display, crt);
const frame = haloFrame(
presetSpriteOutlinePx(style, selected),
display,
);
const crtFrame = haloFrame(
presetSpriteOutlinePx('retro', selected),
crt,
);
assert.equal(
(display * frame.ratio) / frame.ratio,
(crt * crtFrame.ratio) / crtFrame.ratio,
'unpadded silhouette matches CRT; only external halo padding grows',
);
assert.equal(
(svg.match(/<path /g) || []).length,
2,
'only outer halo and opaque silhouette',
);
assert.match(svg, /fill="white" \/>/);
}
}
}
});
test('sensor raster halo stays dark across its screen-space band on a white roof', async () => {
@@ -238,3 +247,58 @@ test('sensor raster halo stays dark across its screen-space band on a white roof
assert.ok(black.pass, JSON.stringify({ selected, black }));
}
});
test('a vehicle with a course shows its front; one without claims no direction', async () => {
const sharp = (await import('sharp')).default;
const outline = (svg) => svg.match(/<path d="([^"]+)"\s+fill="white"/)[1];
// Fleet-size raster of the outline alone: row widths from front to back.
const rows = async (d) => {
const { data, info } = await sharp(
Buffer.from(
`<svg xmlns="http://www.w3.org/2000/svg" width="96" height="96" viewBox="-48 -48 96 96"><path d="${d}" fill="white"/></svg>`,
),
)
.resize(20, 20)
.ensureAlpha()
.raw()
.toBuffer({ resolveWithObject: true });
const out = [];
for (let y = 0; y < info.height; y++) {
let sum = 0;
for (let x = 0; x < info.width; x++)
sum += data[(y * info.width + x) * 4 + 3] / 255;
out.push(sum);
}
return out;
};
// How much the outline differs from itself turned end for end, in pixels.
const asymmetry = (r) =>
r.reduce((a, v, i) => a + Math.abs(v - r[r.length - 1 - i]), 0);
for (const kind of TRANSIT_ICON_KINDS) {
const pointed = await rows(outline(decode(transitIcon(kind))));
const neutral = await rows(
outline(decode(transitIcon(kind, 48, { heading: false }))),
);
assert.ok(
asymmetry(pointed) >= 2.5,
`${kind}: front reads at 20 px (${asymmetry(pointed).toFixed(2)})`,
);
assert.ok(
asymmetry(neutral) < 0.5,
`${kind}: no implied heading (${asymmetry(neutral).toFixed(2)})`,
);
// The front is the narrow end: the two leading rows of ink carry less
// than the two trailing rows.
const inked = pointed.flatMap((v, i) => (v > 0.05 ? [i] : []));
const first = inked[0];
const last = inked[inked.length - 1];
const lead = pointed[first] + pointed[first + 1];
const trail = pointed[last] + pointed[last - 1];
assert.ok(lead < trail, `${kind}: nose toward -Y`);
}
assert.notEqual(
transitIcon('bus'),
transitIcon('bus', 48, { heading: false }),
);
assert.equal(transitIcon('bus', 48, { heading: true }), transitIcon('bus'));
});
+1 -1
View File
@@ -155,7 +155,7 @@ export function applyVesselOverlayPolicy(
edgeFade: 'keyhole',
horizonCull: true,
terrainOcclusion: false,
// Only MMSI-keyed cards can resolve back to one actionable vessel.
// Only keyed cards can resolve back to one actionable vessel.
interactive: card?.actionable === true,
};
}