Tidy the vessels layer on the draw port: shared pose key, lazy pose, frame reasons, sprite order

The camera pose key moves to render/camera/poseSignature.js, Cesium-free, and
iconOrientation's cameraPoseSignature builds the same key through it. The
vessels frame hook reads the pose only when a pass runs or a moved camera
could still need its trailing pass, and the unused focus scratch point goes.

The draw port takes the frame port's requestRender, so a GPU icon set's own
frames (its images packed into the atlas) are asked for under the reason
icons:<set id> in the frame diagnostics, where the vessels layer's own
ais-vessels-icons reason used to be. Other draw requests are unchanged.

A host with no registerSpriteSet still draws the ships and warns once. The
vessels draw test now checks the sprite order finds the set's host, and that
a torn-down layer draws a new set registered in the old one's place. The new
motion, icon book and pose key tests join the format check.
This commit is contained in:
Sameh Khamis committed 2026-11-07 02:36:39 -08:00
1 parent 7a9c7b4d96
commit 1c8cf240c4
14 files changed
+334 -76

No files matched your search

+21
View File
@@ -0,0 +1,21 @@
/**
* @module render/camera/poseSignature
* @description A cheap "did the camera move" key for gating passes that
* depend on the view: the eye's ECEF position to 10 m and its heading, pitch
* and roll (radians) to a milliradian. It takes a camera port pose or any
* `{position, heading, pitch, roll}`, so a renderer's own camera reads the
* same key.
*/
/**
* @param {{position: {x: number, y: number, z: number}, heading: number,
* pitch: number, roll: number}} pose
* @returns {string}
*/
export function poseSignature(pose) {
const p = pose.position;
return (
`${Math.round(p.x / 10)}:${Math.round(p.y / 10)}:${Math.round(p.z / 10)}:` +
`${pose.heading.toFixed(3)}:${pose.pitch.toFixed(3)}:${pose.roll.toFixed(3)}`
);
}
+44
View File
@@ -0,0 +1,44 @@
import assert from 'node:assert/strict';
import { readFileSync } from 'node:fs';
import test from 'node:test';
import { cameraPoseSignature } from '../../data/iconOrientation.js';
import { poseSignature } from './poseSignature.js';
const pose = {
position: { x: 3_975_123.4, y: 289_456.7, z: 4_998_765.1 },
heading: 1.23456,
pitch: -0.7071,
roll: 0.0004,
};
test('the pose key holds the eye to 10 m and its angles to a milliradian', () => {
assert.equal(poseSignature(pose), '397512:28946:499877:1.235:-0.707:0.000');
const near = {
...pose,
position: { ...pose.position, x: pose.position.x + 1 },
heading: pose.heading + 0.0003,
};
assert.equal(poseSignature(near), poseSignature(pose), 'too small to move');
assert.notEqual(
poseSignature({ ...pose, pitch: pose.pitch + 0.002 }),
poseSignature(pose),
);
});
test('a Cesium camera keys the same as the pose it reads', () => {
const camera = {
positionWC: pose.position,
heading: pose.heading,
pitch: pose.pitch,
roll: pose.roll,
};
assert.equal(cameraPoseSignature(camera), poseSignature(pose));
});
test('the pose key imports no renderer', () => {
const source = readFileSync(
new URL('./poseSignature.js', import.meta.url),
'utf8',
);
assert.doesNotMatch(source, /from 'cesium'/);
});
+12 -3
View File
@@ -139,13 +139,18 @@ const ANCHORS = {
* sets by id, a version that changes with them, the scene's 3D tilesets and
* the clamp-state watch the frame loop runs after each draw.
* @param {{scene: object, report: (error: unknown) => void,
* capabilities?: ReadonlySet<string>}} options `capabilities` gate the
* GPU icon sets' members (by default they all are).
* capabilities?: ReadonlySet<string>,
* requestRender?: (reason: string) => void}} options `capabilities` gate
* the GPU icon sets' members (by default they all are); `requestRender`,
* the frame port's, asks for the frames a GPU icon set needs on its own
* (its images packed), under the reason `icons:<set id>` (by default the
* scene's, with no reason).
*/
export function createCesiumDraw({
scene,
report,
capabilities = new Set(GPU_ICON_CAPABILITIES),
requestRender: requestFrame = null,
}) {
const sets = new Map();
// Bumped on every change to the sets or what they hold.
@@ -322,7 +327,11 @@ export function createCesiumDraw({
toColor,
imageOf: (record, image) => iconImage(record, image),
peekImage: (image) => atlases.get(image.atlas)?.[image.slot],
requestRender,
requestRender: (reason) => {
if (!live()) return;
if (requestFrame) requestFrame(reason);
else scene.requestRender();
},
});
/**
+127 -43
View File
@@ -1704,12 +1704,12 @@ test('icons scale, fade and show by eye distance, and drop the curves in place',
set.dispose();
});
test('the vessels layer draws its ships as one GPU icon set that holds them on course', async () => {
/**
* The vessels layer over a fake scene, drawing through the draw port, with
* `sprites` as its sprite-order services.
*/
async function vesselLayerOver(scene, sprites) {
const { createVesselLayer } = await import('../../layers/vessels/index.js');
const { IconSetPrimitive } = await import('../../data/iconSetPrimitive.js');
const { ICON_CULL_LIFT, ICON_ROTATES } =
await import('../../data/iconSet.js');
const scene = fakeScene();
const part = createCesiumDraw({
scene,
report: (error) => assert.fail(error),
@@ -1738,7 +1738,7 @@ test('the vessels layer draws its ships as one GPU icon set that holds them on c
clearOverlaySource: noop,
},
geoid: {},
sprites: {},
sprites,
focus: {
focusNowMs: (now) => now,
getFocusTarget: () => null,
@@ -1753,46 +1753,130 @@ test('the vessels layer draws its ships as one GPU icon set that holds them on c
},
},
});
layer.testing._setVesselStateForTest({ viewer, icons: null });
layer.testing._reconcileVesselsForTest(viewer, [
{ mmsi: '244000001', lat: 51.95, lon: 4.1, heading: 90, speed: 12 },
{ mmsi: '244000002', lat: 51.96, lon: 4.2, course: 200, speed: 2 },
]);
const [host] = scene.added;
assert.ok(host instanceof IconSetPrimitive, 'one GPU icon set');
assert.match(host.drawSetId, /^ais-vessels:\d+$/);
const record = part.sets.get(host.drawSetId);
const set = record.gpu.set;
assert.equal(set.count, 2);
const row = set.row('244000001');
const tau = set.seconds(Cesium.JulianDate.now());
assert.equal(set.course(row, tau), 90, 'held on its heading');
assert.equal(set.course(set.row('244000002'), tau), 200, 'or its course');
assert.equal(set.width(row), 32);
assert.ok(Math.abs(set.scale(row) - 0.68) < 1e-6, 'scaled by speed');
assert.equal(set.flags(row) & ICON_ROTATES, ICON_ROTATES);
assert.equal(set.flags(row) & ICON_CULL_LIFT, ICON_CULL_LIFT);
assert.ok(set.depthTestDistance(row) >= 1e30, 'over depth everywhere');
const at = Cesium.Cartographic.fromCartesian(set.position(row, tau));
assert.ok(Math.abs(Cesium.Math.toDegrees(at.longitude) - 4.1) < 1e-6);
assert.ok(Math.abs(Cesium.Math.toDegrees(at.latitude) - 51.95) < 1e-6);
const facade = { show: true };
assert.deepEqual(drawHitOf(host._pickObject('244000001', null, facade)), {
set: host.drawSetId,
id: '244000001',
meta: { layer: 'ais-live-vessels', id: '244000001' },
surface: false,
return { layer, viewer, part, unbind };
}
test('the vessels layer draws its ships as one GPU icon set that holds them on course', async () => {
const { IconSetPrimitive } = await import('../../data/iconSetPrimitive.js');
const { ICON_CULL_LIFT, ICON_ROTATES } =
await import('../../data/iconSet.js');
const spriteOrder = await import('../../data/spriteOrder.js');
const scene = fakeScene();
const registered = [];
const { layer, viewer, part, unbind } = await vesselLayerOver(scene, {
registerSpriteSet(layerId, setId) {
registered.push([layerId, setId]);
return spriteOrder.registerSpriteSet(layerId, setId);
},
});
const military = { name: 'military' };
try {
layer.testing._setVesselStateForTest({ viewer, icons: null });
layer.testing._reconcileVesselsForTest(viewer, [
{ mmsi: '244000001', lat: 51.95, lon: 4.1, heading: 90, speed: 12 },
{ mmsi: '244000002', lat: 51.96, lon: 4.2, course: 200, speed: 2 },
]);
const [host] = scene.added;
assert.ok(host instanceof IconSetPrimitive, 'one GPU icon set');
assert.match(host.drawSetId, /^ais-vessels:\d+$/);
const record = part.sets.get(host.drawSetId);
const set = record.gpu.set;
assert.equal(set.count, 2);
const row = set.row('244000001');
const tau = set.seconds(Cesium.JulianDate.now());
assert.equal(set.course(row, tau), 90, 'held on its heading');
assert.equal(set.course(set.row('244000002'), tau), 200, 'or its course');
assert.equal(set.width(row), 32);
assert.ok(Math.abs(set.scale(row) - 0.68) < 1e-6, 'scaled by speed');
assert.equal(set.flags(row) & ICON_ROTATES, ICON_ROTATES);
assert.equal(set.flags(row) & ICON_CULL_LIFT, ICON_CULL_LIFT);
assert.ok(set.depthTestDistance(row) >= 1e30, 'over depth everywhere');
const at = Cesium.Cartographic.fromCartesian(set.position(row, tau));
assert.ok(Math.abs(Cesium.Math.toDegrees(at.longitude) - 4.1) < 1e-6);
assert.ok(Math.abs(Cesium.Math.toDegrees(at.latitude) - 51.95) < 1e-6);
const facade = { show: true };
assert.deepEqual(drawHitOf(host._pickObject('244000001', null, facade)), {
set: host.drawSetId,
id: '244000001',
meta: { layer: 'ais-live-vessels', id: '244000001' },
surface: false,
});
// A poll that moves one and drops the other writes rows, not a new host.
layer.testing._reconcileVesselsForTest(viewer, [
{ mmsi: '244000001', lat: 51.95, lon: 4.12, heading: 95, speed: 12 },
]);
assert.equal(scene.added[0], host);
assert.equal(set.count, 1);
assert.equal(set.course(set.row('244000001'), tau), 95);
// A poll that moves one and drops the other writes rows, not a new host.
layer.testing._reconcileVesselsForTest(viewer, [
{ mmsi: '244000001', lat: 51.95, lon: 4.12, heading: 95, speed: 12 },
]);
assert.equal(scene.added[0], host);
assert.equal(set.count, 1);
assert.equal(set.course(set.row('244000001'), tau), 95);
// The sprite order finds the host by its set id and stacks it under the
// military sprites.
assert.deepEqual(registered, [['ais', host.drawSetId]]);
spriteOrder.registerSpriteCollection('military', military);
const stack = (list) => ({
scene: {
primitives: {
get: (i) => list[i],
get length() {
return list.length;
},
contains: (p) => list.includes(p),
raiseToTop(p) {
list.splice(list.indexOf(p), 1);
list.push(p);
},
},
},
});
const order = [military, host, { name: 'other' }];
spriteOrder.restoreSpriteOrder(stack(order));
assert.deepEqual(
order.map((p) => p.name ?? p.drawSetId),
['other', host.drawSetId, 'military'],
);
// Torn down and drawn again: a new set, registered in the old one's
// place, with the old host gone from the scene.
layer.destroy(viewer);
assert.equal(scene.added.length, 0, 'destroyed: the set goes');
layer.testing._setVesselStateForTest({ viewer, icons: null });
layer.testing._reconcileVesselsForTest(viewer, [
{ mmsi: '244000003', lat: 51.9, lon: 4.0, heading: 10, speed: 5 },
]);
assert.equal(scene.added.length, 1);
const [again] = scene.added;
assert.notEqual(again, host);
assert.notEqual(again.drawSetId, host.drawSetId, 'a new set id');
assert.equal(part.sets.has(host.drawSetId), false);
assert.deepEqual(registered.at(-1), ['ais', again.drawSetId]);
const stray = { name: 'stray' };
const next = [military, again, stray];
spriteOrder.restoreSpriteOrder(stack(next));
assert.deepEqual(next, [stray, again, military], 'the new host is raised');
layer.destroy(viewer);
assert.equal(scene.added.length, 0);
} finally {
spriteOrder.unregisterSpriteCollection('military', military);
spriteOrder.unregisterSpriteCollection('ais');
unbind();
}
});
test('vessels on a host with no sprite-set registry still draw, and say so once', async (t) => {
const warnings = [];
t.mock.method(console, 'warn', (...args) => warnings.push(args.join(' ')));
const scene = fakeScene();
const { layer, viewer, unbind } = await vesselLayerOver(scene, {});
const ship = { mmsi: '244000001', lat: 51.95, lon: 4.1, heading: 90 };
layer.testing._setVesselStateForTest({ viewer, icons: null });
layer.testing._reconcileVesselsForTest(viewer, [ship]);
assert.equal(scene.added.length, 1, 'drawn');
layer.destroy(viewer);
layer.testing._setVesselStateForTest({ viewer, icons: null });
layer.testing._reconcileVesselsForTest(viewer, [ship]);
const said = warnings.filter((w) => w.includes('registerSpriteSet'));
assert.equal(said.length, 1, 'once, not per set');
layer.destroy(viewer);
assert.equal(scene.added.length, 0, 'destroyed: the set goes');
unbind();
});
+2 -2
View File
@@ -174,7 +174,7 @@ function rasterPxOf(url, item) {
* toColor: (color: unknown) => Cesium.Color,
* imageOf: (record: object, image: unknown) => unknown,
* peekImage: (ref: {atlas: string, slot: string}) => unknown,
* requestRender: () => void}} options `imageOf` reads an atlas slot
* requestRender: (reason: string) => void}} options `imageOf` reads an atlas slot
* through the draw port's atlases (undefined while it is not registered),
* noting that the set draws from it; `peekImage` only reads it.
*/
@@ -286,7 +286,7 @@ export function createGpuIcons({
set,
renderTime: (frameState) =>
clockTime(frameState, new Cesium.JulianDate()),
requestRender,
requestRender: () => requestRender(`icons:${spec.id}`),
cull: () => spec.horizonCull === true,
// Picked as the draw port's other items are: `{set, id, meta,
// lodGroup}` as the item now is, hidden row by row for drill picks.
+33
View File
@@ -833,3 +833,36 @@ test('the atlas holds more than 64 images, every one addressed on WebGL 2', asyn
);
assert.equal(slots.size, 70, 'each its own slot');
});
test('a GPU icon set asks the frame port for its atlas frames, under its own reason', async () => {
const { iconAtlas } = await import('../../data/iconAtlas.js');
const onChange = iconAtlas.onChange;
const heard = [];
iconAtlas.onChange = (listener) => (heard.push(listener), () => {});
try {
const reasons = [];
const { scene, draw } = drawOver({
requestRender: (reason) => reasons.push(reason),
});
const set = draw.icons({ id: 'gpu:reason' });
set.set([icon('a', { motion: { kind: 'hold' } })]);
assert.equal(heard.length, 1, 'its host listens for packed images');
const before = scene.renders;
heard[0]();
assert.deepEqual(reasons, ['icons:gpu:reason']);
assert.equal(scene.renders, before, 'through the frame port only');
set.dispose();
// With no frame port, the scene's own request, as before.
const bare = drawOver();
const bareSet = bare.draw.icons({ id: 'gpu:bare' });
bareSet.set([icon('a', { motion: { kind: 'hold' } })]);
assert.equal(heard.length, 2);
const was = bare.scene.renders;
heard[1]();
assert.equal(bare.scene.renders, was + 1);
bareSet.dispose();
} finally {
iconAtlas.onChange = onChange;
}
});
+6 -1
View File
@@ -290,7 +290,12 @@ export function createCesiumPorts(widget, { capabilities, credentials = {} }) {
// --- Draw ------------------------------------------------------------------
const drawPart = createCesiumDraw({ scene, report, capabilities });
const drawPart = createCesiumDraw({
scene,
report,
capabilities,
requestRender: (reason) => frame.requestRender(reason),
});
const { port: draw, sets, tilesets } = drawPart;
const cameraPart = createCesiumCamera({ scene, camera, report, widget });