From b65bb86db325ae023ffa976b18fbca73bd968d07 Mon Sep 17 00:00:00 2001 From: Sameh Khamis Date: Sun, 15 Nov 2026 16:13:28 -0800 Subject: [PATCH 1/3] vessels: project label candidates with the camera read once per pass The label pass projects every vessel in view each time it runs. It asked Cesium for each one, which reads the camera and allocates for every point. createWindowProjector reads the camera's matrices and the canvas size once and runs the same arithmetic in the same order, so the window positions are the same numbers (a test compares them bit for bit with Cesium); outside a 3D perspective view it asks Cesium as before. Grid cells are keyed by number, a cell's candidate is made only for its first vessel and updated in place, and whether a name is worth a card is kept per vessel until its name, MMSI or id changes. Measured in the browser (perf harness, 9,000 vessels, 1 min/s): the label pass 33 ms -> 11 ms, the forced visibility pass 42 ms -> 27 ms. --- scripts/package-boundaries.json | 3 + src/data/windowProjection.js | 65 +++++++++++++++ src/data/windowProjection.test.mjs | 122 +++++++++++++++++++++++++++++ src/layers/vessels/rendering.js | 63 +++++++++++---- 4 files changed, 239 insertions(+), 14 deletions(-) create mode 100644 src/data/windowProjection.js create mode 100644 src/data/windowProjection.test.mjs diff --git a/scripts/package-boundaries.json b/scripts/package-boundaries.json index ec76dd86f..2aa8c9452 100644 --- a/scripts/package-boundaries.json +++ b/scripts/package-boundaries.json @@ -1734,6 +1734,7 @@ "src/layers/vessels/policy.js", "src/layers/vessels/queries.js", "src/layers/vessels/rendering.js", + "src/data/windowProjection.js", "src/layers/vessels/selection.js", "src/layers/vessels/state.js", "src/layers/vessels/testing.js", @@ -3038,6 +3039,7 @@ "src/layers/vessels/policy.js", "src/layers/vessels/queries.js", "src/layers/vessels/rendering.js", + "src/data/windowProjection.js", "src/layers/vessels/selection.js", "src/layers/vessels/state.js", "src/layers/vessels/testing.js", @@ -4232,6 +4234,7 @@ "src/layers/vessels/policy.js", "src/layers/vessels/queries.js", "src/layers/vessels/rendering.js", + "src/data/windowProjection.js", "src/layers/vessels/selection.js", "src/layers/vessels/state.js", "src/layers/vessels/testing.js", diff --git a/src/data/windowProjection.js b/src/data/windowProjection.js new file mode 100644 index 000000000..5533103cb --- /dev/null +++ b/src/data/windowProjection.js @@ -0,0 +1,65 @@ +import * as Cesium from 'cesium'; + +/** + * A projector from world positions to window coordinates for one pass over + * many positions under one camera, giving what + * `Cesium.SceneTransforms.worldToWindowCoordinates` gives: in a 3D scene with + * a perspective camera it runs the same arithmetic in the same order once the + * camera's matrices and the canvas size are read, so the results are the same + * numbers; otherwise it asks Cesium for each. + * + * Read the camera again (a new projector) whenever it may have moved. + * @param {Cesium.Scene} scene + * @returns {(position: Cesium.Cartesian3, result: Cesium.Cartesian2) => + * Cesium.Cartesian2|undefined} The window position in `result`, or + * undefined behind the camera. + */ +export function createWindowProjector(scene) { + const camera = scene?.camera; + const frustum = camera?.frustum; + if ( + scene?.frameState?.mode !== Cesium.SceneMode.SCENE3D || + !camera || + frustum instanceof Cesium.OrthographicFrustum || + frustum instanceof Cesium.OrthographicOffCenterFrustum + ) + return (position, result) => + Cesium.SceneTransforms.worldToWindowCoordinates(scene, position, result); + const v = camera.viewMatrix; + const p = frustum.projectionMatrix; + const width = scene.canvas.clientWidth; + const height = scene.canvas.clientHeight; + const halfWidth = width * 0.5; + const halfHeight = height * 0.5; + return (position, result) => { + if (!position) + return Cesium.SceneTransforms.worldToWindowCoordinates( + scene, + position, + result, + ); + const { x, y, z } = position; + // Eye coordinates, as Matrix4.multiplyByVector computes them (w = 1). + const ex = v[0] * x + v[4] * y + v[8] * z + v[12]; + const ey = v[1] * x + v[5] * y + v[9] * z + v[13]; + const ez = v[2] * x + v[6] * y + v[10] * z + v[14]; + const ew = v[3] * x + v[7] * y + v[11] * z + v[15]; + // At the eye itself Cesium's own steps have no direction to take. + if (ex === 0 && ey === 0 && ez === 0) + return Cesium.SceneTransforms.worldToWindowCoordinates( + scene, + position, + result, + ); + // Clip coordinates. + const cx = p[0] * ex + p[4] * ey + p[8] * ez + p[12] * ew; + const cy = p[1] * ex + p[5] * ey + p[9] * ez + p[13] * ew; + const cz = p[2] * ex + p[6] * ey + p[10] * ez + p[14] * ew; + const cw = p[3] * ex + p[7] * ey + p[11] * ez + p[15] * ew; + if (cz < 0) return undefined; + // The viewport transform of the canvas, then window y downward. + result.x = halfWidth * (cx / cw) + halfWidth; + result.y = height - (halfHeight * (cy / cw) + halfHeight); + return result; + }; +} diff --git a/src/data/windowProjection.test.mjs b/src/data/windowProjection.test.mjs new file mode 100644 index 000000000..ae1fe4883 --- /dev/null +++ b/src/data/windowProjection.test.mjs @@ -0,0 +1,122 @@ +import test from 'node:test'; +import assert from 'node:assert/strict'; +import * as Cesium from 'cesium'; +import { createWindowProjector } from './windowProjection.js'; + +function sceneLooking( + lon, + lat, + heightM, + pitchDeg, + mode = Cesium.SceneMode.SCENE3D, +) { + const scene = { + canvas: { clientWidth: 1713, clientHeight: 941 }, + drawingBufferWidth: 1713, + drawingBufferHeight: 941, + mapProjection: new Cesium.GeographicProjection(), + ellipsoid: Cesium.Ellipsoid.WGS84, + frameState: { mode, mapProjection: new Cesium.GeographicProjection() }, + globe: undefined, + tweens: { add() {} }, + screenSpaceCameraController: { minimumZoomDistance: 1 }, + }; + scene.camera = new Cesium.Camera(scene); + scene.camera.frustum.aspectRatio = 1713 / 941; + scene.camera.setView({ + destination: Cesium.Cartesian3.fromDegrees(lon, lat, heightM), + orientation: { + heading: 0.3, + pitch: Cesium.Math.toRadians(pitchDeg), + roll: 0, + }, + }); + return scene; +} + +function positionsAround(lon, lat, spreadDeg, count) { + let seed = 7; + const rnd = () => (seed = (seed * 16807) % 2147483647) / 2147483647; + return Array.from({ length: count }, () => + Cesium.Cartesian3.fromDegrees( + lon + (rnd() - 0.5) * spreadDeg, + lat + (rnd() - 0.5) * spreadDeg, + rnd() * 50, + ), + ); +} + +test('a 3D perspective projector gives the same numbers Cesium gives', () => { + for (const [pitch, spread, heightM] of [ + [-90, 1, 60_000], + [-35, 4, 60_000], + [-5, 40, 60_000], + // Just above the sea, points near and behind the near plane. + [-10, 0.002, 3], + ]) { + const scene = sceneLooking(4.1, 51.95, heightM, pitch); + const project = createWindowProjector(scene); + let behind = 0; + for (const position of positionsAround(4.1, 51.95, spread, 2000)) { + const expected = Cesium.SceneTransforms.worldToWindowCoordinates( + scene, + position, + new Cesium.Cartesian2(), + ); + const actual = project(position, new Cesium.Cartesian2()); + if (!expected) { + behind++; + assert.equal(actual, undefined); + continue; + } + assert.equal(actual.x, expected.x); + assert.equal(actual.y, expected.y); + } + if (pitch === -5) + assert.ok(behind > 0, 'some positions fall behind the camera'); + } +}); + +test('outside a 3D scene the projector asks Cesium', () => { + const scene = sceneLooking( + 4.1, + 51.95, + 60_000, + -90, + Cesium.SceneMode.COLUMBUS_VIEW, + ); + const calls = []; + const original = Cesium.SceneTransforms.worldToWindowCoordinates; + Cesium.SceneTransforms.worldToWindowCoordinates = (...args) => { + calls.push(args); + return args[2]; + }; + try { + const result = new Cesium.Cartesian2(); + const position = Cesium.Cartesian3.fromDegrees(4.1, 51.95); + assert.equal(createWindowProjector(scene)(position, result), result); + assert.equal(calls.length, 1); + assert.equal(calls[0][1], position); + } finally { + Cesium.SceneTransforms.worldToWindowCoordinates = original; + } +}); + +test('at the eye itself, or with no position, the projector asks Cesium', () => { + const scene = sceneLooking(4.1, 51.95, 60_000, -90); + const original = Cesium.SceneTransforms.worldToWindowCoordinates; + const asked = []; + Cesium.SceneTransforms.worldToWindowCoordinates = (_scene, position) => { + asked.push(position); + return undefined; + }; + try { + const project = createWindowProjector(scene); + const eye = Cesium.Cartesian3.clone(scene.camera.positionWC); + assert.equal(project(eye, new Cesium.Cartesian2()), undefined); + assert.equal(project(undefined, new Cesium.Cartesian2()), undefined); + assert.deepEqual(asked, [eye, undefined]); + } finally { + Cesium.SceneTransforms.worldToWindowCoordinates = original; + } +}); diff --git a/src/layers/vessels/rendering.js b/src/layers/vessels/rendering.js index cc49ce7b4..bb4c2aa90 100644 --- a/src/layers/vessels/rendering.js +++ b/src/layers/vessels/rendering.js @@ -31,6 +31,12 @@ import { } from '../../data/fleetModels.js'; import { createFleetModelLayer } from '../../data/fleetModelInstances.js'; import { isAidToNavigation } from '../../data/vesselTypes.js'; +import { createWindowProjector } from '../../data/windowProjection.js'; + +// Label grid cells are keyed by column * LABEL_CELL_ROW + row, unique while +// rows stay within half of it either side; a cell further off screen is keyed +// by its text. +const LABEL_CELL_ROW = 1 << 20; /** A moving vessel's next frame is asked for once it would move this far on * screen (pixels), so it glides when it moves visibly and the scene idles @@ -70,6 +76,7 @@ export function createRendering({ }) { const { state } = vesselState; let visualRecords = new WeakMap(); + const labelScreenScratch = new Cesium.Cartesian2(); // The fallback preserves helper calls with externally supplied render records. function getVisual(record) { @@ -1038,25 +1045,30 @@ export function createRendering({ return; } + // Every vessel in view is projected, so the camera is read once and each + // is a few multiplications (see windowProjection.js) into one screen + // point; a cell gets a candidate only for the vessel that leads it. + const project = createWindowProjector(scene); const cells = new Map(); for (const record of records) { - const visual = getVisual(record); if (record === selected) continue; - const screen = Cesium.SceneTransforms.worldToWindowCoordinates( - scene, - visual.position, - ); + const screen = project(getVisual(record).position, labelScreenScratch); if (!screen) continue; - const key = `${Math.floor(screen.x / LABEL_GRID_PX)}:${Math.floor(screen.y / LABEL_GRID_PX)}`; - const candidate = { - record, - score: labelPriority(record, selected), - x: screen.x, - y: screen.y, - }; + const column = Math.floor(screen.x / LABEL_GRID_PX); + const row = Math.floor(screen.y / LABEL_GRID_PX); + const key = + Math.abs(row) < LABEL_CELL_ROW / 2 && Math.abs(column) < LABEL_CELL_ROW + ? column * LABEL_CELL_ROW + row + : `${column}:${row}`; + const score = labelPriority(record, selected); const existing = cells.get(key); - if (!existing || candidate.score > existing.score) { - cells.set(key, candidate); + if (!existing) { + cells.set(key, { record, score, x: screen.x, y: screen.y }); + } else if (score > existing.score) { + existing.record = record; + existing.score = score; + existing.x = screen.x; + existing.y = screen.y; } } @@ -1148,7 +1160,30 @@ export function createRendering({ return score; } + // Whether a vessel's name is worth a card, kept per vessel until what it + // is judged from changes: the label pass asks for every vessel in view. + const usefulNames = new WeakMap(); + function hasUsefulName(record) { + const known = usefulNames.get(record); + if ( + known && + known.name === record.name && + known.mmsi === record.mmsi && + known.id === record.id + ) + return known.useful; + const useful = nameIsUseful(record); + usefulNames.set(record, { + name: record.name, + mmsi: record.mmsi, + id: record.id, + useful, + }); + return useful; + } + + function nameIsUseful(record) { const text = String(record.name || '').trim(); return Boolean( text && From 121b69561a3edf50f7a5223e922acf917ce88c44 Mon Sep 17 00:00:00 2001 From: Sameh Khamis Date: Sun, 15 Nov 2026 16:13:28 -0800 Subject: [PATCH 2/3] timeline: read each entry's time once when merging runs mergeTimelineRuns read an entry's time again on every comparison, and the vessel layer passed a new arrow for every vessel. Times are now read once into arrays, the leading older entries the loop would keep one by one are sliced in one step, and the layer passes one function. The result is the same entries in the same order; a test checks 3,000 random merges against the previous algorithm. Measured in the browser, one implementation per page, 9,000 vessels with 240 kept fixes each, 5 alternating pairs: 65-87 ms -> 57-61 ms per snapshot. --- src/layers/vessels/records.js | 5 +- src/time/timelineFixes.js | 47 ++++++++++++----- src/time/timelineFixes.test.mjs | 93 +++++++++++++++++++++++++++++++++ 3 files changed, 132 insertions(+), 13 deletions(-) diff --git a/src/layers/vessels/records.js b/src/layers/vessels/records.js index c0ad357e8..e18d380db 100644 --- a/src/layers/vessels/records.js +++ b/src/layers/vessels/records.js @@ -58,6 +58,9 @@ function stampFix(record, receivedAtMs, feedLatestEpoch) { record.fixFeedEpoch = feedLatestEpoch; } +/** A fix's time, as the fixes are merged (one function for every vessel). */ +const fixTime = (fix) => fix.atMs; + function positiveNumber(value) { const number = finiteNumber(value); return number !== null && number > 0 ? number : null; @@ -164,7 +167,7 @@ export class VesselRecords { ? mergeTimelineRuns( record.fixes ?? [], next.fixes, - (fix) => fix.atMs, + fixTime, (next.lastPositionEpoch ?? 0) * 1000, ) : null; diff --git a/src/time/timelineFixes.js b/src/time/timelineFixes.js index e8b078cc3..5ba1c24e3 100644 --- a/src/time/timelineFixes.js +++ b/src/time/timelineFixes.js @@ -82,43 +82,66 @@ export function mergeTimelineRuns( centreMs, limit = TIMELINE_FIXES_LIMIT, ) { - const first = newer.length ? timeOf(newer[0]) : Infinity; - const last = newer.length ? timeOf(newer[newer.length - 1]) : -Infinity; + // Each entry's time is read once: a layer merges a run for every contact + // in a snapshot, each holding up to `limit` entries. + const olderTimes = new Array(older.length); + for (let k = 0; k < older.length; k++) olderTimes[k] = timeOf(older[k]); + const newerTimes = new Array(newer.length); + for (let k = 0; k < newer.length; k++) newerTimes[k] = timeOf(newer[k]); + const first = newer.length ? newerTimes[0] : Infinity; + const last = newer.length ? newerTimes[newer.length - 1] : -Infinity; const newest = newer[newer.length - 1]; + // The older entries before the newer run that the loop below would keep + // one by one, each far enough from the one before, are taken at once: a + // contact's kept entries mostly stand before each snapshot's run. + let lead = 0; + while ( + lead < older.length && + !(olderTimes[lead] >= first && olderTimes[lead] <= last) && + (newer.length === 0 || olderTimes[lead] < first) && + (lead === 0 || + olderTimes[lead] - olderTimes[lead - 1] >= TIMELINE_FIX_SPACING_MS) + ) + lead++; // Both runs in order, the older entries within the newer run's time left // out, thinned to the spacing. - const merged = []; - const take = (entry) => { + const merged = older.slice(0, lead); + const times = olderTimes.slice(0, lead); + const take = (entry, t) => { const k = merged.length - 1; - if (k < 0 || timeOf(entry) - timeOf(merged[k]) >= TIMELINE_FIX_SPACING_MS) { + if (k < 0 || t - times[k] >= TIMELINE_FIX_SPACING_MS) { merged.push(entry); + times.push(t); } else if (entry === newest) { merged[k] = entry; + times[k] = t; } }; - let i = 0; + let i = lead; let j = 0; while (i < older.length || j < newer.length) { if (i < older.length) { - const t = timeOf(older[i]); + const t = olderTimes[i]; if (t >= first && t <= last) { i++; continue; } - if (j >= newer.length || t < timeOf(newer[j])) { - take(older[i++]); + if (j >= newer.length || t < newerTimes[j]) { + take(older[i], t); + i++; continue; } } - take(newer[j++]); + take(newer[j], newerTimes[j]); + j++; } if (merged.length <= limit) return merged; // The window of `limit` entries nearest the centre. let start = 0; while ( start + limit < merged.length && - Math.abs(timeOf(merged[start + limit]) - centreMs) < - Math.abs(timeOf(merged[start]) - centreMs) + Math.abs(times[start + limit] - centreMs) < + Math.abs(times[start] - centreMs) ) start++; return merged.slice(start, start + limit); diff --git a/src/time/timelineFixes.test.mjs b/src/time/timelineFixes.test.mjs index 9ab47c184..346388872 100644 --- a/src/time/timelineFixes.test.mjs +++ b/src/time/timelineFixes.test.mjs @@ -96,3 +96,96 @@ test('past the limit only the fixes nearest the centre are kept', () => { [0, 1, 2, 3], ); }); + +/** The merge as first written, a reference the faster one must match. */ +function referenceMerge(older, newer, timeOf, centreMs, limit = 240) { + const SPACING = 20_000; + const first = newer.length ? timeOf(newer[0]) : Infinity; + const last = newer.length ? timeOf(newer[newer.length - 1]) : -Infinity; + const newest = newer[newer.length - 1]; + const merged = []; + const take = (entry) => { + const k = merged.length - 1; + if (k < 0 || timeOf(entry) - timeOf(merged[k]) >= SPACING) + merged.push(entry); + else if (entry === newest) merged[k] = entry; + }; + let i = 0; + let j = 0; + while (i < older.length || j < newer.length) { + if (i < older.length) { + const t = timeOf(older[i]); + if (t >= first && t <= last) { + i++; + continue; + } + if (j >= newer.length || t < timeOf(newer[j])) { + take(older[i++]); + continue; + } + } + take(newer[j++]); + } + if (merged.length <= limit) return merged; + let start = 0; + while ( + start + limit < merged.length && + Math.abs(timeOf(merged[start + limit]) - centreMs) < + Math.abs(timeOf(merged[start]) - centreMs) + ) + start++; + return merged.slice(start, start + limit); +} + +test('the merge keeps exactly what it always kept, for runs of every shape', () => { + let seed = 3; + const rnd = () => (seed = (seed * 16807) % 2147483647) / 2147483647; + const run = (n, from, stepMs, sorted) => { + const out = Array.from({ length: n }, (_, k) => ({ + atMs: + rnd() < 0.05 + ? Number.NaN + : from + + Math.round((sorted ? k : rnd() * n) * stepMs * (0.5 + rnd())), + })); + if (sorted) out.sort((a, b) => a.atMs - b.atMs); + return out; + }; + for (let round = 0; round < 3000; round++) { + const sorted = round % 5 !== 0; + const older = run( + Math.floor(rnd() * 300), + Math.floor(rnd() * 4e6), + 15_000 + rnd() * 50_000, + sorted, + ); + const newer = run( + Math.floor(rnd() * 30), + Math.floor(rnd() * 6e6), + 5_000 + rnd() * 70_000, + sorted, + ); + // The newest of the newer run is sometimes an entry of the older one. + if (newer.length && older.length && rnd() < 0.1) + newer[newer.length - 1] = older[older.length - 1]; + const centreMs = rnd() * 7e6; + const limit = rnd() < 0.5 ? 240 : 1 + Math.floor(rnd() * 40); + const expected = referenceMerge( + older, + newer, + (f) => f.atMs, + centreMs, + limit, + ); + const actual = mergeTimelineRuns( + older, + newer, + (f) => f.atMs, + centreMs, + limit, + ); + assert.equal(actual.length, expected.length, `round ${round}`); + for (let k = 0; k < expected.length; k++) + assert.equal(actual[k], expected[k], `round ${round} entry ${k}`); + } +}); From 3909c7735a41038afff49ff7c47ebc48d403b802 Mon Sep 17 00:00:00 2001 From: Sameh Khamis Date: Sun, 15 Nov 2026 16:13:56 -0800 Subject: [PATCH 3/3] changelog: vessel labels and fix merge --- changelog.d/1757-vessel-labels-merge.md | 3 +++ 1 file changed, 3 insertions(+) create mode 100644 changelog.d/1757-vessel-labels-merge.md diff --git a/changelog.d/1757-vessel-labels-merge.md b/changelog.d/1757-vessel-labels-merge.md new file mode 100644 index 000000000..4aff2b35e --- /dev/null +++ b/changelog.d/1757-vessel-labels-merge.md @@ -0,0 +1,3 @@ +### Changed + +- Playing the world clock with thousands of vessels in view spends less time choosing which vessels get name cards (about a third of the time before) and merging each vessel's kept positions at every snapshot.