@aguacerowx/mapsgl 0.0.31 → 0.0.41

package/src/nexrad/PreprocessedSweepParser.ts

@@ -0,0 +1,226 @@
+/**
+ * Parser for the pre-processed sweep binary format produced by the NEXRAD Lambda.
+ *
+ * Binary layout (all little-endian — numpy default on x86):
+ *   [0-3]   int32   version = 1
+ *   [4-7]   float32 scale
+ *   [8-11]  float32 offset
+ *   [12-15] float32 sweep_idx
+ *   [16-19] float32 elev_angle (degrees)
+ *   [20-23] float32 n_rays 
+ *   [24-27] float32 n_gates
+ *   [28-31] float32 first_gate (km — range to center of first gate)
+ *   [32-35] float32 gate_width (km — range sample interval)
+ *   [36 ...]              float32[n_rays] azimuths (degrees)
+ *   [36+n_rays*4 ...]     float32[n_rays] elevations (degrees, unused for 2-D rendering)
+ *   [36+n_rays*8 ...]     int16[n_rays * n_gates] gate values (-32768 = masked/NaN)
+ *
+ * Gate decoding: physical_value = raw_int16 * scale + offset  (when raw != -32768)
+ * Masked gates are stored as -99 in the output dataMoments array to match the
+ * existing VertexDataGenerator convention.
+ */
+
+const PREPROCESSED_VERSION = 1;
+const HEADER_SIZE = 36; // 4 + 8 + 24 bytes
+
+export interface NexradSite {
+    id: string;
+    lat: number;
+    lon: number;
+}
+
+/** Minimal moment interface consumed by VertexDataGenerator */
+export interface SweepMoment {
+    dataMomentName: string;
+    azimuth: number;
+    /** Distance to center of first gate (km) */
+    dataMomentRange: number;
+    /** Gate width / range sample interval (km) */
+    dataMomentRangeSampleInterval: number;
+    /** Physical gate values; masked gates = -99 */
+    dataMoments: Float32Array;
+}
+
+export interface SweepRay {
+    dataMoments: SweepMoment[];
+}
+
+/** Minimal archive interface consumed by VertexDataGenerator and MapboxRadarLayer */
+export interface RadarArchive {
+    latitude: number;
+    longitude: number;
+    fieldName: string;
+    elevAngle: number;
+    nRays: number;
+    nGates: number;
+    volume: {
+        sweeps: Array<{ rays: SweepRay[] }>;
+    };
+}
+
+/**
+ * Returns true if the buffer starts with the preprocessed sweep version header.
+ * Used in RadarLayer to dispatch to the correct parser.
+ */
+export function isPreprocessedFormat(buffer: ArrayBuffer): boolean {
+    if (buffer.byteLength < HEADER_SIZE) return false;
+    return new DataView(buffer).getInt32(0, true) === PREPROCESSED_VERSION;
+}
+
+export function parsePreprocessedSweep(
+    buffer: ArrayBuffer,
+    stationId: string,
+    fieldName: string,
+    nexradSites: NexradSite[],
+): RadarArchive | null {
+    const LE = true;
+    const view = new DataView(buffer);
+
+    const version = view.getInt32(0, LE);
+    if (version !== PREPROCESSED_VERSION) {
+        console.error(`[PreprocessedSweepParser] Unknown version ${version}, expected ${PREPROCESSED_VERSION}`);
+        return null;
+    }
+
+    const scale     = view.getFloat32(4,  LE);
+    const offsetVal = view.getFloat32(8,  LE);
+    // sweep_idx at bytes 12-15 (not needed for rendering)
+    const elevAngle = view.getFloat32(16, LE);
+    const nRays     = Math.round(view.getFloat32(20, LE));
+    const nGates    = Math.round(view.getFloat32(24, LE));
+    const firstGate = view.getFloat32(28, LE); // km
+    const gateWidth = view.getFloat32(32, LE); // km
+
+    const azOffset   = HEADER_SIZE;                    // 36
+    const elOffset   = azOffset  + nRays * 4;          // 36 + nRays*4
+    const gateOffset = elOffset  + nRays * 4;          // 36 + nRays*8
+
+    const expectedBytes = gateOffset + nRays * nGates * 2;
+    if (buffer.byteLength < expectedBytes) {
+        console.error(
+            `[PreprocessedSweepParser] Buffer too small: got ${buffer.byteLength} bytes, ` +
+            `need ${expectedBytes} (nRays=${nRays}, nGates=${nGates})`,
+        );
+        return null;
+    }
+
+    const site = nexradSites.find(s => s.id === stationId);
+    if (!site) {
+        console.error(`[PreprocessedSweepParser] Station "${stationId}" not found in nexrad.json`);
+        return null;
+    }
+
+    // Slice into aligned copies for typed-array access
+    const azimuths = new Float32Array(buffer.slice(azOffset, azOffset + nRays * 4));
+    const gatesRaw = new Int16Array(buffer.slice(gateOffset, gateOffset + nRays * nGates * 2));
+
+    const rays: SweepRay[] = [];
+    for (let i = 0; i < nRays; i++) {
+        const physicalGates = new Float32Array(nGates);
+        const base = i * nGates;
+        for (let g = 0; g < nGates; g++) {
+            const raw = gatesRaw[base + g];
+            physicalGates[g] = raw === -32768 ? -99 : raw * scale + offsetVal;
+        }
+        rays.push({
+            dataMoments: [{
+                dataMomentName: fieldName,
+                azimuth: azimuths[i],
+                dataMomentRange: firstGate,
+                dataMomentRangeSampleInterval: gateWidth,
+                dataMoments: physicalGates,
+            }],
+        });
+    }
+
+    return {
+        latitude: site.lat,
+        longitude: site.lon,
+        fieldName,
+        elevAngle,
+        nRays,
+        nGates,
+        volume: { sweeps: [{ rays }] },
+    };
+}
+
+const SLOT_HDR_BYTES = 28;
+
+export function parseSlotBuffer(
+    buffer: ArrayBuffer,
+    stationId: string,
+    fieldName: string,
+    nexradSites: NexradSite[],
+    // These come from the file header fetched separately
+    nRaysFile: number,
+    nGatesFile: number,
+    firstGateKm: number,
+    gateWidthKm: number,
+    azimuths: Float32Array,
+): RadarArchive | null {
+    const BE = false; // DataView default is big-endian when false
+    const view = new DataView(buffer);
+
+    const scale    = view.getFloat32(0,  false); // big-endian
+    const offsetV  = view.getFloat32(4,  false);
+    const present  = view.getUint32(8,   false);
+    const nRays    = view.getUint16(12,  false);
+    const nGates   = view.getUint16(14,  false);
+
+    if (present === 0) {
+        console.warn(`[parseSlotBuffer] Slot for ${fieldName} marked not present`);
+        return null;
+    }
+
+    const gateOffset = SLOT_HDR_BYTES;
+    const expectedBytes = gateOffset + nRays * nGates * 2;
+    if (buffer.byteLength < expectedBytes) {
+        console.error(
+            `[parseSlotBuffer] Buffer too small: got ${buffer.byteLength}, need ${expectedBytes}`
+        );
+        return null;
+    }
+
+    const site = nexradSites.find(s => s.id === stationId);
+    if (!site) {
+        console.error(`[parseSlotBuffer] Station "${stationId}" not found`);
+        return null;
+    }
+
+    // Gate data is big-endian int16
+    const gateBytes = buffer.slice(gateOffset, gateOffset + nRays * nGates * 2);
+    const gatesRaw = new Int16Array(nRays * nGates);
+    const gateView = new DataView(gateBytes);
+    for (let i = 0; i < nRays * nGates; i++) {
+        gatesRaw[i] = gateView.getInt16(i * 2, false); // big-endian
+    }
+
+    const rays: SweepRay[] = [];
+    for (let i = 0; i < nRays; i++) {
+        const physicalGates = new Float32Array(nGates);
+        const base = i * nGates;
+        for (let g = 0; g < nGates; g++) {
+            const raw = gatesRaw[base + g];
+            physicalGates[g] = raw === -32768 ? -99 : raw * scale + offsetV;
+        }
+        rays.push({
+            dataMoments: [{
+                dataMomentName:               fieldName,
+                azimuth:                      azimuths[i],
+                dataMomentRange:              firstGateKm,
+                dataMomentRangeSampleInterval: gateWidthKm,
+                dataMoments:                  physicalGates,
+            }],
+        });
+    }
+
+    return {
+        latitude:  site.lat,
+        longitude: site.lon,
+        fieldName,
+        elevAngle: 0, // not stored in slot, pass from file header if needed
+        nRays,
+        nGates,
+        volume: { sweeps: [{ rays }] },
+    };
+}

