@walkthru-earth/objex 1.2.1 → 1.3.1

package/dist/utils/cog.js

@@ -1,103 +1,37 @@
 import { inferRenderPipeline } from '@developmentseed/deck.gl-geotiff';
-import { LinearRescale } from '@developmentseed/deck.gl-raster/gpu-modules';
+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 proj4Lib from 'proj4';
+import { buildDataTypeLabel, clampBounds, SF_LABELS, safeClamp } from './cog-pure.js';
+import { COLORMAP_INDEX, getColormapTexture } from './colormap-sprite.js';
+export { buildDataTypeLabel, clampBounds, SF_LABELS, safeClamp };
 // ─── Constants ───────────────────────────────────────────────────
-/** SampleFormat tag value → human label. */
-export const SF_LABELS = {
-    1: 'uint',
-    2: 'int',
-    3: 'float',
-    4: 'void',
-    5: 'complex int',
-    6: 'complex float'
-};
-export const COLOR_RAMP_STOPS = {
-    grayscale: [
-        [0, 0, 0],
-        [255, 255, 255]
-    ],
-    terrain: [
-        [0, 0, 128],
-        [0, 100, 200],
-        [0, 154, 80],
-        [120, 180, 50],
-        [200, 170, 60],
-        [180, 120, 50],
-        [140, 90, 40],
-        [200, 200, 200],
-        [255, 255, 255]
-    ],
-    viridis: [
-        [68, 1, 84],
-        [72, 36, 117],
-        [64, 67, 135],
-        [52, 94, 141],
-        [33, 145, 140],
-        [43, 176, 127],
-        [95, 201, 97],
-        [186, 222, 39],
-        [253, 231, 37]
-    ],
-    magma: [
-        [0, 0, 4],
-        [22, 11, 57],
-        [67, 15, 98],
-        [114, 24, 114],
-        [161, 48, 104],
-        [206, 82, 83],
-        [237, 132, 62],
-        [251, 192, 75],
-        [252, 253, 191]
-    ],
-    turbo: [
-        [48, 18, 59],
-        [31, 82, 188],
-        [23, 158, 227],
-        [47, 212, 161],
-        [121, 238, 104],
-        [193, 241, 57],
-        [245, 206, 27],
-        [253, 141, 31],
-        [213, 47, 24]
-    ],
-    spectral: [
-        [158, 1, 66],
-        [213, 62, 79],
-        [244, 109, 67],
-        [253, 174, 97],
-        [254, 224, 139],
-        [255, 255, 191],
-        [230, 245, 152],
-        [171, 221, 164],
-        [94, 79, 162]
-    ]
+/**
+ * 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.
+ *
+ * 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.
+ */
+const Sampler2DArrayPrecision = {
+    name: 'sampler2darray-precision',
+    fs: '',
+    inject: {
+        'fs:#decl': 'precision highp sampler2DArray;\n'
+    }
 };
-/** Interpolate a normalized value (0..1) into an RGB color from a ramp. */
-export function interpolateRamp(stops, t) {
-    const n = stops.length - 1;
-    const idx = Math.max(0, Math.min(n, t * n));
-    const lo = Math.floor(idx);
-    const hi = Math.min(lo + 1, n);
-    const f = idx - lo;
-    return [
-        Math.round(stops[lo][0] + f * (stops[hi][0] - stops[lo][0])),
-        Math.round(stops[lo][1] + f * (stops[hi][1] - stops[lo][1])),
-        Math.round(stops[lo][2] + f * (stops[hi][2] - stops[lo][2]))
-    ];
-}
-/** Generate a CSS linear-gradient string for a color ramp. */
-export function rampToGradientCss(id) {
-    const stops = COLOR_RAMP_STOPS[id];
-    const colors = stops.map((s, i) => `rgb(${s[0]},${s[1]},${s[2]}) ${((i / (stops.length - 1)) * 100).toFixed(0)}%`);
-    return `linear-gradient(to right, ${colors.join(', ')})`;
-}
 /** Create a sensible default band config based on COG metadata. */
 export function defaultBandConfig(bandCount, sampleFormat) {
-    if (bandCount >= 3) {
+    if (bandCount >= 3 && bandCount <= 4) {
         return {
             mode: 'rgb',
             rBand: 0,
@@ -150,6 +84,12 @@ export function needsCustomPipelineForConfig(geotiff, config) {
     const tags = geotiff.cachedTags;
     const sf = tags.sampleFormat;
     const isUint = sf !== null && sf[0] === 1;
+    // GPU textures accept 1-4 channels; COGs with more samples per pixel (embeddings,
+    // hyperspectral, multi-band features) must route through the CPU pipeline which
+    // reads selected band indices and bakes RGBA. Otherwise the library throws
+    // "Unsupported SamplesPerPixel N" in verifySamplesPerPixel.
+    if (geotiff.count > 4)
+        return true;
     if (!isUint)
         return true;
     // Palette-indexed uint COGs with an embedded ColorMap tag are auto-rendered
@@ -165,6 +105,12 @@ export function needsCustomPipelineForConfig(geotiff, config) {
         return true;
     if (config.rBand !== 0 || config.gBand !== 1 || config.bBand !== 2)
         return true;
+    // 4-band uint (e.g. NAIP RGB+NIR) must route through the CPU pipeline.
+    // The library default maps all 4 samples to RGBA, turning the extra band
+    // into a variable alpha channel even when it is not an alpha declaration.
+    // The custom pipeline explicitly picks 3 bands and bakes alpha=255.
+    if (geotiff.count === 4)
+        return true;
     return false;
 }
 export const DEFAULT_RESCALE = { min: 0, max: 1 };
@@ -215,6 +161,27 @@ 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).
+ */
+export function buildBandRenderPipeline(opts = {}) {
+    const modules = [];
+    if (opts.noDataVal !== undefined && opts.noDataVal !== null) {
+        modules.push({
+            module: FilterNoDataVal,
+            props: { noDataVal: opts.noDataVal }
+        });
+    }
+    if (opts.rescale && isRescaleActive(opts.rescale)) {
+        modules.push({
+            module: LinearRescale,
+            props: { rescaleMin: opts.rescale.min, rescaleMax: opts.rescale.max }
+        });
+    }
+    return modules;
+}
 // ─── GeoTIFF normalization for COGLayer ──────────────────────────
 // Web Mercator's safe latitude limit. EPSG:4326 bboxes outside ±85.051129° hit
 // out-of-domain proj4 NaN when the library generates its tile matrix set.
@@ -275,13 +242,17 @@ export function selectCogPipeline(geotiff, opts = {}) {
     if (useCustom && bandConfig) {
         return {
             getTileData: createConfigurableGetTileData(geotiff, bandConfig),
-            renderTile: customRenderTile
+            renderTile: buildCustomRenderTile(bandConfig, rescale)
         };
     }
     if (useCustom) {
+        // Synthesize a single-band config so the GPU Colormap path still
+        // applies when a non-uint COG renders without a user-chosen ramp.
+        const fallbackSf = geotiff.cachedTags.sampleFormat?.[0] ?? 1;
+        const fallbackConfig = defaultBandConfig(geotiff.count, fallbackSf);
         return {
             getTileData: createCustomGetTileData(geotiff),
-            renderTile: customRenderTile
+            renderTile: buildCustomRenderTile(fallbackConfig, rescale)
         };
     }
     if (rescale && isRescaleActive(rescale)) {
@@ -295,27 +266,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-pure.ts` 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.
@@ -624,12 +577,17 @@ 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;
 /**
  * Create custom getTileData for non-uint COGs.
  * Reads band 0, normalizes using GDAL statistics / per-tile adaptive stretch,
- * applies terrain color ramp for single-band data.
+ * bakes a grayscale `r`-channel image so the GPU `Colormap` shader module
+ * (wired downstream by `selectCogPipeline`) can apply the ramp by sampling
+ * `colormaps.png`. Reserves `r = 0` for nodata so `FilterNoDataVal` can
+ * discard those fragments before the ramp sample.
  */
-export function createCustomGetTileData(geotiff) {
+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;
@@ -656,26 +614,37 @@ export function createCustomGetTileData(geotiff) {
         globalMax = globalMax * (gdalScale ?? 1) + (gdalOffset ?? 0);
     }
     const bandCount = geotiff.count;
-    const sf = tags.sampleFormat?.[0] ?? 1;
     const isSingleBand = bandCount === 1;
     // Shared range across all tiles — when no GDAL stats exist, the first
     // tile's scan seeds the range and subsequent tiles widen it. This
     // eliminates visible seams between tiles caused by per-tile normalization.
     let sharedMin = globalMin;
     let sharedMax = globalMax;
+    // Resolve the sprite texture from the first tile's device; reuse per-device.
+    let texturePromise = null;
     return async (image, options) => {
-        const tile = await image.fetchTile(options.x, options.y, {
-            boundless: false,
-            // eslint-disable-next-line @typescript-eslint/no-explicit-any
-            pool: options.pool,
-            signal: options.signal
-        });
+        if (isSingleBand && !texturePromise) {
+            texturePromise = getColormapTexture(options.device);
+        }
+        const [tile, colormapTexture] = await Promise.all([
+            image.fetchTile(options.x, options.y, {
+                boundless: false,
+                // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                pool: options.pool,
+                signal: options.signal
+            }),
+            texturePromise ?? Promise.resolve(undefined)
+        ]);
         const arr = tile.array;
         const { width, height, nodata } = arr;
         const bandData = arr.layout === 'band-separate' ? arr.bands[0] : arr.data;
         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;
@@ -704,7 +673,10 @@ export function createCustomGetTileData(geotiff) {
         const rangeMin = sharedMin;
         const rangeMax = sharedMax;
         const range = rangeMax - rangeMin || 1;
-        // Render to RGBA
+        // Render to RGBA. For single-band we bake normalized value into the
+        // `r` channel and reserve `r = 0` for nodata (see CustomTileData
+        // docs). Multi-band non-uint keeps the plain grayscale + α=255
+        // output so the default library pipeline consumes it unchanged.
         const rgba = new Uint8ClampedArray(pixelCount * 4);
         for (let i = 0; i < pixelCount; i++) {
             const raw = bandData[i];
@@ -719,15 +691,18 @@ export function createCustomGetTileData(geotiff) {
             }
             const v = hasScaleOffset ? raw * scale + offset : raw;
             const t = Math.max(0, Math.min(1, (v - rangeMin) / range));
-            if (isSingleBand && (sf === 2 || sf === 3)) {
-                // Terrain color ramp for single-band int/float (likely elevation/DEM)
-                const [r, g, b] = terrainColor(t);
-                rgba[idx] = r;
-                rgba[idx + 1] = g;
-                rgba[idx + 2] = b;
+            if (isSingleBand) {
+                // Reserve r=0 for nodata; valid data maps to [1, 255].
+                const gray = 1 + Math.round(t * 254);
+                rgba[idx] = gray;
+                rgba[idx + 1] = 0;
+                rgba[idx + 2] = 0;
+                if (histogram) {
+                    const bin = Math.min(HISTOGRAM_BIN_COUNT - 1, Math.floor(t * HISTOGRAM_BIN_COUNT));
+                    histogram[bin]++;
+                }
             }
             else {
-                // Grayscale for multi-band or other types
                 const gray = Math.round(t * 255);
                 rgba[idx] = gray;
                 rgba[idx + 1] = gray;
@@ -738,18 +713,57 @@ export function createCustomGetTileData(geotiff) {
         return {
             imageData: new ImageData(rgba, width, height),
             width,
-            height
+            height,
+            colormapTexture: isSingleBand ? colormapTexture : undefined,
+            nodataSentinel: isSingleBand ? 0 : undefined,
+            histogram: histogram ?? undefined
         };
     };
 }
 /**
- * Custom renderTile for non-uint COGs.
- * v0.5 RasterLayer requires a RenderTileResult with `image` or `renderPipeline`.
- * We produce an ImageData and pass it through the `image` slot. deck.gl manages
- * the texture lifecycle and prepends a CreateTexture module automatically.
+ * Custom renderTile for COGs that use the CPU pipeline. For RGB mode (and
+ * legacy multi-band non-uint), the `image` slot carries a fully-baked RGBA
+ * `ImageData` and there is nothing to append on the GPU. For single-band
+ * mode, the image carries a normalized `r`-channel and this function
+ * appends `FilterNoDataVal` (to discard r=0 nodata sentinels), optional
+ * `LinearRescale` (brightness/contrast slider), and the sprite-based
+ * `Colormap` module so switching ramps is a uniform update — no tile
+ * re-decode required. The `colormapTexture` is stashed on `data` by the
+ * corresponding `getTileData` factory; if the sprite failed to resolve we
+ * fall back to the plain grayscale image.
  */
-export function customRenderTile(data) {
-    return { image: data.imageData };
+export function buildCustomRenderTile(config, rescale) {
+    return (data) => {
+        if (config.mode === 'rgb' || !data.colormapTexture) {
+            return { image: data.imageData };
+        }
+        const colormapIndex = COLORMAP_INDEX[config.colorRamp] ?? COLORMAP_INDEX.viridis;
+        const pipeline = [
+            {
+                module: FilterNoDataVal,
+                props: { value: (data.nodataSentinel ?? 0) / 255 }
+            }
+        ];
+        if (rescale && isRescaleActive(rescale)) {
+            pipeline.push({
+                module: LinearRescale,
+                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: {} }, {
+            module: Colormap,
+            props: {
+                colormapTexture: data.colormapTexture,
+                colormapIndex,
+                reversed: false
+            }
+        });
+        return { image: data.imageData, renderPipeline: pipeline };
+    };
 }
 // ─── Configurable custom pipeline ────────────────────────────────
 /**
@@ -806,25 +820,40 @@ function computeBandRanges(bands, bandIndices, pixelCount, nodata) {
 }
 /**
  * Create a configurable getTileData that respects BandConfig.
- * Supports both RGB mode (multi-band → R,G,B) and single-band mode (color ramp).
+ * 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`).
  */
-export function createConfigurableGetTileData(geotiff, config) {
+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;
     return async (image, options) => {
-        const tile = await image.fetchTile(options.x, options.y, {
-            boundless: false,
-            // eslint-disable-next-line @typescript-eslint/no-explicit-any
-            pool: options.pool,
-            signal: options.signal
-        });
+        if (config.mode === 'single' && !texturePromise) {
+            texturePromise = getColormapTexture(options.device);
+        }
+        const [tile, colormapTexture] = await Promise.all([
+            image.fetchTile(options.x, options.y, {
+                boundless: false,
+                // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                pool: options.pool,
+                signal: options.signal
+            }),
+            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);
+        // 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 = config.mode === 'single' ? new Uint32Array(HISTOGRAM_BIN_COUNT) : null;
         if (config.mode === 'rgb') {
             // RGB mode: map 3 bands to R, G, B
             const indices = [config.rBand, config.gBand, config.bBand];
@@ -870,7 +899,9 @@ export function createConfigurableGetTileData(geotiff, config) {
             }
         }
         else {
-            // Single-band mode: normalize + color ramp
+            // 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 bandData = bands[bi];
             if (!sharedMins.has(bi) && bandData) {
@@ -881,7 +912,6 @@ export function createConfigurableGetTileData(geotiff, config) {
             const rangeMin = sharedMins.get(bi) ?? 0;
             const rangeMax = sharedMaxs.get(bi) ?? 1;
             const range = rangeMax - rangeMin || 1;
-            const rampStops = COLOR_RAMP_STOPS[config.colorRamp];
             for (let i = 0; i < pixelCount; i++) {
                 const raw = bandData?.[i] ?? 0;
                 const isND = (nodata !== null && raw === nodata) || !Number.isFinite(raw);
@@ -894,15 +924,25 @@ export function createConfigurableGetTileData(geotiff, config) {
                 }
                 else {
                     const t = Math.max(0, Math.min(1, (raw - rangeMin) / range));
-                    const [r, g, b] = interpolateRamp(rampStops, t);
-                    rgba[idx] = r;
-                    rgba[idx + 1] = g;
-                    rgba[idx + 2] = b;
+                    rgba[idx] = 1 + Math.round(t * 254);
+                    rgba[idx + 1] = 0;
+                    rgba[idx + 2] = 0;
                     rgba[idx + 3] = 255;
+                    if (histogram) {
+                        const bin = Math.min(HISTOGRAM_BIN_COUNT - 1, Math.floor(t * HISTOGRAM_BIN_COUNT));
+                        histogram[bin]++;
+                    }
                 }
             }
         }
-        return { imageData: new ImageData(rgba, width, height), width, height };
+        return {
+            imageData: new ImageData(rgba, width, height),
+            width,
+            height,
+            colormapTexture: config.mode === 'single' ? colormapTexture : undefined,
+            nodataSentinel: config.mode === 'single' ? 0 : undefined,
+            histogram: histogram ?? undefined
+        };
     };
 }
 // ─── EPSG resolution via bundled database ────────────────────────

package/dist/utils/colormap-sprite.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Shared loader for the `colormaps.png` sprite shipped by
+ * `@developmentseed/deck.gl-raster`. Decodes the sprite once per session and
+ * uploads it to the GPU once per `Device`, so every COG / mosaic / multicog
+ * viewer that renders a single-band colormap shares the same 2D-array
+ * texture.
+ *
+ * The sprite is ~16 KB. Decode is fire-and-forget on first touch and caches
+ * the resulting `ImageData` for the life of the tab; texture upload runs
+ * synchronously once the device is known. Switching color ramps becomes a
+ * uniform update (`colormapIndex`) rather than a texture rebind.
+ */
+import { type ColormapName } from '@developmentseed/deck.gl-raster/gpu-modules';
+import type { Device, Texture } from '@luma.gl/core';
+export { COLORMAP_INDEX, type ColormapName } from '@developmentseed/deck.gl-raster/gpu-modules';
+/** URL of the shipped sprite, consumable as a CSS `background-image`. */
+export declare const COLORMAP_SPRITE_URL: any;
+/** Number of distinct ramps encoded as 1-pixel-tall rows in the sprite. */
+export declare const COLORMAP_SPRITE_LAYERS: number;
+/** Width of each ramp row in pixels (also the sampling resolution). */
+export declare const COLORMAP_SPRITE_WIDTH = 256;
+/** All ramp names, sorted alphabetically (matches `COLORMAP_INDEX` key order). */
+export declare const COLORMAP_NAMES: ColormapName[];
+/** Decode the shipped sprite once per session. Safe to call repeatedly. */
+export declare function loadColormapSprite(): Promise<ImageData>;
+/**
+ * Get (or lazily build) the `sampler2DArray` colormap texture for a given
+ * device. Returns the same `Texture` on subsequent calls for the same device
+ * so it can be passed directly as the `colormapTexture` prop of the
+ * `Colormap` shader module.
+ */
+export declare function getColormapTexture(device: Device): Promise<Texture>;
+/**
+ * CSS `background` properties that render a single colormap row from the
+ * shipped sprite. Vertically scales the sprite so each 1-pixel row fills
+ * the container's full height, then offsets to land on the requested layer.
+ * Returns `undefined` for unknown ramp names so the caller can fall back.
+ */
+export declare function spriteBackgroundStyle(name: ColormapName, heightPx: number): string | undefined;

package/dist/utils/colormap-sprite.js

@@ -0,0 +1,77 @@
+/**
+ * Shared loader for the `colormaps.png` sprite shipped by
+ * `@developmentseed/deck.gl-raster`. Decodes the sprite once per session and
+ * uploads it to the GPU once per `Device`, so every COG / mosaic / multicog
+ * viewer that renders a single-band colormap shares the same 2D-array
+ * texture.
+ *
+ * The sprite is ~16 KB. Decode is fire-and-forget on first touch and caches
+ * the resulting `ImageData` for the life of the tab; texture upload runs
+ * synchronously once the device is known. Switching color ramps becomes a
+ * uniform update (`colormapIndex`) rather than a texture rebind.
+ */
+import { COLORMAP_INDEX, createColormapTexture, decodeColormapSprite } from '@developmentseed/deck.gl-raster/gpu-modules';
+// The `?url` suffix makes Vite emit the PNG as a fingerprinted asset and
+// hand us back a string URL. Bundlers like Rollup/webpack behave the same
+// for this pattern; the build define in `vite.config.ts` already copies the
+// PNG into the production bundle.
+import colormapsPngUrl from '@developmentseed/deck.gl-raster/gpu-modules/colormaps.png?url';
+export { COLORMAP_INDEX } from '@developmentseed/deck.gl-raster/gpu-modules';
+/** URL of the shipped sprite, consumable as a CSS `background-image`. */
+export const COLORMAP_SPRITE_URL = colormapsPngUrl;
+/** Number of distinct ramps encoded as 1-pixel-tall rows in the sprite. */
+export const COLORMAP_SPRITE_LAYERS = Object.keys(COLORMAP_INDEX).length;
+/** Width of each ramp row in pixels (also the sampling resolution). */
+export const COLORMAP_SPRITE_WIDTH = 256;
+/** All ramp names, sorted alphabetically (matches `COLORMAP_INDEX` key order). */
+export const COLORMAP_NAMES = Object.keys(COLORMAP_INDEX).sort();
+let spritePromise = null;
+const textureCache = new WeakMap();
+/** Decode the shipped sprite once per session. Safe to call repeatedly. */
+export function loadColormapSprite() {
+    if (!spritePromise) {
+        spritePromise = (async () => {
+            const res = await fetch(colormapsPngUrl);
+            if (!res.ok) {
+                throw new Error(`Failed to fetch colormaps.png: ${res.status}`);
+            }
+            const bytes = await res.arrayBuffer();
+            return decodeColormapSprite(bytes);
+        })();
+    }
+    return spritePromise;
+}
+/**
+ * Get (or lazily build) the `sampler2DArray` colormap texture for a given
+ * device. Returns the same `Texture` on subsequent calls for the same device
+ * so it can be passed directly as the `colormapTexture` prop of the
+ * `Colormap` shader module.
+ */
+export async function getColormapTexture(device) {
+    const cached = textureCache.get(device);
+    if (cached)
+        return cached;
+    const imageData = await loadColormapSprite();
+    const texture = createColormapTexture(device, imageData);
+    textureCache.set(device, texture);
+    return texture;
+}
+/**
+ * CSS `background` properties that render a single colormap row from the
+ * shipped sprite. Vertically scales the sprite so each 1-pixel row fills
+ * the container's full height, then offsets to land on the requested layer.
+ * Returns `undefined` for unknown ramp names so the caller can fall back.
+ */
+export function spriteBackgroundStyle(name, heightPx) {
+    const index = COLORMAP_INDEX[name];
+    if (index === undefined)
+        return undefined;
+    const totalHeight = COLORMAP_SPRITE_LAYERS * heightPx;
+    const yOffset = index * heightPx;
+    return [
+        `background-image: url("${COLORMAP_SPRITE_URL}")`,
+        'background-repeat: no-repeat',
+        `background-size: 100% ${totalHeight}px`,
+        `background-position: 0 -${yOffset}px`
+    ].join('; ');
+}

package/dist/utils/connection-identity.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Canonical connection identity.
+ *
+ * Single source of truth for deciding when two connection configs point at
+ * the same bucket. Used by the connections store to deduplicate auto-detect,
+ * manual add, and edit flows, so one physical bucket never ends up with
+ * multiple competing local records.
+ *
+ * Identity rules, per provider:
+ *
+ *   azure  → (provider, endpoint, bucket)     endpoint carries the account
+ *   gcs    → (provider, bucket)               GCS bucket names are global
+ *   s3     → (provider, bucket, region)       AWS native: same bucket name
+ *                                             can exist in exactly one region,
+ *                                             but the region is load-bearing
+ *                                             for signing, so a paste with a
+ *                                             different region is a distinct
+ *                                             connection until the user merges
+ *   other  → (provider, endpoint, bucket)     r2, b2, minio, wasabi, storj,
+ *                                             digitalocean, contabo, hetzner,
+ *                                             linode, ovhcloud, custom
+ *
+ * Endpoint normalization is aggressive: scheme + host + non-default port +
+ * pathname, with trailing slashes and default ports stripped, host lowercased.
+ * That collapses the common trip hazards — http vs https, :443 vs empty,
+ * trailing slash drift, mixed case host.
+ */
+import type { ProviderId } from '../storage/providers.js';
+export interface ConnectionIdentityInput {
+    provider: string;
+    endpoint: string;
+    bucket: string;
+    region: string;
+}
+/**
+ * Normalize an endpoint URL to a canonical form suitable for equality checks.
+ * Empty / whitespace-only input returns `''` (the "no endpoint" sentinel).
+ * Non-URL strings are lowercased and stripped of trailing slashes as a best
+ * effort so the comparison is still deterministic.
+ */
+export declare function normalizeEndpoint(raw: string | undefined | null): string;
+/** Collapse unknown / empty providers to `'s3'`; otherwise lowercase. */
+export declare function normalizeProvider(provider: string | undefined | null): ProviderId;
+/**
+ * Produce a canonical key for a connection's identity. Two connection
+ * configs with the same identity key point at the same physical bucket.
+ * Returns `''` when the config is too incomplete to identify a bucket.
+ */
+export declare function connectionIdentityKey(input: ConnectionIdentityInput): string;
+/** Convenience: true when both inputs share the same non-empty identity. */
+export declare function isSameConnectionIdentity(a: ConnectionIdentityInput, b: ConnectionIdentityInput): boolean;