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 // when it is drawn from one 2048 × 1024 mosaic. const GLOBAL_TILE_MAXIMUM_LEVEL = 3; // Detail of the tiled products when the feed does not name its own. const TILE_MAXIMUM_LEVEL = 6; // The deepest level a feed may name: about 150 m a pixel. const SUPPLIED_MAXIMUM_LEVEL_LIMIT = 12; // 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; /** The deepest level the feed's own tiles of `product` go to, or null. */ function suppliedLevel(product) { if (!frameSource?.getTile) return null; let level = null; try { level = frameSource.maximumLevel?.(product) ?? null; } catch { return null; } return Number.isInteger(level) && level >= 0 && level <= SUPPLIED_MAXIMUM_LEVEL_LIMIT ? level : null; } /** Global clouds come from one mosaic unless the feed tiles them itself. */ function fromMosaic(product) { return product === 'clouds' && suppliedLevel(product) === null; } function profile(product) { return { tileSize: 256, maximumLevel: suppliedLevel(product) ?? (product === 'clouds' ? GLOBAL_TILE_MAXIMUM_LEVEL : TILE_MAXIMUM_LEVEL), }; } 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 = fromMosaic(snapshot.product); 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 = fromMosaic(snapshot.product); 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. // Infrared tiles get the display transfer the mosaic already // carries. if ( !frame.closed && !global && (snapshot.product === 'clouds-regional' || snapshot.product === 'clouds') ) 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; }, }; }