mirror of
https://github.com/bilawalsidhu/gods-eye-view.git
synced 2026-11-16 08:12:24 +00:00
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.
336 lines
12 KiB
JavaScript
336 lines
12 KiB
JavaScript
/**
|
|
* @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();
|
|
},
|
|
};
|
|
}
|