Merge upstream main into feat/australia-transit

Upstream main (0ceee8df) adds Shipwrecks and News rows to the CURRENT-STATE
layer table, which re-aligns every row. Keep main's table and re-apply this
PR's Transit cell (53 keyless feeds, 50 regions). Main does not touch
transitFeeds.js, so the registry counts are unchanged: 53 feeds, 50 regions.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
This commit is contained in:
Renzo WillandClaude Opus 5.5 committed 2026-11-11 17:50:53 +10:00
commit 504ea69a5c
346 files changed
+42527 -1717

No files matched your search

+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);
+103 -23
View File
@@ -287,7 +287,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,
@@ -314,8 +314,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',
@@ -565,7 +565,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,
@@ -581,7 +581,7 @@ test('superseded AIS response cannot mutate or finalize a replacement request',
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.selectedId, replacement.mmsi);
second.resolve(jsonResponse({ status: 'open', lastMessageAt: null, rows: [] }));
await replacementLoad;
@@ -590,8 +590,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;
@@ -784,21 +784,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(
@@ -810,16 +810,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' },
@@ -834,8 +834,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',
@@ -849,6 +850,8 @@ function makeRecord(overrides = {}) {
billboard: null,
...overrides,
};
if (!Object.hasOwn(overrides, 'id')) record.id = record.mmsi;
return record;
}
function makeTrailSpy() {
@@ -948,7 +951,7 @@ function installWireHarness(picked, stateOverrides = {}) {
records: [record],
selectedRecord: record,
trail,
trailMmsi: record.mmsi,
trailId: record.mmsi,
trailPositions: [POS],
interactionHandlerFactory,
interactionKeyTarget: keyTarget,
@@ -983,7 +986,7 @@ test('vessel interaction wire: trail pick does not deselect', () => {
harness.handler.click({ position: { x: 10, y: 20 } });
assert.equal(aisLiveVesselsLayer.getSelectedInfo()?.mmsi, 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();
}
@@ -1213,7 +1216,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],
interactionHandlerFactory: harness.interactionHandlerFactory,
interactionKeyTarget: harness.keyTarget,
@@ -1287,7 +1290,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,
});
@@ -1302,14 +1305,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,
});
@@ -1566,6 +1569,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
@@ -1689,11 +1714,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 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', () => {
@@ -1740,7 +1781,7 @@ test('vessel selection passes the opaque source reference to optional history',
getSnapshot: async () => ({ records: [] }),
getTrack: async (reference, options) => { requests.push({ reference, options }); return { records: [] }; },
});
const harness = installWireHarness(undefined, { selectedRecord: null, trailMmsi: null });
const harness = installWireHarness(undefined, { selectedRecord: null, trailId: null });
try {
harness.record.reference = 'opaque:test-reference';
assert.equal(aisLiveVesselsLayer.selectById(harness.record.mmsi), true);
@@ -1802,3 +1843,42 @@ test('vessel focus wire skips hidden sprites at rest while a target is tracked',
assert.equal(result.activeCount, 1);
for (const billboard of hidden) assert.equal(billboard.color.alpha, 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,
billboard: null,
});
const keyed = vessel('200', 'GOLDEN BEAR');
const unkeyed = { ...vessel('', 'NO MMSI'), lat: 37.8, lon: -122.4 };
_setVesselStateForTest({
viewer: {},
records: [keyed, unkeyed],
billboardCollection: { show: true, remove() {} },
});
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
@@ -1518,3 +1518,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
@@ -134,6 +134,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:
@@ -566,6 +573,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:
@@ -632,6 +671,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';
@@ -43,6 +44,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.
@@ -182,6 +190,26 @@ test('every Street Level imagery source is in the attribution lightbox', () => {
);
});
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/);
+109 -4
View File
@@ -21,7 +21,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,
@@ -47,6 +50,8 @@ import {
viewScaleForAltitude,
} from './detectionPolicy.js';
import { detectionBracketOpacity } from './detectionPresentation.js';
import { SurfaceOcclusion } from './detectionOcclusion.js';
import { SceneOcclusionProbe } from './sceneOcclusionProbe.js';
import {
createCyberSonarSampler,
cyberSonarFrameDelay,
@@ -107,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. */
@@ -263,6 +270,22 @@ let _allocationStrategy = ALLOCATION_ELASTIC;
let _lastNonOffMode = MODE_BALANCED;
/** @type {LabelArbiter} Shared stable callout selector. */
const _labelArbiter = new LabelArbiter();
/**
* 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; `_surfaceOcclusion`
* remembers the answers and decides, every frame, who is drawn.
*/
const _occlusionProbe = new SceneOcclusionProbe();
const _surfaceOcclusion = new SurfaceOcclusion(_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;
@@ -367,6 +390,9 @@ export function destroyDetection() {
_suspended = false;
_suspendReason = '';
_labelArbiter.clear();
_surfaceOcclusion.clear();
_surfaceSuppressedKeys.clear();
_occlusionProbe.destroy();
_lastLabelSolveAt = 0;
_labelSolveDirty = true;
_lastDiagnostics = null;
@@ -576,7 +602,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;
}
@@ -691,6 +718,9 @@ function _applyModeState() {
_syncSurfaceVisibility();
_setLanesActive(false);
_labelArbiter.clear();
_surfaceOcclusion.clear();
_surfaceSuppressedKeys.clear();
_occlusionProbe.reset();
_lastLabelSolveAt = 0;
_labelSolveDirty = true;
_lastSolveSnapshot = {
@@ -1077,6 +1107,9 @@ function _stashCallout(entry, acquireFade, keyhole) {
font: FONT,
microFont: MICRO_FONT,
alpha: 1,
cardSourceId: '',
cardEntryId: '',
paintAlpha: 1,
};
_calloutPool[_calloutCount] = row;
}
@@ -1103,6 +1136,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++;
}
@@ -1134,7 +1169,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;
}
@@ -1211,6 +1254,8 @@ function _materializeCandidate(
primary,
micro,
hasMicro: card.hasMicro,
cardSourceId: obj.cardSourceId ? String(obj.cardSourceId) : '',
cardEntryId: obj.cardEntryId ? String(obj.cardEntryId) : '',
};
}
@@ -1316,6 +1361,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(_viewer?.scene, _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
@@ -1426,6 +1474,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);
@@ -1526,6 +1597,8 @@ function _drawOverlay(frame) {
candidateMap.set(candidate.key, candidate);
}
}
// Start this frame's occlusion tests; nothing here waits for them.
_occlusionProbe.endFrame();
const altitude = _viewer?.camera?.positionCartographic?.height ?? 1e9;
const collectiveBudget = labelBudgetFor(altitude, _densityPct);
@@ -1536,6 +1609,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,
@@ -1622,7 +1702,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
@@ -1677,6 +1775,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;
+471
View File
@@ -20,15 +20,28 @@ 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 './fixtures/fakeDepthScene.mjs';
test('detection diagnostics count rendered fading rows instead of absent selected identities', () => {
assert.equal(countFadingRenderEntries([
@@ -579,6 +592,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
@@ -1190,3 +1375,289 @@ 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 });
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();
}
});
+466
View File
@@ -0,0 +1,466 @@
/**
* 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. `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 `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 './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();
}
+1 -1
View File
@@ -276,7 +276,7 @@ test('a click on neither sprite nor card clears without moving the camera', () =
const SIBLING_PICKS = [
['flights', 'a1b2c3', { id: 'a1b2c3' }],
['flights', 'a1b2c3', { primitive: { id: 'a1b2c3' } }],
['ais-live-vessels', '353136000', { id: { mmsi: '353136000', name: 'EVER GIVEN' } }],
['ais-live-vessels', '353136000', { id: { id: '353136000', mmsi: '353136000', name: 'EVER GIVEN' } }],
['cctv', 'atx-cam-3', { id: { id: 'atx-cam-3', name: 'entity-like' } }],
['satellites', '25544', { id: 25544 }],
];
+351
View File
@@ -0,0 +1,351 @@
/**
* A stand-in scene and WebGL context for tests of the occlusion probe: just
* the members `sceneOcclusionProbe.js` uses, with depth images the test
* controls.
*
* The fake context cannot run GLSL. When the probe draws a point inside a
* query, the fake decides whether the point draws by applying the same rule
* to the same inputs the vertex shader gets (the uploaded attributes, the
* bound depth textures and the uniforms), using the CPU decode from
* `detectionOcclusion.js`. That checks everything around the shader; the
* shader itself is checked against `scene.pickPosition` in a real browser.
*/
import * as Cesium from 'cesium';
import { depthToViewDistance, unpackDepth } from '../detectionOcclusion.js';
/** Inverse of `unpackDepth`: four base-255 digits, most significant first. */
export function packDepth(depth) {
const bytes = [];
let rest = Math.min(Math.max(depth, 0), 1);
for (let i = 0; i < 4; i++) {
rest *= 255;
const digit = Math.min(255, Math.floor(rest));
bytes.push(digit);
rest -= digit;
}
return bytes;
}
/** Inverse of `depthToViewDistance`. */
export function viewDistanceToDepth(distance, near, far, logDepth) {
if (logDepth)
return Math.log2(distance - near + 1) / Math.log2(far - near + 1);
return (far * (distance - near)) / (distance * (far - near));
}
/**
* An RGBA8 depth image filled from a function of the texel.
* @param {number} width
* @param {number} height
* @param {(column: number, row: number) => number} depthAt Window depth; rows
* count from the bottom.
*/
export function depthImage(width, height, depthAt) {
const data = new Uint8Array(width * height * 4);
for (let row = 0; row < height; row++)
for (let column = 0; column < width; column++)
data.set(packDepth(depthAt(column, row)), (row * width + column) * 4);
return { width, height, data };
}
const GL = {
FRAMEBUFFER: 0x8d40,
READ_FRAMEBUFFER: 0x8ca8,
DRAW_FRAMEBUFFER: 0x8ca9,
FRAMEBUFFER_BINDING: 0x8ca6,
DRAW_FRAMEBUFFER_BINDING: 0x8ca6,
READ_FRAMEBUFFER_BINDING: 0x8caa,
TEXTURE_BINDING_2D: 0x8069,
TEXTURE_2D: 0x0de1,
TEXTURE0: 0x84c0,
ACTIVE_TEXTURE: 0x84e0,
COLOR_ATTACHMENT0: 0x8ce0,
FRAMEBUFFER_COMPLETE: 0x8cd5,
ARRAY_BUFFER: 0x8892,
ARRAY_BUFFER_BINDING: 0x8894,
VERTEX_ARRAY_BINDING: 0x85b5,
CURRENT_PROGRAM: 0x8b8d,
STREAM_DRAW: 0x88e0,
SCISSOR_TEST: 0x0c11,
VIEWPORT: 0x0ba2,
POINTS: 0x0000,
FLOAT: 0x1406,
RGBA: 0x1908,
RGBA8: 0x8058,
UNSIGNED_BYTE: 0x1401,
VERTEX_SHADER: 0x8b31,
FRAGMENT_SHADER: 0x8b30,
COMPILE_STATUS: 0x8b81,
LINK_STATUS: 0x8b82,
ANY_SAMPLES_PASSED_CONSERVATIVE: 0x8d6a,
QUERY_RESULT: 0x8866,
QUERY_RESULT_AVAILABLE: 0x8867,
};
/**
* A recording WebGL context. `webgl2: false` leaves out queries, vertex
* arrays and immutable textures, as a WebGL 1 context does. Query results
* stay unavailable until `finishGpu()`.
*/
export function createFakeGl({ webgl2 = true } = {}) {
const state = {
read: null,
draw: null,
units: [null, null, null, null, null, null, null, null],
unit: 0,
array: null,
vertexArray: null,
program: null,
scissor: false,
viewport: [0, 0, 1920, 1080],
lost: false,
/** Whether a point that should draw does (false: a broken draw path). */
drawsLand: true,
/** Whether shaders compile: a boolean, or a function of the shader type. */
compiles: true,
};
const counts = {
readPixels: 0,
queries: 0,
draws: 0,
resultReads: 0,
deleted: 0,
};
const liveQueries = new Set();
const liveShaders = new Set();
let activeQuery = null;
const gl = {
...GL,
state,
counts,
liveQueries,
liveShaders,
isContextLost: () => state.lost,
getParameter(name) {
if (name === GL.READ_FRAMEBUFFER_BINDING) return state.read;
if (name === GL.DRAW_FRAMEBUFFER_BINDING) return state.draw;
if (name === GL.TEXTURE_BINDING_2D) return state.units[state.unit];
if (name === GL.ACTIVE_TEXTURE) return GL.TEXTURE0 + state.unit;
if (name === GL.ARRAY_BUFFER_BINDING) return state.array;
if (name === GL.VERTEX_ARRAY_BINDING) return state.vertexArray;
if (name === GL.CURRENT_PROGRAM) return state.program;
if (name === GL.VIEWPORT) return Int32Array.from(state.viewport);
return null;
},
isEnabled: (cap) => cap === GL.SCISSOR_TEST && state.scissor,
enable(cap) {
if (cap === GL.SCISSOR_TEST) state.scissor = true;
},
disable(cap) {
if (cap === GL.SCISSOR_TEST) state.scissor = false;
},
createFramebuffer: () => ({ image: null }),
createTexture: () => ({ image: null }),
createBuffer: () => ({ data: null }),
deleteFramebuffer() {
counts.deleted++;
},
deleteTexture() {
counts.deleted++;
},
deleteBuffer() {
counts.deleted++;
},
activeTexture(unit) {
state.unit = unit - GL.TEXTURE0;
},
bindTexture(_target, texture) {
state.units[state.unit] = texture;
},
bindFramebuffer(target, framebuffer) {
if (target !== GL.DRAW_FRAMEBUFFER) state.read = framebuffer;
if (target !== GL.READ_FRAMEBUFFER) state.draw = framebuffer;
},
bindBuffer(_target, buffer) {
state.array = buffer;
},
readPixels(x, y, width, height, _format, _type, destination) {
counts.readPixels++;
const image = state.read.image;
for (let row = 0; row < height; row++) {
const from = ((y + row) * image.width + x) * 4;
destination.set(
image.data.subarray(from, from + width * 4),
row * width * 4,
);
}
},
};
if (webgl2) {
Object.assign(gl, {
texStorage2D(_target, _levels, _format, width, height) {
state.units[state.unit].image = {
width,
height,
data: new Uint8Array(width * height * 4),
};
},
framebufferTexture2D(_target, _attachment, _kind, texture) {
state.draw.image = texture.image;
},
checkFramebufferStatus: () => GL.FRAMEBUFFER_COMPLETE,
createShader(type) {
const shader = { type };
liveShaders.add(shader);
return shader;
},
shaderSource() {},
compileShader() {},
getShaderParameter: (shader) =>
typeof state.compiles === 'function'
? state.compiles(shader.type)
: state.compiles,
deleteShader(shader) {
liveShaders.delete(shader);
},
createProgram: () => ({ uniforms: {} }),
attachShader() {},
linkProgram() {},
getProgramParameter: () => true,
deleteProgram() {
counts.deleted++;
},
getUniformLocation: (_program, name) => name,
useProgram(program) {
state.program = program;
},
viewport(x, y, width, height) {
state.viewport = [x, y, width, height];
},
uniform1i(name, value) {
state.program.uniforms[name] = value;
},
uniform4f(name, x, y, z, w) {
state.program.uniforms[name] = [x, y, z, w];
},
createVertexArray: () => ({ buffer: null }),
deleteVertexArray() {
counts.deleted++;
},
bindVertexArray(vertexArray) {
state.vertexArray = vertexArray;
},
enableVertexAttribArray() {},
vertexAttribPointer() {
state.vertexArray.buffer = state.array;
},
bufferData(_target, data) {
state.array.data = Float32Array.from(data);
},
createQuery() {
const query = { drew: false, available: false, ended: false };
liveQueries.add(query);
return query;
},
deleteQuery(query) {
liveQueries.delete(query);
},
beginQuery(_target, query) {
counts.queries++;
query.drew = false;
query.available = false;
query.ended = false;
activeQuery = query;
},
endQuery() {
activeQuery.ended = true;
activeQuery = null;
},
/** The vertex shader's rule, applied to what the shader would be given. */
drawArrays(_mode, first) {
counts.draws++;
const uniforms = state.program.uniforms;
const data = state.vertexArray.buffer.data;
const u = data[first * 3];
const v = data[first * 3 + 1];
const threshold = data[first * 3 + 2];
let surface = -1;
for (let i = 0; i < uniforms.u_count && surface < 0; i++) {
const image = state.units[uniforms[`u_depth${i}`]].image;
const column = Math.min(image.width - 1, Math.floor(u * image.width));
const row = Math.min(image.height - 1, Math.floor(v * image.height));
const distance = depthToViewDistance(
unpackDepth(image.data, (row * image.width + column) * 4),
uniforms.u_near[i],
uniforms.u_far[i],
uniforms.u_logDepth === 1,
);
if (distance === distance) surface = distance;
}
const hidden = surface > 0 && surface < threshold;
// A point at the middle of the viewport lands only if that is the
// target's one pixel and the scissor test is not in the way. A
// sampler left on a unit with no texture fails the whole draw.
const samplersBound = [0, 1, 2, 3].every(
(i) => state.units[uniforms[`u_depth${i}`]]?.image,
);
const lands =
state.drawsLand &&
samplersBound &&
!state.scissor &&
state.draw?.image?.width === 1 &&
state.viewport.join() === '0,0,1,1';
if (activeQuery && !hidden && lands) activeQuery.drew = true;
},
getQueryParameter(query, name) {
if (name === GL.QUERY_RESULT_AVAILABLE) return query.available;
counts.resultReads++;
return query.available && query.drew ? 1 : 0;
},
});
}
/** Let every query issued so far finish. */
gl.finishGpu = () => {
for (const query of liveQueries) if (query.ended) query.available = true;
};
return gl;
}
/**
* A scene drawn in the given depth ranges, nearest first.
* @param {{
* gl?: object,
* ranges: Array<{near: number, far: number, image: object}>,
* logDepth?: boolean, fovy?: number, aspectRatio?: number,
* viewMatrix?: Cesium.Matrix4,
* }} options
*/
export function createFakeDepthScene({
gl = createFakeGl(),
ranges,
logDepth = true,
fovy = Math.PI / 2,
aspectRatio = 1,
viewMatrix = Cesium.Matrix4.clone(Cesium.Matrix4.IDENTITY),
}) {
return {
mode: Cesium.SceneMode.SCENE3D,
useDepthPicking: true,
opaqueFrustumNearOffset: 0.9999,
context: { _gl: gl, depthTexture: true, webgl2: !!gl.createQuery },
_environmentState: { useGlobeDepthFramebuffer: true },
frameState: { useLogDepth: logDepth },
camera: { frustum: { fovy, aspectRatio }, viewMatrix },
view: {
frustumCommandsList: ranges.map(({ near, far }) => ({ near, far })),
pickDepths: ranges.map(({ image }) => {
const texture = { image };
return {
framebuffer: {
_framebuffer: { image },
getColorTexture: () => ({
width: image.width,
height: image.height,
_texture: texture,
}),
},
};
}),
},
};
}
+2
View File
@@ -40,5 +40,7 @@ export const _driveFleetModelHandoffForTest =
flightsLayer.testing._driveFleetModelHandoffForTest;
export const _ensureFleetModelForTest =
flightsLayer.testing._ensureFleetModelForTest;
export const _resetEnrichmentForTest =
flightsLayer.testing._resetEnrichmentForTest;
export const mapAnalystRecord = flightsLayer.mapAnalystRecord;
export default flightsLayer;
+293 -2
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 * as Cesium from 'cesium';
import flightsLayer, {
@@ -14,21 +14,53 @@ import flightsLayer, {
_setTrackedFlightRefreshStateForTest,
_floorGroundedDisplayPositionForTest,
_clearDisplayFloorStateForTest,
_resetEnrichmentForTest,
mapAnalystRecord,
} from './flights.js';
import { setMilitaryLayerActive } from './militaryRegistry.js';
import {
isMilitaryLayerActive,
registerMilitaryIcaos,
setMilitaryLayerActive,
} from './militaryRegistry.js';
import {
GROUND_FLOOR_LIFT_M,
reportMeshFloorCell,
reportValidatedMeshFloorCell,
setMeshFloorPreferred,
_clearMeshFloorCellsForTest,
} from './groundFloor.js';
import { resolveEllipsoidalGround } from './terrainHeights.js';
import {
_setTrackedOverlayHostForTest,
destroyTrackedReadout,
initTrackedReadout,
} from './trackedReadout.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(
@@ -402,6 +434,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);
@@ -1181,6 +1439,39 @@ test('display floor: a grounded contact that drifted onto a higher cell is lifte
assert.ok(Math.abs(Cesium.Math.toDegrees(c.longitude) + 97.6604) < 1e-6);
});
test('display floor: reads the reading nearest the contact, not the cell centre', async () => {
_clearDisplayFloorStateForTest();
_clearMeshFloorCellsForTest();
setMeshFloorPreferred(true);
const realFetch = globalThis.fetch;
globalThis.fetch = async () =>
new Response(JSON.stringify({ results: [{ ellipsoid: 120 }] }), {
status: 200,
headers: { 'Content-Type': 'application/json' },
});
try {
await resolveEllipsoidalGround([{ lat: 30.317, lon: -97.717 }]);
} finally {
globalThis.fetch = realFetch;
}
// A hangar roof over the cell's centre; the apron where the contact is.
assert.equal(reportValidatedMeshFloorCell(30.317, -97.717, 142), true);
assert.equal(reportValidatedMeshFloorCell(30.3173, -97.7173, 121), true);
const pos = Cesium.Cartesian3.fromDegrees(-97.7173, 30.3173, 100);
const out = _floorGroundedDisplayPositionForTest(
{ onGround: true },
pos,
false,
);
const c = _floorCarto(out);
assert.ok(
Math.abs(c.height - (121 + GROUND_FLOOR_LIFT_M)) < 0.05,
`height ${c.height} should be the apron's 121 + lift`,
);
_clearMeshFloorCellsForTest();
_clearDisplayFloorStateForTest();
});
test('display floor: an AIRBORNE contact over the same cell is never lifted', () => {
_clearDisplayFloorStateForTest();
_clearMeshFloorCellsForTest();
+1
View File
@@ -22,6 +22,7 @@ export const {
reportMeshFloorCell,
meshFloorSampleWithinPrior,
reportValidatedMeshFloorCell,
meshFloorPriorReady,
cachedMeshFloor,
_clearMeshFloorCellsForTest,
cachedGroundFloor,
+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
+178 -1
View File
@@ -24,7 +24,7 @@ import { sampleMeshFloorCells } from './meshFloorSampler.js';
import { resolveEllipsoidalGround } from './terrainHeights.js';
import {
cachedGroundFloor, cachedMeshFloor, setMeshFloorPreferred,
_clearMeshFloorCellsForTest,
_clearMeshFloorCellsForTest, reportValidatedMeshFloorCell,
} from './groundFloor.js';
/** Distinct site per test — terrainHeights' cache is module-global and warm
@@ -137,3 +137,180 @@ test('sampler: a cell just across the antimeridian is still near the viewer', ()
sampleMeshFloorCells(scene, [{ lat: -16.81, lon: 179.999 }], { viewerLat: -16.81, viewerLon: -179.999 });
assert.equal(calls, 2, 'about 200 m apart, so both cells are probed');
});
test('sampler: the probe goes where the point is, not to the cell centre', async () => {
reset();
const cell = nextSite();
await seedDem(cell, 120.0);
const asked = [];
const scene = fakeScene((carto) => {
asked.push(Cesium.Math.toDegrees(carto.longitude));
return 122.0;
});
const point = { lat: cell.lat + 0.0003, lon: cell.lon + 0.0004 };
sampleMeshFloorCells(scene, [point], { viewerLat: cell.lat, viewerLon: cell.lon });
assert.equal(asked.length, 1);
assert.ok(Math.abs(asked[0] - point.lon) < 1e-9, `probed at ${asked[0]}, not ${point.lon}`);
});
test('sampler: a viaduct and the street beside it in one cell keep their own heights', async () => {
reset();
const cell = nextSite();
await seedDem(cell, 120.0);
// A viaduct deck 9 m up along one line of the cell, the street elsewhere.
const deckLat = cell.lat + 0.0003;
let calls = 0;
const scene = fakeScene((carto) => {
calls += 1;
return Math.abs(Cesium.Math.toDegrees(carto.latitude) - deckLat) < 1e-7 ? 129.0 : 121.0;
});
const opts = { viewerLat: cell.lat, viewerLon: cell.lon };
const onDeck = { lat: deckLat, lon: cell.lon };
const street = { lat: cell.lat - 0.0003, lon: cell.lon };
sampleMeshFloorCells(scene, [onDeck], opts);
sampleMeshFloorCells(scene, [street], opts);
assert.equal(calls, 2);
assert.equal(cachedMeshFloor(onDeck.lat, onDeck.lon + 0.0001), 129.0, 'the train stays on the deck');
assert.equal(cachedMeshFloor(street.lat, street.lon - 0.0001), 121.0, 'the bus stays on the street');
assert.equal(cachedGroundFloor(street.lat, street.lon), 121.0);
sampleMeshFloorCells(scene, [{ lat: deckLat, lon: cell.lon + 0.00001 }], opts);
assert.equal(calls, 2, 'a point next to one already probed is not probed again');
});
test('sampler: a roof over the cell centre does not lift a bus on the street', async () => {
reset();
const cell = nextSite();
await seedDem(cell, 120.0);
// A roof 22 m up covering the cell's centre; the street 30 m west of it.
const scene = fakeScene((carto) =>
Math.abs(Cesium.Math.toDegrees(carto.longitude) - cell.lon) < 0.0001 ? 142.0 : 121.0);
const bus = { lat: cell.lat, lon: cell.lon - 0.0003 };
sampleMeshFloorCells(scene, [bus], { viewerLat: cell.lat, viewerLon: cell.lon });
assert.equal(cachedGroundFloor(bus.lat, bus.lon), 121.0);
});
test('sampler: a second reading at the same spot keeps the lower one', async () => {
reset();
const cell = nextSite();
await seedDem(cell, 120.0);
assert.equal(reportValidatedMeshFloorCell(cell.lat, cell.lon, 131.0), true);
assert.equal(reportValidatedMeshFloorCell(cell.lat + 0.00002, cell.lon, 122.0), true);
assert.equal(cachedMeshFloor(cell.lat, cell.lon), 122.0);
assert.equal(reportValidatedMeshFloorCell(cell.lat, cell.lon + 0.00002, 140.0), true);
assert.equal(cachedMeshFloor(cell.lat, cell.lon), 122.0, 'a higher one never raises it');
});
test('sampler: a cell with a reading is probed a few times at most', async () => {
reset();
const cell = nextSite();
await seedDem(cell, 120.0);
let calls = 0;
const scene = fakeScene(() => {
calls += 1;
return 121.0;
});
const opts = { viewerLat: cell.lat, viewerLon: cell.lon };
for (let i = 0; i < 20; i++)
sampleMeshFloorCells(
scene,
[{ lat: cell.lat - 0.0004 + (i % 5) * 0.0002, lon: cell.lon - 0.00045 + Math.floor(i / 5) * 0.0003 }],
opts,
);
assert.equal(calls, 8);
});
test('sampler: a cell with no accepted reading is probed again on every call', async () => {
reset();
const cell = nextSite();
let calls = 0;
const scene = fakeScene(() => {
calls += 1;
return 138.0;
});
const opts = { viewerLat: cell.lat, viewerLon: cell.lon };
for (let i = 0; i < 3; i++) sampleMeshFloorCells(scene, [cell], opts);
assert.equal(calls, 3, 'no DEM prior yet, so nothing is kept and the cell is retried');
await seedDem(cell, 120.0);
sampleMeshFloorCells(scene, [cell], opts);
assert.equal(cachedMeshFloor(cell.lat, cell.lon), 138.0, 'and lands once the prior is warm');
});
test('sampler: a spot whose reading is refused does not use up the cell', async () => {
reset();
const cell = nextSite();
await seedDem(cell, 120.0);
// A tower 260 m up where the first vehicle waits; the street elsewhere and
// a deck 9 m up along one line of the cell.
const towerLon = cell.lon + 0.0004;
const deckLat = cell.lat + 0.0003;
const scene = fakeScene((carto) => {
if (Math.abs(Cesium.Math.toDegrees(carto.longitude) - towerLon) < 1e-7) return 380.0;
return Math.abs(Cesium.Math.toDegrees(carto.latitude) - deckLat) < 1e-7 ? 129.0 : 121.0;
});
const opts = { viewerLat: cell.lat, viewerLon: cell.lon };
for (let i = 0; i < 10; i++) sampleMeshFloorCells(scene, [{ lat: cell.lat, lon: towerLon }], opts);
assert.equal(cachedMeshFloor(cell.lat, cell.lon), null, 'the tower is refused every time');
sampleMeshFloorCells(scene, [{ lat: cell.lat - 0.0003, lon: cell.lon }], opts);
sampleMeshFloorCells(scene, [{ lat: deckLat, lon: cell.lon - 0.0003 }], opts);
assert.equal(cachedMeshFloor(deckLat, cell.lon - 0.0003), 129.0, 'the deck is still probed');
});
test('ground floor: a cell keeps at most sixteen readings', async () => {
reset();
const cell = nextSite();
await seedDem(cell, 120.0);
for (let i = 0; i < 40; i++) {
const lat = cell.lat - 0.00045 + (i % 8) * 0.0001;
const lon = cell.lon - 0.00045 + Math.floor(i / 8) * 0.0002;
reportValidatedMeshFloorCell(lat, lon, 121.0 + i);
}
// Readings 0..15 are kept; reading 39 (at the far corner) is not, so that
// spot answers from the nearest kept one.
assert.equal(cachedMeshFloor(cell.lat - 0.00045, cell.lon - 0.00045), 121.0);
assert.equal(cachedMeshFloor(cell.lat + 0.00025, cell.lon + 0.00035), 121.0 + 15);
});
test('sampler: a spot refused while the DEM was cold is probed again once it is warm', async () => {
reset();
const cell = nextSite();
const deckLat = cell.lat + 0.0003;
let calls = 0;
const scene = fakeScene((carto) => {
calls += 1;
return Math.abs(Cesium.Math.toDegrees(carto.latitude) - deckLat) < 1e-7 ? 129.0 : 121.0;
});
const opts = { viewerLat: cell.lat, viewerLon: cell.lon };
const onDeck = { lat: deckLat, lon: cell.lon };
sampleMeshFloorCells(scene, [onDeck], opts);
assert.equal(cachedMeshFloor(onDeck.lat, onDeck.lon), null, 'no prior, nothing kept');
await seedDem(cell, 120.0);
sampleMeshFloorCells(scene, [{ lat: cell.lat - 0.0003, lon: cell.lon }], opts);
sampleMeshFloorCells(scene, [onDeck], opts);
assert.equal(calls, 3);
assert.equal(cachedMeshFloor(onDeck.lat, onDeck.lon), 129.0);
});
test('sampler: a spot refused while the DEM prior was evicted is probed again', async () => {
const { createGroundFloor } = await import('../services/groundFloor.js');
const { createMeshFloorSampler } = await import('../services/meshFloorSampler.js');
let prior = 120.0;
const terrain = {
cachedRealEllipsoidalGround: () => prior,
resolveEllipsoidalGround: async () => {},
};
const groundFloor = createGroundFloor({ terrain });
const sampler = createMeshFloorSampler({ groundFloor });
const cell = { lat: 41.5, lon: -97.66 };
const deckLat = cell.lat + 0.0003;
const scene = fakeScene((carto) =>
Math.abs(Cesium.Math.toDegrees(carto.latitude) - deckLat) < 1e-7 ? 129.0 : 121.0);
const opts = { viewerLat: cell.lat, viewerLon: cell.lon };
const onDeck = { lat: deckLat, lon: cell.lon };
sampler.sampleMeshFloorCells(scene, [{ lat: cell.lat - 0.0003, lon: cell.lon }], opts);
prior = null; // the cell's DEM entry is evicted; the street reading stays
sampler.sampleMeshFloorCells(scene, [onDeck], opts);
assert.equal(groundFloor.cachedMeshFloor(onDeck.lat, onDeck.lon), 121.0);
prior = 120.0;
sampler.sampleMeshFloorCells(scene, [onDeck], opts);
assert.equal(groundFloor.cachedMeshFloor(onDeck.lat, onDeck.lon), 129.0);
});
+88 -2
View File
@@ -425,7 +425,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();
@@ -1118,6 +1118,92 @@ 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 = { camera: { positionCartographic: null }, scene: {} };
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,
billboard: { position, color: Cesium.Color.WHITE, show: true },
billboardCollection: { show: true, remove() {} },
viewer: sourceViewer,
meta,
});
runtime.viewer.trackedEntity = { gevTrackedId: `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,
billboard: { position, show: true },
billboardCollection: { 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
@@ -1721,7 +1807,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;
+181 -8
View File
@@ -198,6 +198,157 @@ 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: Cesium.Cartesian3, 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 = Cesium.Cartographic.fromCartesian(
fix.position,
Cesium.Ellipsoid.WGS84,
_holdCarto,
);
const groundM =
carto && typeof cachedGroundFloor === 'function'
? cachedGroundFloor(
Cesium.Math.toDegrees(carto.latitude),
Cesium.Math.toDegrees(carto.longitude),
)
: null;
fix.staleHolds = staleHoldsAtLastReport({
onGround,
heightM: carto?.height,
groundM,
});
return fix.staleHolds;
}
const _holdCarto = new Cesium.Cartographic();
/**
* 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 {Cesium.Cartesian3} position - Mutated in place.
* @param {(latDeg: number, lonDeg: number) => number|null} [cachedGroundFloor]
* @returns {Cesium.Cartesian3}
*/
export function floorCoastedPosition(position, cachedGroundFloor) {
if (typeof cachedGroundFloor !== 'function') return position;
const carto = Cesium.Cartographic.fromCartesian(
position,
Cesium.Ellipsoid.WGS84,
_coastCarto,
);
if (!carto) return position;
const ground = cachedGroundFloor(
Cesium.Math.toDegrees(carto.latitude),
Cesium.Math.toDegrees(carto.longitude),
);
if (!Number.isFinite(ground) || carto.height >= ground + COAST_FLOOR_LIFT_M)
return position;
return Cesium.Cartesian3.fromRadians(
carto.longitude,
carto.latitude,
ground + COAST_FLOOR_LIFT_M,
Cesium.Ellipsoid.WGS84,
position,
);
}
const _coastCarto = new Cesium.Cartographic();
/**
* 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.
@@ -446,12 +597,21 @@ const _forwardFixOffset = new Cesium.Cartesian3();
* 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: Cesium.JulianDate, epochMs?: number, position: Cesium.Cartesian3,
* 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: Cesium.JulianDate, epochMs: number, position: Cesium.Cartesian3,
* 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))
@@ -461,12 +621,18 @@ export function synthesizeForwardKinematicsFix(newest, next = {}) {
: Cesium.JulianDate.toDate(newest.time).getTime();
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,
@@ -485,14 +651,21 @@ export function synthesizeForwardKinematicsFix(newest, next = {}) {
Cesium.Ellipsoid.WGS84,
_forwardFixEnu,
);
const position = Cesium.Matrix4.multiplyByPoint(
enu,
_forwardFixOffset,
new Cesium.Cartesian3(),
const position = floorCoastedPosition(
Cesium.Matrix4.multiplyByPoint(
enu,
_forwardFixOffset,
new Cesium.Cartesian3(),
),
next.cachedGroundFloor,
);
return {
time: Cesium.JulianDate.fromDate(new Date(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 -4
View File
@@ -21,7 +21,7 @@ const _owners = new Map();
*
* Layers use heterogeneous pick ids: flights/military/bikeshare/CCTV use
* strings, satellites use numeric NORAD catalog ids, live AIS vessels attach
* the vessel record OBJECT (identity = its `mmsi`), and entity picks surface
* the vessel record OBJECT (identity = its `id`), and entity picks surface
* the Cesium Entity (identity = its string `id`). Everything is coerced to a
* String so predicates match against one canonical form.
*
@@ -33,9 +33,7 @@ export function resolvePickId(picked) {
const unwrap = (id) => {
if (id === null || id === undefined) return undefined;
if (typeof id === 'object') {
// AIS vessel record (id object with .mmsi) or Cesium Entity (.id string)
if (typeof id.mmsi === 'string' || typeof id.mmsi === 'number')
return id.mmsi;
// AIS vessel record or Cesium Entity: both are keyed by their `.id`.
if (typeof id.id === 'string' || typeof id.id === 'number') return id.id;
return undefined;
}
+8 -6
View File
@@ -33,10 +33,12 @@ test('resolvePickId: numeric pick id (satellite NORAD numbers) → String', () =
assert.equal(resolvePickId({ id: undefined, primitive: { id: 43013 } }), '43013');
});
test('resolvePickId: AIS vessel record object → its mmsi', () => {
const record = { mmsi: '367123450', name: 'EVER GIVEN', billboard: {} };
test('resolvePickId: AIS vessel record object → its id, not its MMSI', () => {
const record = { id: '367123450', mmsi: '367123450', name: 'EVER GIVEN', billboard: {} };
assert.equal(resolvePickId({ id: record }), '367123450');
assert.equal(resolvePickId({ primitive: { id: record } }), '367123450');
const shared = { id: 'hull-b', mmsi: '367123450', name: 'EVER GIVEN' };
assert.equal(resolvePickId({ id: shared }), 'hull-b');
});
test('resolvePickId: Cesium-Entity-like object → its string id', () => {
@@ -48,7 +50,7 @@ test('resolvePickId: unresolvable picks → null', () => {
assert.equal(resolvePickId(null), null);
assert.equal(resolvePickId(undefined), null);
assert.equal(resolvePickId({}), null);
assert.equal(resolvePickId({ id: {} }), null); // object with no mmsi/id
assert.equal(resolvePickId({ id: {} }), null); // object with no id
assert.equal(resolvePickId({ primitive: {} }), null);
});
@@ -67,8 +69,8 @@ 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({ id: 25544 })), true);
// Flights asking about a vessel pick (record object → mmsi)
assert.equal(isOwnedByOtherLayer('flights', resolvePickId({ id: { mmsi: '367123450' } })), true);
// Flights asking about a vessel pick (record object → id)
assert.equal(isOwnedByOtherLayer('flights', resolvePickId({ id: { id: '367123450', mmsi: '367123450' } })), true);
// A layer never owns its own pick via the sibling scan
assert.equal(isOwnedByOtherLayer('satellites', '25544'), false);
// Unknown ids belong to nobody
@@ -147,7 +149,7 @@ test('touch contact pick expands only a surface miss, bounded to 8 hits in 14 CS
test('touch contact pick returns the first registered sibling, never a caller-specific preference', (t) => {
primaryPointer(t, true);
contactOwners(t);
for (const first of [{ id: 'military' }, { id: { mmsi: '123456789' } }]) {
for (const first of [{ id: 'military' }, { id: { id: '123456789', mmsi: '123456789' } }]) {
const scene = {
pick: () => mapTile,
drillPick: () => [mapTile, first, { id: 'civil' }],
+2 -2
View File
@@ -64,8 +64,8 @@ function contextCarrierRecord(picked, 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
+4 -1
View File
@@ -140,7 +140,10 @@ test('the actual native tracked label hides the wrong leg and keeps a healthy ro
].map((name) => [name, {}]),
);
services.aircraftPresentation = { isTr3b: () => false };
const parts = { queries: { _contactLabel: (_, info) => info.callsign } };
const parts = {
queries: { _contactLabel: (_, info) => info.callsign },
motion: { _signalLost: () => null },
};
const tracking = createTracking({ flightState, services, parts });
for (const [position, expected] of [
[beyond, false],
+796
View File
@@ -0,0 +1,796 @@
/**
* Asks the GPU, per contact, whether the scene drew something in front of it,
* without waiting for the answer.
*
* The scene already keeps the depth of the frame it has just drawn (for
* picking). `scene.pickPosition` reads one texel of it back and waits, a
* fraction of a millisecond to over a millisecond per call; asking once per
* labelled contact turns a 2 ms frame into a 40 ms one. Copying the whole
* depth image back instead is no better where it matters: Chromium answers
* `getBufferSubData` with a round trip to its GPU process even after a sync
* object has signalled, measured here at 1.5 ms on a quiet machine and 15 to
* 25 ms on a busy one.
*
* So nothing is read back at all. Each tested contact becomes one point drawn
* into a private 1x1 target, inside an occlusion query. The vertex shader looks
* up the frame's depth at the contact's pixel, decodes it, and throws the point
* away when the drawn surface is nearer than the contact's threshold (see
* `projectContact`). The query's "did anything draw" bit is the answer, and
* asking whether a query result is in is the one question WebGL 2 lets a page
* put to the GPU without waiting (Chromium publishes results to the page
* through shared memory between frames): `_collect` just looks.
*
* - `beginFrame(scene, now)` collects the answers that have arrived.
* - `add(contact, position)` queues a contact for testing against this frame.
* - `endFrame()` draws the queued points. Answers land a frame or two later.
*
* A WebGL 1 context has no queries. There the probe falls back to reading the
* frame's depth back synchronously, at most every `SYNC_READ_INTERVAL_MS`, and
* answering on the CPU; `mode` then reads `'sync'`. Where the scene keeps no
* pick depth, or is not a 3D perspective view, `mode` reads `'off'`, nothing
* is tested and callers carry on as if no contact were hidden.
*
* Every read of renderer internals is in `readSceneDepthSource` below; the
* rest of the file is plain WebGL on the handles that function returns.
*/
import * as Cesium from 'cesium';
import { DepthSnapshot, projectContact } from './detectionOcclusion.js';
/**
* Depth ranges tested, nearest first. Logarithmic depth draws nearly every
* view in one or two; anything past the fourth is beyond where depth-tested
* contacts are labelled.
*/
export const PROBE_MAX_FRUSTUMS = 4;
/** Contacts tested per frame; the rest wait for the next one. */
export const PROBE_MAX_PER_FRAME = 256;
/** Painted frames a batch of queries may stay unanswered before it is dropped. */
export const PROBE_MAX_PENDING_FRAMES = 120;
/** Batches in a row whose control point failed before the probe stands down. */
export const PROBE_MAX_CONTROL_FAILURES = 3;
/** How long the probe stands down after a failure before trying again. */
export const PROBE_RETRY_AFTER_MS = 10_000;
/** Shortest gap between two synchronous depth reads (WebGL 1 fallback). */
export const SYNC_READ_INTERVAL_MS = 125;
/**
* Everything this module takes from the renderer, in one place.
*
* RENDERER INTERNALS. Checked against cesium 1.138.0 (@cesium/engine 22.3.0);
* re-check on an engine upgrade. Undocumented members used, and what each is
* assumed to be:
*
* - `scene.context._gl`: the WebGL context. `scene.context.webgl2` says which.
* - `scene.view.frustumCommandsList[i].near` / `.far`: the depth ranges the
* last frame was drawn in, nearest first.
* - `scene.view.pickDepths[i].framebuffer`: one framebuffer per depth range,
* refreshed every frame while `scene.useDepthPicking` is on and
* `scene._environmentState.useGlobeDepthFramebuffer` is true, whose first
* colour attachment is an RGBA8 texture holding window-space depth packed
* four bytes to a texel (`czm_packDepth`; see `unpackDepth`).
* `framebuffer._framebuffer` is the raw WebGL framebuffer, and
* `framebuffer.getColorTexture(0)` the texture (`._texture` its raw handle).
* - Opaque geometry in every range but the nearest is drawn with its near
* plane pulled in by `scene.opaqueFrustumNearOffset` (public), exactly as
* `scene.pickPosition` assumes when it decodes the same textures.
* - `scene.frameState.useLogDepth`: whether depth is logarithmic (see
* `depthToViewDistance`). Anything but a boolean there is "no depth".
*
* Any of these missing or shaped differently returns null, which callers treat
* as "no depth".
*
* @param {Cesium.Scene} scene
* @param {Float64Array} [viewScratch] Sixteen numbers to write the view matrix
* into instead of allocating; the result's `view` is then this array.
* @returns {null | {
* gl: WebGLRenderingContext|WebGL2RenderingContext, webgl2: boolean,
* width: number, height: number, framebuffers: WebGLFramebuffer[],
* textures: WebGLTexture[],
* frustums: Array<{near: number, far: number}>, logDepth: boolean,
* view: Float64Array, tanHalfFovX: number, tanHalfFovY: number,
* }}
*/
export function readSceneDepthSource(scene, viewScratch) {
try {
if (!scene || scene.mode !== Cesium.SceneMode.SCENE3D) return null;
if (scene.useDepthPicking !== true) return null;
const context = scene.context;
const gl = context?._gl;
if (!gl || context.depthTexture !== true) return null;
if (scene._environmentState?.useGlobeDepthFramebuffer !== true) return null;
const camera = scene.camera;
const frustum = camera?.frustum;
const fovy = frustum?.fovy;
const aspectRatio = frustum?.aspectRatio;
if (!(fovy > 0 && fovy < Math.PI) || !(aspectRatio > 0)) return null;
if (frustum.xOffset || frustum.yOffset) return null;
const view = scene.view;
const ranges = view?.frustumCommandsList;
const pickDepths = view?.pickDepths;
if (!ranges?.length || !pickDepths?.length) return null;
const count = Math.min(
ranges.length,
pickDepths.length,
PROBE_MAX_FRUSTUMS,
);
const nearOffset = Number(scene.opaqueFrustumNearOffset) || 1;
const framebuffers = [];
const textures = [];
const frustums = [];
let width = 0;
let height = 0;
for (let i = 0; i < count; i++) {
const framebuffer = pickDepths[i]?.framebuffer;
const raw = framebuffer?._framebuffer;
const texture = framebuffer?.getColorTexture?.(0);
const near = ranges[i]?.near * (i === 0 ? 1 : nearOffset);
const far = ranges[i]?.far;
if (!raw || !texture?._texture || !(near > 0) || !(far > near))
return null;
if (i === 0) {
width = texture.width;
height = texture.height;
} else if (texture.width !== width || texture.height !== height) {
return null;
}
framebuffers.push(raw);
textures.push(texture._texture);
frustums.push({ near, far });
}
if (!(width > 0) || !(height > 0)) return null;
// Read as standard depth, logarithmic depth puts every surface a few
// metres from the camera and would hide every contact: unknown is "no".
const logDepth = scene.frameState?.useLogDepth;
if (typeof logDepth !== 'boolean') return null;
const tanHalfFovY = Math.tan(fovy / 2);
return {
gl,
webgl2: context.webgl2 === true,
width,
height,
framebuffers,
textures,
frustums,
logDepth,
view: Cesium.Matrix4.toArray(
camera.viewMatrix,
viewScratch || new Float64Array(16),
),
tanHalfFovX: tanHalfFovY * aspectRatio,
tanHalfFovY,
};
} catch {
return null;
}
}
/**
* One point per contact. `a_contact` is (u, v, threshold): where the contact
* is in the frame, and the view distance a drawn surface must be under to hide
* it. A hidden contact's point is moved outside the clip volume, so nothing is
* drawn and its query reports no samples. A visible one lands on the single
* pixel of the 1x1 target (the viewport is set to match while these draw).
*/
export const PROBE_VERTEX_SHADER = `#version 300 es
precision highp float;
precision highp sampler2D;
layout(location = 0) in vec3 a_contact;
uniform sampler2D u_depth0;
uniform sampler2D u_depth1;
uniform sampler2D u_depth2;
uniform sampler2D u_depth3;
uniform int u_count;
uniform bool u_logDepth;
uniform vec4 u_near;
uniform vec4 u_far;
float viewDistance(sampler2D depthTexture, float near, float far) {
ivec2 size = textureSize(depthTexture, 0);
ivec2 texel = min(ivec2(a_contact.xy * vec2(size)), size - 1);
float depth = dot(
texelFetch(depthTexture, texel, 0),
vec4(1.0, 1.0 / 255.0, 1.0 / 65025.0, 1.0 / 16581375.0));
if (depth <= 0.0 || depth >= 1.0) return -1.0;
if (u_logDepth) return near + exp2(depth * log2(far - near + 1.0)) - 1.0;
return near * far / (far - depth * (far - near));
}
void main() {
float surface = viewDistance(u_depth0, u_near.x, u_far.x);
if (surface < 0.0 && u_count > 1) surface = viewDistance(u_depth1, u_near.y, u_far.y);
if (surface < 0.0 && u_count > 2) surface = viewDistance(u_depth2, u_near.z, u_far.z);
if (surface < 0.0 && u_count > 3) surface = viewDistance(u_depth3, u_near.w, u_far.w);
bool hidden = surface > 0.0 && surface < a_contact.z;
gl_Position = hidden ? vec4(2.0, 2.0, 2.0, 1.0) : vec4(0.0, 0.0, 0.0, 1.0);
gl_PointSize = 1.0;
}
`;
const FRAGMENT_SHADER = `#version 300 es
precision mediump float;
out vec4 color;
void main() { color = vec4(1.0); }
`;
function canQuery(gl) {
return (
typeof gl.createQuery === 'function' &&
typeof gl.beginQuery === 'function' &&
typeof gl.getQueryParameter === 'function' &&
typeof gl.createVertexArray === 'function'
);
}
function compile(gl, type, source) {
const shader = gl.createShader(type);
gl.shaderSource(shader, source);
gl.compileShader(shader);
if (!gl.getShaderParameter(shader, gl.COMPILE_STATUS)) {
gl.deleteShader(shader);
return null;
}
return shader;
}
/** Owns the GPU objects and the query batches in flight. */
export class SceneOcclusionProbe {
/**
* @param {{
* now?: () => number,
* readSource?: typeof readSceneDepthSource,
* }} [options]
*/
constructor({
now = () => performance.now(),
readSource = readSceneDepthSource,
} = {}) {
this._clock = now;
this._readSource = readSource;
/** Most tests one frame takes; read by whoever schedules them. */
this.maxPerFrame = PROBE_MAX_PER_FRAME;
/** `'async'` (queries), `'sync'` (blocking read), or `'off'`. */
this.mode = 'off';
/** Milliseconds the last frame spent collecting answers and drawing. */
this.lastFrameMs = 0;
/** Contact tests started in the last frame. */
this.lastFrameTests = 0;
this._scene = null;
this._now = 0;
this._source = undefined;
this._gl = null;
/** A context the probe's shader failed to build on; never retried. */
this._unsupportedGl = null;
this._resources = null;
this._queryPool = [];
this._batches = [];
this._attributes = new Float32Array((PROBE_MAX_PER_FRAME + 1) * 3);
this._queued = [];
this._projected = { u: 0, v: 0, threshold: 0 };
this._controlFailures = 0;
this._retryAt = Number.NEGATIVE_INFINITY;
this._frame = 0;
this._view = new Float64Array(16);
this._snapshot = null;
this._snapshotAt = Number.NEGATIVE_INFINITY;
this._spent = 0;
}
/**
* Open a frame: take in the answers that have arrived. Call after the scene
* has rendered (a post-render listener), before `add`.
* @param {Cesium.Scene} scene
* @param {number} now The caller's clock, in milliseconds. Answers are
* dated by it, so it must be the clock the caller judges their age on.
*/
beginFrame(scene, now) {
const started = this._clock();
this._scene = scene;
this._now = now;
this._frame++;
this._source = undefined;
// A frame that never reached `endFrame` leaves its contacts untested.
this._release(this._queued);
this._queued.length = 0;
this.lastFrameTests = 0;
this._collect();
this._spent = this._clock() - started;
}
/**
* Queue a contact for testing against the frame just drawn.
* @param {{lastHiddenAt: number, pending: boolean, answered: boolean}}
* contact Updated when the answer arrives: `pending` cleared, `answered`
* set and, if the contact was hidden, `lastHiddenAt` set to the time of
* the frame it was tested against.
* @param {{x: number, y: number, z: number}} position
* @returns {boolean} False when the contact cannot be tested now.
*/
add(contact, position) {
if (this._source === undefined) this._openSource();
const source = this._source;
if (!source) return false;
if (this.mode === 'sync') {
const hidden = this._snapshot?.hides(position);
if (hidden === null || hidden === undefined) return false;
contact.answered = true;
if (hidden) contact.lastHiddenAt = this._now;
this.lastFrameTests++;
return true;
}
const queued = this._queued;
if (queued.length >= PROBE_MAX_PER_FRAME) return false;
const projected = this._projected;
if (
!projectContact(
source.view,
source.tanHalfFovX,
source.tanHalfFovY,
position,
projected,
)
)
return false;
// Slot 0 is the control point; contacts start at 1.
const at = (queued.length + 1) * 3;
const attributes = this._attributes;
attributes[at] = projected.u;
attributes[at + 1] = projected.v;
attributes[at + 2] = projected.threshold;
queued.push(contact);
contact.pending = true;
this.lastFrameTests++;
return true;
}
/** Close the frame: draw the queued contacts' queries. */
endFrame() {
const started = this._clock();
if (this._queued.length > 0 && this._source && this.mode === 'async') {
try {
this._draw(this._source);
} catch {
this._release(this._queued);
this._fail();
}
}
this._queued.length = 0;
this._source = undefined;
this.lastFrameMs = this._spent + (this._clock() - started);
}
/**
* Drop every test in flight but keep the GPU objects, so that switching the
* overlay off and on again does not compile the shader a second time.
*/
reset() {
const gl = this._gl;
for (const batch of this._batches) this._release(batch.contacts);
this._release(this._queued);
try {
if (gl && !gl.isContextLost?.()) {
for (const batch of this._batches)
for (let i = batch.cursor; i < batch.queries.length; i++)
this._queryPool.push(batch.queries[i]);
}
} catch {
// A context that is going away has already released them.
}
this._batches.length = 0;
this._queued.length = 0;
this._source = undefined;
this._snapshot = null;
this._snapshotAt = Number.NEGATIVE_INFINITY;
this._controlFailures = 0;
this._retryAt = Number.NEGATIVE_INFINITY;
this.mode = 'off';
}
/** Delete the GPU objects and drop every test in flight. */
destroy() {
this.reset();
const gl = this._gl;
try {
if (gl && !gl.isContextLost?.()) {
for (const query of this._queryPool) gl.deleteQuery(query);
const resources = this._resources;
if (resources) {
gl.deleteProgram(resources.program);
gl.deleteVertexArray(resources.vertexArray);
gl.deleteBuffer(resources.buffer);
gl.deleteFramebuffer(resources.framebuffer);
gl.deleteTexture(resources.texture);
}
}
} catch {
// A context that is going away has already released them.
}
this._queryPool.length = 0;
this._resources = null;
this._gl = null;
this._unsupportedGl = null;
}
/** Tests that will never be answered stop counting as in flight. */
_release(contacts) {
for (const contact of contacts) if (contact) contact.pending = false;
}
/**
* Something in the query path broke: stand down for a while and keep
* everything drawn, then try again in case the cause was passing.
*/
_fail() {
this._retryAt = this._now + PROBE_RETRY_AFTER_MS;
this._controlFailures = 0;
this.mode = 'off';
}
/** Read this frame's depth source, once, when the first contact asks. */
_openSource() {
this._source = null;
if (this._now < this._retryAt) return;
const source = this._readSource(this._scene, this._view);
if (!source) {
this.mode = 'off';
return;
}
if (source.gl !== this._gl) {
// A different context (a rebuilt viewer) orphans whatever was in flight.
this.destroy();
this._gl = source.gl;
}
try {
if (source.gl.isContextLost?.()) {
// Everything made on the lost context went with it.
this.reset();
this._queryPool.length = 0;
this._resources = null;
return;
}
if (source.gl === this._unsupportedGl) {
// The shader did not build on this context: nothing is tested here.
this.mode = 'off';
return;
}
if (source.webgl2 && canQuery(source.gl)) {
if (!this._resources && !this._createResources(source.gl)) {
this._fail();
return;
}
this.mode = 'async';
} else {
this.mode = 'sync';
if (this._now - this._snapshotAt >= SYNC_READ_INTERVAL_MS) {
this._snapshot = this._readSync(source);
this._snapshotAt = this._now;
}
}
this._source = source;
} catch {
this._fail();
}
}
/**
* Compile the shader and make the 1x1 target. This is the one place the
* probe does wait on the GPU process (compile, link and framebuffer status
* are answered synchronously): once per WebGL context, on the first frame a
* depth-tested contact is in view. `reset` keeps the result.
*/
_createResources(gl) {
const vertex = compile(gl, gl.VERTEX_SHADER, PROBE_VERTEX_SHADER);
const fragment = compile(gl, gl.FRAGMENT_SHADER, FRAGMENT_SHADER);
if (!vertex || !fragment) {
if (vertex) gl.deleteShader(vertex);
if (fragment) gl.deleteShader(fragment);
// The same source will not compile on this context next time either.
this._unsupportedGl = gl;
return false;
}
const program = gl.createProgram();
gl.attachShader(program, vertex);
gl.attachShader(program, fragment);
gl.linkProgram(program);
gl.deleteShader(vertex);
gl.deleteShader(fragment);
if (!gl.getProgramParameter(program, gl.LINK_STATUS)) {
gl.deleteProgram(program);
this._unsupportedGl = gl;
return false;
}
const uniform = (name) => gl.getUniformLocation(program, name);
const previousArray = gl.getParameter(gl.VERTEX_ARRAY_BINDING);
const previousBuffer = gl.getParameter(gl.ARRAY_BUFFER_BINDING);
const previousTexture = gl.getParameter(gl.TEXTURE_BINDING_2D);
const previousDraw = gl.getParameter(gl.DRAW_FRAMEBUFFER_BINDING);
const vertexArray = gl.createVertexArray();
const buffer = gl.createBuffer();
gl.bindVertexArray(vertexArray);
gl.bindBuffer(gl.ARRAY_BUFFER, buffer);
gl.enableVertexAttribArray(0);
gl.vertexAttribPointer(0, 3, gl.FLOAT, false, 0, 0);
gl.bindVertexArray(previousArray);
gl.bindBuffer(gl.ARRAY_BUFFER, previousBuffer);
const texture = gl.createTexture();
const framebuffer = gl.createFramebuffer();
gl.bindTexture(gl.TEXTURE_2D, texture);
gl.texStorage2D(gl.TEXTURE_2D, 1, gl.RGBA8, 1, 1);
gl.bindTexture(gl.TEXTURE_2D, previousTexture);
gl.bindFramebuffer(gl.DRAW_FRAMEBUFFER, framebuffer);
gl.framebufferTexture2D(
gl.DRAW_FRAMEBUFFER,
gl.COLOR_ATTACHMENT0,
gl.TEXTURE_2D,
texture,
0,
);
const complete =
gl.checkFramebufferStatus(gl.DRAW_FRAMEBUFFER) ===
gl.FRAMEBUFFER_COMPLETE;
gl.bindFramebuffer(gl.DRAW_FRAMEBUFFER, previousDraw);
if (!complete) {
// Leave nothing half-made behind, so a later retry starts from scratch.
gl.deleteProgram(program);
gl.deleteVertexArray(vertexArray);
gl.deleteBuffer(buffer);
gl.deleteFramebuffer(framebuffer);
gl.deleteTexture(texture);
return false;
}
this._resources = {
program,
vertexArray,
buffer,
texture,
framebuffer,
depth: [0, 1, 2, 3].map((i) => uniform(`u_depth${i}`)),
count: uniform('u_count'),
logDepth: uniform('u_logDepth'),
near: uniform('u_near'),
far: uniform('u_far'),
};
return true;
}
/**
* Draw one query per queued contact, preceded by a control point that must
* always draw. The renderer caches the framebuffer, viewport and scissor
* state it last set, so those are put back exactly as found, along with
* every binding touched here. Depth, stencil, blending and the colour mask
* need no care: the target has no depth or stencil attachment, and a query
* counts samples whether or not they are written.
*/
_draw(source) {
const gl = source.gl;
const resources = this._resources;
const contacts = this._queued.slice();
const count = contacts.length + 1;
const attributes = this._attributes;
// The control point: mid-frame, with a threshold nothing can be under.
attributes[0] = 0.5;
attributes[1] = 0.5;
attributes[2] = -1;
const layers = source.textures.length;
const frustums = source.frustums;
const previousProgram = gl.getParameter(gl.CURRENT_PROGRAM);
const previousArray = gl.getParameter(gl.VERTEX_ARRAY_BINDING);
const previousBuffer = gl.getParameter(gl.ARRAY_BUFFER_BINDING);
const previousDraw = gl.getParameter(gl.DRAW_FRAMEBUFFER_BINDING);
const previousUnit = gl.getParameter(gl.ACTIVE_TEXTURE);
const previousViewport = gl.getParameter(gl.VIEWPORT);
const previousTextures = [];
const scissor = gl.isEnabled(gl.SCISSOR_TEST);
const queries = [];
const pool = this._queryPool;
let open = false;
try {
for (let i = 0; i < layers; i++) {
gl.activeTexture(gl.TEXTURE0 + i);
previousTextures.push(gl.getParameter(gl.TEXTURE_BINDING_2D));
gl.bindTexture(gl.TEXTURE_2D, source.textures[i]);
}
if (scissor) gl.disable(gl.SCISSOR_TEST);
gl.bindFramebuffer(gl.DRAW_FRAMEBUFFER, resources.framebuffer);
gl.viewport(0, 0, 1, 1);
gl.useProgram(resources.program);
// Samplers past the ranges in use point at the first range's texture:
// every sampler a program declares must be drawable, read or not.
for (let i = 0; i < PROBE_MAX_FRUSTUMS; i++)
gl.uniform1i(resources.depth[i], i < layers ? i : 0);
gl.uniform1i(resources.count, layers);
gl.uniform1i(resources.logDepth, source.logDepth ? 1 : 0);
gl.uniform4f(
resources.near,
frustums[0].near,
frustums[1]?.near ?? 1,
frustums[2]?.near ?? 1,
frustums[3]?.near ?? 1,
);
gl.uniform4f(
resources.far,
frustums[0].far,
frustums[1]?.far ?? 2,
frustums[2]?.far ?? 2,
frustums[3]?.far ?? 2,
);
gl.bindVertexArray(resources.vertexArray);
gl.bindBuffer(gl.ARRAY_BUFFER, resources.buffer);
gl.bufferData(
gl.ARRAY_BUFFER,
attributes.subarray(0, count * 3),
gl.STREAM_DRAW,
);
for (let i = 0; i < count; i++) {
const query = pool.pop() || gl.createQuery();
queries.push(query);
gl.beginQuery(gl.ANY_SAMPLES_PASSED_CONSERVATIVE, query);
open = true;
gl.drawArrays(gl.POINTS, i, 1);
gl.endQuery(gl.ANY_SAMPLES_PASSED_CONSERVATIVE);
open = false;
}
} catch (error) {
// Leave no query open and none unaccounted for; the caller stands down.
try {
if (open) gl.endQuery(gl.ANY_SAMPLES_PASSED_CONSERVATIVE);
for (const query of queries) gl.deleteQuery(query);
} catch {
// Nothing more can be done for them.
}
throw error;
} finally {
gl.bindBuffer(gl.ARRAY_BUFFER, previousBuffer);
gl.bindVertexArray(previousArray);
gl.useProgram(previousProgram);
gl.bindFramebuffer(gl.DRAW_FRAMEBUFFER, previousDraw);
if (previousViewport)
gl.viewport(
previousViewport[0],
previousViewport[1],
previousViewport[2],
previousViewport[3],
);
if (scissor) gl.enable(gl.SCISSOR_TEST);
for (let i = previousTextures.length - 1; i >= 0; i--) {
gl.activeTexture(gl.TEXTURE0 + i);
gl.bindTexture(gl.TEXTURE_2D, previousTextures[i]);
}
gl.activeTexture(previousUnit);
}
this._batches.push({
queries,
contacts,
at: this._now,
frame: this._frame,
cursor: 0,
control: false,
});
}
/**
* Take in whatever answers have arrived, oldest batch first, without
* waiting for any that have not. An answer is dated to the frame its test
* was drawn on, so one that arrives late (the overlay was not painting for
* a while) is as stale as it is old.
*/
_collect() {
const batches = this._batches;
if (batches.length === 0) return;
const gl = this._gl;
try {
if (gl.isContextLost?.()) {
// Queries made on a lost context are gone with it.
this.reset();
this._queryPool.length = 0;
this._resources = null;
return;
}
while (batches.length > 0) {
const batch = batches[0];
const { queries, contacts } = batch;
while (batch.cursor < queries.length) {
const query = queries[batch.cursor];
if (!gl.getQueryParameter(query, gl.QUERY_RESULT_AVAILABLE)) break;
const drew = !!gl.getQueryParameter(query, gl.QUERY_RESULT);
if (batch.cursor === 0) {
batch.control = drew;
} else {
const contact = contacts[batch.cursor - 1];
contact.pending = false;
// Without the control point's yes the batch means nothing: not a
// "hidden", and not a first answer that ends a new contact's
// hold-back either.
if (batch.control) {
contact.answered = true;
if (!drew && batch.at > contact.lastHiddenAt)
contact.lastHiddenAt = batch.at;
}
}
this._queryPool.push(query);
batch.cursor++;
}
if (batch.cursor < queries.length) break;
batches.shift();
if (batch.control) {
this._controlFailures = 0;
} else if (++this._controlFailures >= PROBE_MAX_CONTROL_FAILURES) {
this._fail();
}
}
// Whatever is still unanswered after too many frames is dropped,
// wherever it stands in the queue, so its contacts can be tested again.
const overdue = this._frame - PROBE_MAX_PENDING_FRAMES;
for (let i = batches.length - 1; i >= 0; i--) {
const batch = batches[i];
if (batch.frame >= overdue) continue;
for (let k = batch.cursor; k < batch.queries.length; k++)
gl.deleteQuery(batch.queries[k]);
for (
let k = Math.max(0, batch.cursor - 1);
k < batch.contacts.length;
k++
)
batch.contacts[k].pending = false;
batches.splice(i, 1);
}
} catch {
for (const batch of batches) this._release(batch.contacts);
batches.length = 0;
this._fail();
}
}
/**
* No queries (WebGL 1): read each depth range at full size and wait for it.
* Costs milliseconds per read; used only where nothing better exists.
*/
_readSync(source) {
const gl = source.gl;
const { width, height } = source;
const layers = source.framebuffers.length;
const layerBytes = width * height * 4;
const byteLength = layerBytes * layers;
const bytes =
this._snapshot?.bytes.length === byteLength
? this._snapshot.bytes
: new Uint8Array(byteLength);
const previous = gl.getParameter(gl.FRAMEBUFFER_BINDING);
for (let i = 0; i < layers; i++) {
gl.bindFramebuffer(gl.FRAMEBUFFER, source.framebuffers[i]);
gl.readPixels(
0,
0,
width,
height,
gl.RGBA,
gl.UNSIGNED_BYTE,
bytes.subarray(i * layerBytes, (i + 1) * layerBytes),
);
}
gl.bindFramebuffer(gl.FRAMEBUFFER, previous);
return new DepthSnapshot({
width,
height,
bytes,
frustums: source.frustums,
logDepth: source.logDepth,
// The source's matrix is a scratch array the next frame overwrites.
view: Float64Array.from(source.view),
tanHalfFovX: source.tanHalfFovX,
tanHalfFovY: source.tanHalfFovY,
});
}
}
+688
View File
@@ -0,0 +1,688 @@
import test from 'node:test';
import assert from 'node:assert/strict';
import * as Cesium from 'cesium';
import {
PROBE_MAX_CONTROL_FAILURES,
PROBE_MAX_FRUSTUMS,
PROBE_MAX_PENDING_FRAMES,
PROBE_MAX_PER_FRAME,
PROBE_RETRY_AFTER_MS,
PROBE_VERTEX_SHADER,
SYNC_READ_INTERVAL_MS,
SceneOcclusionProbe,
readSceneDepthSource,
} from './sceneOcclusionProbe.js';
import {
createFakeDepthScene,
createFakeGl,
depthImage,
viewDistanceToDepth,
} from './fixtures/fakeDepthScene.mjs';
const NEAR = 1;
const FAR = 100_000;
/** Left half a wall 400 m away, right half ground 500 m away. */
function wallImage(width, height, logDepth = true, wall = 400) {
return depthImage(width, height, (column) =>
viewDistanceToDepth(column < width / 2 ? wall : 500, NEAR, FAR, logDepth),
);
}
function wallScene({ width = 64, height = 32, logDepth = true, gl } = {}) {
return createFakeDepthScene({
gl,
logDepth,
aspectRatio: width / height,
ranges: [
{ near: NEAR, far: FAR, image: wallImage(width, height, logDepth) },
],
});
}
const behindWall = { x: -250, y: 0, z: -500 };
const onStreet = { x: 250, y: 0, z: -500 };
const contact = () => ({
lastHiddenAt: Number.NEGATIVE_INFINITY,
pending: false,
});
/** One frame: collect, queue the given contacts, draw. */
function frame(probe, scene, now, tests = []) {
probe.beginFrame(scene, now);
const accepted = tests.map(([entry, position]) => probe.add(entry, position));
probe.endFrame();
return accepted;
}
test('a test is drawn at once and answered on a later frame, without anything being read back', () => {
const scene = wallScene();
const gl = scene.context._gl;
const probe = new SceneOcclusionProbe();
const hidden = contact();
const shown = contact();
assert.equal(probe.mode, 'off');
assert.deepEqual(
frame(probe, scene, 1000, [
[hidden, behindWall],
[shown, onStreet],
]),
[true, true],
);
assert.equal(probe.mode, 'async');
assert.equal(probe.lastFrameTests, 2);
assert.equal(hidden.pending, true);
assert.equal(
gl.counts.queries,
3,
'the control point and one query per contact',
);
assert.equal(gl.counts.draws, 3);
// Frames pass before the GPU has answered: nothing changes, nothing waits.
frame(probe, scene, 1016);
frame(probe, scene, 1032);
assert.equal(hidden.pending, true);
assert.equal(hidden.lastHiddenAt, Number.NEGATIVE_INFINITY);
assert.equal(gl.counts.resultReads, 0);
assert.equal(gl.counts.readPixels, 0);
gl.finishGpu();
frame(probe, scene, 1048);
assert.equal(hidden.pending, false);
assert.equal(shown.pending, false);
assert.equal(hidden.answered, true);
assert.equal(shown.answered, true);
assert.equal(hidden.lastHiddenAt, 1000, 'dated to its test frame');
assert.equal(shown.lastHiddenAt, Number.NEGATIVE_INFINITY);
assert.equal(gl.counts.readPixels, 0, 'depth never leaves the GPU');
});
test('queries are reused, and every depth range is tested nearest first', () => {
const width = 64;
const height = 32;
const farNear = 900;
const farFar = 5_000_000;
const scene = createFakeDepthScene({
aspectRatio: 2,
ranges: [
// Near range: the wall on the left, nothing drawn on the right.
{
near: NEAR,
far: 1000,
image: depthImage(width, height, (column) =>
column < width / 2 ? viewDistanceToDepth(400, NEAR, 1000, true) : 1,
),
},
// Far range: ground 20 km away, drawn with its near plane pulled in.
{
near: farNear,
far: farFar,
image: depthImage(width, height, () =>
viewDistanceToDepth(20_000, farNear * 0.9999, farFar, true),
),
},
],
});
const gl = scene.context._gl;
const probe = new SceneOcclusionProbe();
const cases = [
[contact(), { x: -7500, y: 0, z: -15_000 }, true], // behind the near wall
[contact(), { x: 7500, y: 0, z: -15_000 }, false], // above the far ground
[contact(), { x: 15_000, y: 0, z: -30_000 }, true], // under the far ground
[contact(), { x: -150, y: 0, z: -300 }, false], // in front of the wall
];
for (let round = 0; round < 3; round++) {
frame(
probe,
scene,
round * 100,
cases.map(([entry, position]) => [entry, position]),
);
gl.finishGpu();
frame(probe, scene, round * 100 + 16);
for (const [entry, , hidden] of cases) {
assert.equal(entry.pending, false);
assert.equal(entry.lastHiddenAt === round * 100, hidden);
}
}
assert.equal(gl.liveQueries.size, 5, 'five queries serve every round');
const source = readSceneDepthSource(scene);
assert.equal(source.frustums[1].near, farNear * 0.9999);
});
test('standard depth scenes are tested too', () => {
const scene = wallScene({ logDepth: false });
const probe = new SceneOcclusionProbe();
const hidden = contact();
const shown = contact();
frame(probe, scene, 0, [
[hidden, behindWall],
[shown, onStreet],
]);
scene.context._gl.finishGpu();
frame(probe, scene, 16);
assert.equal(hidden.lastHiddenAt, 0);
assert.equal(shown.lastHiddenAt, Number.NEGATIVE_INFINITY);
});
test('every binding the renderer relies on is left as found', () => {
const scene = wallScene();
const gl = scene.context._gl;
const found = {
read: { image: null },
draw: { image: null },
units: [{}, {}, {}, {}, {}, {}, {}, {}],
unit: 5,
array: {},
vertexArray: {},
program: { uniforms: {} },
scissor: true,
viewport: [12, 34, 640, 480],
};
Object.assign(gl.state, found, { units: [...found.units] });
const probe = new SceneOcclusionProbe();
const hidden = contact();
frame(probe, scene, 0, [[hidden, behindWall]]);
for (const key of [
'read',
'draw',
'unit',
'array',
'vertexArray',
'program',
'scissor',
])
assert.equal(gl.state[key], found[key], key);
assert.deepEqual(gl.state.units, found.units);
assert.deepEqual(gl.state.viewport, [12, 34, 640, 480]);
// The scissor test and the offset viewport would both have kept the points
// off the target, so neither was in force for them: the control point drew,
// and the answer counts.
gl.finishGpu();
frame(probe, scene, 16);
assert.equal(hidden.lastHiddenAt, 0);
assert.equal(gl.state.scissor, true);
});
test('a contact outside the frame, or past the frame budget, is not taken', () => {
const scene = wallScene();
const probe = new SceneOcclusionProbe();
probe.beginFrame(scene, 0);
const outside = contact();
assert.equal(probe.add(outside, { x: -1100, y: 0, z: -500 }), false);
assert.equal(probe.add(outside, { x: 0, y: 0, z: 500 }), false);
assert.equal(outside.pending, false);
const taken = [];
for (let i = 0; i < PROBE_MAX_PER_FRAME + 10; i++)
taken.push(probe.add(contact(), onStreet));
probe.endFrame();
assert.equal(taken.filter(Boolean).length, PROBE_MAX_PER_FRAME);
assert.equal(taken.lastIndexOf(true), PROBE_MAX_PER_FRAME - 1);
assert.equal(scene.context._gl.counts.queries, PROBE_MAX_PER_FRAME + 1);
});
test('a frame with nothing to test touches nothing', () => {
let reads = 0;
const probe = new SceneOcclusionProbe({
readSource: () => {
reads++;
return null;
},
});
frame(probe, {}, 0);
frame(probe, {}, 16);
assert.equal(reads, 0);
assert.equal(probe.lastFrameTests, 0);
});
test('no depth source: nothing is tested and nothing is in flight', () => {
const broken = [
null,
{},
{ ...wallScene(), mode: Cesium.SceneMode.SCENE2D },
{ ...wallScene(), mode: Cesium.SceneMode.COLUMBUS_VIEW },
{ ...wallScene(), useDepthPicking: false },
{ ...wallScene(), _environmentState: { useGlobeDepthFramebuffer: false } },
{ ...wallScene(), view: { frustumCommandsList: [], pickDepths: [] } },
{ ...wallScene(), view: undefined },
(() => {
const scene = wallScene();
scene.context.depthTexture = false;
return scene;
})(),
(() => {
const scene = wallScene();
scene.camera.frustum = { width: 1000, aspectRatio: 2 }; // orthographic
return scene;
})(),
(() => {
const scene = wallScene();
scene.camera.frustum.xOffset = 10;
return scene;
})(),
(() => {
const scene = wallScene();
scene.view.pickDepths[0].framebuffer = undefined; // not drawn yet
return scene;
})(),
// Whether depth is logarithmic, unknown: decoding it the wrong way would
// put every surface in front of every contact.
{ ...wallScene(), frameState: {} },
{ ...wallScene(), frameState: { useLogDepth: 1 } },
{ ...wallScene(), frameState: undefined },
(() => {
const scene = wallScene();
Object.defineProperty(scene, 'view', {
get() {
throw new Error('renderer changed shape');
},
});
return scene;
})(),
];
for (const scene of broken) {
assert.equal(readSceneDepthSource(scene), null);
const probe = new SceneOcclusionProbe();
const entry = contact();
assert.deepEqual(frame(probe, scene, 0, [[entry, behindWall]]), [false]);
assert.equal(probe.mode, 'off');
assert.equal(entry.pending, false);
}
});
test('depth that comes and goes is picked up frame by frame', () => {
const scene = wallScene();
const gl = scene.context._gl;
const probe = new SceneOcclusionProbe();
const entry = contact();
scene.useDepthPicking = false;
assert.deepEqual(frame(probe, scene, 0, [[entry, behindWall]]), [false]);
assert.equal(probe.mode, 'off');
scene.useDepthPicking = true;
assert.deepEqual(frame(probe, scene, 16, [[entry, behindWall]]), [true]);
assert.equal(probe.mode, 'async');
gl.finishGpu();
frame(probe, scene, 32);
assert.equal(entry.lastHiddenAt, 16);
});
test('depth ranges past the limit are left out, nearest kept', () => {
const image = wallImage(8, 8);
const ranges = [];
for (let i = 0; i < PROBE_MAX_FRUSTUMS + 2; i++)
ranges.push({ near: 10 ** i, far: 10 ** (i + 1), image });
const source = readSceneDepthSource(createFakeDepthScene({ ranges }));
assert.equal(source.frustums.length, PROBE_MAX_FRUSTUMS);
assert.equal(source.textures.length, PROBE_MAX_FRUSTUMS);
assert.equal(source.frustums[0].near, 1);
});
test('a control point that does not draw voids its batch; a run of them stands the probe down for a while', () => {
const scene = wallScene();
const gl = scene.context._gl;
const probe = new SceneOcclusionProbe();
// Something outside the probe's reach stops every point from drawing, so
// every query reads "nothing drew", which would otherwise mean "hidden".
gl.state.drawsLand = false;
let now = 0;
for (let i = 0; i < PROBE_MAX_CONTROL_FAILURES; i++) {
const entry = contact();
assert.deepEqual(frame(probe, scene, now, [[entry, behindWall]]), [true]);
gl.finishGpu();
now += 16;
frame(probe, scene, now);
assert.equal(entry.pending, false);
assert.equal(entry.lastHiddenAt, Number.NEGATIVE_INFINITY, 'not believed');
assert.notEqual(entry.answered, true, 'and not a first answer either');
now += 16;
}
assert.equal(probe.mode, 'off');
const stoodDownAt = now - 16;
assert.deepEqual(frame(probe, scene, now, [[contact(), behindWall]]), [
false,
]);
assert.deepEqual(
frame(probe, scene, stoodDownAt + PROBE_RETRY_AFTER_MS - 1, [
[contact(), behindWall],
]),
[false],
);
// The cause has passed: the probe picks up where it left off.
gl.state.drawsLand = true;
const entry = contact();
const retryAt = stoodDownAt + PROBE_RETRY_AFTER_MS;
assert.deepEqual(frame(probe, scene, retryAt, [[entry, behindWall]]), [true]);
assert.equal(probe.mode, 'async');
gl.finishGpu();
frame(probe, scene, retryAt + 16);
assert.equal(entry.lastHiddenAt, retryAt);
assert.equal(entry.answered, true);
// One good batch in between resets the count.
const healthy = new SceneOcclusionProbe();
const other = wallScene();
for (let i = 0; i < 6; i++) {
other.context._gl.state.drawsLand = i % 2 === 1;
frame(healthy, other, i * 32, [[contact(), onStreet]]);
other.context._gl.finishGpu();
frame(healthy, other, i * 32 + 16);
}
assert.equal(healthy.mode, 'async');
});
test('a shader that does not compile, or a WebGL call that throws, stands the probe down cleanly', () => {
let scene = wallScene();
// Only the fragment shader fails: the vertex shader that did compile must
// not be left behind.
scene.context._gl.state.compiles = (type) =>
type !== scene.context._gl.FRAGMENT_SHADER;
let probe = new SceneOcclusionProbe();
let entry = contact();
assert.deepEqual(frame(probe, scene, 0, [[entry, behindWall]]), [false]);
assert.equal(probe.mode, 'off');
assert.equal(entry.pending, false);
// Nothing half-made is kept, and the same context is never asked again:
// compiling is a wait on the GPU process and would fail the same way.
let gl = scene.context._gl;
assert.equal(gl.liveShaders.size, 0, 'no shader left behind');
let shaderCalls = 0;
const createShader = gl.createShader;
gl.createShader = (...args) => {
shaderCalls++;
return createShader(...args);
};
for (const now of [PROBE_RETRY_AFTER_MS + 16, 5 * PROBE_RETRY_AFTER_MS])
assert.deepEqual(frame(probe, scene, now, [[entry, behindWall]]), [false]);
assert.equal(shaderCalls, 0);
assert.equal(probe.mode, 'off');
// A draw that throws part-way: bindings restored, no query left behind.
scene = wallScene();
gl = scene.context._gl;
const found = {
draw: { image: null },
program: { uniforms: {} },
viewport: [0, 0, 800, 600],
};
Object.assign(gl.state, found, { scissor: true });
let draws = 0;
const drawArrays = gl.drawArrays;
gl.drawArrays = (...args) => {
if (++draws === 2) throw new Error('driver');
return drawArrays(...args);
};
probe = new SceneOcclusionProbe();
entry = contact();
const other = contact();
assert.deepEqual(
frame(probe, scene, 0, [
[entry, behindWall],
[other, onStreet],
]),
[true, true],
);
assert.equal(entry.pending, false, 'released when the draw failed');
assert.equal(other.pending, false);
assert.equal(probe.mode, 'off');
assert.equal(gl.state.draw, found.draw);
assert.equal(gl.state.program, found.program);
assert.deepEqual(gl.state.viewport, found.viewport);
assert.equal(gl.state.scissor, true);
assert.equal(gl.liveQueries.size, 0);
assert.deepEqual(frame(probe, scene, 16, [[entry, behindWall]]), [false]);
scene = wallScene();
gl = scene.context._gl;
probe = new SceneOcclusionProbe();
entry = contact();
frame(probe, scene, 0, [[entry, behindWall]]);
gl.getQueryParameter = () => {
throw new Error('driver');
};
frame(probe, scene, 16);
assert.equal(entry.pending, false);
assert.equal(probe.mode, 'off');
});
test('a frame that never reaches its end leaves no contact waiting for an answer', () => {
const scene = wallScene();
const probe = new SceneOcclusionProbe();
const entry = contact();
probe.beginFrame(scene, 0);
assert.equal(probe.add(entry, behindWall), true);
assert.equal(entry.pending, true);
// The painter threw before endFrame; the next frame starts clean.
probe.beginFrame(scene, 16);
assert.equal(entry.pending, false);
assert.equal(probe.add(entry, behindWall), true);
probe.endFrame();
assert.equal(
scene.context._gl.counts.queries,
2,
'only the second frame drew',
);
});
test('an answer collected late is dated to its test, not to its arrival', () => {
const scene = wallScene();
const gl = scene.context._gl;
const probe = new SceneOcclusionProbe();
const entry = contact();
frame(probe, scene, 1000, [[entry, behindWall]]);
gl.finishGpu();
// The overlay paints nothing for 20 seconds, then resumes.
frame(probe, scene, 21_000);
assert.equal(entry.pending, false);
assert.equal(entry.lastHiddenAt, 1000);
// An older answer never overwrites a newer one.
entry.lastHiddenAt = 30_000;
frame(probe, scene, 22_000, [[entry, behindWall]]);
gl.finishGpu();
frame(probe, scene, 22_016);
assert.equal(entry.lastHiddenAt, 30_000);
});
test('samplers for depth ranges not in use point at a texture that is bound', () => {
const scene = wallScene();
const gl = scene.context._gl;
// Whatever the renderer left on the other units is not the probe's to read.
gl.state.units = [null, null, null, null, null, null, null, null];
const probe = new SceneOcclusionProbe();
const entry = contact();
frame(probe, scene, 0, [[entry, behindWall]]);
gl.finishGpu();
frame(probe, scene, 16);
assert.equal(
entry.lastHiddenAt,
0,
'the draw was valid, so the answer counts',
);
assert.deepEqual(gl.state.units, [
null,
null,
null,
null,
null,
null,
null,
null,
]);
});
test('reset drops tests in flight but keeps the GPU objects for next time', () => {
const scene = wallScene();
const gl = scene.context._gl;
const probe = new SceneOcclusionProbe();
const entry = contact();
frame(probe, scene, 0, [[entry, behindWall]]);
probe.reset();
assert.equal(entry.pending, false);
assert.equal(probe.mode, 'off');
assert.equal(gl.counts.deleted, 0);
gl.finishGpu();
frame(probe, scene, 16);
assert.equal(
entry.lastHiddenAt,
Number.NEGATIVE_INFINITY,
'the dropped answer is not applied',
);
frame(probe, scene, 32, [[entry, behindWall]]);
assert.equal(probe.mode, 'async');
assert.equal(gl.liveQueries.size, 2, 'queries are reused, not recreated');
});
test('a lost context drops what was in flight and starts over when it returns', () => {
const scene = wallScene();
const gl = scene.context._gl;
const probe = new SceneOcclusionProbe();
const entry = contact();
frame(probe, scene, 0, [[entry, behindWall]]);
gl.state.lost = true;
assert.deepEqual(frame(probe, scene, 16, [[contact(), behindWall]]), [false]);
assert.equal(entry.pending, false);
assert.equal(probe.mode, 'off');
gl.state.lost = false;
assert.deepEqual(frame(probe, scene, 32, [[entry, behindWall]]), [true]);
gl.finishGpu();
frame(probe, scene, 48);
assert.equal(entry.lastHiddenAt, 32);
});
test('queries that are never answered are abandoned', () => {
const scene = wallScene();
const gl = scene.context._gl;
const probe = new SceneOcclusionProbe();
const entry = contact();
frame(probe, scene, 0, [[entry, behindWall]]);
for (let i = 1; i <= PROBE_MAX_PENDING_FRAMES; i++)
frame(probe, scene, i * 16);
assert.equal(entry.pending, true);
frame(probe, scene, (PROBE_MAX_PENDING_FRAMES + 1) * 16);
assert.equal(entry.pending, false);
assert.equal(entry.lastHiddenAt, Number.NEGATIVE_INFINITY);
assert.equal(gl.liveQueries.size, 0);
assert.equal(probe.mode, 'async', 'and the next contact is tested as usual');
});
test('every batch times out on its own, however many are queued ahead of it', () => {
const scene = wallScene();
const gl = scene.context._gl;
const probe = new SceneOcclusionProbe();
const entries = [];
// Ten frames each start a batch; the GPU answers none of them.
for (let i = 0; i < 10; i++) {
const entry = contact();
entries.push(entry);
frame(probe, scene, i * 16, [[entry, behindWall]]);
}
for (let i = 10; i <= PROBE_MAX_PENDING_FRAMES; i++)
frame(probe, scene, i * 16);
assert.ok(entries.every((entry) => entry.pending));
// Ten more frames and all ten have been dropped, not one every 120 frames.
for (let i = 1; i <= 10; i++)
frame(probe, scene, (PROBE_MAX_PENDING_FRAMES + i) * 16);
assert.ok(entries.every((entry) => !entry.pending));
assert.equal(gl.liveQueries.size, 0);
});
test('a target that cannot be made leaves nothing behind, and the next try starts from scratch', () => {
const scene = wallScene();
const gl = scene.context._gl;
const complete = gl.checkFramebufferStatus;
gl.checkFramebufferStatus = () => 0;
const probe = new SceneOcclusionProbe();
const entry = contact();
assert.deepEqual(frame(probe, scene, 0, [[entry, behindWall]]), [false]);
assert.equal(probe.mode, 'off');
assert.equal(gl.counts.deleted, 5, 'program, array, buffer, target');
// Memory pressure passes; after the stand-down the probe builds it all again.
gl.checkFramebufferStatus = complete;
assert.deepEqual(
frame(probe, scene, PROBE_RETRY_AFTER_MS, [[entry, behindWall]]),
[true],
);
assert.equal(probe.mode, 'async');
gl.finishGpu();
frame(probe, scene, PROBE_RETRY_AFTER_MS + 16);
assert.equal(entry.lastHiddenAt, PROBE_RETRY_AFTER_MS);
});
test('a new WebGL context, or destroy, releases everything', () => {
const probe = new SceneOcclusionProbe();
const first = wallScene();
const entry = contact();
frame(probe, first, 0, [[entry, behindWall]]);
const second = wallScene();
const again = contact();
assert.deepEqual(frame(probe, second, 16, [[again, behindWall]]), [true]);
assert.equal(entry.pending, false, 'the first context will never answer');
assert.equal(first.context._gl.liveQueries.size, 0);
assert.equal(
first.context._gl.counts.deleted,
5,
'program, array, buffer, target',
);
probe.destroy();
assert.equal(again.pending, false);
assert.equal(second.context._gl.liveQueries.size, 0);
assert.equal(probe.mode, 'off');
});
test('without queries (WebGL 1) depth is read back synchronously, at most every interval, and the mode says so', () => {
const gl = createFakeGl({ webgl2: false });
const scene = wallScene({ gl });
assert.equal(scene.context.webgl2, false);
const sceneFramebuffer = { image: null };
gl.state.read = sceneFramebuffer;
gl.state.draw = sceneFramebuffer;
const probe = new SceneOcclusionProbe();
const hidden = contact();
const shown = contact();
assert.deepEqual(
frame(probe, scene, 1000, [
[hidden, behindWall],
[shown, onStreet],
[contact(), { x: -1100, y: 0, z: -500 }],
]),
[true, true, false],
);
assert.equal(probe.mode, 'sync');
assert.equal(gl.counts.readPixels, 1);
assert.equal(gl.state.read, sceneFramebuffer);
assert.equal(gl.state.draw, sceneFramebuffer);
assert.equal(hidden.lastHiddenAt, 1000, 'answered on the spot');
assert.equal(hidden.pending, false);
assert.equal(shown.answered, true);
assert.equal(shown.lastHiddenAt, Number.NEGATIVE_INFINITY);
// Frames inside the interval answer from the read already made.
frame(probe, scene, 1000 + SYNC_READ_INTERVAL_MS - 1, [[hidden, behindWall]]);
assert.equal(gl.counts.readPixels, 1);
assert.equal(hidden.lastHiddenAt, 1000 + SYNC_READ_INTERVAL_MS - 1);
frame(probe, scene, 1000 + SYNC_READ_INTERVAL_MS, [[hidden, behindWall]]);
assert.equal(gl.counts.readPixels, 2);
});
test('the shader decodes depth the way the CPU decode does', () => {
// The fake context stands in for the shader, so pin the parts of the source
// the two must agree on: the unpack weights, both depth formulas, the
// nearest-range-first order and the comparison.
const source = PROBE_VERTEX_SHADER.replace(/\s+/g, ' ');
assert.match(
source,
/vec4\(1\.0, 1\.0 \/ 255\.0, 1\.0 \/ 65025\.0, 1\.0 \/ 16581375\.0\)/,
);
assert.match(source, /if \(depth <= 0\.0 \|\| depth >= 1\.0\) return -1\.0;/);
assert.match(
source,
/near \+ exp2\(depth \* log2\(far - near \+ 1\.0\)\) - 1\.0/,
);
assert.match(source, /near \* far \/ \(far - depth \* \(far - near\)\)/);
assert.match(
source,
/bool hidden = surface > 0\.0 && surface < a_contact\.z;/,
);
assert.ok(
source.indexOf('u_depth0, u_near.x') < source.indexOf('u_depth1, u_near.y'),
);
});
+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 for near-plane-clamped contact sprite collections. */
export const SPRITE_LAYER_ORDER = Object.freeze([
'shipwrecks',
'cctv',
'firms',
'wildlife-sightings',
+607
View File
@@ -0,0 +1,607 @@
/**
* @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 * as Cesium from 'cesium';
/** @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 {Cesium.Cartesian3} a
* @param {Cesium.Cartesian3} b
* @returns {number}
*/
export function trailDistanceM(a, b) {
return Cesium.Cartesian3.angleBetween(a, b) * 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: Cesium.Cartesian3|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 {Cesium.Cartesian3|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 &&
Cesium.Cartesian3.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 {Cesium.Cartesian3[][]}
*/
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 {Cesium.Cartesian3[][]} 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 {Cesium.Cartesian3} 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 (Cesium.Cartesian3.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 ? Cesium.JulianDate.toDate(fix.time).getTime() : 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;
const _u = new Cesium.Cartesian3();
const _v = new Cesium.Cartesian3();
/** Cosine of the turn at `b` on the way a → b → c, or NaN for a zero step. */
function turnCos(a, b, c) {
Cesium.Cartesian3.subtract(b, a, _u);
Cesium.Cartesian3.subtract(c, b, _v);
const lu = Cesium.Cartesian3.magnitude(_u);
const lv = Cesium.Cartesian3.magnitude(_v);
if (!(lu > 0 && lv > 0)) return NaN;
return Cesium.Cartesian3.dot(_u, _v) / (lu * lv);
}
const SPUR_COS = Math.cos(Cesium.Math.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(
Cesium.Cartesian3.distance(a, b),
Cesium.Cartesian3.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;
}
const _ab = new Cesium.Cartesian3();
const _ap = new Cesium.Cartesian3();
const _off = new Cesium.Cartesian3();
const _up = new Cesium.Cartesian3();
/** Whether `p` lies within the thinning tolerance of segment a → b, across the track and in height. */
function nearSegment(p, a, b) {
Cesium.Cartesian3.subtract(b, a, _ab);
Cesium.Cartesian3.subtract(p, a, _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.multiplyByScalar(_ab, t, _off);
Cesium.Cartesian3.subtract(_ap, _off, _off);
Cesium.Cartesian3.normalize(p, _up);
const vertical = Cesium.Cartesian3.dot(_off, _up);
const across = Math.sqrt(
Math.max(0, Cesium.Cartesian3.magnitudeSquared(_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 (Cesium.Cartesian3.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 {Cesium.Cartesian3} 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 {Cesium.Cartesian3} 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 &&
Cesium.Cartesian3.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));
}
+269 -58
View File
@@ -14,6 +14,18 @@
* the whole history renders at one readable alpha (dimmer where it passes
* behind/below geometry).
*
* A trail with breaks draws each segment separately and nothing between
* them. Every segment is cut into chunks of up to CHUNK_POINTS points;
* adjacent chunks share their boundary point, so the line has no seam. A
* chunk that can no longer change (every chunk except the newest one of the
* newest segment) is FROZEN: an entity with constant positions, built once as
* static geometry, so it costs nothing per frame. Only the newest chunk stays
* dynamic. A freshly frozen chunk is also drawn dynamically until its static
* geometry is in the scene, so freezing never shows a blank frame. A chunk is
* identified by its position objects, so a chunk survives every update that
* keeps those points: appends, a backfill prepended ahead of it, or the
* oldest points dropping off the front (which rebuilds only the first chunk).
*
* Trails update at poll cadence (~15-60 s) plus once on history backfill, so
* assigning a fresh positions array per update is cheap. `allowPicking` has
* no entity equivalent; the polyline entity is excluded from clicks by never
@@ -42,6 +54,13 @@ const TRAIL_ALPHA = 0.85;
const TRAIL_OCCLUDED_ALPHA = 0.4;
/** @constant {number} Squared distance (m^2) below which consecutive points are merged. */
const MIN_SEGMENT_DISTANCE_SQ = 0.01;
/** @constant {Cesium.Cartesian3[]} What a spare dynamic polyline draws. */
const NO_POSITIONS = Object.freeze([]);
/** @constant {number} Points per chunk; adjacent chunks share one point. */
export const CHUNK_POINTS = 128;
/** @constant {number} Visible frames a frozen chunk's stand-in waits for its
* static geometry before it is dropped anyway. */
const STAND_IN_MAX_FRAMES = 600;
/**
* Create an always-visible polyline trail bound to a viewer.
@@ -49,93 +68,285 @@ const MIN_SEGMENT_DISTANCE_SQ = 0.01;
* @param {object} options - Trail options.
* @param {string} options.color - CSS color string for the trail hue.
* @param {number} [options.width=2.5] - Polyline width in pixels.
* @returns {{setPositions: function(Cesium.Cartesian3[]): void, setVisible: function(boolean): void, clear: function(): void, destroy: function(): void}}
* Trail handle: setPositions replaces the geometry, setVisible temporarily
* hides it without discarding history, clear empties it, and destroy removes
* the entity permanently.
* @returns {{setPositions: function(Cesium.Cartesian3[]): void, setSegments: function(Cesium.Cartesian3[][]): void, setVisible: function(boolean): void, clear: function(): void, destroy: function(): void}}
* Trail handle: setPositions replaces the geometry with one line,
* setSegments with one line per segment, setVisible temporarily hides it
* without discarding history, clear empties it, and destroy removes the
* entities permanently.
*/
export function createTrail(viewer, { color, width = 2.5 }) {
const baseColor = Cesium.Color.fromCssColorString(color);
/** @type {Cesium.Cartesian3[]} Current deduped positions (owned copy). */
let current = [];
const material = baseColor.withAlpha(TRAIL_ALPHA);
const depthFailMaterial = baseColor.withAlpha(TRAIL_OCCLUDED_ALPHA);
let destroyed = false;
let visible = true;
/** @type {Cesium.Entity|null} */
let entity = null;
/** @type {{positions: Cesium.Cartesian3[], entity: Cesium.Entity, standIn: boolean, frames: number}[]} */
let frozen = [];
/** Newest chunk of the newest segment: the only part that changes. */
let tail = NO_POSITIONS;
/** What the dynamic polylines draw: the tail, then frozen chunks whose
* static geometry is not in the scene yet. */
let dynamicRuns = [];
/** @type {Cesium.Entity[]} Pooled dynamic polylines; spares draw nothing. */
const dynamicEntities = [];
let removeReadyListener = null;
const scratchSphere = new Cesium.BoundingSphere();
function ensureEntity() {
if (entity || destroyed || !viewer || viewer.isDestroyed()) return;
entity = viewer.entities.add({
const usable = () => !destroyed && viewer && !viewer.isDestroyed();
function polyline(positions) {
return {
positions,
width,
material,
// The owner-locked rule (round 6): a segment below the photoreal
// mesh renders dimmed — it must never disappear into the ground.
depthFailMaterial,
// Round 8 (owner: UAL1104's Pacific trail "cutting through the
// globe"): NONE draws straight 3D chords between waypoints — over a
// sparse trans-oceanic trace a single segment spans hundreds of km
// and tunnels through the planet. GEODESIC subdivides each segment
// along the curved surface (heights interpolated), so long legs hug
// the globe instead of chording through it.
arcType: Cesium.ArcType.GEODESIC,
};
}
function addEntity(positions) {
return viewer.entities.add({
id: `gev-trail:${++_trailSeq}`,
show: visible,
polyline: {
// CallbackProperty so a positions swap never rebuilds the entity —
// Cesium re-reads on change; `false` marks it non-constant.
positions: new Cesium.CallbackProperty(() => current, false),
width,
material: baseColor.withAlpha(TRAIL_ALPHA),
// The owner-locked rule (round 6): a segment below the photoreal
// mesh renders dimmed — it must never disappear into the ground.
depthFailMaterial: baseColor.withAlpha(TRAIL_OCCLUDED_ALPHA),
// Round 8 (owner: UAL1104's Pacific trail "cutting through the
// globe"): NONE draws straight 3D chords between waypoints — over a
// sparse trans-oceanic trace a single segment spans hundreds of km
// and tunnels through the planet. GEODESIC subdivides each segment
// along the curved surface (heights interpolated), so long legs hug
// the globe instead of chording through it.
arcType: Cesium.ArcType.GEODESIC,
},
polyline: polyline(positions),
});
}
function removeEntity(entity) {
try {
viewer.entities.remove(entity);
} catch {
/* torn down */
}
}
function syncDynamic() {
dynamicRuns = [];
if (tail.length >= 2) dynamicRuns.push(tail);
for (const chunk of frozen)
if (chunk.standIn) dynamicRuns.push(chunk.positions);
while (dynamicEntities.length < Math.max(1, dynamicRuns.length)) {
const index = dynamicEntities.length;
dynamicEntities.push(
addEntity(
// CallbackProperty so a positions swap never rebuilds the entity —
// Cesium re-reads on change; `false` marks it non-constant.
new Cesium.CallbackProperty(
() => dynamicRuns[index] ?? NO_POSITIONS,
false,
),
),
);
}
}
/** Whether a frozen chunk's static geometry is drawn in the scene. */
function staticReady(chunk) {
const display = viewer.dataSourceDisplay;
if (typeof display?.getBoundingSphere !== 'function') return true;
if (!visible) return false;
chunk.frames += 1;
if (chunk.frames > STAND_IN_MAX_FRAMES) return true;
try {
return (
display.getBoundingSphere(chunk.entity, false, scratchSphere) ===
Cesium.BoundingSphereState.DONE
);
} catch {
return false;
}
}
/** Drop stand-ins whose static geometry is in; stop listening when none are left. */
function resolveStandIns() {
if (!usable()) return;
let changed = false;
for (const chunk of frozen) {
if (chunk.standIn && staticReady(chunk)) {
chunk.standIn = false;
changed = true;
}
}
if (changed) syncDynamic();
if (!frozen.some((chunk) => chunk.standIn)) stopListening();
}
function stopListening() {
if (removeReadyListener) removeReadyListener();
removeReadyListener = null;
}
function listenForStandIns() {
if (removeReadyListener) return;
const event = viewer.scene?.postRender;
if (typeof event?.addEventListener !== 'function') {
resolveStandIns();
return;
}
removeReadyListener = event.addEventListener(resolveStandIns);
}
/** Drop consecutive near-duplicates: zero-length segments add nothing. */
function dedupe(cartesians) {
const positions = [];
for (const position of Array.isArray(cartesians) ? cartesians : []) {
if (!position) continue;
const last = positions[positions.length - 1];
if (
last &&
Cesium.Cartesian3.distanceSquared(last, position) <
MIN_SEGMENT_DISTANCE_SQ
)
continue;
positions.push(position);
}
return positions;
}
/** 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;
}
/**
* Cut segments into chunks, reusing every frozen chunk whose points are
* still drawn in the same order. New chunks end where a reusable one begins,
* so dropping the oldest point rebuilds only the first chunk.
*/
function reconcile(segments) {
const byStart = new Map();
for (const chunk of frozen) 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 = [];
let nextTail = NO_POSITIONS;
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) {
nextTail = 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);
next.push({
positions,
entity: addEntity(positions),
standIn: true,
frames: 0,
});
i = end;
}
});
for (const chunk of frozen)
if (!kept.has(chunk)) removeEntity(chunk.entity);
frozen = next;
tail = nextTail;
syncDynamic();
if (frozen.some((chunk) => chunk.standIn)) listenForStandIns();
else stopListening();
}
function release() {
stopListening();
for (const chunk of frozen) removeEntity(chunk.entity);
frozen = [];
tail = NO_POSITIONS;
dynamicRuns = [];
}
return {
/**
* Replace the trail geometry with a chronological position list
* Replace the trail geometry with one chronological position list
* (oldest first). Fewer than 2 distinct positions clears the trail.
* @param {Cesium.Cartesian3[]} cartesians - Positions, oldest -> newest.
*/
setPositions(cartesians) {
if (destroyed || !viewer || viewer.isDestroyed()) return;
// Drop consecutive near-duplicates: zero-length segments add nothing.
const positions = [];
for (const position of Array.isArray(cartesians) ? cartesians : []) {
if (!position) continue;
const last = positions[positions.length - 1];
if (
last &&
Cesium.Cartesian3.distanceSquared(last, position) <
MIN_SEGMENT_DISTANCE_SQ
)
continue;
positions.push(position);
}
current = positions.length >= 2 ? positions : [];
ensureEntity();
this.setSegments([cartesians]);
},
/**
* Replace the trail geometry with chronological segments (oldest first).
* Nothing is drawn between segments. A segment with fewer than 2 distinct
* positions draws nothing. Pass the same position objects on every
* update: a chunk whose points are unchanged is never rebuilt.
* @param {Cesium.Cartesian3[][]} list - Segments, each oldest -> newest.
*/
setSegments(list) {
if (!usable()) return;
reconcile(
(Array.isArray(list) ? list : [])
.map(dedupe)
.filter((positions) => positions.length >= 2),
);
},
/** Temporarily hide/show the trail without discarding accumulated history. */
setVisible(nextVisible) {
visible = nextVisible !== false;
if (entity) entity.show = visible;
for (const entity of dynamicEntities) entity.show = visible;
for (const chunk of frozen) chunk.entity.show = visible;
},
/** Empty the trail without removing the entity (cheap re-arm). */
/** Empty the trail and release its frozen geometry; dynamic polylines stay for re-arm. */
clear() {
current = [];
if (!usable()) return;
release();
},
/** Remove the trail entity permanently (layer disable/teardown). */
/** Remove every trail entity permanently (layer disable/teardown). */
destroy() {
destroyed = true;
current = [];
if (entity && viewer && !viewer.isDestroyed()) {
try {
viewer.entities.remove(entity);
} catch {
/* torn down */
}
if (usable()) {
release();
for (const entity of dynamicEntities) removeEntity(entity);
}
entity = null;
destroyed = true;
frozen = [];
tail = NO_POSITIONS;
dynamicRuns = [];
dynamicEntities.length = 0;
stopListening();
},
/** Test seam: frozen chunks (positions, stand-in state) and the dynamic runs. */
_chunksForTest() {
return {
frozen: frozen.map((chunk) => ({
positions: chunk.positions,
standIn: chunk.standIn,
entity: chunk.entity,
})),
dynamic: dynamicRuns.slice(),
};
},
};
}
+251 -1
View File
@@ -1,7 +1,7 @@
import test from 'node:test';
import assert from 'node:assert/strict';
import * as Cesium from 'cesium';
import { createTrail } from './trailRenderer.js';
import { CHUNK_POINTS, createTrail } from './trailRenderer.js';
test('trail visibility can change without discarding its accumulated geometry', () => {
const added = [];
@@ -37,3 +37,253 @@ test('trail visibility can change without discarding its accumulated geometry',
trail.destroy();
assert.deepEqual(removed, [added[0]]);
});
/**
* A fake viewer. `ready` holds the frozen-chunk entities whose static
* geometry is in the scene; `frame()` runs one post-render pass.
*/
function fakeViewer({ scene = true } = {}) {
const added = [];
const removed = [];
const ready = new Set();
let listeners = [];
const viewer = {
added,
removed,
ready,
isDestroyed: () => false,
entities: {
add(definition) {
added.push(definition);
return definition;
},
remove(entity) {
removed.push(entity);
},
},
listenerCount: () => listeners.length,
frame() {
for (const listener of listeners.slice()) listener();
},
};
if (scene) {
viewer.scene = {
postRender: {
addEventListener(listener) {
listeners.push(listener);
return () => {
listeners = listeners.filter((l) => l !== listener);
};
},
},
};
viewer.dataSourceDisplay = {
getBoundingSphere: (entity) =>
ready.has(entity)
? Cesium.BoundingSphereState.DONE
: Cesium.BoundingSphereState.PENDING,
};
}
return viewer;
}
const valueOf = (positions) =>
typeof positions?.getValue === 'function' ? positions.getValue() : positions;
/** Every line the scene can draw now: live entities with two or more points. */
function drawnRuns(viewer) {
return viewer.added
.filter((entity) => !viewer.removed.includes(entity))
.map((entity) => valueOf(entity.polyline.positions))
.filter((positions) => positions.length >= 2);
}
/** Distinct position objects across all drawn lines. */
function drawnPoints(viewer) {
return new Set(drawnRuns(viewer).flat());
}
function line(count, offset = 0) {
return Array.from(
{ length: count },
(_, i) => new Cesium.Cartesian3(6_378_137 + offset, i * 1000, 0),
);
}
test('a trail with breaks draws each segment and nothing between them', () => {
const viewer = fakeViewer({ scene: false });
const trail = createTrail(viewer, { color: '#ffffff' });
const first = line(2, 0);
const lone = line(1, 50_000);
const second = line(3, 100_000);
trail.setSegments([first, lone, second]);
assert.deepEqual(
drawnRuns(viewer).sort((a, b) => a[0].x - b[0].x),
[first, second],
);
for (const entity of viewer.added) {
assert.match(String(entity.id), /^gev-trail:/);
assert.equal(entity.polyline.width, 2.5);
}
// The first segment is gone later: its geometry is released.
trail.setSegments([second]);
assert.deepEqual(drawnRuns(viewer), [second]);
trail.setVisible(false);
assert.ok(
viewer.added
.filter((entity) => !viewer.removed.includes(entity))
.every((entity) => entity.show === false),
);
trail.destroy();
assert.equal(new Set(viewer.removed).size, viewer.added.length);
});
test('chunks share their boundary points and only the newest chunk is dynamic', () => {
const viewer = fakeViewer({ scene: false });
const trail = createTrail(viewer, { color: '#ffffff' });
const points = line(300);
trail.setPositions(points);
const { frozen, dynamic } = trail._chunksForTest();
assert.deepEqual(
frozen.map((chunk) => chunk.positions.length),
[CHUNK_POINTS, CHUNK_POINTS],
);
assert.equal(frozen[0].positions.at(-1), frozen[1].positions[0]);
assert.equal(dynamic.length, 1);
assert.equal(frozen[1].positions.at(-1), dynamic[0][0]);
assert.equal(dynamic[0].at(-1), points.at(-1));
assert.equal(drawnPoints(viewer).size, points.length);
// A frozen chunk is constant geometry, not a per-frame callback.
for (const chunk of frozen)
assert.ok(Array.isArray(chunk.entity.polyline.positions));
});
test('freezing a chunk keeps every point drawn, and the dynamic copy goes only once the static geometry is in', () => {
const viewer = fakeViewer();
const trail = createTrail(viewer, { color: '#ffffff' });
const points = line(CHUNK_POINTS + 20);
for (let n = 2; n <= points.length; n++) {
trail.setPositions(points.slice(0, n));
assert.equal(drawnPoints(viewer).size, n, `points drawn at ${n}`);
}
const { frozen } = trail._chunksForTest();
assert.equal(frozen.length, 1);
// Not in the scene yet: the chunk is still drawn by a dynamic polyline.
viewer.frame();
assert.equal(trail._chunksForTest().frozen[0].standIn, true);
assert.ok(
trail._chunksForTest().dynamic.includes(frozen[0].positions),
'the dynamic copy stays until the static geometry is ready',
);
viewer.ready.add(frozen[0].entity);
viewer.frame();
const after = trail._chunksForTest();
assert.equal(after.frozen[0].standIn, false);
assert.ok(!after.dynamic.includes(frozen[0].positions));
assert.equal(after.dynamic.length, 1);
assert.equal(viewer.listenerCount(), 0, 'no listener once nothing waits');
// The frozen entity is the same object: freezing built it once.
assert.equal(after.frozen[0].entity, frozen[0].entity);
});
test('a hidden trail keeps its dynamic copy until it is shown and the static geometry is in', () => {
const viewer = fakeViewer();
const trail = createTrail(viewer, { color: '#ffffff' });
trail.setVisible(false);
trail.setPositions(line(CHUNK_POINTS + 5));
const [chunk] = trail._chunksForTest().frozen;
viewer.ready.add(chunk.entity);
viewer.frame();
assert.equal(trail._chunksForTest().frozen[0].standIn, true);
trail.setVisible(true);
viewer.frame();
assert.equal(trail._chunksForTest().frozen[0].standIn, false);
});
test('dropping the oldest point rebuilds only the first chunk', () => {
const viewer = fakeViewer({ scene: false });
const trail = createTrail(viewer, { color: '#ffffff' });
const points = line(400);
trail.setPositions(points);
const before = trail._chunksForTest().frozen;
trail.setPositions(points.slice(1));
const after = trail._chunksForTest().frozen;
assert.equal(after.length, before.length);
assert.notEqual(after[0].entity, before[0].entity);
assert.ok(viewer.removed.includes(before[0].entity));
for (let k = 1; k < before.length; k++)
assert.equal(after[k].entity, before[k].entity);
assert.equal(after[0].positions.at(-1), after[1].positions[0]);
assert.equal(drawnPoints(viewer).size, 399);
});
test('a backfill prepended ahead of frozen chunks keeps them and joins at a shared point', () => {
const viewer = fakeViewer({ scene: false });
const trail = createTrail(viewer, { color: '#ffffff' });
const live = line(300, 0);
trail.setPositions(live);
const before = trail._chunksForTest().frozen;
// History older than every live point, joined as one path.
const history = Array.from(
{ length: 200 },
(_, i) => new Cesium.Cartesian3(6_378_137, -(200 - i) * 1000, 0),
);
trail.setPositions(history.concat(live));
const after = trail._chunksForTest().frozen;
for (const chunk of before)
assert.ok(after.some((c) => c.entity === chunk.entity));
for (let k = 0; k + 1 < after.length; k++)
assert.equal(after[k].positions.at(-1), after[k + 1].positions[0]);
assert.equal(drawnPoints(viewer).size, 500);
// A backfill that breaks from the live trail is its own segment.
trail.setSegments([history, live]);
assert.equal(drawnPoints(viewer).size, 500);
const runs = drawnRuns(viewer);
assert.ok(
!runs.some((run) => run.includes(history.at(-1)) && run.includes(live[0])),
'no line across the break',
);
});
test('clearing and re-tracking release every frozen chunk', () => {
const viewer = fakeViewer();
const trail = createTrail(viewer, { color: '#ffffff' });
trail.setPositions(line(600));
const frozen = trail._chunksForTest().frozen.map((chunk) => chunk.entity);
assert.ok(frozen.length >= 4);
assert.equal(viewer.listenerCount(), 1);
trail.clear();
for (const entity of frozen) assert.ok(viewer.removed.includes(entity));
assert.equal(viewer.listenerCount(), 0);
assert.equal(drawnRuns(viewer).length, 0);
// Another aircraft: nothing of the first one survives.
const other = line(200, 900_000);
trail.setPositions(other);
assert.equal(drawnPoints(viewer).size, 200);
trail.destroy();
assert.equal(new Set(viewer.removed).size, viewer.added.length);
assert.equal(viewer.listenerCount(), 0);
});
test('replacing the newest point and removing points inside the trail draws exactly the new trail', () => {
const viewer = fakeViewer({ scene: false });
const trail = createTrail(viewer, { color: '#ffffff' });
const points = line(400);
trail.setPositions(points.slice());
// A recorded point replaces the newest one; a spur point inside a frozen
// chunk and one at a chunk boundary go.
points[points.length - 1] = new Cesium.Cartesian3(6_378_137, 399_500, 10);
points.splice(200, 1);
points.splice(CHUNK_POINTS - 1, 1);
trail.setPositions(points.slice());
assert.deepEqual(drawnPoints(viewer), new Set(points));
// Every drawn line runs through consecutive trail points only.
const next = new Map(points.slice(0, -1).map((p, i) => [p, points[i + 1]]));
for (const run of drawnRuns(viewer))
for (let i = 1; i < run.length; i++) assert.equal(next.get(run[i - 1]), run[i]);
});
+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,
};
}