@aguacerowx/mapsgl 0.0.31 → 0.0.41

package/src/nexrad/radarDecode.worker.ts

@@ -0,0 +1,227 @@
+import { decompress as decompressZstd } from 'fzstd';
+import { type NexradSite } from './PreprocessedSweepParser.js';
+
+type DecodeRequest =
+    | {
+          type: 'DECODE_SLOT';
+          requestId: number;
+          objectKey: string;
+          slotBuffer: ArrayBuffer;       // compressed slot blob
+          nRays: number;
+          nGates: number;
+          firstGateKm: number;
+          gateWidthKm: number;
+          azimuthsBuffer: ArrayBuffer;   // Float32Array big-endian from file header
+          sites: NexradSite[];
+      };
+
+type DecodeResponse = {
+    type: 'DECODE_RESULT';
+    requestId: number;
+    gateData: Uint8Array | null;
+    stationLat?: number;
+    stationLon?: number;
+    firstGateKm?: number;
+    gateWidthKm?: number;
+    valueScale?: number;
+    valueOffset?: number;
+    rayBoundariesDeg?: Float32Array;
+    nRays?: number;
+    nGates?: number;
+    error?: string;
+};
+
+const SLOT_HDR_BYTES = 28;
+
+function isZstd(bytes: Uint8Array): boolean {
+    return bytes.length >= 4 &&
+        bytes[0] === 0x28 && bytes[1] === 0xb5 && bytes[2] === 0x2f && bytes[3] === 0xfd;
+}
+
+function parseObjectKey(objectKey: string): { stationId: string } | null {
+    const parts = objectKey.split('_');
+    if (parts.length < 2) return null;
+    return { stationId: parts[0] };
+}
+
+/**
+ * Calculates robust boundaries between rays. 
+ * Using midpoints and a fallback spacing prevents precision gaps at the 0/360 seam 
+ * which often causes "flashing" during map transforms.
+ */
+function buildRayBoundariesDeg(azimuths: Float32Array): Float32Array {
+    const nRays = azimuths.length;
+    const boundaries = new Float32Array(nRays + 1);
+    if (nRays === 0) return boundaries;
+
+    let totalSpacing = 0;
+    let validCount = 0;
+    for (let i = 1; i < nRays; i++) {
+        let diff = azimuths[i] - azimuths[i - 1];
+        while (diff < -180) diff += 360;
+        while (diff > 180) diff -= 360;
+        const absDiff = Math.abs(diff);
+        if (absDiff > 0 && absDiff < 10) {
+            totalSpacing += absDiff;
+            validCount++;
+        }
+    }
+    
+    let avgSpacing = (validCount > 0) ? (totalSpacing / validCount) : (360 / nRays);
+    if (avgSpacing <= 0 || isNaN(avgSpacing)) avgSpacing = 1.0;
+
+    boundaries[0] = azimuths[0] - (avgSpacing / 2);
+    for (let i = 1; i < nRays; i++) {
+        let diff = azimuths[i] - azimuths[i - 1];
+        while (diff < -180) diff += 360;
+        while (diff > 180) diff -= 360;
+        boundaries[i] = azimuths[i - 1] + (diff / 2);
+    }
+    boundaries[nRays] = azimuths[nRays - 1] + (avgSpacing / 2);
+
+    return boundaries;
+}
+
+self.onmessage = (event: MessageEvent<DecodeRequest>) => {
+    const data = event.data;
+    if (!data || data.type !== 'DECODE_SLOT') return;
+
+    const { requestId, objectKey, slotBuffer, nRays, nGates,
+            firstGateKm, gateWidthKm, azimuthsBuffer, sites } = data;
+
+    try {
+        const compressed = new Uint8Array(slotBuffer);
+        if (!isZstd(compressed)) {
+            self.postMessage({ type: 'DECODE_RESULT', requestId, gateData: null,
+                error: `Slot for ${objectKey} is not valid zstd` });
+            return;
+        }
+
+        const decompressed = decompressZstd(compressed);
+        const buffer = decompressed.buffer.slice(
+            decompressed.byteOffset,
+            decompressed.byteOffset + decompressed.byteLength,
+        ) as ArrayBuffer;
+
+        const view = new DataView(buffer);
+        const valueScale  = view.getFloat32(0, false);
+        const valueOffset = view.getFloat32(4, false);
+        const present     = view.getUint32(8, false);
+
+        if (present === 0) {
+            self.postMessage({ type: 'DECODE_RESULT', requestId, gateData: null,
+                error: `Slot for ${objectKey} marked not present` });
+            return;
+        }
+
+        const slotNRays  = view.getUint16(12, false);
+        const slotNGates = view.getUint16(14, false);
+
+        const gateBytes = buffer.byteLength - SLOT_HDR_BYTES;
+        const expectedGates = slotNRays * slotNGates;
+        const bytesPerGate = gateBytes / expectedGates;
+        
+        if (bytesPerGate !== 1 && bytesPerGate !== 2 && bytesPerGate !== 4) {
+            self.postMessage({ type: 'DECODE_RESULT', requestId, gateData: null,
+                error: `Unexpected bytesPerGate=${bytesPerGate} for ${objectKey}` });
+            return;
+        }
+
+        const keyParts = parseObjectKey(objectKey);
+        if (!keyParts) {
+            self.postMessage({ type: 'DECODE_RESULT', requestId, gateData: null,
+                error: `Unable to parse station from key: ${objectKey}` });
+            return;
+        }
+
+        const site = sites.find(s => s.id === keyParts.stationId);
+        if (!site) {
+            self.postMessage({ type: 'DECODE_RESULT', requestId, gateData: null,
+                error: `Station "${keyParts.stationId}" not found` });
+            return;
+        }
+
+        /**
+         * FIX: We MUST use slotNRays (the actual data count) to build geometry.
+         * Using the header's nRays when the slot contains a different count 
+         * creates UV misalignment that causes flickering on map movement.
+         */
+        const azimuths = new Float32Array(slotNRays);
+        const azView = new DataView(azimuthsBuffer);
+        const headerNRays = azimuthsBuffer.byteLength / 4;
+        
+        for (let i = 0; i < slotNRays; i++) {
+            if (i < headerNRays) {
+                azimuths[i] = azView.getFloat32(i * 4, false);
+            } else {
+                // Fallback for edge cases where data exceeds metadata
+                const prevAz = i > 0 ? azimuths[i - 1] : 0;
+                azimuths[i] = (prevAz + (360 / slotNRays)) % 360;
+            }
+        }
+
+        const rayBoundariesDeg = buildRayBoundariesDeg(azimuths);
+
+        const gateCount = slotNRays * slotNGates;
+        const gateDataCopy = new Uint8Array(slotNRays * slotNGates * 2); 
+        const outView = new DataView(gateDataCopy.buffer);
+
+        if (bytesPerGate === 1) {
+            const raw = new Uint8Array(buffer, SLOT_HDR_BYTES, gateCount);
+            for (let ray = 0; ray < slotNRays; ray++) {
+                let prev = 0;
+                for (let g = 0; g < slotNGates; g++) {
+                    const idx = ray * slotNGates + g;
+                    const delta = raw[idx];
+                    const val = (prev + delta) & 0xFF;
+                    prev = val;
+                    if (val === 0) {
+                        outView.setInt16(idx * 2, -32768, false);
+                    } else {
+                        outView.setInt16(idx * 2, val, false);
+                    }
+                }
+            }
+        } else {
+            const rawBytes = new Uint8Array(buffer, SLOT_HDR_BYTES, gateCount * 2);
+            for (let ray = 0; ray < slotNRays; ray++) {
+                let prev = 0;
+                for (let g = 0; g < slotNGates; g++) {
+                    const idx = ray * slotNGates + g;
+                    const hi = rawBytes[idx * 2];
+                    const lo = rawBytes[idx * 2 + 1];
+                    const delta = (hi << 8 | lo) << 16 >> 16;
+                    const val = (prev + delta) | 0;
+                    prev = val;
+                    outView.setInt16(idx * 2, val, false);
+                }
+            }
+        }
+
+        const response: DecodeResponse = {
+            type: 'DECODE_RESULT',
+            requestId,
+            gateData: gateDataCopy,
+            stationLat: site.lat,
+            stationLon: site.lon,
+            firstGateKm,
+            gateWidthKm,
+            valueScale,
+            valueOffset,
+            rayBoundariesDeg,
+            nRays: slotNRays, 
+            nGates: slotNGates,
+        };
+
+        // Transfer the buffers to the main thread to avoid copying overhead
+        (self as any).postMessage(response, [
+            gateDataCopy.buffer as ArrayBuffer,
+            rayBoundariesDeg.buffer as ArrayBuffer,
+        ]);
+    } catch (error) {
+        self.postMessage({
+            type: 'DECODE_RESULT', requestId, gateData: null,
+            error: error instanceof Error ? error.message : 'Unknown worker error',
+        });
+    }
+};

