import * as Cesium from 'cesium'; import { createWindRendering } from './rendering.js'; import { WIND_FIELDS } from './fields.js'; import { formatWindReading, windReadingResult, windUnitChips, } from './presentation.js'; import { inspectWindAtCenter, WIND_UNITS } from './inspection.js'; import { createWindInspectionMarker } from './inspectionMarker.js'; import { t, msg, translateKnown } from '../../i18n/index.js'; import { unitLabel } from '../../ui/unitLabels.js'; /** Format a forecast timestamp explicitly in UTC. */ export function formatWindValidTime(value) { const ms = Date.parse(value); return Number.isFinite(ms) ? `${new Date(ms).toISOString().slice(0, 16).replace('T', ' ')} UTC` : null; } /* * Reasons the server puts in the manifest (server/providers/wind.js). They stay * English in data and are translated where they are shown. */ const SERVER_REASONS = new Set([msg('Wind upstream unavailable')]); const reasonText = (reason) => SERVER_REASONS.has(reason) ? t(reason) : translateKnown(reason) || null; /** * A wind problem in the UI language. Source errors are English data; the * HTTP status line carries a number, so it goes back onto a placeholder. */ function presentWindProblem(problem) { const http = /^Wind HTTP (\d+)$/.exec(problem); if (http) return t('{source} HTTP {status}', { source: t('Wind'), status: http[1] }); return t(problem); } /** Forecast issue time is source age; valid time is reported separately. */ export function windStats(manifest) { const run = Date.parse(manifest?.cycle?.runIso); return { count: manifest?.grid ? manifest.grid.nx * manifest.grid.ny : 0, lastUpdate: Number.isFinite(run) ? run : null, error: manifest?.reason || (manifest?.unavailable ? msg('Wind unavailable') : null), }; } /** Construct one wind layer with an explicit source and owned animation. */ export function createWindLayer({ feed, clock, cesium = Cesium, container, createRendering = createWindRendering, } = {}) { if (typeof feed?.getSnapshot !== 'function') throw new TypeError('Wind requires a snapshot source'); let viewer = null; let request = null; let enabled = false; let rendering = null; let imageryHost = null; let manifest = null; let error = null; let loading = false; let model = 'gfs'; let overlay = 'none'; let paused = false; let units = 'km/h'; let reading = null; let inspectionMarker = null; let sampledPosition = null; const hideInspection = () => { reading = null; sampledPosition = null; inspectionMarker?.clear(); }; const sample = (position) => { reading = inspectWindAtCenter(manifest, viewer, cesium, { position, units, overlay, model: model === 'ifs' ? 'ECMWF' : 'GFS', validTime: formatWindValidTime(manifest?.cycle?.validIso) || 'Unavailable', // i18n-ignore: English reading for AI tools; the card status uses t() status: loading ? 'Loading forecast' : error || manifest?.reason || (manifest?.stale ? 'Cached forecast 路 stale' : 'Model forecast'), }); sampledPosition = reading.position || position || null; inspectionMarker?.show(sampledPosition); }; const requestedScalar = () => ['temperature', 'pressure'].includes(overlay) ? overlay : 'none'; let generation = 0; let rowControlsListener = null; const notify = () => rowControlsListener?.(); const unsubscribeClock = clock?.subscribe(notify); const layer = { id: 'wind', name: 'Wind', icon: '馃尙', source: 'GFS / ECMWF IFS 路 FORECAST', updateInterval: 3600_000, init(nextViewer) { viewer = nextViewer; rendering = createRendering({ cesium, container: container ?? nextViewer.container, getViewer: () => viewer, getHost: () => imageryHost?.() ?? { collection: viewer.imageryLayers ?? viewer.scene?.imageryLayers, kind: 'globe', }, onStatusChange: notify, }); rendering.attach(); rendering.setOptions?.({ overlay, paused }); const target = container ?? nextViewer.container; inspectionMarker = createWindInspectionMarker({ container: target, viewer, cesium, }); }, attachShellServices(services) { imageryHost = typeof services?.imageryHost === 'function' ? services.imageryHost : null; rendering?.rehome?.(); }, enable() { enabled = true; rendering?.start(); }, disable() { enabled = false; generation += 1; request?.abort(); request = null; loading = false; // The renderer releases its field on disable. Retaining a manifest here // would falsely satisfy an appearance-only reuse after the next enable. manifest = null; error = null; hideInspection(); rendering?.stop(); rendering?.clear(); }, async update(nextViewer, { signal } = {}) { if (!enabled) return false; rendering?.rehome?.(); request?.abort(); const controller = new AbortController(); if (signal?.aborted) controller.abort(signal.reason); const abort = () => controller.abort(signal.reason); signal?.addEventListener('abort', abort, { once: true }); request = controller; generation += 1; loading = true; notify(); try { signal?.throwIfAborted(); const snapshot = await feed.getSnapshot({ signal: controller.signal, model, overlay: requestedScalar(), }); if (!enabled || controller.signal.aborted || request !== controller) return enabled && !signal?.aborted && request !== controller; manifest = snapshot; error = null; if (sampledPosition) sample(sampledPosition); if (snapshot.unavailable) { rendering.stop(); rendering.clear(); } else { rendering.setOptions?.({ overlay, paused }); rendering.setField(snapshot); rendering.start(); } return true; } catch (cause) { if (controller.signal.aborted || request !== controller) return enabled && !signal?.aborted && request !== controller; error = cause?.message || msg('Wind source unavailable'); return true; } finally { signal?.removeEventListener('abort', abort); if (request === controller) { request = null; loading = false; notify(); } } }, setParams(params = {}) { const previousScalar = requestedScalar(); const modelChanged = ['gfs', 'ifs'].includes(params.model) && params.model !== model; const overlayChanged = ['none', 'speed', 'temperature', 'pressure'].includes(params.overlay) && params.overlay !== overlay; if (typeof params.paused === 'boolean') paused = params.paused; const unitsChanged = Object.hasOwn(WIND_UNITS, params.units) && params.units !== units; if (unitsChanged) units = params.units; if (modelChanged) model = params.model; if (overlayChanged) overlay = params.overlay; rendering?.setOptions?.({ overlay, paused }); if (unitsChanged) reading = formatWindReading(reading, units); if (params.inspect === false) hideInspection(); if (modelChanged) { manifest = null; error = null; rendering?.stop(); rendering?.clear(); } const needsField = modelChanged || (overlayChanged && (!manifest?.u || manifest.unavailable || (requestedScalar() !== 'none' && manifest?.scalar?.kind !== overlay))); const changesRequest = modelChanged || (overlayChanged && previousScalar !== requestedScalar()); // None and Speed use the identical U/V request. Keep an active refresh // alive while changing its presentation, including the first load. if (changesRequest || (overlayChanged && needsField && !request)) { request?.abort(); request = null; const current = ++generation; loading = enabled && needsField; if (enabled && needsField) queueMicrotask(() => { if (enabled && generation === current) void layer.update(viewer); }); else if (enabled && manifest && !manifest.unavailable) rendering?.start(); } if (overlayChanged && !needsField && sampledPosition) sample(sampledPosition); if (params.inspect === true && enabled) { sample(); } notify(); }, getParams() { return { model, overlay, paused, units }; }, getRowControls() { const historyStatus = clock?.getState().mode === 'history' ? t('Forecast 路 does not follow history') : null; const valid = formatWindValidTime(manifest?.cycle?.validIso); const run = formatWindValidTime(manifest?.cycle?.runIso); const diagnostic = rendering?.getDiagnostics?.(); const motionPaused = paused || diagnostic?.reducedMotion; const preparing = enabled && diagnostic?.renderMode === 'gpu-streamlines' && diagnostic.gpu?.pathCount > 0 && !diagnostic.gpu?.ready; const scalarMissing = !loading && requestedScalar() !== 'none' && manifest && (!manifest.scalar || manifest.scalar.kind !== overlay); // Stored in English for diagnostics; shown translated. const imageryError = enabled && !loading && diagnostic?.imageryError ? t(diagnostic.imageryError) : null; const label = { none: t('Wind motion'), speed: t('Wind speed'), pressure: t('Sea-level pressure'), temperature: t('Air temperature 路 2 m'), }[overlay]; const kind = ['temperature', 'pressure'].includes(overlay) ? overlay : 'speed'; const spec = WIND_FIELDS[kind]; const legendUnit = kind === 'speed' ? units : spec.units; const legend = spec.stops.map((color, index) => { const value = spec.min + ((spec.max - spec.min) * index) / (spec.stops.length - 1); const display = Math.round( kind === 'speed' ? value * WIND_UNITS[units] : value, ); return { color, label: `${display}${index === spec.stops.length - 1 ? '+' : ''}`, }; }); const speedLegendVisible = !imageryError && (overlay === 'speed' || (overlay === 'none' && diagnostic?.renderMode === 'canvas-fallback')); const controls = { readout: true, summary: { label, coverage: t('Global 路 1掳 grid'), validTime: manifest?.cycle?.validIso, issuedTime: manifest?.cycle?.runIso, detail: t('{model} forecast 路 {time}', { model: model === 'ifs' ? 'ECMWF IFS' : 'GFS', time: valid || t('Unavailable'), }), status: loading ? t('Loading forecast') : preparing ? t('Preparing flow') : (error && presentWindProblem(error)) || reasonText(manifest?.reason) || imageryError || (scalarMissing ? t('Selected field unavailable') : null) || (manifest?.stale ? t('Cached forecast 路 stale') : null), units: legendUnit, }, chips: [ ...['gfs', 'ifs'].map((value) => ({ id: `model-${value}`, label: value === 'ifs' ? 'ECMWF' : 'GFS', // i18n-ignore: forecast model names active: model === value, params: { model: value }, title: value === 'ifs' ? t('ECMWF IFS surface forecast') : t('NOAA GFS surface forecast'), })), { id: 'motion', label: diagnostic?.reducedMotion ? t('Reduced motion') : paused ? t('Resume') : t('Pause'), active: motionPaused, disabled: Boolean(diagnostic?.reducedMotion), params: { paused: !paused }, title: t( 'Pause visual flow; forecast time does not advance with animation', ), }, ...['none', 'speed', 'pressure', 'temperature'].map((value) => ({ id: `overlay-${value}`, label: { none: t('None'), speed: t('Speed'), pressure: t('Pressure'), temperature: t('Temperature'), }[value], active: overlay === value, params: { overlay: value }, title: { none: t('Wind trails with no field shading'), speed: t('How hard the surface wind is blowing'), pressure: t('Sea-level air pressure: broad highs and lows'), temperature: t('Air temperature two meters above the surface'), }[value], })), ...(speedLegendVisible || diagnostic?.renderMode === 'canvas-fallback' || Number.isFinite(reading?.speed) ? Object.keys(WIND_UNITS) : [] ).map((value) => ({ id: `units-${value}`, label: unitLabel(value), active: units === value, params: { units: value }, title: t('Wind speed units'), })), { id: 'read-wind', label: t('Read wind at map center'), params: { inspect: true }, disabled: loading || !manifest?.u || manifest?.unavailable, title: t( 'Read the forecast at the center of the map without changing selection', ), }, ], legend: scalarMissing || imageryError || (overlay === 'none' && !speedLegendVisible) ? [] : legend, info: `${t('{model} forecast 路 {field} ({unit})', { model: model === 'ifs' ? 'ECMWF IFS' : 'GFS', field: label, unit: unitLabel(legendUnit), })}${historyStatus ? `\n${historyStatus}` : ''}\n${t('Valid: {time}', { time: valid || t('Unavailable') })}${loading ? ` 路 ${t('loading')}` : preparing ? ` 路 ${t('preparing')}` : ''}\n${t('Issued: {time}', { time: run || t('Unavailable') })}${manifest?.stale ? ` 路 ${t('STALE')}` : ''}${error ? `\n${presentWindProblem(error)}` : ''}${scalarMissing ? `\n${t('Selected field unavailable 路 wind remains visible')}` : ''}${imageryError && !scalarMissing ? `\n${t('{error} 路 wind remains visible', { error: imageryError })}` : ''}`, infoTitle: t( 'Surface wind at 10 m. Approximately 1掳 global grid. Curves follow the 10 m wind field, lifted 12 km for visibility; display height is not weather altitude. View lighting is for readability. Animation shows flow through one fixed forecast; it does not advance time. Color fields drape the globe basemap or the active photorealistic 3D Tiles.', ), }; controls.summary.reading = reading; controls.summary.result = reading ? windReadingResult(reading) : null; const setting = (id, label, prefix) => ({ id, label, chips: controls.chips.filter((chip) => chip.id.startsWith(prefix)), }); controls.summary.settings = [ setting('model', t('MODEL'), 'model-'), setting('field', t('FIELD'), 'overlay-'), ...(controls.chips.some(({ id }) => id.startsWith('units-')) ? [{ id: 'units', label: t('UNITS'), chips: windUnitChips(units) }] : []), setting('motion', t('MOTION'), 'motion'), ]; controls.summary.actions = controls.chips.filter( ({ id }) => id === 'read-wind', ); return controls; }, setRowControlsListener(listener) { rowControlsListener = typeof listener === 'function' ? listener : null; }, destroy() { layer.disable(); unsubscribeClock?.(); rendering?.destroy(); rendering = null; imageryHost = null; viewer = null; rowControlsListener = null; inspectionMarker?.destroy(); inspectionMarker = null; }, getStats() { const diagnostic = rendering?.getDiagnostics?.(); const preparing = enabled && diagnostic?.renderMode === 'gpu-streamlines' && diagnostic.gpu?.pathCount > 0 && !diagnostic.gpu?.ready; const imageryError = enabled && !loading ? rendering?.getDiagnostics?.()?.imageryError : null; return { ...windStats(manifest), countLabel: t('Forecast'), loading: loading || Boolean(preparing), model: model.toUpperCase(), overlay, paused, stale: Boolean(manifest?.stale), source: model === 'ifs' ? 'ECMWF IFS' : 'NOAA GFS', validTime: formatWindValidTime(manifest?.cycle?.validIso) || t('Unavailable'), error: error || windStats(manifest).error || (requestedScalar() !== 'none' ? manifest?.scalarError : null) || imageryError, }; }, getDiagnostics() { return rendering?.getDiagnostics?.() || {}; }, getParticleCount() { return rendering?.getParticleCount() || 0; }, }; return layer; }