From e31de29cccb5a4fe89fa79089ccbafc3d0fa17fc Mon Sep 17 00:00:00 2001 From: Sameh Khamis Date: Sat, 14 Nov 2026 23:18:28 -0800 Subject: [PATCH 01/13] Move satellites every frame between SGP4 samples Satellite points were propagated once a second and held still in between, so while the world clock plays faster than real time they jumped: at 1 min/s, about 45 px once a second at globe scale. Each SGP4 call now keeps a sample of the satellite's inertial position, velocity, gravity and its rate of change (src/layers/satellites/motion.js). Every frame each shown point is reckoned from its sample to the world time and turned into the Earth-fixed frame by the sidereal angle, so points glide at any play speed. Core satellites still take a fresh sample every second, and at once when the world time is 30 s from it (fast play, a seek), which keeps every point within about 10 m of SGP4. Starlink extras take their first sample as they load and are resampled round-robin, more per frame the faster time plays (up to 2,000 a frame); a point more than two minutes from its sample waits for the next one. Hidden points are moved when shown again, and the tracked satellite keeps its per-frame path. Measured at globe scale: at 1 min/s points move on every frame, 0.4 px a frame and at most 1.4 px (before: once a second, 45 px). With 11,880 satellites (Starlink on) the scene holds 60 fps, frames 16.7 ms median and 19.7 ms p95; reckoning costs 0.02 ms a frame for 1,342 points. --- docs/CURRENT-STATE.md | 8 +- scripts/format-scope.json | 3 + scripts/package-boundaries.json | 3 + src/layers/satellites/catalog.js | 76 +++++++------ src/layers/satellites/motion.js | 80 +++++++++++++ src/layers/satellites/motion.test.mjs | 86 ++++++++++++++ src/layers/satellites/policy.js | 18 ++- src/layers/satellites/reckon.test.mjs | 157 ++++++++++++++++++++++++++ src/layers/satellites/rendering.js | 89 +++++++++++---- src/layers/satellites/state.js | 4 + src/layers/satellites/tracking.js | 2 +- 11 files changed, 466 insertions(+), 60 deletions(-) create mode 100644 src/layers/satellites/motion.js create mode 100644 src/layers/satellites/motion.test.mjs create mode 100644 src/layers/satellites/reckon.test.mjs diff --git a/docs/CURRENT-STATE.md b/docs/CURRENT-STATE.md index 2ba3165f0..cc578dcfd 100644 --- a/docs/CURRENT-STATE.md +++ b/docs/CURRENT-STATE.md @@ -4940,8 +4940,8 @@ down | auth-failed` (plus the unchanged `missing-key`/`unsupported`) with > Cesium entity carries no label graphic. > - **Phase 5 ISS and tracked-satellite labels:** The ISS path and large red > point remain native, while persistent `ISS` text is a one-entry moving -> ambient-label host source. Its getter reads the already-propagated point -> cache, preserving the 1 Hz fleet epoch and eliminating the former second ISS +> ambient-label host source. Its getter reads the point's own position, which +> moves every frame, eliminating the former second ISS > propagation. Satellite tracking continues to publish exactly one protected > tracked-lane card through `gevLabelModel` and `_trackedDisplayCached`; the > tracked entity is point-only. Tracking ISS suppresses the ambient entry and @@ -7002,7 +7002,7 @@ silently demoting every later lookup for the session. `activeCameraCardEnabled` presentation option can publish the retained protected-card path. Disable tears the tier down completely. Coverage/viewshed semantics unchanged. -- **Satellites**: orbit rings rotate about Earth's Z by ΔGMST every ~1s (exact inertial→ECEF compensation; no SGP4 re-runs); the tracked satellite propagates per frame with one shared epoch for dot/label/camera. Verified: ISS holds <1km perpendicular to its ring while tracked. Pass prediction (`src/data/satellitePass.js`; `getNextSatellitePass`, `getNextIssPass`) scans at 20s, bisects rise/set to ~0.2s, fits the peak with a parabola, and marks a pass visible when the satellite is outside a cylindrical Earth shadow while the observer's Sun is at or below −6°. `next_iss_pass` preserves its geometric-pass ordering and appends visibility metadata. General `next_satellite_pass` accepts a loaded NORAD ID or unambiguous name, searches 24 hours and optionally requires estimated visibility. These estimates do not account for weather or satellite brightness. +- **Satellites**: every point moves every frame. Each satellite's SGP4 sample (position, velocity, gravity and its rate of change; `src/layers/satellites/motion.js`) is reckoned forward or back to the world time and turned into the Earth-fixed frame, so points glide at any play speed instead of stepping once a second. Core satellites take a fresh sample every second, or as soon as the world time is 30 s from their sample (fast play, a seek), which keeps every point within about 10 m of SGP4; Starlink extras are sampled round-robin, more per frame the faster time plays, and a point more than two minutes from its sample waits for the next one. Hidden points are not moved until shown. Orbit rings rotate about Earth's Z by ΔGMST every ~1s (exact inertial→ECEF compensation; no SGP4 re-runs); the tracked satellite propagates per frame with one shared epoch for dot/label/camera. Verified: ISS holds <1km perpendicular to its ring while tracked. Pass prediction (`src/data/satellitePass.js`; `getNextSatellitePass`, `getNextIssPass`) scans at 20s, bisects rise/set to ~0.2s, fits the peak with a parabola, and marks a pass visible when the satellite is outside a cylindrical Earth shadow while the observer's Sun is at or below −6°. `next_iss_pass` preserves its geometric-pass ordering and appends visibility metadata. General `next_satellite_pass` accepts a loaded NORAD ID or unambiguous name, searches 24 hours and optionally requires estimated visibility. These estimates do not account for weather or satellite brightness. - **Space Missions (30d)**: recent launches render as bounded shared-host, horizon-occluded mission markers using Launch Library 2 v2.3 detailed records. Enabling the layer selects the unified right-side Context panel's Space Missions mode and enables the required satellite layer. Before applying its temporary dense/hidden Satellite mode, Space Missions snapshots the complete standalone Satellite parameter set and exact enabled-layer set. Disabling Space Missions from either Context or the left Data Layers rail restores those parameters and the exact prior enabled state, so a Satellite layer that was already on stays on while a mode-owned dependency returns off; enabling Satellites by itself remains independent. Selecting a mission isolates its launch-to-orbit transfer and dashed satellite orbit, fills that same panel with navigation/details, and animates a small phase-colored marker along the exact displayed Cartesian samples. Marker hit testing drill-picks through photorealistic tiles so the depth-test-free tactical dot remains reliably selectable; its text is non-interactive shared-host presentation. The selected pad is the camera's zoom pivot: the overview remains centered on its launch site, wheel zoom approaches that site instead of drifting elsewhere, and camera pitch progressively changes from global nadir to an oblique close 3D view. Its protected shared-host callout remains visible and expands to include both mission and launch-site names. `FOCUS` flies directly to a 12 km oblique frame around the selected launch site and retains the same anchored zoom/orbit behavior. `REPLAY ASCENT` resets the selected marker at the pad, frames it from an oblique third-person angle, and follows it through the mission-specific compressed ascent directly into one orbital lap at the default `1×` rate. A live `0.25×`–`4×` slider changes ascent and orbit playback speed; adjusting it mid-replay preserves the current path position and historical mission timestamp. Re-entry/recovery cannot be inserted into replay. At orbit insertion the camera smoothly pulls back over the first fifth of the orbital replay and pitches to a globe-scale nadir view while continuing to target the moving replay point. Replay Cancel, mission navigation, deselection, layer disable, and data refresh all release camera ownership. Reconstructed paths are one continuous 128-sample geodetic curve: horizontal departure begins near zero while altitude rises quickly, then the climb progressively bends toward insertion without the former hard 120 km corner. Unmatched orbit fallbacks are smooth planar inclined rings rather than longitude/latitude ground-track curves. The panel lists disclosed payload names, types, operators/manufacturers, mass, multiplicity, and destination when supplied; an empty LL2 payload collection is shown as `CLASSIFIED / MULTI-PAYLOAD`. Launcher, spacecraft, and recoverable payload stages appear in a compact stage table with serial/flight/reuse details, recovery outcome/type, destination, and final coordinates when those records exist; an empty recovery collection omits the section. Stage recoveries with confirmed coordinates use those coordinates; return-to-launch-site records use the pad; downrange-only records receive an explicitly labeled estimated endpoint along the ascent azimuth. Available endpoints render as static 2 px dashed descent/recovery paths with a fixed final-position dot and an estimated atmospheric-interface segment when applicable. The ascent is geodetically densified above the ellipsoid toward the orbit's nearest insertion point, then rendered with `ArcType.NONE`, so it neither cuts through Earth nor separates from the marker. Because LL2 does not normally supply continuous ascent telemetry, pad-to-insertion paths without upstream trajectory samples are labeled `RECONSTRUCTED ESTIMATE` / `ASCENT ESTIMATE`; only supplied trajectory samples receive the replay wording. Selected-orbit framing fits the complete ring, rear-side linework uses normal scene depth occlusion, and current distance, speed, and callout data come only from a launch-year-validated satellite match. Both the loaded-catalog and active-TLE lookups read the launch year from the TLE international designator through one parser (`src/sources/tle.js`); a blank or malformed designator is an unknown year, which skips the year check rather than rejecting the match. Speed is the magnitude of the SGP4 inertial velocity vector at the same propagation epoch as position, displayed in km/s with km/h available as hover detail. Unavailable operator, site, launch-time, orbit, current-altitude, and speed values omit their detail rows instead of reserving panel space with placeholders. Newly launched payloads absent from the core operational groups use CelesTrak's cached active TLE feed as a lookup-only fallback; weak constellation-name matches are rejected. The replay callout maps compressed animation progress onto Launch Library's mission-relative timeline, showing the historical UTC date/time at the marker's current path position; unavailable timelines remain explicit. Matched live satellite positions propagate at one-second cadence and use a distinct green dot/callout with the current UTC date/time. When no mission is selected, the Context panel presents a scrollable newest-first roster of every launch in the rolling window, including the smaller 5 px operator-colored marker, provider, and launch date. Hovering or keyboard-focusing a row shows four compact cyan corner brackets on both that roster row and its corresponding globe dot, rotates the globe at the current zoom to center it, and gives its label declutter priority without selecting it; the globe label remains unbracketed. Selecting a roster row invokes the same mission isolation and full-orbit framing as clicking its globe marker. The replay vehicle is one screen-space SVG/CSS HUD overlay rather than separate Cesium billboard, label, and reticle graphics. It is hidden during ordinary Focus and manual close views, where the standard selected launch-site label remains visible, and exists only while ascent replay is active. Its fixed pixel scale is shared by ascent and insertion, so camera range never resizes the rocket on screen before the phase boundary. Generic Launch Library pad names are reduced to their identifying suffix, and replay timestamps use a cyan state title over unprefixed white UTC date/time values. `REPLAY ASCENT` holds the unframed cyan/white rocket at the pad for a real-time `T−10` countdown, transitions through `LIFTOFF`, and attaches six tapered cyan/white ellipse waves directly below it from liftoff through insertion to convey thrust without adding scene geometry. While replay is active, the single start button is replaced by compact Play, Pause, and Cancel icon controls. Pause freezes countdown or mission time, vehicle/stage positions, camera target, labels, and thrust-wave animation; Play resumes from that exact frame, and Cancel releases replay camera ownership. The rocket and thrust group rotates from the path's live screen-space tangent, so its nose follows the visible ascent curve while the adjacent text remains upright. The camera begins as a close oblique launch chase, then smoothly widens between roughly 120 and 420 km vehicle altitude into a higher oblique context view that keeps the moving rocket targeted while exposing the ascent bend and orbit connection. At insertion the rocket/thrust glyph is replaced by the fixed-size cyan orbit dot, which the camera follows through the existing globe-scale orbit pullback. The chase camera limits per-frame yaw changes across heading wraps so it cannot abruptly cross in front of the vehicle and make ascent read in reverse; the replay-speed slider affects mission playback but not countdown duration. Mission world text has no native `LabelGraphics`: overview launch markers publish at most 48 ambient candidates for a 24-winner budget, while selecting a mission clears that overview source and publishes its launch-site callout, stage re-entry annotations, live/estimated payload-position readout, and orbit annotation as protected selected-lane entries. The source retains the exact former strings and colors. Static anchors reuse the Cartesian values used to build their mission geometry; the moving payload entry reads the layer's per-frame live-position cache; catalog-backed orbit annotation positions are cached in the same one-second matrix update that realigns the orbit primitive. Keyhole edge fade, horizon culling, final collision placement, and UI exclusion are owned by the shared host. Deselect restores the bounded overview, and refresh, disable, and destroy replace or clear both mission sources. @@ -8197,7 +8197,7 @@ The Space Missions roster prioritizes data-rich records using available mission, When no live catalog track is available, the mission view marks the approximate orbital ring as `PROJECTED ORBIT` in purple and renders the ascent-to-insertion transfer in green; catalog-backed satellite orbits remain cyan. The replay vehicle is a smaller solid cyan silhouette without the former orange flame; its initial pad anchor uses photoreal terrain, globe height, or launch elevation fallback so it remains above the surface during tile loading. Replay begins at a close launch-complex range so pad detail remains visible before the camera widens into the ascent context view. Its initial camera heading is perpendicular to the ascent/orbit direction for a profile view, then eases into tangent tracking. Small screen-space reprojection changes are damped for the animated marker on both ascent and orbit, while large camera or phase changes snap to the authoritative path position. -Space Missions keeps the Satellite layer available for catalog/TLE matching but suppresses its standalone fleet points and orbit rings. While those visuals are hidden, their per-frame dense propagation, one-second core point-buffer rewrite, and one-second orbit-matrix rotation are suspended; selected mission telemetry continues to propagate independently. The selected mission's live or estimated satellite marker uses fractional wall-clock time, so it moves continuously rather than creating a once-per-second position discontinuity and one-frame photoreal globe LOD pulse. +Space Missions keeps the Satellite layer available for catalog/TLE matching but suppresses its standalone fleet points and orbit rings. While those visuals are hidden, their sampling, per-frame point moves, and one-second orbit-matrix rotation are suspended; selected mission telemetry continues to propagate independently. The selected mission's live or estimated satellite marker uses fractional wall-clock time, so it moves continuously rather than creating a once-per-second position discontinuity and one-frame photoreal globe LOD pulse. During ascent replay, the camera, Cesium callbacks, and HTML vehicle overlay share one replay sample per rendered frame. The tracked overlay is projected directly from that shared position instead of applying a second screen-space lag filter, preventing the vehicle and globe from repeatedly advancing and snapping back. diff --git a/scripts/format-scope.json b/scripts/format-scope.json index 849f73e1f..8487f7472 100644 --- a/scripts/format-scope.json +++ b/scripts/format-scope.json @@ -456,6 +456,7 @@ "src/layers/satellites/ingestion.js", "src/layers/satellites/index.js", "src/layers/satellites/orbits.js", + "src/layers/satellites/motion.js", "src/layers/launches/lifecycle.js", "src/layers/launches/controls.js", "src/layers/launches/panel.js", @@ -483,6 +484,8 @@ "src/data/rocketLaunches.js", "src/layers/satellites/source.test.mjs", "src/layers/satellites/stale.test.mjs", + "src/layers/satellites/motion.test.mjs", + "src/layers/satellites/reckon.test.mjs", "src/layers/launches/source.test.mjs", "src/layers/launches/ingestion.test.mjs", "src/layers/launches/failedEntry.test.mjs", diff --git a/scripts/package-boundaries.json b/scripts/package-boundaries.json index 95e87d082..c275337cb 100644 --- a/scripts/package-boundaries.json +++ b/scripts/package-boundaries.json @@ -1854,6 +1854,7 @@ "src/layers/satellites/interaction.js", "src/layers/satellites/labels.js", "src/layers/satellites/lifecycle.js", + "src/layers/satellites/motion.js", "src/layers/satellites/orbits.js", "src/layers/satellites/records.js", "src/layers/satellites/policy.js", @@ -2972,6 +2973,7 @@ "src/layers/satellites/interaction.js", "src/layers/satellites/labels.js", "src/layers/satellites/lifecycle.js", + "src/layers/satellites/motion.js", "src/layers/satellites/orbits.js", "src/sources/tle.js", "src/layers/satellites/records.js", @@ -4159,6 +4161,7 @@ "src/layers/satellites/interaction.js", "src/layers/satellites/labels.js", "src/layers/satellites/lifecycle.js", + "src/layers/satellites/motion.js", "src/layers/satellites/orbits.js", "src/sources/tle.js", "src/layers/satellites/records.js", diff --git a/src/layers/satellites/catalog.js b/src/layers/satellites/catalog.js index b1faf8f70..c04d9bb8c 100644 --- a/src/layers/satellites/catalog.js +++ b/src/layers/satellites/catalog.js @@ -1,11 +1,14 @@ import * as Cesium from 'cesium'; -import { twoline2satrec } from 'satellite.js'; +import { gstime, twoline2satrec } from 'satellite.js'; import { noradIdFromSatnum, tleLineLaunchYear } from '../../sources/tle.js'; +import { reckonEarthFixed, sampleOrbit } from './motion.js'; import { DENSE_REFRESH_FRAMES, DENSE_GROUP_PATH, + DENSE_SAMPLES_PER_FRAME_MAX, POINT_STYLES, DENSE_CREATE_CHUNK, + ORBIT_SAMPLE_HORIZON_MS, } from './policy.js'; export function createCatalog({ state: layerState, services, parts, source }) { @@ -18,37 +21,42 @@ export function createCatalog({ state: layerState, services, parts, source }) { } /** - * Re-propagate a small per-frame slice of the dense extras (round-robin). - * Budget: the full dense set completes one pass every ~DENSE_REFRESH_FRAMES - * frames (~5s at 60fps ≈ 1/5 of the core cadence), so per-frame cost stays - * ~35 propagations (~0.1 ms) even with 10K+ Starlink sats — spreading the - * work per frame avoids the once-per-second spike a tick-sized chunk - * (~2K props ≈ 4ms) would cause. + * Sample a small per-frame slice of the dense extras (round-robin); every + * point is then reckoned from its sample each frame (rendering.js + * _reckonPoints). At normal speed the full dense set is sampled once every + * ~DENSE_REFRESH_FRAMES frames (~5s at 60fps), so per-frame cost stays ~35 + * propagations (~0.1 ms) even with 10K+ Starlink sats — spreading the work + * per frame avoids the once-per-second spike a tick-sized chunk (~2K props + * ≈ 4ms) would cause. While time plays fast, or after a seek, the slice + * grows so each sample stays within ORBIT_SAMPLE_HORIZON_MS of the world + * time, up to DENSE_SAMPLES_PER_FRAME_MAX a frame. + * @param {number} worldStepMs How far the world time moved since the last + * frame (NaN on the first). */ - function _propagateDenseChunk() { - if (layerState._denseIds.length === 0) return; - const perFrame = Math.max( - 1, - Math.ceil(layerState._denseIds.length / DENSE_REFRESH_FRAMES), + function _propagateDenseChunk(worldStepMs) { + const count = layerState._denseIds.length; + if (count === 0) return; + const share = Math.max( + 1 / DENSE_REFRESH_FRAMES, + Number.isFinite(worldStepMs) + ? Math.abs(worldStepMs) / ORBIT_SAMPLE_HORIZON_MS + : 1, ); - const now = new Date(layerState.now()); + const perFrame = Math.min( + count, + DENSE_SAMPLES_PER_FRAME_MAX, + Math.max(1, Math.ceil(count * share)), + ); + const nowMs = layerState.now(); for (let i = 0; i < perFrame; i++) { - if (layerState._denseCursor >= layerState._denseIds.length) - layerState._denseCursor = 0; + if (layerState._denseCursor >= count) layerState._denseCursor = 0; const noradId = layerState._denseIds[layerState._denseCursor++]; if (noradId === layerState._trackedNorad) continue; // per-frame tracked path owns it const sat = layerState._catalog.get(noradId); - const point = layerState._points.get(noradId); - if (!sat || !point) continue; - const pos = parts.orbits.propagatePosition(sat.satrec, now); - if (pos) { - point.position = Cesium.Cartesian3.fromDegrees( - pos.longitude, - pos.latitude, - pos.altitude, - ); - } + if (!sat) continue; + const sample = sampleOrbit(sat.satrec, nowMs, sat.orbitSample); + if (sample) sat.orbitSample = sample; } } @@ -97,7 +105,8 @@ export function createCatalog({ state: layerState, services, parts, source }) { const entries = parts.orbits.parseTLE(text); const style = POINT_STYLES.dense; - const now = new Date(layerState.now()); + const nowMs = layerState.now(); + const gmst = gstime(new Date(nowMs)); let added = 0; for (let start = 0; start < entries.length; start += DENSE_CREATE_CHUNK) { @@ -116,8 +125,9 @@ export function createCatalog({ state: layerState, services, parts, source }) { if (!satrec || satrec.error !== 0) continue; const noradId = noradIdFromSatnum(satrec.satnum); if (layerState._catalog.has(noradId)) continue; // core catalog keeps priority - const pos = parts.orbits.propagatePosition(satrec, now); - if (!pos) continue; + // Its first sample places it now and moves it from then on. + const orbitSample = sampleOrbit(satrec, nowMs); + if (!orbitSample) continue; layerState._catalog.set(noradId, { name: entry.name, @@ -131,12 +141,14 @@ export function createCatalog({ state: layerState, services, parts, source }) { ucs: null, satcat: null, sensor: null, + orbitSample, }); const point = layerState._pointCollection.add({ - position: Cesium.Cartesian3.fromDegrees( - pos.longitude, - pos.latitude, - pos.altitude, + position: reckonEarthFixed( + orbitSample, + nowMs, + gmst, + new Cesium.Cartesian3(), ), pixelSize: style.pixelSize, color: style.color, diff --git a/src/layers/satellites/motion.js b/src/layers/satellites/motion.js new file mode 100644 index 000000000..defbd2ee0 --- /dev/null +++ b/src/layers/satellites/motion.js @@ -0,0 +1,80 @@ +import { propagate } from 'satellite.js'; + +/** The Earth's gravitational parameter, km³/s², as SGP4's WGS72 constants. */ +const MU_KM3_S2 = 398600.8; + +/** Floats in one orbit sample: its time, then position, velocity, + * acceleration and jerk. */ +export const ORBIT_SAMPLE_LENGTH = 13; + +/** + * One SGP4 state of a satellite for dead reckoning: its inertial (TEME) + * position and velocity at `atMs`, with the two-body acceleration and its + * rate of change (jerk) there. + * Layout: [atMs, rx, ry, rz (km), vx, vy, vz (km/s), ax, ay, az (km/s²), + * jx, jy, jz (km/s³)]. + * @param {object} satrec + * @param {number} atMs Epoch milliseconds. + * @param {Float64Array} [out] + * @returns {Float64Array|null} Null when SGP4 has no state for that time. + */ +export function sampleOrbit( + satrec, + atMs, + out = new Float64Array(ORBIT_SAMPLE_LENGTH), +) { + let state; + try { + state = propagate(satrec, new Date(atMs)); + } catch { + return null; + } + const p = state?.position; + const v = state?.velocity; + if (!p || typeof p === 'boolean' || !v || typeof v === 'boolean') return null; + const r = Math.hypot(p.x, p.y, p.z); + if (!(r > 0) || !Number.isFinite(v.x + v.y + v.z)) return null; + const k = -MU_KM3_S2 / (r * r * r); + // d/dt of -μ r/|r|³: -μ (v/|r|³ - 3 (r·v) r/|r|⁵). + const radial = (3 * (p.x * v.x + p.y * v.y + p.z * v.z)) / (r * r); + out[0] = atMs; + out[1] = p.x; + out[2] = p.y; + out[3] = p.z; + out[4] = v.x; + out[5] = v.y; + out[6] = v.z; + out[7] = k * p.x; + out[8] = k * p.y; + out[9] = k * p.z; + out[10] = k * (v.x - radial * p.x); + out[11] = k * (v.y - radial * p.y); + out[12] = k * (v.z - radial * p.z); + return out; +} + +/** + * Where a satellite is at `atMs`, reckoned from its sample along the inertial + * path (position, velocity, gravity and its change) and turned into the + * Earth-fixed frame by the Greenwich sidereal angle at that time. Over half a + * minute of world time the reckoned point stays within metres of SGP4. + * @param {Float64Array} sample From sampleOrbit. + * @param {number} atMs Epoch milliseconds. + * @param {number} gmst Greenwich mean sidereal angle at `atMs`, radians. + * @param {{x: number, y: number, z: number}} out Receives Earth-fixed metres. + * @returns {{x: number, y: number, z: number}} `out`. + */ +export function reckonEarthFixed(sample, atMs, gmst, out) { + const dt = (atMs - sample[0]) / 1000; + const half = 0.5 * dt * dt; + const sixth = (half * dt) / 3; + const x = sample[1] + sample[4] * dt + sample[7] * half + sample[10] * sixth; + const y = sample[2] + sample[5] * dt + sample[8] * half + sample[11] * sixth; + const z = sample[3] + sample[6] * dt + sample[9] * half + sample[12] * sixth; + const cos = Math.cos(gmst); + const sin = Math.sin(gmst); + out.x = (x * cos + y * sin) * 1000; + out.y = (-x * sin + y * cos) * 1000; + out.z = z * 1000; + return out; +} diff --git a/src/layers/satellites/motion.test.mjs b/src/layers/satellites/motion.test.mjs new file mode 100644 index 000000000..eb9a6c096 --- /dev/null +++ b/src/layers/satellites/motion.test.mjs @@ -0,0 +1,86 @@ +// src/layers/satellites/motion.test.mjs — a satellite's point reckoned from +// one SGP4 sample stays on SGP4's track between samples. +import test from 'node:test'; +import assert from 'node:assert/strict'; +import * as Cesium from 'cesium'; +import { gstime, twoline2satrec } from 'satellite.js'; +import { createOrbits } from './orbits.js'; +import { reckonEarthFixed, sampleOrbit } from './motion.js'; + +const ISS = twoline2satrec( + '1 25544U 98067A 08264.51782528 -.00002182 00000-0 -11606-4 0 2927', + '2 25544 51.6416 247.4627 0006703 130.5360 325.0288 15.72125391563537', +); +const AT_MS = Date.UTC(2008, 8, 20, 12, 30, 0); +const orbits = createOrbits({ state: {}, services: {}, parts: {} }); + +/** Where the layer has always drawn a satellite: SGP4, through geodetic. */ +function drawnBySgp4(atMs) { + const pos = orbits.propagatePosition(ISS, new Date(atMs)); + return Cesium.Cartesian3.fromDegrees( + pos.longitude, + pos.latitude, + pos.altitude, + ); +} + +function reckoned(sample, atMs) { + return reckonEarthFixed( + sample, + atMs, + gstime(new Date(atMs)), + new Cesium.Cartesian3(), + ); +} + +test('at its own time the reckoned point is where SGP4 draws it', () => { + const sample = sampleOrbit(ISS, AT_MS); + const gap = Cesium.Cartesian3.distance( + reckoned(sample, AT_MS), + drawnBySgp4(AT_MS), + ); + assert.ok(gap < 1, `${gap} m`); +}); + +test('between samples the point keeps to the SGP4 track', () => { + const sample = sampleOrbit(ISS, AT_MS); + for (const [seconds, withinM] of [ + [0.016, 1], + [1, 2], + [10, 2], + [30, 10], + [60, 50], + ]) { + const atMs = AT_MS + seconds * 1000; + const gap = Cesium.Cartesian3.distance( + reckoned(sample, atMs), + drawnBySgp4(atMs), + ); + assert.ok(gap < withinM, `${seconds} s: ${gap} m`); + } +}); + +test('the point moves every frame, at orbital speed', () => { + const sample = sampleOrbit(ISS, AT_MS); + const a = reckoned(sample, AT_MS + 500); + const b = reckoned(sample, AT_MS + 516); + const speed = Cesium.Cartesian3.distance(a, b) / 0.016; + // ISS ground-relative speed: about 7.2–7.7 km/s. + assert.ok(speed > 7000 && speed < 8000, `${speed} m/s`); +}); + +test('reckoning backwards in time works as forwards', () => { + const sample = sampleOrbit(ISS, AT_MS); + const atMs = AT_MS - 30_000; + const gap = Cesium.Cartesian3.distance( + reckoned(sample, atMs), + drawnBySgp4(atMs), + ); + assert.ok(gap < 10, `${gap} m`); +}); + +test('an element set SGP4 cannot propagate has no sample', () => { + const decayed = { ...ISS, error: 0 }; + decayed.ecco = 2; // not an orbit + assert.equal(sampleOrbit(decayed, AT_MS), null); +}); diff --git a/src/layers/satellites/policy.js b/src/layers/satellites/policy.js index 44b31d814..9608b7b57 100644 --- a/src/layers/satellites/policy.js +++ b/src/layers/satellites/policy.js @@ -31,7 +31,16 @@ export const ISS_OVERLAY_SOURCE_OPTIONS = Object.freeze({ export const ORBIT_PATH_STEPS = 180; // points per orbital path +/** How often every core satellite takes a fresh SGP4 sample (wall ms). */ export const POSITION_UPDATE_MS = 1000; +/** + * Between SGP4 samples every point is reckoned each frame from its last one + * (motion.js). A sample this far from the world time is taken again, so a + * point is never more than about 10 m off SGP4 however fast time plays. + */ +export const ORBIT_SAMPLE_HORIZON_MS = 30_000; +/** Beyond this from its sample a point is left where it is until sampled again. */ +export const ORBIT_RECKON_LIMIT_MS = 120_000; /** How far either side of now SGP4 on current element sets stays meaningful. */ export const SATELLITE_COVERAGE_MS = 14 * 24 * 3_600_000; @@ -41,7 +50,6 @@ export const SATELLITE_COVERAGE_MS = 14 * 24 * 3_600_000; * drifts a few degrees a day. */ export const ORBIT_REBAKE_MS = 30 * 60_000; -// re-propagate every 1s (SGP4 is smooth at this rate) export const RING_ROTATION_MS = 1000; // re-align baked orbit rings to current GMST every 1s @@ -80,6 +88,14 @@ export const DENSE_GROUP_PATH = 'starlink'; export const DENSE_REFRESH_FRAMES = 300; // full dense pass spread over ~300 frames (~5s @ 60fps) +/** + * The most dense extras sampled in one frame while time plays fast (~4 ms). + * Past about 10 minutes of world time a second the full dense set no longer + * fits within ORBIT_RECKON_LIMIT_MS, and its points move only as they are + * sampled. + */ +export const DENSE_SAMPLES_PER_FRAME_MAX = 2000; + export const DENSE_CREATE_CHUNK = 1500; // satrec builds per macro-task while loading diff --git a/src/layers/satellites/reckon.test.mjs b/src/layers/satellites/reckon.test.mjs new file mode 100644 index 000000000..64dcfde0e --- /dev/null +++ b/src/layers/satellites/reckon.test.mjs @@ -0,0 +1,157 @@ +// src/layers/satellites/reckon.test.mjs — every frame each shown point moves +// to where its satellite is at the world time; samples are taken again when +// time has moved far from them, and dense extras are sampled faster the +// faster time plays. +import test from 'node:test'; +import assert from 'node:assert/strict'; +import * as Cesium from 'cesium'; +import { twoline2satrec } from 'satellite.js'; +import { createCatalog } from './catalog.js'; +import { createOrbits } from './orbits.js'; +import { createRendering } from './rendering.js'; +import { sampleOrbit } from './motion.js'; +import { + DENSE_REFRESH_FRAMES, + DENSE_SAMPLES_PER_FRAME_MAX, + ORBIT_RECKON_LIMIT_MS, + ORBIT_SAMPLE_HORIZON_MS, +} from './policy.js'; + +const ISS = twoline2satrec( + '1 25544U 98067A 08264.51782528 -.00002182 00000-0 -11606-4 0 2927', + '2 25544 51.6416 247.4627 0006703 130.5360 325.0288 15.72125391563537', +); +const AT_MS = Date.UTC(2008, 8, 20, 12, 30, 0); +const orbits = createOrbits({ state: {}, services: {}, parts: {} }); + +/** A point primitive that counts position writes. */ +function point(show = true) { + let position = new Cesium.Cartesian3(); + return { + show, + writes: 0, + get position() { + return position; + }, + set position(value) { + this.writes++; + position = Cesium.Cartesian3.clone(value); + }, + }; +} + +function scene(entries, { tracked = null } = {}) { + const state = { + _points: new Map(), + _catalog: new Map(), + _trackedNorad: tracked, + _denseIds: [], + _denseCursor: 0, + }; + for (const [id, entry] of Object.entries(entries)) { + state._points.set(id, entry.point); + state._catalog.set(id, { satrec: ISS, group: 'core', ...entry.sat }); + } + const rendering = createRendering({ + state, + services: { focus: {} }, + parts: {}, + }); + return { state, rendering }; +} + +function sgp4At(atMs) { + const pos = orbits.propagatePosition(ISS, new Date(atMs)); + return Cesium.Cartesian3.fromDegrees( + pos.longitude, + pos.latitude, + pos.altitude, + ); +} + +test('a shown point moves to its satellite at the world time; hidden and tracked ones do not', () => { + const shown = point(); + const hidden = point(false); + const tracked = point(); + const { rendering } = scene( + { + shown: { point: shown }, + hidden: { point: hidden }, + tracked: { point: tracked }, + }, + { tracked: 'tracked' }, + ); + rendering._reckonPoints(AT_MS); + assert.ok(Cesium.Cartesian3.distance(shown.position, sgp4At(AT_MS)) < 1); + assert.equal(hidden.writes, 0); + assert.equal(tracked.writes, 0); + // The same time again (the clock paused): nothing is written. + rendering._reckonPoints(AT_MS); + assert.equal(shown.writes, 1); + // Shown while paused, a hidden point moves at once. + hidden.show = true; + rendering._reckonPoints(AT_MS); + assert.equal(hidden.writes, 1); +}); + +test('between samples the point keeps to the track; far from its sample, a core satellite is sampled again', () => { + const p = point(); + const { state, rendering } = scene({ iss: { point: p } }); + rendering._reckonPoints(AT_MS); + const sample = state._catalog.get('iss').orbitSample; + assert.equal(sample[0], AT_MS); + // Within the horizon the same sample moves it on. + const soon = AT_MS + ORBIT_SAMPLE_HORIZON_MS / 2; + rendering._reckonPoints(soon); + assert.equal(state._catalog.get('iss').orbitSample[0], AT_MS); + assert.ok(Cesium.Cartesian3.distance(p.position, sgp4At(soon)) < 5); + // A seek an hour back samples it again there. + const back = AT_MS - 3_600_000; + rendering._reckonPoints(back); + assert.equal(state._catalog.get('iss').orbitSample[0], back); + assert.ok(Cesium.Cartesian3.distance(p.position, sgp4At(back)) < 1); +}); + +test('a dense extra is left for its round-robin, and stays put once too far from its sample', () => { + const p = point(); + const { rendering } = scene({ + starlink: { + point: p, + sat: { group: 'dense', orbitSample: sampleOrbit(ISS, AT_MS) }, + }, + }); + rendering._reckonPoints(AT_MS + ORBIT_SAMPLE_HORIZON_MS * 2); + assert.equal(p.writes, 1, 'reckoned from its own sample'); + rendering._reckonPoints(AT_MS + ORBIT_RECKON_LIMIT_MS + 1); + assert.equal(p.writes, 1, 'too far: left where it is'); +}); + +test('the dense slice grows with how fast the world time moves, up to its cap', () => { + const sampled = (count, worldStepMs) => { + const state = { + _denseIds: [], + _denseCursor: 0, + _catalog: new Map(), + _trackedNorad: null, + now: () => AT_MS, + }; + for (let i = 0; i < count; i++) { + state._denseIds.push(String(i)); + state._catalog.set(String(i), { satrec: ISS, group: 'dense' }); + } + createCatalog({ + state, + services: {}, + parts: {}, + source: {}, + })._propagateDenseChunk(worldStepMs); + return [...state._catalog.values()].filter((sat) => sat.orbitSample).length; + }; + // Real time: the set over DENSE_REFRESH_FRAMES frames. + assert.equal(sampled(3000, 16), Math.ceil(3000 / DENSE_REFRESH_FRAMES)); + // A tenth of the horizon a frame: a tenth of the set. + assert.equal(sampled(3000, ORBIT_SAMPLE_HORIZON_MS / 10), 300); + // A seek, or the first frame: as many as the cap allows. + assert.equal(sampled(3000, Number.NaN), DENSE_SAMPLES_PER_FRAME_MAX); + assert.equal(sampled(1000, -ORBIT_SAMPLE_HORIZON_MS * 5), 1000); +}); diff --git a/src/layers/satellites/rendering.js b/src/layers/satellites/rendering.js index 177884b48..7240db460 100644 --- a/src/layers/satellites/rendering.js +++ b/src/layers/satellites/rendering.js @@ -1,12 +1,18 @@ import * as Cesium from 'cesium'; import { gstime } from 'satellite.js'; +import { reckonEarthFixed, sampleOrbit } from './motion.js'; import { ISS_NORAD, ORBIT_REBAKE_MS, + ORBIT_RECKON_LIMIT_MS, + ORBIT_SAMPLE_HORIZON_MS, POSITION_UPDATE_MS, RING_ROTATION_MS, } from './policy.js'; +/** Scratch for a point's reckoned position. */ +const _reckoned = new Cesium.Cartesian3(); + export function createRendering({ state: layerState, services, @@ -158,40 +164,73 @@ export function createRendering({ } /** - * Propagate all CORE satellite positions and update point primitives. - * (About 1,300 core satellites: ~840 measured at ≈ 1.6 ms/pass, so ≈ 2.5 ms, - * fine at the 1s/200ms cadence.) Dense extras are - * excluded: they refresh on the round-robin budget in _propagateDenseChunk. + * Take a fresh SGP4 sample of every CORE satellite (motion.js); the points + * move from these each frame in _reckonPoints. (About 1,300 core + * satellites: ~840 measured at ≈ 1.6 ms/pass, so ≈ 2.5 ms, fine at the + * 1s/200ms cadence.) Dense extras are excluded: they are sampled on the + * round-robin budget in _propagateDenseChunk. + * @returns {number} How many satellites were sampled. */ function _propagateAll() { - const now = new Date(layerState.now()); + const nowMs = layerState.now(); let updated = 0; - for (const [noradId, sat] of layerState._catalog) { + for (const sat of layerState._catalog.values()) { if (sat.group === 'dense') continue; - const pos = parts.orbits.propagatePosition(sat.satrec, now); - if (!pos) continue; - - const cartesian = Cesium.Cartesian3.fromDegrees( - pos.longitude, - pos.latitude, - pos.altitude, - ); - const point = layerState._points.get(noradId); - if (point) { - point.position = cartesian; - updated++; - } + if (_sample(sat, nowMs)) updated++; } return updated; } + /** + * Sample one satellite's orbit at `atMs` into its reused sample. + * @returns {boolean} Whether SGP4 had a state for that time. + */ + + function _sample(sat, atMs) { + const sample = sampleOrbit(sat.satrec, atMs, sat.orbitSample); + if (!sample) return false; + sat.orbitSample = sample; + return true; + } + + /** + * Move every shown point to where its satellite is at the world time, + * reckoned from its last sample, so points glide every frame between + * samples instead of stepping once a second. A core sample more than + * ORBIT_SAMPLE_HORIZON_MS from the world time (time playing fast, or a + * seek) is taken again first; dense extras are resampled by their own + * round-robin. A hidden point is moved when it is shown again, and the + * tracked satellite is placed by its per-frame path. + * @param {number} nowMs World time, epoch ms. + */ + + function _reckonPoints(nowMs) { + const gmst = gstime(new Date(nowMs)); + for (const [noradId, point] of layerState._points) { + if (!point.show || noradId === layerState._trackedNorad) continue; + const sat = layerState._catalog.get(noradId); + if (!sat || sat.reckonedAtMs === nowMs) continue; + let sample = sat.orbitSample; + if ( + sat.group !== 'dense' && + (!sample || Math.abs(nowMs - sample[0]) > ORBIT_SAMPLE_HORIZON_MS) + ) + sample = _sample(sat, nowMs) ? sat.orbitSample : null; + if (!sample || Math.abs(nowMs - sample[0]) > ORBIT_RECKON_LIMIT_MS) + continue; + point.position = reckonEarthFixed(sample, nowMs, gmst, _reckoned); // setter clones + sat.reckonedAtMs = nowMs; + } + } + /** * Shared scene.preRender tick (single definition for init + enable): - * - core fleet propagation at 200ms-tracked / 1s-idle cadence, - * - dense extras on a per-frame round-robin budget, + * - core fleet SGP4 samples at 200ms-tracked / 1s-idle cadence, + * - dense extras sampled on a per-frame round-robin budget, + * - every point reckoned from its sample each frame (motion.js), * - tracked satellite's point primitive per frame (WS-D2), * - orbit ring GMST re-alignment every ~1s (WS-D1). */ @@ -213,7 +252,12 @@ export function createRendering({ layerState._lastPropagation = now; } - if (layerState._params.showPoints) parts.catalog._propagateDenseChunk(); + if (layerState._params.showPoints) { + const worldMs = layerState.now(); + parts.catalog._propagateDenseChunk(worldMs - layerState._lastReckonMs); + layerState._lastReckonMs = worldMs; + _reckonPoints(worldMs); + } // Keep the tracked dot on the per-frame epoch shared with label + camera — // runs after _propagateAll so the per-frame sample wins over the 200ms one. @@ -339,6 +383,7 @@ export function createRendering({ _updateOrbitPathRotations, _hideOrbitPath, _propagateAll, + _reckonPoints, _preRenderTick, _updatePointFocus, applySatellitePointFocusDeemphasis, diff --git a/src/layers/satellites/state.js b/src/layers/satellites/state.js index 73f5c79c9..1d6ce5bc5 100644 --- a/src/layers/satellites/state.js +++ b/src/layers/satellites/state.js @@ -64,6 +64,10 @@ export function createState({ services }) { state._lastPropagation = 0; + // The world time of the last frame that reckoned the points (motion.js), + // NaN before the first. + state._lastReckonMs = NaN; + state._lastRingRotation = 0; state._lastFocusUpdate = 0; diff --git a/src/layers/satellites/tracking.js b/src/layers/satellites/tracking.js index 8cfaf3041..2af574979 100644 --- a/src/layers/satellites/tracking.js +++ b/src/layers/satellites/tracking.js @@ -429,7 +429,7 @@ export function createTracking({ state: layerState, services, parts, source }) { // Tracked entity position propagates per evaluation through the per-frame // cache (WS-D2) — dot, host readout, and camera share one SGP4 epoch per frame. - // Falls back to the point primitive's 1s-throttled position if SGP4 fails. + // Falls back to the point primitive's reckoned position if SGP4 fails. const positionProperty = new Cesium.CallbackProperty(() => { const pos = _getTrackedFramePosition(); return pos ? layerState._trackedFrameCartesian : point.position; From 57bacd98a803ca756b13af0c6aab729889746152 Mon Sep 17 00:00:00 2001 From: Sameh Khamis Date: Sat, 14 Nov 2026 23:18:57 -0800 Subject: [PATCH 02/13] Move vessels every frame and ask for frames as they move Vessels between two fixes, and live vessels a host placement places, were redrawn at most every 250 ms, and a frame was asked for only once a second. With nothing else asking for frames the scene drew vessels at about 1 to 2 fps live, and none at all while the world clock played at 1x. They are now redrawn every frame the scene draws, moved in place without new allocations. After each pass the layer works out how far the fastest drawn vessel moved on screen and asks for the next frame for when it will have moved another half pixel, at least once a second while any drawn vessel moves. A vessel crossing the view close up therefore glides, and one far away lets the scene idle. A frame already asked for later is brought forward when a vessel speeds up. --- docs/CURRENT-STATE.md | 10 +- src/layers/vessels/renderGovernor.test.mjs | 59 ++++++++- src/layers/vessels/rendering.js | 146 +++++++++++++++------ 3 files changed, 169 insertions(+), 46 deletions(-) diff --git a/docs/CURRENT-STATE.md b/docs/CURRENT-STATE.md index 2ba3165f0..5f4635cfb 100644 --- a/docs/CURRENT-STATE.md +++ b/docs/CURRENT-STATE.md @@ -380,9 +380,10 @@ in view while their placed position changes; one it holds still lets the render loop idle and is asked again each second, moving on once its placement does. A placed transit vehicle is drawn at its placed point, and a placed train where it is placed rather than on its bound railway line. Live vessels -a provider places move on between refreshes: redrawn in place at most every -250 ms, with a frame asked for each second while the provider places any -drawn vessel, and none once the layer is off. +a provider places move on between refreshes: redrawn in place every frame, +with the next frame asked for as soon as the fastest drawn vessel will have +moved half a pixel on screen, at least once a second while the provider places +any drawn vessel, and none once the layer is off. Application catalog composition accepts an optional `streetLevelProviders` list. An explicit list replaces the default Mapillary provider; an empty list removes @@ -1999,7 +2000,8 @@ 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. Records, absences and the Layers panel's age +circle, never past the newer one, redrawn every frame with frames asked for +as for placed live vessels. 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/layers/vessels/renderGovernor.test.mjs b/src/layers/vessels/renderGovernor.test.mjs index a1f6ec93c..128e1ce16 100644 --- a/src/layers/vessels/renderGovernor.test.mjs +++ b/src/layers/vessels/renderGovernor.test.mjs @@ -3,6 +3,7 @@ import assert from 'node:assert/strict'; import { createVesselLayer } from './index.js'; import { VISIBILITY_UPDATE_MS } from './policy.js'; import { layerPlacement } from '../../data/placementProvider.js'; +import * as Cesium from 'cesium'; // Vessels move only when a poll lands, so the layer must let the scene idle: // it asks for frames for forced passes and one trailing frame after the camera @@ -75,7 +76,16 @@ function setup({ placement = null } = {}) { } }; const frame = () => layer.testing._runVisibilityPassForTest(); - return { layer, camera, requests, holds, timers, advance, frame }; + return { + layer, + camera, + requests, + holds, + timers, + advance, + frame, + now: () => clock, + }; } test('a parked camera schedules no frames after the cadence pass', () => { @@ -196,3 +206,50 @@ test('a placement that places nothing asks for no frames; one that places a draw advance(1_000); assert.deepEqual(requests, ['ais-vessels-placement']); }); + +test('a vessel moving visibly asks for its next frame as soon as it moves half a pixel; a slow one once a second', (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; + }); + let spot = { lat: 51.93, lon: 4.05 }; + const { layer, camera, timers, advance, now } = setup({ + placement: { layer: () => ({ place: () => spot }) }, + }); + // 20 km above the vessel, in a 1,000 px tall view about 57° tall. + 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, + billboard: { show: true, position: null }, + }; + layer.testing._setVesselStateForTest({ + viewer: { camera, scene: {}, canvas: { clientHeight: 1000 } }, + records: [record], + }); + layer.testing._prepareVesselVisualForTest(record); + // How long after a pass the next frame is asked for, once the vessel moved + // `dLat` in the 16 ms since the pass before. + const waitAfterStep = (dLat) => { + layer.testing._runPlacementPassForTest(); + advance(1_000); // whatever frame that asked for comes and goes + assert.equal(timers.size, 0); + mono += 16; + spot = { lat: spot.lat + dLat, lon: spot.lon }; + layer.testing._runPlacementPassForTest(); + assert.equal(timers.size, 1); + const [timer] = [...timers.values()]; + return timer.at - now(); + }; + // About 11 m in a frame, 20 km away: over half a pixel, so the next frame + // is asked for within the frame. + assert.ok(waitAfterStep(0.0001) <= 16); + // About 1 cm in a frame: half a pixel takes seconds, so once a second. + assert.equal(waitAfterStep(0.0000001), 1000); +}); diff --git a/src/layers/vessels/rendering.js b/src/layers/vessels/rendering.js index dcb85e82f..7dba03e11 100644 --- a/src/layers/vessels/rendering.js +++ b/src/layers/vessels/rendering.js @@ -31,14 +31,19 @@ import { import { createFleetModelLayer } from '../../data/fleetModelInstances.js'; import { isAidToNavigation } from '../../data/vesselTypes.js'; -/** How often vessels move on as the world clock plays (wall ms). */ -const FOLLOW_POSITION_MS = 250; -/** A frame is asked for this often while a placement moves live vessels. */ +/** 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 + * when it does not. */ +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 the vessels near enough for a model are gathered again (wall ms). */ const MODEL_CANDIDATES_MS = 500; +/** Scratch for where a moved vessel was drawn. */ +const _movedFrom = new Cesium.Cartesian3(); + export function createRendering({ vesselState, services, @@ -442,62 +447,121 @@ export function createRendering({ }); } - // As the world clock plays, vessels between two fixes move on along them. - let followedAtWallMs = -Infinity; + // As the world clock plays, vessels between two fixes move on along them, + // every frame. let followedAtMs = null; function followClockPositions() { - const wallMs = performance.now(); - if (wallMs - followedAtWallMs < FOLLOW_POSITION_MS) return; - followedAtWallMs = wallMs; const atMs = vesselState.worldNow(); if (atMs === followedAtMs) return; followedAtMs = atMs; + const motion = startMotionPass(); for (const record of state.records.all) { if (!record.motion) continue; - const visual = prepareRecordVisual(record); + let visual = visualRecords.get(record); + if (visual?.position) { + const { lat, lon } = vesselPositionAt(record, atMs); + moveDrawnVisual(visual, lat, lon, motion); + } else visual = prepareRecordVisual(record); if (visual.billboard) visual.billboard.position = visual.position; } + askMotionFrame(motion); } // Live with a host-supplied placement, vessels move on between refreshes: - // drawn where it places them at most every FOLLOW_POSITION_MS, with a frame - // asked for every PLACEMENT_FRAME_MS while it places any drawn vessel, so - // they move while the scene idles. - let placedAtWallMs = -Infinity; - let placing = false; - let placementFrameTimer = null; + // drawn where it places them every frame, with the next frame asked for + // as soon as a drawn vessel would move visibly, so they move while the + // scene idles. function followPlacements() { - const wallMs = performance.now(); - if (wallMs - placedAtWallMs >= FOLLOW_POSITION_MS) { - placedAtWallMs = wallMs; - placing = false; - const nowMs = vesselState._aisRuntime.now(); - // Drawn vessels only, as a sprite or a model: a hidden one is placed - // again when it is drawn. - for (const record of state.records.all) { - const visual = visualRecords.get(record); - if (!visual?.position) continue; - if (!visual.billboard?.show && !visual.modelOwnsVisual) continue; - const placed = services.placement.place(record.id, nowMs); - if (placed) placing = true; - const { lat, lon } = placed ?? record; - if (lat === visual.drawnLat && lon === visual.drawnLon) continue; - moveRecordVisual(visual, lat, lon); - if (visual.billboard) visual.billboard.position = visual.position; - } + const nowMs = vesselState._aisRuntime.now(); + const motion = startMotionPass(); + // Drawn vessels only, as a sprite or a model: a hidden one is placed + // again when it is drawn. + for (const record of state.records.all) { + const visual = visualRecords.get(record); + if (!visual?.position) continue; + if (!visual.billboard?.show && !visual.modelOwnsVisual) continue; + const placed = services.placement.place(record.id, nowMs); + if (placed) motion.moving = true; + const { lat, lon } = placed ?? record; + if (lat === visual.drawnLat && lon === visual.drawnLon) continue; + moveDrawnVisual(visual, lat, lon, motion); + if (visual.billboard) visual.billboard.position = visual.position; } - if (placing && placementFrameTimer === null) - placementFrameTimer = vesselState._aisRuntime.setTimeout(() => { - placementFrameTimer = null; - if (state.feed.enabled && !followsClock(vesselState)) - governorRequestRender('ais-vessels-placement'); - }, PLACEMENT_FRAME_MS); + askMotionFrame(motion); + } + + // One pass of moving vessels: whether any drawn vessel is moving, the + // largest angle one moved through as seen from the camera (radians), and + // the wall time since the pass before. + let motionPassWallMs = null; + const motionPass = { camera: null, sinceMs: 0, moving: false, angle: 0 }; + function startMotionPass() { + const wallMs = performance.now(); + motionPass.camera = state.viewer?.camera ?? null; + motionPass.sinceMs = + motionPassWallMs === null ? 0 : wallMs - motionPassWallMs; + motionPass.moving = false; + motionPass.angle = 0; + motionPassWallMs = wallMs; + return motionPass; + } + + /** Move a drawn visual, noting how far it moved as seen from the camera. */ + function moveDrawnVisual(visual, lat, lon, motion) { + const from = Cesium.Cartesian3.clone(visual.position, _movedFrom); + moveRecordVisual(visual, lat, lon); + if (!visual.billboard?.show && !visual.modelOwnsVisual) return; + motion.moving = true; + const eye = motion.camera?.positionWC; + if (!eye) return; + const distance = Cesium.Cartesian3.distance(eye, from); + if (distance > 0) + motion.angle = Math.max( + motion.angle, + Cesium.Cartesian3.distance(from, visual.position) / distance, + ); + } + + // The timer for the next vessel frame while one is asked for, and when it + // is due (the AIS runtime's clock). + let placementFrameTimer = null; + let placementFrameDueMs = 0; + /** + * While a drawn vessel moves, ask for the next frame when the fastest one + * will have moved VESSEL_STEP_PX on screen at the speed this pass saw, and + * at most PLACEMENT_FRAME_MS away. + */ + function askMotionFrame(motion) { + if (!motion.moving) return; + let waitMs = PLACEMENT_FRAME_MS; + const canvasHeight = state.viewer?.canvas?.clientHeight; + const fovy = motion.camera?.frustum?.fovy; + if ( + canvasHeight > 0 && + fovy > 0 && + motion.angle > 0 && + motion.sinceMs > 0 + ) { + const movedPx = (motion.angle * canvasHeight) / (2 * Math.tan(fovy / 2)); + waitMs = Math.min(waitMs, (VESSEL_STEP_PX * motion.sinceMs) / movedPx); + } + // A frame already asked for no later than this one stands. + const runtime = vesselState._aisRuntime; + const dueMs = runtime.now() + waitMs; + if (placementFrameTimer !== null) { + if (placementFrameDueMs <= dueMs) return; + runtime.clearTimeout(placementFrameTimer); + } + placementFrameDueMs = dueMs; + placementFrameTimer = runtime.setTimeout(() => { + placementFrameTimer = null; + if (state.feed.enabled) governorRequestRender('ais-vessels-placement'); + }, waitMs); } /** Stop asking for placement frames (the layer turned off or went away). */ function cancelPlacementFrame() { - placedAtWallMs = -Infinity; - placing = false; + motionPassWallMs = null; if (placementFrameTimer === null) return; vesselState._aisRuntime.clearTimeout(placementFrameTimer); placementFrameTimer = null; From e4afde3317a9a8d58e76787ca9ffee267b24a027 Mon Sep 17 00:00:00 2001 From: Sameh Khamis Date: Sat, 14 Nov 2026 23:19:26 -0800 Subject: [PATCH 03/13] Add the changelog fragment for #1746 --- changelog.d/1746-satellites-every-frame.md | 5 +++++ 1 file changed, 5 insertions(+) create mode 100644 changelog.d/1746-satellites-every-frame.md diff --git a/changelog.d/1746-satellites-every-frame.md b/changelog.d/1746-satellites-every-frame.md new file mode 100644 index 000000000..deb52ae3a --- /dev/null +++ b/changelog.d/1746-satellites-every-frame.md @@ -0,0 +1,5 @@ +- Move satellites every frame. Points were propagated once a second and held + still in between, so at 1 min/s they jumped about 45 px a second; each now + glides from its last SGP4 sample (position, velocity, gravity and its rate + of change) to the world time, resampled every second and whenever time + moves 30 s from it, within about 10 m of SGP4 (Sameh Khamis, #1746). From 7bea88b395b1a606c761b25bb0c9586cf748cdbc Mon Sep 17 00:00:00 2001 From: Sameh Khamis Date: Sat, 14 Nov 2026 23:19:27 -0800 Subject: [PATCH 04/13] Add the changelog fragment for #1747 --- changelog.d/1747-vessels-every-frame.md | 5 +++++ 1 file changed, 5 insertions(+) create mode 100644 changelog.d/1747-vessels-every-frame.md diff --git a/changelog.d/1747-vessels-every-frame.md b/changelog.d/1747-vessels-every-frame.md new file mode 100644 index 000000000..d0b452c47 --- /dev/null +++ b/changelog.d/1747-vessels-every-frame.md @@ -0,0 +1,5 @@ +- Move vessels every frame. Vessels between fixes, and live vessels a host + placement places, were redrawn at most every 250 ms with a frame asked for + once a second; they are now redrawn every frame, and the next frame is asked + for once the fastest drawn vessel will have moved half a pixel on screen + (Sameh Khamis, #1747). From 52695daf5c8dd97162eb58c0ddc0d2bfecc23a68 Mon Sep 17 00:00:00 2001 From: Sameh Khamis Date: Sat, 14 Nov 2026 23:30:38 -0800 Subject: [PATCH 05/13] fix(vessels): world-clock motion moves only drawn vessels, once per world time Vessels out of view move on every 250 ms so one coming into view is current; vessels at the end of their fixes ask for no frames; nothing moves while the layer is off; 2D views judge the half-pixel step across the view's width; a re-floor redraws vessels where they are on the next pass. --- docs/CURRENT-STATE.md | 2 +- src/layers/vessels/renderGovernor.test.mjs | 108 ++++++++++++++++++++- src/layers/vessels/rendering.js | 101 ++++++++++++------- src/layers/vessels/testing.js | 8 ++ src/layers/vessels/tracking.js | 9 +- 5 files changed, 183 insertions(+), 45 deletions(-) diff --git a/docs/CURRENT-STATE.md b/docs/CURRENT-STATE.md index 5f4635cfb..ed33813aa 100644 --- a/docs/CURRENT-STATE.md +++ b/docs/CURRENT-STATE.md @@ -2001,7 +2001,7 @@ 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. Records, absences and the Layers panel's age +as for placed live vessels (vessels out of view move on every 250 ms). 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/layers/vessels/renderGovernor.test.mjs b/src/layers/vessels/renderGovernor.test.mjs index 128e1ce16..c5ce2e855 100644 --- a/src/layers/vessels/renderGovernor.test.mjs +++ b/src/layers/vessels/renderGovernor.test.mjs @@ -5,9 +5,9 @@ import { VISIBILITY_UPDATE_MS } from './policy.js'; import { layerPlacement } from '../../data/placementProvider.js'; import * as Cesium from 'cesium'; -// Vessels move only when a poll lands, so the layer must let the scene idle: -// it asks for frames for forced passes and one trailing frame after the camera -// stops, and never schedules a frame from a pass the camera did not cause. +// The layer must let the scene idle: it asks for frames for forced passes, +// for vessels that move, and one trailing frame after the camera stops, and +// never schedules a frame from a pass nothing caused. const noop = () => {}; @@ -252,4 +252,106 @@ test('a vessel moving visibly asks for its next frame as soon as it moves half a assert.ok(waitAfterStep(0.0001) <= 16); // About 1 cm in a frame: half a pixel takes seconds, so once a second. assert.equal(waitAfterStep(0.0000001), 1000); + // A 2D view 40 km across in 1,000 px: 11 m is over a quarter pixel, so the + // next frame comes within two frames. + camera.frustum = { left: -20_000, right: 20_000 }; + layer.testing._setVesselStateForTest({ + viewer: { camera, scene: {}, canvas: { clientWidth: 1000 } }, + records: [record], + }); + layer.testing._prepareVesselVisualForTest(record); + assert.ok(waitAfterStep(0.0001) <= 32); +}); + +test('following the clock moves drawn vessels in place each world time, prepares missing ones and leaves hidden ones be', (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, timers, advance } = setup(); + camera.positionWC = Cesium.Cartesian3.fromDegrees(4.05, 51.93, 20_000); + camera.frustum = { fovy: 1 }; + const motion = { + fromLat: 51.93, + fromLon: 4.05, + fromMs: 0, + toLat: 51.94, + toLon: 4.05, + toMs: 60_000, + }; + const vessel = (mmsi, show) => ({ + mmsi, + lat: 51.94, + lon: 4.05, + motion: { ...motion }, + billboard: { show, position: null }, + }); + const drawn = vessel('111', true); + const hidden = vessel('222', false); + const owned = vessel('333', false); + const missing = vessel('444', true); + layer.testing._setVesselStateForTest({ + viewer: { camera, scene: {}, canvas: { clientHeight: 1000 } }, + records: [drawn, hidden, owned, missing], + }); + const visuals = [drawn, hidden, owned].map((record) => + layer.testing._prepareVesselVisualForTest(record), + ); + visuals[2].modelOwnsVisual = true; + 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. + layer.testing._runClockPassForTest(10_000); + mono += 16; + layer.testing._runClockPassForTest(20_000); + assert.equal(visuals[0].position, positions[0], 'written in place'); + assert.notDeepEqual({ ...visuals[0].position }, before[0]); + assert.notDeepEqual({ ...visuals[2].position }, before[2], 'model moves'); + const hiddenAt = { ...visuals[1].position }; + 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); + mono += 250; + layer.testing._runClockPassForTest(40_000); + assert.notDeepEqual({ ...visuals[1].position }, hiddenAt); + + // The same world time again moves nothing and asks for no frame. + advance(1_000); + assert.equal(timers.size, 0); + const still = { ...visuals[0].position }; + mono += 16; + layer.testing._runClockPassForTest(40_000); + assert.deepEqual({ ...visuals[0].position }, still); + assert.equal(timers.size, 0); + + // Scrubbed back, a vessel moves back. + mono += 16; + layer.testing._runClockPassForTest(20_000); + assert.notDeepEqual({ ...visuals[0].position }, still); + + // Each vessel moves once per world time: new fixes at the same world time + // are drawn when the snapshot that brings them prepares the visual. + const backAt = { ...visuals[0].position }; + drawn.motion = { ...motion, toLat: 52 }; + mono += 16; + layer.testing._runClockPassForTest(20_000); + assert.deepEqual({ ...visuals[0].position }, backAt); + + // Past the newest fix, vessels hold still and ask for nothing. + mono += 16; + layer.testing._runClockPassForTest(70_000); + advance(1_000); + mono += 16; + layer.testing._runClockPassForTest(80_000); + assert.equal(timers.size, 0); }); diff --git a/src/layers/vessels/rendering.js b/src/layers/vessels/rendering.js index 7dba03e11..ec123cc8f 100644 --- a/src/layers/vessels/rendering.js +++ b/src/layers/vessels/rendering.js @@ -37,6 +37,9 @@ 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. */ +const HIDDEN_FOLLOW_MS = 250; /** How often the vessels near enough for a model are gathered again (wall ms). */ const MODEL_CANDIDATES_MS = 500; @@ -87,10 +90,8 @@ export function createRendering({ visual.position, new Cesium.Cartesian3(), ); - if (services.placement) { - visual.drawnLat = lat; - visual.drawnLon = lon; - } + visual.drawnLat = lat; + visual.drawnLon = lon; return visual; } @@ -429,39 +430,51 @@ export function createRendering({ modelCandidatesAtMs = -Infinity; } - // Vessels move only when a poll lands, so the layer does not hold the - // continuous render loop. Its passes run in preRender, which idle mode fires - // only for rendered frames: 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 + // 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. function installRuntime(viewer) { if (state.preRenderRemover || !viewer) return; state.preRenderRemover = viewer.scene.preRender.addEventListener(() => { - if (followsClock(vesselState)) followClockPositions(); - else if (services.placement && state.feed.enabled) followPlacements(); + if (state.feed.enabled) { + if (followsClock(vesselState)) followClockPositions(); + else if (services.placement) followPlacements(); + } updateVisibility(); if (state.feed.enabled) updateModels(); }); } - // As the world clock plays, vessels between two fixes move on along them, - // every frame. - let followedAtMs = null; + // 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; function followClockPositions() { const atMs = vesselState.worldNow(); - if (atMs === followedAtMs) return; - followedAtMs = atMs; 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) continue; let visual = visualRecords.get(record); - if (visual?.position) { + 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); - } else visual = prepareRecordVisual(record); + } if (visual.billboard) visual.billboard.position = visual.position; } askMotionFrame(motion); @@ -490,18 +503,27 @@ export function createRendering({ askMotionFrame(motion); } - // One pass of moving vessels: whether any drawn vessel is moving, the - // largest angle one moved through as seen from the camera (radians), and - // the wall time since the pass before. + // One pass of moving vessels: whether any drawn vessel is moving, how far + // the fastest moved (as an angle seen from the camera, radians, and in + // metres), the pass's wall time and the wall time since the pass before. let motionPassWallMs = null; - const motionPass = { camera: null, sinceMs: 0, moving: false, angle: 0 }; + const motionPass = { + camera: null, + wallMs: 0, + sinceMs: 0, + moving: false, + angle: 0, + metres: 0, + }; function startMotionPass() { const wallMs = performance.now(); motionPass.camera = state.viewer?.camera ?? null; + motionPass.wallMs = wallMs; motionPass.sinceMs = motionPassWallMs === null ? 0 : wallMs - motionPassWallMs; motionPass.moving = false; motionPass.angle = 0; + motionPass.metres = 0; motionPassWallMs = wallMs; return motionPass; } @@ -512,14 +534,28 @@ export function createRendering({ moveRecordVisual(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 eye = motion.camera?.positionWC; if (!eye) return; const distance = Cesium.Cartesian3.distance(eye, from); - if (distance > 0) - motion.angle = Math.max( - motion.angle, - Cesium.Cartesian3.distance(from, visual.position) / distance, + if (distance > 0) motion.angle = Math.max(motion.angle, metres / distance); + } + + /** How far the fastest drawn vessel moved on screen in a pass (pixels): + * through the perspective view's angle, or across the 2D view's width. */ + function movedPixels(motion) { + const canvas = state.viewer?.canvas; + const frustum = motion.camera?.frustum; + if (!canvas || !frustum) return 0; + if (frustum.fovy > 0 && canvas.clientHeight > 0) + return ( + (motion.angle * canvas.clientHeight) / (2 * Math.tan(frustum.fovy / 2)) ); + const width = frustum.right - frustum.left; + if (!(frustum.fovy > 0) && width > 0 && canvas.clientWidth > 0) + return (motion.metres * canvas.clientWidth) / width; + return 0; } // The timer for the next vessel frame while one is asked for, and when it @@ -534,17 +570,9 @@ export function createRendering({ function askMotionFrame(motion) { if (!motion.moving) return; let waitMs = PLACEMENT_FRAME_MS; - const canvasHeight = state.viewer?.canvas?.clientHeight; - const fovy = motion.camera?.frustum?.fovy; - if ( - canvasHeight > 0 && - fovy > 0 && - motion.angle > 0 && - motion.sinceMs > 0 - ) { - const movedPx = (motion.angle * canvasHeight) / (2 * Math.tan(fovy / 2)); + 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. const runtime = vesselState._aisRuntime; const dueMs = runtime.now() + waitMs; @@ -943,6 +971,7 @@ export function createRendering({ cancelTrailingVisibilityPass, cancelPlacementFrame, followPlacements, + followClockPositions, applyVesselFocusDeemphasis, makeOccluder, isVisible, diff --git a/src/layers/vessels/testing.js b/src/layers/vessels/testing.js index 6c8355bae..197d41b5e 100644 --- a/src/layers/vessels/testing.js +++ b/src/layers/vessels/testing.js @@ -174,6 +174,13 @@ export function createTesting({ components.rendering.followPlacements(); } + /** Run one world-clock pass at world time `atMs`. Test-only seam. */ + + function _runClockPassForTest(atMs) { + vesselState.worldNow = () => atMs; + components.rendering.followClockPositions(); + } + /** True while a trailing visibility frame is scheduled. Test-only seam. */ function _hasTrailingVisibilityPassForTest() { @@ -208,6 +215,7 @@ export function createTesting({ _runVisibilityPassForTest, _prepareVesselVisualForTest, _runPlacementPassForTest, + _runClockPassForTest, _hasTrailingVisibilityPassForTest, }; } diff --git a/src/layers/vessels/tracking.js b/src/layers/vessels/tracking.js index 5e3906557..4f2c127bf 100644 --- a/src/layers/vessels/tracking.js +++ b/src/layers/vessels/tracking.js @@ -73,11 +73,10 @@ export function createTracking({ heightM, ); if (visual.billboard) visual.billboard.position = visual.position; - // A placed vessel is drawn again at its placement on the next pass. - if (services.placement) { - visual.drawnLat = NaN; - visual.drawnLon = NaN; - } + // A moving vessel is drawn again where it is on the next pass. + visual.drawnLat = NaN; + visual.drawnLon = NaN; + visual.followedAtMs = undefined; } } From 97bce938c4ab31f0a12969d77920c13f63e3d357 Mon Sep 17 00:00:00 2001 From: Sameh Khamis Date: Sun, 15 Nov 2026 09:14:33 -0800 Subject: [PATCH 06/13] Global clouds drawn from a feed's tiles to the level it names A weather feed that supplies its own tiles may name, per product, the deepest level of the geographic tiling its tiles hold detail at (frameMaximumLevel, 0-12). Global infrared is then drawn from those tiles to that level, each given the regional infrared display transfer, rather than from one 2048x1024 image cut to level 3. Other tiled products take the named level in place of 6. A feed naming no usable level keeps the layer's own detail. --- docs/CURRENT-STATE.md | 10 +- src/layers/weather/rendering.js | 45 ++++++++- src/layers/weather/source.js | 12 ++- src/layers/weather/source.test.mjs | 7 ++ src/layers/weather/weather.test.mjs | 139 ++++++++++++++++++++++++++++ 5 files changed, 205 insertions(+), 8 deletions(-) diff --git a/docs/CURRENT-STATE.md b/docs/CURRENT-STATE.md index e03fb3d45..194b10ebf 100644 --- a/docs/CURRENT-STATE.md +++ b/docs/CURRENT-STATE.md @@ -1020,7 +1020,9 @@ other map content draws over the shells, and shells are not pickable. A map-source change tears down one renderer and restages the shown observation on the other. A map without an imagery host pauses history while metadata refresh continues, then resumes when a host returns. -Globe tiled products use 256 px tiles to maximum level 6. The tile proxy accepts +Globe tiled products use 256 px tiles to maximum level 6, or to the level a +feed that supplies its own tiles names for the product (`frameMaximumLevel`, +0–12; any other answer keeps 6). The tile proxy accepts size=256 (default), 512 or 1024 and keys cached bytes by size, retaining the 24-hour immutable response and eight upstream slots. The image proxy serves every product as one whole-extent PNG at its advertised bounds, up to 4096×2048 for @@ -1062,7 +1064,11 @@ open latest. Global infrared fetches one capped 4 MiB, 2048×1024 mosaic per frame and decodes and processes it before staging. Globe hosts crop that canvas into 256 px tiles to maximum level 3 on a geographic 2×1 root grid bounded to the manifest extent, -avoiding request-dependent contrast seams. +avoiding request-dependent contrast seams. On globe hosts, a feed that supplies +tiles and names a level for global infrared instead has it drawn from its tiles +to that level, +each tile given the same display transfer as regional infrared tiles, and no +mosaic is read. On globe hosts, regional infrared retains network tiles and processes each decoded tile once; shells process each whole frame once. Exact-time tile and image responses are immutable for 24 hours; manifests and diff --git a/src/layers/weather/rendering.js b/src/layers/weather/rendering.js index d7c2527ab..89dcd778d 100644 --- a/src/layers/weather/rendering.js +++ b/src/layers/weather/rendering.js @@ -13,8 +13,13 @@ import { acquireInfraredMosaic, processInfraredImage, } from './infraredImage.js'; -// Bounded display detail for the hourly, approximately 3 km global product. +// Bounded display detail for the hourly, approximately 3 km global product +// when it is drawn from one 2048 × 1024 mosaic. const GLOBAL_TILE_MAXIMUM_LEVEL = 3; +// Detail of the tiled products when the feed does not name its own. +const TILE_MAXIMUM_LEVEL = 6; +// The deepest level a feed may name: about 150 m a pixel. +const SUPPLIED_MAXIMUM_LEVEL_LIMIT = 12; // Six decoded 2048×1024 canvases (8 MiB each) bound the cache below 50 MiB. const MAX_MOSAICS = 6; const MAX_PREFETCH_TILES = 8; @@ -45,10 +50,33 @@ function createGlobeRendering({ let prefetchJob = null; let prefetchedKey = null; + /** The deepest level the feed's own tiles of `product` go to, or null. */ + function suppliedLevel(product) { + if (!frameSource?.getTile) return null; + let level = null; + try { + level = frameSource.maximumLevel?.(product) ?? null; + } catch { + return null; + } + return Number.isInteger(level) && + level >= 0 && + level <= SUPPLIED_MAXIMUM_LEVEL_LIMIT + ? level + : null; + } + + /** Global clouds come from one mosaic unless the feed tiles them itself. */ + function fromMosaic(product) { + return product === 'clouds' && suppliedLevel(product) === null; + } + function profile(product) { return { tileSize: 256, - maximumLevel: product === 'clouds' ? GLOBAL_TILE_MAXIMUM_LEVEL : 6, + maximumLevel: + suppliedLevel(product) ?? + (product === 'clouds' ? GLOBAL_TILE_MAXIMUM_LEVEL : TILE_MAXIMUM_LEVEL), }; } @@ -252,7 +280,7 @@ function createGlobeRendering({ !snapshot.times.includes(time) ) return false; - const global = snapshot.product === 'clouds'; + const global = fromMosaic(snapshot.product); const tiles = global ? [] : prefetchTiles(snapshot); const supplied = !global && Boolean(frameSource?.getTile); const urls = global || supplied ? [] : tileUrls(snapshot, time, tiles); @@ -315,7 +343,7 @@ function createGlobeRendering({ lastError = null; const { west, south, east, north } = snapshot.bounds; const rectangle = cesium.Rectangle.fromDegrees(west, south, east, north); - const global = snapshot.product === 'clouds'; + const global = fromMosaic(snapshot.product); const frame = { snapshot, creditSnapshot, @@ -484,7 +512,14 @@ function createGlobeRendering({ .then((image) => { // Cesium decodes tiles as ImageBitmaps already flipped, since WebGL // ignores UNPACK_FLIP_Y for them; a canvas upload flips again. - if (!frame.closed && snapshot.product === 'clouds-regional') + // Infrared tiles get the display transfer the mosaic already + // carries. + if ( + !frame.closed && + !global && + (snapshot.product === 'clouds-regional' || + snapshot.product === 'clouds') + ) image = processInfraredImage(image, infrared, createCanvas, { flipY: typeof ImageBitmap !== 'undefined' && diff --git a/src/layers/weather/source.js b/src/layers/weather/source.js index 276e9bf2e..465c89312 100644 --- a/src/layers/weather/source.js +++ b/src/layers/weather/source.js @@ -121,6 +121,10 @@ export function weatherTileUrl(product, time, { size } = {}) { * degrees) a detail window of it. `getFrameTile` returns one `size`-pixel tile * of the geographic tiling scheme, or null for a transparent tile. Rows run * top-down (north first), as an image does. Both honour `signal`. + * `frameMaximumLevel` names the deepest level of that scheme the feed's tiles + * of a product hold detail at (0–12), or null for the layer's own: with it, + * global clouds are drawn from the feed's tiles to that level instead of from + * one 2048 × 1024 image. * @typedef {object} WeatherFrameFeed * @property {(request: { product: string, time: string, * size: { width: number, height: number }, @@ -129,19 +133,25 @@ export function weatherTileUrl(product, time, { size } = {}) { * @property {(request: { product: string, time: string, z: number, x: number, * y: number, size: number, signal: AbortSignal }) * => Promise} [getFrameTile] + * @property {(product: string) => number | null} [frameMaximumLevel] */ /** * The frame source a feed provides, or null when it has neither method. A * missing method is left undefined, so that path keeps the routes. * @param {WeatherFrameFeed | undefined} feed - * @returns {{ getImage?: Function, getTile?: Function } | null} + * @returns {{ getImage?: Function, getTile?: Function, + * maximumLevel?: Function } | null} */ export function weatherFrameSource(feed) { const image = typeof feed?.getFrameImage === 'function'; const tile = typeof feed?.getFrameTile === 'function'; if (!image && !tile) return null; + const level = typeof feed?.frameMaximumLevel === 'function'; return { + maximumLevel: level + ? (product) => feed.frameMaximumLevel(product) + : undefined, getImage: image ? ({ product, time, size, bbox = null, signal }) => feed.getFrameImage({ product, time, size, bbox, signal }) diff --git a/src/layers/weather/source.test.mjs b/src/layers/weather/source.test.mjs index ff69fce2f..81b37c6fa 100644 --- a/src/layers/weather/source.test.mjs +++ b/src/layers/weather/source.test.mjs @@ -257,6 +257,13 @@ test('a frame source forwards exactly the documented requests to its feed', asyn assert.equal(imagesOnly.getTile, undefined, 'tiles keep the tile route'); const tilesOnly = weatherFrameSource({ getFrameTile: feed.getFrameTile }); assert.equal(tilesOnly.getImage, undefined, 'images keep the image route'); + assert.equal(tilesOnly.maximumLevel, undefined); + const leveled = weatherFrameSource({ + getFrameTile: feed.getFrameTile, + frameMaximumLevel: (product) => (product === 'clouds' ? 6 : null), + }); + assert.equal(leveled.maximumLevel('clouds'), 6); + assert.equal(leveled.maximumLevel('radar'), null); }); test('supplied pixels report their drawn size, draw at the origin and close once', (t) => { diff --git a/src/layers/weather/weather.test.mjs b/src/layers/weather/weather.test.mjs index 309b51165..2b9dba5d8 100644 --- a/src/layers/weather/weather.test.mjs +++ b/src/layers/weather/weather.test.mjs @@ -2694,6 +2694,99 @@ test('a frame source supplies regional tiles in place of the tile route, through h.rendering.clear(); }); +test('a frame source that names its tile detail draws global clouds from its tiles to that level', async () => { + let now = 0; + const requests = []; + const h = renderingHarness({ + now: () => now, + fetchImpl: () => assert.fail('supplied clouds are not fetched'), + frameSource: { + getImage: () => assert.fail('no mosaic when the feed tiles clouds'), + getTile: async (request) => { + requests.push(request); + return suppliedTile(); + }, + maximumLevel: (product) => (product === 'clouds' ? 6 : 8), + }, + }); + h.viewer.scene.globe.tilesLoaded = false; + const loaded = h.rendering.setFrame(globalSnapshot, times[0]); + assert.equal(h.providers.length, 1); + const [provider] = h.providers; + assert.equal(provider.options, undefined, 'no URL template provider'); + assert.equal(provider.maximumLevel, 6); + await provider.requestImage(5, 3, 4, {}); + assert.deepEqual( + [requests[0].product, requests[0].z, requests[0].x, requests[0].y], + ['clouds', 4, 5, 3], + ); + now = 500; + h.settle(); + assert.equal(await loaded, true); + h.rendering.clear(); + + // Radar takes the level the feed names for it. + const radar = renderingHarness({ + frameSource: { + getTile: async () => suppliedTile(), + maximumLevel: () => 8, + }, + }); + radar.rendering.setFrame(snapshot, times[0]); + assert.equal(radar.providers[0].maximumLevel, 8); + radar.rendering.clear(); +}); + +test("a frame source naming no usable level keeps the layer's own detail", async () => { + for (const maximumLevel of [ + () => null, + () => 13, + () => 2.5, + () => 'deep', + () => { + throw new Error('no level'); + }, + ]) { + const h = renderingHarness({ + frameSource: { getTile: async () => suppliedTile(), maximumLevel }, + }); + h.rendering.setFrame(snapshot, times[0]); + assert.equal(h.providers[0].maximumLevel, 6); + h.rendering.clear(); + // Global clouds stay on the one image, cut to level 3. + let mosaics = 0; + const clouds = renderingHarness({ + frameSource: { + getImage: async () => { + mosaics++; + return { width: 2048, height: 1024, close() {} }; + }, + getTile: () => assert.fail('clouds are not tiled without a level'), + maximumLevel, + }, + }); + await showMosaic(clouds, times[0]); + assert.equal(mosaics, 1); + assert.equal(clouds.providers[0].maximumLevel, 3); + clouds.rendering.clear(); + } + // A level without tiles leaves global clouds on the mosaic. + let images = 0; + const h = renderingHarness({ + frameSource: { + getImage: async () => { + images++; + return suppliedTile(); + }, + maximumLevel: () => 6, + }, + }); + h.rendering.setFrame(globalSnapshot, times[0]); + await flush(); + assert.equal(images, 1); + h.rendering.clear(); +}); + test('a failed supplied tile fails the staged frame through errorEvent', async () => { const h = renderingHarness({ frameSource: { @@ -2748,6 +2841,52 @@ test('supplied regional infrared tiles are canvases, so they get the transfer wi } }); +test('global clouds tiles get the infrared transfer, and prefetch asks for tiles, not the image', async () => { + const hadBitmap = Object.hasOwn(globalThis, 'ImageBitmap'); + const previous = globalThis.ImageBitmap; + globalThis.ImageBitmap = class ImageBitmap { + width = 256; + height = 256; + close() {} + }; + try { + const requests = []; + const h = renderingHarness({ + frameSource: { + getImage: () => assert.fail('no image when the feed tiles clouds'), + getTile: async (request) => { + requests.push(request); + return new globalThis.ImageBitmap(); + }, + maximumLevel: () => 6, + }, + }); + void h.rendering.setFrame(globalSnapshot, times[0]); + const tile = await h.providers[0].requestImage(5, 3, 4, {}); + assert.equal(tile.drawnWith, null, 'drawn upright, not flipped'); + assert.ok(tile.pixels, 'the infrared transfer ran'); + h.rendering.clear(); + requests.length = 0; + const warm = renderingHarness({ + frameSource: { + getImage: () => assert.fail('no image when the feed tiles clouds'), + getTile: async (request) => { + requests.push(request); + return new globalThis.ImageBitmap(); + }, + maximumLevel: () => 6, + }, + }); + assert.equal(await warm.rendering.prefetch(globalSnapshot, times[1]), true); + assert.ok(requests.length > 0, 'prefetch asked for tiles'); + assert.ok(requests.every((request) => request.product === 'clouds')); + warm.rendering.clear(); + } finally { + if (hadBitmap) globalThis.ImageBitmap = previous; + else delete globalThis.ImageBitmap; + } +}); + test('tiled prefetch asks the frame source for the same level 0/1 tiles and releases them', async (t) => { const requests = []; const supplied = []; From dc045859f7c3b6a0e11899e064abe7ea96dcd7e3 Mon Sep 17 00:00:00 2001 From: Sameh Khamis Date: Sun, 15 Nov 2026 09:14:49 -0800 Subject: [PATCH 07/13] Changelog fragment for #1748 --- changelog.d/1748-clouds-feed-detail.md | 5 +++++ 1 file changed, 5 insertions(+) create mode 100644 changelog.d/1748-clouds-feed-detail.md diff --git a/changelog.d/1748-clouds-feed-detail.md b/changelog.d/1748-clouds-feed-detail.md new file mode 100644 index 000000000..bf4440e7d --- /dev/null +++ b/changelog.d/1748-clouds-feed-detail.md @@ -0,0 +1,5 @@ +- A weather feed that supplies its own tiles can name how deep they go for + each product (`frameMaximumLevel`). Global satellite clouds are then drawn + from those tiles to that level instead of from one 2048 × 1024 image, so + they stay sharp when zoomed in; radar and the other tiled products take the + named level too. Without it, clouds keep the single image and level 3. From 2b5fb5168401cfc03930e35766e698f9802c0565 Mon Sep 17 00:00:00 2001 From: Sameh Khamis Date: Sun, 15 Nov 2026 09:27:29 -0800 Subject: [PATCH 08/13] Contacts move back as smoothly as they move on A snapshot timeline may declare spanMs: each record of a snapshot at a time then carries its own fixes from spanMs before the time to spanMs after it. Flights, military flights and vessels following the clock are placed on those fixes, so a seek or a move back within the fixes loaded is no jump: nothing is cleared and play does not wait. The step there is asked for once and stands in for every contact; those it has keep their place. Fixes are merged across snapshots at least 20 s apart, at most 240 a contact, and a contact is not drawn more than a minute before its first fix. --- docs/CURRENT-STATE.md | 16 +- scripts/package-boundaries.json | 12 +- src/data/timelineHistory.js | 171 ++++++++++++++++ src/data/timelineHistory.test.mjs | 147 ++++++++++++++ src/layers/flights/motion.js | 30 ++- src/layers/flights/rendering.js | 10 +- src/layers/flights/snapshotRenderer.js | 169 +++++++++------- src/layers/flights/state.js | 5 + src/layers/military/motion.js | 18 +- src/layers/military/rendering.js | 10 +- src/layers/military/snapshotRenderer.js | 172 ++++++++++------- src/layers/military/state.js | 5 + src/layers/vessels/cockpitSubject.test.mjs | 5 +- src/layers/vessels/ingestion.js | 6 +- src/layers/vessels/motion.js | 56 +++++- src/layers/vessels/motion.test.mjs | 34 +++- src/layers/vessels/records.js | 25 ++- src/layers/vessels/records.test.mjs | 12 ++ src/layers/vessels/renderGovernor.test.mjs | 20 ++ src/layers/vessels/rendering.js | 42 +++- src/layers/vessels/state.js | 2 + src/layers/vessels/testing.js | 8 + src/sources/live/contract.js | 19 +- src/time/snapshotTimeline.js | 127 +++++++++++- src/time/snapshotTimeline.test.mjs | 215 ++++++++++++++++++++- src/time/timelineFixes.js | 125 ++++++++++++ src/time/timelineFixes.test.mjs | 98 ++++++++++ 27 files changed, 1377 insertions(+), 182 deletions(-) create mode 100644 src/data/timelineHistory.js create mode 100644 src/data/timelineHistory.test.mjs create mode 100644 src/time/timelineFixes.js create mode 100644 src/time/timelineFixes.test.mjs diff --git a/docs/CURRENT-STATE.md b/docs/CURRENT-STATE.md index 194b10ebf..6b4c8252f 100644 --- a/docs/CURRENT-STATE.md +++ b/docs/CURRENT-STATE.md @@ -1983,7 +1983,7 @@ layer's existing lifecycle and selection guards continue to reject late work. ### Following the world clock A source may declare a timeline: it can answer a snapshot at a given time. -`source.timeline` is `{ coverage(), stepMs, subscribe? }`, validated by +`source.timeline` is `{ coverage(), stepMs, spanMs?, subscribe? }`, validated by `readSnapshotTimeline` (`src/sources/live/contract.js`): `coverage()` returns the span `{ start, end }` in epoch ms it can answer, or null while it does not know yet; `stepMs` is the spacing of its snapshots; the optional @@ -2017,6 +2017,20 @@ the older is aborted before a newer starts. Moving the view while vessels follow area at the same time. Back at live the contacts are cleared and the layer polls at once. +A timeline may also declare `spanMs`: each record of a snapshot at a time then +carries `fixes`, `{ atMs, lat, lon, altitudeM? }` in time order, its own track +from `spanMs` before the time to `spanMs` after it +(`src/time/timelineFixes.js`). The layer places each contact on its fixes at +the clock's time, so a seek or a move back that stays within the fixes the +loaded snapshots carry is no jump: nothing is cleared, play does not wait, +and contacts move to the time smoothly. The snapshot at a step before the +newest loaded is asked for once and then stands in for every contact: it +brings back any that had left after it and drops those not there yet, while +those it has keep their place, as their fixes put them. Paused, a time nearing +the end of the fixes after the newest asks for the snapshot there. A contact is not drawn more than a minute before its first +fix, as it was not there yet. Each contact keeps at most 240 fixes, at least +20 seconds apart, and the loaded snapshot times span at most 20 minutes. + A snapshot at `atMs` describes the world as it stood then: `observedAtMs` is at or before `atMs`, no record is observed later than `atMs`, freshness and staleness are judged against `atMs`, `atMs` is echoed back, and a vessel diff --git a/scripts/package-boundaries.json b/scripts/package-boundaries.json index c275337cb..bb65b6c34 100644 --- a/scripts/package-boundaries.json +++ b/scripts/package-boundaries.json @@ -1563,6 +1563,8 @@ "src/layers/flights/records.js", "src/layers/flights/clockFollow.js", "src/time/snapshotTimeline.js", + "src/data/timelineHistory.js", + "src/time/timelineFixes.js", "src/sources/live/contract.js", "src/layers/flights/recordPolicy.js", "src/layers/flights/snapshotRenderer.js", @@ -1629,6 +1631,8 @@ "src/layers/military/ingestion.js", "src/layers/military/clockFollow.js", "src/time/snapshotTimeline.js", + "src/data/timelineHistory.js", + "src/time/timelineFixes.js", "src/sources/live/contract.js", "src/layers/military/lifecycle.js", "src/layers/military/motion.js", @@ -1715,6 +1719,7 @@ "src/layers/vessels/ingestion.js", "src/layers/vessels/motion.js", "src/time/snapshotTimeline.js", + "src/time/timelineFixes.js", "src/time/worldClock.js", "src/sources/live/contract.js", "src/layers/vessels/cameraArea.js", @@ -2892,6 +2897,8 @@ "src/layers/flights/index.js", "src/layers/flights/clockFollow.js", "src/time/snapshotTimeline.js", + "src/data/timelineHistory.js", + "src/time/timelineFixes.js", "src/layers/flights/ingestion.js", "src/layers/flights/lifecycle.js", "src/layers/flights/motion.js", @@ -4079,6 +4086,8 @@ "src/layers/flights/index.js", "src/layers/flights/clockFollow.js", "src/time/snapshotTimeline.js", + "src/data/timelineHistory.js", + "src/time/timelineFixes.js", "src/sources/live/contract.js", "src/layers/flights/ingestion.js", "src/layers/flights/lifecycle.js", @@ -4870,7 +4879,8 @@ "exports": ["./layers/vessels/records"], "modules": [ "src/layers/vessels/records.js", - "src/layers/vessels/recordPolicy.js" + "src/layers/vessels/recordPolicy.js", + "src/time/timelineFixes.js" ], "external": [] }, diff --git a/src/data/timelineHistory.js b/src/data/timelineHistory.js new file mode 100644 index 000000000..d48c99d06 --- /dev/null +++ b/src/data/timelineHistory.js @@ -0,0 +1,171 @@ +import * as Cesium from 'cesium'; +import { + mergeTimelineRuns, + readTimelineFixes, + TIMELINE_UNSEEN_MS, +} from '../time/timelineFixes.js'; + +/** Fixes nearer than this are too close to read a course between. */ +const COURSE_MIN_M = 5; +const EARTH_RADIUS_M = 6_371_000; + +/** The initial great-circle course from one fix to another (degrees from + * north), or null when they are too close to tell. */ +function courseBetween(from, to) { + const lat1 = Cesium.Math.toRadians(from.lat); + const lat2 = Cesium.Math.toRadians(to.lat); + const dLon = Cesium.Math.toRadians(to.lon - from.lon); + const dLat = lat2 - lat1; + const a = + Math.sin(dLat / 2) ** 2 + + Math.cos(lat1) * Math.cos(lat2) * Math.sin(dLon / 2) ** 2; + if (2 * EARTH_RADIUS_M * Math.asin(Math.min(1, Math.sqrt(a))) < COURSE_MIN_M) + return null; + const y = Math.sin(dLon) * Math.cos(lat2); + const x = + Math.cos(lat1) * Math.sin(lat2) - + Math.sin(lat1) * Math.cos(lat2) * Math.cos(dLon); + return (Cesium.Math.toDegrees(Math.atan2(y, x)) + 360) % 360; +} + +/** + * An aircraft's motion history with the fixes its record carries at a time + * (`observation.fixes`, see src/time/timelineFixes.js) merged in, so the + * layer places it on its own track at any time they span; null when the + * record carries none. Each fix is drawn at the record's render height, + * moved by the fix's own barometric change from the record's, and heads + * where its track goes next (the last, where it came from). Entries are + * marked `timeline`. + * @param {object[]|undefined} history The contact's history entries. + * @param {object} observation The record, with `fixes` and `baroAltitudeM`. + * @param {{renderAltitudeM: number, renderAltitudeInvented?: boolean}} meta + * @param {number|null} velocity The record's ground speed (m/s). + * @param {number} centreMs The snapshot's time: the fixes kept are nearest it. + * @returns {object[]|null} + */ +export function mergeAircraftTimelineFixes( + history, + observation, + meta, + velocity, + centreMs, +) { + const fixes = readTimelineFixes(observation?.fixes); + if (!fixes) return null; + const baroM = Number.isFinite(observation.baroAltitudeM) + ? observation.baroAltitudeM + : null; + const entries = fixes.map((fix, index) => { + const course = + index + 1 < fixes.length + ? courseBetween(fix, fixes[index + 1]) + : courseBetween(fixes[index - 1], fix); + return { + time: Cesium.JulianDate.fromDate(new Date(fix.atMs)), + epochMs: fix.atMs, + position: Cesium.Cartesian3.fromDegrees( + fix.lon, + fix.lat, + baroM !== null && fix.altitudeM !== null + ? meta.renderAltitudeM + (fix.altitudeM - baroM) + : meta.renderAltitudeM, + ), + velocity, + // No reported track per fix: the course is read from the fixes. + track: course ?? undefined, + inventedHeight: meta.renderAltitudeInvented === true, + timeline: true, + }; + }); + return mergeTimelineRuns( + history ?? [], + entries, + (entry) => entry.epochMs, + centreMs, + ); +} + +/** + * The index of the first history entry at or after `renderTime` (the last + * entry when none is), by halving: a contact following the clock keeps up to + * TIMELINE_FIXES_LIMIT entries, and it is placed on every fleet tick. The + * bracketing pair is the entry before it and it. + * @param {Array<{time: Cesium.JulianDate}>} history In time order. + * @param {Cesium.JulianDate} renderTime + * @returns {number} + */ +export function historyBracketIndex(history, renderTime) { + let low = 0; + let high = history.length - 1; + while (low < high) { + const mid = (low + high) >> 1; + if (Cesium.JulianDate.lessThan(history[mid].time, renderTime)) + low = mid + 1; + else high = mid; + } + return low; +} + +/** + * Whether a contact following the clock is not to be drawn at `renderTime`: + * its history is its own fixes around the time (`timeline` entries), and the + * time is more than TIMELINE_UNSEEN_MS before the first, when it was not + * there yet. + * @param {Array<{time: Cesium.JulianDate, timeline?: boolean}>|undefined} history + * @param {Cesium.JulianDate} renderTime + * @returns {boolean} + */ +export function historyUnseenAt(history, renderTime) { + const first = history?.[0]; + return ( + first?.timeline === true && + Cesium.JulianDate.secondsDifference(first.time, renderTime) > + TIMELINE_UNSEEN_MS / 1000 + ); +} + +/** + * Lift a grounded contact's history onto the floor: its newest fix to + * `position`, or, when the history is its own fixes around the time + * (`timeline` entries, the newest of them later than the time drawn), every + * fix by the lift from `fromM` to `toM`, so it is not drawn rising to it. + * @param {object[]|undefined} history + * @param {Cesium.Cartesian3} position The newest fix lifted. + * @param {number|null} fromM The height it was drawn at. + * @param {number} toM The height it is lifted to. + */ +export function liftGroundedHistory(history, position, fromM, toM) { + const newest = history?.[history.length - 1]; + if (!newest) return; + if (history[0].timeline !== true || !Number.isFinite(fromM)) { + newest.position = Cesium.Cartesian3.clone(position, newest.position); + return; + } + for (const entry of history) { + const carto = Cesium.Cartographic.fromCartesian(entry.position); + if (!carto) continue; + entry.position = Cesium.Cartesian3.fromRadians( + carto.longitude, + carto.latitude, + carto.height + (toM - fromM), + undefined, + entry.position, + ); + } +} + +/** + * The history entries a tracked contact's trail has yet to take: those after + * its newest point (`trail` entries have `timeMs`) up to `untilMs`, the + * snapshot's time, so the trail grows as the snapshots bring fixes. + * @param {Array<{epochMs: number}>} history + * @param {Array<{timeMs: number}>} trail + * @param {number} untilMs + * @returns {object[]} + */ +export function historyAfterTrail(history, trail, untilMs) { + const lastMs = trail.length ? trail[trail.length - 1].timeMs : -Infinity; + return history.filter( + (entry) => entry.epochMs > lastMs && entry.epochMs <= untilMs, + ); +} diff --git a/src/data/timelineHistory.test.mjs b/src/data/timelineHistory.test.mjs new file mode 100644 index 000000000..e3689b582 --- /dev/null +++ b/src/data/timelineHistory.test.mjs @@ -0,0 +1,147 @@ +import test from 'node:test'; +import assert from 'node:assert/strict'; +import * as Cesium from 'cesium'; +import { + historyAfterTrail, + historyBracketIndex, + historyUnseenAt, + liftGroundedHistory, + mergeAircraftTimelineFixes, +} from './timelineHistory.js'; + +const META = { renderAltitudeM: 3_000 }; +const fix = (atMs, lat, altitudeM = null, lon = 0) => ({ + atMs, + lat, + lon, + altitudeM, +}); +const julian = (ms) => Cesium.JulianDate.fromDate(new Date(ms)); + +test('an aircraft with no fixes merges nothing', () => { + assert.equal( + mergeAircraftTimelineFixes([], { fixes: null }, META, 100, 0), + null, + ); +}); + +test("an aircraft's fixes join its history in order, each at the render height moved by its own climb", () => { + const history = mergeAircraftTimelineFixes( + [], + { + baroAltitudeM: 1_000, + fixes: [fix(120_000, 1, 1_200), fix(60_000, 0, 1_000), fix(180_000, 2)], + }, + META, + 100, + 120_000, + ); + assert.deepEqual( + history.map((entry) => entry.epochMs), + [60_000, 120_000, 180_000], + ); + const height = (entry) => + Cesium.Cartographic.fromCartesian(entry.position).height; + assert.ok(Math.abs(height(history[0]) - 3_000) < 1e-3); + assert.ok(Math.abs(height(history[1]) - 3_200) < 1e-3); + assert.ok( + Math.abs(height(history[2]) - 3_000) < 1e-3, + 'no altitude: the render height', + ); + // A later snapshot's fixes add to the earlier ones. + const more = mergeAircraftTimelineFixes( + history, + { baroAltitudeM: 1_000, fixes: [fix(180_000, 2), fix(240_000, 3)] }, + META, + 100, + 180_000, + ); + assert.deepEqual( + more.map((entry) => entry.epochMs), + [60_000, 120_000, 180_000, 240_000], + ); +}); + +test('the bracketing entry is the first at or after the time, else the last', () => { + const history = [1_000, 2_000, 3_000].map((ms) => ({ + time: Cesium.JulianDate.fromDate(new Date(ms)), + })); + const at = (ms) => + historyBracketIndex(history, Cesium.JulianDate.fromDate(new Date(ms))); + assert.equal(at(500), 0); + assert.equal(at(1_000), 0); + assert.equal(at(1_500), 1); + assert.equal(at(3_000), 2); + assert.equal(at(9_000), 2); +}); + +test('each fix heads where the track goes next, the last where it came from', () => { + const history = mergeAircraftTimelineFixes( + [], + { + fixes: [ + fix(0, 0, null, 0), + fix(60_000, 0, null, 0.01), + fix(120_000, 0.01, null, 0.01), + fix(180_000, 0.01, null, 0.01), + ], + }, + META, + 100, + 0, + ); + const tracks = history.map((entry) => entry.track); + assert.ok(Math.abs(tracks[0] - 90) < 0.5, 'east'); + assert.ok(Math.abs(tracks[1]) < 0.5, 'north'); + assert.equal(tracks[2], undefined, 'no move to read'); + assert.equal(tracks[3], undefined); + assert.ok(history.every((entry) => entry.timeline === true)); +}); + +test('a contact is unseen only well before the first of its own fixes', () => { + const history = mergeAircraftTimelineFixes( + [], + { fixes: [fix(600_000, 0), fix(660_000, 1)] }, + META, + 100, + 600_000, + ); + assert.equal(historyUnseenAt(history, julian(0)), true); + assert.equal(historyUnseenAt(history, julian(560_000)), false); + const live = [{ time: julian(600_000) }]; + assert.equal(historyUnseenAt(live, julian(0)), false, 'not on its fixes'); + assert.equal(historyUnseenAt(undefined, julian(0)), false); +}); + +test('a grounded contact on its own fixes is lifted whole; else its newest fix', () => { + const height = (entry) => + Cesium.Cartographic.fromCartesian(entry.position).height; + const history = mergeAircraftTimelineFixes( + [], + { fixes: [fix(0, 0), fix(60_000, 0.001)] }, + { renderAltitudeM: 5 }, + 0, + 0, + ); + const lifted = Cesium.Cartesian3.fromDegrees(0, 0.001, 30); + liftGroundedHistory(history, lifted, 5, 30); + assert.ok(history.every((entry) => Math.abs(height(entry) - 30) < 1e-3)); + const live = [ + { position: Cesium.Cartesian3.fromDegrees(0, 0, 5) }, + { position: Cesium.Cartesian3.fromDegrees(0, 0.001, 5) }, + ]; + liftGroundedHistory(live, lifted, 5, 30); + assert.ok(Math.abs(height(live[0]) - 5) < 1e-3); + assert.ok(Math.abs(height(live[1]) - 30) < 1e-3); +}); + +test("a tracked trail takes the fixes after its newest point, up to the snapshot's time", () => { + const history = [0, 60_000, 120_000, 180_000].map((epochMs) => ({ epochMs })); + assert.deepEqual( + historyAfterTrail(history, [{ timeMs: 60_000 }], 120_000).map( + (entry) => entry.epochMs, + ), + [120_000], + ); + assert.equal(historyAfterTrail(history, [], 120_000).length, 3); +}); diff --git a/src/layers/flights/motion.js b/src/layers/flights/motion.js index ccf2ca8c1..756fef1d2 100644 --- a/src/layers/flights/motion.js +++ b/src/layers/flights/motion.js @@ -1,4 +1,9 @@ import * as Cesium from 'cesium'; +import { + historyBracketIndex, + historyUnseenAt, + liftGroundedHistory, +} from '../../data/timelineHistory.js'; import { julianAt } from '../../time/julian.js'; import { COURSE_HOLD_SPEED_MPS, @@ -120,6 +125,7 @@ export function createMotion({ info.renderAltitudeM >= floor - 1 ) continue; + const drawnM = info.renderAltitudeM; info.renderAltitudeM = lifted; flightState._cullPositions.delete(icao24); // above the ellipsoid now (or floors say otherwise next poll) const position = Cesium.Cartesian3.fromDegrees( @@ -127,10 +133,12 @@ export function createMotion({ info.rawLat, lifted, ); - const history = flightState._positionHistory.get(icao24); - const newest = history?.[history.length - 1]; - if (newest) - newest.position = Cesium.Cartesian3.clone(position, newest.position); + liftGroundedHistory( + flightState._positionHistory.get(icao24), + position, + drawnM, + lifted, + ); const bb = flightState._billboards.get(icao24); if (bb) bb.position = position; } @@ -153,6 +161,7 @@ export function createMotion({ function _deadReckon(icao24, result, sampledRenderTime) { const info = flightState.records.data.get(icao24); + flightState._drUnseen = false; if (FOCUS_EVIDENCE_DEV && flightState._focusEvidenceIds.has(icao24)) { const position = flightState._billboards.get(icao24)?.position; flightState._drCourseDeg = info?.true_track || 0; @@ -198,7 +207,15 @@ export function createMotion({ ); // Bracketing pair: interpolate — no extrapolation error, no snap-back. - for (let i = history.length - 1; i >= 1; i--) { + // The pair around the render time (and the one before it, for a fix at + // exactly that time), found by halving: a contact following the clock + // keeps a long history. + for ( + let i = historyBracketIndex(history, renderTime), + stop = Math.max(1, i - 1); + i >= stop; + i-- + ) { const a = history[i - 1]; const b = history[i]; if ( @@ -254,6 +271,9 @@ export function createMotion({ // the oldest fix froze the icon; extrapolating the NEWEST fix to wall-clock now made // the icon jump back ~one poll interval the instant interpolation took over.) const oldest = history[0]; + // Following the clock, a time well before its first fix is before it + // was there: the fleet pass hides it. + flightState._drUnseen = historyUnseenAt(history, renderTime); const lookbackSec = Cesium.JulianDate.secondsDifference( oldest.time, renderTime, diff --git a/src/layers/flights/rendering.js b/src/layers/flights/rendering.js index 64d9064ff..ec4846ac1 100644 --- a/src/layers/flights/rendering.js +++ b/src/layers/flights/rendering.js @@ -1032,6 +1032,7 @@ export function createRendering({ flightState._scratchFleetPos, renderTime, ); + const unseen = flightState._drUnseen; // The dead-reckoned point drifts away from the fix whose cell supplied the // height, so a grounded contact's sprite ends up under the mesh it taxied // (or coasted) over. Re-floor at the DISPLAYED coordinate — read-only, and @@ -1057,9 +1058,12 @@ export function createRendering({ // sub-ellipsoid point near the limb "beyond the horizon" and the fleet // pass would hide a plane that is really just low over high-N terrain // waiting for its floor to warm (ATL grounded contacts at geoid −31 m). - const beyondHorizon = !occluder.isPointVisible( - flightState._cullPositions.get(icao24) || bb.position, - ); + // A contact not there yet at the time drawn is hidden as one beyond it. + const beyondHorizon = + unseen || + !occluder.isPointVisible( + flightState._cullPositions.get(icao24) || bb.position, + ); // A billboard flipping INTO view (horizon reveal while the camera idles) // gets its rotation refreshed THIS tick even without a pose change — // otherwise it reappears wearing its stale (often creation-north) nose for diff --git a/src/layers/flights/snapshotRenderer.js b/src/layers/flights/snapshotRenderer.js index 0306e85de..48a8b931d 100644 --- a/src/layers/flights/snapshotRenderer.js +++ b/src/layers/flights/snapshotRenderer.js @@ -10,6 +10,10 @@ import { aircraftIcon } from '../../data/aircraftIcons.js'; import { POSITION_HISTORY_LIMIT } from './recordPolicy.js'; import { followsClock } from './policy.js'; import { observeLiveAircraft } from './placed.js'; +import { + historyAfterTrail, + mergeAircraftTimelineFixes, +} from '../../data/timelineHistory.js'; /** Apply reconciled aircraft records to Cesium resources and follow state. */ export function createFlightSnapshotRenderer({ @@ -101,6 +105,18 @@ export function createFlightSnapshotRenderer({ ); const isTracked = icao24 === flightState._trackedIcao; + // Following the clock, a record may carry its own track around the + // time: the contact is placed on it, so the clock can move within it, + // back as well as on, without another snapshot. + const timelineHistory = followsClock(flightState) + ? mergeAircraftTimelineFixes( + flightState._positionHistory.get(icao24), + observation, + meta, + meta.velocity, + snapshot.observedAtMs ?? fixEpochMs, + ) + : null; // A host-supplied placement, if any, is told every fix as taken. observeLiveAircraft( flightState, @@ -111,80 +127,94 @@ export function createFlightSnapshotRenderer({ meta.velocity, meta.true_track, ); - - // Append to position history stamped with the FEED's fix epoch - // (time_position), not client receipt time — OpenSky positions arrive - // 5-15s stale and receipt-time stamping is what caused the - // back/forward oscillation. Only append when the fix actually - // advances, so stale repeats don't create zero-dt segments. - const fixTime = Cesium.JulianDate.fromDate(new Date(fixEpochMs)); - if (!flightState._positionHistory.has(icao24)) { - flightState._positionHistory.set(icao24, []); - } - const history = flightState._positionHistory.get(icao24); - const newest = history[history.length - 1]; - if (!newest || Cesium.JulianDate.greaterThan(fixTime, newest.time)) { - // Per-fix kinematics: the fix's own velocity/track ride along so the - // extrapolation paths use the values that BELONG to the fix they - // extend, not whatever the latest poll reported. - history.push({ - time: fixTime, - epochMs: fixEpochMs, - position: position.clone(), - velocity: meta.velocity, - track: meta.true_track, - // Drawn at an invented height: a trail seeded from history keeps no - // position for it. - inventedHeight: meta.renderAltitudeInvented === true, - }); - if (history.length > POSITION_HISTORY_LIMIT) { - history.shift(); - } - // Turn rate from the fix-track history — computed once per new fix - // (≤5 samples), consumed by the extrapolation paths at tick rate. - meta.turnRateDps = turnRateFromFixHistory(history); - // Trail accumulation is separate from the 5-fix DR history (PRD F1) - // so the visible trail keeps growing while tracked. Ground traffic - // appends nothing — a touchdown freezes the existing trail. - // Round 2 (owner): ground traffic appends too — taxi history stays - // live after touchdown (grounded flights positions are already - // surface-clamped via the surfaceM chain, so the ground leg drapes). + if (timelineHistory) { if (isTracked) - tracking._appendTrailFix(position.clone(), fixEpochMs, { - nullAltitude: meta.renderAltitudeInvented === true, - }); + for (const entry of historyAfterTrail( + timelineHistory, + flightState._trailFixes, + snapshot.observedAtMs ?? fixEpochMs, + )) + tracking._appendTrailFix(entry.position.clone(), entry.epochMs, { + nullAltitude: entry.inventedHeight, + }); + flightState._positionHistory.set(icao24, timelineHistory); + meta.turnRateDps = 0; } else { - const modelOwnsGroundVisual = rendering._modelOwnsVisual(icao24); - if (!modelOwnsGroundVisual) { - liftRepeatedGroundFix(newest, position, meta.onGround); + // Append to position history stamped with the FEED's fix epoch + // (time_position), not client receipt time — OpenSky positions arrive + // 5-15s stale and receipt-time stamping is what caused the + // back/forward oscillation. Only append when the fix actually + // advances, so stale repeats don't create zero-dt segments. + const fixTime = Cesium.JulianDate.fromDate(new Date(fixEpochMs)); + if (!flightState._positionHistory.has(icao24)) { + flightState._positionHistory.set(icao24, []); } - // Apply fresh kinematics only from a forward synthetic fix. Mutating - // the historical fix reprojects the entire stale interval and snaps - // the rendered aircraft when course or speed changes late. The stale - // rules apply: none for a contact that holds at its report, a coast - // capped from the real report, never below the ground. It is a motion - // aid, not a report, so it never joins the trail. - const kinematicsChanged = - newest.velocity !== meta.velocity || newest.track !== meta.true_track; - const holds = staleHoldsForFix(newest, { - onGround: meta.onGround, - cachedGroundFloor, - }); - if (kinematicsChanged && !holds) { - const synthetic = synthesizeForwardKinematicsFix(newest, { - // Following the clock, the snapshot's time is the moment it moves on from. - epochMs: followsClock(flightState) - ? snapshot.observedAtMs - : Date.now(), + const history = flightState._positionHistory.get(icao24); + const newest = history[history.length - 1]; + if (!newest || Cesium.JulianDate.greaterThan(fixTime, newest.time)) { + // Per-fix kinematics: the fix's own velocity/track ride along so the + // extrapolation paths use the values that BELONG to the fix they + // extend, not whatever the latest poll reported. + history.push({ + time: fixTime, + epochMs: fixEpochMs, + position: position.clone(), velocity: meta.velocity, track: meta.true_track, - turnRateDps: meta.turnRateDps, + // Drawn at an invented height: a trail seeded from history keeps no + // position for it. + inventedHeight: meta.renderAltitudeInvented === true, + }); + if (history.length > POSITION_HISTORY_LIMIT) { + history.shift(); + } + // Turn rate from the fix-track history — computed once per new fix + // (≤5 samples), consumed by the extrapolation paths at tick rate. + meta.turnRateDps = turnRateFromFixHistory(history); + // Trail accumulation is separate from the 5-fix DR history (PRD F1) + // so the visible trail keeps growing while tracked. Ground traffic + // appends nothing — a touchdown freezes the existing trail. + // Round 2 (owner): ground traffic appends too — taxi history stays + // live after touchdown (grounded flights positions are already + // surface-clamped via the surfaceM chain, so the ground leg drapes). + if (isTracked) + tracking._appendTrailFix(position.clone(), fixEpochMs, { + nullAltitude: meta.renderAltitudeInvented === true, + }); + } else { + const modelOwnsGroundVisual = rendering._modelOwnsVisual(icao24); + if (!modelOwnsGroundVisual) { + liftRepeatedGroundFix(newest, position, meta.onGround); + } + // Apply fresh kinematics only from a forward synthetic fix. Mutating + // the historical fix reprojects the entire stale interval and snaps + // the rendered aircraft when course or speed changes late. The stale + // rules apply: none for a contact that holds at its report, a coast + // capped from the real report, never below the ground. It is a motion + // aid, not a report, so it never joins the trail. + const kinematicsChanged = + newest.velocity !== meta.velocity || + newest.track !== meta.true_track; + const holds = staleHoldsForFix(newest, { + onGround: meta.onGround, cachedGroundFloor, }); - if (synthetic) { - history.push(synthetic); - if (history.length > POSITION_HISTORY_LIMIT) history.shift(); - meta.turnRateDps = turnRateFromFixHistory(history); + if (kinematicsChanged && !holds) { + const synthetic = synthesizeForwardKinematicsFix(newest, { + // Following the clock, the snapshot's time is the moment it moves on from. + epochMs: followsClock(flightState) + ? snapshot.observedAtMs + : Date.now(), + velocity: meta.velocity, + track: meta.true_track, + turnRateDps: meta.turnRateDps, + cachedGroundFloor, + }); + if (synthetic) { + history.push(synthetic); + if (history.length > POSITION_HISTORY_LIMIT) history.shift(); + meta.turnRateDps = turnRateFromFixHistory(history); + } } } } @@ -228,6 +258,7 @@ export function createFlightSnapshotRenderer({ // the raw fix drew it ahead until the next fleet tick snapped it back; // skipping the floor started a taxiing contact low and then raised it. const delayed = motion._deadReckon(icao24, new Cesium.Cartesian3()); + const unseenAtStart = flightState._drUnseen; const displayed = (delayed && motion._floorGroundedDisplayPosition( @@ -256,7 +287,9 @@ export function createFlightSnapshotRenderer({ // close (_groundDepthDistance). disableDepthTestDistance: rendering._groundDepthDistance(), id: icao24, - show: !isTracked, // hidden if currently tracked (entity replaces it) + // Hidden if currently tracked (entity replaces it), or not there yet + // at the time drawn (see historyUnseenAt). + show: !isTracked && !unseenAtStart, }); flightState._billboards.set(icao24, bb); rendering._applyFleetBillboardPresentation(icao24, bb); diff --git a/src/layers/flights/state.js b/src/layers/flights/state.js index 17bf8b560..1e7c87bd5 100644 --- a/src/layers/flights/state.js +++ b/src/layers/flights/state.js @@ -321,6 +321,11 @@ export function createFlightState({ source, services }) { flightState._drExtrapolating = false; + /** Set by `_deadReckon`: following the clock, the time drawn is well + * before the contact's first fix, so the fleet pass does not draw it. */ + + flightState._drUnseen = false; + /** Frame-cached course for the tracked aircraft (sibling of _cachedDRPosition). */ flightState._cachedDRCourse = null; diff --git a/src/layers/military/motion.js b/src/layers/military/motion.js index 0073937b2..4b009ce93 100644 --- a/src/layers/military/motion.js +++ b/src/layers/military/motion.js @@ -1,4 +1,8 @@ import * as Cesium from 'cesium'; +import { + historyBracketIndex, + historyUnseenAt, +} from '../../data/timelineHistory.js'; import { julianAt } from '../../time/julian.js'; import { lerpAngleDeg, @@ -61,6 +65,7 @@ export function createMotion({ */ function _deadReckon(icao24, result) { + flightState._drUnseen = false; const history = flightState._positionHistory.get(icao24); const info = flightState.records.data.get(icao24); if (!history || history.length === 0) { @@ -93,7 +98,15 @@ export function createMotion({ ); // Bracketing pair: interpolate — no extrapolation error, no snap-back. - for (let i = history.length - 1; i >= 1; i--) { + // The pair around the render time (and the one before it, for a fix at + // exactly that time), found by halving: a contact following the clock + // keeps a long history. + for ( + let i = historyBracketIndex(history, renderTime), + stop = Math.max(1, i - 1); + i >= stop; + i-- + ) { const a = history[i - 1]; const b = history[i]; if ( @@ -147,6 +160,9 @@ export function createMotion({ // the bracketing interpolation above with NO freeze and NO backward snap. (Holding // the oldest fix froze the icon until enough history accrued, then jumped.) const oldest = history[0]; + // Following the clock, a time well before its first fix is before it + // was there: the fleet pass hides it. + flightState._drUnseen = historyUnseenAt(history, renderTime); const lookbackSec = Cesium.JulianDate.secondsDifference( oldest.time, renderTime, diff --git a/src/layers/military/rendering.js b/src/layers/military/rendering.js index 7e19b4567..9dd1707ac 100644 --- a/src/layers/military/rendering.js +++ b/src/layers/military/rendering.js @@ -917,6 +917,7 @@ export function createRendering({ if (icao24 === flightState._trackedIcao) continue; // tracked entity owns its own motion const dr = parts.motion._deadReckon(icao24, flightState._scratchFleetPos); + const unseen = flightState._drUnseen; // Gate the write — assigning Billboard.position dirties the whole // collection's vertex buffer, so skip sub-meter moves. if (dr && Cesium.Cartesian3.distanceSquared(dr, bb.position) > 1.0) { @@ -926,9 +927,12 @@ export function createRendering({ // Round 6: occlusion-test a LIFTED point for contacts at/below the // ellipsoid (mirror of flights.js — sub-ellipsoid points near the limb // read "beyond the horizon" and would hide low contacts awaiting floors). - const beyondHorizon = !occluder.isPointVisible( - flightState.records.data.get(icao24)?.cullPosition || bb.position, - ); + // A contact not there yet at the time drawn is hidden as one beyond it. + const beyondHorizon = + unseen || + !occluder.isPointVisible( + flightState.records.data.get(icao24)?.cullPosition || bb.position, + ); // A billboard flipping INTO view (horizon reveal while the camera idles) // gets its rotation refreshed THIS tick even without a pose change — // otherwise it reappears wearing its stale (often creation-north) nose for diff --git a/src/layers/military/snapshotRenderer.js b/src/layers/military/snapshotRenderer.js index e70cd242f..56c135185 100644 --- a/src/layers/military/snapshotRenderer.js +++ b/src/layers/military/snapshotRenderer.js @@ -8,6 +8,11 @@ import { synthesizeForwardKinematicsFix, } from '../../data/motionModel.js'; import { aircraftIcon } from '../../data/aircraftIcons.js'; +import { + historyAfterTrail, + liftGroundedHistory, + mergeAircraftTimelineFixes, +} from '../../data/timelineHistory.js'; import { POSITION_HISTORY_LIMIT } from './recordPolicy.js'; import { BILLBOARD_SCALE, @@ -75,6 +80,18 @@ export function createMilitarySnapshotRenderer({ ); const isTracked = icao24 === flightState._trackedIcao; + // Following the clock, a record may carry its own track around the + // time: the contact is placed on it, so the clock can move within it, + // back as well as on, without another snapshot. + const timelineHistory = followsClock(flightState) + ? mergeAircraftTimelineFixes( + flightState._positionHistory.get(icao24), + aircraft, + meta, + meta.speedMps, + snapshot.observedAtMs ?? fixEpochMs, + ) + : null; // A host-supplied placement, if any, is told every fix as taken. observeLiveAircraft( flightState, @@ -85,76 +102,89 @@ export function createMilitarySnapshotRenderer({ meta.speedMps, meta.track, ); - - // Append to position history stamped with the FEED's fix epoch. - // adsb.lol's seen_pos is the AGE in seconds of the last position - // report, so the fix epoch is receipt time minus that age. Only - // append when the fix actually advances, so stale repeats don't - // create zero-dt segments. - const fixTime = Cesium.JulianDate.fromDate(new Date(fixEpochMs)); - if (!flightState._positionHistory.has(icao24)) { - flightState._positionHistory.set(icao24, []); - } - const history = flightState._positionHistory.get(icao24); - const newest = history[history.length - 1]; - if (!newest || Cesium.JulianDate.greaterThan(fixTime, newest.time)) { - // Per-fix kinematics: the fix's own velocity/track ride along so the - // extrapolation paths use the values that BELONG to the fix they - // extend, not whatever the latest poll reported. - history.push({ - time: fixTime, - epochMs: fixEpochMs, - position: position.clone(), - velocity: meta.speedMps, - track: meta.track, - // Drawn at an invented height: a trail seeded from history keeps no - // position for it. - inventedHeight: meta.renderAltitudeInvented === true, - }); - if (history.length > POSITION_HISTORY_LIMIT) { - history.shift(); - } - // Turn rate from the fix-track history — computed once per new fix - // (≤5 samples), consumed by the extrapolation paths at tick rate. - meta.turnRateDps = turnRateFromFixHistory(history); - // Trail accumulation is separate from the 5-fix DR history (PRD F2) - // so the visible trail keeps growing while tracked. Round 2 - // (owner): ground traffic appends too — taxi history stays live - // after touchdown; _appendTrailFix floors grounded positions at - // the surface so the ground leg drapes instead of diving. + if (timelineHistory) { if (isTracked) - tracking._appendTrailFix(position.clone(), fixEpochMs, { - nullAltitude: meta.renderAltitudeInvented === true, - }); + for (const entry of historyAfterTrail( + timelineHistory, + flightState._trailFixes, + snapshot.observedAtMs ?? fixEpochMs, + )) + tracking._appendTrailFix(entry.position.clone(), entry.epochMs, { + nullAltitude: entry.inventedHeight, + }); + flightState._positionHistory.set(icao24, timelineHistory); + meta.turnRateDps = 0; } else { - const modelOwnsGroundVisual = rendering._modelOwnsVisual(icao24); - if (!modelOwnsGroundVisual) { - liftRepeatedGroundFix(newest, position, meta.onGround); + // Append to position history stamped with the FEED's fix epoch. + // adsb.lol's seen_pos is the AGE in seconds of the last position + // report, so the fix epoch is receipt time minus that age. Only + // append when the fix actually advances, so stale repeats don't + // create zero-dt segments. + const fixTime = Cesium.JulianDate.fromDate(new Date(fixEpochMs)); + if (!flightState._positionHistory.has(icao24)) { + flightState._positionHistory.set(icao24, []); } - // A forward synthetic fix follows the stale rules (none while the - // contact holds at its report, a coast capped from the real report, - // never below the ground) and is a motion aid, never a trail report. - const kinematicsChanged = - newest.velocity !== meta.speedMps || newest.track !== meta.track; - const holds = staleHoldsForFix(newest, { - onGround: meta.onGround, - cachedGroundFloor, - }); - if (kinematicsChanged && !holds) { - const synthetic = synthesizeForwardKinematicsFix(newest, { - // Following the clock, the snapshot's time is the moment it moves on from. - epochMs: followsClock(flightState) - ? snapshot.observedAtMs - : Date.now(), + const history = flightState._positionHistory.get(icao24); + const newest = history[history.length - 1]; + if (!newest || Cesium.JulianDate.greaterThan(fixTime, newest.time)) { + // Per-fix kinematics: the fix's own velocity/track ride along so the + // extrapolation paths use the values that BELONG to the fix they + // extend, not whatever the latest poll reported. + history.push({ + time: fixTime, + epochMs: fixEpochMs, + position: position.clone(), velocity: meta.speedMps, track: meta.track, - turnRateDps: meta.turnRateDps, + // Drawn at an invented height: a trail seeded from history keeps no + // position for it. + inventedHeight: meta.renderAltitudeInvented === true, + }); + if (history.length > POSITION_HISTORY_LIMIT) { + history.shift(); + } + // Turn rate from the fix-track history — computed once per new fix + // (≤5 samples), consumed by the extrapolation paths at tick rate. + meta.turnRateDps = turnRateFromFixHistory(history); + // Trail accumulation is separate from the 5-fix DR history (PRD F2) + // so the visible trail keeps growing while tracked. Round 2 + // (owner): ground traffic appends too — taxi history stays live + // after touchdown; _appendTrailFix floors grounded positions at + // the surface so the ground leg drapes instead of diving. + if (isTracked) + tracking._appendTrailFix(position.clone(), fixEpochMs, { + nullAltitude: meta.renderAltitudeInvented === true, + }); + } else { + const modelOwnsGroundVisual = rendering._modelOwnsVisual(icao24); + if (!modelOwnsGroundVisual) { + liftRepeatedGroundFix(newest, position, meta.onGround); + } + // A forward synthetic fix follows the stale rules (none while the + // contact holds at its report, a coast capped from the real report, + // never below the ground) and is a motion aid, never a trail report. + const kinematicsChanged = + newest.velocity !== meta.speedMps || newest.track !== meta.track; + const holds = staleHoldsForFix(newest, { + onGround: meta.onGround, cachedGroundFloor, }); - if (synthetic) { - history.push(synthetic); - if (history.length > POSITION_HISTORY_LIMIT) history.shift(); - meta.turnRateDps = turnRateFromFixHistory(history); + if (kinematicsChanged && !holds) { + const synthetic = synthesizeForwardKinematicsFix(newest, { + // Following the clock, the snapshot's time is the moment it moves on from. + epochMs: followsClock(flightState) + ? snapshot.observedAtMs + : Date.now(), + velocity: meta.speedMps, + track: meta.track, + turnRateDps: meta.turnRateDps, + cachedGroundFloor, + }); + if (synthetic) { + history.push(synthetic); + if (history.length > POSITION_HISTORY_LIMIT) history.shift(); + meta.turnRateDps = turnRateFromFixHistory(history); + } } } } @@ -195,6 +225,7 @@ export function createMilitarySnapshotRenderer({ // it ahead until the next fleet tick snapped it back. const displayed = motion._deadReckon(icao24, new Cesium.Cartesian3()) || position; + const unseenAtStart = flightState._drUnseen; const bb = flightState._billboardCollection.add({ position: displayed, image: aircraftIcon(rendering._iconKind(icao24, meta.klass)), @@ -217,7 +248,9 @@ export function createMilitarySnapshotRenderer({ // close (_groundDepthDistance). disableDepthTestDistance: rendering._groundDepthDistance(), id: icao24, - show: !isTracked, // hidden if currently tracked (entity replaces it) + // Hidden if currently tracked (entity replaces it), or not there yet + // at the time drawn (see historyUnseenAt). + show: !isTracked && !unseenAtStart, }); flightState._billboards.set(icao24, bb); rendering._applyFleetBillboardPresentation(icao24, bb); @@ -259,6 +292,7 @@ export function createMilitarySnapshotRenderer({ info.renderAltitudeM >= floor - 1 ) continue; + const drawnM = info.renderAltitudeM; info.renderAltitudeM = lifted; flightState._cullPositions.delete(icao24); const liftedPos = Cesium.Cartesian3.fromDegrees( @@ -266,10 +300,12 @@ export function createMilitarySnapshotRenderer({ info.rawLat, lifted, ); - const hist = flightState._positionHistory.get(icao24); - const newest = hist?.[hist.length - 1]; - if (newest) - newest.position = Cesium.Cartesian3.clone(liftedPos, newest.position); + liftGroundedHistory( + flightState._positionHistory.get(icao24), + liftedPos, + drawnM, + lifted, + ); const bbStale = flightState._billboards.get(icao24); if (bbStale) bbStale.position = liftedPos; } diff --git a/src/layers/military/state.js b/src/layers/military/state.js index 9bdf2684c..0bccf9e84 100644 --- a/src/layers/military/state.js +++ b/src/layers/military/state.js @@ -282,6 +282,11 @@ export function createFlightState({ source, services }) { flightState._drCourseHold = false; + /** Set by `_deadReckon`: following the clock, the time drawn is well + * before the contact's first fix, so the fleet pass does not draw it. */ + + flightState._drUnseen = false; + /** Frame-cached course for the tracked aircraft (sibling of _cachedDRPosition). */ flightState._cachedDRCourse = null; diff --git a/src/layers/vessels/cockpitSubject.test.mjs b/src/layers/vessels/cockpitSubject.test.mjs index 784749b37..ebbc3c858 100644 --- a/src/layers/vessels/cockpitSubject.test.mjs +++ b/src/layers/vessels/cockpitSubject.test.mjs @@ -101,7 +101,10 @@ test('the subject says whether its track is the heading or the course', () => { test('a vessel without identity or position is not a subject', () => { assert.equal(vesselCockpitInfo(null), null); assert.equal(vesselCockpitInfo({ lat: 1, lon: 1 }), null); - assert.equal(vesselCockpitInfo({ id: '1', mmsi: '1', lat: 'x', lon: 1 }), null); + assert.equal( + vesselCockpitInfo({ id: '1', mmsi: '1', lat: 'x', lon: 1 }), + null, + ); }); test('a vessel missing from recent refreshes reads as stale', () => { diff --git a/src/layers/vessels/ingestion.js b/src/layers/vessels/ingestion.js index 2eb2d34f0..008507d01 100644 --- a/src/layers/vessels/ingestion.js +++ b/src/layers/vessels/ingestion.js @@ -39,8 +39,9 @@ export function createIngestion({ * @returns {Promise} */ async function loadAt(atMs, { signal = null, replace = false } = {}) { - // Whatever polls or loads for another time no longer applies. - if (replace && feed.loading) { + // Whatever polls or loads for another time no longer applies: the + // timeline asks for one time at a time. + if (feed.loading) { feed.abort?.abort(); feed.loading = false; feed.abort = null; @@ -209,6 +210,7 @@ export function createIngestion({ reference: record.reference, lat: record.latitude, lon: record.longitude, + fixes: record.fixes, name: record.name, imo: record.imo, type: record.type, diff --git a/src/layers/vessels/motion.js b/src/layers/vessels/motion.js index f4efb7d18..83e463ffc 100644 --- a/src/layers/vessels/motion.js +++ b/src/layers/vessels/motion.js @@ -1,14 +1,39 @@ /** * Where a vessel is at world time `tMs` while the layer follows the world - * clock: between the fix it moved from and the fix it moved to, along the - * great circle; at the earlier fix before it, at the newer fix after it. A - * vessel is never projected past its newest fix. + * clock: on its own fixes around the time when its record carries them + * (`fixes`, see src/time/timelineFixes.js), else between the fix it moved + * from and the fix it moved to; along the great circle between two fixes, at + * the first before them and at the last after them. A vessel is never + * projected past its newest fix. * @param {{lat: number, lon: number, motion?: {fromLat: number, fromLon: number, * fromMs: number, toLat: number, toLon: number, toMs: number}|null}} record * @param {number} tMs * @returns {{lat: number, lon: number}} */ export function vesselPositionAt(record, tMs) { + const fixes = record?.fixes; + if (fixes?.length >= 2 && Number.isFinite(tMs)) { + const first = fixes[0]; + const last = fixes[fixes.length - 1]; + if (tMs <= first.atMs) return { lat: first.lat, lon: first.lon }; + if (tMs >= last.atMs) return { lat: last.lat, lon: last.lon }; + let low = 1; + let high = fixes.length - 1; + while (low < high) { + const mid = (low + high) >> 1; + if (fixes[mid].atMs < tMs) low = mid + 1; + else high = mid; + } + const a = fixes[low - 1]; + const b = fixes[low]; + return greatCircleAt( + a.lat, + a.lon, + b.lat, + b.lon, + b.atMs > a.atMs ? (tMs - a.atMs) / (b.atMs - a.atMs) : 1, + ); + } const motion = record?.motion; if ( !motion || @@ -60,3 +85,28 @@ function unit(lat, lon) { 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(); + +/** + * Whether a vessel's fixes (`record.fixes`) put it in more than one place, + * so following the clock moves it; a moored vessel's do not. + * @param {Array<{lat: number, lon: number}>|null|undefined} fixes + * @returns {boolean} + */ +export function fixesMove(fixes) { + if (!fixes?.length) return false; + let moves = moving.get(fixes); + if (moves === undefined) { + const [first] = fixes; + moves = fixes.some( + (fix) => + Math.abs(fix.lat - first.lat) > 1e-6 || + Math.abs(fix.lon - first.lon) > 1e-6, + ); + moving.set(fixes, moves); + } + return moves; +} diff --git a/src/layers/vessels/motion.test.mjs b/src/layers/vessels/motion.test.mjs index f5370ae85..79378853f 100644 --- a/src/layers/vessels/motion.test.mjs +++ b/src/layers/vessels/motion.test.mjs @@ -1,6 +1,6 @@ import test from 'node:test'; import assert from 'node:assert/strict'; -import { vesselPositionAt } from './motion.js'; +import { fixesMove, vesselPositionAt } from './motion.js'; const record = { lat: 1, @@ -29,3 +29,35 @@ test('a vessel with no move is at its record', () => { assert.equal(vesselPositionAt(still, 2_000), still); assert.equal(vesselPositionAt({ ...still, motion: null }, 2_000).lat, 4); }); + +test('a vessel with fixes around the time is placed on them, held at either end', () => { + const tracked = { + lat: 9, + lon: 9, + motion: record.motion, + fixes: [ + { atMs: 1_000, lat: 0, lon: 0, altitudeM: null }, + { atMs: 2_000, lat: 1, lon: 0, altitudeM: null }, + { atMs: 4_000, lat: 1, lon: 2, altitudeM: null }, + ], + }; + assert.deepEqual(vesselPositionAt(tracked, 0), { lat: 0, lon: 0 }); + assert.deepEqual(vesselPositionAt(tracked, 9_000), { lat: 1, lon: 2 }); + const back = vesselPositionAt(tracked, 1_500); + assert.ok(Math.abs(back.lat - 0.5) < 1e-3 && Math.abs(back.lon) < 1e-6); + const on = vesselPositionAt(tracked, 3_000); + assert.ok(Math.abs(on.lat - 1) < 1e-3 && Math.abs(on.lon - 1) < 1e-3); +}); + +test('fixes that stay in one place do not move a vessel', () => { + const still = [ + { atMs: 0, lat: 1, lon: 2 }, + { atMs: 60_000, lat: 1, lon: 2 }, + ]; + assert.equal(fixesMove(still), false); + assert.equal( + fixesMove([...still, { atMs: 90_000, lat: 1.001, lon: 2 }]), + true, + ); + assert.equal(fixesMove(null), false); +}); diff --git a/src/layers/vessels/records.js b/src/layers/vessels/records.js index a076368d4..c0ad357e8 100644 --- a/src/layers/vessels/records.js +++ b/src/layers/vessels/records.js @@ -1,3 +1,7 @@ +import { + mergeTimelineRuns, + readTimelineFixes, +} from '../../time/timelineFixes.js'; import { PARTIAL_RETENTION_MS, SELECTED_PIN_REFRESHES, @@ -35,6 +39,9 @@ export function normalizeVessel(row) { virtual: row.virtual === true, lastPositionUtc: String(row.last_position_UTC || ''), lastPositionEpoch: finiteNumber(row.last_position_epoch), + // Its own track around the time, from a snapshot at a time (see + // src/time/timelineFixes.js); null when the row carries none. + fixes: readTimelineFixes(row.fixes), missedRefreshes: 0, }; } @@ -146,8 +153,22 @@ export class VesselRecords { record.fixReceivedAtMs = next.fixReceivedAtMs; record.fixFeedEpoch = next.fixFeedEpoch; } - if (replace) record.motion = null; - else if (follow) record.motion = motionBetween(record, next); + if (replace) { + record.motion = null; + record.fixes = next.fixes; + } else if (follow) { + record.motion = motionBetween(record, next); + // Without fixes now, it is placed by its record, not by fixes + // that end before it. + record.fixes = next.fixes + ? mergeTimelineRuns( + record.fixes ?? [], + next.fixes, + (fix) => fix.atMs, + (next.lastPositionEpoch ?? 0) * 1000, + ) + : null; + } else record.fixes = null; record.reference = next.reference; record.mmsi = next.mmsi; record.receivedAtMs = next.receivedAtMs; diff --git a/src/layers/vessels/records.test.mjs b/src/layers/vessels/records.test.mjs index d531ff532..3fba36944 100644 --- a/src/layers/vessels/records.test.mjs +++ b/src/layers/vessels/records.test.mjs @@ -181,3 +181,15 @@ test('an AIS row with no id is keyed by its MMSI; one with neither is unkeyed', assert.equal(probe.store.byId.size, 0); assert.equal(probe.store.unkeyed.length, 2); }); + +const fixes = (...pairs) => + pairs.map(([atMs, lat]) => ({ atMs, lat, lon: 4.05, altitudeM: null })); + +test('following the clock, a vessel whose next record carries no fixes is placed by the record', () => { + const probe = setup(); + probe.reconcile([row('111', { fixes: fixes([0, 1], [60_000, 2]) })], { + replace: true, + }); + probe.reconcile([row('111', { lat: 3 })], { follow: true }); + assert.equal(probe.store.byId.get('111').fixes, null); +}); diff --git a/src/layers/vessels/renderGovernor.test.mjs b/src/layers/vessels/renderGovernor.test.mjs index c5ce2e855..90ee46993 100644 --- a/src/layers/vessels/renderGovernor.test.mjs +++ b/src/layers/vessels/renderGovernor.test.mjs @@ -124,6 +124,26 @@ test('a camera that stops inside the cadence gets exactly one trailing frame', ( assert.equal(timers.size, 0); }); +test('following the clock, a time moved inside the cadence gets one trailing frame', () => { + const { layer, requests, timers, advance, frame } = setup(); + layer.testing._followClockForTest(1_000_000); + frame(); + advance(100); + // A seek while paused: the camera is still, the time drawn is not. + layer.testing._followClockForTest(940_000); + frame(); + assert.equal(timers.size, 1); + advance(VISIBILITY_UPDATE_MS); + assert.deepEqual(requests, ['ais-vessels-visibility']); + frame(); + for (let i = 0; i < 20; i += 1) { + advance(100); + frame(); + } + assert.deepEqual(requests, ['ais-vessels-visibility']); + assert.equal(timers.size, 0); +}); + test('a forced pass requests its own frame', () => { const { layer, requests } = setup(); layer.testing._runVisibilityPassForTest(true); diff --git a/src/layers/vessels/rendering.js b/src/layers/vessels/rendering.js index ec123cc8f..e9d2ada62 100644 --- a/src/layers/vessels/rendering.js +++ b/src/layers/vessels/rendering.js @@ -22,7 +22,8 @@ import { CARD_MIN_SEP_PX, followsClock, } from './policy.js'; -import { vesselPositionAt } from './motion.js'; +import { fixesMove, vesselPositionAt } from './motion.js'; +import { TIMELINE_UNSEEN_MS } from '../../time/timelineFixes.js'; import { fleetModelSet, loadFleetModelSet, @@ -190,7 +191,7 @@ export function createRendering({ function addRecordPrimitives(record, occluder) { const visible = state.feed.enabled && - isVisible(getVisual(record).surfacePosition, occluder); + isVisible(getVisual(record).surfacePosition, occluder, record); getVisual(record).billboard = state.billboardCollection.add({ position: getVisual(record).position, show: visible, @@ -319,7 +320,7 @@ export function createRendering({ function billboardShown(record, occluder) { const visual = getVisual(record); return ( - isVisible(visual.surfacePosition, occluder) && + isVisible(visual.surfacePosition, occluder, record) && record.id !== state.cockpitSubjectId && !visual.modelOwnsVisual ); @@ -343,7 +344,7 @@ export function createRendering({ item.position = getVisual(record).waterline; // An aid to navigation is a fixed mark: it does not turn to a heading. item.headingDeg = item.spec?.fixed ? 0 : vesselCourseDeg(record); - item.show = record.id !== state.cockpitSubjectId; + item.show = record.id !== state.cockpitSubjectId && seenYet(record); return item; } @@ -461,7 +462,7 @@ export function createRendering({ motion.wallMs - hiddenFollowedAtWallMs >= HIDDEN_FOLLOW_MS; if (moveHidden) hiddenFollowedAtWallMs = motion.wallMs; for (const record of state.records.all) { - if (!record.motion) continue; + if (!record.motion && !fixesMove(record.fixes)) continue; let visual = visualRecords.get(record); if (!visual?.position) { visual = prepareRecordVisual(record); @@ -623,14 +624,23 @@ export function createRendering({ const focusPass = focusPassIsNeeded(focusTarget, state.activeFocusCount) && (force || now - state.lastFocusUpdate >= FOCUS_UPDATE_MS); + // Following the clock, the time drawn decides which vessels are there + // yet: a time that moved since the last pass (a seek while paused) gets + // its pass too. + const worldMs = followsClock(vesselState) ? vesselState.worldNow() : null; if ( !regularPass && - state.viewer?.camera && - cameraPoseSignature(state.viewer.camera) !== vesselState._lastCamPoseSig + ((state.viewer?.camera && + cameraPoseSignature(state.viewer.camera) !== + vesselState._lastCamPoseSig) || + worldMs !== state.visibilityWorldMs) ) scheduleTrailingVisibilityPass(now); if (!regularPass && !focusPass) return; - if (regularPass) state.lastVisibilityUpdate = now; + if (regularPass) { + state.lastVisibilityUpdate = now; + state.visibilityWorldMs = worldMs; + } if (focusPass) state.lastFocusUpdate = now; if (!state.records.all.length) { // No records — flush any lingering card entries (vanished-feed case). @@ -662,7 +672,7 @@ export function createRendering({ const labelCandidates = []; for (const record of state.records.all) { const visual = getVisual(record); - const visible = isVisible(visual.surfacePosition, occluder); + const 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. @@ -786,11 +796,23 @@ export function createRendering({ ); } - function isVisible(surfacePosition, occluder) { + function isVisible(surfacePosition, occluder, record) { + if (record && !seenYet(record)) return false; if (!surfacePosition || !occluder) return true; return occluder.isPointVisible(surfacePosition); } + /** Whether a vessel is there at the time drawn: following the clock, not + * more than TIMELINE_UNSEEN_MS before its first fix. */ + function seenYet(record) { + const first = record.fixes?.[0]; + return ( + !first || + !followsClock(vesselState) || + vesselState.worldNow() >= first.atMs - TIMELINE_UNSEEN_MS + ); + } + /** * Source selector for the shared world-overlay pipeline: the * grid declutter picks which vessels get cards — one winner per screen-space diff --git a/src/layers/vessels/state.js b/src/layers/vessels/state.js index 8875d706e..3ed51e88d 100644 --- a/src/layers/vessels/state.js +++ b/src/layers/vessels/state.js @@ -81,6 +81,8 @@ export function createVesselState({ source, services }) { /** Pending timer that renders one frame after a cadence-skipped pass. */ trailingVisibilityTimer: null, lastVisibilityUpdate: 0, + /** Following the clock, the world time the last visibility pass drew. */ + visibilityWorldMs: null, lastFocusUpdate: 0, /** Sprites whose animated emphasis remains outside the 1.0 deadband. */ activeFocusCount: 0, diff --git a/src/layers/vessels/testing.js b/src/layers/vessels/testing.js index 197d41b5e..c0268494b 100644 --- a/src/layers/vessels/testing.js +++ b/src/layers/vessels/testing.js @@ -181,6 +181,13 @@ export function createTesting({ components.rendering.followClockPositions(); } + /** Follow the world clock, standing at world time `atMs`. Test-only seam. */ + + function _followClockForTest(atMs) { + vesselState.timeline = { active: () => true }; + vesselState.worldNow = () => atMs; + } + /** True while a trailing visibility frame is scheduled. Test-only seam. */ function _hasTrailingVisibilityPassForTest() { @@ -203,6 +210,7 @@ export function createTesting({ return { _bindVesselInteractionForTest, _setVesselStateForTest, + _followClockForTest, _setVesselOverlayHostForTest, _updateVesselCardsForTest, _reconcileVesselsForTest, diff --git a/src/sources/live/contract.js b/src/sources/live/contract.js index e201fc8de..718d1faf2 100644 --- a/src/sources/live/contract.js +++ b/src/sources/live/contract.js @@ -24,6 +24,13 @@ * freshness and staleness judged against `atMs`, and `atMs` echoed back. A * vessel snapshot at a time reports `transportStatus: 'live'`. getTrack then * receives `{ signal, atMs }` and returns only points at or before `atMs`. + * + * A timeline that declares `spanMs` lets each record of a snapshot at a time + * carry `fixes`: `{atMs, lat, lon, altitudeM?}` in time order, its own track + * from `spanMs` before the time to `spanMs` after it (see + * src/time/timelineFixes.js). The layer places the contact on them at any + * time they span, earlier ones too, so the clock can move within them, + * forwards or back, without a new snapshot. */ // Messages are English data (AI tools read them too); the Layers panel shows // them translated by their shape (translateFeedError in src/ui/statusText.js), @@ -164,10 +171,13 @@ export function httpError(response, source) { * null while it does not know yet; `stepMs` is the spacing of its snapshots; * the optional `subscribe(listener)` tells of a change in coverage, or of a * better answer for a time already answered (a paused layer then loads the - * time shown again), and returns the unsubscribe. + * time shown again), and returns the unsubscribe. The optional `spanMs` is + * how far either side of its time a snapshot's records carry their `fixes` + * (0 when they carry none). * @param {object|null|undefined} source * @returns {{coverage: () => ({start: number, end: number}|null), - * stepMs: number, subscribe: ((listener: () => void) => () => void)|null}|null} + * stepMs: number, spanMs: number, + * subscribe: ((listener: () => void) => () => void)|null}|null} */ export function readSnapshotTimeline(source) { const timeline = source?.timeline; @@ -177,9 +187,14 @@ export function readSnapshotTimeline(source) { if (!Number.isFinite(stepMs) || stepMs <= 0) return null; if (timeline.subscribe != null && typeof timeline.subscribe !== 'function') return null; + const spanMs = + Number.isFinite(timeline.spanMs) && timeline.spanMs > 0 + ? timeline.spanMs + : 0; return { coverage: () => timeline.coverage(), stepMs, + spanMs, subscribe: timeline.subscribe ? (listener) => timeline.subscribe(listener) : null, diff --git a/src/time/snapshotTimeline.js b/src/time/snapshotTimeline.js index f270e49e7..98f360c97 100644 --- a/src/time/snapshotTimeline.js +++ b/src/time/snapshotTimeline.js @@ -1,4 +1,5 @@ import { readSnapshotTimeline } from '../sources/live/contract.js'; +import { TIMELINE_HELD_MS } from './timelineFixes.js'; /** The longest play waits on a snapshot before it goes on without it. */ export const SNAPSHOT_WAIT_MS = 8_000; @@ -23,6 +24,16 @@ export const SNAPSHOT_RETRY_MS = 5_000; * step as the clock nears the newest it has, and play does not pass a * snapshot still loading (for at most SNAPSHOT_WAIT_MS). Those snapshots * are applied as polls are (`replace: false`), so contacts move on smoothly. + * - When the source's timeline declares `spanMs`, its records carry their + * fixes from `spanMs` before a snapshot's time to `spanMs` after it, and + * the layer places each contact on them by the clock. A seek or a move + * back that stays within the fixes the loaded snapshots carry is then no + * jump: nothing is cleared, play does not wait, and contacts move to the + * time smoothly. A move to a step before the newest loaded asks for that + * step once (`replace: true`): it brings back the contacts that left + * after it and drops those not there yet, while those it has keep their + * place, as their fixes put them. Paused, a time nearing the end of the + * fixes after the newest asks for the snapshot there (`replace: false`). * - Outside the source's coverage the layer is `clear()`ed and nothing loads; * while the coverage is not known yet nothing loads and nothing is cleared. * - Back at live, the layer is `clear()`ed and `resumeLive()` polls at once. @@ -61,8 +72,11 @@ export function createSnapshotTimeline({ // Each request's number; an answer to an older one is dropped. let sequence = 0; let inflight = null; - // The time of the newest snapshot applied since the last jump. + // The times of the newest and oldest snapshots applied since the last jump. let lead = null; + let base = null; + // The step a move back last asked for, until a newer snapshot applies. + let scrubbed = null; // Cleared for a time outside coverage, so it is not cleared again. let empty = false; let waiting = null; @@ -135,23 +149,27 @@ export function createSnapshotTimeline({ clear(); }; - function request(atMs, replace) { + // `quiet`: a move within the loaded fixes, which shows the contacts + // already: play does not wait for it, and its failure clears nothing. + function request(atMs, replace, quiet = false) { // One load at a time: an older one is dropped before a newer starts. inflight?.controller.abort(); const mine = ++sequence; const controller = new AbortController(); - inflight = { atMs, controller }; + inflight = { atMs, controller, quiet }; const failed = () => { inflight = null; // A time that could not be shown shows nothing, not another time. - if (replace) clearOnce(); + if (replace && !quiet) clearOnce(); + // Asked again once the retry is due. + if (quiet) scrubbed = null; capped = false; stopWaiting(); failedUntil = now() + SNAPSHOT_RETRY_MS; stopRetry(); retryTimer = setTimeout(() => { retryTimer = null; - if (started) follow(clock.getState()); + resume(); }, SNAPSHOT_RETRY_MS); }; // The source dropped this request for a newer one of its own: nothing @@ -159,10 +177,11 @@ export function createSnapshotTimeline({ // as the clock next moves, or shortly. const superseded = () => { inflight = null; + if (quiet) scrubbed = null; stopRetry(); retryTimer = setTimeout(() => { retryTimer = null; - if (started) follow(clock.getState()); + resume(); }, SNAPSHOT_RETRY_MS); }; Promise.resolve() @@ -175,7 +194,7 @@ export function createSnapshotTimeline({ return; } inflight = null; - lead = atMs; + held(atMs, replace); empty = false; capped = false; stopWaiting(); @@ -193,10 +212,87 @@ export function createSnapshotTimeline({ ); } + // The snapshot at `atMs` is applied: the stretch of snapshot times loaded + // (`base` to `lead`) takes it in. One the stretch does not reach with its + // fixes (play went on without waiting, far past the newest) starts it + // afresh: the contacts have no fixes for the time between. The stretch is + // kept to TIMELINE_HELD_MS, from the end just loaded, which every + // contact's fixes still cover. + function held(atMs, replace) { + const reach = 2 * (timeline.spanMs || 0); + scrubbed = null; + if ( + replace || + lead === null || + atMs > lead + reach || + atMs < base - reach + ) { + lead = atMs; + base = atMs; + return; + } + lead = Math.max(lead, atMs); + base = Math.min(base, atMs); + if (lead - base <= TIMELINE_HELD_MS) return; + if (atMs === lead) base = lead - TIMELINE_HELD_MS; + else lead = base + TIMELINE_HELD_MS; + } + + // Ask again for what the time needs, after a failure or a dropped load: + // a time within the loaded fixes may still need a snapshot near their end. + function resume() { + if (!started) return; + const state = clock.getState(); + if (!state.live && wasActive && heldAt(state.timeMs)) + scrubTo(state.timeMs, state); + else follow(state); + } + + // Whether the fixes of the snapshots loaded since the last jump span the + // time, so contacts can be placed there without a jump. + const heldAt = (timeMs) => + timeline.spanMs > 0 && + lead !== null && + base !== null && + timeMs >= base - timeline.spanMs && + timeMs <= lead + timeline.spanMs; + + // The clock moved to a time the loaded fixes span: contacts move there as + // they are. A step before the newest loaded is asked for once, in place + // of every contact; paused, a time in the outer half of the fixes after + // the newest asks for the snapshot at its step, which brings those beyond. + function scrubTo(timeMs, state) { + const covered = span(); + if (!covered) return; + if (!within(timeMs, covered)) { + cancel(); + lead = null; + base = null; + setGate(null); + clearOnce(); + return; + } + const half = timeline.spanMs / 2; + const step = Math.max(covered.start, stepAtOrBefore(timeMs)); + if (step < lead) { + if (step !== scrubbed && now() >= failedUntil) { + scrubbed = step; + if (inflight?.atMs !== step) request(step, true, true); + } + return; + } + if (!playsOn(state) && timeMs > lead + half && step > lead) { + if (inflight?.atMs !== step && now() >= failedUntil) request(step, false); + return; + } + keepUp(timeMs, state); + } + // Show the time afresh: the snapshot at its step replaces every contact. function jumpTo(timeMs) { cancel(); lead = null; + base = null; setGate(null); const covered = span(); if (!covered) return; @@ -215,12 +311,14 @@ export function createSnapshotTimeline({ if (!within(timeMs, covered)) { cancel(); lead = null; + base = null; setGate(null); clearOnce(); return; } if (inflight) { - if (playsOn(state) && timeMs >= inflight.atMs) startWaiting(); + if (playsOn(state) && timeMs >= inflight.atMs && !inflight.quiet) + startWaiting(); return; } if (now() < failedUntil) return; @@ -246,7 +344,10 @@ export function createSnapshotTimeline({ return; } setGate(capped ? null : next); - request(next, false); + // Past what the loaded fixes reach (play went on without waiting), the + // contacts have no fixes for the time between: the step stands in for + // them all. + request(next, timeline.spanMs > 0 && next > lead + 2 * timeline.spanMs); } function follow(state) { @@ -259,6 +360,7 @@ export function createSnapshotTimeline({ cancel(); setGate(null); lead = null; + base = null; empty = false; failedUntil = -Infinity; clear(); @@ -266,6 +368,8 @@ export function createSnapshotTimeline({ return; } const timeMs = state.timeMs; + // Away from live already: a move may stay within the loaded fixes. + const wasFollowing = wasActive; const jumped = !wasActive || state.jumps !== lastJumps || @@ -273,7 +377,8 @@ export function createSnapshotTimeline({ wasActive = true; lastJumps = state.jumps; lastTimeMs = timeMs; - if (jumped) { + if (jumped && wasFollowing && heldAt(timeMs)) scrubTo(timeMs, state); + else if (jumped) { failedUntil = -Infinity; jumpTo(timeMs); } else keepUp(timeMs, state); @@ -303,6 +408,7 @@ export function createSnapshotTimeline({ lastJumps = null; lastTimeMs = null; lead = null; + base = null; empty = false; failedUntil = -Infinity; gated = undefined; @@ -330,6 +436,7 @@ export function createSnapshotTimeline({ setGate(null); wasActive = false; lead = null; + base = null; for (const release of releases.splice(0).reverse()) release(); timeline = null; }, diff --git a/src/time/snapshotTimeline.test.mjs b/src/time/snapshotTimeline.test.mjs index 6e053b611..026c17414 100644 --- a/src/time/snapshotTimeline.test.mjs +++ b/src/time/snapshotTimeline.test.mjs @@ -10,7 +10,7 @@ import { const STEP = 10_000; const WALL = Date.UTC(2026, 10, 1, 12); -function harness({ timeline = true, coverage } = {}) { +function harness({ timeline = true, coverage, spanMs } = {}) { const t = { wall: WALL, mono: 1_000, @@ -34,6 +34,7 @@ function harness({ timeline = true, coverage } = {}) { timeline: { coverage: () => span, stepMs: STEP, + ...(spanMs && { spanMs }), subscribe(listener) { coverageListeners.add(listener); return () => coverageListeners.delete(listener); @@ -335,3 +336,215 @@ test('a source that tells of a better answer has the paused time loaded again, n assert.equal(loads(h.calls).length, live, 'live, nothing is loaded'); h.follower.stop(); }); + +test('with fixes either side, a move back within them asks for its step once, clearing nothing and holding nothing', async () => { + const SPAN = 5 * STEP; + const h = harness({ spanMs: SPAN }); + h.follower.start(); + const at = WALL - 600_000; + h.clock.seek(at); + await flush(); + await h.answer(); + assert.equal(loads(h.calls).length, 1); + // Within the step loaded: the contacts move along their fixes. + h.clock.seek(at + STEP / 2); + h.clock.seek(at + 1_000); + await flush(); + assert.equal(loads(h.calls).length, 1); + // Back two steps: the contacts move along their fixes, and the step there + // stands in for every contact once it loads, bringing back any that left + // after it. Nothing is cleared and play does not wait. + const before = h.calls.length; + h.clock.seek(at - 2 * STEP); + await flush(); + assert.deepEqual(h.calls.slice(before), [ + { type: 'load', atMs: at - 2 * STEP, replace: true }, + ]); + assert.equal(h.clock.getState().buffering, false); + // Moving within that step while it loads asks for nothing more. + h.clock.seek(at - 2 * STEP + 1_000); + await flush(); + assert.equal(loads(h.calls).length, 2); + await h.answer(); + h.clock.seek(at - 2 * STEP + 2_000); + await flush(); + assert.equal(loads(h.calls).length, 2); + // Playing on from there asks for the next step, as play does. + h.clock.play(); + h.advance(STEP - 2_000); + h.clock.coverageChanged(); + await flush(); + assert.deepEqual(loads(h.calls).at(-1), { + type: 'load', + atMs: at - STEP, + replace: false, + }); + await h.answer(); + h.clock.pause(); + // Paused past the outer half after the newest: the step there. + const newest = loads(h.calls).at(-1).atMs; + h.clock.seek(newest + 3 * STEP + 1_000); + await flush(); + assert.deepEqual(loads(h.calls).at(-1), { + type: 'load', + atMs: newest + 3 * STEP, + replace: false, + }); + await h.answer(); + // Beyond the fixes is a jump: the time is shown afresh, play held. + h.clock.seek(at - 60 * STEP); + await flush(); + assert.deepEqual(loads(h.calls).at(-1), { + type: 'load', + atMs: at - 60 * STEP, + replace: true, + }); + h.follower.stop(); +}); + +test('playing, a seek back within the fixes does not hold play on its step', async () => { + const SPAN = 5 * STEP; + const h = harness({ spanMs: SPAN }); + h.follower.start(); + const at = WALL - 600_000; + h.clock.seek(at); + await flush(); + await h.answer(); + h.clock.play(); + h.clock.seek(at - 2 * STEP + 1_000); + await flush(); + assert.equal(loads(h.calls).at(-1).atMs, at - 2 * STEP); + h.advance(STEP / 4); + h.clock.coverageChanged(); + await flush(); + assert.equal(h.clock.getState().buffering, false); + h.follower.stop(); +}); + +test('without a span every move back is a jump', async () => { + const h = harness(); + h.follower.start(); + const at = WALL - 600_000; + h.clock.seek(at); + await flush(); + await h.answer(); + h.clock.seek(at - STEP); + await flush(); + assert.deepEqual(loads(h.calls).at(-1), { + type: 'load', + atMs: at - STEP, + replace: true, + }); + h.follower.stop(); +}); + +test('a snapshot the loaded fixes do not reach starts the held stretch afresh', async () => { + const SPAN = 5 * STEP; + const h = harness({ spanMs: SPAN }); + h.follower.start(); + const at = WALL - 1_200_000; + h.clock.seek(at); + await flush(); + await h.answer(); + h.clock.play(); + h.advance(100); + h.clock.coverageChanged(); + await flush(); + // The next step is slow: play goes on without it, far past the fixes. + h.advance(2 * STEP); + h.clock.coverageChanged(); + h.advance(SNAPSHOT_WAIT_MS); + h.advance(30 * STEP); + h.clock.coverageChanged(); + await h.answer(); + const far = loads(h.calls).at(-1).atMs; + assert.ok(far > at + STEP + 2 * SPAN, 'asked for a step past the fixes'); + assert.equal( + loads(h.calls).at(-1).replace, + true, + 'in place of every contact', + ); + await h.answer(); + h.clock.pause(); + // Back between the two: no snapshot's fixes cover it, so it is a jump. + h.clock.seek(at + SPAN + 2 * STEP); + await flush(); + assert.equal(loads(h.calls).at(-1).replace, true); + h.follower.stop(); +}); + +test('the held stretch is kept to the newest stretch every contact covers', async () => { + const SPAN = 5 * STEP; + const h = harness({ + spanMs: SPAN, + coverage: { start: WALL - 6 * 3_600_000, end: WALL }, + }); + h.follower.start(); + const at = WALL - 3 * 3_600_000; + h.clock.seek(at); + await flush(); + await h.answer(); + h.clock.play(); + // Playing on for well over TIMELINE_HELD_MS, a step at a time. + for (let k = 0; k < 160; k++) { + h.advance(STEP); + h.clock.coverageChanged(); + await flush(); + while (h.pending.length) await h.answer(h.pending.length - 1); + } + h.clock.pause(); + // Back to the first snapshot's time: past what is held, so a jump. + h.clock.seek(at); + await flush(); + assert.equal(loads(h.calls).at(-1).replace, true); + h.follower.stop(); +}); + +test('a step a move back asked for that the source drops is asked again', async () => { + const SPAN = 5 * STEP; + const h = harness({ spanMs: SPAN }); + h.follower.start(); + const at = WALL - 600_000; + h.clock.seek(at); + await flush(); + await h.answer(); + h.clock.seek(at - 2 * STEP); + await flush(); + const asked = loads(h.calls).length; + h.pending + .shift() + .reject(Object.assign(new Error('dropped'), { name: 'AbortError' })); + await flush(); + h.advance(SNAPSHOT_RETRY_MS); + await flush(); + assert.equal(loads(h.calls).length, asked + 1); + assert.equal(loads(h.calls).at(-1).atMs, at - 2 * STEP); + h.follower.stop(); +}); + +test('a step a move back asked for that fails clears nothing and is asked again while paused', async () => { + const SPAN = 5 * STEP; + const h = harness({ spanMs: SPAN }); + h.follower.start(); + const at = WALL - 600_000; + h.clock.seek(at); + await flush(); + await h.answer(); + h.clock.seek(at - 3 * STEP - 1_000); + await flush(); + const asked = loads(h.calls).length; + await h.answer(0, false); + assert.equal( + h.calls.some((call) => call.type === 'clear'), + false, + ); + h.advance(SNAPSHOT_RETRY_MS); + await flush(); + assert.equal(loads(h.calls).length, asked + 1); + assert.deepEqual(loads(h.calls).at(-1), { + type: 'load', + atMs: at - 4 * STEP, + replace: true, + }); + h.follower.stop(); +}); diff --git a/src/time/timelineFixes.js b/src/time/timelineFixes.js new file mode 100644 index 000000000..e8b078cc3 --- /dev/null +++ b/src/time/timelineFixes.js @@ -0,0 +1,125 @@ +/** + * The fixes a snapshot at a time may carry for each contact (a record's + * `fixes`, see readSnapshotTimeline in src/sources/live/contract.js): where + * it was in the minutes around the time, so a layer following the world + * clock places it at nearby times, earlier ones too, without asking again. + */ + +/** Most fixes a contact keeps across the snapshots that brought them. */ +export const TIMELINE_FIXES_LIMIT = 240; +/** Kept fixes are at least this far apart, so the limit spans well over an + * hour around the newest snapshot's time however dense the fixes come. */ +export const TIMELINE_FIX_SPACING_MS = 20_000; +/** + * The longest stretch of snapshot times a layer treats as loaded at once + * (see src/time/snapshotTimeline.js). With each snapshot's fixes reaching a + * span either side, it stays within what every contact keeps around the + * newest snapshot's time. + */ +export const TIMELINE_HELD_MS = 20 * 60_000; +/** + * A contact following the clock is not drawn at a time more than this + * before its first fix: it was not there yet. Within it, it is drawn + * reaching its first fix, as a contact first seen is. + */ +export const TIMELINE_UNSEEN_MS = 60_000; + +/** + * A record's fixes in time order, those with a time and a position only, + * or null when it carries fewer than two. + * @param {unknown} value + * @returns {Array<{atMs: number, lat: number, lon: number, + * altitudeM: number|null}>|null} + */ +export function readTimelineFixes(value) { + if (!Array.isArray(value)) return null; + const fixes = []; + for (const fix of value) { + const atMs = Number(fix?.atMs); + const lat = Number(fix?.lat); + const lon = Number(fix?.lon); + if ( + !Number.isFinite(atMs) || + !Number.isFinite(lat) || + !Number.isFinite(lon) || + Math.abs(lat) > 90 + ) + continue; + const altitudeM = Number(fix?.altitudeM); + fixes.push({ + atMs, + lat, + lon, + altitudeM: + fix?.altitudeM != null && Number.isFinite(altitudeM) ? altitudeM : null, + }); + } + if (fixes.length < 2) return null; + fixes.sort((a, b) => a.atMs - b.atMs); + return fixes; +} + +/** + * Two runs of entries in time order (`timeOf` reads an entry's epoch ms) as + * one: `newer` stands in for the entries of `older` within the time it + * spans, the rest of `older` is kept, and an entry closer than + * TIMELINE_FIX_SPACING_MS to the one kept before it is left out, but for + * the newest of `newer`, which is always kept. Only the `limit` entries nearest + * `centreMs` are kept, so the fixes kept span at least `limit` times that + * spacing. + * @template T + * @param {T[]} older + * @param {T[]} newer + * @param {(entry: T) => number} timeOf + * @param {number} centreMs + * @param {number} [limit] + * @returns {T[]} + */ +export function mergeTimelineRuns( + older, + newer, + timeOf, + centreMs, + limit = TIMELINE_FIXES_LIMIT, +) { + const first = newer.length ? timeOf(newer[0]) : Infinity; + const last = newer.length ? timeOf(newer[newer.length - 1]) : -Infinity; + const newest = newer[newer.length - 1]; + // 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 k = merged.length - 1; + if (k < 0 || timeOf(entry) - timeOf(merged[k]) >= TIMELINE_FIX_SPACING_MS) { + 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; + // 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) + ) + start++; + return merged.slice(start, start + limit); +} diff --git a/src/time/timelineFixes.test.mjs b/src/time/timelineFixes.test.mjs new file mode 100644 index 000000000..9ab47c184 --- /dev/null +++ b/src/time/timelineFixes.test.mjs @@ -0,0 +1,98 @@ +import test from 'node:test'; +import assert from 'node:assert/strict'; +import { mergeTimelineRuns, readTimelineFixes } from './timelineFixes.js'; + +test('fixes are read in time order, the malformed left out, and fewer than two are none', () => { + assert.equal(readTimelineFixes(undefined), null); + assert.equal(readTimelineFixes([{ atMs: 1, lat: 1, lon: 1 }]), null); + assert.deepEqual( + readTimelineFixes([ + { atMs: 3_000, lat: 3, lon: 3, altitudeM: 30 }, + { atMs: 'x', lat: 0, lon: 0 }, + { atMs: 2_000, lat: 95, lon: 2 }, + { atMs: 1_000, lat: 1, lon: 1, altitudeM: null }, + ]), + [ + { atMs: 1_000, lat: 1, lon: 1, altitudeM: null }, + { atMs: 3_000, lat: 3, lon: 3, altitudeM: 30 }, + ], + ); +}); + +test('two runs merge in order, the newer standing in for the older within its time, thinned to the spacing', () => { + const at = (atMs, from) => ({ atMs, from }); + const merged = mergeTimelineRuns( + [at(0, 'old'), at(30_000, 'old'), at(105_000, 'old'), at(160_000, 'old')], + [ + at(40_000, 'new'), + at(80_000, 'new'), + at(90_000, 'new'), + at(150_000, 'new'), + ], + (fix) => fix.atMs, + 60_000, + ); + // 40 s is too near 30 s; 90 s too near 80 s; 105 s is within the newer + // run; 160 s too near 150 s, the newest of the newer run, kept. + assert.deepEqual(merged, [ + at(0, 'old'), + at(30_000, 'old'), + at(80_000, 'new'), + at(150_000, 'new'), + ]); + const ends = mergeTimelineRuns( + [at(0, 'old')], + [at(5_000, 'new'), at(10_000, 'new')], + (fix) => fix.atMs, + 0, + ); + assert.deepEqual(ends, [at(10_000, 'new')]); +}); + +test("runs a step apart, however dense, keep a contact's fixes back over every step", () => { + const spanMs = 5 * 60_000; + for (const [stepMs, spacingMs] of [ + [10_000, 5_000], + [60_000, 5_000], + [60_000, 30_000], + ]) { + let fixes = []; + for (let t = 0; t <= 20 * 60_000; t += stepMs) { + const run = []; + for ( + let f = Math.ceil((t - spanMs) / spacingMs) * spacingMs; + f <= t + spanMs; + f += spacingMs + ) + run.push({ atMs: f }); + fixes = mergeTimelineRuns(fixes, run, (fix) => fix.atMs, t); + } + assert.equal(fixes[0].atMs, -spanMs, `${stepMs}/${spacingMs}`); + assert.equal(fixes.at(-1).atMs, 25 * 60_000); + for (let k = 1; k < fixes.length - 1; k++) + assert.ok(fixes[k].atMs - fixes[k - 1].atMs >= 20_000); + } +}); + +test('past the limit only the fixes nearest the centre are kept', () => { + const run = (from, to) => + Array.from({ length: to - from }, (_, k) => ({ + atMs: (from + k) * 60_000, + })); + const kept = mergeTimelineRuns( + run(0, 10), + run(10, 20), + (f) => f.atMs, + 15 * 60_000, + 6, + ); + assert.deepEqual( + kept.map((f) => f.atMs / 60_000), + [12, 13, 14, 15, 16, 17], + ); + const early = mergeTimelineRuns(run(0, 10), run(10, 20), (f) => f.atMs, 0, 4); + assert.deepEqual( + early.map((f) => f.atMs / 60_000), + [0, 1, 2, 3], + ); +}); From e027fc37948efaa21c8fa0268898003909ba0cd0 Mon Sep 17 00:00:00 2001 From: Sameh Khamis Date: Sun, 15 Nov 2026 09:27:48 -0800 Subject: [PATCH 09/13] Changelog fragment for #1749 --- changelog.d/1749-smooth-rewind.md | 6 ++++++ 1 file changed, 6 insertions(+) create mode 100644 changelog.d/1749-smooth-rewind.md diff --git a/changelog.d/1749-smooth-rewind.md b/changelog.d/1749-smooth-rewind.md new file mode 100644 index 000000000..97ee20b69 --- /dev/null +++ b/changelog.d/1749-smooth-rewind.md @@ -0,0 +1,6 @@ +- Flights, military flights and vessels move back as smoothly as they move on. + A source whose snapshots at a time carry each contact's own fixes either + side of it (`timeline.spanMs`, record `fixes`) lets a seek or a drag back + within those fixes move every contact along its track, with no blank and no + wait; the step there then loads in place of every contact. A contact is not + drawn more than a minute before its first fix. From 4a61c755d94856853747360f8031f989f6488035 Mon Sep 17 00:00:00 2001 From: Sameh Khamis Date: Sun, 15 Nov 2026 09:41:01 -0800 Subject: [PATCH 10/13] Search reads degrees-minutes-seconds, UTM, MGRS and plus codes --- scripts/format-scope.json | 3 + scripts/package-boundaries.json | 8 + src/search/coordinateParser.js | 68 ++++- src/search/coordinateParser.test.mjs | 7 +- src/search/gridReference.js | 232 ++++++++++++++++ src/search/gridReference.test.mjs | 395 +++++++++++++++++++++++++++ src/search/plusCode.js | 90 ++++++ 7 files changed, 788 insertions(+), 15 deletions(-) create mode 100644 src/search/gridReference.js create mode 100644 src/search/gridReference.test.mjs create mode 100644 src/search/plusCode.js diff --git a/scripts/format-scope.json b/scripts/format-scope.json index 8487f7472..99ab5a1c8 100644 --- a/scripts/format-scope.json +++ b/scripts/format-scope.json @@ -180,6 +180,9 @@ "src/search/google.js", "src/search/coordinateParser.js", "src/search/coordinateParser.test.mjs", + "src/search/gridReference.js", + "src/search/gridReference.test.mjs", + "src/search/plusCode.js", "src/search/coordinateGeocoder.js", "src/search/presetGeocoder.js", "src/search/offlineGeocoders.test.mjs", diff --git a/scripts/package-boundaries.json b/scripts/package-boundaries.json index c275337cb..bec87c9ba 100644 --- a/scripts/package-boundaries.json +++ b/scripts/package-boundaries.json @@ -670,6 +670,8 @@ "src/search/alpsGeocoder.js", "src/search/coordinateGeocoder.js", "src/search/coordinateParser.js", + "src/search/gridReference.js", + "src/search/plusCode.js", "src/search/presetGeocoder.js", "src/search/nominatim.js", "src/nominatimGeocode.js", @@ -3268,6 +3270,8 @@ "src/app/layers/directions.js", "src/search/coordinateGeocoder.js", "src/search/coordinateParser.js", + "src/search/gridReference.js", + "src/search/plusCode.js", "src/search/presetGeocoder.js", "src/voice/session.js", "src/voice/sessionCommands.js", @@ -4264,6 +4268,8 @@ "src/app/layers/directions.js", "src/search/coordinateGeocoder.js", "src/search/coordinateParser.js", + "src/search/gridReference.js", + "src/search/plusCode.js", "src/search/presetGeocoder.js", "src/app/localGeojsonServices.js", "src/data/displayText.js", @@ -4609,6 +4615,8 @@ "src/services/terrainHeights.js", "src/search/coordinateGeocoder.js", "src/search/coordinateParser.js", + "src/search/gridReference.js", + "src/search/plusCode.js", "src/search/presetGeocoder.js", "src/search/nominatim.js", "src/nominatimGeocode.js", diff --git a/src/search/coordinateParser.js b/src/search/coordinateParser.js index 948cc25e7..bbcd1f024 100644 --- a/src/search/coordinateParser.js +++ b/src/search/coordinateParser.js @@ -1,14 +1,18 @@ /** - * Strict decimal-degree coordinate parsing for the search box. + * Strict coordinate parsing for the search box. * * A search that guesses is worse than one that declines: reading `12junk, 34oops` * as 12, 34 flies the operator somewhere they did not ask for and looks like a * successful search. So every rule here is exact — a component is a decimal - * number, optionally signed, optionally marked with one hemisphere letter, and - * nothing else. Two-dimensional WGS84 geo URIs use their own strict grammar. - * Degrees/minutes/seconds and grid references are not handled; - * they fall through to the geocoders, which is what happens today. + * number, or degrees with minutes and seconds marked by their symbols + * (`40°26'46"`), optionally signed, optionally marked with one hemisphere + * letter, and nothing else. Two-dimensional WGS84 geo URIs use their own + * strict grammar, as do UTM and MGRS grid references (`gridReference.js`) and + * full plus codes (`plusCode.js`). Unmarked runs such as `40 26 46 N` and + * short plus codes are not handled; they fall through to the geocoders. */ +import { parseGridReference } from './gridReference.js'; +import { parsePlusCode } from './plusCode.js'; /** One decimal-degree component: an optional hemisphere letter on either side. */ const COMPONENT = @@ -18,6 +22,14 @@ const COMPONENT = const GEO_URI = /^geo:(-?\d{1,2}(?:\.\d+)?),(-?\d{1,3}(?:\.\d+)?)(?:;crs=wgs84)?$/i; +/** + * Degrees, minutes and optional seconds, each marked by its symbol, with an + * optional sign and one optional hemisphere letter on either side. Only the + * last number may have a decimal part. + */ +const DMS_COMPONENT = + /^([NSEW])?\s*([+-])?(\d{1,3})\s*[°º]\s*(\d{1,2}(?:\.\d+)?)\s*['′’]\s*(?:(\d{1,2}(?:\.\d+)?)\s*(?:"|″|”|''|′′))?\s*([NSEW])?$/i; + /** Hemisphere letters, by the axis each one can name. */ const LATITUDE_LETTERS = new Set(['N', 'S']); @@ -29,7 +41,7 @@ const LATITUDE_LETTERS = new Set(['N', 'S']); */ function readComponent(text) { const match = COMPONENT.exec(String(text).trim()); - if (!match) return null; + if (!match) return readDmsComponent(text); const [, before, digits, after] = match; // Two letters on one component is a contradiction, not a coordinate. if (before && after) return null; @@ -47,6 +59,34 @@ function readComponent(text) { }; } +/** + * Read one degrees-minutes-seconds component, by the same rules as a decimal + * one: a sign and a letter never both, minutes and seconds below 60, and a + * decimal part only on the last number given. + * + * @param {string} text + * @returns {{ value: number, axis: 'lat'|'lon'|null } | null} + */ +function readDmsComponent(text) { + const match = DMS_COMPONENT.exec(String(text).trim()); + if (!match) return null; + const [, before, sign, degrees, minutes, seconds, after] = match; + if (before && after) return null; + const letter = (before || after || '').toUpperCase(); + if (letter && sign) return null; + if (seconds !== undefined && minutes.includes('.')) return null; + if (Number(minutes) >= 60 || (seconds !== undefined && Number(seconds) >= 60)) + return null; + const magnitude = + Number(degrees) + Number(minutes) / 60 + Number(seconds ?? 0) / 3600; + if (!letter) + return { value: sign === '-' ? -magnitude : magnitude, axis: null }; + return { + value: letter === 'S' || letter === 'W' ? -magnitude : magnitude, + axis: LATITUDE_LETTERS.has(letter) ? 'lat' : 'lon', + }; +} + /** * Split on a comma, a semicolon, or whitespace — never on anything else. * A hemisphere letter stays with the number it names, so `40.7 N 74.0 W` @@ -61,8 +101,9 @@ function splitComponents(query) { return trimmed.length === 2 && trimmed.every(Boolean) ? trimmed : null; } const words = text.split(/\s+/); - // Each component has at most a number, a degree sign and one hemisphere. - if (words.length > 6) return null; + // Each component has at most degrees, minutes and seconds with their + // symbols and one hemisphere letter. + if (words.length > 14) return null; // Keep every character: extracting tokens would turn `1e3` or `1.2.3` // into invented coordinates. A lone letter between numbers can name either // component; require an unambiguous split rather than guessing its owner. @@ -88,7 +129,9 @@ export function formatCoordinateLabel(lat, lon) { } /** - * Parse a decimal-degree pair or a two-dimensional WGS84 geo URI, or return null. + * Parse a decimal-degree or degrees-minutes-seconds pair, a two-dimensional + * WGS84 geo URI, a UTM or MGRS grid reference or a full plus code, or return + * null. * * Both orders are accepted when the hemisphere letters say which is which * (`W 40, N 74` is longitude then latitude); with no letters the conventional @@ -107,7 +150,12 @@ export function parseCoordinateQuery(query) { const parts = /^geo:/i.test(text) ? GEO_URI.exec(text)?.slice(1, 3) : splitComponents(text); - if (!parts) return null; + if (!parts) { + const point = parseGridReference(text) ?? parsePlusCode(text); + return ( + point && { ...point, label: formatCoordinateLabel(point.lat, point.lon) } + ); + } const first = readComponent(parts[0]); const second = readComponent(parts[1]); diff --git a/src/search/coordinateParser.test.mjs b/src/search/coordinateParser.test.mjs index 6128d5f4c..a9ec94de3 100644 --- a/src/search/coordinateParser.test.mjs +++ b/src/search/coordinateParser.test.mjs @@ -124,12 +124,9 @@ test('malformed and ambiguous coordinates are refused, never guessed', () => { '0, 181', '0, -180.5', 'N 100, W 74', - // Degrees/minutes/seconds is out of scope and must fall through, not - // be read as a decimal pair. - '40°26\'46"N, 79°58\'56"W', + // Degrees/minutes/seconds without their symbols must fall through, not + // be read as a decimal pair (marked ones are in gridReference.test.mjs). '40 26 46, 79 58 56', - // A grid reference is out of scope too. - '33UXP0500444998', ]) { assert.equal( parseCoordinateQuery(query), diff --git a/src/search/gridReference.js b/src/search/gridReference.js new file mode 100644 index 000000000..db890f492 --- /dev/null +++ b/src/search/gridReference.js @@ -0,0 +1,232 @@ +/** + * UTM and MGRS grid references to latitude and longitude, for the search box. + * + * Strict, like the decimal parser: a reference either reads exactly or is + * declined. UTM is `18T 585628 4511322` (zone, latitude band, easting, + * northing); MGRS is `18T WL 85650 11369`, spaced or not, with 1 to 5 digits + * each for easting and northing. MGRS letters are capitals, as references are + * printed, unless written unspaced to 100 m or finer (`18twl856113`): + * lower-case `1 jan 2023` or `3 usa 12` is ordinary text, not a grid square. The polar UPS bands (A, B, + * Y, Z) and the zones Svalbard does not use (32X, 34X, 36X) decline. A UTM `S` + * is the 32°N–40°N band when its northing falls in that band, and otherwise + * the southern hemisphere, as UTM is also written; a southern reference + * between about 50°S and 58°S written that way reads as band S. + */ + +/** WGS84. */ +const A = 6378137; +const F = 1 / 298.257223563; +const K0 = 0.9996; +const FALSE_EASTING = 500000; +const FALSE_NORTHING_SOUTH = 10000000; + +/** Latitude bands C to X (no I or O), 8° each from 80°S; X is 12°. */ +const BANDS = 'CDEFGHJKLMNPQRSTUVWX'; + +/** MGRS 100 km column letters by zone set, and the row letters. */ +const COLUMN_SETS = ['ABCDEFGH', 'JKLMNPQR', 'STUVWXYZ']; +const ROW_LETTERS = 'ABCDEFGHJKLMNPQRSTUV'; + +/** The latitude range of a band letter, or null. */ +function bandRange(letter) { + const index = BANDS.indexOf(letter); + if (index < 0) return null; + const south = -80 + index * 8; + return { south, north: letter === 'X' ? 84 : south + 8 }; +} + +/** + * Inverse transverse Mercator (Krüger's series to the sixth order, as in + * Karney 2011): UTM easting and northing in a zone to latitude and longitude. + */ +function utmToLatLon(zone, easting, northing, southern) { + const n = F / (2 - F); + const n2 = n * n; + const n3 = n2 * n; + const n4 = n3 * n; + const n5 = n4 * n; + const n6 = n5 * n; + const rectifying = (A / (1 + n)) * (1 + n2 / 4 + n4 / 64 + n6 / 256); + const beta = [ + n / 2 - + (2 / 3) * n2 + + (37 / 96) * n3 - + n4 / 360 - + (81 / 512) * n5 + + (96199 / 604800) * n6, + n2 / 48 + + n3 / 15 - + (437 / 1440) * n4 + + (46 / 105) * n5 - + (1118711 / 3870720) * n6, + (17 / 480) * n3 - (37 / 840) * n4 - (209 / 4480) * n5 + (5569 / 90720) * n6, + (4397 / 161280) * n4 - (11 / 504) * n5 - (830251 / 7257600) * n6, + (4583 / 161280) * n5 - (108847 / 3991680) * n6, + (20648693 / 638668800) * n6, + ]; + const xi = + (southern ? northing - FALSE_NORTHING_SOUTH : northing) / (K0 * rectifying); + const eta = (easting - FALSE_EASTING) / (K0 * rectifying); + let xiPrime = xi; + let etaPrime = eta; + for (let j = 1; j <= 6; j += 1) { + xiPrime -= beta[j - 1] * Math.sin(2 * j * xi) * Math.cosh(2 * j * eta); + etaPrime -= beta[j - 1] * Math.cos(2 * j * xi) * Math.sinh(2 * j * eta); + } + const conformal = Math.asin(Math.sin(xiPrime) / Math.cosh(etaPrime)); + const longitudeOffset = Math.atan2(Math.sinh(etaPrime), Math.cos(xiPrime)); + // Conformal to geodetic latitude, by Newton's method on tan φ. + const e = Math.sqrt(F * (2 - F)); + const tauPrime = Math.tan(conformal); + let tau = tauPrime; + for (let i = 0; i < 6; i += 1) { + const sigma = Math.sinh( + e * Math.atanh((e * tau) / Math.sqrt(1 + tau * tau)), + ); + const tauIPrime = + tau * Math.sqrt(1 + sigma * sigma) - sigma * Math.sqrt(1 + tau * tau); + const delta = + ((tauPrime - tauIPrime) / Math.sqrt(1 + tauIPrime * tauIPrime)) * + ((1 + (1 - e * e) * tau * tau) / + ((1 - e * e) * Math.sqrt(1 + tau * tau))); + tau += delta; + if (Math.abs(delta) < 1e-12) break; + } + const lat = (Math.atan(tau) * 180) / Math.PI; + let lon = (zone - 1) * 6 - 180 + 3 + (longitudeOffset * 180) / Math.PI; + if (lon > 180) lon -= 360; + if (lon < -180) lon += 360; + return { lat, lon }; +} + +/** + * Whether a latitude sits in a band, allowing `slack` degrees past its edges + * (an MGRS square's centre can lie across the band edge the square touches). + */ +function inBand(lat, range, slack = 0) { + return lat >= range.south - slack && lat <= range.north + slack; +} + +/** Zones 32, 34 and 36 do not exist in band X (Svalbard's widened zones). */ +function zoneExists(zone, band) { + return !(band === 'X' && (zone === 32 || zone === 34 || zone === 36)); +} + +/** UTM `18T 585628 4511322` (or `18 T 585628 4511322`), or null. */ +function parseUtm(text) { + const match = + /^(\d{1,2})\s*([C-HJ-NP-X])\s+(\d{6}(?:\.\d+)?)\s*m?\s+(\d{1,7}(?:\.\d+)?)\s*m?$/i.exec( + text, + ); + if (!match) return null; + const zone = Number(match[1]); + const letter = match[2].toUpperCase(); + const easting = Number(match[3]); + const northing = Number(match[4]); + if ( + zone < 1 || + zone > 60 || + easting < 100000 || + easting > 900000 || + northing > 10000000 || + !zoneExists(zone, letter) + ) + return null; + const range = bandRange(letter); + const asBand = utmToLatLon(zone, easting, northing, range.south < 0); + const bandFits = inBand(asBand.lat, range); + if (bandFits) return asBand; + // `S` is also how UTM is written for the southern hemisphere. Where both + // fit, the 32°N–40°N band (Tokyo, Los Angeles, the Mediterranean) is far + // likelier than 50°S–58°S, so the band wins above. + if (letter === 'S') { + const south = utmToLatLon(zone, easting, northing, true); + if (south.lat < 0 && south.lat >= -80) return south; + } + return null; +} + +/** + * The lowest northing of each band, in metres, that MGRS's 2,000 km row + * cycle is lifted past (the NGA table, as used by proj4's mgrs module). + */ +const BAND_MIN_NORTHING = { + C: 1100000, + D: 2000000, + E: 2800000, + F: 3700000, + G: 4600000, + H: 5500000, + J: 6400000, + K: 7300000, + L: 8200000, + M: 9100000, + N: 0, + P: 800000, + Q: 1700000, + R: 2600000, + S: 3500000, + T: 4400000, + U: 5300000, + V: 6200000, + W: 7000000, + X: 7900000, +}; + +/** + * MGRS as `18TWL8565011369`, `18T WL 8565011369` or `18T WL 85650 11369` + * (easting and northing the same length), or null. + */ +function parseMgrs(text) { + const match = + /^(\d{1,2})\s*([C-HJ-NP-X])\s*([A-HJ-NP-Z])([A-HJ-NP-V])(?:\s*(\d{2,10})|\s*(\d{1,5})\s+(\d{1,5}))$/i.exec( + text, + ); + if (!match) return null; + const zone = Number(match[1]); + const band = match[2].toUpperCase(); + const column = match[3].toUpperCase(); + const row = match[4].toUpperCase(); + let east = ''; + let north = ''; + if (match[5]) { + if (match[5].length % 2) return null; + east = match[5].slice(0, match[5].length / 2); + north = match[5].slice(match[5].length / 2); + } else if (match[6]) { + if (match[6].length !== match[7].length) return null; + [east, north] = [match[6], match[7]]; + } + if (zone < 1 || zone > 60 || !zoneExists(zone, band)) return null; + const precision = east.length; + const letters = text.replace(/[\d\s]/g, ''); + if (letters !== letters.toUpperCase() && (precision < 3 || /\s/.test(text))) + return null; + const columnIndex = COLUMN_SETS[(zone - 1) % 3].indexOf(column); + if (columnIndex < 0) return null; + // Rows start at A in odd zones and at F in even ones. + const rowIndex = + (ROW_LETTERS.indexOf(row) - (zone % 2 === 0 ? 5 : 0) + 20) % 20; + const scale = 10 ** (5 - precision); + // The centre of the square the digits name; a 1 m reference is its corner. + const half = precision < 5 ? scale / 2 : 0; + const easting = (columnIndex + 1) * 100000 + Number(east || 0) * scale + half; + let northing = rowIndex * 100000 + Number(north || 0) * scale + half; + while (northing < BAND_MIN_NORTHING[band]) northing += 2000000; + const range = bandRange(band); + const point = utmToLatLon(zone, easting, northing, range.south < 0); + // Slack of the square's size in degrees of latitude. + return inBand(point.lat, range, scale / 111000) ? point : null; +} + +/** + * A UTM or MGRS reference as `{ lat, lon }`, or null when the text is not + * exactly one. + * @param {string} text + */ +export function parseGridReference(text) { + if (typeof text !== 'string') return null; + const trimmed = text.trim(); + if (!trimmed || trimmed.length > 40) return null; + return parseUtm(trimmed) ?? parseMgrs(trimmed); +} diff --git a/src/search/gridReference.test.mjs b/src/search/gridReference.test.mjs new file mode 100644 index 000000000..aa111400a --- /dev/null +++ b/src/search/gridReference.test.mjs @@ -0,0 +1,395 @@ +// GRID REFERENCES AND PLUS CODES — UTM, MGRS and full Open Location Codes read +// as coordinates. Each is exact or refused, like a decimal pair: a misread +// reference flies the operator somewhere else and looks like success. +// +// The UTM and MGRS points are one per latitude band (and the zone edges) from +// pyproj and the mgrs package; the plus codes are from the Open Location Code +// project's test data (decoding.csv, validityTests.csv). +// +// Run with: npm test +import test from 'node:test'; +import assert from 'node:assert/strict'; +import { parseGridReference } from './gridReference.js'; +import { parsePlusCode } from './plusCode.js'; +import { parseCoordinateQuery } from './coordinateParser.js'; + +/** Metres between two points, near enough for sub-metre checks. */ +function metres(a, b) { + const r = Math.PI / 180; + const h = + Math.sin(((b.lat - a.lat) * r) / 2) ** 2 + + Math.cos(a.lat * r) * + Math.cos(b.lat * r) * + Math.sin(((b.lon - a.lon) * r) / 2) ** 2; + return 12742000 * Math.asin(Math.sqrt(h)); +} + +// [MGRS, its latitude, its longitude, UTM, its latitude, its longitude] +const GRID = [ + [ + '18TWL8565011369', + 40.7488215, + -73.9854319, + '18T 585651 4511369', + 40.748817, + -73.985428, + ], + [ + '56HLH3490052290', + -33.8567842, + 151.2152996, + '56H 334900 6252291', + -33.856784, + 151.215297, + ], + [ + '33XWG1427883355', + 78.2232003, + 15.6266906, + '33X 514279 8683355', + 78.2232, + 15.6267, + ], + [ + '32VKN9747700830', + 60.392994, + 5.3241531, + '32V 297477 6700830', + 60.39299, + 5.32415, + ], + [ + '17MQV8185780012', + -0.1806554, + -78.4678355, + '17M 781858 9980013', + -0.180653, + -78.467834, + ], + [ + '60KXF1292941202', + -17.713404, + 178.0649977, + '60K 612930 8041203', + -17.7134, + 178.065, + ], + [ + '03WVM8047852917', + 64.5010996, + -165.4064093, + '3W 480479 7152918', + 64.5011, + -165.4064, + ], + ['31NAA6603200011', 0.0001039, 9.92e-5, '31N 166033 11', 0.0001, 0.0001], + [ + '01CDM4324728161', + -79.8999987, + -179.9000186, + '1C 443248 1128161', + -79.9, + -179.9, + ], + [ + '19FEV4500027239', + -54.7999989, + -68.2999931, + '19F 545000 3927239', + -54.8, + -68.3, + ], + [ + '54SUD1748374870', + 34.9999987, + 138.9999956, + '54S 317484 3874871', + 35.0, + 139.0, + ], + ['30UXC9988909362', 51.500002, -0.1200043, '30U 699890 5709362', 51.5, -0.12], + [ + '10JBR3890542412', + -26.7152573, + -125.6244681, + '10J 238906 7042412', + -26.7152593, + -125.6244672, + ], + [ + '05RMK1662242662', + 26.6023189, + -153.8374266, + '5R 416623 2942663', + 26.6023191, + -153.8374241, + ], + [ + '31DDC8763628944', + -70.046176, + 2.6753849, + '31D 487636 2228945', + -70.0461753, + 2.6753768, + ], + [ + '50LNP6584960983', + -10.3033721, + 117.601397, + '50L 565849 8860983', + -10.3033722, + 117.6013945, + ], + [ + '14EMV6706624140', + -59.3202819, + -99.5786192, + '14E 467066 3424141', + -59.3202803, + -99.5786205, + ], + [ + '57QYF1413419747', + 22.7716198, + 161.0856759, + '57Q 714135 2519747', + 22.7716153, + 161.0856775, + ], + [ + '24PXB9668711309', + 14.5677772, + -37.1743636, + '24P 696687 1611310', + 14.5677806, + -37.1743652, + ], + [ + '30GTV9870806681', + -41.4662188, + -5.4104109, + '30G 298709 5406682', + -41.4662184, + -5.4104096, + ], + [ + '60XWU3439017795', + 83.8999979, + 179.899971, + '60X 534391 9317796', + 83.9, + 179.9, + ], + ['32VJH3227421798', 55.9999999, 3.1000066, '32V 132274 6221799', 56.0, 3.1], + [ + '60RWP4163073757', + 25.9820077, + 177.4159163, + '60R 541631 2873757', + 25.9820033, + 177.415919, + ], + [ + '60VWL2412126400', + 58.8767223, + 177.4183599, + '60V 524121 6526400', + 58.876719, + 177.4183593, + ], + [ + '60UUD2978050375', + 52.7763309, + 174.4763915, + '60U 329781 5850376', + 52.7763332, + 174.476393, + ], + [ + '32GKT8210286690', + -42.5414587, + 6.3464153, + '32G 282102 5286690', + -42.5414631, + 6.346413, + ], +]; + +test('MGRS and UTM references read to within a metre in every latitude band', () => { + for (const [mgrs, mgrsLat, mgrsLon, utm, utmLat, utmLon] of GRID) { + const fromMgrs = parseGridReference(mgrs); + assert.ok(fromMgrs, mgrs); + assert.ok(metres(fromMgrs, { lat: mgrsLat, lon: mgrsLon }) < 1, mgrs); + const fromUtm = parseGridReference(utm); + assert.ok(fromUtm, utm); + assert.ok(metres(fromUtm, { lat: utmLat, lon: utmLon }) < 1, utm); + } +}); + +test('MGRS reads spaced, unspaced and at every precision', () => { + const times = { lat: 40.74882, lon: -73.98543 }; + for (const text of [ + '18TWL8565011369', + '18T WL 8565011369', + '18T WL 85650 11369', + '18twl8565011369', + ]) + assert.ok(metres(parseGridReference(text), times) < 1, text); + // Coarser references name the centre of their square. + assert.ok(metres(parseGridReference('18TWL856113'), times) < 71, '100 m'); + assert.ok(metres(parseGridReference('18TWL8511'), times) < 710, '1 km'); + assert.ok(metres(parseGridReference('18TWL81'), times) < 7100, '10 km'); + // A square with no digits is not enough to go on. + assert.equal(parseGridReference('18TWL'), null); +}); + +test('a UTM S is the 32°N–40°N band where it fits, else the southern hemisphere', () => { + const tokyo = parseGridReference('54S 383000 3950000'); + assert.ok( + tokyo.lat > 35 && tokyo.lat < 36 && tokyo.lon > 139 && tokyo.lon < 140, + ); + const sydney = parseGridReference('56S 334900 6252291'); + assert.ok(metres(sydney, { lat: -33.856784, lon: 151.215297 }) < 1); +}); + +test('malformed grid references are refused', () => { + for (const text of [ + '18TWL856501136', // odd digit count + '18T WL 8565 11369', // easting and northing of different lengths + '18IWL8565011369', // no band I + '18TIL8565011369', // no column I + '18TAL8565011369', // column A is not in zone 18's set + '61T WL 85650 11369', // no zone 61 + '0T WL 85650 11369', + '18Z WL 85650 11369', // polar bands are UPS, not UTM + '18A 585651 4511369', + '18T 58565 4511369', // a five-digit easting + '18T 585651 4511369 extra', + '18T WL 85650 11369 N', + 'WL 85650 11369', + '18T', + 'ATL', + // Ordinary text that spells a square in lower case. + '1 jan', + '7 feb', + '3 usa', + '1 jan 2023', + '4 cat 12', + '1the12', + '60 jun 202311', + '18t wl 85650 11369', + // Zones Svalbard does not use. + '32X 500000 8700000', + '34X NG 12 34', + '36XNG1234', + ]) + assert.equal(parseGridReference(text), null, text); +}); + +// [code, latitude, longitude] of each code's centre. +const PLUS_CODES = [ + ['7FG49Q00+', 20.375, 2.775], + ['7FG49QCJ+2V', 20.370062500000003, 2.7821875], + ['7FG49QCJ+2VX', 20.3701125, 2.782234375], + ['7FG49QCJ+2VXGJ', 20.370113500000002, 2.7822353515650002], + ['CR4389W6+MV36X2V', 72.34663418, 141.3621622924805], + ['4V44CC8J+XR', -47.5825625, 162.4320625], + ['7G2394VR+3RXCXV', 10.392739899999999, 21.1421003417965], + ['94GG6QPW+', 60.23625, -129.20375], + ['CP9C0000+', 77.5, 108.5], + ['549QX497+9X', -22.0315625, -124.8850625], + ['979V23X2+V97C6Q', 57.0496617, -62.949092041015504], + ['7G6MCJCM+58', 14.4204375, 33.6333125], + ['7VHJGH8G+', 21.51625, 172.57625], + ['423726P5+P72', -48.963237500000005, -174.791859375], + ['2JH70000+', -78.5, 65.5], + ['58P6PP00+', -15.275, -55.275], + ['2Q3P6CPJ+Q3H7HQ7', -88.76306733999999, 134.430234069824], + ['9R000000+', 60.0, 150.0], + ['6FPW3600+', 4.074999999999999, 18.225], + ['C55GR473+C5732', 73.8135255, -109.89708496093749], + ['CV25MQ00+', 70.67500000000001, 163.775], + ['4J86FVGW+9449', -43.5241175, 64.89533984375], + ['8V2H837Q+44', 30.3128125, 171.08781249999998], + ['C8C35800+', 78.17500000000001, -58.675], + ['62M5653J+Q3', 3.2044375, -176.8198125], + ['8H8VW72V+9GXV5', 36.9009955, 57.2938583984375], +]; + +test('full plus codes read to the centre of their area', () => { + for (const [code, lat, lon] of PLUS_CODES) { + const point = parsePlusCode(code); + assert.ok(point, code); + assert.ok( + Math.abs(point.lat - lat) < 1e-9 && Math.abs(point.lon - lon) < 1e-9, + code, + ); + } + assert.deepEqual( + parsePlusCode(' 849vcwc8+r9 '), + parsePlusCode('849VCWC8+R9'), + ); +}); + +// [code, isValid, isShort, isFull] +const VALIDITY = [ + ['8FWC2345+G6', 'true', 'false', 'true'], + ['8FWC2345+G6G', 'true', 'false', 'true'], + ['8fwc2345+', 'true', 'false', 'true'], + ['8FWCX400+', 'true', 'false', 'true'], + ['84000000+', 'true', 'false', 'true'], + ['WC2345+G6g', 'true', 'true', 'false'], + ['2345+G6', 'true', 'true', 'false'], + ['45+G6', 'true', 'true', 'false'], + ['+G6', 'true', 'true', 'false'], + ['G+', 'false', 'false', 'false'], + ['+', 'false', 'false', 'false'], + ['8FWC2345+G', 'false', 'false', 'false'], + ['8FWC2_45+G6', 'false', 'false', 'false'], + ['8FWC2\u03b745+G6', 'false', 'false', 'false'], + ['8FWC2345+G6+', 'false', 'false', 'false'], + ['8FWC2345G6+', 'false', 'false', 'false'], + ['8FWC2300+G6', 'false', 'false', 'false'], + ['WC2300+G6g', 'false', 'false', 'false'], + ['WC2345+G', 'false', 'false', 'false'], + ['WC2300+', 'false', 'false', 'false'], + ['84900000+', 'false', 'false', 'false'], + ['849VGJQF+VX7QR3J', 'true', 'false', 'true'], + ['849VGJQF+VX7QR3U', 'false', 'false', 'false'], + ['849VGJQF+VX7QR3JW', 'true', 'false', 'true'], + ['849VGJQF+VX7QR3JU', 'false', 'false', 'false'], +]; + +test('only valid full plus codes are read; short and invalid ones are refused', () => { + for (const [code, , , isFull] of VALIDITY) + assert.equal(parsePlusCode(code) !== null, isFull === 'true', code); +}); + +test('the search box reads degrees-minutes-seconds, grid references and plus codes', () => { + const near = (query, lat, lon, within) => { + const point = parseCoordinateQuery(query); + assert.ok(point, query); + assert.ok(metres(point, { lat, lon }) < within, query); + assert.match(point.label, /° [NS], .*° [EW]$/, query); + }; + near('40°26\'46"N, 79°58\'56"W', 40.446111, -79.982222, 1); + near('40° 26′ 46″ N 79° 58′ 56″ W', 40.446111, -79.982222, 1); + near("N 40°26.767' W 79°58.933'", 40.446117, -79.982217, 1); + near('-33°51\'24", 151°12\'55"', -33.856667, 151.215278, 1); + near('33UXP0500444998', 48.249493, 16.414495, 1); + near('18T 585651 4511369', 40.748817, -73.985428, 1); + near('849VCWC8+R9', 37.4220625, -122.0840625, 1); + for (const query of [ + '40°26\'46"N', // one component + '40°60\'0"N, 79°0\'0"W', // 60 minutes + '40°26\'60"N, 79°0\'0"W', // 60 seconds + '40°26.5\'46"N, 79°0\'0"W', // a decimal before the last number + '-40°26\'46"N, 79°0\'0"W', // a sign and a letter + 'N 40°26\'46"N, 79°0\'0"W', // two letters + '91°0\'0"N, 79°0\'0"W', // out of range + '40°26\'46"N, 40°26\'46"S', // both latitude + 'CWC8+R9', // a short plus code needs a place + 'CWC8+R9 Mountain View', + ]) + assert.equal(parseCoordinateQuery(query), null, query); +}); diff --git a/src/search/plusCode.js b/src/search/plusCode.js new file mode 100644 index 000000000..368536430 --- /dev/null +++ b/src/search/plusCode.js @@ -0,0 +1,90 @@ +/** + * Full Open Location Codes ("plus codes", `849VCWC8+R9`) to the centre of + * their area, for the search box. Implements the decoding half of the Open + * Location Code specification (github.com/google/open-location-code). Short + * codes (`CWC8+R9 Mountain View`) need a reference place and decline, as does + * anything that is not exactly one valid full code. + */ + +const ALPHABET = '23456789CFGHJMPQRVWX'; +const SEPARATOR = '+'; +const SEPARATOR_POSITION = 8; +const PADDING = '0'; +const PAIR_LENGTH = 10; +const GRID_COLUMNS = 4; +const GRID_ROWS = 5; +const MAX_LENGTH = 15; + +/** Whether `code` is a valid full code (the specification's isFull). */ +function isFullCode(code) { + const separator = code.indexOf(SEPARATOR); + if (separator < 0 || separator !== code.lastIndexOf(SEPARATOR)) return false; + if ( + separator !== SEPARATOR_POSITION || + code.length === SEPARATOR_POSITION + 2 + ) + return false; + const padding = code.indexOf(PADDING); + if (padding >= 0) { + // Padding only before the separator, in an even count from an even place, + // and nothing after the separator. + if (padding === 0 || padding % 2) return false; + const run = /0+/.exec(code)[0]; + if ( + run.length % 2 || + run.length !== code.split('').filter((c) => c === PADDING).length + ) + return false; + if (padding + run.length !== separator) return false; + if (code.length > separator + 1) return false; + } + for (const character of code) + if ( + character !== SEPARATOR && + character !== PADDING && + !ALPHABET.includes(character) + ) + return false; + // The first two characters keep latitude below 90 and longitude below 180. + if (ALPHABET.indexOf(code[0]) * 20 >= 180) return false; + if (ALPHABET.indexOf(code[1]) * 20 >= 360) return false; + return true; +} + +/** + * The centre of a full plus code as `{ lat, lon }`, or null. + * @param {string} text + */ +export function parsePlusCode(text) { + if (typeof text !== 'string') return null; + const code = text.trim().toUpperCase(); + if (!code || code.length > 32 || !isFullCode(code)) return null; + const digits = code + .replace(SEPARATOR, '') + .replace(/0+$/, '') + .slice(0, MAX_LENGTH); + let south = -90; + let west = -180; + let latStep = 400; + let lonStep = 400; + // Pairs: alternating latitude and longitude digits in base 20. + for (let i = 0; i < Math.min(digits.length, PAIR_LENGTH); i += 2) { + latStep /= 20; + lonStep /= 20; + south += ALPHABET.indexOf(digits[i]) * latStep; + if (i + 1 < digits.length) + west += ALPHABET.indexOf(digits[i + 1]) * lonStep; + } + // Beyond ten digits, each one picks a cell of a 4 × 5 grid. + for (let i = PAIR_LENGTH; i < digits.length; i += 1) { + latStep /= GRID_ROWS; + lonStep /= GRID_COLUMNS; + const index = ALPHABET.indexOf(digits[i]); + south += Math.floor(index / GRID_COLUMNS) * latStep; + west += (index % GRID_COLUMNS) * lonStep; + } + const lat = Math.min(90, south + latStep / 2); + let lon = west + lonStep / 2; + if (lon >= 180) lon -= 360; + return { lat, lon }; +} From d91c513e071b78493a64f984c57086440f8fa2f9 Mon Sep 17 00:00:00 2001 From: Sameh Khamis Date: Sun, 15 Nov 2026 09:41:43 -0800 Subject: [PATCH 11/13] Changelog fragment for #1750 --- changelog.d/1750-search-coordinate-formats.md | 6 ++++++ 1 file changed, 6 insertions(+) create mode 100644 changelog.d/1750-search-coordinate-formats.md diff --git a/changelog.d/1750-search-coordinate-formats.md b/changelog.d/1750-search-coordinate-formats.md new file mode 100644 index 000000000..f6dbc4af3 --- /dev/null +++ b/changelog.d/1750-search-coordinate-formats.md @@ -0,0 +1,6 @@ +- Search reads coordinates written the other common ways, with no geocoder + or key: degrees, minutes and seconds (`40°26'46"N 79°58'56"W`), UTM + (`18T 585628 4511322`), MGRS (`18T WL 85650 11369`) and full plus codes + (`849VCWC8+R9`). Before, these went to the geocoders, which matched them + to some place by name or found nothing. Like decimal degrees, a query + either reads exactly or goes to the geocoders as before. From 262de71fec24a558362af21d63691c3ba0b540ba Mon Sep 17 00:00:00 2001 From: Sameh Khamis Date: Sun, 15 Nov 2026 09:48:35 -0800 Subject: [PATCH 12/13] Grid references decline dates and short words in capitals: MGRS to 100 m or finer, within its zone, not spelling a month; UTM N reads as the northern hemisphere --- src/search/gridReference.js | 79 ++++++++++++++++++++++++------- src/search/gridReference.test.mjs | 47 ++++++++++++++++-- 2 files changed, 103 insertions(+), 23 deletions(-) diff --git a/src/search/gridReference.js b/src/search/gridReference.js index db890f492..180877e99 100644 --- a/src/search/gridReference.js +++ b/src/search/gridReference.js @@ -3,14 +3,17 @@ * * Strict, like the decimal parser: a reference either reads exactly or is * declined. UTM is `18T 585628 4511322` (zone, latitude band, easting, - * northing); MGRS is `18T WL 85650 11369`, spaced or not, with 1 to 5 digits - * each for easting and northing. MGRS letters are capitals, as references are - * printed, unless written unspaced to 100 m or finer (`18twl856113`): - * lower-case `1 jan 2023` or `3 usa 12` is ordinary text, not a grid square. The polar UPS bands (A, B, - * Y, Z) and the zones Svalbard does not use (32X, 34X, 36X) decline. A UTM `S` - * is the 32°N–40°N band when its northing falls in that band, and otherwise - * the southern hemisphere, as UTM is also written; a southern reference - * between about 50°S and 58°S written that way reads as band S. + * northing); MGRS is `18T WL 85650 11369`, spaced or not, with 3 to 5 digits + * each for easting and northing (100 m to 1 m). Coarser MGRS (`18T WL 8511`) + * declines: written that way, `1 JAN 2023`, `3 USA 12` or `20 KPH 1000` would + * read as grid squares. MGRS letters are capitals, as references are printed, + * unless written unspaced (`18twl856113`), and the square must lie in its + * zone. Letters that spell a month (`1 JAN 2023 1200`) decline: a date is far + * likelier than one of those few squares. The polar UPS bands (A, B, Y, Z) and the zones Svalbard does not use + * (32X, 34X, 36X) decline. A UTM `N` or `S` is the latitude band when its + * northing falls in that band, and otherwise the hemisphere, as UTM is also + * written (`33N 500000 4500000`); a southern reference between about 50°S and + * 58°S written with `S` reads as band S. */ /** WGS84. */ @@ -112,6 +115,21 @@ function zoneExists(zone, band) { return !(band === 'X' && (zone === 32 || zone === 34 || zone === 36)); } +/** Svalbard's widened zones in band X, as [west, east] longitudes. */ +const SVALBARD_ZONES = { 31: [0, 9], 33: [9, 21], 35: [21, 33], 37: [33, 42] }; + +/** + * The longitudes a zone covers in a band: 6° each, except southwest Norway + * (31V is 0°–3°E, 32V is 3°E–12°E) and Svalbard (band X). + */ +function zoneLongitudes(zone, band) { + if (band === 'V' && zone === 31) return [0, 3]; + if (band === 'V' && zone === 32) return [3, 12]; + if (band === 'X' && SVALBARD_ZONES[zone]) return SVALBARD_ZONES[zone]; + const west = (zone - 1) * 6 - 180; + return [west, west + 6]; +} + /** UTM `18T 585628 4511322` (or `18 T 585628 4511322`), or null. */ function parseUtm(text) { const match = @@ -136,9 +154,13 @@ function parseUtm(text) { const asBand = utmToLatLon(zone, easting, northing, range.south < 0); const bandFits = inBand(asBand.lat, range); if (bandFits) return asBand; - // `S` is also how UTM is written for the southern hemisphere. Where both + // `N` and `S` are also how UTM is written for the hemispheres. Where both // fit, the 32°N–40°N band (Tokyo, Los Angeles, the Mediterranean) is far // likelier than 50°S–58°S, so the band wins above. + if (letter === 'N') { + const north = utmToLatLon(zone, easting, northing, false); + if (north.lat >= 0 && north.lat <= 84) return north; + } if (letter === 'S') { const south = utmToLatLon(zone, easting, northing, true); if (south.lat < 0 && south.lat >= -80) return south; @@ -173,13 +195,26 @@ const BAND_MIN_NORTHING = { X: 7900000, }; +/** Month abbreviations a band and square could spell (`JAN`, `SEP`, …). */ +const MONTHS = new Set([ + 'JAN', + 'FEB', + 'MAR', + 'MAY', + 'JUN', + 'JUL', + 'SEP', + 'NOV', + 'DEC', +]); + /** * MGRS as `18TWL8565011369`, `18T WL 8565011369` or `18T WL 85650 11369` * (easting and northing the same length), or null. */ function parseMgrs(text) { const match = - /^(\d{1,2})\s*([C-HJ-NP-X])\s*([A-HJ-NP-Z])([A-HJ-NP-V])(?:\s*(\d{2,10})|\s*(\d{1,5})\s+(\d{1,5}))$/i.exec( + /^(\d{1,2})\s*([C-HJ-NP-X])\s*([A-HJ-NP-Z])([A-HJ-NP-V])(?:\s*(\d{6,10})|\s*(\d{3,5})\s+(\d{3,5}))$/i.exec( text, ); if (!match) return null; @@ -187,8 +222,8 @@ function parseMgrs(text) { const band = match[2].toUpperCase(); const column = match[3].toUpperCase(); const row = match[4].toUpperCase(); - let east = ''; - let north = ''; + let east; + let north; if (match[5]) { if (match[5].length % 2) return null; east = match[5].slice(0, match[5].length / 2); @@ -200,8 +235,8 @@ function parseMgrs(text) { if (zone < 1 || zone > 60 || !zoneExists(zone, band)) return null; const precision = east.length; const letters = text.replace(/[\d\s]/g, ''); - if (letters !== letters.toUpperCase() && (precision < 3 || /\s/.test(text))) - return null; + if (MONTHS.has(letters.toUpperCase())) return null; + if (letters !== letters.toUpperCase() && /\s/.test(text)) return null; const columnIndex = COLUMN_SETS[(zone - 1) % 3].indexOf(column); if (columnIndex < 0) return null; // Rows start at A in odd zones and at F in even ones. @@ -210,13 +245,21 @@ function parseMgrs(text) { const scale = 10 ** (5 - precision); // The centre of the square the digits name; a 1 m reference is its corner. const half = precision < 5 ? scale / 2 : 0; - const easting = (columnIndex + 1) * 100000 + Number(east || 0) * scale + half; - let northing = rowIndex * 100000 + Number(north || 0) * scale + half; + const easting = (columnIndex + 1) * 100000 + Number(east) * scale + half; + let northing = rowIndex * 100000 + Number(north) * scale + half; while (northing < BAND_MIN_NORTHING[band]) northing += 2000000; const range = bandRange(band); const point = utmToLatLon(zone, easting, northing, range.south < 0); - // Slack of the square's size in degrees of latitude. - return inBand(point.lat, range, scale / 111000) ? point : null; + // Slack of the square's size in degrees of latitude, and in longitude at + // that latitude. + const slack = scale / 111000; + if (!inBand(point.lat, range, slack)) return null; + const [zoneWest, zoneEast] = zoneLongitudes(zone, band); + const lonSlack = + slack / Math.max(Math.cos((point.lat * Math.PI) / 180), 0.01); + return point.lon >= zoneWest - lonSlack && point.lon <= zoneEast + lonSlack + ? point + : null; } /** diff --git a/src/search/gridReference.test.mjs b/src/search/gridReference.test.mjs index aa111400a..94ab1867f 100644 --- a/src/search/gridReference.test.mjs +++ b/src/search/gridReference.test.mjs @@ -226,7 +226,7 @@ test('MGRS and UTM references read to within a metre in every latitude band', () } }); -test('MGRS reads spaced, unspaced and at every precision', () => { +test('MGRS reads spaced and unspaced, to 100 m or finer', () => { const times = { lat: 40.74882, lon: -73.98543 }; for (const text of [ '18TWL8565011369', @@ -237,10 +237,35 @@ test('MGRS reads spaced, unspaced and at every precision', () => { assert.ok(metres(parseGridReference(text), times) < 1, text); // Coarser references name the centre of their square. assert.ok(metres(parseGridReference('18TWL856113'), times) < 71, '100 m'); - assert.ok(metres(parseGridReference('18TWL8511'), times) < 710, '1 km'); - assert.ok(metres(parseGridReference('18TWL81'), times) < 7100, '10 km'); - // A square with no digits is not enough to go on. - assert.equal(parseGridReference('18TWL'), null); + assert.ok(metres(parseGridReference('18T WL 856 113'), times) < 71, '100 m'); + assert.ok(metres(parseGridReference('18TWL85651136'), times) < 8, '10 m'); + // 1 km and 10 km squares, and a square alone, read too much ordinary text. + for (const text of ['18TWL8511', '18T WL 85 11', '18TWL81', '18TWL']) + assert.equal(parseGridReference(text), null, text); +}); + +test('MGRS squares across a zone edge, Norway and Svalbard', () => { + // Paris, the Eiffel Tower. + assert.ok( + metres(parseGridReference('31U DQ 48251 11932'), { + lat: 48.85819, + lon: 2.29449, + }) < 1, + ); + // 32V is widened to 3°E–12°E, 33X to 9°E–21°E. + assert.ok(parseGridReference('32V NM 12345 54321')); + assert.ok(parseGridReference('33X VG 12345 67890')); + // A square that lands outside its zone's longitudes. + assert.equal(parseGridReference('18T SL 50000 50000'), null); +}); + +test('a UTM N is the northern hemisphere where band N does not fit', () => { + const point = parseGridReference('33N 500000 4500000'); + assert.ok( + Math.abs(point.lon - 15) < 1e-9 && point.lat > 40 && point.lat < 41, + ); + // Within 0°–8°N it is band N, the same projection. + assert.ok(parseGridReference('33N 500000 500000').lat < 5); }); test('a UTM S is the 32°N–40°N band where it fits, else the southern hemisphere', () => { @@ -278,6 +303,18 @@ test('malformed grid references are refused', () => { '1the12', '60 jun 202311', '18t wl 85650 11369', + // The same text in capitals, as dates and units are often written. + '1 JAN 2023', + '01 JAN 2023', + '1JAN2023', + '31 DEC 1999', + '25 DEC 2025', + '1 JAN 2023 1200', + '15 SEP 2024 0630', + '3 USA 12', + '4 GAS 12', + '33 UTC 12', + '20 KPH 1000', // Zones Svalbard does not use. '32X 500000 8700000', '34X NG 12 34', From 6a4202242d6a8a4c3b6508afaf9980a51825e121 Mon Sep 17 00:00:00 2001 From: Sameh Khamis Date: Sun, 15 Nov 2026 09:50:44 -0800 Subject: [PATCH 13/13] MGRS squares touching the antimeridian read: the zone check compares longitudes unwrapped --- src/search/gridReference.js | 6 +++++- src/search/gridReference.test.mjs | 3 +++ 2 files changed, 8 insertions(+), 1 deletion(-) diff --git a/src/search/gridReference.js b/src/search/gridReference.js index 180877e99..c8648c4d5 100644 --- a/src/search/gridReference.js +++ b/src/search/gridReference.js @@ -257,7 +257,11 @@ function parseMgrs(text) { const [zoneWest, zoneEast] = zoneLongitudes(zone, band); const lonSlack = slack / Math.max(Math.cos((point.lat * Math.PI) / 180), 0.01); - return point.lon >= zoneWest - lonSlack && point.lon <= zoneEast + lonSlack + // Compare across the antimeridian unwrapped: zone 1 starts at 180°W. + let lon = point.lon; + if (lon - zoneWest > 180) lon -= 360; + if (zoneEast - lon > 180) lon += 360; + return lon >= zoneWest - lonSlack && lon <= zoneEast + lonSlack ? point : null; } diff --git a/src/search/gridReference.test.mjs b/src/search/gridReference.test.mjs index 94ab1867f..6f2551542 100644 --- a/src/search/gridReference.test.mjs +++ b/src/search/gridReference.test.mjs @@ -257,6 +257,9 @@ test('MGRS squares across a zone edge, Norway and Svalbard', () => { assert.ok(parseGridReference('33X VG 12345 67890')); // A square that lands outside its zone's longitudes. assert.equal(parseGridReference('18T SL 50000 50000'), null); + // Squares touching the antimeridian, from either side. + for (const text of ['1HBD1970044714', '60TYQ364873', '1QAC860142']) + assert.ok(parseGridReference(text), text); }); test('a UTM N is the northern hemisphere where band N does not fit', () => {