Files
gods-eye-view/src/render/modelParts.test.mjs
T
Sameh Khamis 7186f720df 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.
2026-11-17 15:09:54 -08:00

574 lines
19 KiB
JavaScript
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
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));
});
});