package/src/nexrad/buildRadarRayGeometry.ts

@@ -0,0 +1,97 @@
+/**
+ * CPU-heavy polar wedge mesh for {@link MapboxRadarLayer}. Extracted for Web Worker offload.
+ */
+export type RadarRayGeometryFrame = {
+    nRays: number;
+    nGates: number;
+    stationLat: number;
+    stationLon: number;
+    firstGateKm: number;
+    gateWidthKm: number;
+    rayBoundariesDeg: Float32Array;
+};
+
+export function buildRadarRayGeometryBuffer(frame: RadarRayGeometryFrame): {
+    buffer: Float32Array;
+    anchorMercator: { x: number; y: number };
+} {
+    const nRays = frame.nRays;
+    const nGates = frame.nGates;
+    if (nRays <= 0 || nGates <= 0) {
+        return { buffer: new Float32Array(0), anchorMercator: { x: 0, y: 0 } };
+    }
+    if (frame.rayBoundariesDeg.length < nRays + 1) {
+        return { buffer: new Float32Array(0), anchorMercator: { x: 0, y: 0 } };
+    }
+
+    const nearRangeM = frame.firstGateKm * 1000;
+    const farRangeM = (frame.firstGateKm + frame.gateWidthKm * nGates) * 1000;
+
+    const floatsPerVertex = 4;
+    const vertsPerGate = 6;
+    const out = new Float32Array(nRays * nGates * vertsPerGate * floatsPerVertex);
+    let write = 0;
+
+    const mercatorXFromLonDeg = (lonDeg: number) => (lonDeg + 180) / 360;
+    const mercatorYFromLatRad = (latRad: number) =>
+        (1 - Math.log(Math.tan(Math.PI * 0.25 + latRad * 0.5)) / Math.PI) * 0.5;
+
+    const anchorX = mercatorXFromLonDeg(frame.stationLon);
+    const anchorY = mercatorYFromLatRad(frame.stationLat * (Math.PI / 180));
+    const anchorMercator = { x: anchorX, y: anchorY };
+
+    const getDestination = (lat: number, lon: number, distanceM: number, bearingDeg: number) => {
+        const R = 6378137;
+        const dRad = distanceM / R;
+        const bRad = bearingDeg * (Math.PI / 180);
+        const lat1 = lat * (Math.PI / 180);
+        const lon1 = lon * (Math.PI / 180);
+        const lat2 = Math.asin(Math.sin(lat1) * Math.cos(dRad) + Math.cos(lat1) * Math.sin(dRad) * Math.cos(bRad));
+        const lon2 =
+            lon1 +
+            Math.atan2(
+                Math.sin(bRad) * Math.sin(dRad) * Math.cos(lat1),
+                Math.cos(dRad) - Math.sin(lat1) * Math.sin(lat2),
+            );
+        return {
+            x: mercatorXFromLonDeg(lon2 * (180 / Math.PI)) - anchorX,
+            y: mercatorYFromLatRad(lat2) - anchorY,
+        };
+    };
+
+    const writeVertex = (x: number, y: number, u: number, v: number) => {
+        out[write++] = x;
+        out[write++] = y;
+        out[write++] = u;
+        out[write++] = v;
+    };
+
+    for (let rayIdx = 0; rayIdx < nRays; rayIdx++) {
+        const az1 = frame.rayBoundariesDeg[rayIdx]!;
+        const az2 = frame.rayBoundariesDeg[rayIdx + 1]!;
+        const v0 = rayIdx / nRays;
+        const v1 = (rayIdx + 1) / nRays;
+
+        for (let g = 0; g < nGates; g++) {
+            const r1 = nearRangeM + (farRangeM - nearRangeM) * (g / nGates);
+            const r2 = nearRangeM + (farRangeM - nearRangeM) * ((g + 1) / nGates);
+            const u0 = g / nGates;
+            const u1 = (g + 1) / nGates;
+
+            const nearLeft = getDestination(frame.stationLat, frame.stationLon, r1, az1);
+            const nearRight = getDestination(frame.stationLat, frame.stationLon, r1, az2);
+            const farLeft = getDestination(frame.stationLat, frame.stationLon, r2, az1);
+            const farRight = getDestination(frame.stationLat, frame.stationLon, r2, az2);
+
+            writeVertex(nearLeft.x, nearLeft.y, u0, v0);
+            writeVertex(nearRight.x, nearRight.y, u0, v1);
+            writeVertex(farLeft.x, farLeft.y, u1, v0);
+
+            writeVertex(nearRight.x, nearRight.y, u0, v1);
+            writeVertex(farRight.x, farRight.y, u1, v1);
+            writeVertex(farLeft.x, farLeft.y, u1, v0);
+        }
+    }
+
+    return { buffer: out, anchorMercator };
+}

