@walkthru-earth/objex 1.3.0 → 1.4.0

package/dist/utils/cog.d.ts

@@ -1,13 +1,18 @@
-import type { GetTileDataOptions, MinimalDataT } from '@developmentseed/deck.gl-geotiff';
-import type { RasterModule, RenderTileResult } from '@developmentseed/deck.gl-raster';
+import type { GetTileDataOptions } from '@developmentseed/deck.gl-geotiff';
+import type { MinimalTileData, RasterModule, RenderTileResult } from '@developmentseed/deck.gl-raster';
 import type { GeoTIFF as GeoTIFFType, Overview } from '@developmentseed/geotiff';
 import { GeoTIFF } from '@developmentseed/geotiff';
 import type { EpsgResolver } from '@developmentseed/proj';
 import type { Device } from '@luma.gl/core';
+import { buildDataTypeLabel, type CogInfo, clampBounds, type GeoBounds, SF_LABELS, safeClamp } from '@walkthru-earth/objex-utils';
 import type maplibregl from 'maplibre-gl';
+import { type GdalBandStats, type GdalImageStats, HISTOGRAM_BINS, type HistogramSnapshot, readGdalStats, type StreamHistogramOptions, streamHistogram } from './cog-histogram.js';
 import { type ColormapName } from './colormap-sprite.js';
-/** SampleFormat tag value → human label. */
-export declare const SF_LABELS: Record<number, string>;
+export declare function loadGeoTIFF(href: string, options?: {
+    chunkSize?: number;
+    cacheSize?: number;
+}): Promise<GeoTIFFType>;
+export { buildDataTypeLabel, type CogInfo, clampBounds, type GdalBandStats, type GdalImageStats, type GeoBounds, HISTOGRAM_BINS, type HistogramSnapshot, readGdalStats, SF_LABELS, type StreamHistogramOptions, safeClamp, streamHistogram };
 /**
  * Any of the 107 named ramps shipped in `@developmentseed/deck.gl-raster`'s
  * `colormaps.png` sprite (matplotlib + rio-tiler + cmocean). Rendering is
@@ -54,6 +59,57 @@ export declare function inspectCogTags(geotiff: GeoTIFFType): CogTagInfo;
  * palette-indexed uint COGs where the embedded ColorMap tag auto-renders.
  */
 export declare function needsCustomPipelineForConfig(geotiff: GeoTIFFType, config: BandConfig): boolean;
+/**
+ * User-controlled tri-state for nodata handling.
+ *
+ * - `auto` — use the value parsed from the GeoTIFF's GDAL_NODATA tag (caller
+ *   resolves via `readGdalNodata(geotiff)`).
+ * - `value` — explicit user-provided sentinel.
+ * - `off` — disable nodata filtering entirely.
+ *
+ * Default is `{ mode: 'auto' }`. The shader-level value is resolved at the
+ * viewer level (Auto pulls from the geotiff, Value uses `value`, Off → null).
+ */
+export type NodataMode = 'auto' | 'value' | 'off';
+export interface NodataConfig {
+    mode: NodataMode;
+    value?: number;
+}
+export declare const DEFAULT_NODATA_CONFIG: NodataConfig;
+/**
+ * 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 declare function readGdalNodata(geotiff: GeoTIFFType): number | null;
+/**
+ * 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`).
+ */
+export declare const FilterNaN: RasterModule["module"];
+/**
+ * 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 declare function nodataModule(nodata: number | null, sampleScale?: number): RasterModule | null;
+/** Resolve a tri-state `NodataConfig` against the auto-detected GDAL_NODATA value. */
+export declare function resolveNodata(cfg: NodataConfig, autoNodata: number | null): number | null;
 /**
  * Min/max rescale values applied via the `LinearRescale` shader module. Values
  * are in normalized shader space [0, 1]. Default `{ min: 0, max: 1 }` is a
@@ -66,6 +122,46 @@ export interface RescaleConfig {
 export declare const DEFAULT_RESCALE: RescaleConfig;
 /** True when the rescale values would produce a visible change on the GPU. */
 export declare function isRescaleActive(cfg: RescaleConfig): boolean;
