From 26893ae37ec2cdc51b3d4f12261b6a5a5f882976 Mon Sep 17 00:00:00 2001 From: Sameh Khamis Date: Mon, 16 Nov 2026 13:22:22 -0800 Subject: [PATCH] Vessel tracks end at the vessel The selected vessel's track drew every fix it held. Following the world clock, it ran ahead of the icon to the vessel's newest fix; live, it stopped at the last fix while the icon moved on from it. A change of time restarted it from a single point until the track at the new time arrived, so it went blank at every step. - The track draws the fixes at or before the time the vessel is drawn at; live, every fix. - Each frame a head joins its last drawn fix to the icon where it is drawn, as flight tracks do; none past TRAIL_HEAD_MAX_M (20 km), where the clock has moved beyond the fixes the track holds. - A change of time keeps the track, drawn up to the new time, until the track at that time replaces it. --- src/layers/vessels/lifecycle.js | 4 + src/layers/vessels/policy.js | 6 ++ src/layers/vessels/snapshotRenderer.js | 4 +- src/layers/vessels/state.js | 7 ++ src/layers/vessels/testing.js | 1 + src/layers/vessels/tracking.js | 139 ++++++++++++++++++++++--- src/layers/vessels/tracking.test.mjs | 137 +++++++++++++++++++++++- 7 files changed, 280 insertions(+), 18 deletions(-) diff --git a/src/layers/vessels/lifecycle.js b/src/layers/vessels/lifecycle.js index eb1c7eb76..c9c7d3e34 100644 --- a/src/layers/vessels/lifecycle.js +++ b/src/layers/vessels/lifecycle.js @@ -133,7 +133,11 @@ export function createLifecycle({ state.activeLabelCount = 0; state.selectedRecord = null; state.trail = null; + state.trailHeadOff?.(); + state.trailHeadOff = null; state.trailPositions = []; + state.trailTimes = []; + state.trailBodyCount = -1; state.trailId = null; state.trailBackfillToken = 0; } diff --git a/src/layers/vessels/policy.js b/src/layers/vessels/policy.js index 1981cdcdc..db231ca15 100644 --- a/src/layers/vessels/policy.js +++ b/src/layers/vessels/policy.js @@ -53,6 +53,12 @@ export const TRAIL_MAX_POINTS = 400; export const TRAIL_MIN_MOVE_M = 25; +/** Longest head (m) drawn from the trail's last drawn fix to the vessel: a + * farther vessel (the clock jumped past the fixes the trail holds) keeps no + * head until its fixes arrive. */ + +export const TRAIL_HEAD_MAX_M = 20000; + /** Whether the layer shows the world clock's time instead of the live feed: * its source declares a timeline and the clock is away from live. */ export const followsClock = (vesselState) => diff --git a/src/layers/vessels/snapshotRenderer.js b/src/layers/vessels/snapshotRenderer.js index ab10a9fe1..54e683a73 100644 --- a/src/layers/vessels/snapshotRenderer.js +++ b/src/layers/vessels/snapshotRenderer.js @@ -90,9 +90,9 @@ export function createVesselSnapshotRenderer({ }, }, ); - // The selected vessel at the new time: its trail starts there. + // The selected vessel at the new time: its trail is drawn to it. if (replace && state.selectedRecord && state.trailId) - tracking.startSelectedVesselTrail(state.selectedRecord); + tracking.retimeSelectedVesselTrail(state.selectedRecord); state.lastVisibilityUpdate = 0; rendering.updateVisibility(true); } diff --git a/src/layers/vessels/state.js b/src/layers/vessels/state.js index d67f984d8..35224a323 100644 --- a/src/layers/vessels/state.js +++ b/src/layers/vessels/state.js @@ -97,6 +97,13 @@ export function createVesselState({ source, services }) { trail: null, /** @type {{x: number, y: number, z: number}[]} Chronological ECEF trail vertices (oldest first) */ trailPositions: [], + /** @type {number[]} Epoch ms of each trail vertex (NaN: undated, drawn + * at any time), parallel to trailPositions. */ + trailTimes: [], + /** How many trail vertices the body draws now, or -1 before it draws. */ + trailBodyCount: -1, + /** @type {(() => void)|null} Stops drawing the trail's head each frame. */ + trailHeadOff: null, /** @type {string|null} Id of the vessel that owns the active selected-vessel trail. */ trailId: null, /** @type {number} Monotonic token — invalidates in-flight backfill responses */ diff --git a/src/layers/vessels/testing.js b/src/layers/vessels/testing.js index fcfff1dc0..f7d7e029d 100644 --- a/src/layers/vessels/testing.js +++ b/src/layers/vessels/testing.js @@ -62,6 +62,7 @@ export function createTesting({ state.trailPositions = Array.isArray(options.trailPositions) ? [...options.trailPositions] : []; + state.trailTimes = state.trailPositions.map(() => Number.NaN); state.feed.transportStatus = options.transportStatus || null; state.feed.lastMessageAt = options.lastMessageAt ?? null; state.feed.rawRowCount = Number.isFinite(options.rawRowCount) diff --git a/src/layers/vessels/tracking.js b/src/layers/vessels/tracking.js index 9bd5be846..10193a82d 100644 --- a/src/layers/vessels/tracking.js +++ b/src/layers/vessels/tracking.js @@ -1,13 +1,22 @@ import { fromDegrees } from '../../geo/ellipsoid.js'; import { distance } from '../../geo/vector.js'; +import { findFrame } from '../../render/rendererOf.js'; import { TRAIL_HEIGHT_M, TRAIL_COLOR, + TRAIL_HEAD_MAX_M, TRAIL_MAX_POINTS, TRAIL_MIN_MOVE_M, followsClock, } from './policy.js'; +/** A vessel record's own fix time, epoch ms (NaN when it gives none). */ +function recordFixMs(record) { + const epoch = record?.lastPositionEpoch; + if (Number.isFinite(epoch)) return epoch * 1000; + return Number.isFinite(record?.receivedAtMs) ? record.receivedAtMs : NaN; +} + export function createTracking({ vesselState, services, @@ -89,18 +98,94 @@ export function createTracking({ state.trailBackfillToken += 1; state.trailId = record.id; state.trailPositions = []; + state.trailTimes = []; const current = vesselTrailPosition(record); - if (current) state.trailPositions.push(current); + if (current) { + state.trailPositions.push(current); + state.trailTimes.push(recordFixMs(record)); + } if (!state.trail && state.viewer) { state.trail = createTrail(state.viewer, { color: TRAIL_COLOR, width: 2.5, }); } - if (state.trail) state.trail.setPositions(state.trailPositions); + if (!state.trailHeadOff && state.viewer) + state.trailHeadOff = + findFrame(state.viewer)?.on('preRender', drawSelectedVesselTrail) ?? + null; + drawTrailBody(); backfillVesselTrail(record.id, state.trailBackfillToken, record.reference); } + /** + * The world clock moved to another time: the trail keeps what it holds, + * drawn up to the new time, until the vessel's track at that time + * replaces it. Clearing it would blank the trail at every step of the clock. + * @param {Object} record - The selected vessel at the new time. + */ + function retimeSelectedVesselTrail(record) { + if (state.trailId !== record.id || !state.trail) { + startSelectedVesselTrail(record); + return; + } + state.trailAbort?.abort(); + state.trailAbort = new AbortController(); + state.trailBackfillToken += 1; + drawSelectedVesselTrail(); + backfillVesselTrail(record.id, state.trailBackfillToken, record.reference, { + replace: true, + }); + } + + /** The world time the selected vessel is drawn at; Infinity live, where + * every fix is behind it. */ + function drawnTimeMs() { + return followsClock(vesselState) ? vesselState.worldNow() : Infinity; + } + + /** How many trail vertices are at or before `atMs` (undated ones always). */ + function bodyCountAt(atMs) { + let count = state.trailTimes.length; + while (count > 0 && state.trailTimes[count - 1] > atMs) count -= 1; + return count; + } + + /** Draw the trail's body: its fixes up to the time the vessel is drawn at. + * A fix ahead of the vessel would draw the trail in front of it. */ + function drawTrailBody() { + if (!state.trail) return; + state.trailBodyCount = bodyCountAt(drawnTimeMs()); + state.trail.setPositions( + state.trailPositions.slice(0, state.trailBodyCount), + ); + } + + /** The head: the body's last vertex to where the vessel is drawn, or none + * (no vessel drawn, or one too far from the body to be on its path). */ + function trailHeadPositions() { + const record = state.selectedRecord; + if (!record || record.id !== state.trailId || state.trailBodyCount < 1) + return null; + // Where its icon is drawn now (the renderer's, while it moves the icons). + const at = components.rendering.drawnPositionNow(record); + const last = state.trailPositions[state.trailBodyCount - 1]; + if (!at || !last) return null; + const metres = distance(last, at); + if (metres < 1 || metres > TRAIL_HEAD_MAX_M) return null; + return [last, { x: at.x, y: at.y, z: at.z }]; + } + + /** + * Each frame before it draws: the body moved on when the drawn time has + * passed a fix, then the head to where the vessel is drawn now. + */ + function drawSelectedVesselTrail() { + if (!state.trail || !state.trailId) return; + if (bodyCountAt(drawnTimeMs()) !== state.trailBodyCount) drawTrailBody(); + state.trail.setHead?.(trailHeadPositions()); + } + /** * Fire-and-forget backfill from the server-side per-vessel ring buffer * (PRD F3 — "recent path" since server boot, not voyage history). Older @@ -112,7 +197,12 @@ export function createTracking({ * @returns {Promise} */ - async function backfillVesselTrail(id, token, reference = id) { + async function backfillVesselTrail( + id, + token, + reference = id, + { replace = false } = {}, + ) { const owner = state.trailAbort; // Following the world clock, the track ends at the world's time. const atMs = followsClock(vesselState) ? vesselState.worldNow() : undefined; @@ -139,6 +229,7 @@ export function createTracking({ if (state.trailId !== id) return; const older = []; + const olderTimes = []; for (const sample of samples) { const lat = Number(sample?.latitude); const lon = Number(sample?.longitude); @@ -156,16 +247,29 @@ export function createTracking({ TRAIL_HEIGHT_M, ); older.push(fromDegrees(lon, lat, heightM)); - } - if (!older.length) return; - - state.trailPositions = older.concat(state.trailPositions); - if (state.trailPositions.length > TRAIL_MAX_POINTS) { - state.trailPositions = state.trailPositions.slice( - state.trailPositions.length - TRAIL_MAX_POINTS, + olderTimes.push( + Number.isFinite(sample?.observedAtMs) ? sample.observedAtMs : NaN, ); } - if (state.trail) state.trail.setPositions(state.trailPositions); + if (replace) { + // The track at the new time, then the vessel's own fix at it. + const record = state.selectedRecord; + const current = record?.id === id ? vesselTrailPosition(record) : null; + state.trailPositions = current ? [...older, current] : older; + state.trailTimes = current + ? [...olderTimes, recordFixMs(record)] + : olderTimes; + } else { + if (!older.length) return; + state.trailPositions = older.concat(state.trailPositions); + state.trailTimes = olderTimes.concat(state.trailTimes); + } + if (state.trailPositions.length > TRAIL_MAX_POINTS) { + const drop = state.trailPositions.length - TRAIL_MAX_POINTS; + state.trailPositions = state.trailPositions.slice(drop); + state.trailTimes = state.trailTimes.slice(drop); + } + drawTrailBody(); } /** @@ -181,9 +285,12 @@ export function createTracking({ const last = state.trailPositions[state.trailPositions.length - 1]; if (last && distance(last, next) <= TRAIL_MIN_MOVE_M) return; state.trailPositions.push(next); - if (state.trailPositions.length > TRAIL_MAX_POINTS) + state.trailTimes.push(recordFixMs(record)); + if (state.trailPositions.length > TRAIL_MAX_POINTS) { state.trailPositions.shift(); - state.trail.setPositions(state.trailPositions); + state.trailTimes.shift(); + } + drawTrailBody(); } /** @@ -196,6 +303,10 @@ export function createTracking({ state.trailBackfillToken += 1; state.trailId = null; state.trailPositions = []; + state.trailTimes = []; + state.trailBodyCount = -1; + state.trailHeadOff?.(); + state.trailHeadOff = null; if (state.trail) state.trail.clear(); } @@ -215,6 +326,8 @@ export function createTracking({ vesselTrailPosition, refloorVesselRecords, startSelectedVesselTrail, + retimeSelectedVesselTrail, + drawSelectedVesselTrail, backfillVesselTrail, appendSelectedVesselTrailFix, clearSelectedVesselTrail, diff --git a/src/layers/vessels/tracking.test.mjs b/src/layers/vessels/tracking.test.mjs index 88f926b2a..89cacc276 100644 --- a/src/layers/vessels/tracking.test.mjs +++ b/src/layers/vessels/tracking.test.mjs @@ -5,10 +5,12 @@ import { createTracking } from './tracking.js'; import { TRAIL_HEIGHT_M, TRAIL_MAX_POINTS } from './policy.js'; /** One tracking part over a fake trail and geoid; `geoidN` is N everywhere. */ -function setup({ geoidN = 40, track = null } = {}) { +function setup({ geoidN = 40, track = null, clockAt = null } = {}) { const drawn = []; + const heads = []; const trail = { setPositions: (positions) => drawn.push([...positions]), + setHead: (positions) => heads.push(positions), clear() {}, destroy() {}, }; @@ -16,7 +18,12 @@ function setup({ geoidN = 40, track = null } = {}) { const records = []; const vesselState = { _geoidReady: true, - _source: { getTrack: async () => track }, + _source: { + getTrack: async (reference, options) => + typeof track === 'function' ? track(options) : track, + }, + timeline: { active: () => clockAt !== null }, + worldNow: () => clockAt, state: { viewer: {}, trail: null, @@ -34,6 +41,17 @@ function setup({ geoidN = 40, track = null } = {}) { }, rendering: { getVisual: (record) => visuals.get(record) ?? record, + // Drawn where its visual says, at the trail's height in these tests. + drawnPositionNow: (record) => { + const visual = visuals.get(record); + return visual + ? Cesium.Cartesian3.fromDegrees( + visual.drawnLon, + visual.drawnLat, + geoidN + TRAIL_HEIGHT_M, + ) + : null; + }, anchorPosition: (record) => ({ anchoredAt: [record.lon, record.lat] }), syncRecordIcon: (record) => synced.push(record), forgetClockStep: () => synced.push('forgetClockStep'), @@ -51,7 +69,16 @@ function setup({ geoidN = 40, track = null } = {}) { layer: {}, options: {}, }); - return { tracking, vesselState, drawn, synced, records, visuals, renders }; + return { + tracking, + vesselState, + drawn, + heads, + synced, + records, + visuals, + renders, + }; } const near = (a, b) => @@ -172,3 +199,107 @@ test('a long backfill keeps the newest TRAIL_MAX_POINTS vertices', async () => { 'the live fix stays newest', ); }); + +const settle = () => new Promise((resolve) => setTimeout(resolve, 0)); +const at = (lat, lon) => + Cesium.Cartesian3.fromDegrees(lon, lat, 40 + TRAIL_HEIGHT_M); + +test('following the clock, the trail ends at the vessel: fixes after its time wait, and a head joins the last one to it', async () => { + const T = 1_800_000_000_000; + const track = { + records: [ + { latitude: 51.8, longitude: 4.0, observedAtMs: T - 120_000 }, + { latitude: 51.81, longitude: 4.0, observedAtMs: T - 60_000 }, + ], + }; + const { tracking, vesselState, drawn, heads, visuals } = setup({ + track, + clockAt: T, + }); + const record = { + id: 'v', + reference: 'v', + lat: 51.83, + lon: 4.0, + lastPositionEpoch: (T + 120_000) / 1000, + }; + vesselState.state.selectedRecord = record; + visuals.set(record, { drawnLat: 51.815, drawnLon: 4.0, drawnAtMs: T }); + tracking.startSelectedVesselTrail(record); + await settle(); + assert.equal(drawn.at(-1).length, 2, 'the fixes before the time'); + assert.ok(near(drawn.at(-1)[1], at(51.81, 4.0))); + tracking.drawSelectedVesselTrail(); + const head = heads.at(-1); + assert.ok(near(head[0], at(51.81, 4.0)), 'from the last drawn fix'); + assert.ok(near(head[1], at(51.815, 4.0)), 'to the vessel as drawn'); + + // The clock passes the vessel's own fix: the body takes it on the next + // frame, and the vessel holds there. + vesselState.worldNow = () => T + 150_000; + visuals.get(record).drawnLat = 51.83; + tracking.drawSelectedVesselTrail(); + assert.equal(drawn.at(-1).length, 3); + assert.equal(heads.at(-1), null, 'no head with the vessel on its fix'); +}); + +test('a clock jump keeps the trail drawn to the new time until the track at it arrives', async () => { + const T = 1_800_000_000_000; + let release; + const later = new Promise((resolve) => (release = resolve)); + let asked = 0; + const first = { + records: [ + { latitude: 51.8, longitude: 4.0, observedAtMs: T - 120_000 }, + { latitude: 51.81, longitude: 4.0, observedAtMs: T - 60_000 }, + ], + }; + const { tracking, vesselState, drawn, visuals } = setup({ + track: () => (asked++ === 0 ? first : later), + clockAt: T, + }); + const record = { + id: 'v', + reference: 'v', + lat: 51.815, + lon: 4.0, + lastPositionEpoch: T / 1000, + }; + vesselState.state.selectedRecord = record; + visuals.set(record, { drawnLat: 51.815, drawnLon: 4.0, drawnAtMs: T }); + tracking.startSelectedVesselTrail(record); + await settle(); + const before = drawn.length; + // Back a minute and a half: one fix is behind the vessel then. + vesselState.worldNow = () => T - 90_000; + tracking.retimeSelectedVesselTrail(record); + assert.ok( + drawn.slice(before).every((positions) => positions.length >= 1), + 'never blanked', + ); + assert.equal(drawn.at(-1).length, 1, 'cut to the new time'); + release({ + records: [ + { latitude: 51.79, longitude: 4.0, observedAtMs: T - 180_000 }, + { latitude: 51.8, longitude: 4.0, observedAtMs: T - 120_000 }, + ], + }); + await settle(); + assert.equal(drawn.at(-1).length, 2, 'the track at the new time'); + assert.ok(near(drawn.at(-1)[0], at(51.79, 4.0))); +}); + +test('live, the head joins the last fix to the vessel where it is placed, and not across a jump', () => { + const { tracking, vesselState, heads, visuals } = setup(); + const record = { id: 'v', reference: 'v', lat: 51.8, lon: 4.0 }; + vesselState.state.selectedRecord = record; + visuals.set(record, { drawnLat: 51.801, drawnLon: 4.0 }); + tracking.startSelectedVesselTrail(record); + tracking.drawSelectedVesselTrail(); + assert.ok(near(heads.at(-1)[0], at(51.8, 4.0))); + assert.ok(near(heads.at(-1)[1], at(51.801, 4.0))); + // Drawn 100 km on: no head across that. + visuals.get(record).drawnLat = 52.7; + tracking.drawSelectedVesselTrail(); + assert.equal(heads.at(-1), null); +});