@aguacerowx/mapsgl 0.0.58 → 0.0.59

package/src/nexrad/MapboxRadarLayer.ts

@@ -1,784 +1,784 @@
-import mapboxgl from 'mapbox-gl';
-import { DEFAULT_COLORMAPS } from '@aguacerowx/javascript-sdk';
-import { buildRadarRayGeometryBuffer } from './buildRadarRayGeometry';
-import { prepareRadarFrameForGpuReadout } from './radarFrameGpuMatch';
-
-/** Per-grid polar mesh keyed by station + range + dimensions (+ optional layout id for L3 tilt products). */
-const GEOMETRY_LRU_MAX = 12;
-type GeometryLruEntry = { buffer: Float32Array; anchor: { x: number; y: number } };
-const geometryLru = new Map<string, GeometryLruEntry>();
-
-function geometryLruTouch(key: string): GeometryLruEntry | undefined {
-    const e = geometryLru.get(key);
-    if (!e) return undefined;
-    geometryLru.delete(key);
-    geometryLru.set(key, e);
-    return e;
-}
-
-function geometryLruPut(key: string, entry: GeometryLruEntry): void {
-    if (geometryLru.has(key)) geometryLru.delete(key);
-    geometryLru.set(key, entry);
-    while (geometryLru.size > GEOMETRY_LRU_MAX) {
-        const oldest = geometryLru.keys().next().value as string | undefined;
-        if (oldest === undefined) break;
-        geometryLru.delete(oldest);
-    }
-}
-
-/** ~0.001° — legacy key; tiny scan-to-scan float differences bust the cache every frame. */
-function fingerprintRayBoundariesDeg(b: Float32Array): string {
-    return fingerprintRayBoundariesDegQuantized(b, 1000);
-}
-
-function fingerprintRayBoundariesDegQuantized(b: Float32Array, unitsPerDeg: number): string {
-    const n = b.length;
-    if (n === 0) return '0';
-    let h = 2166136261;
-    for (let i = 0; i < n; i++) {
-        const v = Math.round(b[i]! * unitsPerDeg);
-        h ^= v;
-        h = Math.imul(h, 16777619);
-    }
-    h ^= n * 73856093;
-    return (h >>> 0).toString(36);
-}
-
-/** Colormap format from defaultColormaps: [value, hexColor, value, hexColor, ...] */
-type ColormapArray = (number | string)[];
-
-function getRefc0DefaultColormap(): ColormapArray | null {
-    const cm = (DEFAULT_COLORMAPS as any)?.refc_0?.units?.dBZ?.colormap;
-    return Array.isArray(cm) && cm.length >= 2 ? cm : null;
-}
-
-export type RadarTextureFrame = {
-    gateData: Uint8Array;
-    nRays: number;
-    nGates: number; 
-    stationLat: number;
-    stationLon: number;
-    firstGateKm: number;
-    gateWidthKm: number;
-    valueScale: number;
-    valueOffset: number;
-    rayBoundariesDeg: Float32Array;
-};
-
-/** Options for {@link MapboxRadarLayer.setFrameData}. */
-export type MapboxRadarFrameUploadOptions = {
-    /**
-     * Disambiguates geometry when site + range + nRays/nGates match (e.g. Level-III KDP/N0H: `site|var|N0K`).
-     * The cache key also includes a **coarse** hash of sorted `rayBoundariesDeg` (~0.1° bins) so the mesh
-     * tracks sweep azimuth; when that hash matches, only the gate texture updates (fast scrub). Layout-only
-     * keys without this caused apparent rotation across volumes.
-     */
-    geometryLayoutKey?: string;
-    /**
-     * Legacy: embed full ray-boundary hash in the cache key (forces frequent mesh rebuilds). Prefer
-     * {@link geometryLayoutKey} without this flag.
-     */
-    geometryCacheKeysRayBoundaries?: boolean;
-};
-
-/**
- * Level-2 radar maps each fragment from interpolated Mercator coords to ENU meters, then to gate indices.
- * By mapping the UV coordinates directly to the generated geometry, we completely avoid floating point
- * interpolation overflow issues on mobile GPUs, resulting in perfectly stable rendering.
- */
-function buildRadarShaders(fragmentHighFloatSupported: boolean): { vertex: string; fragment: string } {
-    const fragPrec = fragmentHighFloatSupported ? 'highp' : 'mediump';
-    
-    // VERTEX SHADER
-    const vertex = `
-precision highp float;
-uniform mat4 u_matrix;
-attribute vec2 a_pos;  // offset from anchor (small numbers)
-attribute vec2 a_uv;
-varying ${fragPrec} vec2 v_uv;
-
-void main() {
-    v_uv = a_uv;
-    // u_matrix already has anchor baked in from CPU-side float64 math
-    gl_Position = u_matrix * vec4(a_pos, 0.0, 1.0);
-}`;
-
-    // FRAGMENT SHADER
-    const fragment = `
-precision ${fragPrec} float;
-varying ${fragPrec} vec2 v_uv;
-
-uniform sampler2D u_gate_texture;
-uniform sampler2D u_lut_texture;
-uniform vec2 u_texture_size;
-uniform vec2 u_value_scale_offset;
-uniform vec2 u_lut_value_range;
-uniform float u_discrete_integer_lut;
-uniform float u_opacity;
-uniform float u_gate_smooth_polar;
-
-float decodeInt16(vec2 encoded) {
-    float hi = floor(encoded.x * 255.0 + 0.5);
-    float lo = floor(encoded.y * 255.0 + 0.5);
-    float raw = lo + hi * 256.0;
-    if (raw >= 32768.0) raw -= 65536.0;
-    return raw;
-}
-
-float sampleGateRawBilinear(vec2 gxy) {
-    vec2 sz = u_texture_size;
-    
-    // Both Range (X) and Azimuth (Y) cover the full domain. 
-    // Scale by size and offset by 0.5 to target the exact texel centers.
-    float x_px = gxy.x * sz.x - 0.5;
-    float y_px = gxy.y * sz.y - 0.5;
-    
-    vec2 i0 = floor(vec2(x_px, y_px));
-    vec2 f = vec2(x_px, y_px) - i0;
-    vec2 i1 = i0 + 1.0;
-    
-    // Clamp Range (X) to valid texel indices
-    i0.x = clamp(i0.x, 0.0, sz.x - 1.0);
-    i1.x = clamp(i1.x, 0.0, sz.x - 1.0);
-    
-    // Wrap Azimuth (Y) seamlessly (add sz.y to avoid negative mod bug on Windows/ANGLE)
-    i0.y = mod(i0.y + sz.y, sz.y);
-    i1.y = mod(i1.y + sz.y, sz.y);
-    
-    // Calculate bilinear weights
-    float w00 = (1.0 - f.x) * (1.0 - f.y);
-    float w10 = f.x * (1.0 - f.y);
-    float w01 = (1.0 - f.x) * f.y;
-    float w11 = f.x * f.y;
-    
-    vec2 invSz = 1.0 / sz;
-    vec4 p00 = texture2D(u_gate_texture, (vec2(i0.x, i0.y) + 0.5) * invSz);
-    vec4 p10 = texture2D(u_gate_texture, (vec2(i1.x, i0.y) + 0.5) * invSz);
-    vec4 p01 = texture2D(u_gate_texture, (vec2(i0.x, i1.y) + 0.5) * invSz);
-    vec4 p11 = texture2D(u_gate_texture, (vec2(i1.x, i1.y) + 0.5) * invSz);
-    
-    float r00 = decodeInt16(vec2(p00.r, p00.a));
-    float r10 = decodeInt16(vec2(p10.r, p10.a));
-    float r01 = decodeInt16(vec2(p01.r, p01.a));
-    float r11 = decodeInt16(vec2(p11.r, p11.a));
-    
-    float acc = 0.0;
-    float wsum = 0.0;
-    if (r00 > -32768.0) { acc += r00 * w00; wsum += w00; }
-    if (r10 > -32768.0) { acc += r10 * w10; wsum += w10; }
-    if (r01 > -32768.0) { acc += r01 * w01; wsum += w01; }
-    if (r11 > -32768.0) { acc += r11 * w11; wsum += w11; }
-    if (wsum < 1e-6) return -32768.0;
-    return acc / wsum;
-}
-
-float sampleGateRawNearest(vec2 gxy) {
-    vec2 sz = u_texture_size;
-    vec2 px = gxy * sz;
-    vec2 i = floor(px);
-    
-    // Clamp Range (X)
-    i.x = clamp(i.x, 0.0, sz.x - 1.0);
-    
-    // Wrap Azimuth (Y) seamlessly (add sz.y to avoid negative mod bug on Windows/ANGLE)
-    i.y = mod(i.y + sz.y, sz.y);
-    
-    vec4 p = texture2D(u_gate_texture, (i + 0.5) / sz);
-    return decodeInt16(vec2(p.r, p.a));
-}
-    
-void main() {
-    float raw;
-    if (u_gate_smooth_polar < 0.5) {
-        raw = sampleGateRawNearest(v_uv);
-    } else {
-        raw = sampleGateRawBilinear(v_uv);
-    }
-    
-    if (raw <= -32768.0) {
-        discard;
-    }
-
-    float physical = raw * u_value_scale_offset.x + u_value_scale_offset.y;
-
-    if (physical < u_lut_value_range.x || physical > u_lut_value_range.y) discard;
-
-    float lutT;
-    if (u_discrete_integer_lut > 0.5) {
-        float n = u_lut_value_range.y - u_lut_value_range.x + 1.0;
-        lutT = (physical - u_lut_value_range.x + 0.5) / max(n, 0.0001);
-    } else {
-        lutT = (physical - u_lut_value_range.x) / max(u_lut_value_range.y - u_lut_value_range.x, 0.0001);
-    }
-    lutT = clamp(lutT, 0.0, 1.0);
-    vec4 color = texture2D(u_lut_texture, vec2(lutT, 0.5));
-    if (color.a <= 0.001) discard;
-    gl_FragColor = vec4(color.rgb, color.a * u_opacity);
-}`;
-    return { vertex, fragment };
-}
-
-
-export class MapboxRadarLayer implements mapboxgl.CustomLayerInterface {
-    id: string;
-    type: 'custom' = 'custom';
-    renderingMode: '2d' = '2d';
-
-    private static readonly DEG_TO_RAD = Math.PI / 180;
-    private static readonly RAD_TO_DEG = 180 / Math.PI;
-    private static readonly EARTH_RADIUS_M = 6378137;
-    private static readonly LUT_SIZE = 256;
-
-    private geometryBuffer: WebGLBuffer | null = null;
-    private gateTexture: WebGLTexture | null = null;
-    private lutTexture: WebGLTexture | null = null;
-    private activeVertCount = 0;
-    private hasFrame = false;
-    private pendingFrame: RadarTextureFrame | null = null;
-    private pendingFrameUploadOptions: MapboxRadarFrameUploadOptions | null = null;
-    /** Coalesce rapid setFrameData calls (same animation frame → one upload). */
-    private pendingSetFrameRaf: number | null = null;
-    private rafCoalesceFrame: RadarTextureFrame | null = null;
-    private rafCoalesceOptions: MapboxRadarFrameUploadOptions | undefined;
-    private anchorMercator: { x: number; y: number } = { x: 0, y: 0 };
-    private program: WebGLProgram | null = null;
-    private gl: WebGLRenderingContext | null = null;
-    private uMatrixLocation: WebGLUniformLocation | null = null;
-    private uGateTextureLocation: WebGLUniformLocation | null = null;
-    private uLutTextureLocation: WebGLUniformLocation | null = null;
-    private uTextureSizeLocation: WebGLUniformLocation | null = null;
-    private uValueScaleOffsetLocation: WebGLUniformLocation | null = null;
-    private uLutValueRangeLocation: WebGLUniformLocation | null = null;
-    private uDiscreteIntegerLutLocation: WebGLUniformLocation | null = null;
-    private uOpacityLocation: WebGLUniformLocation | null = null;
-    private uGateSmoothPolarLocation: WebGLUniformLocation | null = null;
-    
-    private aPosLocation = -1;
-    private aUvLocation = -1; 
-
-    private activeTextureWidth = 0;
-    private activeTextureHeight = 0;
-    private activeValueScale = 1;
-    private activeValueOffset = 0;
-    private lutValueMin = 0;
-    private lutValueMax = 80;
-    private opacity = 1;
-    private currentColormap: ColormapArray | null = null;
-    private interpolateColormap = true;
-    private discreteIntegerLutActive = false;
-    private gateSmoothing = false;
-    private lastUploadedFrame: RadarTextureFrame | null = null;
-    private map: mapboxgl.Map | null = null;
-    private geometryCache: {
-        key: string;
-        buffer: Float32Array;
-        anchor: { x: number; y: number };
-    } | null = null;
-
-    private buildGeometryCacheKey(frame: RadarTextureFrame, options?: MapboxRadarFrameUploadOptions): string {
-        const base = `${frame.stationLat},${frame.stationLon},${frame.firstGateKm},${frame.gateWidthKm},${frame.nRays},${frame.nGates}`;
-        const layout = options?.geometryLayoutKey;
-        if (layout != null && layout !== '') {
-            return `${base},layout:${layout}`;
-        }
-        if (options?.geometryCacheKeysRayBoundaries === true) {
-            return `${base},rb:${fingerprintRayBoundariesDeg(frame.rayBoundariesDeg)}`;
-        }
-        return base;
-    }
-    constructor(id: string) {
-        this.id = id;
-    }
-
-    setValueRange(min: number, max: number): void {
-        const safeMin = Number.isFinite(min) ? min : 0;
-        const safeMax = Number.isFinite(max) && max > safeMin ? max : 80;
-        if (this.lutValueMin === safeMin && this.lutValueMax === safeMax) return;
-        this.lutValueMin = safeMin;
-        this.lutValueMax = safeMax;
-        const gl = this.gl;
-        if (gl && this.lutTexture) {
-            const lut = this.buildLutTextureData();
-            gl.bindTexture(gl.TEXTURE_2D, this.lutTexture);
-            gl.texImage2D(
-                gl.TEXTURE_2D, 0, gl.RGBA, MapboxRadarLayer.LUT_SIZE, 1, 0, gl.RGBA, gl.UNSIGNED_BYTE, lut
-            );
-            this.applyLutTextureFilter(gl);
-        }
-    }
-
-    setOpacity(opacity: number): void {
-        const safe = Math.max(0, Math.min(1, Number.isFinite(opacity) ? opacity : 1));
-        if (this.opacity === safe) return;
-        this.opacity = safe;
-    }
-
-    setColormap(colormap: ColormapArray | null | undefined): void {
-        const effective = (Array.isArray(colormap) && colormap.length >= 2)
-            ? colormap
-            : getRefc0DefaultColormap();
-        const effectiveStr = JSON.stringify(effective);
-        if (JSON.stringify(this.currentColormap) === effectiveStr) return;
-        this.currentColormap = effective;
-        const gl = this.gl;
-        if (gl && this.lutTexture) {
-            const lut = this.buildLutTextureData();
-            gl.bindTexture(gl.TEXTURE_2D, this.lutTexture);
-            gl.texImage2D(
-                gl.TEXTURE_2D, 0, gl.RGBA, MapboxRadarLayer.LUT_SIZE, 1, 0, gl.RGBA, gl.UNSIGNED_BYTE, lut
-            );
-            this.applyLutTextureFilter(gl);
-        }
-    }
-
-    setGateSmoothing(smooth: boolean): void {
-        if (this.gateSmoothing === smooth) return;
-        this.gateSmoothing = smooth;
-    }
-
-    setInterpolateColormap(interpolate: boolean): void {
-        if (this.interpolateColormap === interpolate) return;
-        this.interpolateColormap = interpolate;
-        const gl = this.gl;
-        if (gl && this.lutTexture) {
-            const lut = this.buildLutTextureData();
-            gl.bindTexture(gl.TEXTURE_2D, this.lutTexture);
-            gl.texImage2D(
-                gl.TEXTURE_2D, 0, gl.RGBA, MapboxRadarLayer.LUT_SIZE, 1, 0, gl.RGBA, gl.UNSIGNED_BYTE, lut
-            );
-            this.applyLutTextureFilter(gl);
-        }
-    }
-
-    onAdd(map: mapboxgl.Map, gl: WebGLRenderingContext): void {
-        this.map = map;
-        this.gl = gl;
-
-        const hiFloat = gl.getShaderPrecisionFormat(gl.FRAGMENT_SHADER, gl.HIGH_FLOAT);
-        const fragmentHighFloatSupported = hiFloat != null && hiFloat.precision > 0;
-        const { vertex: vertexSource, fragment: fragmentSource } = buildRadarShaders(fragmentHighFloatSupported);
-
-        const vs = gl.createShader(gl.VERTEX_SHADER)!;
-        gl.shaderSource(vs, vertexSource);
-        gl.compileShader(vs);
-        if (!gl.getShaderParameter(vs, gl.COMPILE_STATUS)) {
-            console.error(`[MapboxRadarLayer] ${this.id} vertex shader error:`, gl.getShaderInfoLog(vs));
-        }
-
-        const fs = gl.createShader(gl.FRAGMENT_SHADER)!;
-        gl.shaderSource(fs, fragmentSource);
-        gl.compileShader(fs);
-        if (!gl.getShaderParameter(fs, gl.COMPILE_STATUS)) {
-            console.error(`[MapboxRadarLayer] ${this.id} fragment shader error:`, gl.getShaderInfoLog(fs));
-        }
-
-        this.program = gl.createProgram()!;
-        gl.attachShader(this.program, vs);
-        gl.attachShader(this.program, fs);
-        gl.linkProgram(this.program);
-        if (!gl.getProgramParameter(this.program, gl.LINK_STATUS)) {
-            console.error(`[MapboxRadarLayer] ${this.id} shader link error:`, gl.getProgramInfoLog(this.program));
-        }
-
-        this.uMatrixLocation = gl.getUniformLocation(this.program, 'u_matrix');
-        this.uGateTextureLocation = gl.getUniformLocation(this.program, 'u_gate_texture');
-        this.uLutTextureLocation = gl.getUniformLocation(this.program, 'u_lut_texture');
-        this.uTextureSizeLocation = gl.getUniformLocation(this.program, 'u_texture_size');
-        this.uValueScaleOffsetLocation = gl.getUniformLocation(this.program, 'u_value_scale_offset');
-        this.uLutValueRangeLocation = gl.getUniformLocation(this.program, 'u_lut_value_range');
-        this.uDiscreteIntegerLutLocation = gl.getUniformLocation(this.program, 'u_discrete_integer_lut');
-        this.uOpacityLocation = gl.getUniformLocation(this.program, 'u_opacity');
-        this.uGateSmoothPolarLocation = gl.getUniformLocation(this.program, 'u_gate_smooth_polar');
-        
-        this.aUvLocation = gl.getAttribLocation(this.program, 'a_uv'); 
-        this.aPosLocation = gl.getAttribLocation(this.program, 'a_pos');
-
-        this.geometryBuffer = gl.createBuffer();
-        this.gateTexture = gl.createTexture();
-        this.lutTexture = gl.createTexture();
-        this.initializeLutTexture(gl);
-
-        if (this.pendingFrame) {
-            this.uploadFrame(gl, this.pendingFrame, this.pendingFrameUploadOptions ?? undefined);
-            this.pendingFrame = null;
-            this.pendingFrameUploadOptions = null;
-        }
-    }
-
-    onRemove(_map: mapboxgl.Map, _gl: WebGLRenderingContext): void {
-        this.map = null;
-    }
-
-    private commitRadarGeometry(
-        gl: WebGLRenderingContext,
-        cacheKey: string,
-        buffer: Float32Array,
-        anchorMercator: { x: number; y: number },
-    ): void {
-        this.anchorMercator = anchorMercator;
-        this.geometryCache = {
-            key: cacheKey,
-            buffer,
-            anchor: anchorMercator,
-        };
-        geometryLruPut(cacheKey, {
-            buffer,
-            anchor: { ...anchorMercator },
-        });
-        gl.bindBuffer(gl.ARRAY_BUFFER, this.geometryBuffer);
-        gl.bufferData(gl.ARRAY_BUFFER, buffer, gl.STATIC_DRAW);
-    }
-
-    private uploadGateTextureAndFinishFrame(gl: WebGLRenderingContext, sortedFrame: RadarTextureFrame): void {
-        if (!this.geometryCache) return;
-
-        this.activeVertCount = this.geometryCache.buffer.length / 4;
-        this.hasFrame = this.activeVertCount > 0;
-        this.activeTextureWidth = sortedFrame.nGates;
-        this.activeTextureHeight = sortedFrame.nRays;
-        this.activeValueScale = sortedFrame.valueScale;
-        this.activeValueOffset = sortedFrame.valueOffset;
-
-        gl.bindTexture(gl.TEXTURE_2D, this.gateTexture!);
-        gl.pixelStorei(gl.UNPACK_ALIGNMENT, 1);
-        this.applyGateTextureFilter(gl);
-        gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_S, gl.CLAMP_TO_EDGE);
-        gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_T, gl.CLAMP_TO_EDGE);
-        gl.texImage2D(
-            gl.TEXTURE_2D,
-            0,
-            gl.LUMINANCE_ALPHA,
-            sortedFrame.nGates,
-            sortedFrame.nRays,
-            0,
-            gl.LUMINANCE_ALPHA,
-            gl.UNSIGNED_BYTE,
-            sortedFrame.gateData,
-        );
-
-        this.map?.triggerRepaint();
-    }
-
-    preloadFrame(_frame: RadarTextureFrame): void {
-        return;
-    }
-
-    setFrameData(frame: RadarTextureFrame, options?: MapboxRadarFrameUploadOptions): void {
-        const gl = this.gl;
-        if (!gl) {
-            this.pendingFrame = frame;
-            this.pendingFrameUploadOptions = options ?? null;
-            return;
-        }
-        /** Legacy ray-hash path only; KDP/N0H layout keys upload synchronously like Level II. */
-        if (options?.geometryCacheKeysRayBoundaries !== true) {
-            this.uploadFrame(gl, frame, options);
-            return;
-        }
-        this.rafCoalesceFrame = frame;
-        this.rafCoalesceOptions = options;
-        if (this.pendingSetFrameRaf != null) return;
-        this.pendingSetFrameRaf = requestAnimationFrame(() => {
-            this.pendingSetFrameRaf = null;
-            const gl2 = this.gl;
-            const f = this.rafCoalesceFrame;
-            const o = this.rafCoalesceOptions;
-            this.rafCoalesceFrame = null;
-            this.rafCoalesceOptions = undefined;
-            if (!gl2 || !f) return;
-            this.uploadFrame(gl2, f, o);
-        });
-    }
-
-    evictAllFrames(): void {
-        if (this.pendingSetFrameRaf != null) {
-            cancelAnimationFrame(this.pendingSetFrameRaf);
-            this.pendingSetFrameRaf = null;
-        }
-        this.rafCoalesceFrame = null;
-        this.rafCoalesceOptions = undefined;
-
-        const gl = this.gl;
-        if (!gl) return;
-
-        if (this.geometryBuffer) {
-            gl.deleteBuffer(this.geometryBuffer);
-            this.geometryBuffer = null;
-        }
-        if (this.gateTexture) {
-            gl.deleteTexture(this.gateTexture);
-            this.gateTexture = null;
-        }
-        if (this.lutTexture) {
-            gl.deleteTexture(this.lutTexture);
-            this.lutTexture = null;
-        }
-        this.pendingFrame = null;
-        this.pendingFrameUploadOptions = null;
-        this.lastUploadedFrame = null;
-        this.activeVertCount = 0;
-        this.hasFrame = false;
-        this.activeTextureWidth = 0;
-        this.activeTextureHeight = 0;
-        this.geometryCache = null;
-    }
-
-    render(gl: WebGLRenderingContext, matrix: number[]): void {
-        if (!this.program || !this.geometryBuffer || !this.gateTexture || !this.lutTexture || !this.hasFrame) return;
-        if (this.activeVertCount === 0) return;
-        if (this.aPosLocation < 0 || this.aUvLocation < 0 || !this.uMatrixLocation) return;
-        
-        if (
-            this.uGateTextureLocation === null
-            || this.uLutTextureLocation === null
-            || this.uTextureSizeLocation === null
-            || this.uValueScaleOffsetLocation === null
-            || this.uLutValueRangeLocation === null
-            || this.uDiscreteIntegerLutLocation === null
-            || this.uOpacityLocation === null
-            || this.uGateSmoothPolarLocation === null
-        ) return;
-    
-        gl.useProgram(this.program);
-    
-        // Bake the anchor into the matrix in float64 on the CPU.
-        // a_pos contains offsets from the anchor (tiny numbers, ~1e-4).
-        // If we uploaded the anchor as a uniform and added it on the GPU in float32,
-        // we'd be adding 0.25004 + 0.0000043 in float32 and losing precision.
-        // Instead, fold anchor * matrix into the translation column here in JS float64.
-        const ax = this.anchorMercator.x;
-        const ay = this.anchorMercator.y;
-        const shiftedMatrix = new Float32Array(16);
-        for (let i = 0; i < 16; i++) shiftedMatrix[i] = matrix[i];
-        // Column-major: column 3 = indices [12,13,14,15]
-        // new_col3 = M * [ax, ay, 0, 1]^T (only x,y terms + existing translation)
-        shiftedMatrix[12] = matrix[0]*ax + matrix[4]*ay + matrix[12];
-        shiftedMatrix[13] = matrix[1]*ax + matrix[5]*ay + matrix[13];
-        shiftedMatrix[14] = matrix[2]*ax + matrix[6]*ay + matrix[14];
-        shiftedMatrix[15] = matrix[3]*ax + matrix[7]*ay + matrix[15];
-    
-        gl.uniformMatrix4fv(this.uMatrixLocation, false, shiftedMatrix);
-    
-        gl.activeTexture(gl.TEXTURE0);
-        gl.bindTexture(gl.TEXTURE_2D, this.gateTexture);
-        gl.uniform1i(this.uGateTextureLocation, 0);
-        gl.activeTexture(gl.TEXTURE1);
-        gl.bindTexture(gl.TEXTURE_2D, this.lutTexture);
-        gl.uniform1i(this.uLutTextureLocation, 1);
-        gl.uniform2f(this.uTextureSizeLocation, this.activeTextureWidth, this.activeTextureHeight);
-        gl.uniform2f(this.uValueScaleOffsetLocation, this.activeValueScale, this.activeValueOffset);
-        gl.uniform2f(this.uLutValueRangeLocation, this.lutValueMin, this.lutValueMax);
-        gl.uniform1f(this.uDiscreteIntegerLutLocation, this.discreteIntegerLutActive ? 1 : 0);
-        gl.uniform1f(this.uOpacityLocation, this.opacity);
-        gl.uniform1f(this.uGateSmoothPolarLocation, this.gateSmoothing ? 1 : 0);
-        
-        gl.bindBuffer(gl.ARRAY_BUFFER, this.geometryBuffer);
-    
-        gl.enableVertexAttribArray(this.aPosLocation);
-        gl.vertexAttribPointer(this.aPosLocation, 2, gl.FLOAT, false, 16, 0);
-        
-        gl.enableVertexAttribArray(this.aUvLocation);
-        gl.vertexAttribPointer(this.aUvLocation, 2, gl.FLOAT, false, 16, 8);
-    
-        gl.enable(gl.BLEND);
-        gl.blendFunc(gl.SRC_ALPHA, gl.ONE_MINUS_SRC_ALPHA);
-    
-        gl.drawArrays(gl.TRIANGLES, 0, this.activeVertCount);
-    
-        gl.disableVertexAttribArray(this.aPosLocation);
-        gl.disableVertexAttribArray(this.aUvLocation);
-    
-        gl.bindBuffer(gl.ARRAY_BUFFER, null);
-        gl.activeTexture(gl.TEXTURE1);
-        gl.bindTexture(gl.TEXTURE_2D, null);
-        gl.activeTexture(gl.TEXTURE0);
-        gl.bindTexture(gl.TEXTURE_2D, null);
-    }
-    private uploadFrame(gl: WebGLRenderingContext, frame: RadarTextureFrame, options?: MapboxRadarFrameUploadOptions): void {
-        if (!this.geometryBuffer || !this.gateTexture) return;
-
-        const sortedFrame = prepareRadarFrameForGpuReadout(frame, options);
-
-        const cacheKey = this.buildGeometryCacheKey(sortedFrame, options);
-
-        let reused = false;
-
-        if (this.geometryCache?.key === cacheKey) {
-            this.anchorMercator = this.geometryCache.anchor;
-            reused = true;
-        }
-
-        if (!reused) {
-            const fromLru = geometryLruTouch(cacheKey);
-            if (fromLru) {
-                this.geometryCache = {
-                    key: cacheKey,
-                    buffer: fromLru.buffer,
-                    anchor: fromLru.anchor,
-                };
-                this.anchorMercator = fromLru.anchor;
-                gl.bindBuffer(gl.ARRAY_BUFFER, this.geometryBuffer);
-                gl.bufferData(gl.ARRAY_BUFFER, fromLru.buffer, gl.STATIC_DRAW);
-                reused = true;
-            }
-        }
-
-        if (reused) {
-            this.uploadGateTextureAndFinishFrame(gl, sortedFrame);
-            return;
-        }
-
-        const built = buildRadarRayGeometryBuffer({
-            nRays: sortedFrame.nRays,
-            nGates: sortedFrame.nGates,
-            stationLat: sortedFrame.stationLat,
-            stationLon: sortedFrame.stationLon,
-            firstGateKm: sortedFrame.firstGateKm,
-            gateWidthKm: sortedFrame.gateWidthKm,
-            rayBoundariesDeg: sortedFrame.rayBoundariesDeg,
-        });
-        this.commitRadarGeometry(gl, cacheKey, built.buffer, built.anchorMercator);
-        this.uploadGateTextureAndFinishFrame(gl, sortedFrame);
-
-    }
-
-    private initializeLutTexture(gl: WebGLRenderingContext): void {
-        if (!this.lutTexture) return;
-        const lut = this.buildLutTextureData();
-        gl.bindTexture(gl.TEXTURE_2D, this.lutTexture);
-        gl.pixelStorei(gl.UNPACK_ALIGNMENT, 1);
-        gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_S, gl.CLAMP_TO_EDGE);
-        gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_T, gl.CLAMP_TO_EDGE);
-        gl.texImage2D(
-            gl.TEXTURE_2D, 0, gl.RGBA, MapboxRadarLayer.LUT_SIZE, 1, 0, gl.RGBA, gl.UNSIGNED_BYTE, lut
-        );
-        this.applyLutTextureFilter(gl);
-    }
-
-    private applyGateTextureFilter(gl: WebGLRenderingContext): void {
-        gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MIN_FILTER, gl.NEAREST);
-        gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MAG_FILTER, gl.NEAREST);
-    }
-
-    private applyLutTextureFilter(gl: WebGLRenderingContext): void {
-        const f = this.interpolateColormap ? gl.LINEAR : gl.NEAREST;
-        gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MIN_FILTER, f);
-        gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MAG_FILTER, f);
-    }
-
-    private buildLutTextureData(): Uint8Array {
-        const cm = this.currentColormap ?? getRefc0DefaultColormap();
-        const stops: Array<{ value: number; color: [number, number, number, number] }> = [];
-
-        if (cm && cm.length >= 2) {
-            for (let i = 0; i < cm.length; i += 2) {
-                const value = Number(cm[i]);
-                const hex = String(cm[i + 1] ?? '');
-                const m = hex.match(/^#?([a-fA-F0-9]{8}|[a-fA-F0-9]{6}|[a-fA-F0-9]{3})$/);
-                let r = 0,
-                    g = 0,
-                    b = 0,
-                    a = 255;
-                if (m) {
-                    const s = m[1];
-                    if (s.length === 8) {
-                        r = parseInt(s.slice(0, 2), 16);
-                        g = parseInt(s.slice(2, 4), 16);
-                        b = parseInt(s.slice(4, 6), 16);
-                        a = parseInt(s.slice(6, 8), 16);
-                    } else if (s.length === 6) {
-                        r = parseInt(s.slice(0, 2), 16);
-                        g = parseInt(s.slice(2, 4), 16);
-                        b = parseInt(s.slice(4, 6), 16);
-                    } else {
-                        r = parseInt(s[0] + s[0], 16);
-                        g = parseInt(s[1] + s[1], 16);
-                        b = parseInt(s[2] + s[2], 16);
-                    }
-                }
-                stops.push({ value, color: [r, g, b, a] });
-            }
-        }
-
-        if (stops.length === 0) {
-            this.discreteIntegerLutActive = false;
-            return new Uint8Array(MapboxRadarLayer.LUT_SIZE * 4);
-        }
-
-        this.discreteIntegerLutActive = this.shouldUseDiscreteIntegerLut(stops);
-        const { interpolateColormap } = this;
-        const out = new Uint8Array(MapboxRadarLayer.LUT_SIZE * 4);
-
-        if (this.discreteIntegerLutActive) {
-            const n = stops.length;
-            for (let i = 0; i < MapboxRadarLayer.LUT_SIZE; i++) {
-                const u = (i + 0.5) / MapboxRadarLayer.LUT_SIZE;
-                const bin = Math.min(Math.floor(u * n), n - 1);
-                const c = stops[bin].color;
-                const idx = i * 4;
-                out[idx] = c[0];
-                out[idx + 1] = c[1];
-                out[idx + 2] = c[2];
-                out[idx + 3] = c[3];
-            }
-            return out;
-        }
-
-        for (let i = 0; i < MapboxRadarLayer.LUT_SIZE; i++) {
-            const value = this.lutValueMin
-                + (i / (MapboxRadarLayer.LUT_SIZE - 1)) * (this.lutValueMax - this.lutValueMin);
-            const color = this.sampleStops(stops, value, interpolateColormap);
-            const idx = i * 4;
-            out[idx] = color[0];
-            out[idx + 1] = color[1];
-            out[idx + 2] = color[2];
-            out[idx + 3] = color[3];
-        }
-        return out;
-    }
-
-    private shouldUseDiscreteIntegerLut(
-        stops: Array<{ value: number; color: [number, number, number, number] }>,
-    ): boolean {
-        if (this.interpolateColormap || stops.length < 2) return false;
-        const lo = this.lutValueMin;
-        const hi = this.lutValueMax;
-        if (!Number.isFinite(lo) || !Number.isFinite(hi)) return false;
-        const nExp = Math.round(hi - lo + 1);
-        if (stops.length !== nExp) return false;
-        if (Math.abs(Math.round(lo) - lo) > 1e-3 || Math.abs(Math.round(hi) - hi) > 1e-3) return false;
-        for (let i = 0; i < stops.length; i++) {
-            if (Math.abs(stops[i].value - (lo + i)) > 1e-3) return false;
-        }
-        return true;
-    }
-
-    private sampleStops(
-        stops: Array<{ value: number; color: [number, number, number, number] }>,
-        value: number,
-        interpolate: boolean,
-    ): [number, number, number, number] {
-        if (value <= stops[0].value) return stops[0].color;
-        if (value >= stops[stops.length - 1].value) return stops[stops.length - 1].color;
-        for (let i = 1; i < stops.length; i++) {
-            if (interpolate) {
-                if (value <= stops[i].value) {
-                    const low = stops[i - 1];
-                    const high = stops[i];
-                    const t = (value - low.value) / Math.max(high.value - low.value, 1e-5);
-                    return [
-                        Math.round(low.color[0] + (high.color[0] - low.color[0]) * t),
-                        Math.round(low.color[1] + (high.color[1] - low.color[1]) * t),
-                        Math.round(low.color[2] + (high.color[2] - low.color[2]) * t),
-                        Math.round(low.color[3] + (high.color[3] - low.color[3]) * t),
-                    ];
-                }
-            } else {
-                if (value < stops[i].value) {
-                    return stops[i - 1].color;
-                }
-            }
-        }
-        return stops[stops.length - 1].color;
-    }
+import mapboxgl from 'mapbox-gl';
+import { DEFAULT_COLORMAPS } from '@aguacerowx/javascript-sdk';
+import { buildRadarRayGeometryBuffer } from './buildRadarRayGeometry';
+import { prepareRadarFrameForGpuReadout } from './radarFrameGpuMatch';
+
+/** Per-grid polar mesh keyed by station + range + dimensions (+ optional layout id for L3 tilt products). */
+const GEOMETRY_LRU_MAX = 12;
+type GeometryLruEntry = { buffer: Float32Array; anchor: { x: number; y: number } };
+const geometryLru = new Map<string, GeometryLruEntry>();
+
+function geometryLruTouch(key: string): GeometryLruEntry | undefined {
+    const e = geometryLru.get(key);
+    if (!e) return undefined;
+    geometryLru.delete(key);
+    geometryLru.set(key, e);
+    return e;
+}
+
+function geometryLruPut(key: string, entry: GeometryLruEntry): void {
+    if (geometryLru.has(key)) geometryLru.delete(key);
+    geometryLru.set(key, entry);
+    while (geometryLru.size > GEOMETRY_LRU_MAX) {
+        const oldest = geometryLru.keys().next().value as string | undefined;
+        if (oldest === undefined) break;
+        geometryLru.delete(oldest);
+    }
+}
+
+/** ~0.001° — legacy key; tiny scan-to-scan float differences bust the cache every frame. */
+function fingerprintRayBoundariesDeg(b: Float32Array): string {
+    return fingerprintRayBoundariesDegQuantized(b, 1000);
+}
+
+function fingerprintRayBoundariesDegQuantized(b: Float32Array, unitsPerDeg: number): string {
+    const n = b.length;
+    if (n === 0) return '0';
+    let h = 2166136261;
+    for (let i = 0; i < n; i++) {
+        const v = Math.round(b[i]! * unitsPerDeg);
+        h ^= v;
+        h = Math.imul(h, 16777619);
+    }
+    h ^= n * 73856093;
+    return (h >>> 0).toString(36);
+}
+
+/** Colormap format from defaultColormaps: [value, hexColor, value, hexColor, ...] */
+type ColormapArray = (number | string)[];
+
+function getRefc0DefaultColormap(): ColormapArray | null {
+    const cm = (DEFAULT_COLORMAPS as any)?.refc_0?.units?.dBZ?.colormap;
+    return Array.isArray(cm) && cm.length >= 2 ? cm : null;
+}
+
+export type RadarTextureFrame = {
+    gateData: Uint8Array;
+    nRays: number;
+    nGates: number; 
+    stationLat: number;
+    stationLon: number;
+    firstGateKm: number;
+    gateWidthKm: number;
+    valueScale: number;
+    valueOffset: number;
+    rayBoundariesDeg: Float32Array;
+};
+
+/** Options for {@link MapboxRadarLayer.setFrameData}. */
+export type MapboxRadarFrameUploadOptions = {
+    /**
+     * Disambiguates geometry when site + range + nRays/nGates match (e.g. Level-III KDP/N0H: `site|var|N0K`).
+     * The cache key also includes a **coarse** hash of sorted `rayBoundariesDeg` (~0.1° bins) so the mesh
+     * tracks sweep azimuth; when that hash matches, only the gate texture updates (fast scrub). Layout-only
+     * keys without this caused apparent rotation across volumes.
+     */
+    geometryLayoutKey?: string;
+    /**
+     * Legacy: embed full ray-boundary hash in the cache key (forces frequent mesh rebuilds). Prefer
+     * {@link geometryLayoutKey} without this flag.
+     */
+    geometryCacheKeysRayBoundaries?: boolean;
+};
+
+/**
+ * Level-2 radar maps each fragment from interpolated Mercator coords to ENU meters, then to gate indices.
+ * By mapping the UV coordinates directly to the generated geometry, we completely avoid floating point
+ * interpolation overflow issues on mobile GPUs, resulting in perfectly stable rendering.
+ */
+function buildRadarShaders(fragmentHighFloatSupported: boolean): { vertex: string; fragment: string } {
+    const fragPrec = fragmentHighFloatSupported ? 'highp' : 'mediump';
+    
+    // VERTEX SHADER
+    const vertex = `
+precision highp float;
+uniform mat4 u_matrix;
+attribute vec2 a_pos;  // offset from anchor (small numbers)
+attribute vec2 a_uv;
+varying ${fragPrec} vec2 v_uv;
+
+void main() {
+    v_uv = a_uv;
+    // u_matrix already has anchor baked in from CPU-side float64 math
+    gl_Position = u_matrix * vec4(a_pos, 0.0, 1.0);
+}`;
+
+    // FRAGMENT SHADER
+    const fragment = `
+precision ${fragPrec} float;
+varying ${fragPrec} vec2 v_uv;
+
+uniform sampler2D u_gate_texture;
+uniform sampler2D u_lut_texture;
+uniform vec2 u_texture_size;
+uniform vec2 u_value_scale_offset;
+uniform vec2 u_lut_value_range;
+uniform float u_discrete_integer_lut;
+uniform float u_opacity;
+uniform float u_gate_smooth_polar;
+
+float decodeInt16(vec2 encoded) {
+    float hi = floor(encoded.x * 255.0 + 0.5);
+    float lo = floor(encoded.y * 255.0 + 0.5);
+    float raw = lo + hi * 256.0;
+    if (raw >= 32768.0) raw -= 65536.0;
+    return raw;
+}
+
+float sampleGateRawBilinear(vec2 gxy) {
+    vec2 sz = u_texture_size;
+    
+    // Both Range (X) and Azimuth (Y) cover the full domain. 
+    // Scale by size and offset by 0.5 to target the exact texel centers.
+    float x_px = gxy.x * sz.x - 0.5;
+    float y_px = gxy.y * sz.y - 0.5;
+    
+    vec2 i0 = floor(vec2(x_px, y_px));
+    vec2 f = vec2(x_px, y_px) - i0;
+    vec2 i1 = i0 + 1.0;
+    
+    // Clamp Range (X) to valid texel indices
+    i0.x = clamp(i0.x, 0.0, sz.x - 1.0);
+    i1.x = clamp(i1.x, 0.0, sz.x - 1.0);
+    
+    // Wrap Azimuth (Y) seamlessly (add sz.y to avoid negative mod bug on Windows/ANGLE)
+    i0.y = mod(i0.y + sz.y, sz.y);
+    i1.y = mod(i1.y + sz.y, sz.y);
+    
+    // Calculate bilinear weights
+    float w00 = (1.0 - f.x) * (1.0 - f.y);
+    float w10 = f.x * (1.0 - f.y);
+    float w01 = (1.0 - f.x) * f.y;
+    float w11 = f.x * f.y;
+    
+    vec2 invSz = 1.0 / sz;
+    vec4 p00 = texture2D(u_gate_texture, (vec2(i0.x, i0.y) + 0.5) * invSz);
+    vec4 p10 = texture2D(u_gate_texture, (vec2(i1.x, i0.y) + 0.5) * invSz);
+    vec4 p01 = texture2D(u_gate_texture, (vec2(i0.x, i1.y) + 0.5) * invSz);
+    vec4 p11 = texture2D(u_gate_texture, (vec2(i1.x, i1.y) + 0.5) * invSz);
+    
+    float r00 = decodeInt16(vec2(p00.r, p00.a));
+    float r10 = decodeInt16(vec2(p10.r, p10.a));
+    float r01 = decodeInt16(vec2(p01.r, p01.a));
+    float r11 = decodeInt16(vec2(p11.r, p11.a));
+    
+    float acc = 0.0;
+    float wsum = 0.0;
+    if (r00 > -32768.0) { acc += r00 * w00; wsum += w00; }
+    if (r10 > -32768.0) { acc += r10 * w10; wsum += w10; }
+    if (r01 > -32768.0) { acc += r01 * w01; wsum += w01; }
+    if (r11 > -32768.0) { acc += r11 * w11; wsum += w11; }
+    if (wsum < 1e-6) return -32768.0;
+    return acc / wsum;
+}
+
+float sampleGateRawNearest(vec2 gxy) {
+    vec2 sz = u_texture_size;
+    vec2 px = gxy * sz;
+    vec2 i = floor(px);
+    
+    // Clamp Range (X)
+    i.x = clamp(i.x, 0.0, sz.x - 1.0);
+    
+    // Wrap Azimuth (Y) seamlessly (add sz.y to avoid negative mod bug on Windows/ANGLE)
+    i.y = mod(i.y + sz.y, sz.y);
+    
+    vec4 p = texture2D(u_gate_texture, (i + 0.5) / sz);
+    return decodeInt16(vec2(p.r, p.a));
+}
+    
+void main() {
+    float raw;
+    if (u_gate_smooth_polar < 0.5) {
+        raw = sampleGateRawNearest(v_uv);
+    } else {
+        raw = sampleGateRawBilinear(v_uv);
+    }
+    
+    if (raw <= -32768.0) {
+        discard;
+    }
+
+    float physical = raw * u_value_scale_offset.x + u_value_scale_offset.y;
+
+    if (physical < u_lut_value_range.x || physical > u_lut_value_range.y) discard;
+
+    float lutT;
+    if (u_discrete_integer_lut > 0.5) {
+        float n = u_lut_value_range.y - u_lut_value_range.x + 1.0;
+        lutT = (physical - u_lut_value_range.x + 0.5) / max(n, 0.0001);
+    } else {
+        lutT = (physical - u_lut_value_range.x) / max(u_lut_value_range.y - u_lut_value_range.x, 0.0001);
+    }
+    lutT = clamp(lutT, 0.0, 1.0);
+    vec4 color = texture2D(u_lut_texture, vec2(lutT, 0.5));
+    if (color.a <= 0.001) discard;
+    gl_FragColor = vec4(color.rgb, color.a * u_opacity);
+}`;
+    return { vertex, fragment };
+}
+
+
+export class MapboxRadarLayer implements mapboxgl.CustomLayerInterface {
+    id: string;
+    type: 'custom' = 'custom';
+    renderingMode: '2d' = '2d';
+
+    private static readonly DEG_TO_RAD = Math.PI / 180;
+    private static readonly RAD_TO_DEG = 180 / Math.PI;
+    private static readonly EARTH_RADIUS_M = 6378137;
+    private static readonly LUT_SIZE = 256;
+
+    private geometryBuffer: WebGLBuffer | null = null;
+    private gateTexture: WebGLTexture | null = null;
+    private lutTexture: WebGLTexture | null = null;
+    private activeVertCount = 0;
+    private hasFrame = false;
+    private pendingFrame: RadarTextureFrame | null = null;
+    private pendingFrameUploadOptions: MapboxRadarFrameUploadOptions | null = null;
+    /** Coalesce rapid setFrameData calls (same animation frame → one upload). */
+    private pendingSetFrameRaf: number | null = null;
+    private rafCoalesceFrame: RadarTextureFrame | null = null;
+    private rafCoalesceOptions: MapboxRadarFrameUploadOptions | undefined;
+    private anchorMercator: { x: number; y: number } = { x: 0, y: 0 };
+    private program: WebGLProgram | null = null;
+    private gl: WebGLRenderingContext | null = null;
+    private uMatrixLocation: WebGLUniformLocation | null = null;
+    private uGateTextureLocation: WebGLUniformLocation | null = null;
+    private uLutTextureLocation: WebGLUniformLocation | null = null;
+    private uTextureSizeLocation: WebGLUniformLocation | null = null;
+    private uValueScaleOffsetLocation: WebGLUniformLocation | null = null;
+    private uLutValueRangeLocation: WebGLUniformLocation | null = null;
+    private uDiscreteIntegerLutLocation: WebGLUniformLocation | null = null;
+    private uOpacityLocation: WebGLUniformLocation | null = null;
+    private uGateSmoothPolarLocation: WebGLUniformLocation | null = null;
+    
+    private aPosLocation = -1;
+    private aUvLocation = -1; 
+
+    private activeTextureWidth = 0;
+    private activeTextureHeight = 0;
+    private activeValueScale = 1;
+    private activeValueOffset = 0;
+    private lutValueMin = 0;
+    private lutValueMax = 80;
+    private opacity = 1;
+    private currentColormap: ColormapArray | null = null;
+    private interpolateColormap = true;
+    private discreteIntegerLutActive = false;
+    private gateSmoothing = false;
+    private lastUploadedFrame: RadarTextureFrame | null = null;
+    private map: mapboxgl.Map | null = null;
+    private geometryCache: {
+        key: string;
+        buffer: Float32Array;
+        anchor: { x: number; y: number };
+    } | null = null;
+
+    private buildGeometryCacheKey(frame: RadarTextureFrame, options?: MapboxRadarFrameUploadOptions): string {
+        const base = `${frame.stationLat},${frame.stationLon},${frame.firstGateKm},${frame.gateWidthKm},${frame.nRays},${frame.nGates}`;
+        const layout = options?.geometryLayoutKey;
+        if (layout != null && layout !== '') {
+            return `${base},layout:${layout}`;
+        }
+        if (options?.geometryCacheKeysRayBoundaries === true) {
+            return `${base},rb:${fingerprintRayBoundariesDeg(frame.rayBoundariesDeg)}`;
+        }
+        return base;
+    }
+    constructor(id: string) {
+        this.id = id;
+    }
+
+    setValueRange(min: number, max: number): void {
+        const safeMin = Number.isFinite(min) ? min : 0;
+        const safeMax = Number.isFinite(max) && max > safeMin ? max : 80;
+        if (this.lutValueMin === safeMin && this.lutValueMax === safeMax) return;
+        this.lutValueMin = safeMin;
+        this.lutValueMax = safeMax;
+        const gl = this.gl;
+        if (gl && this.lutTexture) {
+            const lut = this.buildLutTextureData();
+            gl.bindTexture(gl.TEXTURE_2D, this.lutTexture);
+            gl.texImage2D(
+                gl.TEXTURE_2D, 0, gl.RGBA, MapboxRadarLayer.LUT_SIZE, 1, 0, gl.RGBA, gl.UNSIGNED_BYTE, lut
+            );
+            this.applyLutTextureFilter(gl);
+        }
+    }
+
+    setOpacity(opacity: number): void {
+        const safe = Math.max(0, Math.min(1, Number.isFinite(opacity) ? opacity : 1));
+        if (this.opacity === safe) return;
+        this.opacity = safe;
+    }
+
+    setColormap(colormap: ColormapArray | null | undefined): void {
+        const effective = (Array.isArray(colormap) && colormap.length >= 2)
+            ? colormap
+            : getRefc0DefaultColormap();
+        const effectiveStr = JSON.stringify(effective);
+        if (JSON.stringify(this.currentColormap) === effectiveStr) return;
+        this.currentColormap = effective;
+        const gl = this.gl;
+        if (gl && this.lutTexture) {
+            const lut = this.buildLutTextureData();
+            gl.bindTexture(gl.TEXTURE_2D, this.lutTexture);
+            gl.texImage2D(
+                gl.TEXTURE_2D, 0, gl.RGBA, MapboxRadarLayer.LUT_SIZE, 1, 0, gl.RGBA, gl.UNSIGNED_BYTE, lut
+            );
+            this.applyLutTextureFilter(gl);
+        }
+    }
+
+    setGateSmoothing(smooth: boolean): void {
+        if (this.gateSmoothing === smooth) return;
+        this.gateSmoothing = smooth;
+    }
+
+    setInterpolateColormap(interpolate: boolean): void {
+        if (this.interpolateColormap === interpolate) return;
+        this.interpolateColormap = interpolate;
+        const gl = this.gl;
+        if (gl && this.lutTexture) {
+            const lut = this.buildLutTextureData();
+            gl.bindTexture(gl.TEXTURE_2D, this.lutTexture);
+            gl.texImage2D(
+                gl.TEXTURE_2D, 0, gl.RGBA, MapboxRadarLayer.LUT_SIZE, 1, 0, gl.RGBA, gl.UNSIGNED_BYTE, lut
+            );
+            this.applyLutTextureFilter(gl);
+        }
+    }
+
+    onAdd(map: mapboxgl.Map, gl: WebGLRenderingContext): void {
+        this.map = map;
+        this.gl = gl;
+
+        const hiFloat = gl.getShaderPrecisionFormat(gl.FRAGMENT_SHADER, gl.HIGH_FLOAT);
+        const fragmentHighFloatSupported = hiFloat != null && hiFloat.precision > 0;
+        const { vertex: vertexSource, fragment: fragmentSource } = buildRadarShaders(fragmentHighFloatSupported);
+
+        const vs = gl.createShader(gl.VERTEX_SHADER)!;
+        gl.shaderSource(vs, vertexSource);
+        gl.compileShader(vs);
+        if (!gl.getShaderParameter(vs, gl.COMPILE_STATUS)) {
+            console.error(`[MapboxRadarLayer] ${this.id} vertex shader error:`, gl.getShaderInfoLog(vs));
+        }
+
+        const fs = gl.createShader(gl.FRAGMENT_SHADER)!;
+        gl.shaderSource(fs, fragmentSource);
+        gl.compileShader(fs);
+        if (!gl.getShaderParameter(fs, gl.COMPILE_STATUS)) {
+            console.error(`[MapboxRadarLayer] ${this.id} fragment shader error:`, gl.getShaderInfoLog(fs));
+        }
+
+        this.program = gl.createProgram()!;
+        gl.attachShader(this.program, vs);
+        gl.attachShader(this.program, fs);
+        gl.linkProgram(this.program);
+        if (!gl.getProgramParameter(this.program, gl.LINK_STATUS)) {
+            console.error(`[MapboxRadarLayer] ${this.id} shader link error:`, gl.getProgramInfoLog(this.program));
+        }
+
+        this.uMatrixLocation = gl.getUniformLocation(this.program, 'u_matrix');
+        this.uGateTextureLocation = gl.getUniformLocation(this.program, 'u_gate_texture');
+        this.uLutTextureLocation = gl.getUniformLocation(this.program, 'u_lut_texture');
+        this.uTextureSizeLocation = gl.getUniformLocation(this.program, 'u_texture_size');
+        this.uValueScaleOffsetLocation = gl.getUniformLocation(this.program, 'u_value_scale_offset');
+        this.uLutValueRangeLocation = gl.getUniformLocation(this.program, 'u_lut_value_range');
+        this.uDiscreteIntegerLutLocation = gl.getUniformLocation(this.program, 'u_discrete_integer_lut');
+        this.uOpacityLocation = gl.getUniformLocation(this.program, 'u_opacity');
+        this.uGateSmoothPolarLocation = gl.getUniformLocation(this.program, 'u_gate_smooth_polar');
+        
+        this.aUvLocation = gl.getAttribLocation(this.program, 'a_uv'); 
+        this.aPosLocation = gl.getAttribLocation(this.program, 'a_pos');
+
+        this.geometryBuffer = gl.createBuffer();
+        this.gateTexture = gl.createTexture();
+        this.lutTexture = gl.createTexture();
+        this.initializeLutTexture(gl);
+
+        if (this.pendingFrame) {
+            this.uploadFrame(gl, this.pendingFrame, this.pendingFrameUploadOptions ?? undefined);
+            this.pendingFrame = null;
+            this.pendingFrameUploadOptions = null;
+        }
+    }
+
+    onRemove(_map: mapboxgl.Map, _gl: WebGLRenderingContext): void {
+        this.map = null;
+    }
+
+    private commitRadarGeometry(
+        gl: WebGLRenderingContext,
+        cacheKey: string,
+        buffer: Float32Array,
+        anchorMercator: { x: number; y: number },
+    ): void {
+        this.anchorMercator = anchorMercator;
+        this.geometryCache = {
+            key: cacheKey,
+            buffer,
+            anchor: anchorMercator,
+        };
+        geometryLruPut(cacheKey, {
+            buffer,
+            anchor: { ...anchorMercator },
+        });
+        gl.bindBuffer(gl.ARRAY_BUFFER, this.geometryBuffer);
+        gl.bufferData(gl.ARRAY_BUFFER, buffer, gl.STATIC_DRAW);
+    }
+
+    private uploadGateTextureAndFinishFrame(gl: WebGLRenderingContext, sortedFrame: RadarTextureFrame): void {
+        if (!this.geometryCache) return;
+
+        this.activeVertCount = this.geometryCache.buffer.length / 4;
+        this.hasFrame = this.activeVertCount > 0;
+        this.activeTextureWidth = sortedFrame.nGates;
+        this.activeTextureHeight = sortedFrame.nRays;
+        this.activeValueScale = sortedFrame.valueScale;
+        this.activeValueOffset = sortedFrame.valueOffset;
+
+        gl.bindTexture(gl.TEXTURE_2D, this.gateTexture!);
+        gl.pixelStorei(gl.UNPACK_ALIGNMENT, 1);
+        this.applyGateTextureFilter(gl);
+        gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_S, gl.CLAMP_TO_EDGE);
+        gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_T, gl.CLAMP_TO_EDGE);
+        gl.texImage2D(
+            gl.TEXTURE_2D,
+            0,
+            gl.LUMINANCE_ALPHA,
+            sortedFrame.nGates,
+            sortedFrame.nRays,
+            0,
+            gl.LUMINANCE_ALPHA,
+            gl.UNSIGNED_BYTE,
+            sortedFrame.gateData,
+        );
+
+        this.map?.triggerRepaint();
+    }
+
+    preloadFrame(_frame: RadarTextureFrame): void {
+        return;
+    }
+
+    setFrameData(frame: RadarTextureFrame, options?: MapboxRadarFrameUploadOptions): void {
+        const gl = this.gl;
+        if (!gl) {
+            this.pendingFrame = frame;
+            this.pendingFrameUploadOptions = options ?? null;
+            return;
+        }
+        /** Legacy ray-hash path only; KDP/N0H layout keys upload synchronously like Level II. */
+        if (options?.geometryCacheKeysRayBoundaries !== true) {
+            this.uploadFrame(gl, frame, options);
+            return;
+        }
+        this.rafCoalesceFrame = frame;
+        this.rafCoalesceOptions = options;
+        if (this.pendingSetFrameRaf != null) return;
+        this.pendingSetFrameRaf = requestAnimationFrame(() => {
+            this.pendingSetFrameRaf = null;
+            const gl2 = this.gl;
+            const f = this.rafCoalesceFrame;
+            const o = this.rafCoalesceOptions;
+            this.rafCoalesceFrame = null;
+            this.rafCoalesceOptions = undefined;
+            if (!gl2 || !f) return;
+            this.uploadFrame(gl2, f, o);
+        });
+    }
+
+    evictAllFrames(): void {
+        if (this.pendingSetFrameRaf != null) {
+            cancelAnimationFrame(this.pendingSetFrameRaf);
+            this.pendingSetFrameRaf = null;
+        }
+        this.rafCoalesceFrame = null;
+        this.rafCoalesceOptions = undefined;
+
+        const gl = this.gl;
+        if (!gl) return;
+
+        if (this.geometryBuffer) {
+            gl.deleteBuffer(this.geometryBuffer);
+            this.geometryBuffer = null;
+        }
+        if (this.gateTexture) {
+            gl.deleteTexture(this.gateTexture);
+            this.gateTexture = null;
+        }
+        if (this.lutTexture) {
+            gl.deleteTexture(this.lutTexture);
+            this.lutTexture = null;
+        }
+        this.pendingFrame = null;
+        this.pendingFrameUploadOptions = null;
+        this.lastUploadedFrame = null;
+        this.activeVertCount = 0;
+        this.hasFrame = false;
+        this.activeTextureWidth = 0;
+        this.activeTextureHeight = 0;
+        this.geometryCache = null;
+    }
+
+    render(gl: WebGLRenderingContext, matrix: number[]): void {
+        if (!this.program || !this.geometryBuffer || !this.gateTexture || !this.lutTexture || !this.hasFrame) return;
+        if (this.activeVertCount === 0) return;
+        if (this.aPosLocation < 0 || this.aUvLocation < 0 || !this.uMatrixLocation) return;
+        
+        if (
+            this.uGateTextureLocation === null
+            || this.uLutTextureLocation === null
+            || this.uTextureSizeLocation === null
+            || this.uValueScaleOffsetLocation === null
+            || this.uLutValueRangeLocation === null
+            || this.uDiscreteIntegerLutLocation === null
+            || this.uOpacityLocation === null
+            || this.uGateSmoothPolarLocation === null
+        ) return;
+    
+        gl.useProgram(this.program);
+    
+        // Bake the anchor into the matrix in float64 on the CPU.
+        // a_pos contains offsets from the anchor (tiny numbers, ~1e-4).
+        // If we uploaded the anchor as a uniform and added it on the GPU in float32,
+        // we'd be adding 0.25004 + 0.0000043 in float32 and losing precision.
+        // Instead, fold anchor * matrix into the translation column here in JS float64.
+        const ax = this.anchorMercator.x;
+        const ay = this.anchorMercator.y;
+        const shiftedMatrix = new Float32Array(16);
+        for (let i = 0; i < 16; i++) shiftedMatrix[i] = matrix[i];
+        // Column-major: column 3 = indices [12,13,14,15]
+        // new_col3 = M * [ax, ay, 0, 1]^T (only x,y terms + existing translation)
+        shiftedMatrix[12] = matrix[0]*ax + matrix[4]*ay + matrix[12];
+        shiftedMatrix[13] = matrix[1]*ax + matrix[5]*ay + matrix[13];
+        shiftedMatrix[14] = matrix[2]*ax + matrix[6]*ay + matrix[14];
+        shiftedMatrix[15] = matrix[3]*ax + matrix[7]*ay + matrix[15];
+    
+        gl.uniformMatrix4fv(this.uMatrixLocation, false, shiftedMatrix);
+    
+        gl.activeTexture(gl.TEXTURE0);
+        gl.bindTexture(gl.TEXTURE_2D, this.gateTexture);
+        gl.uniform1i(this.uGateTextureLocation, 0);
+        gl.activeTexture(gl.TEXTURE1);
+        gl.bindTexture(gl.TEXTURE_2D, this.lutTexture);
+        gl.uniform1i(this.uLutTextureLocation, 1);
+        gl.uniform2f(this.uTextureSizeLocation, this.activeTextureWidth, this.activeTextureHeight);
+        gl.uniform2f(this.uValueScaleOffsetLocation, this.activeValueScale, this.activeValueOffset);
+        gl.uniform2f(this.uLutValueRangeLocation, this.lutValueMin, this.lutValueMax);
+        gl.uniform1f(this.uDiscreteIntegerLutLocation, this.discreteIntegerLutActive ? 1 : 0);
+        gl.uniform1f(this.uOpacityLocation, this.opacity);
+        gl.uniform1f(this.uGateSmoothPolarLocation, this.gateSmoothing ? 1 : 0);
+        
+        gl.bindBuffer(gl.ARRAY_BUFFER, this.geometryBuffer);
+    
+        gl.enableVertexAttribArray(this.aPosLocation);
+        gl.vertexAttribPointer(this.aPosLocation, 2, gl.FLOAT, false, 16, 0);
+        
+        gl.enableVertexAttribArray(this.aUvLocation);
+        gl.vertexAttribPointer(this.aUvLocation, 2, gl.FLOAT, false, 16, 8);
+    
+        gl.enable(gl.BLEND);
+        gl.blendFunc(gl.SRC_ALPHA, gl.ONE_MINUS_SRC_ALPHA);
+    
+        gl.drawArrays(gl.TRIANGLES, 0, this.activeVertCount);
+    
+        gl.disableVertexAttribArray(this.aPosLocation);
+        gl.disableVertexAttribArray(this.aUvLocation);
+    
+        gl.bindBuffer(gl.ARRAY_BUFFER, null);
+        gl.activeTexture(gl.TEXTURE1);
+        gl.bindTexture(gl.TEXTURE_2D, null);
+        gl.activeTexture(gl.TEXTURE0);
+        gl.bindTexture(gl.TEXTURE_2D, null);
+    }
+    private uploadFrame(gl: WebGLRenderingContext, frame: RadarTextureFrame, options?: MapboxRadarFrameUploadOptions): void {
+        if (!this.geometryBuffer || !this.gateTexture) return;
+
+        const sortedFrame = prepareRadarFrameForGpuReadout(frame, options);
+
+        const cacheKey = this.buildGeometryCacheKey(sortedFrame, options);
+
+        let reused = false;
+
+        if (this.geometryCache?.key === cacheKey) {
+            this.anchorMercator = this.geometryCache.anchor;
+            reused = true;
+        }
+
+        if (!reused) {
+            const fromLru = geometryLruTouch(cacheKey);
+            if (fromLru) {
+                this.geometryCache = {
+                    key: cacheKey,
+                    buffer: fromLru.buffer,
+                    anchor: fromLru.anchor,
+                };
+                this.anchorMercator = fromLru.anchor;
+                gl.bindBuffer(gl.ARRAY_BUFFER, this.geometryBuffer);
+                gl.bufferData(gl.ARRAY_BUFFER, fromLru.buffer, gl.STATIC_DRAW);
+                reused = true;
+            }
+        }
+
+        if (reused) {
+            this.uploadGateTextureAndFinishFrame(gl, sortedFrame);
+            return;
+        }
+
+        const built = buildRadarRayGeometryBuffer({
+            nRays: sortedFrame.nRays,
+            nGates: sortedFrame.nGates,
+            stationLat: sortedFrame.stationLat,
+            stationLon: sortedFrame.stationLon,
+            firstGateKm: sortedFrame.firstGateKm,
+            gateWidthKm: sortedFrame.gateWidthKm,
+            rayBoundariesDeg: sortedFrame.rayBoundariesDeg,
+        });
+        this.commitRadarGeometry(gl, cacheKey, built.buffer, built.anchorMercator);
+        this.uploadGateTextureAndFinishFrame(gl, sortedFrame);
+
+    }
+
+    private initializeLutTexture(gl: WebGLRenderingContext): void {
+        if (!this.lutTexture) return;
+        const lut = this.buildLutTextureData();
+        gl.bindTexture(gl.TEXTURE_2D, this.lutTexture);
+        gl.pixelStorei(gl.UNPACK_ALIGNMENT, 1);
+        gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_S, gl.CLAMP_TO_EDGE);
+        gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_T, gl.CLAMP_TO_EDGE);
+        gl.texImage2D(
+            gl.TEXTURE_2D, 0, gl.RGBA, MapboxRadarLayer.LUT_SIZE, 1, 0, gl.RGBA, gl.UNSIGNED_BYTE, lut
+        );
+        this.applyLutTextureFilter(gl);
+    }
+
+    private applyGateTextureFilter(gl: WebGLRenderingContext): void {
+        gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MIN_FILTER, gl.NEAREST);
+        gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MAG_FILTER, gl.NEAREST);
+    }
+
+    private applyLutTextureFilter(gl: WebGLRenderingContext): void {
+        const f = this.interpolateColormap ? gl.LINEAR : gl.NEAREST;
+        gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MIN_FILTER, f);
+        gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MAG_FILTER, f);
+    }
+
+    private buildLutTextureData(): Uint8Array {
+        const cm = this.currentColormap ?? getRefc0DefaultColormap();
+        const stops: Array<{ value: number; color: [number, number, number, number] }> = [];
+
+        if (cm && cm.length >= 2) {
+            for (let i = 0; i < cm.length; i += 2) {
+                const value = Number(cm[i]);
+                const hex = String(cm[i + 1] ?? '');
+                const m = hex.match(/^#?([a-fA-F0-9]{8}|[a-fA-F0-9]{6}|[a-fA-F0-9]{3})$/);
+                let r = 0,
+                    g = 0,
+                    b = 0,
+                    a = 255;
+                if (m) {
+                    const s = m[1];
+                    if (s.length === 8) {
+                        r = parseInt(s.slice(0, 2), 16);
+                        g = parseInt(s.slice(2, 4), 16);
+                        b = parseInt(s.slice(4, 6), 16);
+                        a = parseInt(s.slice(6, 8), 16);
+                    } else if (s.length === 6) {
+                        r = parseInt(s.slice(0, 2), 16);
+                        g = parseInt(s.slice(2, 4), 16);
+                        b = parseInt(s.slice(4, 6), 16);
+                    } else {
+                        r = parseInt(s[0] + s[0], 16);
+                        g = parseInt(s[1] + s[1], 16);
+                        b = parseInt(s[2] + s[2], 16);
+                    }
+                }
+                stops.push({ value, color: [r, g, b, a] });
+            }
+        }
+
+        if (stops.length === 0) {
+            this.discreteIntegerLutActive = false;
+            return new Uint8Array(MapboxRadarLayer.LUT_SIZE * 4);
+        }
+
+        this.discreteIntegerLutActive = this.shouldUseDiscreteIntegerLut(stops);
+        const { interpolateColormap } = this;
+        const out = new Uint8Array(MapboxRadarLayer.LUT_SIZE * 4);
+
+        if (this.discreteIntegerLutActive) {
+            const n = stops.length;
+            for (let i = 0; i < MapboxRadarLayer.LUT_SIZE; i++) {
+                const u = (i + 0.5) / MapboxRadarLayer.LUT_SIZE;
+                const bin = Math.min(Math.floor(u * n), n - 1);
+                const c = stops[bin].color;
+                const idx = i * 4;
+                out[idx] = c[0];
+                out[idx + 1] = c[1];
+                out[idx + 2] = c[2];
+                out[idx + 3] = c[3];
+            }
+            return out;
+        }
+
+        for (let i = 0; i < MapboxRadarLayer.LUT_SIZE; i++) {
+            const value = this.lutValueMin
+                + (i / (MapboxRadarLayer.LUT_SIZE - 1)) * (this.lutValueMax - this.lutValueMin);
+            const color = this.sampleStops(stops, value, interpolateColormap);
+            const idx = i * 4;
+            out[idx] = color[0];
+            out[idx + 1] = color[1];
+            out[idx + 2] = color[2];
+            out[idx + 3] = color[3];
+        }
+        return out;
+    }
+
+    private shouldUseDiscreteIntegerLut(
+        stops: Array<{ value: number; color: [number, number, number, number] }>,
+    ): boolean {
+        if (this.interpolateColormap || stops.length < 2) return false;
+        const lo = this.lutValueMin;
+        const hi = this.lutValueMax;
+        if (!Number.isFinite(lo) || !Number.isFinite(hi)) return false;
+        const nExp = Math.round(hi - lo + 1);
+        if (stops.length !== nExp) return false;
+        if (Math.abs(Math.round(lo) - lo) > 1e-3 || Math.abs(Math.round(hi) - hi) > 1e-3) return false;
+        for (let i = 0; i < stops.length; i++) {
+            if (Math.abs(stops[i].value - (lo + i)) > 1e-3) return false;
+        }
+        return true;
+    }
+
+    private sampleStops(
+        stops: Array<{ value: number; color: [number, number, number, number] }>,
+        value: number,
+        interpolate: boolean,
+    ): [number, number, number, number] {
+        if (value <= stops[0].value) return stops[0].color;
+        if (value >= stops[stops.length - 1].value) return stops[stops.length - 1].color;
+        for (let i = 1; i < stops.length; i++) {
+            if (interpolate) {
+                if (value <= stops[i].value) {
+                    const low = stops[i - 1];
+                    const high = stops[i];
+                    const t = (value - low.value) / Math.max(high.value - low.value, 1e-5);
+                    return [
+                        Math.round(low.color[0] + (high.color[0] - low.color[0]) * t),
+                        Math.round(low.color[1] + (high.color[1] - low.color[1]) * t),
+                        Math.round(low.color[2] + (high.color[2] - low.color[2]) * t),
+                        Math.round(low.color[3] + (high.color[3] - low.color[3]) * t),
+                    ];
+                }
+            } else {
+                if (value < stops[i].value) {
+                    return stops[i - 1].color;
+                }
+            }
+        }
+        return stops[stops.length - 1].color;
+    }
 }