Files
gods-eye-view/src/render/cesium/imageryFrames.js
T
Sameh Khamis a043854f27 Timed imagery reads the drawn globe tiles through internals.js
The tiles the globe last drew are a private Cesium field: read through
globeTilesDrawn, whose field the internals test checks the installed
Cesium still declares.
2026-11-11 17:20:58 -08:00

320 lines
11 KiB
JavaScript

/**
* @module render/cesium/imageryFrames
* @description Timed imagery (`imageryFrames`) on the Cesium globe: which
* frames of a `TimedSource` a time shows and prefetches, video tiles drawn
* at a time within their segment, and whether a layer's tiles in view are
* drawn from its own imagery.
*
* A source is a list of frames, in time order. A `frames` source is its own
* list. A `video` source is each segment's videos seen every
* `VIDEO_STEP_MS` from its start to its end (at most `VIDEO_STEPS_MAX`
* steps a segment): a time is shown by the step nearest it, its offset into
* the segment's videos in proportion; outside every segment, the nearest
* segment end is the nearest frame.
*/
import * as Cesium from 'cesium';
import { globeTilesDrawn } from './internals.js';
/** How far apart the times a video segment is seen at are, ms. */
export const VIDEO_STEP_MS = 250;
/** The most times one video segment is seen at. */
export const VIDEO_STEPS_MAX = 1200;
/** Tile videos kept loaded a layer, the least recently seen let go first. */
export const VIDEO_CACHE = 48;
/**
* The frames of a timed source, in time order: `{time, url}`, and for
* video `fraction`, how far into the segment's videos the time is.
* @param {import('../contract/globe').TimedSource} source
* @returns {Array<{time: number, url: string, fraction?: number}>}
*/
export function framesOf(source) {
if (source?.kind === 'video') {
const frames = [];
for (const segment of source.segments ?? []) {
const { url, start, end } = segment;
if (typeof url !== 'string' || !(end >= start)) continue;
const span = end - start;
const steps = Math.min(
VIDEO_STEPS_MAX,
Math.max(1, Math.ceil(span / VIDEO_STEP_MS)),
);
for (let k = 0; k <= steps; k++)
frames.push({
time: start + (span * k) / steps,
url,
fraction: span > 0 ? k / steps : 0,
});
}
return frames.sort((a, b) => a.time - b.time);
}
if (source?.kind === 'frames')
return (source.frames ?? [])
.filter((f) => Number.isFinite(f?.time) && typeof f?.url === 'string')
.map((f) => ({ time: f.time, url: f.url }))
.sort((a, b) => a.time - b.time);
throw new TypeError(`Unknown timed source: ${source?.kind}`);
}
/** The index of the frame nearest `ms` (the earlier one on a tie). */
function nearestIndex(frames, ms) {
let lo = 0;
let hi = frames.length - 1;
while (lo < hi) {
const mid = (lo + hi) >> 1;
if (frames[mid].time < ms) lo = mid + 1;
else hi = mid;
}
if (lo > 0 && ms - frames[lo - 1].time <= frames[lo].time - ms) return lo - 1;
return lo;
}
/**
* What `ms` shows: the nearest frame, and in `blend` mode the frames either
* side of it, each with its weight (the later one's share of the way).
* `nearest` is the frame the clock shows, which `frameReady` names.
* @returns {{nearest: number, shown: Array<{index: number, weight: number}>}|null}
*/
export function shownAt(frames, ms, mode = 'nearest') {
if (!frames.length || !Number.isFinite(ms)) return null;
const nearest = nearestIndex(frames, ms);
if (mode !== 'blend')
return { nearest, shown: [{ index: nearest, weight: 1 }] };
let before = nearest;
if (frames[before].time > ms && before > 0) before -= 1;
const after = Math.min(frames.length - 1, before + 1);
const t0 = frames[before].time;
const t1 = frames[after].time;
if (after === before || ms <= t0 || t1 <= t0)
return { nearest, shown: [{ index: before, weight: 1 }] };
if (ms >= t1) return { nearest, shown: [{ index: after, weight: 1 }] };
const f = (ms - t0) / (t1 - t0);
return {
nearest,
shown: [
{ index: before, weight: 1 },
{ index: after, weight: f },
],
};
}
/**
* The frames to hold loaded: those shown, and the `prefetch` after the
* last of them (playback runs forward).
* @returns {number[]} Indices.
*/
export function heldFrames(frames, shown, prefetch) {
const held = new Set(shown.shown.map((s) => s.index));
const last = Math.max(...held);
for (let k = 1; k <= prefetch && last + k < frames.length; k++)
held.add(last + k);
return [...held];
}
/** The URL of a tile from a template, as `xyz` imagery fills it. */
function tileUrlOf(template, tilingScheme, x, y, level) {
const rows = tilingScheme.getNumberOfYTilesAtLevel(level);
return template
.replaceAll('{x}', String(x))
.replaceAll('{y}', String(y))
.replaceAll('{z}', String(level))
.replaceAll('{reverseY}', String(rows - 1 - y));
}
/**
* Seek a video, resolving once it has: on a `seeked` that leaves it no
* longer seeking (one a seek before it sends late does not count), and its
* frame there presented where the browser says so.
*/
function seekTo(video, time, url) {
return new Promise((resolve, reject) => {
const failed = () => {
video.removeEventListener('seeked', seeked);
reject(new Error(`The video tile did not seek: ${url}`));
};
const seeked = () => {
if (video.seeking) return;
video.removeEventListener('seeked', seeked);
video.removeEventListener('error', failed);
if (typeof video.requestVideoFrameCallback !== 'function') resolve();
else {
// Its frame is drawable once presented; never wait on it for long.
const timer = setTimeout(resolve, 100);
video.requestVideoFrameCallback(() => {
clearTimeout(timer);
resolve();
});
}
};
video.addEventListener('seeked', seeked);
video.addEventListener('error', failed, { once: true });
video.currentTime = time;
});
}
/**
* A layer's tile videos, loaded once each and seeked for each frame drawn
* from them, one seek at a time a video.
*/
export function createTileVideos(limit = VIDEO_CACHE) {
/** url → {video, ready: Promise, queue: Promise} */
const videos = new Map();
function load(url) {
let entry = videos.get(url);
if (entry) {
videos.delete(url);
videos.set(url, entry);
return entry;
}
const video = document.createElement('video');
video.muted = true;
video.playsInline = true;
video.preload = 'auto';
video.crossOrigin = 'anonymous';
const loaded = new Promise((resolve, reject) => {
video.addEventListener('loadeddata', () => resolve(video), {
once: true,
});
video.addEventListener(
'error',
() => reject(new Error(`The video tile did not load: ${url}`)),
{ once: true },
);
});
// A video that does not say how long it is (a recorded WebM, say) is
// seeked past its end once to learn it.
const ready = loaded.then(async () => {
if (!Number.isFinite(video.duration))
await seekTo(video, Number.MAX_SAFE_INTEGER, url);
return video;
});
ready.catch(() => {});
video.src = url;
entry = { video, ready, queue: Promise.resolve() };
videos.set(url, entry);
while (videos.size > limit) {
const [oldest, old] = videos.entries().next().value;
videos.delete(oldest);
old.video.removeAttribute('src');
old.video.load();
}
return entry;
}
/** The video at `fraction` of its length, drawn on a canvas. */
function frame(url, fraction) {
const entry = load(url);
const run = entry.queue.then(async () => {
const video = await entry.ready;
const duration = Number.isFinite(video.duration) ? video.duration : 0;
const at = Math.max(0, Math.min(duration - 1e-3, fraction * duration));
if (Math.abs(video.currentTime - at) > 1e-4) await seekTo(video, at, url);
const canvas = document.createElement('canvas');
canvas.width = video.videoWidth || 1;
canvas.height = video.videoHeight || 1;
canvas.getContext('2d').drawImage(video, 0, 0);
return canvas;
});
entry.queue = run.catch(() => {});
return run;
}
return {
frame,
clear() {
for (const { video } of videos.values()) {
video.removeAttribute('src');
video.load();
}
videos.clear();
},
};
}
/**
* A provider drawing a video frame's tiles: each tile the video its URL
* template names for it (an `xyz` spec), or the one video over the layer's
* rectangle (any other), at the frame's place in it.
* @param {import('../contract/globe').ImagerySpec} spec
* @param {{url: string, fraction: number}} frame
* @param {ReturnType<typeof createTileVideos>} videos
*/
export function videoProvider(spec, frame, videos) {
const tiled = spec.kind === 'xyz';
const rectangle = spec.rectangle
? Cesium.Rectangle.fromDegrees(
spec.rectangle.west,
spec.rectangle.south,
spec.rectangle.east,
spec.rectangle.north,
)
: undefined;
const tilingScheme = tiled
? spec.tiling === 'geographic'
? new Cesium.GeographicTilingScheme()
: new Cesium.WebMercatorTilingScheme()
: new Cesium.GeographicTilingScheme({
rectangle: rectangle ?? Cesium.Rectangle.MAX_VALUE,
numberOfLevelZeroTilesX: 1,
numberOfLevelZeroTilesY: 1,
});
const size = spec.tileSize ?? 256;
return {
tilingScheme,
tileWidth: size,
tileHeight: size,
minimumLevel: tiled ? (spec.minLevel ?? 0) : 0,
maximumLevel: tiled ? spec.maxLevel : 0,
rectangle: rectangle ?? tilingScheme.rectangle,
credit: undefined,
errorEvent: new Cesium.Event(),
hasAlphaChannel: true,
tileDiscardPolicy: undefined,
proxy: undefined,
getTileCredits: () => undefined,
pickFeatures: () => undefined,
requestImage(x, y, level) {
const url = tiled
? tileUrlOf(frame.url, tilingScheme, x, y, level)
: frame.url;
return videos.frame(url, frame.fraction ?? 0);
},
};
}
const { ImageryState } = Cesium;
/** States a tile's imagery settles in: drawn, or nothing better to come. */
const SETTLED = new Set([
ImageryState.READY,
ImageryState.FAILED,
ImageryState.INVALID,
]);
/**
* Whether every globe tile drawn last frame draws `layer` from its own
* imagery (not an ancestor's while its own loads). Tiles outside the
* layer's rectangle have none to draw.
*/
export function layerDrawn(scene, layer) {
if (!layer || layer.isDestroyed?.() || !layer.ready) return false;
const tiles = globeTilesDrawn(scene.globe);
if (!tiles?.length) return false;
const bounds = layer.imageryProvider?.rectangle ?? layer.rectangle;
for (const tile of tiles) {
let found = false;
for (const tileImagery of tile.data?.imagery ?? []) {
const loading = tileImagery.loadingImagery;
const ready = tileImagery.readyImagery;
if ((loading ?? ready)?.imageryLayer !== layer) continue;
found = true;
if (loading && !SETTLED.has(loading.state)) return false;
if (loading?.state === ImageryState.READY && ready !== loading)
return false;
}
if (
!found &&
(!bounds || Cesium.Rectangle.intersection(tile.rectangle, bounds))
)
return false;
}
return true;
}