Read flight and military billboard state from the app's mirror

Flights and military now add their billboards through addBillboard and
write show, position, scale, rotation, size and distance scaling through
setBillboard, which keeps the app's copy in src/data/billboardMirror.js.
Their reads go to billboardState instead of the Cesium billboard, so the
layers no longer read back what they pushed to the renderer.

A mirrored billboard needs an explicit width and height, because unset
Cesium reports the loaded image's size. Colour is not mirrored yet: the
cyber-sonar theme writes it too and tells the writers apart by the live
value, so it moves with the effects port.
This commit is contained in:
Sameh Khamis committed 2026-11-03 10:56:08 -08:00
1 parent 7ebc73393a
commit bb91688a62
23 files changed
+424 -172

No files matched your search

+5 -3
View File
@@ -5,6 +5,7 @@
* with the locked NearFarScalar. It never edits that scalar, culls a contact,
* or allows alpha to reach zero.
*/
import { billboardState, setBillboard } from './billboardMirror.js';
export const DEFAULT_AIRCRAFT_RECESSION_PARAMS = Object.freeze({
startLimbRatio: 0.5,
@@ -220,11 +221,12 @@ export function applyAircraftBillboardTreatment({
const alpha = baseAlpha * composedTreatment;
let scaleWrites = 0;
let alphaWrites = 0;
const pushedScale = billboardState(billboard)?.scale;
if (
!Number.isFinite(billboard.scale) ||
Math.abs(billboard.scale - scale) > tuning.writeEpsilon
!Number.isFinite(pushedScale) ||
Math.abs(pushedScale - scale) > tuning.writeEpsilon
) {
billboard.scale = scale;
setBillboard(billboard, 'scale', scale);
scaleWrites = 1;
}
if (
+5 -4
View File
@@ -7,6 +7,7 @@ import {
applyAircraftModelTreatment,
cameraLimbDistanceM,
} from './aircraftRecession.js';
import { mirrorBillboard } from './billboardMirror.js';
const params = { ...DEFAULT_AIRCRAFT_RECESSION_PARAMS };
const cameraHeightM = 1_000_000;
@@ -68,7 +69,7 @@ test('globe-view transition eases to identity without a threshold pop', () => {
test('aircraft billboard wire writes scale and alpha only for the far treatment', () => {
const color = { withAlpha: (alpha) => ({ alpha }) };
const near = { scale: 1.2, color: { alpha: 0.8 } };
const near = mirrorBillboard({ scale: 1.2, color: { alpha: 0.8 } });
const nearResult = applyAircraftBillboardTreatment({
billboard: near,
baseScale: 1.2,
@@ -82,7 +83,7 @@ test('aircraft billboard wire writes scale and alpha only for the far treatment'
assert.equal(nearResult.scaleWrites, 0);
assert.equal(nearResult.alphaWrites, 0);
const far = { scale: 1.2, color: { alpha: 0.8 } };
const far = mirrorBillboard({ scale: 1.2, color: { alpha: 0.8 } });
const farResult = applyAircraftBillboardTreatment({
billboard: far,
baseScale: 1.2,
@@ -101,7 +102,7 @@ test('aircraft billboard wire writes scale and alpha only for the far treatment'
test('combined focus and haze product is clamped at the composed alpha floor', () => {
const color = { withAlpha: (alpha) => ({ alpha }) };
const billboard = { scale: 0.45, color: { alpha: 1 } };
const billboard = mirrorBillboard({ scale: 0.45, color: { alpha: 1 } });
const result = applyAircraftBillboardTreatment({
billboard,
baseScale: 1,
@@ -118,7 +119,7 @@ test('combined focus and haze product is clamped at the composed alpha floor', (
test('applyAircraftBillboardTreatment returns its documented module singleton', () => {
const color = { withAlpha: (alpha) => ({ alpha }) };
const billboard = { scale: 1, color: { alpha: 1 } };
const billboard = mirrorBillboard({ scale: 1, color: { alpha: 1 } });
const input = {
billboard,
baseAlpha: 1,
+106
View File
@@ -0,0 +1,106 @@
/**
* @module billboardMirror
* @description The app's copy of what a layer pushed to its billboards, so the layer
* reads its own state back from the app instead of from the renderer's objects.
*
* A layer adds billboards with {@link addBillboard}, writes the mirrored fields
* with {@link setBillboard}, and reads them with {@link billboardState}. Fields
* outside the mirror (image, colour, eye offset, …) are written to the billboard
* directly. Colour stays out because the cyber-sonar theme writes it too and
* tells the two writers apart by reading the live value.
*/
import * as Cesium from 'cesium';
import { createEntityStore } from './entityRecords.js';
const mirrors = createEntityStore();
/**
* Mirrored fields with Cesium's defaults for a billboard added without them.
* Width and height have none: unset, Cesium reports the loaded image's size,
* which the app cannot know, so {@link addBillboard} requires them.
*/
const DEFAULTS = Object.freeze({
show: true,
scale: 1,
rotation: 0,
width: undefined,
height: undefined,
scaleByDistance: undefined,
});
/** Cesium copies positions and scalers on write; the mirror keeps its own copy too. */
function copyInto(record, field, value) {
if (field === 'position') {
// Cesium keeps its old position when handed none; so does the mirror.
if (!value && record.position) return;
record.position = Cesium.Cartesian3.clone(
value ?? Cesium.Cartesian3.ZERO,
record.position,
);
} else if (field === 'scaleByDistance') {
record.scaleByDistance = value
? Cesium.NearFarScalar.clone(value, record.scaleByDistance)
: undefined;
} else {
record[field] = value;
}
}
function seed(billboard, source) {
const record = mirrors.write(billboard);
copyInto(record, 'position', source.position);
for (const [field, fallback] of Object.entries(DEFAULTS))
copyInto(record, field, source[field] ?? fallback);
return record;
}
/**
* Add a billboard and remember what was pushed.
* @param {Cesium.BillboardCollection} collection
* @param {Object} options Billboard options, as for `collection.add`, with an
* explicit `width` and `height`.
* @returns {Cesium.Billboard}
*/
export function addBillboard(collection, options) {
if (!Number.isFinite(options?.width) || !Number.isFinite(options?.height))
throw new TypeError(
'A mirrored billboard needs an explicit width and height',
);
const billboard = collection.add(options);
seed(billboard, options);
return billboard;
}
/**
* Start mirroring a billboard the app did not add itself (test seams), from its
* current fields.
* @param {Object} billboard
* @returns {Object} The billboard.
*/
export function mirrorBillboard(billboard) {
if (billboard && typeof billboard === 'object') seed(billboard, billboard);
return billboard;
}
/**
* Write one mirrored field to the billboard and to the app's copy.
* @param {Object} billboard
* @param {'show'|'position'|'scale'|'rotation'|'width'|'height'|'scaleByDistance'} field
* @param {*} value
*/
export function setBillboard(billboard, field, value) {
copyInto(mirrors.write(billboard), field, value);
billboard[field] = value;
}
/**
* The app's copy of a billboard's mirrored fields, or null when it has none (or
* there is no billboard).
* @param {Object|null|undefined} billboard
* @returns {{ show: boolean, position: Cesium.Cartesian3, scale: number,
* rotation: number, width?: number, height?: number,
* scaleByDistance?: Cesium.NearFarScalar }|null}
*/
export function billboardState(billboard) {
return mirrors.read(billboard);
}
+74
View File
@@ -0,0 +1,74 @@
import test from 'node:test';
import assert from 'node:assert/strict';
import * as Cesium from 'cesium';
import {
addBillboard,
billboardState,
mirrorBillboard,
setBillboard,
} from './billboardMirror.js';
const SIZE = Object.freeze({ width: 20, height: 20 });
function fakeCollection() {
return { add: (options) => ({ ...options }) };
}
test('an added billboard is mirrored with Cesium defaults for unset fields', () => {
const position = Cesium.Cartesian3.fromDegrees(10, 20, 30);
const bb = addBillboard(fakeCollection(), { position, width: 20, height: 24 });
const state = billboardState(bb);
assert.equal(state.show, true);
assert.equal(state.scale, 1);
assert.equal(state.rotation, 0);
assert.equal(state.width, 20);
assert.equal(state.height, 24);
assert.ok(Cesium.Cartesian3.equals(state.position, position));
assert.notEqual(state.position, position, 'the mirror keeps its own copy');
});
test('writes reach both the billboard and the mirror', () => {
const bb = addBillboard(fakeCollection(), SIZE);
setBillboard(bb, 'show', false);
setBillboard(bb, 'scale', 0.5);
assert.equal(bb.show, false);
assert.equal(billboardState(bb).show, false);
assert.equal(billboardState(bb).scale, 0.5);
});
test('a reused scratch position does not move the mirror', () => {
const bb = addBillboard(fakeCollection(), SIZE);
const scratch = Cesium.Cartesian3.fromDegrees(1, 2, 3);
setBillboard(bb, 'position', scratch);
const written = Cesium.Cartesian3.clone(scratch);
Cesium.Cartesian3.fromDegrees(50, 50, 50, undefined, scratch);
assert.ok(Cesium.Cartesian3.equals(billboardState(bb).position, written));
});
test('writing no position keeps the last one, as Cesium does', () => {
const position = Cesium.Cartesian3.fromDegrees(1, 2, 3);
const bb = addBillboard(fakeCollection(), { ...SIZE, position });
setBillboard(bb, 'position', undefined);
assert.ok(Cesium.Cartesian3.equals(billboardState(bb).position, position));
});
test('the mirror answers from the app, not from the billboard', () => {
const bb = addBillboard(fakeCollection(), { ...SIZE, show: true });
bb.show = false; // a write that bypassed the mirror
assert.equal(billboardState(bb).show, true);
});
test('a billboard the app did not add can be mirrored from its fields', () => {
const bb = mirrorBillboard({ show: false, scale: 2 });
assert.equal(billboardState(bb).show, false);
assert.equal(billboardState(bb).scale, 2);
assert.ok(Cesium.Cartesian3.equals(billboardState(bb).position, Cesium.Cartesian3.ZERO));
assert.equal(billboardState(null), null);
assert.equal(mirrorBillboard(null), null);
});
test('a billboard without explicit dimensions is refused', () => {
// Unset, Cesium reports the image's size, which the mirror cannot know.
assert.throws(() => addBillboard(fakeCollection(), {}), TypeError);
assert.throws(() => addBillboard(fakeCollection(), { width: 20 }), TypeError);
});
+2 -2
View File
@@ -90,11 +90,11 @@ for (const layer of LAYERS) {
// operator explicitly converted into a TR-3B.
assert.match(source, /bb\.image\s*=\s*aircraftIcon\(\s*_iconKind\(\s*icao24,\s*meta\?\.klass,?\s*\)(,\s*aircraftVisuals\.read\(bb\)\?\.iconLarge\s*\?\s*TRACKED_ICON_PX\s*:\s*undefined)?,?\s*\)/,
'near contacts and model fallbacks retain the class-derived aircraft silhouette');
assert.match(source, /bb\.rotation\s*=\s*0;/,
assert.match(source, /setBillboard\(\s*bb,\s*'rotation',\s*0\s*\);/,
'far dots are reset to a rotation-free presentation');
assert.match(source, /\(\s*!(?:flightState\.)?_cockpitContactMode\s*\|\|\s*isCockpitNear,?\s*\)\s*&&\s*\(\s*doRotations\s*\|\|\s*revealed,?\s*\)/,
'near 2D silhouettes continue to receive projected course');
assert.match(source, /if\s*\(\s*bb\.show,?\s*\)\s*bb\.show\s*=\s*false;\s*\/\/\s*hand\s*off\s*ONLY\s*once\s*the\s*model\s*renders/,
assert.match(source, /if\s*\(\s*billboardState\(bb\)\.show,?\s*\)\s*setBillboard\(\s*bb,\s*'show',\s*false\s*\);\s*\/\/\s*hand\s*off\s*ONLY\s*once\s*the\s*model\s*renders/,
'the gap-proof billboard-to-model handoff remains intact');
});
+4 -1
View File
@@ -3,6 +3,7 @@ import test from 'node:test';
import * as Cesium from 'cesium';
import { routePlausible } from './routePlausible.js';
import { createTracking } from '../layers/flights/tracking.js';
import { addBillboard } from './billboardMirror.js';
const SFO = { lat: 37.6188, lon: -122.3754, code: 'SFO' };
const LAX = { lat: 33.9416, lon: -118.4085, code: 'LAX' };
@@ -156,8 +157,10 @@ test('the actual native tracked label hides the wrong leg and keeps a healthy ro
});
flightState._billboards.set(
id,
collection.add({
addBillboard(collection, {
id,
width: 20,
height: 20,
position: Cesium.Cartesian3.fromDegrees(
position.lon,
position.lat,
+1 -1
View File
@@ -245,7 +245,7 @@ test('both flight layers keep a converted contact 2D and visible (render invaria
// 2. The billboard is never hidden by that suppression — it must keep
// satisfying the getNearby/getDetectableObjects visibility guards, so a
// converted contact still works in Contacts and Cockpit.
assert.match(source, /if\s*\(\s*bb\s*&&\s*id\s*!==\s*(?:flightState\.)?_trackedIcao,?\s*\)\s*bb\.show\s*=\s*true;|if\s*\(\s*modelled\s*&&\s*id\s*!==\s*(?:flightState\.)?_trackedIcao,?\s*\)\s*modelled\.show\s*=\s*true;/,
assert.match(source, /if\s*\(\s*(bb|modelled)\s*&&\s*id\s*!==\s*(?:flightState\.)?_trackedIcao,?\s*\)\s*setBillboard\(\s*\1,\s*'show',\s*true,?\s*\);/,
`${name}: converting restores the billboard the model handoff had hidden`);
// 3. Every aircraftIcon() CALL SITE routes through the kind resolver, so no
+7 -6
View File
@@ -45,6 +45,7 @@ import militaryFlightsLayer, {
} from './militaryFlights.js';
import { clearTr3bRegistry, setTr3b } from './tr3bRegistry.js';
import { reportMeshFloorCell, _clearMeshFloorCellsForTest } from './groundFloor.js';
import { setBillboard } from './billboardMirror.js';
// Sample altitudes are expressed RELATIVE to the band rather than as absolute
// offsets. The thresholds have already been retuned once (1_000_000 → 150_000
@@ -351,7 +352,7 @@ for (const fixture of LAYERS) {
onGround: true,
models: [[icao24, model]],
});
billboard.show = false;
setBillboard(billboard, 'show', false);
let ownsVisual = fixture.driveFleetModel({ icao24, position, course: 92 });
assert.equal(ownsVisual, false, 'cold terrain cannot transfer ownership to 3D');
@@ -487,7 +488,7 @@ for (const fixture of LAYERS) {
onGround: true,
models: [[icao24, model]],
});
billboard.show = false;
setBillboard(billboard, 'show', false);
const atA = Cesium.Cartesian3.fromDegrees(A_LON, LAT, 0);
const atB = Cesium.Cartesian3.fromDegrees(B_LON, LAT, 0);
@@ -622,7 +623,7 @@ for (const fixture of LAYERS) {
0,
1e-6,
), 'a hidden tracked model cannot steal the detection anchor');
billboard.show = false; // tracking hides the fleet sprite; the tracked entity remains the 2D owner
setBillboard(billboard, 'show', false); // tracking hides the fleet sprite; the tracked entity remains the 2D owner
const loadingNearby = fixture.layer.getNearby(billboard.position, 1_000, 50)
.find((object) => object.icao24 === (fixture.name === 'flights' ? 'a0f001' : 'b0f001'));
assert.ok(loadingNearby, 'the tracked contact remains in proximity while its model loads');
@@ -661,7 +662,7 @@ for (const fixture of LAYERS) {
viewer.tileset.tilesLoaded = false;
sampledHeight = undefined;
billboard.position = Cesium.Cartesian3.fromDegrees(-97.71, 30.21, -500);
setBillboard(billboard, 'position', Cesium.Cartesian3.fromDegrees(-97.71, 30.21, -500));
fixture.driveTrackedModel();
assert.equal(model.show, true,
'a successful cached snap survives a poll-time vertical datum change');
@@ -671,7 +672,7 @@ for (const fixture of LAYERS) {
// Taxi past the resample threshold with the tiles gone: the tracked model
// holds its last measured floor rather than handing the operator's own
// selection back to a 2D glyph for a retry backoff.
billboard.position = Cesium.Cartesian3.fromDegrees(-97.709, 30.21, -500);
setBillboard(billboard, 'position', Cesium.Cartesian3.fromDegrees(-97.709, 30.21, -500));
fixture.driveTrackedModel();
assert.equal(model.show, true,
'a taxi-invalidated tracked snap is HELD through the resample outage');
@@ -680,7 +681,7 @@ for (const fixture of LAYERS) {
assert.equal(sampleCalls, 1, 'the hold costs no extra synchronous sample');
// Past the drift bound the memory is released and the gate takes over.
billboard.position = Cesium.Cartesian3.fromDegrees(-97.707, 30.21, -500);
setBillboard(billboard, 'position', Cesium.Cartesian3.fromDegrees(-97.707, 30.21, -500));
fixture.driveTrackedModel();
assert.equal(model.show, false,
'past HELD_SNAP_MAX_DRIFT_M the hold is released and the model is withheld');