Pre-load orbital imagery ahead from the Cesium renderer

A narrow, nadir-looking camera moving over the ground asks the base
imagery for the tiles 5 to 20 s ahead, as the orbital view did from 16x
before it moved onto the renderer contract. The renderer works it out
from its own camera: field of view, look and motion over the ground.
This commit is contained in:
Sameh Khamis committed 2026-11-10 01:46:41 -08:00
1 parent e48ed3eb9e
commit 40a0dce951
5 files changed
+639 -7

No files matched your search

+335
View File
@@ -0,0 +1,335 @@
/**
* @module render/cesium/imageryLookAhead
* @description Pre-loads the globe imagery a narrow, nadir-looking, moving
* camera is about to pass over.
*
* A view 10 to 40 km wide carried along an orbit (about 7 km/s over the
* ground) outruns the imagery under it. The renderer watches its own
* camera: once the vertical field of view is as narrow as an orbital view
* at 16x (`ORBITAL_PREFETCH_MIN_ZOOM`) for the camera's height, the camera
* looks straight down and it moves over the ground, it asks the globe's
* base imagery every ORBITAL_PREFETCH_INTERVAL_MS for the tiles the view
* will need 5 to 20 s ahead (`groundTrackAhead`), at the level Cesium will
* draw there (`imageryLevelForView`), so the browser has them cached when
* the view gets there.
*
* The requests are throttled at the lowest priority: Cesium's request
* scheduler declines one while the imagery server's slots are taken by the
* tiles on screen or the scheduler is full, and a declined tile is asked
* again on a later look-ahead. At most ORBITAL_PREFETCH_MAX_TILES a time;
* the last PREFETCH_MEMORY tiles asked for are not asked again unless their
* request was dropped, and a new base map starts the memory over. When the
* view widens again the requests still pending are cancelled and the memory
* starts over. Nothing while the camera is tilted off nadir, with the scene
* clock away from now (paused, played back), with the camera still, or with
* the globe hidden (Google 3D tiles drawn instead).
*/
import * as Cesium from 'cesium';
import {
ORBITAL_EARTH_RADIUS_M,
ORBITAL_PREFETCH_INTERVAL_MS,
ORBITAL_PREFETCH_MAX_TILES,
ORBITAL_PREFETCH_MIN_ZOOM,
centreLinesFirst,
footprintWidthKm,
fovForZoom,
groundTrackAhead,
imageryLevelForView,
orbitalBaseFovRad,
tilesForPoints,
} from '../../cockpitOrbital.js';
/** Tiles remembered as asked for while the view stays narrow. */
const PREFETCH_MEMORY = 512;
/** How far the scene clock may be from now for the look-ahead to run, ms. */
const PREFETCH_LIVE_TOLERANCE_MS = 60_000;
/** The camera's look may stray this far from straight down, radians. */
const NADIR_TOLERANCE_RAD = (0.5 * Math.PI) / 180;
/** Slower over the ground than this, m/s, the camera is not carried along. */
const MIN_GROUND_SPEED_MPS = 100;
/** The camera's motion is measured over at least this long, ms. */
const MOTION_SAMPLE_MS = 250;
/** A motion measured longer ago than this is no longer trusted, ms. */
const MOTION_MAX_AGE_MS = 2 * ORBITAL_PREFETCH_INTERVAL_MS;
const toRadians = (deg) => (deg * Math.PI) / 180;
const toDegrees = (rad) => (rad * 180) / Math.PI;
/**
* The provider of the lowest shown imagery layer, the base map the globe
* drapes, when it can be asked for a tile; else null.
*/
function baseImageryProvider(viewer) {
const layers = viewer.imageryLayers ?? viewer.scene?.imageryLayers;
const count = Number.isInteger(layers?.length) ? layers.length : 0;
for (let i = 0; i < count; i += 1) {
const layer = layers.get(i);
if (!layer || layer.show === false || layer.alpha === 0) continue;
const provider = layer.imageryProvider;
if (
typeof provider?.requestImage === 'function' &&
typeof provider.tilingScheme?.positionToTileXY === 'function'
)
return provider;
return null;
}
return null;
}
/** Great-circle distance, m, and initial bearing, degrees, between points. */
function groundMove(from, to) {
const lat1 = toRadians(from.lat);
const lat2 = toRadians(to.lat);
const dLat = lat2 - lat1;
const dLon = toRadians(to.lon - from.lon);
const a =
Math.sin(dLat / 2) ** 2 +
Math.cos(lat1) * Math.cos(lat2) * Math.sin(dLon / 2) ** 2;
const distanceM =
2 * ORBITAL_EARTH_RADIUS_M * Math.asin(Math.min(1, Math.sqrt(a)));
const bearingDeg = toDegrees(
Math.atan2(
Math.sin(dLon) * Math.cos(lat2),
Math.cos(lat1) * Math.sin(lat2) -
Math.sin(lat1) * Math.cos(lat2) * Math.cos(dLon),
),
);
return { distanceM, bearingDeg };
}
/** True when the camera looks straight down at the point below it. */
function looksAtNadir(camera) {
const position = camera.positionWC ?? camera.position;
const direction = camera.directionWC ?? camera.direction;
if (!position || !direction) return false;
const r = Math.hypot(position.x, position.y, position.z);
const d = Math.hypot(direction.x, direction.y, direction.z);
if (!(r > 0) || !(d > 0)) return false;
const cos =
-(
position.x * direction.x +
position.y * direction.y +
position.z * direction.z
) /
(r * d);
return cos >= Math.cos(NADIR_TOLERANCE_RAD);
}
/**
* Watch the camera each frame and pre-load the imagery ahead of a narrow,
* nadir-looking, moving view.
* @param {object} viewer Cesium viewer.
* @param {{now?: () => number}} [options] `now` is the wall clock, ms.
* @returns {{update: (nowMs?: number) => number, destroy: () => void}}
* `update` runs one frame's check and returns the tiles asked for; the
* viewer's postRender calls it.
*/
export function preloadImageryAhead(viewer, { now = () => Date.now() } = {}) {
let active = false;
let lastAskMs = -Infinity;
let anchor = null;
let motion = null;
let provider = null;
let memory = new Set();
let requests = new Set();
const cancelPending = () => {
for (const request of requests) request.cancel?.();
requests = new Set();
};
const deactivate = () => {
if (!active) return;
active = false;
cancelPending();
memory = new Set();
provider = null;
lastAskMs = -Infinity;
};
/** Measure the camera's motion over the ground from its own positions. */
const sampleMotion = (cartographic, nowMs) => {
const point = {
lat: toDegrees(cartographic.latitude),
lon: toDegrees(cartographic.longitude),
ms: nowMs,
};
if (!anchor || nowMs < anchor.ms) {
anchor = point;
return;
}
const elapsedMs = nowMs - anchor.ms;
if (elapsedMs < MOTION_SAMPLE_MS) return;
const { distanceM, bearingDeg } = groundMove(anchor, point);
motion = {
groundMps: (distanceM * 1000) / elapsedMs,
bearingDeg,
ms: nowMs,
};
anchor = point;
};
const update = (nowMs = now()) => {
try {
const { scene, camera } = viewer;
const cartographic = camera?.positionCartographic;
const altitudeM = cartographic?.height;
const fovy = camera?.frustum?.fovy;
if (
!cartographic ||
!(altitudeM > 0) ||
!Number.isFinite(fovy) ||
(scene?.mode !== undefined && scene.mode !== Cesium.SceneMode.SCENE3D)
) {
deactivate();
return 0;
}
sampleMotion(cartographic, nowMs);
const threshold = fovForZoom(
orbitalBaseFovRad(altitudeM),
ORBITAL_PREFETCH_MIN_ZOOM,
);
if (!(fovy <= threshold * (1 + 1e-6))) {
deactivate();
return 0;
}
active = true;
// Tilted, the view looks off the track the pre-load follows.
if (!looksAtNadir(camera)) return 0;
if (nowMs - lastAskMs < ORBITAL_PREFETCH_INTERVAL_MS) return 0;
// The look-ahead runs at live speed: with the scene clock paused,
// played back or moved, the view will not pass where it points.
const sceneTime = viewer.clock?.currentTime;
if (sceneTime) {
const sceneMs = Cesium.JulianDate.toDate(sceneTime).getTime();
if (Math.abs(sceneMs - Date.now()) > PREFETCH_LIVE_TOLERANCE_MS)
return 0;
}
if (
!motion ||
nowMs - motion.ms > MOTION_MAX_AGE_MS ||
!(motion.groundMps >= MIN_GROUND_SPEED_MPS)
)
return 0;
lastAskMs = nowMs;
const globe = scene?.globe;
if (!globe || globe.show === false) return 0;
const base = baseImageryProvider(viewer);
if (!base) return 0;
// Another base map: its tiles have not been asked for. A fresh set,
// so a late failure from the old map's requests cannot drop a tile
// the new one has fetched.
if (base !== provider) {
cancelPending();
memory = new Set();
provider = base;
}
const aspect = Number.isFinite(camera.frustum.aspectRatio)
? camera.frustum.aspectRatio
: 1;
const viewKm = footprintWidthKm(altitudeM, fovy, aspect);
// The ground one CSS pixel covers at the nadir point, as Cesium's
// screen-space error measures it: the vertical field of view over the
// canvas height, at the camera's altitude.
const canvas = scene.canvas;
const heightPx = canvas?.clientHeight || canvas?.height;
const terrain = viewer.terrainProvider ?? globe.terrainProvider;
const level = imageryLevelForView(base.tilingScheme, {
metresPerPixel: (altitudeM * 2 * Math.tan(fovy / 2)) / heightPx,
latitudeDeg: toDegrees(cartographic.latitude),
geographic:
base.tilingScheme.projection instanceof Cesium.GeographicProjection,
tileWidthPx: base.tileWidth,
minimumLevel: base.minimumLevel,
maximumLevel: base.maximumLevel,
maximumScreenSpaceError: globe.maximumScreenSpaceError,
terrainLevelErrorM:
typeof terrain?.getLevelMaximumGeometricError === 'function'
? (terrainLevel) =>
terrain.getLevelMaximumGeometricError(terrainLevel)
: undefined,
});
if (level === null) return 0;
const R = ORBITAL_EARTH_RADIUS_M;
const track = {
latitude: toDegrees(cartographic.latitude),
longitude: toDegrees(cartographic.longitude),
groundTrackDeg: motion.bearingDeg,
// groundTrackAhead scales an orbital speed down to the ground.
velocityMps: (motion.groundMps * (R + altitudeM)) / R,
altitudeM,
};
const remembered = memory;
const pending = requests;
const tiles = tilesForPoints(
base.tilingScheme,
centreLinesFirst(groundTrackAhead(track, viewKm)),
level,
{
maxTiles: ORBITAL_PREFETCH_MAX_TILES,
skip: (key) => remembered.has(key),
},
);
let asked = 0;
for (const tile of tiles) {
let promise;
let request;
try {
// The tiles on screen keep their slots: Cesium's scheduler
// declines this request while the imagery server's slots are
// taken (shared with the globe's own tile requests,
// throttleByServer) or the scheduler is full, and at the lowest
// priority it is the first dropped from the priority heap, never
// one the screen asked for.
promise = base.requestImage(
tile.x,
tile.y,
tile.level,
(request = new Cesium.Request({
throttle: true,
throttleByServer: true,
priority: Number.MAX_VALUE,
type: Cesium.RequestType.IMAGERY,
})),
);
} catch {
continue;
}
// A provider that declines now (throttled) is asked again later.
if (!promise) continue;
pending.add(request);
Promise.resolve(promise).then(
() => pending.delete(request),
(error) => {
pending.delete(request);
// Dropped by the scheduler (rejected with no error): asked
// again later. A tile that failed to load stays remembered, so
// one missing from the map is not asked for every look-ahead.
if (error === undefined) remembered.delete(tile.key);
},
);
remembered.add(tile.key);
if (remembered.size > PREFETCH_MEMORY)
remembered.delete(remembered.values().next().value);
asked += 1;
}
return asked;
} catch {
return 0;
}
};
const remove = viewer.scene?.postRender?.addEventListener?.(() => update());
return {
update,
destroy() {
remove?.();
deactivate();
},
};
}