package/src/nexrad/level3StormRelative.ts

@@ -0,0 +1,116 @@
+import type { DecodedRadarFrame } from './nexradArchiveCache.js';
+
+/**
+ * Storm motion from N0S (ICD 56) product description dep8/dep9, same as AtticRadar
+ * (loaders_nexrad.js process_storm_relative_velocity).
+ * dep8: storm speed in tenths of knots; dep9: direction in tenths of degrees.
+ */
+export function parseLevel3StormMotionFromBuffer(buffer: ArrayBuffer): { speedMs: number; directionDeg: number } | null {
+    const bytes = new Uint8Array(buffer);
+    const marker = [83, 68, 85, 83];
+    let start = 0;
+    for (let i = 0; i <= bytes.length - 4; i++) {
+        if (bytes[i] === marker[0] && bytes[i + 1] === marker[1] && bytes[i + 2] === marker[2] && bytes[i + 3] === marker[3]) {
+            start = i;
+            break;
+        }
+    }
+    const dv = new DataView(buffer, start, bytes.length - start);
+    const textLen = 30;
+    const msgHdrLen = 18;
+    const pdbStart = textLen + msgHdrLen;
+    if (pdbStart + 86 > dv.byteLength) return null;
+    if (dv.getInt16(pdbStart, false) !== -1) return null;
+    const dep8Offset = pdbStart + 82;
+    const dep8 = dv.getInt16(dep8Offset, false);
+    const dep9 = dv.getInt16(dep8Offset + 2, false);
+    const stormSpeedKt = dep8 / 10;
+    const speedMs = stormSpeedKt * 0.514444;
+    const directionDeg = dep9 / 10;
+    if (!Number.isFinite(speedMs) || !Number.isFinite(directionDeg)) return null;
+    return { speedMs, directionDeg };
+}
+
+/** AtticRadar calculateStormComponent — radial component of storm motion (m/s). */
+export function level3StormRadialComponentMs(stormSpeedMs: number, stormDirectionDeg: number, azimuthDeg: number): number {
+    const stormDirRad = (stormDirectionDeg * Math.PI) / 180;
+    const azRad = (azimuthDeg * Math.PI) / 180;
+    return stormSpeedMs * Math.cos(stormDirRad - azRad);
+}
+
+function decodeGateRawMs(hi: number, lo: number, valueScale: number, valueOffset: number): number | null {
+    const raw = lo + hi * 256;
+    let signed = raw;
+    if (raw >= 32768) signed = raw - 65536;
+    if (signed <= -32768) return null;
+    return signed * valueScale + valueOffset;
+}
+
+function encodeGateRawMs(physicalMs: number, valueScale: number, valueOffset: number): [number, number] {
+    const raw = Math.round((physicalMs - valueOffset) / valueScale);
+    const signed = Math.max(-32768, Math.min(32767, raw));
+    const u = signed < 0 ? signed + 65536 : signed;
+    return [(u >> 8) & 0xff, u & 0xff];
+}
+
+/**
+ * Apply storm-relative correction to super-res base velocity (N0G): v_srv = v + storm_radial_component.
+ * Matches AtticRadar process_storm_relative_velocity / PR #12.
+ */
+export function applyLevel3StormRelativeToFrame(
+    frame: DecodedRadarFrame,
+    stormSpeedMs: number,
+    stormDirectionDeg: number,
+): DecodedRadarFrame {
+    const { nRays, nGates, gateData, rayBoundariesDeg, valueScale, valueOffset } = frame;
+    const out = new Uint8Array(gateData.length);
+    for (let r = 0; r < nRays; r++) {
+        const azLow = rayBoundariesDeg[r];
+        const azHigh = rayBoundariesDeg[r + 1];
+        const azimuthDeg = (Number(azLow) + Number(azHigh)) * 0.5;
+        const stormComp = level3StormRadialComponentMs(stormSpeedMs, stormDirectionDeg, azimuthDeg);
+        for (let g = 0; g < nGates; g++) {
+            const o = (r * nGates + g) * 2;
+            const hi = gateData[o];
+            const lo = gateData[o + 1];
+            const v = decodeGateRawMs(hi, lo, valueScale, valueOffset);
+            if (v == null) {
+                out[o] = hi;
+                out[o + 1] = lo;
+                continue;
+            }
+            const corrected = v + stormComp;
+            const [nh, nl] = encodeGateRawMs(corrected, valueScale, valueOffset);
+            out[o] = nh;
+            out[o + 1] = nl;
+        }
+    }
+    return { ...frame, gateData: out };
+}
+
+export function pickNearestLevel3ObjectKey(
+    unixTime: number,
+    timeToKeyMap: Record<string, string>,
+    maxDeltaSec = 600,
+): string | null {
+    const direct = timeToKeyMap[String(unixTime)];
+    if (direct) return direct;
+    const entries = Object.entries(timeToKeyMap);
+    if (entries.length === 0) return null;
+    let bestKey: string | null = 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;
+}

