diff --git a/changelog.d/1755-vessel-playback-frames.md b/changelog.d/1755-vessel-playback-frames.md new file mode 100644 index 000000000..cf9404b96 --- /dev/null +++ b/changelog.d/1755-vessel-playback-frames.md @@ -0,0 +1,4 @@ +### Changed + +- Playing the world clock away from live now draws at the display's own refresh rate instead of at most 60 FPS. +- Vessels following a playing clock are moved again once the fastest would have moved half a pixel on screen, at least once a second, and at once when the camera moves or zooms. Before, every drawn vessel moved every frame by a fraction of a pixel, which took most of each frame with thousands of vessels in view. diff --git a/docs/CURRENT-STATE.md b/docs/CURRENT-STATE.md index 7d6fc3698..7b9698fce 100644 --- a/docs/CURRENT-STATE.md +++ b/docs/CURRENT-STATE.md @@ -18,7 +18,9 @@ data sources and update listeners on every animation frame even when it skips the draw; the viewer starts at that cap until the governor is installed. The camera holds continuous render from `moveStart` to `moveEnd`, and samples its pose every 250 ms in between, so a camera drifting by rounding errors (no -`moveEnd`) is released after half a second at rest and held again if it moves. Waits that used to count frames (a followed contact's first +`moveEnd`) is released after half a second at rest and held again if it moves. The world clock holds continuous render while +it plays away from the live edge (not while it steps or waits for data), so +playback draws at the display's rate too. Waits that used to count frames (a followed contact's first position, a shared follow view, a trail's temporary copy) count drawn time through `src/time/frameWait.js`, at most 100 ms a frame, so they last the same at any refresh rate and a background tab does not use them up. @@ -2029,8 +2031,12 @@ Playing, the layer stays a snapshot ahead of the time, and play does not pass a snapshot still loading for more than 8 seconds. Those snapshots apply as polls do, so contacts move on smoothly: aircraft are drawn at the clock's time rather than behind it, and vessels between two fixes move along the great -circle, never past the newer one, redrawn every frame with frames asked for -as for placed live vessels (vessels out of view move on every 250 ms). Records, absences and the Layers panel's age +circle, never past the newer one. Drawn vessels move again once the fastest +of them would have moved half a pixel on screen at the speed it last moved, +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, with frames asked for as for +placed live vessels; vessels out of view move on a share of them each frame, +each within 250 ms, and one that comes into view is moved to the time first. Records, absences and the Layers panel's age are judged at the clock's time. Outside the coverage the layer shows no contacts and loads nothing; while the coverage is unknown it loads nothing and clears nothing. A snapshot that fails clears the time and is asked again after diff --git a/src/app/scene.js b/src/app/scene.js index a1afb0b60..0224d9a26 100644 --- a/src/app/scene.js +++ b/src/app/scene.js @@ -13,6 +13,8 @@ import { initLogoGaze } from '../logoGaze.js'; import { uninstallRenderGovernor, governorRequestRender, + holdContinuousRender, + releaseContinuousRender, } from '../renderGovernor.js'; import { describeError } from './errors.js'; import { isEmbeddedInline } from './embed.js'; @@ -73,6 +75,12 @@ export async function createApplicationScene({ followWorldTime(viewer, worldTimeFor('sky'), { subscribe: worldClock.subscribe, requestRender: () => governorRequestRender('world-time'), + // A playing world time moves something every frame: draw at the + // display's rate meanwhile, not the parked scene's cap. + onPlaying: (playing) => + playing + ? holdContinuousRender('world-time') + : releaseContinuousRender('world-time'), }), ); defer(installFreeLookHeightLimit(viewer)); diff --git a/src/layers/vessels/motion.js b/src/layers/vessels/motion.js index 83e463ffc..60c8038b1 100644 --- a/src/layers/vessels/motion.js +++ b/src/layers/vessels/motion.js @@ -55,37 +55,36 @@ export function vesselPositionAt(record, tMs) { const RAD = Math.PI / 180; -/** The point `fraction` of the way from one position to another. */ +/** The point `fraction` of the way from one position to another. It runs + * for every drawn vessel as the clock plays, so it builds no arrays. */ function greatCircleAt(lat1, lon1, lat2, lon2, fraction) { - const p1 = unit(lat1, lon1); - const p2 = unit(lat2, lon2); - const dot = Math.min( - 1, - Math.max(-1, p1[0] * p2[0] + p1[1] * p2[1] + p1[2] * p2[2]), - ); + const phi1 = lat1 * RAD; + const lambda1 = lon1 * RAD; + const phi2 = lat2 * RAD; + const lambda2 = lon2 * RAD; + const cos1 = Math.cos(phi1); + const cos2 = Math.cos(phi2); + const x1 = cos1 * Math.cos(lambda1); + const y1 = cos1 * Math.sin(lambda1); + const z1 = Math.sin(phi1); + const x2 = cos2 * Math.cos(lambda2); + const y2 = cos2 * Math.sin(lambda2); + const z2 = Math.sin(phi2); + const dot = Math.min(1, Math.max(-1, x1 * x2 + y1 * y2 + z1 * z2)); const angle = Math.acos(dot); if (angle < 1e-12) return { lat: lat2, lon: lon2 }; - const a = Math.sin((1 - fraction) * angle) / Math.sin(angle); - const b = Math.sin(fraction * angle) / Math.sin(angle); - const x = a * p1[0] + b * p2[0]; - const y = a * p1[1] + b * p2[1]; - const z = a * p1[2] + b * p2[2]; + const sinAngle = Math.sin(angle); + const a = Math.sin((1 - fraction) * angle) / sinAngle; + const b = Math.sin(fraction * angle) / sinAngle; + const x = a * x1 + b * x2; + const y = a * y1 + b * y2; + const z = a * z1 + b * z2; return { lat: Math.atan2(z, Math.hypot(x, y)) / RAD, lon: Math.atan2(y, x) / RAD, }; } -function unit(lat, lon) { - const phi = lat * RAD; - const lambda = lon * RAD; - return [ - Math.cos(phi) * Math.cos(lambda), - Math.cos(phi) * Math.sin(lambda), - Math.sin(phi), - ]; -} - // Whether each fixes array moves, read once per array: records keep theirs // until a snapshot brings new ones. const moving = new WeakMap(); diff --git a/src/layers/vessels/renderGovernor.test.mjs b/src/layers/vessels/renderGovernor.test.mjs index 90ee46993..909030956 100644 --- a/src/layers/vessels/renderGovernor.test.mjs +++ b/src/layers/vessels/renderGovernor.test.mjs @@ -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); +}); diff --git a/src/layers/vessels/rendering.js b/src/layers/vessels/rendering.js index e9d2ada62..cc49ce7b4 100644 --- a/src/layers/vessels/rendering.js +++ b/src/layers/vessels/rendering.js @@ -38,13 +38,26 @@ import { isAidToNavigation } from '../../data/vesselTypes.js'; const VESSEL_STEP_PX = 0.5; /** A frame is asked for at least this often while any drawn vessel moves. */ const PLACEMENT_FRAME_MS = 1000; -/** How often vessels not drawn move on as the world clock plays (wall ms), - * so one that comes into view is judged where it is. */ +/** How often each vessel not drawn moves on as the world clock plays (wall + * ms), so one that comes into view is judged where it is. */ const HIDDEN_FOLLOW_MS = 250; /** How often the vessels near enough for a model are gathered again (wall ms). */ const MODEL_CANDIDATES_MS = 500; +/** How far the camera may move or change height, as a share of its height, + * before vessels following the world clock move again however little they + * moved. */ +const CAMERA_STEP = 0.1; +/** The least height that share is taken of (metres), so a camera just above + * the sea, or below the ellipsoid, still lets vessels rest between steps. */ +const CAMERA_STEP_FLOOR_M = 100; + +const DEG_TO_RAD = Math.PI / 180; + +/** Scratch for the camera's position. */ +const _cameraCartographic = new Cesium.Cartographic(); + /** Scratch for where a moved vessel was drawn. */ const _movedFrom = new Cesium.Cartesian3(); @@ -75,60 +88,54 @@ export function createRendering({ ? vesselPositionAt(record, vesselState.worldNow()) : (services.placement?.place(record.id, vesselState._aisRuntime.now()) ?? record); - const heightM = components.queries.vesselDatumHeightM( - components.tracking.currentGeoidN(lat, lon), - VESSEL_LIFT_M, - ); - visual.position = Cesium.Cartesian3.fromDegrees(lon, lat, heightM); - // A ship model's origin is its waterline: the sea surface, unlifted. - visual.waterline = Cesium.Cartesian3.fromDegrees( - lon, - lat, - heightM - VESSEL_LIFT_M, - ); - visual.surfacePosition = Cesium.Cartesian3.fromDegrees(lon, lat, 0); - visual.normal = Cesium.Ellipsoid.WGS84.geodeticSurfaceNormal( - visual.position, - new Cesium.Cartesian3(), - ); - visual.drawnLat = lat; - visual.drawnLon = lon; + visual.position = new Cesium.Cartesian3(); + visual.waterline = new Cesium.Cartesian3(); + visual.surfacePosition = new Cesium.Cartesian3(); + writeVesselPositions(visual, lat, lon); + // The world time it is drawn at, while it follows the clock. + visual.drawnAtMs = followsClock(vesselState) + ? vesselState.worldNow() + : Number.NaN; return visual; } /** - * Move a prepared vessel visual to `lat`/`lon`, writing into its own - * positions rather than allocating new ones: the placement pass runs for - * every drawn vessel several times a second. + * Write where a vessel visual is drawn at `lat`/`lon` into its own + * positions: lifted VESSEL_LIFT_M above the sea surface, its waterline on + * it, and the surface point under it. The placement pass runs for every + * drawn vessel as it moves, so the surface point and its normal are worked + * out once (as Cesium.Cartesian3.fromDegrees does) and the other two are + * along the normal from it. */ - function moveRecordVisual(visual, lat, lon) { + function writeVesselPositions(visual, lat, lon) { const heightM = components.queries.vesselDatumHeightM( components.tracking.currentGeoidN(lat, lon), VESSEL_LIFT_M, ); - const ellipsoid = Cesium.Ellipsoid.WGS84; - Cesium.Cartesian3.fromDegrees( - lon, - lat, - heightM, - ellipsoid, - visual.position, - ); - Cesium.Cartesian3.fromDegrees( - lon, - lat, - heightM - VESSEL_LIFT_M, - ellipsoid, - visual.waterline, - ); - Cesium.Cartesian3.fromDegrees( - lon, - lat, - 0, - ellipsoid, - visual.surfacePosition, - ); - ellipsoid.geodeticSurfaceNormal(visual.position, visual.normal); + const phi = lat * DEG_TO_RAD; + const lambda = lon * DEG_TO_RAD; + const cosPhi = Math.cos(phi); + const nx = cosPhi * Math.cos(lambda); + const ny = cosPhi * Math.sin(lambda); + const nz = Math.sin(phi); + const radiiSquared = Cesium.Ellipsoid.WGS84.radiiSquared; + const kx = radiiSquared.x * nx; + const ky = radiiSquared.y * ny; + const kz = radiiSquared.z * nz; + const gamma = Math.sqrt(nx * kx + ny * ky + nz * kz); + const surface = visual.surfacePosition; + surface.x = kx / gamma; + surface.y = ky / gamma; + surface.z = kz / gamma; + const position = visual.position; + position.x = surface.x + nx * heightM; + position.y = surface.y + ny * heightM; + position.z = surface.z + nz * heightM; + const waterlineM = heightM - VESSEL_LIFT_M; + const waterline = visual.waterline; + waterline.x = surface.x + nx * waterlineM; + waterline.y = surface.y + ny * waterlineM; + waterline.z = surface.z + nz * waterlineM; visual.drawnLat = lat; visual.drawnLon = lon; } @@ -433,12 +440,14 @@ export function createRendering({ // The layer does not hold the continuous render loop. Its passes run in // preRender, which idle mode fires only for rendered frames: moving vessels - // ask for the frame that next moves them visibly (askMotionFrame), a forced - // pass (new data, selection) requests its frame, a frame that moved the - // camera but fell inside the 800 ms cadence leaves a trailing frame so the view the camera stopped on is always - // evaluated, and the continuous hold is kept only while focus emphasis is - // animating. The trailing frame is keyed to camera motion alone: the pass's - // own label publication requests a frame, and scheduling on that would loop. + // ask for the frame that next moves them visibly (askMotionFrame; while the + // world clock plays, the scene draws every frame anyway), a forced pass + // (new data, selection) requests its frame, a frame that moved the camera + // but fell inside the 800 ms cadence leaves a trailing frame so the view + // the camera stopped on is always evaluated, and the continuous hold is + // kept only while focus emphasis is animating. The trailing frame is keyed + // to camera motion alone: the pass's own label publication requests a + // frame, and scheduling on that would loop. function installRuntime(viewer) { if (state.preRenderRemover || !viewer) return; state.preRenderRemover = viewer.scene.preRender.addEventListener(() => { @@ -451,34 +460,183 @@ export function createRendering({ }); } - // As the world clock plays, vessels between two fixes move on along them: - // drawn ones every frame, each once per world time, hidden ones (which may - // come into view) every HIDDEN_FOLLOW_MS. - let hiddenFollowedAtWallMs = -Infinity; + // As the world clock plays, vessels between two fixes move on along them. + // Drawn ones move each world time once the fastest would have moved + // VESSEL_STEP_PX on screen, at least once a second, and at once when the + // camera moves or zooms (underClockStep). Hidden ones (which may come into + // view) move a share of them each pass, so each moves at least every + // HIDDEN_FOLLOW_MS without one frame moving them all. The scene renders as + // fast as the display while the clock plays, and moving thousands of + // vessels a fraction of a pixel each frame would take most of every frame. + let hiddenFollowedAtWallMs = null; + let hiddenCursor = 0; + let clockPassAtMs = null; + // Whether the last pass left drawn vessels short of its world time. + let drawnBehind = false; function followClockPositions() { const atMs = vesselState.worldNow(); - const motion = startMotionPass(); - const moveHidden = - motion.wallMs - hiddenFollowedAtWallMs >= HIDDEN_FOLLOW_MS; - if (moveHidden) hiddenFollowedAtWallMs = motion.wallMs; - for (const record of state.records.all) { - if (!record.motion && !fixesMove(record.fixes)) continue; - let visual = visualRecords.get(record); - if (!visual?.position) { - visual = prepareRecordVisual(record); - visual.followedAtMs = atMs; - } else { - const drawn = visual.billboard?.show || visual.modelOwnsVisual; - if (visual.followedAtMs === atMs || (!drawn && !moveHidden)) continue; - visual.followedAtMs = atMs; - const { lat, lon } = vesselPositionAt(record, atMs); - // At either end of its fixes a vessel holds still. - if (lat === visual.drawnLat && lon === visual.drawnLon) continue; - moveDrawnVisual(visual, lat, lon, motion); - } - if (visual.billboard) visual.billboard.position = visual.position; + const wallMs = performance.now(); + const all = state.records.all; + // Each vessel moves once per world time; drawn ones a pass left short + // move to it on the next, so a paused clock shows them where they are. + const sameTime = atMs === clockPassAtMs; + const moveDrawn = sameTime ? drawnBehind : !underClockStep(atMs, wallMs); + clockPassAtMs = atMs; + if (moveDrawn) drawnBehind = false; + else if (!sameTime) { + drawnBehind = true; + askFrameIn(PLACEMENT_FRAME_MS); } + const motion = moveDrawn ? startMotionPass() : null; + if (moveDrawn) + for (const record of all) followRecord(record, atMs, true, motion); + // As much of the list as the wall time since the last pass is of + // HIDDEN_FOLLOW_MS, going round it. + const sinceMs = + hiddenFollowedAtWallMs === null + ? HIDDEN_FOLLOW_MS + : wallMs - hiddenFollowedAtWallMs; + const share = Math.min( + all.length, + Math.ceil((all.length * Math.max(0, sinceMs)) / HIDDEN_FOLLOW_MS), + ); + if (share > 0) hiddenFollowedAtWallMs = wallMs; + for (let k = 0; k < share; k += 1) { + if (hiddenCursor >= all.length) hiddenCursor = 0; + followRecord(all[hiddenCursor], atMs, false, motionPass); + hiddenCursor += 1; + } + if (!moveDrawn) return; askMotionFrame(motion); + noteClockStep(atMs, motion); + } + + /** + * Draw a vessel where it is at world time `atMs` if the clock passes have + * not yet; true when it moved. + */ + function catchUpVisual(record, atMs) { + const visual = visualRecords.get(record); + if (!visual?.position || visual.followedAtMs === atMs) return false; + if (!record.motion && !fixesMove(record.fixes)) return false; + visual.followedAtMs = atMs; + visual.drawnAtMs = atMs; + const { lat, lon } = vesselPositionAt(record, atMs); + if (lat === visual.drawnLat && lon === visual.drawnLon) return false; + writeVesselPositions(visual, lat, lon); + if (visual.billboard) visual.billboard.position = visual.position; + return true; + } + + /** + * Move a vessel to where it is at world time `atMs`, if it is drawn + * (`drawn`) or hidden (not `drawn`) as asked; one with no visual yet is + * prepared either way. A hidden vessel's move notes nothing in `motion`. + */ + function followRecord(record, atMs, drawn, motion) { + if (!record.motion && !fixesMove(record.fixes)) return; + let visual = visualRecords.get(record); + if (!visual?.position) { + visual = prepareRecordVisual(record); + visual.followedAtMs = atMs; + } else { + const shown = Boolean(visual.billboard?.show || visual.modelOwnsVisual); + if (shown !== drawn || visual.followedAtMs === atMs) return; + visual.followedAtMs = atMs; + const { lat, lon } = vesselPositionAt(record, atMs); + const elapsedMs = Math.abs(atMs - visual.drawnAtMs); + visual.drawnAtMs = atMs; + // At either end of its fixes a vessel holds still. + if (lat === visual.drawnLat && lon === visual.drawnLon) return; + moveDrawnVisual(visual, lat, lon, motion, elapsedMs); + } + if (visual.billboard) visual.billboard.position = visual.position; + } + + // The clock pass that last moved drawn vessels: its world time and wall + // time, how fast the fastest drawn vessel moved on screen (pixels per world + // ms), and the camera then: where it was, its height and its view's size. + const clockStep = { + atMs: null, + wallMs: 0, + pxPerMs: Infinity, + heightM: 0, + eye: new Cesium.Cartesian3(), + fovy: Number.NaN, + width: Number.NaN, + }; + + /** Measure, after a pass that moved drawn vessels, how fast the fastest + * moved on screen: each over the world time since it was last drawn. */ + function noteClockStep(atMs, motion) { + const camera = motion.camera; + if (!motion.moving || motion.unmeasured || !camera?.positionWC) { + clockStep.atMs = null; + return; + } + const pxPerMs = movedPixels({ + camera, + angle: motion.angleRate, + metres: motion.metresRate, + }); + clockStep.pxPerMs = pxPerMs > 0 ? pxPerMs : Infinity; + clockStep.atMs = atMs; + clockStep.wallMs = motion.wallMs; + clockStep.heightM = cameraHeightM(); + Cesium.Cartesian3.clone(camera.positionWC, clockStep.eye); + clockStep.fovy = camera.frustum?.fovy; + clockStep.width = viewWidth(camera.frustum); + } + + /** Forget how fast vessels moved, so the next clock pass moves the drawn + * ones however little they moved (they were drawn somewhere else). */ + function forgetClockStep() { + clockStep.atMs = null; + clockPassAtMs = null; + } + + const viewWidth = (frustum) => + frustum ? frustum.right - frustum.left : Number.NaN; + const sameNumber = (a, b) => a === b || (Number.isNaN(a) && Number.isNaN(b)); + + /** + * Whether the fastest drawn vessel would have moved less than + * VESSEL_STEP_PX on screen since the clock pass that last moved them, at + * the speed it moved then: drawn vessels are left where they are. They + * move anyway once PLACEMENT_FRAME_MS has gone by, or once the camera has + * moved or changed height by more than CAMERA_STEP of its height, or its + * view has changed size (a pixel then covers another distance). + */ + function underClockStep(atMs, wallMs) { + if (clockStep.atMs === null || !(clockStep.pxPerMs < Infinity)) + return false; + if (wallMs - clockStep.wallMs >= PLACEMENT_FRAME_MS) return false; + const camera = state.viewer?.camera; + if (!camera?.positionWC) return false; + const limitM = + CAMERA_STEP * Math.max(clockStep.heightM, CAMERA_STEP_FLOOR_M); + if (!(Math.abs(cameraHeightM() - clockStep.heightM) <= limitM)) + return false; + if ( + !(Cesium.Cartesian3.distance(camera.positionWC, clockStep.eye) <= limitM) + ) + return false; + if ( + !sameNumber(camera.frustum?.fovy, clockStep.fovy) || + !sameNumber(viewWidth(camera.frustum), clockStep.width) + ) + return false; + return Math.abs(atMs - clockStep.atMs) * clockStep.pxPerMs < VESSEL_STEP_PX; + } + + /** The camera's height above the ellipsoid (metres), NaN without one. */ + function cameraHeightM() { + const eye = state.viewer?.camera?.positionWC; + if (!eye) return Number.NaN; + return ( + Cesium.Ellipsoid.WGS84.cartesianToCartographic(eye, _cameraCartographic) + ?.height ?? Number.NaN + ); } // Live with a host-supplied placement, vessels move on between refreshes: @@ -515,6 +673,9 @@ export function createRendering({ moving: false, angle: 0, metres: 0, + angleRate: 0, + metresRate: 0, + unmeasured: false, }; function startMotionPass() { const wallMs = performance.now(); @@ -525,22 +686,37 @@ export function createRendering({ motionPass.moving = false; motionPass.angle = 0; motionPass.metres = 0; + motionPass.angleRate = 0; + motionPass.metresRate = 0; + motionPass.unmeasured = false; motionPassWallMs = wallMs; return motionPass; } - /** Move a drawn visual, noting how far it moved as seen from the camera. */ - function moveDrawnVisual(visual, lat, lon, motion) { + /** Move a drawn visual, noting how far it moved as seen from the camera, + * and, given the world time since it was last drawn (`elapsedMs`), how + * fast. */ + function moveDrawnVisual(visual, lat, lon, motion, elapsedMs) { const from = Cesium.Cartesian3.clone(visual.position, _movedFrom); - moveRecordVisual(visual, lat, lon); + writeVesselPositions(visual, lat, lon); if (!visual.billboard?.show && !visual.modelOwnsVisual) return; motion.moving = true; const metres = Cesium.Cartesian3.distance(from, visual.position); motion.metres = Math.max(motion.metres, metres); + const timed = elapsedMs > 0; + if (elapsedMs !== undefined && !timed) motion.unmeasured = true; + if (timed) + motion.metresRate = Math.max(motion.metresRate, metres / elapsedMs); const eye = motion.camera?.positionWC; if (!eye) return; const distance = Cesium.Cartesian3.distance(eye, from); - if (distance > 0) motion.angle = Math.max(motion.angle, metres / distance); + if (!(distance > 0)) return; + motion.angle = Math.max(motion.angle, metres / distance); + if (timed) + motion.angleRate = Math.max( + motion.angleRate, + metres / distance / elapsedMs, + ); } /** How far the fastest drawn vessel moved on screen in a pass (pixels): @@ -574,7 +750,12 @@ export function createRendering({ const movedPx = movedPixels(motion); if (movedPx > 0 && motion.sinceMs > 0) waitMs = Math.min(waitMs, (VESSEL_STEP_PX * motion.sinceMs) / movedPx); - // A frame already asked for no later than this one stands. + askFrameIn(waitMs); + } + + /** Ask for a vessel frame `waitMs` from now; one already asked for no + * later stands. */ + function askFrameIn(waitMs) { const runtime = vesselState._aisRuntime; const dueMs = runtime.now() + waitMs; if (placementFrameTimer !== null) { @@ -591,6 +772,9 @@ export function createRendering({ /** Stop asking for placement frames (the layer turned off or went away). */ function cancelPlacementFrame() { motionPassWallMs = null; + forgetClockStep(); + drawnBehind = false; + hiddenFollowedAtWallMs = null; if (placementFrameTimer === null) return; vesselState._aisRuntime.clearTimeout(placementFrameTimer); placementFrameTimer = null; @@ -670,9 +854,21 @@ export function createRendering({ if (doRotations) vesselState._lastCamPoseSig = poseSig; const occluder = makeOccluder(); const labelCandidates = []; + // The time the clock pass drew (a playing clock's time moves on within + // the frame), so only vessels it did not reach are moved. + const catchUpAtMs = worldMs === null ? null : (clockPassAtMs ?? worldMs); for (const record of state.records.all) { const visual = getVisual(record); - const visible = isVisible(visual.surfacePosition, occluder, record); + let visible = isVisible(visual.surfacePosition, occluder, record); + // One in view that the clock passes have not moved to the time yet + // (a seek while paused shows it before its turn) is moved there and + // judged again: no later pass would move it while the clock rests. + if ( + visible && + catchUpAtMs !== null && + catchUpVisual(record, catchUpAtMs) + ) + visible = isVisible(visual.surfacePosition, occluder, record); if (visual.billboard) { // The bridge camera sits on this sprite; showing it would fill the view. // The same rule as billboardShown, its horizon test already made. @@ -978,6 +1174,7 @@ export function createRendering({ } return { getVisual, + forgetClockStep, prepareRecordVisual, resetRecordVisuals, renderRowLimit, diff --git a/src/layers/vessels/tracking.js b/src/layers/vessels/tracking.js index 4f2c127bf..f0d0b737a 100644 --- a/src/layers/vessels/tracking.js +++ b/src/layers/vessels/tracking.js @@ -77,7 +77,9 @@ export function createTracking({ visual.drawnLat = NaN; visual.drawnLon = NaN; visual.followedAtMs = undefined; + visual.drawnAtMs = Number.NaN; } + components.rendering.forgetClockStep(); } /** diff --git a/src/time/viewerClock.js b/src/time/viewerClock.js index e4c456d42..53df66697 100644 --- a/src/time/viewerClock.js +++ b/src/time/viewerClock.js @@ -11,16 +11,29 @@ import * as Cesium from 'cesium'; * The clock's `currentTime` follows too, for anything that samples it. * @param {Cesium.Viewer} viewer * @param {() => number} readTime Epoch ms the sky is drawn at. - * @param {{subscribe?: Function, requestRender?: () => void}} [options] + * @param {{subscribe?: Function, requestRender?: () => void, + * onPlaying?: (playing: boolean) => void}} [options] * A world clock to hear moves from, so a resting scene repaints when the - * world time jumps. + * world time jumps. `onPlaying` hears when the world clock starts and stops + * playing away from live (not stepped by a driver and not waiting for a + * layer's data), so the scene can draw every frame meanwhile. * @returns {() => void} Stop following. */ export function followWorldTime( viewer, readTime, - { subscribe, requestRender = () => viewer.scene.requestRender() } = {}, + { + subscribe, + requestRender = () => viewer.scene.requestRender(), + onPlaying = () => {}, + } = {}, ) { + let playing = false; + const setPlaying = (next) => { + if (next === playing) return; + playing = next; + onPlaying(next); + }; const date = new Date(); const removePreUpdate = viewer.scene.preUpdate.addEventListener( (_scene, time) => { @@ -33,7 +46,12 @@ export function followWorldTime( ); let last = readTime(); const unsubscribe = - subscribe?.(() => { + subscribe?.((state) => { + setPlaying( + Boolean( + state?.playing && !state.live && !state.stepping && !state.buffering, + ), + ); const next = readTime(); if (next === last) return; last = next; @@ -42,5 +60,6 @@ export function followWorldTime( return () => { removePreUpdate(); unsubscribe(); + setPlaying(false); }; } diff --git a/src/time/viewerClock.test.mjs b/src/time/viewerClock.test.mjs new file mode 100644 index 000000000..f36f098ae --- /dev/null +++ b/src/time/viewerClock.test.mjs @@ -0,0 +1,59 @@ +import test from 'node:test'; +import assert from 'node:assert/strict'; +import { followWorldTime } from './viewerClock.js'; + +function fakeViewer() { + const listeners = new Set(); + return { + clock: { currentTime: {} }, + scene: { + requestRender() {}, + preUpdate: { + addEventListener(fn) { + listeners.add(fn); + return () => listeners.delete(fn); + }, + }, + }, + }; +} + +test('the scene hears when the world time plays on its own, and when it stops', () => { + let listener = null; + const subscribe = (fn) => { + listener = fn; + return () => (listener = null); + }; + const heard = []; + let at = 0; + const stop = followWorldTime(fakeViewer(), () => at, { + subscribe, + requestRender: () => {}, + onPlaying: (playing) => heard.push(playing), + }); + const state = (fields) => ({ + live: false, + playing: false, + stepping: false, + buffering: false, + ...fields, + }); + listener(state({ live: true, playing: true })); + assert.deepEqual(heard, [], 'live time is not playback'); + listener(state({ playing: true })); + listener(state({ playing: true })); + assert.deepEqual(heard, [true], 'heard once'); + listener(state({ playing: true, buffering: true })); + assert.deepEqual(heard, [true, false], 'waiting for a layer: still'); + listener(state({ playing: true })); + listener(state({ playing: true, stepping: true })); + assert.deepEqual(heard, [true, false, true, false], 'a driver steps it'); + listener(state({ playing: true })); + stop(); + assert.deepEqual( + heard, + [true, false, true, false, true, false], + 'stopping releases', + ); + assert.equal(listener, null); +});