+/**
+ * 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 declare function defaultRescaleForGeotiff(geotiff: GeoTIFFType): RescaleConfig;
+/**
+ * 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 declare function percentileFromHistogram(histogram: Uint32Array | null, p: number): number | null;
+export declare function buildHistogramFromGeotiff(geotiff: GeoTIFFType, signal?: AbortSignal): Promise<Uint32Array | null>;
 /**
  * Build a `getTileData` + `renderTile` pair that reuses the library-default
  * uint pipeline (via `inferRenderPipeline`) and appends `LinearRescale` to the
@@ -78,19 +174,30 @@ export declare function isRescaleActive(cfg: RescaleConfig): boolean;
  * tile's `GetTileDataOptions`, so the pipeline is built lazily on first call.
  */
 export declare function createRescaledPipeline(geotiff: GeoTIFFType, rescale: RescaleConfig): {
-    getTileData: (image: GeoTIFFType | Overview, options: GetTileDataOptions) => Promise<MinimalDataT>;
-    renderTile: (data: MinimalDataT) => RenderTileResult;
+    getTileData: (image: GeoTIFFType | Overview, options: GetTileDataOptions) => Promise<MinimalTileData>;
+    renderTile: (data: MinimalTileData) => RenderTileResult;
 };
 export interface BandRenderPipelineOptions {
-    /** Value treated as "no-data" and zeroed out by `FilterNoDataVal`. */
+    /**
+     * Resolved nodata value. `NaN` routes through `FilterNaN`, finite numbers
+     * through `FilterNoDataVal`, `null` / undefined / non-finite disables the
+     * nodata stage entirely.
+     */
     noDataVal?: number | null;
+    /**
+     * Hardware sample scale used to bring `noDataVal` into the shader's coord
+     * space. Defaults to 1 (raw float). Pass 255 for r8unorm, 65535 for r16unorm.
+     */
+    noDataSampleScale?: number;
     /** Linear rescale applied after no-data masking. Omit for no rescaling. */
     rescale?: RescaleConfig;
 }
 /**
  * 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 declare function buildBandRenderPipeline(opts?: BandRenderPipelineOptions): RasterModule[];
 /**
@@ -110,7 +217,7 @@ export declare function normalizeCogGeotiff(geotiff: GeoTIFFType): void;
  * Spread into `new COGLayer({ ..., ...resolved })` to activate.
  *
  * COGLayer's data-prop types are a discriminated XOR and the four pipelines we
- * dispatch to return different DataT shapes (`CustomTileData`, `MinimalDataT`).
+ * dispatch to return different DataT shapes (`CustomTileData`, `MinimalTileData`).
  * Typing this as `Record<string, any>` matches the `customProps` pattern
  * already used at the COGLayer boundary and keeps the dispatch site simple.
  */
@@ -120,11 +227,6 @@ export interface SelectCogPipelineOptions {
     bandConfig?: BandConfig | null;
     /** Linear rescale GPU module values. No-op when omitted or at defaults. */
     rescale?: RescaleConfig;
-    /**
-     * Forwarded to the CPU bake factories in single-band mode; receives a
-     * 64-bin histogram of normalized data after each tile for slider UI.
-     */
-    onHistogram?: (bins: Uint32Array) => void;
 }
 /**
  * Decide which getTileData/renderTile pair COGLayer should use for a GeoTIFF.
@@ -143,29 +245,6 @@ export interface SelectCogPipelineOptions {
  * viewers can call it per sub-COG without re-implementing the decision tree.
  */
 export declare function selectCogPipeline(geotiff: GeoTIFFType, opts?: SelectCogPipelineOptions): ResolvedCogPipeline;
-export interface GeoBounds {
-    west: number;
-    south: number;
-    east: number;
-    north: number;
-}
-export interface CogInfo {
-    width: number;
-    height: number;
-    bandCount: number;
-    dataType: string;
-    bounds: GeoBounds;
-    downsampled?: boolean;
-}
-/** Safely clamp a number to a range, treating NaN/Infinity as the fallback. */
-export declare function safeClamp(v: number, lo: number, hi: number, fallback: number): number;
-/** Clamp geographic bounds to valid MapLibre web-Mercator range. */
-export declare function clampBounds(b: GeoBounds): GeoBounds;
-/**
- * Build a data-type label from GeoTIFF sample format and bits per sample.
- * e.g. "uint8", "float32", "int16"
- */
-export declare function buildDataTypeLabel(sampleFormat: number, bitsPerSample: number): string;
 /**
  * Query the GPU's MAX_TEXTURE_SIZE from MapLibre's WebGL context.
  * Falls back to 4096 (lowest common denominator for mobile GPUs).
@@ -215,6 +294,16 @@ export interface CustomTileData {
      * lookup. `undefined` for RGB tiles.
      */
     nodataSentinel?: number;
+    /**
+     * Per-tile 64-bin normalized histogram (0..1, nodata excluded) baked during
+     * single-band CPU decoding. `undefined` for RGB tiles. deck.gl's TileLayer
+     * caches the returned tile object, so this array is retained alongside the
+     * bitmap without a rebake on pan/zoom revisits. Summing the histograms of
+     * currently-visible tiles, via the TileLayer `onViewportLoad` hook, gives a
+     * cloud-native "histogram of what COG tiles the viewport currently shows at
+     * the active overview level", matching COG pyramid behavior.
+     */
+    histogram?: Uint32Array;
 }
 type Texture = import('@luma.gl/core').Texture;
 /**
@@ -223,18 +312,27 @@ type Texture = import('@luma.gl/core').Texture;
  * Signed int (2) and float (3) need custom getTileData/renderTile.
  */
 export declare function needsCustomPipeline(geotiff: GeoTIFFType): boolean;
