@aguacerowx/mapsgl 0.0.57 → 0.0.58

package/src/nexrad/nexradCrossSectionSampleAtLatLon.ts

@@ -1,121 +1,121 @@
-/**
- * Sample a decoded NEXRAD frame at lat/lon (same geometry as MapboxRadarLayer / readout).
- * Extracted from RadarLayer so workers and cross-section code can import without pulling the layer bundle.
- */
-import type { DecodedRadarFrame } from './nexradArchiveCache.js';
-
-export type SampleNexradAtLatLonOptions = {
-    /**
-     * When true, match `MapboxRadarLayer` with gate smoothing: continuous gateX/gateY + bilinear blend of
-     * decoded int16 samples (nodata excluded). When false, snap to nearest gate/ray like unsmoothed shader.
-     */
-    smoothPolar?: boolean;
-};
-
-function wrapAzimuthDeltaDeg(azDeg: number, azimuthBaseDeg: number): number {
-    let da = azDeg - azimuthBaseDeg;
-    da -= Math.floor(da / 360) * 360;
-    if (da < 0) da += 360;
-    return da;
-}
-
-/** Same as `snapGateCoord` in MapboxRadarLayer fragment shader. */
-function snapGateCoord(t: number, nCells: number): number {
-    if (nCells <= 1) return 0;
-    const idx = Math.floor(t * (nCells - 1) + 0.5);
-    return idx / (nCells - 1);
-}
-
-function readGateRawSigned(frame: DecodedRadarFrame, rayIdx: number, gateIdx: number): number | null {
-    if (rayIdx < 0 || gateIdx < 0 || rayIdx >= frame.nRays || gateIdx >= frame.nGates) return null;
-    const byteOffset = (rayIdx * frame.nGates + gateIdx) * 2;
-    const hi = frame.gateData[byteOffset]!;
-    const lo = frame.gateData[byteOffset + 1]!;
-    const raw = lo + hi * 256;
-    const rawSigned = raw >= 32768 ? raw - 65536 : raw;
-    if (rawSigned <= -32768) return null;
-    return rawSigned;
-}
-
-/** Mirrors `sampleGateRawBilinear` in MapboxRadarLayer (NEAREST cells, blend after decode). */
-function sampleGateRawBilinearDecoded(frame: DecodedRadarFrame, gateX: number, gateY: number): number | null {
-    const w = frame.nGates;
-    const h = frame.nRays;
-    if (w < 1 || h < 1) return null;
-    const gx = Math.min(1, Math.max(0, gateX));
-    const gy = Math.min(1, Math.max(0, gateY));
-    const sx = gx * Math.max(w - 1, 1);
-    const sy = gy * Math.max(h - 1, 1);
-    const i0 = Math.floor(sx);
-    const j0 = Math.floor(sy);
-    const i1 = Math.min(i0 + 1, w - 1);
-    const j1 = Math.min(j0 + 1, h - 1);
-    const fx = sx - i0;
-    const fy = sy - j0;
-    const w00 = (1 - fx) * (1 - fy);
-    const w10 = fx * (1 - fy);
-    const w01 = (1 - fx) * fy;
-    const w11 = fx * fy;
-    let acc = 0;
-    let wsum = 0;
-    const add = (r: number | null, wt: number) => {
-        if (r !== null) {
-            acc += r * wt;
-            wsum += wt;
-        }
-    };
-    add(readGateRawSigned(frame, j0, i0), w00);
-    add(readGateRawSigned(frame, j0, i1), w10);
-    add(readGateRawSigned(frame, j1, i0), w01);
-    add(readGateRawSigned(frame, j1, i1), w11);
-    if (wsum < 1e-6) return null;
-    return acc / wsum;
-}
-
-export function sampleNexradFrameAtLatLon(
-    frame: DecodedRadarFrame,
-    lat: number,
-    lon: number,
-    options?: SampleNexradAtLatLonOptions,
-): { value: number; groundRangeKm: number } | null {
-    const DEG_TO_RAD = Math.PI / 180;
-    const EARTH_RADIUS_M = 6378137;
-
-    const dLatDeg = lat - frame.stationLat;
-    const dLonDeg = lon - frame.stationLon;
-    const cosLat = Math.max(Math.cos(lat * DEG_TO_RAD), 1e-6);
-    const xM = dLonDeg * DEG_TO_RAD * EARTH_RADIUS_M * cosLat;
-    const yM = dLatDeg * DEG_TO_RAD * EARTH_RADIUS_M;
-    const rangeM = Math.hypot(xM, yM);
-    const rangeKm = rangeM / 1000;
-
-    if (rangeKm < frame.firstGateKm) return null;
-    const spanKm = frame.nGates * frame.gateWidthKm;
-    if (!(spanKm > 0)) return null;
-    const maxRangeKm = frame.firstGateKm + spanKm;
-    if (rangeKm >= maxRangeKm) return null;
-
-    let azDeg = Math.atan2(xM, yM) * (180 / Math.PI);
-    if (azDeg < 0) azDeg += 360;
-
-    const boundaries = frame.rayBoundariesDeg;
-    const azimuthBaseDeg = boundaries.length > 0 ? Number(boundaries[0]) : 0;
-    const da = wrapAzimuthDeltaDeg(azDeg, azimuthBaseDeg);
-    let gateY = da / 360;
-    gateY = Math.min(1, Math.max(0, gateY));
-
-    let gateX = (rangeKm - frame.firstGateKm) / spanKm;
-    gateX = Math.min(1, Math.max(0, gateX));
-
-    const smoothPolar = options?.smoothPolar === true;
-    if (!smoothPolar) {
-        gateX = snapGateCoord(gateX, frame.nGates);
-        gateY = snapGateCoord(gateY, frame.nRays);
-    }
-
-    const rawSigned = sampleGateRawBilinearDecoded(frame, gateX, gateY);
-    if (rawSigned === null) return null;
-
-    const physical = rawSigned * frame.valueScale + frame.valueOffset;
-    return { value: physical, groundRangeKm: rangeKm };
-}
+/**
+ * Sample a decoded NEXRAD frame at lat/lon (same geometry as MapboxRadarLayer / readout).
+ * Extracted from RadarLayer so workers and cross-section code can import without pulling the layer bundle.
+ */
+import type { DecodedRadarFrame } from './nexradArchiveCache.js';
+
+export type SampleNexradAtLatLonOptions = {
+    /**
+     * When true, match `MapboxRadarLayer` with gate smoothing: continuous gateX/gateY + bilinear blend of
+     * decoded int16 samples (nodata excluded). When false, snap to nearest gate/ray like unsmoothed shader.
+     */
+    smoothPolar?: boolean;
+};
+
+function wrapAzimuthDeltaDeg(azDeg: number, azimuthBaseDeg: number): number {
+    let da = azDeg - azimuthBaseDeg;
+    da -= Math.floor(da / 360) * 360;
+    if (da < 0) da += 360;
+    return da;
+}
+
+/** Same as `snapGateCoord` in MapboxRadarLayer fragment shader. */
+function snapGateCoord(t: number, nCells: number): number {
+    if (nCells <= 1) return 0;
+    const idx = Math.floor(t * (nCells - 1) + 0.5);
+    return idx / (nCells - 1);
+}
+
+function readGateRawSigned(frame: DecodedRadarFrame, rayIdx: number, gateIdx: number): number | null {
+    if (rayIdx < 0 || gateIdx < 0 || rayIdx >= frame.nRays || gateIdx >= frame.nGates) return null;
+    const byteOffset = (rayIdx * frame.nGates + gateIdx) * 2;
+    const hi = frame.gateData[byteOffset]!;
+    const lo = frame.gateData[byteOffset + 1]!;
+    const raw = lo + hi * 256;
+    const rawSigned = raw >= 32768 ? raw - 65536 : raw;
+    if (rawSigned <= -32768) return null;
+    return rawSigned;
+}
+
+/** Mirrors `sampleGateRawBilinear` in MapboxRadarLayer (NEAREST cells, blend after decode). */
+function sampleGateRawBilinearDecoded(frame: DecodedRadarFrame, gateX: number, gateY: number): number | null {
+    const w = frame.nGates;
+    const h = frame.nRays;
+    if (w < 1 || h < 1) return null;
+    const gx = Math.min(1, Math.max(0, gateX));
+    const gy = Math.min(1, Math.max(0, gateY));
+    const sx = gx * Math.max(w - 1, 1);
+    const sy = gy * Math.max(h - 1, 1);
+    const i0 = Math.floor(sx);
+    const j0 = Math.floor(sy);
+    const i1 = Math.min(i0 + 1, w - 1);
+    const j1 = Math.min(j0 + 1, h - 1);
+    const fx = sx - i0;
+    const fy = sy - j0;
+    const w00 = (1 - fx) * (1 - fy);
+    const w10 = fx * (1 - fy);
+    const w01 = (1 - fx) * fy;
+    const w11 = fx * fy;
+    let acc = 0;
+    let wsum = 0;
+    const add = (r: number | null, wt: number) => {
+        if (r !== null) {
+            acc += r * wt;
+            wsum += wt;
+        }
+    };
+    add(readGateRawSigned(frame, j0, i0), w00);
+    add(readGateRawSigned(frame, j0, i1), w10);
+    add(readGateRawSigned(frame, j1, i0), w01);
+    add(readGateRawSigned(frame, j1, i1), w11);
+    if (wsum < 1e-6) return null;
+    return acc / wsum;
+}
+
+export function sampleNexradFrameAtLatLon(
+    frame: DecodedRadarFrame,
+    lat: number,
+    lon: number,
+    options?: SampleNexradAtLatLonOptions,
+): { value: number; groundRangeKm: number } | null {
+    const DEG_TO_RAD = Math.PI / 180;
+    const EARTH_RADIUS_M = 6378137;
+
+    const dLatDeg = lat - frame.stationLat;
+    const dLonDeg = lon - frame.stationLon;
+    const cosLat = Math.max(Math.cos(lat * DEG_TO_RAD), 1e-6);
+    const xM = dLonDeg * DEG_TO_RAD * EARTH_RADIUS_M * cosLat;
+    const yM = dLatDeg * DEG_TO_RAD * EARTH_RADIUS_M;
+    const rangeM = Math.hypot(xM, yM);
+    const rangeKm = rangeM / 1000;
+
+    if (rangeKm < frame.firstGateKm) return null;
+    const spanKm = frame.nGates * frame.gateWidthKm;
+    if (!(spanKm > 0)) return null;
+    const maxRangeKm = frame.firstGateKm + spanKm;
+    if (rangeKm >= maxRangeKm) return null;
+
+    let azDeg = Math.atan2(xM, yM) * (180 / Math.PI);
+    if (azDeg < 0) azDeg += 360;
+
+    const boundaries = frame.rayBoundariesDeg;
+    const azimuthBaseDeg = boundaries.length > 0 ? Number(boundaries[0]) : 0;
+    const da = wrapAzimuthDeltaDeg(azDeg, azimuthBaseDeg);
+    let gateY = da / 360;
+    gateY = Math.min(1, Math.max(0, gateY));
+
+    let gateX = (rangeKm - frame.firstGateKm) / spanKm;
+    gateX = Math.min(1, Math.max(0, gateX));
+
+    const smoothPolar = options?.smoothPolar === true;
+    if (!smoothPolar) {
+        gateX = snapGateCoord(gateX, frame.nGates);
+        gateY = snapGateCoord(gateY, frame.nRays);
+    }
+
+    const rawSigned = sampleGateRawBilinearDecoded(frame, gateX, gateY);
+    if (rawSigned === null) return null;
+
+    const physical = rawSigned * frame.valueScale + frame.valueOffset;
+    return { value: physical, groundRangeKm: rangeKm };
+}

