@walkthru-earth/objex 1.3.0 → 1.4.0

package/dist/utils/cog.js

@@ -1,41 +1,65 @@
+import { SourceCache, SourceChunk } from '@chunkd/middleware';
+import { SourceView } from '@chunkd/source';
+import { SourceHttp } from '@chunkd/source-http';
 import { inferRenderPipeline } from '@developmentseed/deck.gl-geotiff';
 import { Colormap, FilterNoDataVal, LinearRescale } from '@developmentseed/deck.gl-raster/gpu-modules';
 import loadEpsg from '@developmentseed/epsg/all';
 import epsgCsvUrl from '@developmentseed/epsg/all.csv.gz?url';
 import { GeoTIFF } from '@developmentseed/geotiff';
 import { parseWkt } from '@developmentseed/proj';
+import { buildDataTypeLabel, clampBounds, SF_LABELS, safeClamp } from '@walkthru-earth/objex-utils';
 import proj4Lib from 'proj4';
+import { HISTOGRAM_BINS, readGdalStats, streamHistogram } from './cog-histogram.js';
 import { COLORMAP_INDEX, getColormapTexture } from './colormap-sprite.js';
-// ─── Constants ───────────────────────────────────────────────────
 /**
- * Patches a GLSL ES 3.00 compile error in `@developmentseed/deck.gl-raster`
- * v0.6.0-alpha.1. The `Colormap` shader module injects
- * `uniform sampler2DArray colormapTexture;` without a precision qualifier,
- * which the Apple-GPU path of luma.gl's WebGL2 backend rejects with
- * `ERROR: 'sampler2DArray' : No precision specified`. In GLSL ES 3.00,
- * every sampler type other than `sampler2D`/`samplerCube` needs explicit
- * precision in fragment shaders.
+ * Open a `GeoTIFF` from a URL, priming `SourceHttp.metadata.size` before
+ * chunked reads start. Replaces `GeoTIFF.fromUrl` which skips the head and
+ * can leave size unset (chunkd#1666, stac-map#459).
  *
- * Chain this module immediately BEFORE `Colormap` in the renderPipeline so
- * the combined `fs:#decl` inject emits the precision declaration first,
- * then the sampler uniform. Remove once upstream ships the precision fix.
+ * Primer strategy depends on whether the URL is SigV4-query-string signed.
+ * `presign.ts` signs URLs with `aws4fetch.signQuery({method: 'GET'})`, which
+ * binds the HTTP method into the signature, so a bare `HEAD` against a
+ * `GET`-signed URL 403s with `SignatureDoesNotMatch`. For signed URLs we
+ * use a 1-byte `Range: bytes=0-0` GET that returns `Content-Range:
+ * bytes 0-0/<TOTAL>`. For unsigned public URLs we use `source.head()`,
+ * which returns `Content-Length: <TOTAL>` directly.
+ *
+ * Why the split: the Range primer's total-size depends on the
+ * `Content-Range` response header being CORS-exposed via
+ * `Access-Control-Expose-Headers`. GCS public buckets only expose
+ * `Content-Length` and a handful of `X-Goog-*` headers (NOT
+ * `Content-Range`), so `response.headers.get('content-range')` returns
+ * null in the browser, `SourceHttp.metadata.size` falls back to
+ * `Content-Length` = 1, and `Tiff.readHeader` throws "offset is outside
+ * the bounds of the DataView" on the first IFD read past byte 0. HEAD
+ * avoids this entirely because `Content-Length` is a CORS-safelisted
+ * response header.
  */
