Files
gods-eye-view/src/layers/weather/rendering.js
T
Sameh Khamis e18353f769 feat(weather): a host can supply decoded frames to the weather layers
A weather feed may also be a frame source. With an optional
getFrameImage({ product, time, size, bbox, signal }) the layers take
whole-extent images, detail windows and the global mosaic from it; with an
optional getFrameTile({ product, time, z, x, y, size, signal }) regional
tiles and their prefetch come from it, null being a transparent tile. Pixels
may be an ImageBitmap, ImageData, canvas or VideoFrame of exactly the
requested size; the layer draws them once and closes them. Cancellation
reaches the source, and a feed without these methods reads the image and
tile routes as before.
2026-11-10 21:54:08 -08:00

817 lines
27 KiB
JavaScript
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
import { weatherTileUrl, closeWeatherPixels } from './source.js';
import { orderWeatherImagery } from './imageryOrder.js';
import { imageryHostStatus } from './imageryHost.js';
import {
createRasterTileProvider,
createFrameTileProvider,
} from './rasterTiles.js';
import { createWeatherShell } from './shellRendering.js';
import { weatherDisplay, escapeCreditText } from './display.js';
import { msg } from '../../i18n/index.js';
import { readResponseBytesCapped } from '../../sources/httpBody.js';
import {
acquireInfraredMosaic,
processInfraredImage,
} from './infraredImage.js';
// Bounded display detail for the hourly, approximately 3 km global product.
const GLOBAL_TILE_MAXIMUM_LEVEL = 3;
// Six decoded 2048×1024 canvases (8 MiB each) bound the cache below 50 MiB.
const MAX_MOSAICS = 6;
const MAX_PREFETCH_TILES = 8;
// How often a staged frame waiting out its quiet interval rechecks readiness.
export const READY_WAKE_MS = 150;
/** Globe imagery: own at most a displayed and a staging frame. Use native Cesium
* tile scheduling, projection and texture disposal; the application clock is never touched. */
function createGlobeRendering({
viewer,
cesium,
getHost,
onChange,
timeoutMs,
now,
fetchImpl,
decodeImage,
createCanvas,
frameSource,
}) {
let current = null;
let incoming = null;
const retiring = new Set();
let alpha = 0.7;
let frameHidden = false;
let lastError = null;
const mosaics = new Map();
let prefetchJob = null;
let prefetchedKey = null;
function profile(product) {
return {
tileSize: 256,
maximumLevel: product === 'clouds' ? GLOBAL_TILE_MAXIMUM_LEVEL : 6,
};
}
function cancelPrefetch() {
clearTimeout(prefetchJob?.timeout);
prefetchJob?.controller.abort();
prefetchJob = null;
prefetchedKey = null;
}
async function mosaic(time, mode, signal, onFetched) {
signal.throwIfAborted();
const key = `${time}|${mode}`;
const texture = mosaics.get(key);
if (texture) {
mosaics.delete(key);
mosaics.set(key, texture);
return { texture, decodeMs: 0, cached: true };
}
const result = await acquireInfraredMosaic(time, {
signal,
mode,
createCanvas,
fetchImpl,
decodeImage,
now,
onFetched,
frameSource,
});
// An aborted decode may still finish; never repopulate a cleared instance.
signal.throwIfAborted();
mosaics.delete(key);
mosaics.set(key, result.texture);
while (mosaics.size > MAX_MOSAICS)
mosaics.delete(mosaics.keys().next().value);
return { ...result, cached: false };
}
/** Level 0–1 tiles of the visible product bounds, at most eight. */
function prefetchTiles(snapshot) {
const { west, south, east, north } = snapshot.bounds;
const bounds = cesium.Rectangle.fromDegrees(west, south, east, north);
const view = viewer.camera?.computeViewRectangle?.(
viewer.scene.globe?.ellipsoid,
);
const coverage = view
? cesium.Rectangle.intersection(bounds, view)
: bounds;
if (!coverage) return [];
const scheme = new cesium.GeographicTilingScheme();
const tiles = [];
for (let z = 0; z <= 1; z++) {
for (let y = 0; y < scheme.getNumberOfYTilesAtLevel(z); y++) {
for (let x = 0; x < scheme.getNumberOfXTilesAtLevel(z); x++) {
if (
!cesium.Rectangle.intersection(
coverage,
scheme.tileXYToRectangle(x, y, z),
)
)
continue;
tiles.push({ z, x, y });
if (tiles.length === MAX_PREFETCH_TILES) return tiles;
}
}
}
return tiles;
}
function tileUrls(snapshot, time, tiles) {
const template = weatherTileUrl(snapshot.product, time, {
size: profile(snapshot.product).tileSize,
});
return tiles.map(({ z, x, y }) =>
template.replace('{z}', z).replace('{x}', x).replace('{y}', y),
);
}
/** Warm tiles through the frame source; the pixels themselves are released. */
function prefetchFrameTiles(snapshot, time, tiles, signal) {
const size = profile(snapshot.product).tileSize;
return Promise.all(
tiles.map(async ({ z, x, y }) =>
closeWeatherPixels(
await frameSource.getTile({
product: snapshot.product,
time,
z,
x,
y,
size,
signal,
}),
),
),
);
}
function creditText(snapshot) {
const sourceCredit = weatherDisplay(snapshot).credit;
return sourceCredit !== undefined
? escapeCreditText(sourceCredit)
: snapshot.product === 'lightning'
? 'NOAA/NWS lightning density · derived from Vaisala NLDN/GLD360'
: snapshot.product === 'radar'
? 'NOAA nowCOAST · NWS/OAR MRMS'
: 'NOAA nowCOAST · NESDIS GOES / global satellite partners';
}
function setCredit(frame) {
const text = creditText(frame.creditSnapshot ?? frame.snapshot);
if (frame.credit?.html === text) return false;
frame.credit = new cesium.Credit(text, false);
return true;
}
/**
* Take the credit of a refreshed manifest of the same product. Each frame
* keeps the snapshot it was staged from, whose time and bounds still match,
* and remembers the refreshed one for its credit, including a frame that
* is still loading and takes its credit when installed.
*/
function updateSnapshot(snapshot) {
let changed = false;
for (const frame of new Set([current, incoming, ...retiring])) {
if (!frame || frame.product !== snapshot.product) continue;
frame.creditSnapshot = snapshot;
if (frame.credit && setCredit(frame)) changed = true;
}
if (changed) viewer.scene.requestRender();
}
function remove(frame) {
if (!frame) return;
frame.closed = true;
frame.controller.abort();
frame.offRetire?.();
frame.offInstall?.();
retiring.delete(frame);
frame.offError?.();
frame.offAbort?.();
frame.offRender?.();
frame.offCamera?.();
clearTimeout(frame.timeout);
clearTimeout(frame.wake);
for (const request of frame.requests) request.cancel?.();
frame.requests.clear();
frame.retries.clear();
if (!frame.layer) return;
const collection = frame.collection;
if (
collection &&
!collection.isDestroyed?.() &&
collection.contains(frame.layer)
)
collection.remove(frame.layer, true);
else if (!frame.layer.isDestroyed?.()) frame.layer.destroy?.();
}
function cancelIncoming() {
if (!incoming) return;
const previous = incoming;
incoming = null;
remove(previous);
previous.resolve(false);
}
function rehome() {
const host = getHost();
const { collection } = host;
const hidden = frameHidden || imageryHostStatus(host) !== null;
const changed =
(current && current.collection !== collection) ||
(incoming && incoming.collection !== collection);
const visibilityChanged = current && current.layer.show === hidden;
if (changed || imageryHostStatus(host) !== null) {
cancelPrefetch();
cancelIncoming();
for (const frame of retiring) remove(frame);
}
if (current) {
if (!hidden && current.layer.alpha !== alpha) current.layer.alpha = alpha;
if (visibilityChanged) current.layer.show = !hidden;
}
if (current && current.collection !== collection) {
current.collection?.remove(current.layer, false);
current.collection = collection;
if (collection) {
collection.add(current.layer);
orderWeatherImagery(collection, current.layer, current.priority);
}
}
if (changed || visibilityChanged) viewer.scene.requestRender();
return Boolean(changed || visibilityChanged);
}
return {
rehome,
cancelPrefetch,
updateSnapshot,
async prefetch(snapshot, time, { infrared = 'filtered' } = {}) {
let job;
try {
if (
frameHidden ||
incoming ||
imageryHostStatus(getHost()) ||
!snapshot.times.includes(time)
)
return false;
const global = snapshot.product === 'clouds';
const tiles = global ? [] : prefetchTiles(snapshot);
const supplied = !global && Boolean(frameSource?.getTile);
const urls = global || supplied ? [] : tileUrls(snapshot, time, tiles);
const key = global
? `${time}|${infrared}`
: supplied
? `${snapshot.product}|${time}|${tiles.map(({ z, x, y }) => `${z}/${x}/${y}`).join('|')}`
: urls.join('|');
if (prefetchJob?.key === key || prefetchedKey === key) return false;
cancelPrefetch();
job = { key, controller: new AbortController() };
prefetchJob = job;
const { signal } = job.controller;
job.timeout = setTimeout(() => job.controller.abort(), timeoutMs);
if (global) await mosaic(time, infrared, signal);
else if (supplied)
await prefetchFrameTiles(snapshot, time, tiles, signal);
else
await Promise.all(
urls.map(async (url) => {
const response = await fetchImpl(url, { signal });
if (!response.ok)
throw new Error(msg('Weather prefetch unavailable'));
await readResponseBytesCapped(response, 4 * 1024 * 1024 + 65_536);
}),
);
signal.throwIfAborted();
if (prefetchJob === job) prefetchedKey = key;
return true;
} catch {
job?.controller.abort();
return false;
} finally {
clearTimeout(job?.timeout);
if (job && prefetchJob === job) prefetchJob = null;
}
},
async setFrame(
snapshot,
time,
{ signal, infrared = 'filtered', creditSnapshot } = {},
) {
signal?.throwIfAborted();
cancelPrefetch();
rehome();
cancelIncoming();
const host = getHost();
const { collection, kind } = host;
if (imageryHostStatus(host)) return false;
const nextProfile = profile(snapshot.product);
if (
current?.time === time &&
current.product === snapshot.product &&
current.kind === kind &&
current.infrared === infrared
) {
updateSnapshot(creditSnapshot ?? snapshot);
return true;
}
lastError = null;
const { west, south, east, north } = snapshot.bounds;
const rectangle = cesium.Rectangle.fromDegrees(west, south, east, north);
const global = snapshot.product === 'clouds';
const frame = {
snapshot,
creditSnapshot,
time,
infrared,
mosaic: global
? { fetched: false, decodeMs: null, cached: false }
: undefined,
controller: new AbortController(),
collection,
kind,
priority:
snapshot.product === 'lightning'
? 3
: snapshot.product === 'radar'
? 2
: 1,
product: snapshot.product,
requests: new Set(),
retries: new Map(),
deferred: new Set(),
pending: 0,
loaded: 0,
lastActivity: now(),
startedAt: now(),
closed: false,
failed: false,
resolve: null,
};
incoming = frame;
const result = new Promise((resolve) => {
frame.resolve = resolve;
});
const finish = (ok) => {
if (incoming !== frame) return;
incoming = null;
frame.offRender?.();
frame.offRender = null;
frame.offCamera?.();
frame.offCamera = null;
clearTimeout(frame.timeout);
clearTimeout(frame.wake);
frame.wake = null;
frame.offAbort?.();
if (ok) {
lastError = null;
const previous = current;
current = frame;
frame.loadMs = now() - frame.startedAt;
frame.layer.alpha = alpha;
frame.layer.show = !frameHidden;
viewer.scene.requestRender();
if (previous) {
retiring.add(previous);
previous.offRetire = viewer.scene.postRender.addEventListener(
() => {
remove(previous);
viewer.scene.requestRender();
},
);
}
} else {
lastError = msg(
'Weather tiles unavailable · previous frame retained',
);
remove(frame);
}
frame.resolve(ok);
viewer.scene.requestRender();
onChange();
};
const abort = () => {
if (incoming === frame) cancelIncoming();
viewer.scene.requestRender();
};
signal?.addEventListener('abort', abort, { once: true });
frame.offAbort = () => signal?.removeEventListener('abort', abort);
frame.timeout = setTimeout(() => finish(false), timeoutMs);
const install = (texture) => {
if (frame.closed) return;
// Keep at most two installed layers during rapid successive selections.
if (retiring.size) {
frame.offInstall = viewer.scene.postRender.addEventListener(() => {
frame.offInstall();
frame.offInstall = null;
try {
install(texture);
} catch {
finish(false);
}
});
viewer.scene.requestRender();
return;
}
const tilingScheme = new cesium.GeographicTilingScheme(
global
? {
rectangle,
numberOfLevelZeroTilesX: 2,
numberOfLevelZeroTilesY: 1,
}
: undefined,
);
setCredit(frame);
const credit = frame.credit;
const provider = global
? createRasterTileProvider({
cesium,
texture,
rectangle,
tilingScheme,
maximumLevel: GLOBAL_TILE_MAXIMUM_LEVEL,
tileSize: nextProfile.tileSize,
credit,
createCanvas,
})
: frameSource?.getTile
? createFrameTileProvider({
cesium,
frameSource,
product: snapshot.product,
time,
tilingScheme,
rectangle,
maximumLevel: nextProfile.maximumLevel,
tileSize: nextProfile.tileSize,
credit,
createCanvas,
signal: frame.controller.signal,
})
: new cesium.UrlTemplateImageryProvider({
url: weatherTileUrl(snapshot.product, time, {
size: nextProfile.tileSize,
}),
tilingScheme,
rectangle,
tileWidth: nextProfile.tileSize,
tileHeight: nextProfile.tileSize,
maximumLevel: nextProfile.maximumLevel,
enablePickFeatures: false,
credit,
});
// Cesium reads a provider's credit every frame; a refreshed manifest
// can replace it without restaging the imagery.
Object.defineProperty(provider, 'credit', {
configurable: true,
enumerable: true,
get: () => frame.credit,
});
const requestImage = provider.requestImage.bind(provider);
provider.requestImage = (x, y, level, request) => {
if (frame.closed) return undefined;
const result = requestImage(x, y, level, request);
const tileKey = `${level}/${x}/${y}`;
if (!result) {
// Scheduler admission is part of readiness, not a successful tile.
frame.deferred.add(tileKey);
frame.lastActivity = now();
return result;
}
frame.deferred.delete(tileKey);
frame.pending++;
frame.lastActivity = now();
if (request) frame.requests.add(request);
return Promise.resolve(result)
.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')
image = processInfraredImage(image, infrared, createCanvas, {
flipY:
typeof ImageBitmap !== 'undefined' &&
image instanceof ImageBitmap,
});
frame.retries.delete(tileKey);
frame.loaded++;
return image;
})
.finally(() => {
frame.pending--;
frame.lastActivity = now();
frame.requests.delete(request);
if (!frame.closed) viewer.scene.requestRender();
});
};
frame.offError = provider.errorEvent.addEventListener((error) => {
if (frame.closed) return;
const status = error?.error?.statusCode;
// Cesium retries synchronously after this event; no delay hook is exposed.
const tileKey = `${error.level}/${error.x}/${error.y}`;
const retries = frame.retries.get(tileKey) ?? 0;
error.retry = false;
if ((status === 429 || status === 503) && retries < 3) {
frame.retries.set(tileKey, retries + 1);
error.retry = true;
return;
}
frame.failed = true;
lastError = msg('Some weather tiles unavailable');
onChange();
});
// A shown, transparent layer lets Cesium request staging tiles while the last
// complete observation stays visible underneath it.
frame.layer = collection.addImageryProvider(provider);
frame.layer.alpha = 0;
orderWeatherImagery(collection, frame.layer, frame.priority);
let settled = 0;
frame.offCamera = viewer.camera?.moveEnd?.addEventListener(() => {
// Tiles abandoned by a previous viewport are no longer admission work.
frame.deferred.clear();
frame.lastActivity = now();
settled = 0;
viewer.scene.requestRender();
});
frame.offRender = viewer.scene.postRender.addEventListener(() => {
if (frame.failed) return finish(false);
// Unrelated terrain/basemap work must not indefinitely hold a ready
// observation. Require successful own tiles and a quiet scheduling
// interval before admitting a frame when the rest of the globe is busy.
const ownReady =
frame.loaded > 0 &&
frame.deferred.size === 0 &&
now() - frame.lastActivity >= 200;
if (
((frame.kind === 'globe' && viewer.scene.globe.tilesLoaded) ||
ownReady) &&
frame.pending === 0
) {
if (++settled >= 2) finish(true);
else viewer.scene.requestRender();
} else settled = 0;
// Waiting out the quiet interval needs another readiness check
// later, not a render every frame: wake on a timer so the render
// governor's frame cap still holds while a frame is staged.
if (
incoming === frame &&
frame.pending === 0 &&
frame.loaded > 0 &&
!frame.wake
)
frame.wake = setTimeout(() => {
frame.wake = null;
if (!frame.closed && incoming === frame)
viewer.scene.requestRender();
}, READY_WAKE_MS);
});
viewer.scene.requestRender();
onChange();
};
if (global) {
void mosaic(time, infrared, frame.controller.signal, () => {
frame.mosaic.fetched = true;
})
.then(({ texture, decodeMs, cached }) => {
frame.mosaic.decodeMs = decodeMs;
frame.mosaic.cached = cached;
install(texture);
})
.catch(() => finish(false));
} else {
try {
install();
} catch {
finish(false);
}
}
viewer.scene.requestRender();
onChange();
return result;
},
setHidden(value) {
frameHidden = Boolean(value);
if (frameHidden) {
cancelPrefetch();
cancelIncoming();
for (const frame of retiring) remove(frame);
}
rehome();
viewer.scene.requestRender();
},
setAlpha(value) {
alpha = value;
if (current && current.layer.show) current.layer.alpha = alpha;
viewer.scene.requestRender();
},
clear() {
cancelPrefetch();
cancelIncoming();
remove(current);
for (const frame of retiring) remove(frame);
current = null;
frameHidden = false;
lastError = null;
mosaics.clear();
viewer.scene.requestRender();
},
getDiagnostics() {
return {
host: 'globe',
cache: { mosaics: mosaics.size, prefetching: !!prefetchJob },
imageryCount:
Number(!!current) + Number(!!incoming?.layer) + retiring.size,
mosaic: (incoming || current)?.mosaic,
infrared: (incoming || current)?.infrared ?? 'filtered',
loading: !!incoming,
time: frameHidden ? null : (current?.time ?? null),
hidden: frameHidden,
product: current?.product ?? null,
pendingTiles: incoming?.pending ?? 0,
deferredTiles: incoming?.deferred.size ?? 0,
loadedTiles: (incoming || current)?.loaded ?? 0,
frameLoadMs: current?.loadMs ?? null,
error: imageryHostStatus(getHost()) || lastError,
};
},
};
}
/** Globe hosts keep draped imagery; 3D Tiles hosts get a raised shell per product.
* A host switch tears one renderer down and restages the last frame on the other. */
export function createWeatherRendering({
viewer,
cesium,
getHost = () => ({ collection: viewer.imageryLayers, kind: 'globe' }),
onChange = () => {},
timeoutMs = 25_000,
now = () => performance.now(),
fetchImpl = (...args) => globalThis.fetch(...args),
decodeImage,
createCanvas = () => document.createElement('canvas'),
createShell = createWeatherShell,
frameSource = null,
}) {
const shared = {
viewer,
cesium,
getHost,
onChange,
timeoutMs,
now,
fetchImpl,
decodeImage,
createCanvas,
frameSource,
};
const globe = createGlobeRendering(shared);
let shell = null;
let active = null;
let alpha = 0.7;
let hidden = false;
let shown = null;
let restaging = null;
// The last refreshed manifest, so a frame shown after it keeps its credit.
let refreshed = null;
// A host without imagery keeps the active renderer, which retains its frame.
const wanted = () => {
const { kind } = getHost();
return kind === 'tileset'
? 'shell'
: kind === 'globe'
? 'globe'
: (active ?? 'globe');
};
const renderer = () => (active === 'shell' ? shell : globe);
function shellFor(product) {
if (shell?.product === product) return shell;
shell?.clear();
shell = createShell({ ...shared, product });
shell.setAlpha(alpha);
shell.setHidden(hidden);
return shell;
}
function restage(frame) {
const target =
active === 'shell' ? shellFor(frame.snapshot.product) : globe;
restaging = frame;
const settle = (ok) => {
if (restaging !== frame) return;
restaging = null;
if (!ok) onChange();
};
// The restaged frame takes the newest refreshed credit; a refresh while
// it loads reaches it through the globe's own updateSnapshot.
target
.setFrame(frame.snapshot, frame.time, {
infrared: frame.infrared,
...(target === globe ? { creditSnapshot: shown?.latest } : {}),
})
.then(settle, () => settle(false));
}
function switchHost() {
const next = wanted();
if (next === active) return false;
const previous = active;
active = next;
if (previous === null) return false;
restaging = null;
if (previous === 'shell') {
shell?.clear();
shell = null;
} else globe.clear();
if (active === 'globe') {
globe.setAlpha(alpha);
if (hidden) globe.setHidden(true);
}
if (shown && !hidden) restage(shown);
viewer.scene.requestRender();
return true;
}
return {
rehome() {
const switched = switchHost();
if (active === 'shell' && !shell) return switched;
return renderer().rehome() || switched;
},
cancelPrefetch() {
renderer()?.cancelPrefetch();
},
prefetch(snapshot, time, options) {
switchHost();
if (active === 'shell' && shell?.product !== snapshot.product)
return Promise.resolve(false);
return renderer().prefetch(snapshot, time, options);
},
async setFrame(snapshot, time, options = {}) {
options.signal?.throwIfAborted();
switchHost();
restaging = null;
const target = active === 'shell' ? shellFor(snapshot.product) : globe;
const before = refreshed;
const ok = await target.setFrame(snapshot, time, options);
if (ok) {
// Keep a refresh that arrived while this frame loaded.
const latest =
refreshed !== before && refreshed?.product === snapshot.product
? refreshed
: undefined;
shown = {
snapshot,
time,
infrared: options.infrared ?? 'filtered',
...(latest ? { latest } : {}),
};
}
return ok;
},
// The shown frame keeps its staged snapshot for a restage on another
// host; only the refreshed credit is remembered and applied.
updateSnapshot(snapshot) {
refreshed = snapshot;
if (shown?.snapshot.product === snapshot.product)
shown = { ...shown, latest: snapshot };
globe.updateSnapshot(snapshot);
},
setHidden(value) {
hidden = Boolean(value);
if (hidden) restaging = null;
renderer()?.setHidden(hidden);
},
setAlpha(value) {
alpha = value;
renderer()?.setAlpha(value);
},
clear() {
restaging = null;
shown = null;
refreshed = null;
hidden = false;
shell?.clear();
shell = null;
globe.clear();
},
getDiagnostics() {
const diagnostics =
active === 'shell' && shell
? shell.getDiagnostics()
: active === 'shell'
? {
host: 'shell',
cache: { mosaics: 0, bytes: 0, prefetching: false },
imageryCount: 0,
infrared: 'filtered',
loading: false,
time: null,
hidden,
product: null,
frameLoadMs: null,
error: imageryHostStatus(getHost()),
}
: globe.getDiagnostics();
// A host switch restages the retained frame; keep reporting its time.
return restaging && !hidden && diagnostics.time === null
? { ...diagnostics, time: restaging.time }
: diagnostics;
},
};
}