/** * Camera policy for the orbital (satellite) view: the eye rides the tracked * satellite and looks straight down at the Earth's centre. Satellites publish * no attitude, so the picture is turned to the ground track (track-up; see * nadirOrientation's `headingDeg`), or north-up for a satellite with none * (geostationary). This module holds the zoom steps, * the field of view, the nadir orientation, the ground footprint and the zoom * transition curves. No DOM, Cesium or i18n dependencies: vectors are plain * `{x, y, z}` objects in Earth-fixed (ECEF) metres, so the policy is * unit-testable and the Cockpit camera copies them into its own scratch. */ /** Mean Earth radius used for footprint and framing geometry, metres. */ export const ORBITAL_EARTH_RADIUS_M = 6371008.8; /** * The whole zoom ladder. Steps past ORBITAL_BASE_MAX_ZOOM belong only to * imaging satellites with a known sensor, each up to the step its sensor's * swath allows (`orbitalMaxZoom`). */ export const ORBITAL_ZOOM_LADDER = Object.freeze([1, 2, 4, 8, 16, 32, 64, 128]); /** The tightest step for a satellite without sensor data. */ export const ORBITAL_BASE_MAX_ZOOM = 8; /** The zoom an orbital view opens at. */ export const ORBITAL_DEFAULT_ZOOM = 1; /** * Vertical field of view at 1x for low orbits. From the ISS (~420 km) a 60° * frame spans roughly 490 km of ground top to bottom: a regional picture * with the curvature just out of frame, which 8x narrows to ~60 km. */ export const ORBITAL_BASE_FOV_LEO_RAD = (60 * Math.PI) / 180; /** * How much wider than the Earth's disk a high orbit's 1x frame is. A fixed * 60° frame from GEO (~35,786 km) would show a 17° Earth floating in black; * above about 8,000 km the base frame instead fits the whole disk with this * margin, so 1x is "the whole Earth" and the steps zoom into it. */ export const ORBITAL_DISK_MARGIN = 1.15; /** Duration of one zoom step's field-of-view change, ms. */ export const ORBITAL_ZOOM_TRANSITION_MS = 400; /** How long the reticle shows its lock tick after a step settles, ms. */ export const ORBITAL_LOCK_TICK_MS = 220; /** Peak focus-pull blur at the middle of a zoom step, CSS pixels. */ export const ORBITAL_MAX_BLUR_PX = 6; /** * Longest a zoom step holds its focus pull for the new field of view's * imagery, ms. The camera moves at orbital speed, so the tiles may never * all arrive; the hold gives them a start, then the reticle locks anyway. */ export const ORBITAL_SETTLE_MAX_MS = 2500; /** The soft blur held while a step waits for its imagery, CSS pixels. */ export const ORBITAL_SETTLE_BLUR_PX = 2.5; /** Relative slack so a zoom computed in floating point still meets its step. */ const ZOOM_EPSILON = 1e-6; /** * The next tighter ladder step, up to `maxZoom`; at the cap the zoom stays. * A zoom between steps (the SENSOR step) moves to the step above it. * @param {number} zoom Current zoom. * @param {number} [maxZoom] The satellite's tightest step. * @returns {number} */ export function nextOrbitalZoom(zoom, maxZoom = ORBITAL_BASE_MAX_ZOOM) { const current = Number.isFinite(zoom) && zoom > 0 ? zoom : 1; const next = ORBITAL_ZOOM_LADDER.find( (step) => step > current * (1 + ZOOM_EPSILON) && step <= maxZoom, ); return next ?? current; } /** * The next wider ladder step; 1x stays where it is. A zoom between steps * moves to the step below it. * @param {number} zoom Current zoom. * @returns {number} */ export function previousOrbitalZoom(zoom) { const current = Number.isFinite(zoom) && zoom > 0 ? zoom : 1; const wider = ORBITAL_ZOOM_LADDER.filter( (step) => step < current * (1 - ZOOM_EPSILON), ); return wider.length ? wider[wider.length - 1] : ORBITAL_DEFAULT_ZOOM; } /** * The ground width the view spans at a zoom: what the SWATH readout shows. * @param {number} altitudeM Satellite altitude, metres. * @param {number} zoom Magnification. * @param {number} aspect Canvas width / height. * @returns {number|null} Kilometres, or null for an unusable altitude. */ export function viewWidthKm(altitudeM, zoom, aspect) { return footprintWidthKm( altitudeM, fovForZoom(orbitalBaseFovRad(altitudeM), zoom), aspect, ); } /** * A satellite's tightest zoom step at its live altitude: the tightest ladder * step whose view is still at least as wide as its sensor's narrowest * standard swath, so the view never shows finer ground than the sensor * images. Never below ORBITAL_BASE_MAX_ZOOM; no sensor swath, no extra steps. * @param {number} altitudeM Live altitude, metres. * @param {number|null|undefined} sensorSwathKm Narrowest standard swath. * @param {number} aspect Canvas width / height. * @returns {number} One of ORBITAL_ZOOM_LADDER. */ export function orbitalMaxZoom(altitudeM, sensorSwathKm, aspect) { if (!Number.isFinite(sensorSwathKm) || sensorSwathKm <= 0) return ORBITAL_BASE_MAX_ZOOM; let max = ORBITAL_BASE_MAX_ZOOM; for (const step of ORBITAL_ZOOM_LADDER) { if (step <= ORBITAL_BASE_MAX_ZOOM) continue; const width = viewWidthKm(altitudeM, step, aspect); if (!Number.isFinite(width)) break; if (width * (1 + ZOOM_EPSILON) < sensorSwathKm) break; max = step; } return max; } /** * The zoom at which the view is exactly as wide as the sensor's swath, for * the SENSOR step; null when that lies outside 1x..`maxZoom` (a swath wider * than the 1x view, or narrower than the tightest allowed step). * @param {number} altitudeM Live altitude, metres. * @param {number|null|undefined} sensorSwathKm * @param {number} aspect Canvas width / height. * @param {number} maxZoom The satellite's tightest step. * @returns {number|null} */ export function sensorSwathZoom(altitudeM, sensorSwathKm, aspect, maxZoom) { if (!Number.isFinite(sensorSwathKm) || sensorSwathKm <= 0) return null; const widest = viewWidthKm(altitudeM, 1, aspect); const tightest = viewWidthKm(altitudeM, maxZoom, aspect); if (!Number.isFinite(widest) || !Number.isFinite(tightest)) return null; if (sensorSwathKm > widest * (1 + ZOOM_EPSILON)) return null; if (sensorSwathKm < tightest * (1 - ZOOM_EPSILON)) return null; // The width falls monotonically with zoom: bisect in log space. let low = 0; let high = Math.log2(maxZoom); for (let i = 0; i < 48; i += 1) { const mid = (low + high) / 2; if (viewWidthKm(altitudeM, 2 ** mid, aspect) > sensorSwathKm) low = mid; else high = mid; } return Math.round(2 ** ((low + high) / 2) * 100) / 100; } /** * How much of the view's width a sensor swath covers, for the strip drawn * to scale in the reticle: 0..1, 1 when the swath fills the view or more. * @param {number|null|undefined} sensorSwathKm * @param {number|null|undefined} viewKm The view's current ground width. * @returns {number|null} Null without both widths. */ export function sensorStripFraction(sensorSwathKm, viewKm) { if (!Number.isFinite(sensorSwathKm) || sensorSwathKm <= 0) return null; if (!Number.isFinite(viewKm) || viewKm <= 0) return null; return Math.min(1, sensorSwathKm / viewKm); } /** * Angular radius of the Earth's disk seen from an altitude, radians. * @param {number} altitudeM Height above the mean sphere, metres. * @returns {number} Half-angle from nadir to the limb (π/2 at the surface). */ export function earthAngularRadiusRad(altitudeM) { const h = Math.max(0, Number.isFinite(altitudeM) ? altitudeM : 0); return Math.asin(ORBITAL_EARTH_RADIUS_M / (ORBITAL_EARTH_RADIUS_M + h)); } /** * Vertical field of view at 1x for an altitude, radians. * * Low orbits get the fixed 60° regional frame. Higher orbits, where 60° would * leave the Earth small in a black frame, get the Earth's disk plus * ORBITAL_DISK_MARGIN. The two meet near 8,100 km, so the base never jumps * as an eccentric orbit climbs: GPS (~20,200 km) opens at ~32°, GEO at ~20°. * @param {number} altitudeM Satellite altitude, metres. * @returns {number} Vertical field of view, radians. */ export function orbitalBaseFovRad(altitudeM) { const diskFov = 2 * earthAngularRadiusRad(altitudeM) * ORBITAL_DISK_MARGIN; return Math.min(ORBITAL_BASE_FOV_LEO_RAD, diskFov); } /** * Field of view at an optical zoom: magnification divides the tangent of * the half-angle, as a lens's focal length does. * @param {number} baseFovRad Field of view at 1x, radians. * @param {number} zoom Magnification (1 leaves the base unchanged). * @returns {number} Field of view, radians. */ export function fovForZoom(baseFovRad, zoom) { const magnification = Number.isFinite(zoom) && zoom > 0 ? zoom : 1; return 2 * Math.atan(Math.tan(baseFovRad / 2) / magnification); } /** * Cesium's `PerspectiveFrustum.fov` is horizontal on a landscape canvas and * vertical on a portrait one; convert a vertical field of view to it. * @param {number} verticalFovRad Vertical field of view, radians. * @param {number} aspect Canvas width / height. * @returns {number} The value to assign to `frustum.fov`, radians. */ export function cesiumFrustumFovRad(verticalFovRad, aspect) { if (!(aspect > 1)) return verticalFovRad; return 2 * Math.atan(Math.tan(verticalFovRad / 2) * aspect); } /** * Ground width covered across the frame, along a great circle through the * sub-satellite point, km. A ray past the limb ends at the horizon, so a * frame wider than the disk reports the visible cap's width. * @param {number} altitudeM Satellite altitude, metres. * @param {number} fovRad Vertical field of view, radians. * @param {number} [aspect=1] Frame width / height; the width is measured * across the wider horizontal extent. * @returns {number|null} Width in kilometres, or null without a usable input. */ export function footprintWidthKm(altitudeM, fovRad, aspect = 1) { if (!Number.isFinite(altitudeM) || altitudeM <= 0) return null; if (!Number.isFinite(fovRad) || fovRad <= 0) return null; const ratio = Number.isFinite(aspect) && aspect > 0 ? aspect : 1; const halfAngle = Math.atan(Math.tan(fovRad / 2) * ratio); const R = ORBITAL_EARTH_RADIUS_M; const sinGround = ((R + altitudeM) / R) * Math.sin(halfAngle); // Central angle from nadir to where the ray meets the sphere, or the limb. const central = sinGround >= 1 ? Math.acos(R / (R + altitudeM)) : Math.asin(sinGround) - halfAngle; return (2 * R * central) / 1000; } function length(v) { return Math.hypot(v.x, v.y, v.z); } function scale(v, s) { return { x: v.x * s, y: v.y * s, z: v.z * s }; } function dot(a, b) { return a.x * b.x + a.y * b.y + a.z * b.z; } function cross(a, b) { return { x: a.y * b.z - a.z * b.y, y: a.z * b.x - a.x * b.z, z: a.x * b.y - a.y * b.x, }; } /** `v` with its component along unit `d` removed, or null when degenerate. */ function perpendicularUnit(v, d) { const along = dot(v, d); const p = { x: v.x - along * d.x, y: v.y - along * d.y, z: v.z - along * d.z, }; const n = length(p); return n > 1e-6 ? scale(p, 1 / n) : null; } const NORTH_AXIS = Object.freeze({ x: 0, y: 0, z: 1 }); /** * Camera orientation looking from an Earth-fixed position at the Earth's * centre, with north at the top of the frame. * * `up` is the Earth's rotation axis projected perpendicular to the view, which * is local north at the sub-satellite point. Directly over a pole north is * undefined; the previous frame's `up` is kept when given (so a polar pass * does not spin the picture), otherwise the limit along the prime meridian * is used: over the north pole the top of the frame faces 180°E, over the * south pole 0°E. * * With `headingDeg` the frame turns so that bearing (degrees clockwise from * north) is at the top: the ground track, for a view that scrolls along it. * @param {{x: number, y: number, z: number}} position ECEF position, metres. * @param {{previousUp?: {x: number, y: number, z: number}|null, * headingDeg?: number|null}} [options] `previousUp` is a previous frame's * `north`, not its turned `up`. * @returns {{direction: {x: number, y: number, z: number}, * up: {x: number, y: number, z: number}, * right: {x: number, y: number, z: number}, * north: {x: number, y: number, z: number}}|null} Unit vectors (right = * direction × up, as Cesium's camera keeps them), or null at the centre. */ export function nadirOrientation( position, { previousUp = null, headingDeg = null } = {}, ) { if (!position) return null; const r = length(position); if (!Number.isFinite(r) || r < 1) return null; const direction = scale(position, -1 / r); let up = perpendicularUnit(NORTH_AXIS, direction); if (!up && previousUp && Number.isFinite(length(previousUp))) up = perpendicularUnit(previousUp, direction); if (!up) { // Looking down -z (north pole): north at longitude 0 points along -x. up = perpendicularUnit( { x: direction.z < 0 ? -1 : 1, y: 0, z: 0 }, direction, ); } const north = up; if (Number.isFinite(headingDeg) && headingDeg % 360 !== 0) { // Looking down, right = direction × north is east: the bearing turns // north toward it. const east = cross(direction, north); const θ = (headingDeg * Math.PI) / 180; up = { x: north.x * Math.cos(θ) + east.x * Math.sin(θ), y: north.y * Math.cos(θ) + east.y * Math.sin(θ), z: north.z * Math.cos(θ) + east.z * Math.sin(θ), }; } return { direction, up, right: cross(direction, up), north }; } /** * Ease-in-out progress of a zoom step (cubic), clamped to 0..1. * @param {number} elapsedMs Time since the step began. * @param {{durationMs?: number, reducedMotion?: boolean}} [options] * Reduced motion cuts straight to the end. * @returns {number} Eased progress, 0..1. */ export function zoomTransitionProgress( elapsedMs, { durationMs = ORBITAL_ZOOM_TRANSITION_MS, reducedMotion = false } = {}, ) { if (reducedMotion || !(durationMs > 0)) return 1; const linear = Math.min(1, Math.max(0, (elapsedMs || 0) / durationMs)); return linear < 0.5 ? 4 * linear ** 3 : 1 - (-2 * linear + 2) ** 3 / 2; } /** * Focus-pull blur for a zoom step: zero at both ends, peaking mid-step. * @param {number} progress Step progress, 0..1 (linear or eased). * @param {{maxBlurPx?: number, reducedMotion?: boolean}} [options] * Reduced motion never blurs. * @returns {number} Blur radius, CSS pixels. */ export function zoomTransitionBlurPx( progress, { maxBlurPx = ORBITAL_MAX_BLUR_PX, reducedMotion = false } = {}, ) { if (reducedMotion || !Number.isFinite(progress)) return 0; const p = Math.min(1, Math.max(0, progress)); return Math.max(0, maxBlurPx) * Math.sin(Math.PI * p); } /** * Field of view part-way through a zoom step. Interpolates the tangent of * the half-angle geometrically, so each moment of the step magnifies by the * same ratio and 1x→2x feels like 4x→8x. * @param {number} fromFovRad Field of view the step starts at. * @param {number} toFovRad Field of view the step ends at. * @param {number} progress Eased progress, 0..1. * @returns {number} Field of view, radians. */ export function interpolateZoomFov(fromFovRad, toFovRad, progress) { const p = Math.min(1, Math.max(0, Number.isFinite(progress) ? progress : 1)); const a = Math.log(Math.tan(fromFovRad / 2)); const b = Math.log(Math.tan(toFovRad / 2)); return 2 * Math.atan(Math.exp(a + (b - a) * p)); } /** * The HUD's transition state at a moment of a zoom step, in the store shape * `{ active, blurPx, lockTick }`: blur while the field of view moves, then a * brief reticle lock tick once it settles. Reduced motion skips the blur and * the tick (the cut is instant). * @param {number} elapsedMs Time since the step began. * @param {{durationMs?: number, lockTickMs?: number, maxBlurPx?: number, * reducedMotion?: boolean}} [options] * @returns {{active: boolean, progress: number, blurPx: number, * lockTick: boolean}} */ export function zoomTransitionState( elapsedMs, { durationMs = ORBITAL_ZOOM_TRANSITION_MS, lockTickMs = ORBITAL_LOCK_TICK_MS, maxBlurPx = ORBITAL_MAX_BLUR_PX, reducedMotion = false, } = {}, ) { const progress = zoomTransitionProgress(elapsedMs, { durationMs, reducedMotion, }); if (reducedMotion) return { active: false, progress: 1, blurPx: 0, lockTick: false }; const elapsed = Math.max(0, elapsedMs || 0); const linear = durationMs > 0 ? Math.min(1, elapsed / durationMs) : 1; return { active: elapsed < durationMs, progress, blurPx: zoomTransitionBlurPx(linear, { maxBlurPx }), lockTick: elapsed >= durationMs && elapsed < durationMs + lockTickMs, }; } /** * Whether a zoom step whose field of view has landed still holds its focus * pull: until the imagery has loaded, at most `maxHoldMs`. * @param {number} sinceLandedMs Time since the field of view stopped moving. * @param {boolean} tilesLoaded Whether the scene's imagery has loaded. * @param {{maxHoldMs?: number}} [options] */ export function zoomSettleHolding( sinceLandedMs, tilesLoaded, { maxHoldMs = ORBITAL_SETTLE_MAX_MS } = {}, ) { return !tilesLoaded && Math.max(0, sinceLandedMs || 0) < maxHoldMs; } /** * The total angle between a tilted view and nadir, degrees: * acos(cos north · cos east), as `offNadirOrientation` tilts. * @param {{northDeg?: number, eastDeg?: number}} [offset] Tilt in degrees. * @returns {number} */ export function offNadirAngleDeg({ northDeg = 0, eastDeg = 0 } = {}) { const n = ((Number.isFinite(northDeg) ? northDeg : 0) * Math.PI) / 180; const e = ((Number.isFinite(eastDeg) ? eastDeg : 0) * Math.PI) / 180; const cosine = Math.min(1, Math.max(-1, Math.cos(n) * Math.cos(e))); return (Math.acos(cosine) * 180) / Math.PI; } /** * Whether the view's centre, tilted off nadir, still meets the Earth: its * angle from nadir (`offNadirAngleDeg`) is within the Earth's angular radius * from the satellite, asin(R / (R + altitude)). * @param {number} altitudeM * @param {{northDeg?: number, eastDeg?: number}} [offset] * @returns {boolean} */ export function offNadirCentreMeetsEarth(altitudeM, offset = {}) { if (!Number.isFinite(altitudeM) || altitudeM <= 0) return false; const R = ORBITAL_EARTH_RADIUS_M; const limbDeg = (Math.asin(R / (R + altitudeM)) * 180) / Math.PI; return offNadirAngleDeg(offset) < limbDeg; } /** * Roughly how much wider the ground across the frame is at the centre of a * tilted view than at nadir, on a flat Earth: tilting across the frame (east, * the frame's right) stretches its width by 1/cos², tilting along it (north, * the frame's top) by 1/cos. 1 at nadir; an approximation, so the HUD marks * the width it scales with ≈. * @param {{northDeg?: number, eastDeg?: number}} [offset] Tilt in degrees. * @returns {number} At least 1. */ export function offNadirSwathScale({ northDeg = 0, eastDeg = 0 } = {}) { const n = ((Number.isFinite(northDeg) ? northDeg : 0) * Math.PI) / 180; const e = ((Number.isFinite(eastDeg) ? eastDeg : 0) * Math.PI) / 180; const along = Math.abs(Math.cos(n)); const across = Math.cos(e) ** 2; if (!(along > 1e-6) || !(across > 1e-6)) return 1; return Math.max(1, 1 / (along * across)); } /** * Tilt a nadir orientation off nadir: first toward north (a rotation about * the nadir frame's right axis), then toward east (about the tilted up * axis). The base frame is always the nadir one, so a tilt never drifts with * the orbit; the angle from nadir is acos(cos north · cos east). * @param {{direction: object, up: object, right: object}} nadir From * {@link nadirOrientation}. * @param {{northDeg?: number, eastDeg?: number}} [offset] Tilt in degrees; * negative is south or west. * @returns {{direction: object, up: object, right: object}} Unit vectors, * right = direction × up. */ export function offNadirOrientation(nadir, { northDeg = 0, eastDeg = 0 } = {}) { const n = ((Number.isFinite(northDeg) ? northDeg : 0) * Math.PI) / 180; const e = ((Number.isFinite(eastDeg) ? eastDeg : 0) * Math.PI) / 180; if (n === 0 && e === 0) return nadir; const { direction: d, up: u, right: r } = nadir; const combine = (a, ka, b, kb) => ({ x: a.x * ka + b.x * kb, y: a.y * ka + b.y * kb, z: a.z * ka + b.z * kb, }); // Toward north: the view swings onto the up axis, up swings off it. const d1 = combine(d, Math.cos(n), u, Math.sin(n)); const u1 = combine(u, Math.cos(n), d, -Math.sin(n)); // Toward east: the view swings onto the right axis. const direction = combine(d1, Math.cos(e), r, Math.sin(e)); return { direction, up: u1, right: cross(direction, u1) }; } /** Scroll distance, in pixels, that makes one zoom step. A mouse notch is ~100. */ export const ORBITAL_WHEEL_PIXELS_PER_STEP = 100; /** * After a step, the rest of that gesture is absorbed for this long, so one * physical notch (which some browsers deliver as several events) is one step. */ export const ORBITAL_WHEEL_COOLDOWN_MS = 200; /** * A pause this long ends a scroll gesture: a partial sum left from an earlier * gesture never adds to a later one. */ export const ORBITAL_WHEEL_GESTURE_GAP_MS = 300; /** `WheelEvent.deltaMode` line and page units, in pixels. */ const WHEEL_LINE_PX = 16; const WHEEL_PAGE_PX = 800; /** * Turn wheel events into zoom steps. Trackpads send many small pixel deltas, * so they are summed until they reach a step; a change of direction, or a * pause of ORBITAL_WHEEL_GESTURE_GAP_MS, starts over. Wheeling away from the * viewer (negative deltaY) zooms in. * @param {{sum: number, lastStepMs: number, lastEventMs?: number}|null} * accumulator Previous state. * @param {{deltaY: number, deltaMode?: number}} wheel The event's deltas. * @param {number} nowMs * @returns {{accumulator: {sum: number, lastStepMs: number, * lastEventMs: number}, step: -1|0|1}} The new state and the step to take * (1 = zoom in). */ export function wheelZoomStep(accumulator, wheel, nowMs) { const held = accumulator || { sum: 0, lastStepMs: -Infinity }; const previous = nowMs - (held.lastEventMs ?? -Infinity) > ORBITAL_WHEEL_GESTURE_GAP_MS ? { ...held, sum: 0 } : held; const unit = wheel?.deltaMode === 1 ? WHEEL_LINE_PX : wheel?.deltaMode === 2 ? WHEEL_PAGE_PX : 1; const delta = (Number.isFinite(wheel?.deltaY) ? wheel.deltaY : 0) * unit; if (!delta) return { accumulator: held, step: 0 }; if (nowMs - previous.lastStepMs < ORBITAL_WHEEL_COOLDOWN_MS) return { accumulator: { ...previous, sum: 0, lastEventMs: nowMs }, step: 0, }; const sum = Math.sign(previous.sum) === -Math.sign(delta) ? delta : previous.sum + delta; if (Math.abs(sum) < ORBITAL_WHEEL_PIXELS_PER_STEP) return { accumulator: { ...previous, sum, lastEventMs: nowMs }, step: 0 }; return { accumulator: { sum: 0, lastStepMs: nowMs, lastEventMs: nowMs }, step: sum < 0 ? 1 : -1, }; } /** From this zoom the view pre-loads imagery ahead along the ground track. */ export const ORBITAL_PREFETCH_MIN_ZOOM = 16; /** How often the pre-load looks ahead, ms. */ export const ORBITAL_PREFETCH_INTERVAL_MS = 2000; /** How far ahead it looks, seconds of ground-track travel, nearest first. */ export const ORBITAL_PREFETCH_LEAD_S = Object.freeze([5, 10, 15, 20]); /** * Where across the track it looks, as fractions of the view's width: the * centre line, a third out and the frame's edges each side, so a row of * tiles a fifth of the view wide or more spans the frame. */ export const ORBITAL_PREFETCH_ACROSS = Object.freeze([ 0, -1 / 3, 1 / 3, -1 / 2, 1 / 2, ]); /** * The points ahead, regrouped by their place across the track: every lead's * centre point first, then each lead's next pair out, so the tile cap trims * the frame's edges before it trims the far leads. * @param {Array<{lat: number, lon: number}>} points From `groundTrackAhead`, * lead by lead. * @param {number} [across] Points per lead. * @returns {Array<{lat: number, lon: number}>} */ export function centreLinesFirst( points, across = ORBITAL_PREFETCH_ACROSS.length, ) { const out = []; for (let k = 0; k < across; k += 1) for (let i = k; i < points.length; i += across) out.push(points[i]); return out; } /** At most this many tile requests per look-ahead. */ export const ORBITAL_PREFETCH_MAX_TILES = 12; const toRadians = (deg) => (deg * Math.PI) / 180; const toDegrees = (rad) => (rad * 180) / Math.PI; /** * The point `distanceM` from a point along an initial bearing, on a sphere. * @returns {{lat: number, lon: number}} Degrees, longitude in -180..180. */ export function destinationPoint(latDeg, lonDeg, bearingDeg, distanceM) { const delta = distanceM / ORBITAL_EARTH_RADIUS_M; const lat1 = toRadians(latDeg); const theta = toRadians(bearingDeg); const lat2 = Math.asin( Math.sin(lat1) * Math.cos(delta) + Math.cos(lat1) * Math.sin(delta) * Math.cos(theta), ); const lon2 = toRadians(lonDeg) + Math.atan2( Math.sin(theta) * Math.sin(delta) * Math.cos(lat1), Math.cos(delta) - Math.sin(lat1) * Math.sin(lat2), ); const lon = ((((toDegrees(lon2) + 180) % 360) + 360) % 360) - 180; return { lat: toDegrees(lat2), lon }; } /** * Points the view will pass over: for each lead time, the sub-satellite * point that far along the ground track (orbital speed scaled down to the * ground), and points across the track at `across` fractions of the view's * width. Nearest lead first. Empty without a track, speed or width. * @param {{latitude: number, longitude: number, groundTrackDeg: number, * velocityMps: number, altitudeM: number}} info Satellite subject. * @param {number} viewKm The view's ground width, km. * @returns {Array<{lat: number, lon: number}>} */ export function groundTrackAhead( info, viewKm, { leadS = ORBITAL_PREFETCH_LEAD_S, across = ORBITAL_PREFETCH_ACROSS } = {}, ) { const { latitude, longitude, groundTrackDeg, velocityMps, altitudeM } = info || {}; if ( ![latitude, longitude, groundTrackDeg, velocityMps, altitudeM].every( Number.isFinite, ) || velocityMps <= 0 || altitudeM <= 0 || !(viewKm > 0) ) return []; const R = ORBITAL_EARTH_RADIUS_M; const groundMps = (velocityMps * R) / (R + altitudeM); const points = []; for (const seconds of leadS) { const centre = destinationPoint( latitude, longitude, groundTrackDeg, groundMps * seconds, ); for (const fraction of across) { points.push( fraction === 0 ? centre : destinationPoint( centre.lat, centre.lon, groundTrackDeg + (fraction > 0 ? 90 : -90), Math.abs(fraction) * viewKm * 1000, ), ); } } return points; } /** WGS84's equatorial radius: Cesium sizes terrain and imagery tiles on it. */ const WGS84_MAXIMUM_RADIUS_M = 6378137; /** * Cesium's geometric error for a heightmap terrain tile at `level`, metres: * its level-zero estimate (TerrainProvider's * getEstimatedLevelZeroGeometricErrorForAHeightmap, heightmap quality 0.25) * for the ellipsoid terrain's 64-sample tiles on two root tiles, halved per * level. * @param {number} level * @returns {number} */ export function ellipsoidTerrainLevelErrorM(level) { return (WGS84_MAXIMUM_RADIUS_M * 2 * Math.PI * 0.25) / (64 * 2) / 2 ** level; } /** The deepest terrain level considered. */ const MAX_TERRAIN_LEVEL = 30; /** * The imagery level Cesium draws under the view, and so the one to pre-load. * Cesium refines the terrain tile under the view while its geometric error * spans more than `maximumScreenSpaceError` pixels (QuadtreePrimitive's * screenSpaceError: error over the ground a pixel covers), then drapes the * imagery level whose texel spacing is nearest that error (ImageryLayer's * getLevelWithMaximumTexelSpacing, rounded): about one to two screen pixels * per texel, not one. Fog, which below 800 km can only coarsen the choice, * is left out. Clamped to the provider's levels; null without a usable input. * @param {{getNumberOfXTilesAtLevel?: (level: number) => number, * rectangle?: {width: number}}} tilingScheme The imagery tiling scheme. * @param {{metresPerPixel: number, latitudeDeg: number, * geographic?: boolean, tileWidthPx?: number, minimumLevel?: number, * maximumLevel?: number, maximumScreenSpaceError?: number, * terrainLevelErrorM?: (level: number) => number}} view `metresPerPixel` * is the ground one CSS pixel covers at the view's centre; `geographic` * marks a scheme in the geographic projection, whose texels do not narrow * with latitude as Web Mercator's do; `terrainLevelErrorM` is the terrain * provider's getLevelMaximumGeometricError. * @returns {number|null} */ export function imageryLevelForView( tilingScheme, { metresPerPixel, latitudeDeg, geographic = false, tileWidthPx = 256, minimumLevel = 0, maximumLevel = 30, maximumScreenSpaceError = 2, terrainLevelErrorM = ellipsoidTerrainLevelErrorM, }, ) { if (!(metresPerPixel > 0) || !Number.isFinite(latitudeDeg)) return null; const sse = maximumScreenSpaceError > 0 ? maximumScreenSpaceError : 2; let terrainLevel = 0; while ( terrainLevel < MAX_TERRAIN_LEVEL && !(terrainLevelErrorM(terrainLevel) / metresPerPixel <= sse) ) terrainLevel += 1; const errorM = terrainLevelErrorM(terrainLevel); if (!(errorM > 0)) return null; const rootTiles = tilingScheme?.getNumberOfXTilesAtLevel?.(0) || 1; const widthRad = tilingScheme?.rectangle?.width || 2 * Math.PI; const latitudeFactor = geographic ? 1 : Math.cos(toRadians(Math.min(89, Math.abs(latitudeDeg)))); const levelZeroTexelM = (WGS84_MAXIMUM_RADIUS_M * widthRad * latitudeFactor) / ((tileWidthPx || 256) * rootTiles); const level = Math.max(0, Math.round(Math.log2(levelZeroTexelM / errorM))); if (!Number.isFinite(level)) return null; const top = Number.isFinite(maximumLevel) ? maximumLevel : 30; const bottom = Number.isFinite(minimumLevel) ? minimumLevel : 0; return Math.min(top, Math.max(bottom, level)); } /** * The tiles at `level` holding `points`, in order, without repeats or tiles * `skip` reports as already asked for, at most `maxTiles`. * @param {{positionToTileXY: Function}} tilingScheme Cesium tiling scheme. * @param {Array<{lat: number, lon: number}>} points Degrees. * @param {number} level * @param {{maxTiles?: number, skip?: (key: string) => boolean}} [options] * @returns {Array<{x: number, y: number, level: number, key: string}>} */ export function tilesForPoints( tilingScheme, points, level, { maxTiles = ORBITAL_PREFETCH_MAX_TILES, skip = () => false } = {}, ) { const tiles = []; if (typeof tilingScheme?.positionToTileXY !== 'function') return tiles; if (!Number.isInteger(level) || level < 0) return tiles; const seen = new Set(); for (const point of points) { if (tiles.length >= maxTiles) break; const xy = tilingScheme.positionToTileXY( { longitude: toRadians(point.lon), latitude: toRadians(point.lat) }, level, ); if (!xy) continue; const key = `${level}/${xy.x}/${xy.y}`; if (seen.has(key) || skip(key)) continue; seen.add(key); tiles.push({ x: xy.x, y: xy.y, level, key }); } return tiles; }