package/src/nexrad/nexradMapboxFrameOpts.ts

@@ -1,126 +1,126 @@
-/**
- * MapboxRadarLayer upload options for NEXRAD — matches aguacero-frontend `RadarLayer` / MapboxRadarLayer docs:
- * Level-III KDP/N0H/VEL use {@link geometryLayoutKey} so frames use canonical azimuth bins (stable mesh; fast scrub).
- * Other Level-III radials use ray-boundary-keyed geometry when layout cannot be fixed to a manifest product.
- */
-import { clampNexradTiltForVariable, getDefaultRadarTilt, getRadarTilts } from '@aguacerowx/javascript-sdk';
-import { nexradLevel3S3VelocityProductForSiteTilt } from './nexradLevel3Products.js';
-
-export type MapboxRadarFrameUploadOptions = {
-    geometryLayoutKey?: string;
-    geometryCacheKeysRayBoundaries?: boolean;
-};
-
-const NEXRAD_LEVEL3_KDP_PRODUCTS_FOR_MANIFEST = [
-    'N0K',
-    'NAK',
-    'N1K',
-    'NBK',
-    'N2K',
-    'N3K',
-];
-
-const NEXRAD_LEVEL3_DHC_PRODUCTS_FOR_MANIFEST = [
-    'N0H',
-    'NAH',
-    'N1H',
-    'NBH',
-    'N2H',
-    'N3H',
-];
-
-const NEXRAD_LEVEL3_MANIFEST_TILT_COUNT = NEXRAD_LEVEL3_KDP_PRODUCTS_FOR_MANIFEST.length;
-
-function nearestTiltInSortedList(tilts: number[], target: number): number {
-    if (!tilts.length) return target;
-    let best = tilts[0]!;
-    let bestD = Math.abs(best - target);
-    for (let i = 1; i < tilts.length; i++) {
-        const t = tilts[i]!;
-        const d = Math.abs(t - target);
-        if (d < bestD || (d === bestD && t < best)) {
-            best = t;
-            bestD = d;
-        }
-    }
-    return best;
-}
-
-function getNexradLevel3RadarTilts(siteId: string, radarVariable: string): number[] {
-    return getRadarTilts(siteId, radarVariable).slice(0, NEXRAD_LEVEL3_MANIFEST_TILT_COUNT);
-}
-
-export function nexradLevel3UsesTiltIndexedS3Products(radarVariable: string | undefined): boolean {
-    const v = radarVariable || '';
-    return v === 'KDP' || v === 'N0H';
-}
-
-function clampTiltForLevel3CompositeKey(siteId: string, radarVariable: string, tilt: number): number {
-    if (!nexradLevel3UsesTiltIndexedS3Products(radarVariable)) {
-        return clampNexradTiltForVariable(siteId, radarVariable, tilt);
-    }
-    const tilts = getNexradLevel3RadarTilts(siteId, radarVariable);
-    const c = clampNexradTiltForVariable(siteId, radarVariable, tilt);
-    if (!tilts.length) return c;
-    return nearestTiltInSortedList(tilts, c);
-}
-
-/**
- * Map site tilt to Level-III S3 product mnemonic (N0K, NAK, … / N0H, …) — aguacero-frontend parity.
- */
-export function nexradLevel3S3ProductForSiteTilt(
-    siteId: string,
-    radarVariable: 'KDP' | 'N0H',
-    tilt: number,
-): string {
-    const products =
-        radarVariable === 'KDP' ? NEXRAD_LEVEL3_KDP_PRODUCTS_FOR_MANIFEST : NEXRAD_LEVEL3_DHC_PRODUCTS_FOR_MANIFEST;
-    const tilts = getNexradLevel3RadarTilts(siteId, radarVariable);
-    if (!tilts.length) {
-        return products[0]!;
-    }
-    const clamped = clampTiltForLevel3CompositeKey(siteId, radarVariable, tilt);
-    let idx = tilts.indexOf(clamped);
-    if (idx === -1) {
-        idx = tilts.reduce(
-            (bestI, t, i) => (Math.abs(t - clamped) < Math.abs(tilts[bestI]! - clamped) ? i : bestI),
-            0,
-        );
-    }
-    idx = Math.min(idx, products.length - 1);
-    return products[idx]!;
-}
-
-type NexradStateForMapbox = {
-    nexradDataSource?: string;
-    nexradSite?: string | null;
-    nexradProduct?: string | null;
-    nexradTilt?: number | null;
-};
-
-/**
- * @param state - AguaceroCore state (or state:change payload) with NEXRAD fields
- */
-export function mapboxFrameUploadOptionsForNexradState(
-    state: NexradStateForMapbox | null | undefined,
-): MapboxRadarFrameUploadOptions | undefined {
-    if (!state) return { geometryLayoutKey: 'canonical' };
-    if (state.nexradDataSource !== 'level3') return { geometryLayoutKey: 'canonical' };
-    const site = state.nexradSite;
-    const radarVar = (state.nexradProduct || 'REF').toUpperCase();
-
-    if (nexradLevel3UsesTiltIndexedS3Products(radarVar) && site) {
-        const tilt = Number.isFinite(state.nexradTilt) ? Number(state.nexradTilt) : getDefaultRadarTilt(site);
-        const kind = radarVar === 'KDP' ? 'KDP' : 'N0H';
-        const mnemonic = nexradLevel3S3ProductForSiteTilt(site, kind, tilt);
-        return { geometryLayoutKey: `${site}|${radarVar}|${mnemonic}` };
-    }
-
-    if (radarVar === 'VEL' && site) {
-        const tilt = Number.isFinite(state.nexradTilt) ? Number(state.nexradTilt) : getDefaultRadarTilt(site);
-        const mnemonic = nexradLevel3S3VelocityProductForSiteTilt(site, tilt);
-        return { geometryLayoutKey: `${site}|${radarVar}|${mnemonic}` };
-    }
-
-    return { geometryLayoutKey: 'canonical' };
-}
+/**
+ * MapboxRadarLayer upload options for NEXRAD — matches aguacero-frontend `RadarLayer` / MapboxRadarLayer docs:
+ * Level-III KDP/N0H/VEL use {@link geometryLayoutKey} so frames use canonical azimuth bins (stable mesh; fast scrub).
+ * Other Level-III radials use ray-boundary-keyed geometry when layout cannot be fixed to a manifest product.
+ */
+import { clampNexradTiltForVariable, getDefaultRadarTilt, getRadarTilts } from '@aguacerowx/javascript-sdk';
+import { nexradLevel3S3VelocityProductForSiteTilt } from './nexradLevel3Products.js';
+
+export type MapboxRadarFrameUploadOptions = {
+    geometryLayoutKey?: string;
+    geometryCacheKeysRayBoundaries?: boolean;
+};
+
+const NEXRAD_LEVEL3_KDP_PRODUCTS_FOR_MANIFEST = [
+    'N0K',
+    'NAK',
+    'N1K',
+    'NBK',
+    'N2K',
+    'N3K',
+];
+
+const NEXRAD_LEVEL3_DHC_PRODUCTS_FOR_MANIFEST = [
+    'N0H',
+    'NAH',
+    'N1H',
+    'NBH',
+    'N2H',
+    'N3H',
+];
+
+const NEXRAD_LEVEL3_MANIFEST_TILT_COUNT = NEXRAD_LEVEL3_KDP_PRODUCTS_FOR_MANIFEST.length;
+
+function nearestTiltInSortedList(tilts: number[], target: number): number {
+    if (!tilts.length) return target;
+    let best = tilts[0]!;
+    let bestD = Math.abs(best - target);
+    for (let i = 1; i < tilts.length; i++) {
+        const t = tilts[i]!;
+        const d = Math.abs(t - target);
+        if (d < bestD || (d === bestD && t < best)) {
+            best = t;
+            bestD = d;
+        }
+    }
+    return best;
+}
+
+function getNexradLevel3RadarTilts(siteId: string, radarVariable: string): number[] {
+    return getRadarTilts(siteId, radarVariable).slice(0, NEXRAD_LEVEL3_MANIFEST_TILT_COUNT);
+}
+
+export function nexradLevel3UsesTiltIndexedS3Products(radarVariable: string | undefined): boolean {
+    const v = radarVariable || '';
+    return v === 'KDP' || v === 'N0H';
+}
+
+function clampTiltForLevel3CompositeKey(siteId: string, radarVariable: string, tilt: number): number {
+    if (!nexradLevel3UsesTiltIndexedS3Products(radarVariable)) {
+        return clampNexradTiltForVariable(siteId, radarVariable, tilt);
+    }
+    const tilts = getNexradLevel3RadarTilts(siteId, radarVariable);
+    const c = clampNexradTiltForVariable(siteId, radarVariable, tilt);
+    if (!tilts.length) return c;
+    return nearestTiltInSortedList(tilts, c);
+}
+
+/**
+ * Map site tilt to Level-III S3 product mnemonic (N0K, NAK, … / N0H, …) — aguacero-frontend parity.
+ */
+export function nexradLevel3S3ProductForSiteTilt(
+    siteId: string,
+    radarVariable: 'KDP' | 'N0H',
+    tilt: number,
+): string {
+    const products =
+        radarVariable === 'KDP' ? NEXRAD_LEVEL3_KDP_PRODUCTS_FOR_MANIFEST : NEXRAD_LEVEL3_DHC_PRODUCTS_FOR_MANIFEST;
+    const tilts = getNexradLevel3RadarTilts(siteId, radarVariable);
+    if (!tilts.length) {
+        return products[0]!;
+    }
+    const clamped = clampTiltForLevel3CompositeKey(siteId, radarVariable, tilt);
+    let idx = tilts.indexOf(clamped);
+    if (idx === -1) {
+        idx = tilts.reduce(
+            (bestI, t, i) => (Math.abs(t - clamped) < Math.abs(tilts[bestI]! - clamped) ? i : bestI),
+            0,
+        );
+    }
+    idx = Math.min(idx, products.length - 1);
+    return products[idx]!;
+}
+
+type NexradStateForMapbox = {
+    nexradDataSource?: string;
+    nexradSite?: string | null;
+    nexradProduct?: string | null;
+    nexradTilt?: number | null;
+};
+
+/**
+ * @param state - AguaceroCore state (or state:change payload) with NEXRAD fields
+ */
+export function mapboxFrameUploadOptionsForNexradState(
+    state: NexradStateForMapbox | null | undefined,
+): MapboxRadarFrameUploadOptions | undefined {
+    if (!state) return { geometryLayoutKey: 'canonical' };
+    if (state.nexradDataSource !== 'level3') return { geometryLayoutKey: 'canonical' };
+    const site = state.nexradSite;
+    const radarVar = (state.nexradProduct || 'REF').toUpperCase();
+
+    if (nexradLevel3UsesTiltIndexedS3Products(radarVar) && site) {
+        const tilt = Number.isFinite(state.nexradTilt) ? Number(state.nexradTilt) : getDefaultRadarTilt(site);
+        const kind = radarVar === 'KDP' ? 'KDP' : 'N0H';
+        const mnemonic = nexradLevel3S3ProductForSiteTilt(site, kind, tilt);
+        return { geometryLayoutKey: `${site}|${radarVar}|${mnemonic}` };
+    }
+
+    if (radarVar === 'VEL' && site) {
+        const tilt = Number.isFinite(state.nexradTilt) ? Number(state.nexradTilt) : getDefaultRadarTilt(site);
+        const mnemonic = nexradLevel3S3VelocityProductForSiteTilt(site, tilt);
+        return { geometryLayoutKey: `${site}|${radarVar}|${mnemonic}` };
+    }
+
+    return { geometryLayoutKey: 'canonical' };
+}