vessels: move drawn vessels following the clock once they would move half a pixel

A profile of about 9,000 vessels following a playing world clock spent
~13 ms of every frame in the clock pass, moving every drawn vessel a
fraction of a pixel, and ~4 ms more re-uploading their billboards.

- Drawn vessels move again once the fastest would have moved half a pixel
  on screen at the speed each last moved (measured from the world time it
  was drawn at), at least once a second, and at once when the camera moves
  or changes height by a tenth of its height or the view zooms. A pass that
  holds them back asks for a frame, so a paused clock settles on the time.
- Hidden vessels move a share of them each pass, each within 250 ms, rather
  than all of them in one frame; the visibility pass moves one coming into
  view to the time first.
- A vessel's three positions are written from one surface point and normal
  (Cesium's own formula) instead of three fromDegrees calls; the unused
  normal is dropped. The great-circle step builds no arrays.

The pass falls from 4.6 ms to 0.37 ms a frame on average in a benchmark of
9,000 vessels (3,000 drawn) at 240 frames a second.
This commit is contained in:
Sameh Khamis committed 2026-11-15 13:35:11 -08:00
1 parent 8af8c086a6
commit 1f6e8914f2
5 files changed
+589 -114

No files matched your search

+277 -6
View File
@@ -325,8 +325,7 @@ test('following the clock moves drawn vessels in place each world time, prepares
const before = visuals.map((visual) => ({ ...visual.position }));
const positions = visuals.map((visual) => visual.position);
// The first pass also moves hidden vessels, so the next stays within
// HIDDEN_FOLLOW_MS of it.
// The first pass moves hidden vessels too.
layer.testing._runClockPassForTest(10_000);
mono += 16;
layer.testing._runClockPassForTest(20_000);
@@ -337,10 +336,7 @@ test('following the clock moves drawn vessels in place each world time, prepares
assert.ok(missing.billboard.position, 'a missing visual is prepared');
assert.equal(timers.size, 1, 'moving vessels ask for a frame');
// The hidden vessel waits for HIDDEN_FOLLOW_MS.
mono += 16;
layer.testing._runClockPassForTest(30_000);
assert.deepEqual({ ...visuals[1].position }, hiddenAt);
// Hidden vessels move a share each pass, each within HIDDEN_FOLLOW_MS.
mono += 250;
layer.testing._runClockPassForTest(40_000);
assert.notDeepEqual({ ...visuals[1].position }, hiddenAt);
@@ -375,3 +371,278 @@ test('following the clock moves drawn vessels in place each world time, prepares
layer.testing._runClockPassForTest(80_000);
assert.equal(timers.size, 0);
});
test('following the clock, drawn vessels move again once the fastest would have moved half a pixel, a second has gone by or the camera changed height', (t) => {
let mono = 0;
t.mock.method(performance, 'now', () => mono);
const originalDocument = globalThis.document;
globalThis.document = { getElementById: () => null };
t.after(() => {
if (originalDocument === undefined) delete globalThis.document;
else globalThis.document = originalDocument;
});
const { layer, camera } = setup();
// 20 km above, in a 1,000 px tall view about 57° tall: half a pixel is
// about 11 m. The vessel makes about 1.9 m a second of world time.
camera.positionWC = Cesium.Cartesian3.fromDegrees(4.05, 51.93, 20_000);
camera.frustum = { fovy: 1 };
const record = {
mmsi: '111',
lat: 51.93,
lon: 4.05,
motion: {
fromLat: 51.93,
fromLon: 4.05,
fromMs: 0,
toLat: 51.94,
toLon: 4.05,
toMs: 600_000,
},
billboard: { show: true, position: null },
};
layer.testing._setVesselStateForTest({
viewer: { camera, scene: {}, canvas: { clientHeight: 1000 } },
records: [record],
});
const visual = layer.testing._prepareVesselVisualForTest(record);
const at = () => ({ ...visual.position });
const pass = (atMs, wallMs = 16) => {
mono += wallMs;
layer.testing._runClockPassForTest(atMs);
};
// Two passes a world second apart measure how fast it moves on screen.
pass(10_000);
pass(11_000);
let drawn = at();
// A few metres more stay under half a pixel: it is left where it is.
pass(12_000);
pass(14_000);
assert.deepEqual(at(), drawn);
// About 13 m on from where it was drawn: it moves.
pass(18_000);
assert.notDeepEqual(at(), drawn);
drawn = at();
// Under half a pixel, but a second later: it moves.
pass(19_000, 1_000);
assert.notDeepEqual(at(), drawn);
drawn = at();
pass(20_000);
assert.deepEqual(at(), drawn);
// Under half a pixel, but the camera came down by half: it moves.
camera.positionWC = Cesium.Cartesian3.fromDegrees(4.05, 51.93, 10_000);
pass(21_000);
assert.notDeepEqual(at(), drawn);
// Scrubbed well back, it moves back at once.
drawn = at();
pass(1_000);
assert.notDeepEqual(at(), drawn);
});
test('a vessel is drawn lifted above the sea surface, its waterline on it, as Cesium places them', () => {
const { layer, camera } = setup();
const record = {
mmsi: '111',
lat: 51.93,
lon: 4.05,
billboard: { show: true, position: null },
};
layer.testing._setVesselStateForTest({
viewer: { camera, scene: {} },
records: [record],
});
const visual = layer.testing._prepareVesselVisualForTest(record);
const heightOf = (position) =>
Cesium.Ellipsoid.WGS84.cartesianToCartographic(position).height;
const close = (actual, expected) =>
assert.ok(
Cesium.Cartesian3.distance(actual, expected) < 1e-6,
`${actual} is not ${expected}`,
);
close(visual.surfacePosition, Cesium.Cartesian3.fromDegrees(4.05, 51.93, 0));
close(
visual.position,
Cesium.Cartesian3.fromDegrees(4.05, 51.93, heightOf(visual.position)),
);
close(
visual.waterline,
Cesium.Cartesian3.fromDegrees(4.05, 51.93, heightOf(visual.waterline)),
);
assert.ok(heightOf(visual.position) > heightOf(visual.waterline));
});
test('following the clock, a pass moves hidden vessels in proportion to the wall time since the last, so all move within HIDDEN_FOLLOW_MS', (t) => {
let mono = 0;
t.mock.method(performance, 'now', () => mono);
const originalDocument = globalThis.document;
globalThis.document = { getElementById: () => null };
t.after(() => {
if (originalDocument === undefined) delete globalThis.document;
else globalThis.document = originalDocument;
});
const { layer, camera } = setup();
const records = Array.from({ length: 100 }, (_, i) => ({
mmsi: String(i),
lat: 51.93,
lon: 4.05,
motion: {
fromLat: 51.93,
fromLon: 4.05,
fromMs: 0,
toLat: 51.94,
toLon: 4.05,
toMs: 600_000,
},
billboard: { show: false, position: null },
}));
layer.testing._setVesselStateForTest({
viewer: { camera, scene: {}, canvas: { clientHeight: 1000 } },
records,
});
const visuals = records.map((record) =>
layer.testing._prepareVesselVisualForTest(record),
);
layer.testing._runClockPassForTest(10_000);
const moved = (atMs) => visuals.filter((v) => v.followedAtMs === atMs).length;
assert.equal(moved(10_000), 100, 'the first pass moves them all');
mono += 25;
layer.testing._runClockPassForTest(20_000);
assert.equal(moved(20_000), 10, 'a tenth of HIDDEN_FOLLOW_MS, a tenth');
for (let i = 0; i < 9; i += 1) {
mono += 25;
layer.testing._runClockPassForTest(20_000);
}
assert.equal(moved(20_000), 100, 'all within HIDDEN_FOLLOW_MS');
});
test('following the clock, the step gate measures each vessel from when it was drawn, and reopens for a pan, a zoom or a pause', (t) => {
let mono = 0;
t.mock.method(performance, 'now', () => mono);
const originalDocument = globalThis.document;
globalThis.document = { getElementById: () => null };
t.after(() => {
if (originalDocument === undefined) delete globalThis.document;
else globalThis.document = originalDocument;
});
const { layer, camera } = setup();
const above = Cesium.Cartesian3.fromDegrees(4.05, 51.93, 20_000);
camera.positionWC = above;
camera.frustum = { fovy: 1 };
const record = {
mmsi: '111',
lat: 51.93,
lon: 4.05,
motion: {
fromLat: 51.93,
fromLon: 4.05,
fromMs: 0,
toLat: 51.94,
toLon: 4.05,
toMs: 600_000,
},
billboard: { show: true, position: null },
};
layer.testing._setVesselStateForTest({
viewer: { camera, scene: {}, canvas: { clientHeight: 1000 } },
records: [record],
});
const visual = layer.testing._prepareVesselVisualForTest(record);
const at = () => ({ ...visual.position });
const pass = (atMs) => {
mono += 16;
layer.testing._runClockPassForTest(atMs);
};
// About 0.08 px a world second: measured over a second.
pass(10_000);
pass(11_000);
pass(13_000);
// A snapshot draws it afresh just before the next pass: the pass after
// it measures the move over that short time, not since 11 s.
layer.testing._followClockForTest(17_900);
layer.testing._prepareVesselVisualForTest(record);
pass(18_000);
let drawn = at();
pass(19_000);
assert.deepEqual(at(), drawn, 'the speed it measured is still its own');
pass(24_500);
assert.notDeepEqual(at(), drawn, 'and it moves once half a pixel is up');
// Panned sideways by more than a tenth of the camera's height: it moves.
drawn = at();
pass(25_000);
assert.deepEqual(at(), drawn);
camera.positionWC = Cesium.Cartesian3.fromDegrees(4.1, 51.93, 20_000);
pass(25_500);
assert.notDeepEqual(at(), drawn);
// Zoomed in by narrowing the view: it moves.
drawn = at();
pass(26_000);
assert.deepEqual(at(), drawn);
camera.frustum = { fovy: 0.5 };
pass(26_500);
assert.notDeepEqual(at(), drawn);
// Paused just after a pass that left it short: the next frame at the same
// time draws it where it is.
drawn = at();
pass(27_000);
assert.deepEqual(at(), drawn);
pass(27_000);
assert.notDeepEqual(at(), drawn);
const where = at();
pass(27_000);
assert.deepEqual(at(), where, 'then holds');
});
test('following the clock, a vessel the visibility pass shows before the clock passes moved it is drawn at the time', (t) => {
let mono = 0;
t.mock.method(performance, 'now', () => mono);
const originalDocument = globalThis.document;
globalThis.document = { getElementById: () => null };
t.after(() => {
if (originalDocument === undefined) delete globalThis.document;
else globalThis.document = originalDocument;
});
const { layer, camera } = setup();
camera.positionWC = Cesium.Cartesian3.fromDegrees(4.05, 51.93, 20_000);
camera.frustum = { fovy: 1 };
const vessel = (mmsi) => ({
mmsi,
lat: 51.93,
lon: 4.05,
motion: {
fromLat: 51.93,
fromLon: 4.05,
fromMs: 0,
toLat: 52.93,
toLon: 4.05,
toMs: 3_600_000,
},
billboard: { show: false, position: null },
});
const records = Array.from({ length: 40 }, (_, i) => vessel(String(i)));
const last = records.at(-1);
layer.testing._setVesselStateForTest({
// No scene: the labels are not placed.
viewer: { camera, scene: null, canvas: { clientHeight: 1000 } },
records,
});
layer.testing._followClockForTest(0);
const visual = layer.testing._prepareVesselVisualForTest(last);
for (const record of records.slice(0, -1))
layer.testing._prepareVesselVisualForTest(record);
layer.testing._runClockPassForTest(10_000);
// Paused, a seek far on: the next frame moves only a share of the hidden
// vessels, not the last.
mono += 16;
layer.testing._runClockPassForTest(11_000);
mono += 16;
layer.testing._runClockPassForTest(1_800_000);
assert.notEqual(visual.followedAtMs, 1_800_000);
layer.testing._runVisibilityPassForTest(true);
assert.equal(last.billboard.show, true);
const { latitude } = Cesium.Ellipsoid.WGS84.cartesianToCartographic(
visual.surfacePosition,
);
assert.ok(Math.abs(Cesium.Math.toDegrees(latitude) - 52.43) < 1e-6);
});