package/src/nexrad/radarFrameGpuMatch.ts

@@ -0,0 +1,111 @@
+/**
+ * Frame transforms applied in {@link MapboxRadarLayer} before GPU upload.
+ * Mouse readouts must use the **same** gate/ray ordering as the texture or samples drift from pixels.
+ */
+import type { DecodedRadarFrame } from './nexradArchiveCache.js';
+
+/** Shortest distance between two headings on [0, 360), in degrees. */
+function angularDistanceDeg(a: number, b: number): number {
+    let d = Math.abs(a - b) % 360;
+    if (d > 180) d = 360 - d;
+    return d;
+}
+
+/**
+ * For Level-III layout products (KDP/N0H): remap incoming rays into fixed canonical azimuth bins
+ * (same as MapboxRadarLayer `sortFrameToCanonicalBins`).
+ */
+export function canonicalBinsRadarFrame(frame: DecodedRadarFrame): DecodedRadarFrame {
+    const nRays = frame.nRays;
+    const nGates = frame.nGates;
+    if (nRays <= 0 || nGates <= 0) return frame;
+    if (frame.rayBoundariesDeg.length < nRays + 1) return frame;
+
+    const degPerBin = 360 / nRays;
+    const bytesPerRay = nGates * 2;
+
+    const centers = new Float32Array(nRays);
+    for (let r = 0; r < nRays; r++) {
+        const lower = frame.rayBoundariesDeg[r]!;
+        const upper = frame.rayBoundariesDeg[r + 1]!;
+        const center = (lower + upper) * 0.5;
+        centers[r] = ((center % 360) + 360) % 360;
+    }
+
+    const canonicalGateData = new Uint8Array(nRays * bytesPerRay);
+    for (let i = 0; i < canonicalGateData.length; i += 2) {
+        canonicalGateData[i] = 128;
+    }
+
+    const used = new Array<boolean>(nRays).fill(false);
+    for (let bin = 0; bin < nRays; bin++) {
+        const targetDeg = ((((bin + 0.5) * degPerBin) % 360) + 360) % 360;
+        let bestR = -1;
+        let bestDist = Infinity;
+        for (let r = 0; r < nRays; r++) {
+            if (used[r]) continue;
+            const dist = angularDistanceDeg(centers[r], targetDeg);
+            if (dist < bestDist) {
+                bestDist = dist;
+                bestR = r;
+            }
+        }
+        if (bestR >= 0) {
+            used[bestR] = true;
+            canonicalGateData.set(
+                frame.gateData.subarray(bestR * bytesPerRay, (bestR + 1) * bytesPerRay),
+                bin * bytesPerRay,
+            );
+        }
+    }
+
+    const canonicalBoundaries = new Float32Array(nRays + 1);
+    for (let i = 0; i <= nRays; i++) {
+        canonicalBoundaries[i] = i * degPerBin;
+    }
+
+    return { ...frame, gateData: canonicalGateData, rayBoundariesDeg: canonicalBoundaries };
+}
+
+/** Sort rays by ascending start azimuth — same as MapboxRadarLayer `sortFrameByAzimuth`. */
+export function sortRadarFrameByAzimuth(frame: DecodedRadarFrame): DecodedRadarFrame {
+    const nRays = frame.nRays;
+    const nGates = frame.nGates;
+    const bytesPerRay = nGates * 2;
+
+    const rayOrder = Array.from({ length: nRays }, (_, i) => i).sort(
+        (a, b) => frame.rayBoundariesDeg[a] - frame.rayBoundariesDeg[b],
+    );
+
+    const sortedGateData = new Uint8Array(nRays * bytesPerRay);
+    const sortedBoundaries = new Float32Array(nRays + 1);
+
+    for (let newIdx = 0; newIdx < nRays; newIdx++) {
+        const oldIdx = rayOrder[newIdx]!;
+        sortedGateData.set(
+            frame.gateData.subarray(oldIdx * bytesPerRay, (oldIdx + 1) * bytesPerRay),
+            newIdx * bytesPerRay,
+        );
+        sortedBoundaries[newIdx] = frame.rayBoundariesDeg[oldIdx]!;
+    }
+    sortedBoundaries[nRays] =
+        frame.rayBoundariesDeg[rayOrder[nRays - 1]!]! +
+        (frame.rayBoundariesDeg[rayOrder[1]!]! - frame.rayBoundariesDeg[rayOrder[0]!]!);
+
+    return { ...frame, gateData: sortedGateData, rayBoundariesDeg: sortedBoundaries };
+}
+
+export type GpuReadoutFrameOptions = {
+    geometryLayoutKey?: string | null;
+};
+
+/**
+ * Match {@link MapboxRadarLayer} `uploadFrame` gate/ray ordering for CPU readout.
+ */
+export function prepareRadarFrameForGpuReadout(
+    frame: DecodedRadarFrame,
+    options?: GpuReadoutFrameOptions,
+): DecodedRadarFrame {
+    const hasLayoutKey = options?.geometryLayoutKey != null && options.geometryLayoutKey !== '';
+    return hasLayoutKey ? canonicalBinsRadarFrame(frame) : sortRadarFrameByAzimuth(frame);
+}