-const Sampler2DArrayPrecision = {
-    name: 'sampler2darray-precision',
-    fs: '',
-    inject: {
-        'fs:#decl': 'precision highp sampler2DArray;\n'
+function isSignedQueryUrl(href) {
+    try {
+        const url = new URL(href);
+        const params = url.searchParams;
+        return params.has('X-Amz-Signature') || params.has('X-Goog-Signature') || params.has('sig');
     }
-};
-/** SampleFormat tag value → human label. */
-export const SF_LABELS = {
-    1: 'uint',
-    2: 'int',
-    3: 'float',
-    4: 'void',
-    5: 'complex int',
-    6: 'complex float'
-};
+    catch {
+        return false;
+    }
+}
+export async function loadGeoTIFF(href, options = {}) {
+    const { chunkSize = 32 * 1024, cacheSize = 1024 * 1024 } = options;
+    const source = new SourceHttp(href, {});
+    if (isSignedQueryUrl(href)) {
+        await source.fetch(0, 1);
+    }
+    else {
+        await source.head();
+    }
+    const chunk = new SourceChunk({ size: chunkSize });
+    const cache = new SourceCache({ size: cacheSize });
+    const view = new SourceView(source, [chunk, cache]);
+    return await GeoTIFF.open({ dataSource: source, headerSource: view });
+}
+export { buildDataTypeLabel, clampBounds, HISTOGRAM_BINS, readGdalStats, SF_LABELS, safeClamp, streamHistogram };
 /** Create a sensible default band config based on COG metadata. */
 export function defaultBandConfig(bandCount, sampleFormat) {
     if (bandCount >= 3 && bandCount <= 4) {
@@ -120,11 +144,183 @@ export function needsCustomPipelineForConfig(geotiff, config) {
         return true;
     return false;
 }
+export const DEFAULT_NODATA_CONFIG = { mode: 'auto' };
+/**
+ * Read the GDAL_NODATA tag from a GeoTIFF.
+ *
+ * GDAL convention: the tag is an ASCII string serialized via `Number()`; the
+ * literal `"nan"` (case-insensitive) round-trips to JS `NaN`. The library's
+ * `geotiff.nodata` getter already performs that `Number(rawString)` conversion,
+ * so this helper just exposes the resulting `number | null` (preserving `NaN`)
+ * behind a stable name for callers that want to drive `NodataConfig`.
+ */
+export function readGdalNodata(geotiff) {
+    return geotiff.nodata;
+}
+/**
+ * Custom shader module that discards pixels whose `color.r` is NaN. Float COGs
+ * commonly encode nodata as NaN, but the shipped `FilterNoDataVal` does a
+ * `color.r == nodata.value` comparison which IEEE 754 always returns false for
+ * NaN. Mirrors the reference implementation in `src/render/shader-modules.ts`.
+ *
+ * Slots into a `RasterModule[]` render pipeline the same way as the upstream
+ * modules (e.g. `LinearRescale`).
+ */
+// Typed as RasterModule['module'] (a luma.gl ShaderModule) so it composes
+// with the upstream-shipped modules. No uniforms / no getUniforms needed.
+export const FilterNaN = {
+    name: 'filterNaN',
+    inject: {
+        'fs:DECKGL_FILTER_COLOR': /* glsl */ `
+  if (isnan(color.r)) {
+    discard;
+  }
+`
+    }
+};
+/**
+ * Pick the correct nodata-discard module for a resolved nodata value.
+ *
+ * - `NaN` → `FilterNaN` (IEEE 754: `x == NaN` is always false).
+ * - finite number → `FilterNoDataVal { value: nodata / sampleScale }`.
+ * - `null` / non-finite (e.g. ±Infinity) → no module (nodata off).
+ *
+ * `sampleScale` divides the raw nodata value to put it in the same coordinate
+ * space the shader sees after hardware normalization (e.g. 255 for r8unorm,
+ * 65535 for r16unorm). Pass `1` when the shader receives raw float values.
+ */
+export function nodataModule(nodata, sampleScale = 1) {
+    if (nodata === null)
+        return null;
+    if (Number.isNaN(nodata))
+        return { module: FilterNaN };
+    if (!Number.isFinite(nodata))
+        return null;
+    return {
+        module: FilterNoDataVal,
+        props: { value: nodata / sampleScale }
+    };
+}
+/** Resolve a tri-state `NodataConfig` against the auto-detected GDAL_NODATA value. */
+export function resolveNodata(cfg, autoNodata) {
+    if (cfg.mode === 'off')
+        return null;
+    if (cfg.mode === 'value')
+        return cfg.value ?? null;
+    return autoNodata;
+}
 export const DEFAULT_RESCALE = { min: 0, max: 1 };
 /** True when the rescale values would produce a visible change on the GPU. */
 export function isRescaleActive(cfg) {
     return cfg.min !== DEFAULT_RESCALE.min || cfg.max !== DEFAULT_RESCALE.max;
 }
+/**
+ * Pick a sensible default `RescaleConfig` for a freshly opened COG. The slider
+ * operates in normalized shader space [0, 1], but the GPU's hardware
+ * normalization (`r8unorm` / `r16unorm` in `MultiCOGLayer`, or the library
+ * default uint pipeline elsewhere) collapses raw integer values onto that
+ * range by dividing by the format's max (255 for uint8, 65535 for uint16).
+ *
+ * For uint8 visual COGs (Sentinel-2 `visual` TCI, NAIP `image`) the natural
+ * land brightness sits around raw 50-100, so `max: 0.3` (≈ raw 76) gives a
+ * nicely contrasted preview. For uint16 reflectance bands (Sentinel-2 raw
+ * `nir` / `swir16` / `red`, Landsat C2 L2 `*_B*`) typical land surfaces sit at
+ * raw 800-3000 (reflectance × 10000), which is `0.012-0.046` after r16unorm.
+ * `max: 0.3` would render those near-black; `max: 0.05` (≈ raw 3277) keeps
+ * vegetation, soil, and water in the visible range while leaving headroom for
+ * brighter targets.
+ *
+ * Float / int sample formats fall back to the conservative `{0, 1}` no-op so
+ * the user can dial in their own range via the slider.
+ */
+export function defaultRescaleForGeotiff(geotiff) {
+    const tags = geotiff.cachedTags;
+    const sampleFormat = tags.sampleFormat?.[0] ?? 1;
+    if (sampleFormat !== 1)
+        return { ...DEFAULT_RESCALE };
+    const bps = tags.bitsPerSample?.[0] ?? 8;
+    if (bps <= 8)
+        return { min: 0, max: 0.3 };
+    return { min: 0, max: 0.05 };
+}
+/**
+ * Build a 64-bin histogram of band 0 from a GeoTIFF's smallest overview, in
+ * the same shader-space [0, 1] coordinate system the rescale slider operates
+ * on (raw / 65535 for uint16, raw / 255 for uint8, raw clamped to [0, 1] for
+ * float). Used by viewers on the multi-asset MultiCOGLayer path to give the
+ * rescale slider a histogram backdrop without hooking per-tile sampling into
+ * the layer.
+ *
+ * Returns null if the smallest overview cannot be fetched. Skips the GeoTIFF's
+ * declared nodata value and non-finite values.
+ */
+/**
+ * Walk a cumulative histogram (`HISTOGRAM_BIN_COUNT` bins covering [0, 1])
+ * and return the shader-space value at percentile `p` (0..1). Returns null
+ * when the histogram is empty. Linearly interpolates within the matching bin
+ * so the result is monotonic across calls with adjacent percentiles, instead
+ * of jumping in `1/HISTOGRAM_BIN_COUNT` increments.
+ */
+export function percentileFromHistogram(histogram, p) {
+    if (!histogram || histogram.length !== HISTOGRAM_BIN_COUNT)
+        return null;
+    let total = 0;
+    for (let i = 0; i < HISTOGRAM_BIN_COUNT; i++)
+        total += histogram[i];
+    if (total === 0)
+        return null;
+    const target = total * Math.max(0, Math.min(1, p));
+    let acc = 0;
+    for (let i = 0; i < HISTOGRAM_BIN_COUNT; i++) {
+        const next = acc + histogram[i];
+        if (next >= target) {
+            const frac = histogram[i] === 0 ? 0 : (target - acc) / histogram[i];
+            return (i + frac) / HISTOGRAM_BIN_COUNT;
+        }
+        acc = next;
+    }
+    return 1;
+}
+export async function buildHistogramFromGeotiff(geotiff, signal) {
+    const tags = geotiff.cachedTags;
+    const sampleFormat = tags.sampleFormat?.[0] ?? 1;
+    const bps = tags.bitsPerSample?.[0] ?? 8;
+    const norm = sampleFormat === 1 ? (bps <= 8 ? 255 : 65535) : 1;
+    const nodata = geotiff.nodata;
+    const overviews = geotiff.overviews ?? [];
+    const sourceImage = overviews.length ? overviews[overviews.length - 1] : geotiff;
+    try {
+        const tile = await sourceImage.fetchTile(0, 0, { signal });
+        if (signal?.aborted)
+            return null;
+        const arr = tile.array;
+        const data = arr.layout === 'band-separate' ? arr.bands[0] : arr.data;
+        const stride = arr.layout === 'band-separate' ? 1 : (arr.count ?? 1);
+        const histogram = new Uint32Array(HISTOGRAM_BIN_COUNT);
+        let counted = 0;
+        const len = data.length;
+        for (let i = 0; i < len; i += stride) {
+            const raw = data[i];
+            if (!Number.isFinite(raw))
+                continue;
+            if (nodata !== null && raw === nodata)
+                continue;
+            const t = sampleFormat === 1 ? raw / norm : Math.max(0, Math.min(1, raw));
+            if (t < 0 || t > 1)
+                continue;
+            const bin = Math.min(HISTOGRAM_BIN_COUNT - 1, Math.floor(t * HISTOGRAM_BIN_COUNT));
+            histogram[bin]++;
+            counted++;
+        }
+        if (counted === 0)
+            return null;
+        return histogram;
+    }
+    catch {
+        /* swallow */
+        return null;
+    }
+}
 /**
  * Build a `getTileData` + `renderTile` pair that reuses the library-default
  * uint pipeline (via `inferRenderPipeline`) and appends `LinearRescale` to the
@@ -144,7 +340,7 @@ export function createRescaledPipeline(geotiff, rescale) {
         if (builtFor === device && defaultGetTileData && defaultRenderTile)
             return;
         const inferred = inferRenderPipeline(geotiff, device);
-        // `inferRenderPipeline` returns generic callbacks. `MinimalDataT` is the
+        // `inferRenderPipeline` returns generic callbacks. `MinimalTileData` is the
         // contractual superset used by COGLayer — safe upcast.
         defaultGetTileData = inferred.getTileData;
         defaultRenderTile = inferred.renderTile;
@@ -170,17 +366,18 @@ export function createRescaledPipeline(geotiff, rescale) {
 }
 /**
  * Build a `renderPipeline` array for `MultiCOGLayer` / raster mosaics.
- * Combines optional `FilterNoDataVal` + `LinearRescale` stages in the order
- * the GPU expects (no-data mask first, then rescale).
+ * Combines an optional nodata-discard module + `LinearRescale` in the order
+ * the GPU expects (no-data mask first, then rescale). The nodata module is
+ * selected by `nodataModule()` so NaN sentinels route through `FilterNaN`
+ * instead of the always-false `==` comparison in `FilterNoDataVal`.
  */
 export function buildBandRenderPipeline(opts = {}) {
     const modules = [];
-    if (opts.noDataVal !== undefined && opts.noDataVal !== null) {
-        modules.push({
-            module: FilterNoDataVal,
-            props: { noDataVal: opts.noDataVal }
-        });
-    }
+    const nodataMod = opts.noDataVal !== undefined
+        ? nodataModule(opts.noDataVal ?? null, opts.noDataSampleScale ?? 1)
+        : null;
+    if (nodataMod)
+        modules.push(nodataMod);
     if (opts.rescale && isRescaleActive(opts.rescale)) {
         modules.push({
             module: LinearRescale,
@@ -247,10 +444,11 @@ export function selectCogPipeline(geotiff, opts = {}) {
         ? needsCustomPipelineForConfig(geotiff, bandConfig)
         : needsCustomPipeline(geotiff);
     if (useCustom && bandConfig) {
+        // Note: callers that want identity-stable getTileData across config
+        // swaps should call `createConfigurableGetTileData` directly and reuse
+        // the loader, rather than re-running selectCogPipeline.
         return {
-            getTileData: createConfigurableGetTileData(geotiff, bandConfig, {
-                onHistogram: opts.onHistogram
-            }),
+            getTileData: createConfigurableGetTileData(geotiff, bandConfig).getTileData,
             renderTile: buildCustomRenderTile(bandConfig, rescale)
         };
     }
@@ -260,7 +458,7 @@ export function selectCogPipeline(geotiff, opts = {}) {
         const fallbackSf = geotiff.cachedTags.sampleFormat?.[0] ?? 1;
         const fallbackConfig = defaultBandConfig(geotiff.count, fallbackSf);
         return {
-            getTileData: createCustomGetTileData(geotiff, { onHistogram: opts.onHistogram }),
+            getTileData: createCustomGetTileData(geotiff),
             renderTile: buildCustomRenderTile(fallbackConfig, rescale)
         };
     }
@@ -275,27 +473,9 @@ export function selectCogPipeline(geotiff, opts = {}) {
 }
 const BITMAP_SOURCE = 'geotiff-bitmap-src';
 const BITMAP_LAYER = 'geotiff-bitmap-layer';
-// ─── Pure helpers ────────────────────────────────────────────────
-/** Safely clamp a number to a range, treating NaN/Infinity as the fallback. */
-export function safeClamp(v, lo, hi, fallback) {
-    return Number.isFinite(v) ? Math.max(lo, Math.min(hi, v)) : fallback;
-}
-/** Clamp geographic bounds to valid MapLibre web-Mercator range. */
-export function clampBounds(b) {
-    return {
-        west: safeClamp(b.west, -180, 180, -180),
-        south: safeClamp(b.south, -85.051129, 85.051129, -85.051129),
-        east: safeClamp(b.east, -180, 180, 180),
-        north: safeClamp(b.north, -85.051129, 85.051129, 85.051129)
-    };
-}
-/**
- * Build a data-type label from GeoTIFF sample format and bits per sample.
- * e.g. "uint8", "float32", "int16"
- */
-export function buildDataTypeLabel(sampleFormat, bitsPerSample) {
-    return `${SF_LABELS[sampleFormat] ?? `sf${sampleFormat}`}${bitsPerSample ?? ''}`;
-}
+// ─── Types & pure helpers ────────────────────────────────────────
+// `GeoBounds`, `CogInfo`, `safeClamp`, `clampBounds`, `buildDataTypeLabel`
+// live in `cog-info.ts` in @walkthru-earth/objex-utils and are re-exported at the top of this file.
 // ─── Map helpers (depend on maplibre-gl) ─────────────────────────
 /**
  * Query the GPU's MAX_TEXTURE_SIZE from MapLibre's WebGL context.
@@ -458,7 +638,7 @@ const MAX_NONTILED_PIXELS = 100_000_000;
 export async function renderNonTiledBitmap(options) {
     const { url, map, signal } = options;
     // Open GeoTIFF (reuse if already opened for pre-flight)
-    const geotiff = options.geotiff ?? (await GeoTIFF.fromUrl(url));
+    const geotiff = options.geotiff ?? (await loadGeoTIFF(url));
     if (signal.aborted)
         throw new DOMException('Aborted', 'AbortError');
     const imgW = geotiff.width;
@@ -604,8 +784,15 @@ export function needsCustomPipeline(geotiff) {
     // sampleFormat is null or not uint → needs custom
     return sf === null || sf[0] !== 1;
 }
-/** Number of histogram buckets produced by the CPU bake. */
-export const HISTOGRAM_BIN_COUNT = 64;
+/**
+ * Number of histogram buckets produced by the CPU bake.
+ *
+ * Canonical value lives in `./cog-histogram.ts` as `HISTOGRAM_BINS`; this
+ * is kept as an alias so existing CogViewer / StacMosaicViewer imports
+ * continue to compile. Both names resolve to the same number — see
+ * `./cog-histogram.ts` for the streaming histogram + GDAL stats reader.
+ */
+export const HISTOGRAM_BIN_COUNT = HISTOGRAM_BINS;
 /**
  * Create custom getTileData for non-uint COGs.
  * Reads band 0, normalizes using GDAL statistics / per-tile adaptive stretch,
@@ -614,7 +801,7 @@ export const HISTOGRAM_BIN_COUNT = 64;
  * `colormaps.png`. Reserves `r = 0` for nodata so `FilterNoDataVal` can
  * discard those fragments before the ramp sample.
  */
-export function createCustomGetTileData(geotiff, opts = {}) {
+export function createCustomGetTileData(geotiff, _opts = {}) {
     // Read Scale/Offset TIFF tags (GDAL convention for scaled datasets like DEMs)
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
     const tags = geotiff.cachedTags;
@@ -649,7 +836,6 @@ export function createCustomGetTileData(geotiff, opts = {}) {
     let sharedMax = globalMax;
     // Resolve the sprite texture from the first tile's device; reuse per-device.
     let texturePromise = null;
-    const histogram = isSingleBand ? new Uint32Array(HISTOGRAM_BIN_COUNT) : null;
     return async (image, options) => {
         if (isSingleBand && !texturePromise) {
             texturePromise = getColormapTexture(options.device);
@@ -669,6 +855,10 @@ export function createCustomGetTileData(geotiff, opts = {}) {
         const pixelCount = width * height;
         const scale = gdalScale ?? 1;
         const offset = gdalOffset ?? 0;
+        // Allocate per-tile histogram so deck.gl's tile cache retains it with
+        // the tile object. The viewer sums histograms of visible tiles from
+        // TileLayer's `onViewportLoad` hook, no shared accumulator needed.
+        const histogram = isSingleBand ? new Uint32Array(HISTOGRAM_BIN_COUNT) : null;
         // When no global stats, scan this tile and widen the shared range
         if (sharedMin === null || sharedMax === null) {
             let tMin = Infinity;
@@ -734,14 +924,13 @@ export function createCustomGetTileData(geotiff, opts = {}) {
             }
             rgba[idx + 3] = 255;
         }
-        if (histogram && opts.onHistogram)
-            opts.onHistogram(histogram);
         return {
             imageData: new ImageData(rgba, width, height),
             width,
             height,
             colormapTexture: isSingleBand ? colormapTexture : undefined,
-            nodataSentinel: isSingleBand ? 0 : undefined
+            nodataSentinel: isSingleBand ? 0 : undefined,
+            histogram: histogram ?? undefined
         };
     };
 }
@@ -775,11 +964,7 @@ export function buildCustomRenderTile(config, rescale) {
                 props: { rescaleMin: rescale.min, rescaleMax: rescale.max }
             });
         }
-        pipeline.push(
-        // Precision shim must come before Colormap, its `fs:#decl` inject
-        // declares `precision highp sampler2DArray;` so the subsequent
-        // sampler uniform compiles on WebGL2 / Apple GPU.
-        { module: Sampler2DArrayPrecision, props: {} }, {
+        pipeline.push({
             module: Colormap,
             props: {
                 colormapTexture: data.colormapTexture,
@@ -848,18 +1033,27 @@ function computeBandRanges(bands, bandIndices, pixelCount, nodata) {
  * Supports RGB mode (multi-band → R,G,B with alpha=255, fully baked) and
  * single-band mode (band N normalized into the `r` channel; the ramp is
  * applied downstream by the GPU `Colormap` module via `buildCustomRenderTile`).
+ *
+ * The returned `getTileData` reference is stable across `updateConfig` calls.
+ * deck.gl's TileLayer treats a changed `getTileData` identity as a cache
+ * invalidation, so reusing this loader across band/ramp swaps preserves tiles.
  */
-export function createConfigurableGetTileData(geotiff, config, opts = {}) {
+export function createConfigurableGetTileData(geotiff, config, _opts = {}) {
     const bandCount = geotiff.count;
-    // Shared per-band ranges across tiles (seeded on first tile, widened by subsequent)
-    const sharedMins = new Map();
-    const sharedMaxs = new Map();
-    // Resolve the sprite texture from the first tile's device; reuse per-device.
-    let texturePromise = null;
-    const histogram = config.mode === 'single' ? new Uint32Array(HISTOGRAM_BIN_COUNT) : null;
-    return async (image, options) => {
-        if (config.mode === 'single' && !texturePromise) {
-            texturePromise = getColormapTexture(options.device);
+    // Mutable refs read on every tile bake. Mutating in place keeps the closure
+    // — and therefore the function reference — stable across config swaps.
+    const refs = {
+        config,
+        // Shared per-band ranges across tiles (seeded on first tile, widened by subsequent)
+        sharedMins: new Map(),
+        sharedMaxs: new Map(),
+        // Resolve the sprite texture from the first tile's device; reuse per-device.
+        texturePromise: null
+    };
+    const getTileData = async (image, options) => {
+        const currentConfig = refs.config;
+        if (currentConfig.mode === 'single' && !refs.texturePromise) {
+            refs.texturePromise = getColormapTexture(options.device);
         }
         const [tile, colormapTexture] = await Promise.all([
             image.fetchTile(options.x, options.y, {
@@ -868,33 +1062,38 @@ export function createConfigurableGetTileData(geotiff, config, opts = {}) {
                 pool: options.pool,
                 signal: options.signal
             }),
-            texturePromise ?? Promise.resolve(undefined)
+            refs.texturePromise ?? Promise.resolve(undefined)
         ]);
         const arr = tile.array;
         const { width, height, nodata } = arr;
         const pixelCount = width * height;
         const bands = extractBands(arr, bandCount, pixelCount);
         const rgba = new Uint8ClampedArray(pixelCount * 4);
-        if (config.mode === 'rgb') {
+        // Per-tile histogram, cached by deck.gl's tile cache with the tile
+        // object. Cloud-native by construction: at each zoom level, COG only
+        // decodes the overview tiles that cover the viewport, so the summed
+        // histogram naturally reflects "what the user is looking at right now".
+        const histogram = currentConfig.mode === 'single' ? new Uint32Array(HISTOGRAM_BIN_COUNT) : null;
+        if (currentConfig.mode === 'rgb') {
             // RGB mode: map 3 bands to R, G, B
-            const indices = [config.rBand, config.gBand, config.bBand];
+            const indices = [currentConfig.rBand, currentConfig.gBand, currentConfig.bBand];
             // Compute ranges for the 3 selected bands
             for (const bi of indices) {
-                if (!sharedMins.has(bi)) {
+                if (!refs.sharedMins.has(bi)) {
                     const { mins, maxs } = computeBandRanges(bands, [bi], pixelCount, nodata);
-                    sharedMins.set(bi, mins[0]);
-                    sharedMaxs.set(bi, maxs[0]);
+                    refs.sharedMins.set(bi, mins[0]);
+                    refs.sharedMaxs.set(bi, maxs[0]);
                 }
             }
-            const rBand = bands[config.rBand];
-            const gBand = bands[config.gBand];
-            const bBand = bands[config.bBand];
-            const rMin = sharedMins.get(config.rBand);
-            const rMax = sharedMaxs.get(config.rBand);
-            const gMin = sharedMins.get(config.gBand);
-            const gMax = sharedMaxs.get(config.gBand);
-            const bMin = sharedMins.get(config.bBand);
-            const bMax = sharedMaxs.get(config.bBand);
+            const rBand = bands[currentConfig.rBand];
+            const gBand = bands[currentConfig.gBand];
+            const bBand = bands[currentConfig.bBand];
+            const rMin = refs.sharedMins.get(currentConfig.rBand);
+            const rMax = refs.sharedMaxs.get(currentConfig.rBand);
+            const gMin = refs.sharedMins.get(currentConfig.gBand);
+            const gMax = refs.sharedMaxs.get(currentConfig.gBand);
+            const bMin = refs.sharedMins.get(currentConfig.bBand);
+            const bMax = refs.sharedMaxs.get(currentConfig.bBand);
             const rRange = rMax - rMin || 1;
             const gRange = gMax - gMin || 1;
             const bRange = bMax - bMin || 1;
@@ -923,15 +1122,15 @@ export function createConfigurableGetTileData(geotiff, config, opts = {}) {
             // Single-band mode: normalize the selected band into the `r`
             // channel and reserve `r = 0` as a nodata sentinel that
             // `FilterNoDataVal` discards before the `Colormap` GPU lookup.
-            const bi = config.band;
+            const bi = currentConfig.band;
             const bandData = bands[bi];
-            if (!sharedMins.has(bi) && bandData) {
+            if (!refs.sharedMins.has(bi) && bandData) {
                 const { mins, maxs } = computeBandRanges(bands, [bi], pixelCount, nodata);
-                sharedMins.set(bi, mins[0]);
-                sharedMaxs.set(bi, maxs[0]);
+                refs.sharedMins.set(bi, mins[0]);
+                refs.sharedMaxs.set(bi, maxs[0]);
             }
-            const rangeMin = sharedMins.get(bi) ?? 0;
-            const rangeMax = sharedMaxs.get(bi) ?? 1;
+            const rangeMin = refs.sharedMins.get(bi) ?? 0;
+            const rangeMax = refs.sharedMaxs.get(bi) ?? 1;
             const range = rangeMax - rangeMin || 1;
             for (let i = 0; i < pixelCount; i++) {
                 const raw = bandData?.[i] ?? 0;
@@ -955,17 +1154,34 @@ export function createConfigurableGetTileData(geotiff, config, opts = {}) {
                     }
                 }
             }
-            if (histogram && opts.onHistogram)
-                opts.onHistogram(histogram);
         }
         return {
             imageData: new ImageData(rgba, width, height),
             width,
             height,
-            colormapTexture: config.mode === 'single' ? colormapTexture : undefined,
-            nodataSentinel: config.mode === 'single' ? 0 : undefined
+            colormapTexture: currentConfig.mode === 'single' ? colormapTexture : undefined,
+            nodataSentinel: currentConfig.mode === 'single' ? 0 : undefined,
+            histogram: histogram ?? undefined
         };
     };
+    return {
+        getTileData,
+        updateConfig(next) {
+            // Mode/band swap implies different per-band ranges; clear so the next
+            // tile reseeds them. The function identity itself is preserved.
+            const prev = refs.config;
+            refs.config = next;
+            const bandsChanged = prev.mode !== next.mode ||
+                (prev.mode === 'rgb' &&
+                    next.mode === 'rgb' &&
+                    (prev.rBand !== next.rBand || prev.gBand !== next.gBand || prev.bBand !== next.bBand)) ||
+                (prev.mode === 'single' && next.mode === 'single' && prev.band !== next.band);
+            if (bandsChanged) {
+                refs.sharedMins.clear();
+                refs.sharedMaxs.clear();
+            }
+        }
+    };
 }
 // ─── EPSG resolution via bundled database ────────────────────────
 /**
@@ -1052,13 +1268,58 @@ export async function resolveProj4Def(crs, _signal) {
     // ProjJSON — stringify for proj4
     return JSON.stringify(crs);
 }
+/**
+ * Standard Web Mercator ground resolution (meters per screen pixel) at a given
+ * zoom and latitude. Equivalent to MapLibre's `metersPerPixel`. Use this to
+ * pick a COG overview level that matches what's painted on screen.
+ */
+export function mapResolutionMetersPerPixel(zoom, latitude) {
+    return (156543.03392 * Math.cos((latitude * Math.PI) / 180)) / 2 ** zoom;
+}
+/**
+ * Pick the coarsest overview whose pixel size is ≤ `targetMetersPerPixel`,
+ * matching lazycogs' `_select_overview`. Walks `geotiff.overviews` in
+ * finest → coarsest order (the documented sort) and returns the last entry
+ * that still satisfies the constraint. Returns `null` to mean "use full
+ * resolution" (either the COG has no overviews, the target is already finer
+ * than native, or every overview is coarser than the target — never
+ * upsample).
+ *
+ * The COG's affine `a` component is the X-pixel-size in the COG's native CRS
+ * units. For Web Mercator and other meter-based CRSes this is meters/pixel
+ * and lines up directly with `mapResolutionMetersPerPixel`. For degree-based
+ * CRSes (EPSG:4326) the comparison is against degrees/pixel, so callers
+ * should derive the target in the same units.
+ */
+export function selectOverviewForResolution(geotiff, targetMetersPerPixel) {
+    if (!geotiff.overviews.length)
+        return null;
+    const nativeRes = Math.abs(geotiff.transform[0]);
+    if (targetMetersPerPixel <= nativeRes)
+        return null;
+    let selected = null;
+    for (const overview of geotiff.overviews) {
+        if (Math.abs(overview.transform[0]) <= targetMetersPerPixel) {
+            selected = overview;
+        }
+        else {
+            break;
+        }
+    }
+    return selected;
+}
 /**
  * Read pixel values at a given lng/lat from a GeoTIFF.
  * Converts WGS84 → source CRS → pixel coords, fetches the tile, reads all bands.
+ *
+ * If `options.overview` is supplied, the read happens against that overview
+ * level instead of the full-resolution image (so the inspected value matches
+ * the overview deck.gl is currently painting on screen). Pass `null` /
+ * `undefined` to keep the legacy full-resolution behaviour.
  */
 export async function readPixelAtLngLat(geotiff, lng, lat, proj4Def, 
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
-pool, signal) {
+pool, signal, options) {
     // Convert WGS84 to source CRS
     let srcX = lng;
     let srcY = lat;
@@ -1072,15 +1333,17 @@ pool, signal) {
             return null;
         }
     }
+    // Read against the selected overview if one was supplied, else full res.
+    const source = options?.overview ?? geotiff;
     // Get pixel indices (row, col)
-    const [row, col] = geotiff.index(srcX, srcY);
-    if (row < 0 || row >= geotiff.height || col < 0 || col >= geotiff.width)
+    const [row, col] = source.index(srcX, srcY);
+    if (row < 0 || row >= source.height || col < 0 || col >= source.width)
         return null;
     // Compute tile indices
-    const tileX = Math.floor(col / geotiff.tileWidth);
-    const tileY = Math.floor(row / geotiff.tileHeight);
+    const tileX = Math.floor(col / source.tileWidth);
+    const tileY = Math.floor(row / source.tileHeight);
     // Fetch tile
-    const tile = await geotiff.fetchTile(tileX, tileY, { pool, signal });
+    const tile = await source.fetchTile(tileX, tileY, { pool, signal });
     const arr = tile.array;
     // Read all band values at this pixel
     const localCol = col - tileX * arr.width;