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

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

No files matched your search

+573
View File
@@ -0,0 +1,573 @@
import assert from 'node:assert/strict';
import { describe, test } from 'node:test';
import {
gltfMeshMatrix,
PART_HIDDEN,
PART_HIGHLIGHT,
partMatrices,
partTableOf,
readPartTable,
asksHighlight,
} from './modelParts.js';
/** `m` (column-major 4×4 at `at`) times the point `p`. */
function apply(m, at, p) {
const out = [0, 0, 0];
for (let row = 0; row < 3; row++)
out[row] =
m[at + row] * p[0] +
m[at + 4 + row] * p[1] +
m[at + 8 + row] * p[2] +
m[at + 12 + row];
return out;
}
function close(actual, expected, digits = 6) {
assert.equal(actual.length, expected.length);
const tolerance = 10 ** -digits / 2;
actual.forEach((value, i) =>
assert.ok(
Math.abs(value - expected[i]) <= tolerance,
`[${i}] ${value} is not ${expected[i]}`,
),
);
}
const IDENTITY = [1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1];
/** A model in the glTF frame (nose −X, Y up, right −Z). */
const TABLE = partTableOf({
parts: [
{ name: 'body', kind: 'body' },
// Nose gear: stowed at 90, down at 0, turning about +Z through a point ahead and below.
{
name: 'gear_nose',
kind: 'hinge',
pivot: [-10, -1, 0],
axis: [0, 0, 1],
limits: [90, 0],
},
// A flap about the right axis (−Z), 0 to 40 degrees, drawn at 0.
{
name: 'flap',
kind: 'hinge',
pivot: [2, 0, -3],
axis: [0, 0, -1],
limits: [0, 40],
},
{ name: 'engine', kind: 'marker', pivot: [0, -2, -5] },
{
name: 'fan',
kind: 'spin',
parent: 'engine',
pivot: [-2, -2, -5],
axis: [1, 0, 0],
},
{
name: 'stage_1',
kind: 'separable',
pivot: [0, 40, 0],
axis: [0, -1, 0],
limits: [0, 30],
},
{
name: 'leg_1',
kind: 'hinge',
parent: 'stage_1',
pivot: [1, 1, 0],
axis: [0, 0, -1],
limits: [0, 110],
},
{
name: 'door',
kind: 'slide',
pivot: [0, 0, 1],
axis: [2, 0, 0],
limits: [0, 1.5],
},
{
name: 'panel',
kind: 'deploy',
pivot: [0, 0, 4],
axis: [1, 0, 0],
limits: [90, 0],
rest: 0,
},
],
});
function matrices(state, timeS = 0) {
const out = new Float64Array(TABLE.parts.length * 16);
const flags = new Uint8Array(TABLE.parts.length);
const posed = partMatrices(TABLE, state, timeS, out, { flags });
const at = (name) => TABLE.byName.get(name) * 16;
return { out, flags, posed, at };
}
const slice = (out, at) => Array.from(out.subarray(at, at + 16));
describe('partTableOf', () => {
test('reads a table with its defaults', () => {
assert.deepEqual(
TABLE.parts.map((p) => p.name),
[
'body',
'gear_nose',
'flap',
'engine',
'fan',
'stage_1',
'leg_1',
'door',
'panel',
],
);
const body = TABLE.parts[0];
assert.equal(body.kind, 'body');
assert.equal(body.parent, null);
assert.equal(body.parentIndex, -1);
assert.deepEqual(body.pivot, [0, 0, 0]);
assert.equal(body.axis, null);
assert.equal(body.limits, null);
assert.equal(body.rest, null);
// `rest` is the stowed limit unless given; `parent` is the body unless given.
assert.equal(TABLE.parts[1].parent, 'body');
assert.equal(TABLE.parts[1].parentIndex, 0);
assert.equal(TABLE.parts[1].rest, 90);
assert.deepEqual(TABLE.parts[8].limits, [90, 0]);
assert.equal(TABLE.parts[8].rest, 0);
assert.equal(TABLE.parts[4].parent, 'engine');
assert.equal(TABLE.parts[4].parentIndex, 3);
assert.equal(TABLE.parts[4].rest, null);
// The axis is made unit length.
assert.deepEqual(TABLE.parts[7].axis, [1, 0, 0]);
assert.equal(TABLE.byName.get('leg_1'), 6);
});
test('a model without a table has none', () => {
assert.equal(partTableOf(undefined), null);
assert.equal(partTableOf({}), null);
assert.equal(partTableOf({ other: 1 }), null);
});
const body = { name: 'body', kind: 'body' };
for (const [extras, message] of [
[{ parts: [] }, /list of parts/],
[{ parts: [{ name: 'hull', kind: 'marker' }] }, /body/],
[{ parts: [body, { name: 'x', kind: 'wobble' }] }, /kind wobble/],
[{ parts: [body, { name: 'body', kind: 'marker' }] }, /twice/],
[
{ parts: [body, { name: 'a', kind: 'marker', parent: 'b' }] },
/not an earlier part/,
],
[{ parts: [body, { name: 'a', kind: 'spin', axis: [0, 0] }] }, /axis/],
[
{ parts: [body, { name: 'a', kind: 'spin', axis: [0, 0, 0] }] },
/zero axis/,
],
[{ parts: [body, { name: 'a', kind: 'hinge', limits: [0] }] }, /limits/],
])
test(`refuses a malformed table (${message})`, () => {
assert.throws(() => partTableOf(extras), message);
});
});
/** A GLB of `json` and no binary chunk. */
function glb(json) {
let text = new TextEncoder().encode(JSON.stringify(json));
const padded = new Uint8Array(Math.ceil(text.length / 4) * 4).fill(0x20);
padded.set(text);
text = padded;
const out = new Uint8Array(20 + text.length);
const view = new DataView(out.buffer);
view.setUint32(0, 0x46546c67, true);
view.setUint32(4, 2, true);
view.setUint32(8, out.length, true);
view.setUint32(12, text.length, true);
view.setUint32(16, 0x4e4f534a, true);
out.set(text, 20);
return out;
}
describe('readPartTable', () => {
test('reads the table of the scene’s root node', () => {
const extras = {
parts: [
{ name: 'body', kind: 'body' },
{ name: 'radar', kind: 'spin' },
],
};
const bytes = glb({
scene: 0,
scenes: [{ nodes: [1] }],
nodes: [
{ extras: { parts: [{ name: 'body', kind: 'body' }] } },
{ mesh: 0, extras },
],
});
assert.deepEqual(
readPartTable(bytes).parts.map((p) => p.name),
['body', 'radar'],
);
assert.equal(readPartTable(bytes.buffer).parts.length, 2);
});
test('a model that is only its body has none', () => {
assert.equal(
readPartTable(glb({ scenes: [{ nodes: [0] }], nodes: [{ mesh: 0 }] })),
null,
);
});
test('refuses bytes that are not a GLB', () => {
assert.throws(
() => readPartTable(new TextEncoder().encode('glTF but not really')),
/GLB/,
);
});
});
describe('gltfMeshMatrix', () => {
test('the mesh node’s transform with its parents’', () => {
const m = gltfMeshMatrix({
scenes: [{ nodes: [0] }],
nodes: [
{ translation: [1, 2, 3], children: [1] },
// A packed model's dequantization: a scale and an offset.
{ mesh: 0, translation: [0, 2, 0], scale: [10, 10, 10] },
],
});
close(apply(m, 0, [1, 0, 0]), [11, 4, 3]);
close(apply(m, 0, [0, -1, 0]), [1, -6, 3]);
});
test('turned by a node’s rotation', () => {
// 90 degrees about +Y: +X turns to −Z.
const s = Math.SQRT1_2;
const m = gltfMeshMatrix({
nodes: [{ mesh: 0, rotation: [0, s, 0, s] }],
});
close(apply(m, 0, [1, 0, 0]), [0, 0, -1]);
});
test('the identity without a mesh', () => {
assert.deepEqual(gltfMeshMatrix({ nodes: [{}] }), IDENTITY);
});
});
describe('partMatrices', () => {
test('no state, or an empty one, leaves every part at rest', () => {
for (const state of [null, {}, { poses: {}, spin: {}, deploy: {} }]) {
const { out, flags, posed } = matrices(state);
assert.equal(posed, false);
for (let k = 0; k < TABLE.parts.length; k++)
assert.deepEqual(slice(out, k * 16), IDENTITY);
assert.deepEqual(
Array.from(flags),
new Array(TABLE.parts.length).fill(0),
);
}
});
test('a hinge turns about its pivot, off the origin', () => {
// Deployed: from 90 (as drawn) to 0, so −90 degrees about +Z through [-10, -1, 0].
const { out, at, posed } = matrices({ deploy: { gear_nose: 1 } });
assert.equal(posed, true);
close(apply(out, at('gear_nose'), [-10, -1, 0]), [-10, -1, 0]);
// 2 m along −Y from the pivot turns to 2 m along −X.
close(apply(out, at('gear_nose'), [-10, -3, 0]), [-12, -1, 0]);
// Halfway is 45 degrees.
const half = matrices({ deploy: { gear_nose: 0.5 } });
const s = Math.SQRT1_2 * 2;
close(apply(half.out, half.at('gear_nose'), [-10, -3, 0]), [
-10 - s,
-1 - s,
0,
]);
// Other parts stay at rest.
assert.deepEqual(slice(out, at('flap')), IDENTITY);
});
test('a hinge’s pose is clamped to its limits, its swing left free', () => {
// The flap's axis is the model's right, so pitch turns it: 0 to 40 degrees.
const tip = [3, 0, -3];
const turned = (deg) => [
2 + Math.cos(deg * (Math.PI / 180)),
// Nose up: what is behind the hinge goes down.
-Math.sin(deg * (Math.PI / 180)),
-3,
];
for (const [pitch, expected] of [
[25, 25],
[60, 40],
[-10, 0],
[400, 40],
]) {
const { out, at } = matrices({ poses: { flap: { pitchDeg: pitch } } });
close(apply(out, at('flap'), tip), turned(expected));
}
// A roll is about the forward axis, not the hinge's: kept as posed.
const rolled = matrices({ poses: { flap: { rollDeg: 90 } } });
close(apply(rolled.out, rolled.at('flap'), [2, 1, -3]), [2, 0, -4]);
});
test('the deploy fraction is clamped to 0..1, and a pose adds to it within limits', () => {
const over = matrices({ deploy: { gear_nose: 3 } });
const full = matrices({ deploy: { gear_nose: 1 } });
close(Array.from(over.out), Array.from(full.out));
// The gear down (0) and pitched 30 more (−30 about its +Z axis): still
// 0, its limit; pitched the other way, it comes 30 back up.
const past = matrices({
deploy: { gear_nose: 1 },
poses: { gear_nose: { pitchDeg: 30 } },
});
close(Array.from(past.out), Array.from(full.out));
const back = matrices({
deploy: { gear_nose: 1 },
poses: { gear_nose: { pitchDeg: -30 } },
});
const thirty = matrices({ deploy: { gear_nose: 1 - 30 / 90 } });
close(Array.from(back.out), Array.from(thirty.out));
// A deploy part drawn deployed (rest 0) stows to 90 about +X.
const stowed = matrices({ deploy: { panel: 0 } });
close(apply(stowed.out, stowed.at('panel'), [0, 1, 4]), [0, 0, 5]);
});
test('a child part rides its parent', () => {
// The engine moved 1 m up: its fan, at rest about its own hub, moves with it.
const { out, at } = matrices({ poses: { engine: { offsetM: [0, 0, 1] } } });
close(apply(out, at('engine'), [0, -2, -5]), [0, -1, -5]);
close(apply(out, at('fan'), [-2, -2, -5]), [-2, -1, -5]);
// Spinning too: the hub stays on the moved axis, a blade tip turns about it.
const spun = matrices(
{ poses: { engine: { offsetM: [0, 0, 1] } }, spin: { fan: 90 } },
1,
);
close(apply(spun.out, spun.at('fan'), [-2, -2, -5]), [-2, -1, -5]);
// +90 about +X: +Y turns to +Z.
close(apply(spun.out, spun.at('fan'), [-2, -1, -5]), [-2, -1, -4]);
});
test('a child hinge turns about its pivot as carried by its parent', () => {
const { out, at } = matrices({ deploy: { stage_1: 1, leg_1: 1 } });
// The stage leaves 30 m along −Y; the leg's hinge goes with it and turns 110 about −Z there.
close(apply(out, at('leg_1'), [1, 1, 0]), [1, -29, 0]);
const deg = 110 * (Math.PI / 180);
close(apply(out, at('leg_1'), [1, 2, 0]), [
1 + Math.sin(deg),
-29 + Math.cos(deg),
0,
]);
});
test('a spin turns at its rate over time', () => {
const tip = [-2, -1, -5];
const at = (timeS) => {
const m = matrices({ spin: { fan: 90 } }, timeS);
return apply(m.out, m.at('fan'), tip);
};
close(at(0), tip);
close(at(1), [-2, -2, -4]);
close(at(2), [-2, -3, -5]);
close(at(4), tip);
// A rate times an epoch clock still lands where it should.
close(at(1_700_000_000), tip, 4);
close(at(1_700_000_001), [-2, -2, -4], 4);
// A spin driving a part with no axis does nothing.
assert.equal(matrices({ spin: { engine: 90 } }, 1).posed, false);
});
test('a separable part moves freely: its limits bound only the deploy fraction', () => {
const half = matrices({ deploy: { stage_1: 0.5 } });
close(apply(half.out, half.at('stage_1'), [0, 40, 0]), [0, 25, 0]);
// Posed 500 m right and turned, past any limit (right is −Z).
const { out, at } = matrices({
poses: { stage_1: { offsetM: [500, 0, -200], yawDeg: 30 } },
});
close(apply(out, at('stage_1'), [0, 40, 0]), [0, -160, -500]);
});
test('a slide is clamped along its axis, free across it', () => {
// The door slides along +X (the model's back) 0 to 1.5 m; offsetM is [right, forward, up].
const back = (metres) =>
matrices({ poses: { door: { offsetM: [0, -metres, 0] } } });
close(apply(back(1).out, back(1).at('door'), [0, 0, 1]), [1, 0, 1]);
close(apply(back(9).out, back(9).at('door'), [0, 0, 1]), [1.5, 0, 1]);
close(apply(back(-2).out, back(-2).at('door'), [0, 0, 1]), [0, 0, 1]);
const up = matrices({ poses: { door: { offsetM: [0, -9, 2] } } });
close(apply(up.out, up.at('door'), [0, 0, 1]), [1.5, 2, 1]);
});
test('hidden hides the part and every part riding it', () => {
const { out, flags, at, posed } = matrices({
poses: { engine: { hidden: true } },
});
assert.equal(posed, true);
assert.deepEqual(slice(out, at('engine')), new Array(16).fill(0));
assert.deepEqual(slice(out, at('fan')), new Array(16).fill(0));
assert.equal(flags[TABLE.byName.get('engine')], PART_HIDDEN);
assert.equal(flags[TABLE.byName.get('fan')], PART_HIDDEN);
assert.equal(flags[TABLE.byName.get('flap')], 0);
assert.deepEqual(slice(out, at('flap')), IDENTITY);
});
test('highlight marks the part alone, and does not move it', () => {
const { out, flags, posed } = matrices({
poses: { engine: { highlight: '#ff0' } },
});
assert.equal(posed, true);
assert.equal(flags[TABLE.byName.get('engine')], PART_HIGHLIGHT);
assert.equal(flags[TABLE.byName.get('fan')], 0);
for (let k = 0; k < TABLE.parts.length; k++)
assert.deepEqual(slice(out, k * 16), IDENTITY);
assert.equal(
matrices({ poses: { engine: { highlight: false } } }).posed,
false,
);
});
test('a highlight is true or a colour; anything else asks for none', () => {
for (const value of [true, '#ff0', 'red', [1, 0.5, 0], [1, 0, 0, 0.5]])
assert.equal(asksHighlight(value), true, String(value));
for (const value of [
false,
'',
' ',
0,
1,
null,
undefined,
{},
[1, 0],
[1, 'x', 0],
[NaN, 0, 0],
])
assert.equal(asksHighlight(value), false, String(value));
assert.equal(
matrices({ poses: { engine: { highlight: '' } } }).posed,
false,
);
assert.equal(
matrices({ poses: { engine: { highlight: 0 } } }).posed,
false,
);
});
test('a pose value that is not finite counts as 0', () => {
const { out, posed } = matrices({
poses: {
engine: {
yawDeg: NaN,
pitchDeg: Infinity,
rollDeg: -Infinity,
offsetM: [NaN, Infinity, undefined],
},
},
});
assert.equal(posed, false);
for (let k = 0; k < TABLE.parts.length; k++)
assert.deepEqual(slice(out, k * 16), IDENTITY);
// Beside a finite one, it is still 0 and no NaN is written.
const mixed = matrices({
poses: { engine: { yawDeg: 90, pitchDeg: NaN, offsetM: [NaN, 0, 1] } },
});
assert.equal(mixed.posed, true);
assert.ok(mixed.out.every(Number.isFinite));
});
test('names the table does not have are ignored', () => {
const { posed } = matrices({
poses: { rotor_main: { yawDeg: 30, hidden: true } },
spin: { rotor_main: 100 },
deploy: { gear_main: 1 },
});
assert.equal(posed, false);
});
test('writes from an offset, into float32', () => {
const out = new Float32Array(16 + TABLE.parts.length * 16).fill(7);
const flags = new Uint8Array(3 + TABLE.parts.length).fill(9);
partMatrices(TABLE, { poses: { flap: { hidden: true } } }, 0, out, {
offset: 16,
flags,
flagsOffset: 3,
});
assert.deepEqual(Array.from(out.subarray(0, 16)), new Array(16).fill(7));
assert.deepEqual(Array.from(out.subarray(16, 32)), IDENTITY);
assert.deepEqual(Array.from(flags.subarray(0, 3)), [9, 9, 9]);
assert.equal(flags[3 + TABLE.byName.get('flap')], PART_HIDDEN);
});
});
describe('partMatrices on a stretched model', () => {
/** Where `p` is drawn by a model stretched `scale` whose part is `out`'s matrix at `at`: S · X · p. */
const drawnAt = (out, at, scale, p) => {
const x = apply(out, at, p);
return [x[0] * scale[0], x[1] * scale[1], x[2] * scale[2]];
};
const RADAR = partTableOf({
parts: [
{ name: 'body', kind: 'body' },
{ name: 'radar', kind: 'spin', pivot: [5, 3, 0], axis: [0, 1, 0] },
],
});
const length = (a, b) => Math.hypot(a[0] - b[0], a[1] - b[1], a[2] - b[2]);
test('a radar on a hull drawn twice its length keeps its length at every angle', () => {
const scale = [2, 1, 1];
const hub = [5, 3, 0];
const tip = [6, 3, 0];
const state = { spin: { radar: 30 } };
for (let timeS = 0; timeS < 12; timeS++) {
const out = new Float64Array(32);
partMatrices(RADAR, state, timeS, out, { scale });
const h = drawnAt(out, 16, scale, hub);
const t = drawnAt(out, 16, scale, tip);
// The hub stays where the stretched hull draws it; the 1 m arm is drawn 2 m long.
close(h, [10, 3, 0]);
assert.ok(Math.abs(length(t, h) - 2) < 1e-9);
}
// Unscaled matrices under the same stretch distort it: 1 m long across the hull.
const naive = new Float64Array(32);
partMatrices(RADAR, state, 3, naive);
const h = drawnAt(naive, 16, scale, hub);
const t = drawnAt(naive, 16, scale, tip);
assert.ok(Math.abs(length(t, h) - 1) < 1e-9);
});
test('a hinge turns rigidly about its stretched pivot', () => {
const scale = [1, 3, 1];
const out = new Float64Array(TABLE.parts.length * 16);
partMatrices(TABLE, { deploy: { gear_nose: 1 } }, 0, out, { scale });
const at = TABLE.byName.get('gear_nose') * 16;
close(drawnAt(out, at, scale, [-10, -1, 0]), [-10, -3, 0]);
close(drawnAt(out, at, scale, [-10, -3, 0]), [-16, -3, 0]);
});
test('a slide keeps its limits in the model’s own metres', () => {
const scale = [2, 1, 1];
const out = new Float64Array(TABLE.parts.length * 16);
// Offsets are stretched with the model: 9 m back asked, 1.5 m allowed, drawn 3 m.
partMatrices(TABLE, { poses: { door: { offsetM: [0, -9, 0] } } }, 0, out, {
scale,
});
close(
drawnAt(out, TABLE.byName.get('door') * 16, scale, [0, 0, 1]),
[3, 0, 1],
);
});
test('a scale of one, or none, writes the same matrices', () => {
const state = {
deploy: { gear_nose: 0.3, stage_1: 1, leg_1: 0.5 },
spin: { fan: 33 },
poses: { engine: { offsetM: [1, 2, 3], yawDeg: 10 } },
};
const a = new Float64Array(TABLE.parts.length * 16);
const b = new Float64Array(TABLE.parts.length * 16);
partMatrices(TABLE, state, 1.5, a);
partMatrices(TABLE, state, 1.5, b, { scale: [1, 1, 1] });
assert.deepEqual(Array.from(b), Array.from(a));
});
});