@aguacerowx/mapsgl 0.0.32 → 0.0.42

package/src/NexradSitesOverlay.js

@@ -0,0 +1,148 @@
+/**
+ * GeoJSON markers for all NEXRAD sites (picker mode). Aligned with aguacero-frontend NexradSitesLayer (simplified).
+ */
+const SOURCE_ID = 'aguacero-nexrad-sites-src';
+const CIRCLE_LAYER_ID = 'aguacero-nexrad-sites-circles';
+
+export class NexradSitesOverlay {
+    constructor(map, options = {}) {
+        this.map = map;
+        /** Same path as aguacero-frontend: serve `public/data/nexrad.json` (e.g. Vite → `/data/nexrad.json`). */
+        this.sitesUrl = options.nexradSitesUrl || '/data/nexrad.json';
+        this._onClick = null;
+        /** Coalesces overlapping `show()` calls (e.g. NEXRAD timestamp slider firing many state updates). */
+        this._showPromise = null;
+        this._destroyed = false;
+    }
+
+    _layersPresent() {
+        try {
+            return Boolean(this.map.getSource(SOURCE_ID) && this.map.getLayer(CIRCLE_LAYER_ID));
+        } catch {
+            return false;
+        }
+    }
+
+    async show() {
+        if (this._layersPresent()) {
+            return;
+        }
+        if (this._showPromise) {
+            return this._showPromise;
+        }
+
+        this._showPromise = this._loadAndMountSites();
+        try {
+            await this._showPromise;
+        } finally {
+            this._showPromise = null;
+        }
+    }
+
+    async _loadAndMountSites() {
+        if (this._layersPresent()) {
+            return;
+        }
+        await this.hide();
+        let res;
+        try {
+            res = await fetch(this.sitesUrl);
+        } catch (e) {
+            console.warn('[NexradSitesOverlay] Failed to load site list:', e);
+            return;
+        }
+        if (!res.ok) {
+            console.warn('[NexradSitesOverlay] HTTP', res.status, this.sitesUrl);
+            return;
+        }
+        if (this._destroyed) {
+            return;
+        }
+        const payload = await res.json();
+        const raw = Array.isArray(payload)
+            ? payload
+            : payload?.features
+              ? payload.features
+              : payload?.sites
+                ? payload.sites
+                : [];
+        const features = [];
+        for (const item of raw) {
+            if (!item) continue;
+            const coords = item.geometry?.coordinates
+                ? item.geometry.coordinates
+                : [item.lon ?? item.lng ?? item.longitude, item.lat ?? item.latitude];
+            const lon = Number(coords[0]);
+            const lat = Number(coords[1]);
+            const id = String(item.id ?? item.properties?.id ?? item.station ?? '').toUpperCase();
+            if (!id || !Number.isFinite(lat) || !Number.isFinite(lon)) continue;
+            features.push({
+                type: 'Feature',
+                geometry: { type: 'Point', coordinates: [lon, lat] },
+                properties: { name: id },
+            });
+        }
+        if (this._destroyed) {
+            return;
+        }
+        this.map.addSource(SOURCE_ID, {
+            type: 'geojson',
+            data: { type: 'FeatureCollection', features },
+        });
+        this.map.addLayer({
+            id: CIRCLE_LAYER_ID,
+            type: 'circle',
+            source: SOURCE_ID,
+            paint: {
+                'circle-radius': 5,
+                'circle-color': '#3b82f6',
+                'circle-stroke-width': 1,
+                'circle-stroke-color': '#ffffff',
+            },
+        });
+    }
+
+    hide() {
+        try {
+            if (this.map.getLayer(CIRCLE_LAYER_ID)) this.map.removeLayer(CIRCLE_LAYER_ID);
+            if (this.map.getSource(SOURCE_ID)) this.map.removeSource(SOURCE_ID);
+        } catch {
+            /* ignore */
+        }
+    }
+
+    /**
+     * @param {(siteId: string) => void} handler
+     */
+    bindClick(handler) {
+        this.unbindClick();
+        this._onClick = (e) => {
+            const f = e.features?.[0];
+            const id = f?.properties?.name;
+            if (id) handler(String(id));
+        };
+        this.map.on('click', CIRCLE_LAYER_ID, this._onClick);
+        this.map.on('mouseenter', CIRCLE_LAYER_ID, () => {
+            this.map.getCanvas().style.cursor = 'pointer';
+        });
+        this.map.on('mouseleave', CIRCLE_LAYER_ID, () => {
+            this.map.getCanvas().style.cursor = '';
+        });
+    }
+
+    unbindClick() {
+        if (!this._onClick) return;
+        try {
+            this.map.off('click', CIRCLE_LAYER_ID, this._onClick);
+        } catch {
+            /* ignore */
+        }
+        this._onClick = null;
+    }
+
+    destroy() {
+        this._destroyed = true;
+        this.unbindClick();
+        this.hide();
+    }
+}