package/src/nexrad/loadNexradSites.ts

@@ -0,0 +1,41 @@
+import type { NexradSite } from './PreprocessedSweepParser.js';
+
+type NexradSitesPayload = {
+    sites?: NexradSite[];
+    features?: unknown[];
+} | NexradSite[];
+
+/** Default: same as aguacero-frontend — app serves `public/data/nexrad.json` at `/data/nexrad.json`. */
+let sitesUrl = '/data/nexrad.json';
+
+/** Override default nexrad.json URL if your static path differs. */
+export function setNexradSitesJsonUrl(url: string) {
+    sitesUrl = url || sitesUrl;
+}
+
+let nexradSitesPayloadPromise: Promise<NexradSitesPayload> | null = null;
+
+export function loadNexradSitesPayload(): Promise<NexradSitesPayload> {
+    if (nexradSitesPayloadPromise) {
+        return nexradSitesPayloadPromise;
+    }
+    nexradSitesPayloadPromise = fetch(sitesUrl)
+        .then((response) => {
+            if (!response.ok) throw new Error(`nexrad.json fetch failed: HTTP ${response.status}`);
+            return response.json() as Promise<NexradSitesPayload>;
+        })
+        .catch((error) => {
+            console.error('[mapsgl] Could not load nexrad.json:', error);
+            nexradSitesPayloadPromise = null;
+            throw error;
+        });
+    return nexradSitesPayloadPromise;
+}
+
+export async function loadNexradSites(): Promise<NexradSite[]> {
+    const payload = await loadNexradSitesPayload();
+    if (Array.isArray(payload)) return payload as NexradSite[];
+    const sites = (payload as { sites?: NexradSite[] }).sites;
+    if (sites && Array.isArray(sites)) return sites;
+    return [];
+}

