@aguacerowx/mapsgl 0.0.58 → 0.0.59

package/src/nexrad/radarDecode.worker.ts

@@ -1,25 +1,25 @@
-import { decodeRadarSlotMessage, type DecodeSlotRequest } from './radarDecodeSlot.js';
-
-self.onmessage = (event: MessageEvent<DecodeSlotRequest>) => {
-    const data = event.data;
-    if (!data || data.type !== 'DECODE_SLOT') return;
-
-    try {
-        const response = decodeRadarSlotMessage(data);
-        if (response.gateData && response.rayBoundariesDeg) {
-            (self as unknown as Worker).postMessage(response, [
-                response.gateData.buffer as ArrayBuffer,
-                response.rayBoundariesDeg.buffer as ArrayBuffer,
-            ]);
-        } else {
-            self.postMessage(response);
-        }
-    } catch (error) {
-        self.postMessage({
-            type: 'DECODE_RESULT',
-            requestId: data.requestId,
-            gateData: null,
-            error: error instanceof Error ? error.message : 'Unknown worker error',
-        });
-    }
-};
+import { decodeRadarSlotMessage, type DecodeSlotRequest } from './radarDecodeSlot.js';
+
+self.onmessage = (event: MessageEvent<DecodeSlotRequest>) => {
+    const data = event.data;
+    if (!data || data.type !== 'DECODE_SLOT') return;
+
+    try {
+        const response = decodeRadarSlotMessage(data);
+        if (response.gateData && response.rayBoundariesDeg) {
+            (self as unknown as Worker).postMessage(response, [
+                response.gateData.buffer as ArrayBuffer,
+                response.rayBoundariesDeg.buffer as ArrayBuffer,
+            ]);
+        } else {
+            self.postMessage(response);
+        }
+    } catch (error) {
+        self.postMessage({
+            type: 'DECODE_RESULT',
+            requestId: data.requestId,
+            gateData: null,
+            error: error instanceof Error ? error.message : 'Unknown worker error',
+        });
+    }
+};

package/src/nexrad/radarDecodeSlot.ts

@@ -1,195 +1,195 @@
-import { decompress as decompressZstd } from 'fzstd';
-import type { NexradSite } from './PreprocessedSweepParser.js';
-
-export type DecodeSlotRequest = {
-    type: 'DECODE_SLOT';
-    requestId: number;
-    objectKey: string;
-    slotBuffer: ArrayBuffer;
-    nRays: number;
-    nGates: number;
-    firstGateKm: number;
-    gateWidthKm: number;
-    azimuthsBuffer: ArrayBuffer;
-    sites: NexradSite[];
-};
-
-export type DecodeSlotResponse = {
-    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] };
-}
-
-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;
-}
-
-/** Shared decode path for the dedicated worker and React Native (main-thread shim). */
-export function decodeRadarSlotMessage(data: DecodeSlotRequest): DecodeSlotResponse {
-    const { requestId, objectKey, slotBuffer, nRays, nGates,
-        firstGateKm, gateWidthKm, azimuthsBuffer, sites } = data;
-
-    const compressed = new Uint8Array(slotBuffer);
-    if (!isZstd(compressed)) {
-        return { type: 'DECODE_RESULT', requestId, gateData: null,
-            error: `Slot for ${objectKey} is not valid zstd` };
-    }
-
-    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) {
-        return { type: 'DECODE_RESULT', requestId, gateData: null,
-            error: `Slot for ${objectKey} marked not present` };
-    }
-
-    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) {
-        return { type: 'DECODE_RESULT', requestId, gateData: null,
-            error: `Unexpected bytesPerGate=${bytesPerGate} for ${objectKey}` };
-    }
-
-    const keyParts = parseObjectKey(objectKey);
-    if (!keyParts) {
-        return { type: 'DECODE_RESULT', requestId, gateData: null,
-            error: `Unable to parse station from key: ${objectKey}` };
-    }
-
-    const site = sites.find(s => s.id === keyParts.stationId);
-    if (!site) {
-        return { type: 'DECODE_RESULT', requestId, gateData: null,
-            error: `Station "${keyParts.stationId}" not found` };
-    }
-
-    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 {
-            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);
-            }
-        }
-    }
-
-    return {
-        type: 'DECODE_RESULT',
-        requestId,
-        gateData: gateDataCopy,
-        stationLat: site.lat,
-        stationLon: site.lon,
-        firstGateKm,
-        gateWidthKm,
-        valueScale,
-        valueOffset,
-        rayBoundariesDeg,
-        nRays: slotNRays,
-        nGates: slotNGates,
-    };
-}
+import { decompress as decompressZstd } from 'fzstd';
+import type { NexradSite } from './PreprocessedSweepParser.js';
+
+export type DecodeSlotRequest = {
+    type: 'DECODE_SLOT';
+    requestId: number;
+    objectKey: string;
+    slotBuffer: ArrayBuffer;
+    nRays: number;
+    nGates: number;
+    firstGateKm: number;
+    gateWidthKm: number;
+    azimuthsBuffer: ArrayBuffer;
+    sites: NexradSite[];
+};
+
+export type DecodeSlotResponse = {
+    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] };
+}
+
+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;
+}
+
+/** Shared decode path for the dedicated worker and React Native (main-thread shim). */
+export function decodeRadarSlotMessage(data: DecodeSlotRequest): DecodeSlotResponse {
+    const { requestId, objectKey, slotBuffer, nRays, nGates,
+        firstGateKm, gateWidthKm, azimuthsBuffer, sites } = data;
+
+    const compressed = new Uint8Array(slotBuffer);
+    if (!isZstd(compressed)) {
+        return { type: 'DECODE_RESULT', requestId, gateData: null,
+            error: `Slot for ${objectKey} is not valid zstd` };
+    }
+
+    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) {
+        return { type: 'DECODE_RESULT', requestId, gateData: null,
+            error: `Slot for ${objectKey} marked not present` };
+    }
+
+    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) {
+        return { type: 'DECODE_RESULT', requestId, gateData: null,
+            error: `Unexpected bytesPerGate=${bytesPerGate} for ${objectKey}` };
+    }
+
+    const keyParts = parseObjectKey(objectKey);
+    if (!keyParts) {
+        return { type: 'DECODE_RESULT', requestId, gateData: null,
+            error: `Unable to parse station from key: ${objectKey}` };
+    }
+
+    const site = sites.find(s => s.id === keyParts.stationId);
+    if (!site) {
+        return { type: 'DECODE_RESULT', requestId, gateData: null,
+            error: `Station "${keyParts.stationId}" not found` };
+    }
+
+    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 {
+            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);
+            }
+        }
+    }
+
+    return {
+        type: 'DECODE_RESULT',
+        requestId,
+        gateData: gateDataCopy,
+        stationLat: site.lat,
+        stationLon: site.lon,
+        firstGateKm,
+        gateWidthKm,
+        valueScale,
+        valueOffset,
+        rayBoundariesDeg,
+        nRays: slotNRays,
+        nGates: slotNGates,
+    };
+}

package/src/nexrad/radarFrameGpuMatch.ts

@@ -1,111 +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);
-}
+/**
+ * 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);
+}