package/src/NexradWeatherController.js

@@ -0,0 +1,491 @@
+/**
+ * Connects AguaceroCore NEXRAD state to MapboxRadarLayer + archive fetch (aguacero-frontend parity).
+ * Preloads all timestamps on the active timeline (MRMS/satellite-style) so scrubbing does not trigger loads.
+ */
+import { getUnitConversionFunction, getDefaultRadarTilt } from '@aguacerowx/javascript-sdk';
+import { fetchAndParseArchive, objectKeyToUrl, setNexradArchiveApiKey } from './nexrad/radarArchiveCore.bundled.js';
+import { MapboxRadarLayer } from './nexrad/MapboxRadarLayer.bundled.js';
+import { nexradBinGroupIdForKey, variableToNexradGroup } from '@aguacerowx/javascript-sdk';
+import { sampleNexradFrameAtLatLon } from './nexrad/nexradCrossSectionSampleAtLatLon.bundled.js';
+import { prepareRadarFrameForGpuReadout } from './nexrad/radarFrameGpuMatch.bundled.js';
+import { mapboxFrameUploadOptionsForNexradState } from './nexrad/nexradMapboxFrameOpts.js';
+
+function pickNearestLevel3ObjectKey(unixTime, timeToKeyMap, maxDeltaSec = 600) {
+    const direct = timeToKeyMap[String(unixTime)];
+    if (direct) return direct;
+    const entries = Object.entries(timeToKeyMap || {});
+    if (entries.length === 0) return null;
+    let bestKey = null;
+    let bestDelta = Infinity;
+    for (const [tStr, key] of entries) {
+        const t = Number(tStr);
+        if (!Number.isFinite(t)) continue;
+        const d = Math.abs(t - unixTime);
+        if (d < bestDelta) {
+            bestDelta = d;
+            bestKey = key;
+        }
+    }
+    if (bestKey == null) return null;
+    if (bestDelta > maxDeltaSec && Number.isFinite(maxDeltaSec)) return null;
+    return bestKey;
+}
+
+function isVelocityStyleRadarVar(radarVariable) {
+    return radarVariable === 'VEL' || radarVariable === 'SW' || radarVariable === 'N0G' || radarVariable === 'N0W';
+}
+
+function velocityRangeToMs(rangeMin, rangeMax, displayUnit) {
+    if (rangeMin == null || rangeMax == null || !displayUnit || displayUnit.toLowerCase() === 'm/s' || displayUnit.toLowerCase() === 'ms') {
+        return [rangeMin, rangeMax];
+    }
+    const toMs = getUnitConversionFunction(displayUnit, 'm/s', 'nexrad_vel');
+    if (!toMs) return [rangeMin, rangeMax];
+    return [toMs(rangeMin), toMs(rangeMax)];
+}
+
+function colormapToMs(colormap, radarVariable, displayUnit) {
+    if (!colormap || !Array.isArray(colormap) || colormap.length < 2) return colormap;
+    if (!isVelocityStyleRadarVar(radarVariable)) return colormap;
+    if (!displayUnit || displayUnit.toLowerCase() === 'm/s' || displayUnit.toLowerCase() === 'ms') return colormap;
+    const toMs = getUnitConversionFunction(
+        displayUnit,
+        'm/s',
+        radarVariable === 'SW' || radarVariable === 'N0W' ? 'nexrad_sw' : 'nexrad_vel',
+    );
+    if (!toMs) return colormap;
+    const out = [...colormap];
+    for (let i = 0; i < out.length; i += 2) {
+        const v = out[i];
+        if (typeof v === 'number' && Number.isFinite(v)) out[i] = toMs(v);
+    }
+    return out;
+}
+
+function radarShaderValueRange(rangeMin, rangeMax, radarVariable, units, nexradDataSource) {
+    const v = (radarVariable || '').toUpperCase();
+    if (isVelocityStyleRadarVar(v)) {
+        const [vmin, vmax] = velocityRangeToMs(rangeMin, rangeMax, units);
+        return [vmin ?? 0, vmax ?? 80];
+    }
+    if (nexradDataSource === 'level3' && (v === 'N0H' || v === 'HHC')) {
+        const lo = rangeMin ?? 0;
+        let hi = rangeMax ?? 11;
+        if (hi > 11) hi = 11;
+        if (hi < lo) hi = lo;
+        return [lo, hi];
+    }
+    if (v === 'KDP') {
+        const lo = rangeMin ?? -2;
+        let hi = rangeMax ?? 8;
+        if (hi < lo) hi = lo;
+        return [lo, hi];
+    }
+    return [rangeMin ?? 0, rangeMax ?? 80];
+}
+
+/** Level-III digital / hybrid hydrometeor classification (aguacero-frontend `nexradLevel3IsHydrometeorClassification`). */
+function nexradLevel3IsHydrometeorClassification(radarVariable) {
+    const v = (radarVariable || '').toUpperCase();
+    return v === 'N0H' || v === 'HHC';
+}
+
+/** NWS class labels for digital HC (indices 0–11). */
+const NEXRAD_HYDROMETEOR_CLASS_LABELS = [
+    'Biological',
+    'Ground clutter',
+    'Ice crystals',
+    'Dry snow',
+    'Wet snow',
+    'Light rain',
+    'Heavy rain',
+    'Big drops',
+    'Graupel',
+    'Hail/rain',
+    'Large hail',
+    'Giant hail',
+];
+
+function nexradHydrometeorLabelForClassIndex(value) {
+    const idx = Math.round(Number(value));
+    if (idx >= 12) return null;
+    if (idx >= 0 && idx < NEXRAD_HYDROMETEOR_CLASS_LABELS.length) {
+        return NEXRAD_HYDROMETEOR_CLASS_LABELS[idx];
+    }
+    return `Class ${idx}`;
+}
+
+function velocityMsToDisplay(valueMs, displayUnit) {
+    if (!displayUnit || displayUnit.toLowerCase() === 'm/s' || displayUnit.toLowerCase() === 'ms') {
+        return valueMs;
+    }
+    const fromMs = getUnitConversionFunction('m/s', displayUnit, 'nexrad_vel');
+    return fromMs ? fromMs(valueMs) : valueMs;
+}
+
+/** Standard 4/3-earth beam height (km AGL at antenna) from slant range and elevation — matches frontend `beamHeightKm`. */
+function beamHeightKm(slantRangeKm, elevDeg) {
+    const el = (elevDeg * Math.PI) / 180;
+    const ReKm = (6371000 * 4) / (3 * 1000);
+    const cosEl = Math.max(Math.cos(el), 0.05);
+    const s = slantRangeKm / cosEl;
+    return Math.sqrt(s * s + ReKm * ReKm + 2 * s * ReKm * Math.sin(el)) - ReKm;
+}
+
+function formatNexradInspectNumeric(raw, radarVariable) {
+    const vu = (radarVariable || '').toUpperCase();
+    const vl = radarVariable || '';
+    if (vu.includes('RATE') || vl.toLowerCase().includes('rate')) {
+        return Number(raw.toFixed(3).replace(/\.?0+$/, ''));
+    }
+    if (vu === 'RHO' || vu === 'ZDR' || vl.includes('RhoHV') || vl.includes('Zdr')) {
+        return Number(raw.toFixed(2));
+    }
+    if (Math.abs(raw) < 10) return Number(raw.toFixed(1));
+    return Math.round(raw);
+}
+
+const PRELOAD_CONCURRENCY = 4;
+
+export class NexradWeatherController {
+    constructor(map, core, options = {}) {
+        this.map = map;
+        this.core = core;
+        this.layerId = options.nexradLayerId || 'aguacero-nexrad-layer';
+        this.mapboxLayer = null;
+        this._lastFetchKey = null;
+        this._abort = null;
+        this._interpolateColormap = options.interpolateNexradColormap !== false;
+        this._gateSmoothing = options.nexradGateSmoothing === true;
+        /** Decoded radar frames keyed by fetchKey from _buildFetchParamsForUnix. */
+        this._frameCache = new Map();
+        this._preloadAbort = null;
+        this._preloadTimelineSig = null;
+        /** @type {(() => string | undefined) | null} */
+        this._getInsertBeforeLayerId = options.getInsertBeforeLayerId || null;
+    }
+
+    destroy() {
+        this._abort?.abort();
+        this._abort = null;
+        this._preloadAbort?.abort();
+        this._preloadAbort = null;
+        this._frameCache.clear();
+        this._preloadTimelineSig = null;
+        if (this.mapboxLayer && this.map.getLayer(this.mapboxLayer.id)) {
+            this.map.removeLayer(this.mapboxLayer.id);
+        }
+        this.mapboxLayer = null;
+        this._lastFetchKey = null;
+    }
+
+    _resolveListingContext(state) {
+        const nk = this.core._nexradTimesCacheKey?.();
+        const ent = nk ? this.core.nexradTimesByStation?.[nk] : null;
+        const timeToKeyMap = state.nexradTimeToKeyMap || ent?.timeToKeyMap || {};
+        const motionMap = state.nexradLevel3MotionTimeToKeyMap || ent?.level3MotionTimeToKeyMap || {};
+        return { nk, ent, timeToKeyMap, motionMap };
+    }
+
+    /**
+     * @param {object} state
+     * @param {number} unix
+     * @returns {{ objectKey: string, url: string, fetchKey: string, motionObjectKey: string | null, radarVar: string, radarSource: string, groupId: number } | null}
+     */
+    _buildFetchParamsForUnix(state, unix) {
+        const radarVar = (state.nexradProduct || 'REF').toUpperCase();
+        const radarSource = state.nexradDataSource === 'level3' ? 'level3' : 'level2';
+        const groupId = nexradBinGroupIdForKey(variableToNexradGroup(radarVar));
+        const { timeToKeyMap, motionMap } = this._resolveListingContext(state);
+        const objectKey = timeToKeyMap[String(unix)];
+        if (!objectKey) return null;
+
+        let motionObjectKey = null;
+        if (radarVar === 'VEL' && state.nexradStormRelative) {
+            motionObjectKey = pickNearestLevel3ObjectKey(unix, motionMap);
+        }
+
+        const url = objectKeyToUrl(objectKey, radarSource);
+        const fetchKey = `${url}|${radarVar}|${radarSource}|${motionObjectKey || ''}`;
+        return { objectKey, url, fetchKey, motionObjectKey, radarVar, radarSource, groupId };
+    }
+
+    async _fetchFrame(state, unix, { signal, priority }) {
+        const p = this._buildFetchParamsForUnix(state, unix);
+        if (!p) return null;
+        return fetchAndParseArchive(p.url, p.objectKey, p.radarVar, p.groupId, p.radarSource, {
+            signal,
+            priority,
+            level3MotionObjectKey: p.motionObjectKey,
+        });
+    }
+
+    _preloadTimelineSignature(state) {
+        const nk = this.core._nexradTimesCacheKey?.() || '';
+        const ts = [...(state.availableNexradTimestamps || [])]
+            .map(Number)
+            .filter((t) => Number.isFinite(t))
+            .sort((a, b) => a - b)
+            .join(',');
+        return `${nk}|${ts}|sr:${state.nexradStormRelative ? 1 : 0}`;
+    }
+
+    /**
+     * Background-load every volume on the slider timeline (like satellite KTX2 preload).
+     * Slider / `nexradTimestamp` changes only swap GPU buffers from cache when possible.
+     * @param {object} state
+     */
+    preloadAllAvailable(state) {
+        if (!state.isNexrad || !state.nexradSite) return;
+
+        const sig = this._preloadTimelineSignature(state);
+        if (sig === this._preloadTimelineSig) return;
+
+        this._preloadTimelineSig = sig;
+        this._preloadAbort?.abort();
+        this._preloadAbort = new AbortController();
+        const signal = this._preloadAbort.signal;
+
+        this._frameCache.clear();
+
+        setNexradArchiveApiKey(this.core.apiKey || '');
+
+        const times = [...(state.availableNexradTimestamps || [])]
+            .map(Number)
+            .filter((t) => Number.isFinite(t));
+        if (!times.length) return;
+
+        const snapshot = { ...state };
+
+        const run = async () => {
+            let cursor = 0;
+            const work = async () => {
+                while (cursor < times.length && !signal.aborted) {
+                    const i = cursor++;
+                    const unix = times[i];
+                    const p = this._buildFetchParamsForUnix(snapshot, unix);
+                    if (!p || signal.aborted) continue;
+                    if (this._frameCache.has(p.fetchKey)) continue;
+                    try {
+                        const frame = await this._fetchFrame(snapshot, unix, {
+                            signal,
+                            priority: 'prefetch',
+                        });
+                        if (frame && !signal.aborted) {
+                            this._frameCache.set(p.fetchKey, frame);
+                        }
+                    } catch {
+                        /* ignore failed preload tiles */
+                    }
+                }
+            };
+            await Promise.all(Array.from({ length: PRELOAD_CONCURRENCY }, () => work()));
+        };
+
+        void run();
+    }
+
+    _ensureLayer() {
+        if (this.mapboxLayer) return;
+        this.mapboxLayer = new MapboxRadarLayer(this.layerId);
+        let beforeId =
+            typeof this._getInsertBeforeLayerId === 'function'
+                ? this._getInsertBeforeLayerId()
+                : undefined;
+        if (!beforeId && this.map.getLayer('AML_-_terrain')) {
+            beforeId = 'AML_-_terrain';
+        }
+        if (beforeId) {
+            this.map.addLayer(this.mapboxLayer, beforeId);
+        } else {
+            this.map.addLayer(this.mapboxLayer);
+        }
+    }
+
+    _uploadFrame(state, frame) {
+        const radarVar = (state.nexradProduct || 'REF').toUpperCase();
+        this.mapboxLayer.setInterpolateColormap(this._interpolateColormap);
+        this.mapboxLayer.setGateSmoothing(this._gateSmoothing);
+
+        const colormapFlat = state.colormap;
+        const colormapForShader = colormapToMs(colormapFlat, radarVar, state.units);
+        const [shaderMin, shaderMax] = radarShaderValueRange(
+            colormapFlat?.[0],
+            colormapFlat?.[colormapFlat.length - 2],
+            radarVar,
+            state.units,
+            state.nexradDataSource,
+        );
+
+        this.mapboxLayer.setColormap(colormapForShader);
+        this.mapboxLayer.setValueRange(shaderMin, shaderMax);
+        this.mapboxLayer.setOpacity(state.opacity ?? 1);
+        this.mapboxLayer.setFrameData(frame, mapboxFrameUploadOptionsForNexradState(state));
+        this.map.triggerRepaint();
+    }
+
+    /**
+     * @param {object} state - core state + emitted colormap (from state:change)
+     */
+    async sync(state) {
+        if (!state.isNexrad || !state.nexradSite || state.nexradTimestamp == null) {
+            this.destroy();
+            return;
+        }
+
+        setNexradArchiveApiKey(this.core.apiKey || '');
+
+        const unix = Number(state.nexradTimestamp);
+        const p = this._buildFetchParamsForUnix(state, unix);
+        if (!p) {
+            return;
+        }
+
+        if (p.fetchKey === this._lastFetchKey && this.mapboxLayer) {
+            this._applyStyle(state);
+            return;
+        }
+
+        const cached = this._frameCache.get(p.fetchKey);
+        if (cached) {
+            this._ensureLayer();
+            this._uploadFrame(state, cached);
+            this._lastFetchKey = p.fetchKey;
+            return;
+        }
+
+        this._lastFetchKey = p.fetchKey;
+
+        this._abort?.abort();
+        this._abort = new AbortController();
+
+        let frame;
+        try {
+            frame = await this._fetchFrame(state, unix, {
+                signal: this._abort.signal,
+                priority: 'display',
+            });
+        } catch {
+            return;
+        }
+
+        if (!frame || this._abort.signal.aborted) return;
+
+        this._frameCache.set(p.fetchKey, frame);
+
+        this._ensureLayer();
+        this._uploadFrame(state, frame);
+    }
+
+    _applyStyle(state) {
+        if (!this.mapboxLayer) return;
+        const radarVar = (state.nexradProduct || 'REF').toUpperCase();
+        const colormapFlat = state.colormap;
+        const colormapForShader = colormapToMs(colormapFlat, radarVar, state.units);
+        const [shaderMin, shaderMax] = radarShaderValueRange(
+            colormapFlat?.[0],
+            colormapFlat?.[colormapFlat.length - 2],
+            radarVar,
+            state.units,
+            state.nexradDataSource,
+        );
+        this.mapboxLayer.setColormap(colormapForShader);
+        this.mapboxLayer.setValueRange(shaderMin, shaderMax);
+        this.mapboxLayer.setOpacity(state.opacity ?? 1);
+        this.map.triggerRepaint();
+    }
+
+    /**
+     * Mouse readout at lng/lat — same sampling and formatting as aguacero-frontend `NexradReadoutFrame`
+     * (polar sample + velocity/hydro/range checks). Uses the cached frame for the current timeline key.
+     *
+     * @param {number} lng
+     * @param {number} lat
+     * @param {object} state - Latest `state:change` payload (needs `colormap`, NEXRAD fields).
+     * @returns {object | null}
+     */
+    getInspectPayload(lng, lat, state) {
+        if (!state?.isNexrad || !state.nexradSite || state.nexradTimestamp == null) return null;
+        if (state.visible === false || (state.opacity ?? 1) <= 0) return null;
+
+        const unix = Number(state.nexradTimestamp);
+        const p = this._buildFetchParamsForUnix(state, unix);
+        if (!p) return null;
+
+        const frame = this._frameCache.get(p.fetchKey);
+        if (!frame) return null;
+
+        const colormapFlat = state.colormap;
+        if (!colormapFlat || colormapFlat.length < 2) return null;
+
+        const rangeMin = colormapFlat[0];
+        const rangeMax = colormapFlat[colormapFlat.length - 2];
+
+        const radarVariable = (state.nexradProduct || 'REF').toUpperCase();
+        const radarSource = state.nexradDataSource === 'level3' ? 'level3' : 'level2';
+        const displayUnits =
+            state.units && String(state.units).toLowerCase() !== 'none'
+                ? state.units
+                : isVelocityStyleRadarVar(radarVariable)
+                  ? 'm/s'
+                  : '';
+
+        const gpuFrame = prepareRadarFrameForGpuReadout(frame, mapboxFrameUploadOptionsForNexradState(state));
+        const sample = sampleNexradFrameAtLatLon(gpuFrame, lat, lng, { smoothPolar: this._gateSmoothing });
+        if (!sample) return null;
+
+        const valueMs = sample.value;
+        const isHydro = radarSource === 'level3' && nexradLevel3IsHydrometeorClassification(radarVariable);
+
+        /** @type {number | string} */
+        let valueOut;
+        let unitOut = displayUnits || '';
+
+        if (isVelocityStyleRadarVar(radarVariable)) {
+            valueOut = velocityMsToDisplay(valueMs, displayUnits);
+        } else if (isHydro) {
+            const label = nexradHydrometeorLabelForClassIndex(valueMs);
+            if (label == null) return null;
+            valueOut = label;
+            unitOut = '';
+        } else {
+            valueOut = formatNexradInspectNumeric(valueMs, radarVariable);
+        }
+
+        let inRange;
+        if (isHydro) {
+            const idx = Math.round(Number(valueMs));
+            inRange =
+                (rangeMin == null || idx >= rangeMin) && (rangeMax == null || idx <= rangeMax);
+        } else if (isVelocityStyleRadarVar(radarVariable)) {
+            inRange =
+                (rangeMin == null || valueOut >= rangeMin) && (rangeMax == null || valueOut <= rangeMax);
+        } else {
+            inRange =
+                (rangeMin == null || valueOut >= rangeMin) && (rangeMax == null || valueOut <= rangeMax);
+        }
+
+        if (!inRange) return null;
+
+        const tiltDeg = Number.isFinite(state.nexradTilt) ? state.nexradTilt : getDefaultRadarTilt(state.nexradSite);
+        const bhKm = beamHeightKm(sample.groundRangeKm, tiltDeg);
+        const metric = state.units === 'metric';
+        const beamHeightDisplay = metric ? bhKm : bhKm * 3.280839895013123;
+        const beamUnit = metric ? 'km' : 'kft';
+
+        const fldKey = state.variable;
+        return {
+            lngLat: { lng, lat },
+            variable: {
+                code: fldKey,
+                name: this.core.getVariableDisplayName(fldKey),
+            },
+            value: valueOut,
+            unit: unitOut,
+            beamHeight:
+                Number.isFinite(beamHeightDisplay) && Number.isFinite(bhKm)
+                    ? { value: beamHeightDisplay, unit: beamUnit }
+                    : null,
+        };
+    }
+}