package/src/nexrad/nexradArchiveCache.ts

@@ -0,0 +1,64 @@
+// Shared archive cache for decoded NEXRAD sweep frames.
+// Lives in a separate module so RadarLayer and GlobalStateContext can both access it
+// without creating a circular import dependency.
+//
+// Rolling cache across all radar sites: we do NOT clear on station or variable change,
+// so returning to a previously viewed site reuses cached frames. When the cache exceeds
+// MAX_ARCHIVE_CACHE_ENTRIES, the oldest entries (by insertion order) are evicted.
+
+// ─── Types ────────────────────────────────────────────────────────────────────
+
+export type DecodedRadarFrame = {
+    gateData: Uint8Array;
+    nRays: number;
+    nGates: number;
+    stationLat: number;
+    stationLon: number;
+    firstGateKm: number;
+    gateWidthKm: number;
+    valueScale: number;
+    valueOffset: number;
+    rayBoundariesDeg: Float32Array;
+};
+
+// ─── Cache storage ────────────────────────────────────────────────────────────
+
+// Rolling cache size. Keeps decoded frames across site/variable switches; evicts oldest when over.
+// ~14 tilts × ~72 time steps ≈ 1008 frames per site; 4 sites ≈ 4k frames.
+const MAX_ARCHIVE_CACHE_ENTRIES = 5000;
+
+export const archiveCache = new Map<string, DecodedRadarFrame | null>();
+
+export function setArchiveCache(url: string, archive: DecodedRadarFrame | null): void {
+    archiveCache.delete(url);
+    archiveCache.set(url, archive);
+    while (archiveCache.size > MAX_ARCHIVE_CACHE_ENTRIES) {
+        const oldestKey = archiveCache.keys().next().value;
+        if (!oldestKey) break;
+        archiveCache.delete(oldestKey);
+    }
+}
+
+// ─── Optional explicit eviction ────────────────────────────────────────────────
+
+/**
+ * Remove all archiveCache entries that belong to a given radar station.
+ * Not used on station change (rolling cache); available for manual/optional clearing.
+ */
+export function clearArchiveCacheForStation(stationId: string): void {
+    const prefix = `/${stationId}_`;
+    for (const url of Array.from(archiveCache.keys())) {
+        if (url.includes(prefix)) archiveCache.delete(url);
+    }
+}
+
+/**
+ * Remove all archiveCache entries for a specific station + variable combination.
+ * Not used on variable change (rolling cache); available for manual/optional clearing.
+ */
+export function clearArchiveCacheForStationVariable(stationId: string, variable: string): void {
+    const prefix = `/${stationId}_${variable}_`;
+    for (const url of Array.from(archiveCache.keys())) {
+        if (url.includes(prefix)) archiveCache.delete(url);
+    }
+}

package/src/nexrad/nexradCrossSectionSampleAtLatLon.ts

@@ -0,0 +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 };
+}