-/** Shared options for the CPU tile-baking factories. */
-export interface CustomGetTileDataOptions {
-    /**
-     * Called after each baked tile with a 64-bin histogram of normalized
-     * single-band values (0..1, nodata excluded). Bins accumulate across
-     * tiles; receivers should treat the array as monotonically growing and
-     * debounce UI updates. Never invoked in RGB mode.
-     */
-    onHistogram?: (bins: Uint32Array) => void;
-}
-/** Number of histogram buckets produced by the CPU bake. */
-export declare const HISTOGRAM_BIN_COUNT = 64;
+/**
+ * Shared options for the CPU tile-baking factories.
+ *
+ * The previous `onHistogram` callback accumulated a single closure-owned buffer
+ * across every tile ever baked, which grew unbounded on pan/zoom and never
+ * reflected "what the viewport currently shows". Histograms are now attached
+ * per tile to `CustomTileData.histogram` and aggregated by the viewer from
+ * TileLayer's `onViewportLoad(visibleTiles)` hook, matching COG overview-level
+ * behavior (few big tiles when zoomed out, small AOI-scoped tiles when zoomed
+ * in) and reusing deck.gl's tile cache for free.
+ */
+export type CustomGetTileDataOptions = Record<string, never>;
+/**
+ * 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 declare const HISTOGRAM_BIN_COUNT: number;
 /**
  * Create custom getTileData for non-uint COGs.
  * Reads band 0, normalizes using GDAL statistics / per-tile adaptive stretch,
@@ -243,7 +341,7 @@ export declare const HISTOGRAM_BIN_COUNT = 64;
  * `colormaps.png`. Reserves `r = 0` for nodata so `FilterNoDataVal` can
  * discard those fragments before the ramp sample.
  */
-export declare function createCustomGetTileData(geotiff: GeoTIFFType, opts?: CustomGetTileDataOptions): (image: GeoTIFFType | Overview, options: {
+export declare function createCustomGetTileData(geotiff: GeoTIFFType, _opts?: CustomGetTileDataOptions): (image: GeoTIFFType | Overview, options: {
     x: number;
     y: number;
     pool: unknown;
@@ -263,19 +361,33 @@ export declare function createCustomGetTileData(geotiff: GeoTIFFType, opts?: Cus
  * fall back to the plain grayscale image.
  */
 export declare function buildCustomRenderTile(config: BandConfig, rescale?: RescaleConfig): (data: CustomTileData) => RenderTileResult;
+/**
+ * Stable getTileData factory tied to a GeoTIFF identity. Returns a wrapper with
+ * a frozen `getTileData` reference and an `updateConfig` mutator. Identity must
+ * stay stable so deck.gl's TileLayer cache (keyed in part by function identity)
+ * is preserved across band/ramp swaps.
+ */
+export interface ConfigurableTileLoader {
+    getTileData: (image: GeoTIFFType | Overview, options: {
+        x: number;
+        y: number;
+        pool: unknown;
+        signal?: AbortSignal;
+        device: Device;
+    }) => Promise<CustomTileData>;
+    updateConfig: (next: BandConfig) => void;
+}
 /**
  * Create a configurable getTileData that respects BandConfig.
  * 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 declare function createConfigurableGetTileData(geotiff: GeoTIFFType, config: BandConfig, opts?: CustomGetTileDataOptions): (image: GeoTIFFType | Overview, options: {
-    x: number;
-    y: number;
-    pool: unknown;
-    signal?: AbortSignal;
-    device: Device;
-}) => Promise<CustomTileData>;
+export declare function createConfigurableGetTileData(geotiff: GeoTIFFType, config: BandConfig, _opts?: CustomGetTileDataOptions): ConfigurableTileLoader;
 export interface PixelValue {
     lng: number;
     lat: number;
@@ -298,9 +410,37 @@ export declare function createEpsgResolver(): EpsgResolver;
  * code is not present in the database.
  */
 export declare function resolveProj4Def(crs: number | unknown, _signal: AbortSignal): Promise<string | null>;
+/**
+ * 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 declare function mapResolutionMetersPerPixel(zoom: number, latitude: number): number;
+/**
+ * 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 declare function selectOverviewForResolution(geotiff: GeoTIFFType, targetMetersPerPixel: number): Overview | null;
 /**
  * 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 declare function readPixelAtLngLat(geotiff: GeoTIFFType, lng: number, lat: number, proj4Def: string | null, pool: any, signal?: AbortSignal): Promise<PixelValue | null>;
-export {};
+export declare function readPixelAtLngLat(geotiff: GeoTIFFType, lng: number, lat: number, proj4Def: string | null, pool: any, signal?: AbortSignal, options?: {
+    overview?: Overview | null;
+}): Promise<PixelValue | null>;