@nika-js/onlymap 0.6.26 → 0.7.1

package/dist/raster-pipeline.d.ts

@@ -4,40 +4,135 @@
  * (the GPU modules), NOT on `@developmentseed/deck.gl-geotiff` or `zarrita`, so
  * neither lazy chunk drags the other's decoder in.
  *
- * The contract: a per-tile Float32 texture (single-band `r32float`, or three-
- * band `rgba32float`) plus the styling scalars, run through
- * FilterNoDataVal → LinearRescale → Colormap (single-band only). Restretch and
- * recolor are uniform-only updates on a fresh layer instance; the tile cache
- * survives because the getTileData callback that produced these textures is a
- * module-level stable reference in each layer.
+ * COG v2 (docs/design/cog-v2.md, issue #13): ONE pipeline for single-band and
+ * composite sources, built on CompositeBands — per-band `r32float` textures
+ * created LAZILY from the retained decode, with an `ivec4 channelMap` uniform
+ * routing bands to RGB channels. A single-band source is the degenerate
+ * composite (slot 0 replicated to R=G=B), which keeps every styling feature
+ * written exactly once. Band switches re-run renderTile on a fresh layer
+ * instance; missing band textures are uploaded from the retained array — the
+ * tile cache, the HTTP cache, and the decode all survive. Nothing short of a
+ * `src` change refetches.
+ *
+ * Pipeline order (load-bearing): CreateTexture (base-texture insurance for
+ * the mesh) → CompositeBands (color = raw band values) → FilterNoDataVal
+ * (tests the RAW datum, so it precedes the rescale squash) → LinearRescale →
+ * Colormap (single-band only).
  */
 import type { Device, Texture } from "@luma.gl/core";
 import { type RasterModule } from "@developmentseed/deck.gl-raster/gpu-modules";
-/** A styled tile's GPU payload (satisfies deck.gl-raster's MinimalTileData + ours). */
+/**
+ * The decoded source a tile retains — structural subset of
+ * `@developmentseed/geotiff`'s RasterArray (band-separate carries `bands`,
+ * pixel-interleaved carries `data` + `count`), typed here so the pipeline
+ * stays decoder-agnostic and tests fabricate it without a TIFF in sight.
+ */
+export interface RasterArrayLike {
+    layout: "band-separate" | "pixel-interleaved";
+    width: number;
+    height: number;
+    bands?: ArrayLike<number>[];
+    data?: ArrayLike<number>;
+    count?: number;
+}
+/** A styled tile's payload: retained decode + lazily-created band textures. */
 export interface OmTileData {
     width: number;
     height: number;
     byteLength: number;
-    texture: Texture;
+    /** The device the tile's textures live on — renderTile receives only the data, so lazy uploads need it here. */
+    device: Device;
+    /** Decoded source (ALL bands) retained for the tile-cache lifetime — band switches re-upload from it, identify samples it. Null when the source pre-uploads (Zarr) or retention is off. */
+    array: RasterArrayLike | null;
+    /** 0-based band index → its r32float texture. Lazily filled by ensureBandTextures; fully destroyed by destroyTileTextures. */
+    bandTextures: Map<number, Texture>;
     colormapTexture: Texture;
     bandCount: number;
     nodata: number | null;
 }
-/** The four styling scalars every raster source (COG, Zarr) exposes. */
+/** The styling scalars every raster source (COG, Zarr) exposes. */
 export interface RasterStyle {
-    /** Rescale window; both default to the 8-bit range when absent. */
-    rescaleMin?: number | null;
-    rescaleMax?: number | null;
+    /** Rescale window; both default to the 8-bit range when absent. A number broadcasts to every selected band; a triple gives per-band windows, positionally matching a `bands` triple (COG v2 decision: per-band ships in 0.7.0). */
+    rescaleMin?: number | number[] | null;
+    rescaleMax?: number | number[] | null;
     /** Sprite colormap name (single-band sources only). Unknown names warn + fall back to gray. */
     colormap?: string | null;
+    /** Reversed colormap (upstream Colormap's own `reversed` prop — the fork the design planned turned out unnecessary). */
+    reverse?: boolean | null;
     /** Overrides the source's own nodata sentinel. */
     nodataOverride?: number | null;
+    /** 1-based band selection (GDAL convention): a single band (colormap-eligible) or an [r,g,b] triple. Absent = band 1 / first three. */
+    bands?: number | number[] | null;
+    /** Non-linear stretch applied to the rescaled [0,1] value: linear (default) | log | sqrt. */
+    stretch?: string | null;
+    /** Power-law exponent > 0 (display gamma); 1 = identity. */
+    gamma?: number | null;
 }
 export declare function getColormapTexture(device: Device): Promise<Texture>;
 export declare function resolveColormapIndex(name: string): number;
 /**
- * The styled render pipeline for one tile. Nodata tests the RAW datum, so it
- * precedes the rescale squash; the colormap runs only for single-band sources.
+ * Authored `bands` (1-based) → 0-based indices, validated against the
+ * source's band count. A single index means "single-band" (colormap
+ * pipeline); a triple means RGB composite. Anything unusable falls back to
+ * the source defaults (band 1 / first three) with one warning per shape —
+ * the layer renders SOMETHING rather than blanking (structured errors land
+ * in phase 6).
+ */
+export declare function resolveBands(bands: number | number[] | null | undefined, bandCount: number): number[];
+/** Every band's raw value at one pixel — the identify sampler (no per-band copies; reads the retained layout directly). */
+export declare function sampleAllBands(arr: RasterArrayLike, px: number, py: number, bandCount: number): number[];
+/** One band of a decoded array as Float32 regardless of layout — luma's r32float upload rejects uint8/16 TypedArrays, so non-Float32 sources copy (raw values preserved; that's the contract the rescale window depends on). */
+export declare function extractBand(arr: RasterArrayLike, band: number): Float32Array;
+/**
+ * Creates any missing textures for the selected bands from the retained
+ * array, and destroys textures for bands no longer selected (VRAM stays at
+ * ≤ the selected set). Returns the selected bands' textures in order.
+ * A tile whose array was dropped (identify off — phase 4) keeps whatever
+ * textures it already has; selections it can't satisfy fall back to the
+ * first available texture rather than crashing mid-frame.
+ */
+export declare function ensureBandTextures(tile: OmTileData, bands: number[]): Texture[];
+/** Frees every GPU texture a tile owns and drops the retained decode — the onTileUnload hook (the sprite texture is device-scoped and must NOT be destroyed here). */
+export declare function destroyTileTextures(tile: OmTileData): void;
+/**
+ * Per-band rescale windows (design decision: ships in 0.7.0, not a
+ * follow-up). Used ONLY when a triple window is authored — scalar windows
+ * keep upstream's LinearRescale so existing maps keep their exact shader
+ * (the phase-1 SSIM-1.0 parity stays intact).
+ */
+export declare const PerBandRescale: RasterModule["module"];
+/**
+ * Non-linear stretch + display gamma, applied AFTER the rescale squash (the
+ * value is in [0,1]) and BEFORE the colormap lookup. `log` is the bounded
+ * log10 curve `log(1+9x)/log 10` (monotone, hits 0→0 and 1→1, no -inf).
+ * Inserted only when non-identity, so linear/γ=1 maps keep their shader.
+ */
+export declare const StretchGamma: RasterModule["module"];
+/** stretch attribute → mode number (0 linear / 1 log / 2 sqrt); unknown warns once and stays linear. */
+export declare function resolveStretchMode(stretch: string | null | undefined): number;
+/** gamma attribute → validated exponent (> 0); anything else warns once and is identity. */
+export declare function resolveGamma(gamma: number | null | undefined): number;
+/**
+ * Normalizes the authored window(s) against the selection. Scalars
+ * broadcast; a triple pairs positionally with a `bands` triple. Returns
+ * either a scalar window (upstream LinearRescale — shader parity for
+ * existing maps) or per-band vec3s (PerBandRescale).
+ */
+export declare function resolveWindow(style: RasterStyle, bands: number[]): {
+    kind: "scalar";
+    min: number;
+    max: number;
+} | {
+    kind: "per-band";
+    minV: [number, number, number];
+    maxV: [number, number, number];
+};
+/** channelMap for a selection: single band replicates slot 0 to RGB (gray, colormap-eligible); a triple maps each channel to its band's slot. Alpha is always the shader's opaque -1. */
+export declare function buildChannelMap(bands: number[], slotOf: (band: number) => number): [number, number, number, number];
+/**
+ * The styled render pipeline for one tile. One shape for single-band and
+ * composite sources (design decision: UNIFY, with the Metal-ANGLE pixel
+ * parachute in phase-1 acceptance).
  */
 export declare function buildRenderPipeline(tile: OmTileData, style: RasterStyle): {
     renderPipeline: RasterModule[];

package/dist/raster.d.ts

@@ -1,7 +1,79 @@
+/**
+ * Native COG/GeoTIFF raster layer (spec: "Raster / GeoTIFF — native COG
+ * layer"). A LAZY chunk — dynamically imported the first time a manifest
+ * uses `type="COGLayer"` (see layer-registry's `loadClass` seam), so the
+ * eager bundle stays raster-free.
+ *
+ * Built on `@developmentseed/deck.gl-geotiff` + `deck.gl-raster` (MIT),
+ * compiled INSIDE the library so their `@deck.gl/*` imports resolve to the
+ * bundled deck — the class-identity requirement that rules out consuming
+ * these packages from a consumer's own node_modules.
+ *
+ * Two render paths, chosen per instance:
+ *  - UNSTYLED (no min/max/colormap/nodata authored): COGLayer's own inferred
+ *    default pipeline — correct for plain 8-bit RGB/gray COGs, zero config.
+ *  - STYLED: a Float32-aware getTileData/renderTile pair (ported from a
+ *    production consumer): tile pixels upload as r32float / rgba32float
+ *    textures, then FilterNoDataVal (raw values, BEFORE rescale) →
+ *    LinearRescale (min/max → [0,1]) → Colormap (single-band only, sampled
+ *    from the bundled sprite). Restretch/recolor = uniform updates on a new
+ *    layer instance; the tile cache survives because `getTileData` is a
+ *    module-level stable reference.
+ */
+import type { Device } from "@luma.gl/core";
 import { COGLayer } from "@developmentseed/deck.gl-geotiff";
 import { type OmTileData, type RasterStyle } from "./raster-pipeline";
-/** COGLayer styling scalars (rescale window, colormap, nodata). Shared with the Zarr layer; re-exported for consumer wrappers. */
+import { type RasterIdentifyResult } from "./raster-identify";
+/** COGLayer styling scalars (rescale window, colormap, nodata, bands). Shared with the Zarr layer; re-exported for consumer wrappers. */
 export type OmCOGLayerExtraProps = RasterStyle;
+export declare const omGetTileData: (image: Parameters<NonNullable<ConstructorParameters<typeof COGLayer>[0]["getTileData"]>>[0], { device, x, y, signal, pool, dropDecode, }: {
+    device: Device;
+    x: number;
+    y: number;
+    signal?: AbortSignal;
+    pool: never;
+    /** identify="off": upload the selected bands eagerly and release the CPU decode (the memory-relief contract) — a later bands change refetches instead of re-uploading. The raw `bands` grammar value, resolved here against the tile's own band count. */
+    dropDecode?: {
+        bands: number | number[] | null | undefined;
+    };
+}) => Promise<OmTileData>;
+/** TIFF SampleFormat → readable dtype for the dev notice. */
+export declare function dtypeName(tags: {
+    bitsPerSample?: ArrayLike<number>;
+    sampleFormat?: ArrayLike<number>;
+}): string;
+export declare function isUint8(tags: {
+    bitsPerSample?: ArrayLike<number>;
+    sampleFormat?: ArrayLike<number>;
+}): boolean;
+export type AutoWindow = {
+    min: number | [number, number, number];
+    max: number | [number, number, number];
+    source: "stats" | "overview";
+};
+/** Deterministic path: per-band GDAL STATISTICS tags from the header — no pixel pass. Null when any selected band lacks them. */
+export declare function statsWindow(gdalMetadata: unknown, bands: number[]): AutoWindow | null;
+/** Fallback: one small read of the coarsest overview's first tile — data-derived, so the notice warns harder. */
+export declare function overviewWindow(image: {
+    fetchTile(x: number, y: number, opts: object): Promise<{
+        array: import("./raster-pipeline").RasterArrayLike & {
+            nodata?: number | null;
+        };
+    }>;
+}, bands: number[], pool: unknown): Promise<AutoWindow | null>;
+/**
+ * Palette legend (COG v2 phase 5, the gl#1014 ask): a paletted GeoTIFF
+ * renders through its embedded color table upstream — this derives legend
+ * CLASS rows from it when the number of DISTINCT indices actually used
+ * (sampled from the coarsest overview tile) is small. Beyond the cap the
+ * legend widget's single-swatch fallback stands; TIFF palettes carry no
+ * class names, so labels are the palette indices.
+ */
+export declare const PALETTE_LEGEND_MAX_CLASSES = 12;
+export declare function paletteLegendEntries(colorMap: ArrayLike<number>, arr: import("./raster-pipeline").RasterArrayLike): {
+    color: string;
+    label: string;
+}[] | null;
 type AnyProps = Record<string, unknown>;
 declare const OmCOGLayer_base: new (...props: AnyProps[]) => InstanceType<typeof COGLayer>;
 /**
@@ -16,7 +88,69 @@ export declare class OmCOGLayer extends OmCOGLayer_base {
         rescaleMax: null;
         colormap: null;
         nodataOverride: null;
+        bands: null;
+        stretch: null;
+        gamma: null;
+        reverse: null;
     };
     constructor(props: AnyProps);
+    /**
+     * Upstream's `_parseGeoTIFF` EAGERLY infers a render pipeline at its tail
+     * and HARD-THROWS for int/float sources ("Inferring render pipeline for
+     * non-unsigned integers not yet supported") — before `state.geotiff` ever
+     * lands, which would kill the exact auto-route that exists to serve those
+     * sources. Conditional retry: the normal run stays untouched (uint8 infers
+     * fine, one header fetch); on the inference throw only, re-run with a
+     * props OVERLAY (prototype chain — the real props object is never mutated)
+     * whose callback pair suppresses the infer, so state.geotiff lands and the
+     * resolvers below route the source through the styled pipeline. The retry
+     * costs one extra header fetch, paid only by sources that were a dead
+     * layer before this existed.
+     */
+    /** Structured runtime errors (phase 6) through the injected onRasterError → core.onRuntimeError channel — the layer stays mounted, the map stays alive. */
+    private omReportError;
+    _parseGeoTIFF(): Promise<void>;
+    private omRetryWithoutInference;
+    private omExtra;
+    private omAuthoredStyled;
+    private omGeotiff;
+    /**
+     * The bit-depth auto-route (the "my COG is blank" fix): a non-8-bit
+     * source with NO styling attrs enters the styled pipeline anyway, with a
+     * window from the header. Paletted sources (ColorMap tag) never route —
+     * upstream renders the palette.
+     */
+    private omAutoWanted;
+    /** Resolved auto window, kicking off the one-shot overview sample when stats are absent. Undefined while pending/unavailable. */
+    private omAutoWindow;
+    /** Feeds the resolved window to the consumer (legend derivation) via the injected onAutoWindow deck prop — the onTilesetLoad compose precedent. */
+    private omPublishWindow;
+    private omStyledActive;
+    /** Authored style + auto window filling any unauthored window end. */
+    private omEffectiveStyle;
+    /**
+     * Pixel identify (COG v2 phase 4): lngLat → source CRS (the descriptor's
+     * own projector) → full-res pixel (geotiff.index) → the FINEST currently-
+     * loaded tile containing it → all bands sampled from the retained decode.
+     * No fetch, no GPU readback; null when the point is outside the image or
+     * no covering tile is resident.
+     */
+    identify(lngLat: [number, number]): RasterIdentifyResult | null;
+    updateState(params: Parameters<InstanceType<typeof COGLayer>["updateState"]>[0]): void;
+    /** One-shot palette legend derivation per opened file (phase 5). */
+    private omMaybePaletteLegend;
+    finalizeState(context: Parameters<InstanceType<typeof COGLayer>["finalizeState"]>[0]): void;
+    _getTileDataCallback(): any;
+    _renderTileCallback(): any;
+    /**
+     * identify="off" bakes the selection into fetch-time textures, so a bands
+     * change — or flipping identify back on, which must repopulate the
+     * retained arrays — has to REFETCH. Surfaced as the inner TileLayer's own
+     * `getTileData` update trigger by cloning what upstream renders (it
+     * passes no such trigger through, and `_renderTileLayer` is TS-private).
+     * Retained mode pins a constant, keeping the v2 contract: refetch keyed
+     * on the tileset descriptor alone, never on styling.
+     */
+    renderLayers(): any;
 }
 export type { OmTileData };