@walkthru-earth/objex 1.0.0 → 1.2.0

package/dist/utils/cog.d.ts

@@ -0,0 +1,244 @@
+import type { GetTileDataOptions, MinimalDataT } from '@developmentseed/deck.gl-geotiff';
+import type { 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 maplibregl from 'maplibre-gl';
+/** SampleFormat tag value → human label. */
+export declare const SF_LABELS: Record<number, string>;
+export type ColorRampId = 'grayscale' | 'terrain' | 'viridis' | 'magma' | 'turbo' | 'spectral';
+export declare const COLOR_RAMP_STOPS: Record<ColorRampId, [number, number, number][]>;
+/** Interpolate a normalized value (0..1) into an RGB color from a ramp. */
+export declare function interpolateRamp(stops: [number, number, number][], t: number): [number, number, number];
+/** Generate a CSS linear-gradient string for a color ramp. */
+export declare function rampToGradientCss(id: ColorRampId): string;
+export interface BandConfig {
+    mode: 'rgb' | 'single';
+    /** 0-indexed band indices for RGB channels */
+    rBand: number;
+    gBand: number;
+    bBand: number;
+    /** 0-indexed band index for single-band mode */
+    band: number;
+    colorRamp: ColorRampId;
+}
+/** Create a sensible default band config based on COG metadata. */
+export declare function defaultBandConfig(bandCount: number, sampleFormat: number): BandConfig;
+/** Check if the config matches the default for this COG (no user changes). */
+export declare function isDefaultBandConfig(config: BandConfig, bandCount: number, sampleFormat: number): boolean;
+export interface CogTagInfo {
+    /** TIFF SampleFormat[0] value. 1=uint, 2=int, 3=float. Defaults to 1 when absent. */
+    sampleFormat: number;
+    /** True when SampleFormat[0] === 1 (unsigned integer). */
+    isUint: boolean;
+    /**
+     * True when Photometric === 3 (Palette) and the ColorMap tag is present.
+     * These COGs should defer to the library's default Colormap GPU module,
+     * not our custom JS pipeline, so the embedded palette renders correctly.
+     */
+    isPaletteIndexed: boolean;
+}
+/**
+ * Inspect the TIFF tags that drive pipeline selection. Centralizes the
+ * Photometric.Palette === 3 magic number and the SampleFormat fallback in one
+ * place so viewers don't reimplement raw tag reads. Photometric values come
+ * from the @cogeotiff/core Photometric enum.
+ */
+export declare function inspectCogTags(geotiff: GeoTIFFType): CogTagInfo;
+/**
+ * Check if a given band config requires a custom pipeline (vs library default).
+ * Library default only works for uint with standard RGB band order, or for
+ * palette-indexed uint COGs where the embedded ColorMap tag auto-renders.
+ */
+export declare function needsCustomPipelineForConfig(geotiff: GeoTIFFType, config: BandConfig): boolean;
+/**
+ * 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
+ * no-op and the library-default pipeline is used as-is.
+ */
+export interface RescaleConfig {
+    min: number;
+    max: number;
+}
+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;
+/**
+ * Build a `getTileData` + `renderTile` pair that reuses the library-default
+ * uint pipeline (via `inferRenderPipeline`) and appends `LinearRescale` to the
+ * returned render pipeline. Only safe to use when the default pipeline would
+ * have been chosen anyway, i.e. `needsCustomPipelineForConfig(geotiff, cfg)`
+ * is false. For non-uint or custom band configs the custom JS pipeline already
+ * bakes RGBA in CPU and a GPU rescale would be cosmetic.
+ *
+ * `inferRenderPipeline` needs the GPU `Device` which arrives in the first
+ * 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;
+};
+/**
+ * Apply the two upstream-bug workarounds a GeoTIFF needs before being handed
+ * to `COGLayer`:
+ * 1. Strip oversized overviews (image smaller than tile size). These produce
+ *    out-of-domain proj4 NaN during pre-flight reprojection.
+ * 2. Clamp EPSG:4326 bbox to Web Mercator's safe range. Global 4326 COGs with
+ *    ±90° extents crash the tile matrix generator.
+ *
+ * Mutates the GeoTIFF in place. Safe to call repeatedly. Kept out of the
+ * Svelte component so MultiCOG/Mosaic can apply the same fix per sub-COG.
+ */
+export declare function normalizeCogGeotiff(geotiff: GeoTIFFType): void;
+/**
+ * Resolved COGLayer data props. Empty object means "library default pipeline".
+ * 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`).
+ * Typing this as `Record<string, any>` matches the `customProps` pattern
+ * already used at the COGLayer boundary and keeps the dispatch site simple.
+ */
+export type ResolvedCogPipeline = Record<string, any>;
+export interface SelectCogPipelineOptions {
+    /** Active band/color config, or null/undefined when not yet resolved. */
+    bandConfig?: BandConfig | null;
+    /** Linear rescale GPU module values. No-op when omitted or at defaults. */
+    rescale?: RescaleConfig;
+}
+/**
+ * Decide which getTileData/renderTile pair COGLayer should use for a GeoTIFF.
+ * Four outcomes, in priority order:
+ *
+ * 1. Custom configurable (band swap, color ramp) — when bandConfig is active
+ *    and needsCustomPipelineForConfig is true (non-uint, mode=single, or
+ *    non-standard RGB band order).
+ * 2. Custom non-uint (Int/Float source) — when no bandConfig yet but the
+ *    GeoTIFF itself forces custom handling.
+ * 3. Library default + LinearRescale — uint path is fine AND the user moved
+ *    the rescale slider away from defaults.
+ * 4. Library default — returns `{}`, caller spreads into COGLayer props.
+ *
+ * Pure dispatch. Kept separate from the Svelte component so MultiCOG/Mosaic
+ * 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).
+ */
+export declare function getMaxTextureSize(map: maplibregl.Map): number;
+/**
+ * Fit the map to COG bounds with responsive padding.
+ * Uses smaller padding on mobile to zoom in closer, ensuring overviews load
+ * properly instead of appearing black at very low zoom levels.
+ * After fitting, bumps zoom +2 when the viewport settles at a very low level.
+ */
+export declare function fitCogBounds(map: maplibregl.Map, b: GeoBounds): void;
+/** Remove the native bitmap source/layer from the map (idempotent). */
+export declare function cleanupNativeBitmap(map: maplibregl.Map): void;
+/**
+ * Render a non-tiled GeoTIFF as a MapLibre native image source (bitmap).
+ * Opens the file with @developmentseed/geotiff, reads band 0, normalizes
+ * to grayscale RGBA, and adds to the map as a raster layer.
+ *
+ * Returns CogInfo for the metadata panel.
+ */
+export declare function renderNonTiledBitmap(options: {
+    url: string;
+    map: maplibregl.Map;
+    signal: AbortSignal;
+    geotiff?: GeoTIFF;
+}): Promise<CogInfo>;
+/** Result type returned by our custom getTileData. */
+export interface CustomTileData {
+    imageData: ImageData;
+    width: number;
+    height: number;
+}
+/**
+ * Check whether a GeoTIFF needs a custom render pipeline.
+ * v0.3's inferRenderPipeline only supports unsigned integers (SampleFormat 1).
+ * Signed int (2) and float (3) need custom getTileData/renderTile.
+ */
+export declare function needsCustomPipeline(geotiff: GeoTIFFType): boolean;
+/**
+ * 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.
+ */
+export declare function createCustomGetTileData(geotiff: GeoTIFFType): (image: GeoTIFFType | Overview, options: {
+    x: number;
+    y: number;
+    pool: unknown;
+    signal?: AbortSignal;
+}) => Promise<CustomTileData>;
+/**
+ * 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.
+ */
+export declare function customRenderTile(data: CustomTileData): {
+    image: ImageData;
+};
+/**
+ * Create a configurable getTileData that respects BandConfig.
+ * Supports both RGB mode (multi-band → R,G,B) and single-band mode (color ramp).
+ */
+export declare function createConfigurableGetTileData(geotiff: GeoTIFFType, config: BandConfig): (image: GeoTIFFType | Overview, options: {
+    x: number;
+    y: number;
+    pool: unknown;
+    signal?: AbortSignal;
+}) => Promise<CustomTileData>;
+export interface PixelValue {
+    lng: number;
+    lat: number;
+    values: number[];
+    row: number;
+    col: number;
+}
+/**
+ * Create an async EPSG resolver for `@developmentseed/deck.gl-geotiff`.
+ * Looks up the numeric EPSG code in the bundled WKT database and returns the
+ * `ProjectionDefinition` produced by `parseWkt`. Throws a clear error when the
+ * code is not present in the database.
+ */
+export declare function createEpsgResolver(): EpsgResolver;
+/**
+ * Resolve a proj4-compatible definition for a CRS read from a GeoTIFF.
+ * For numeric EPSG codes this returns the WKT string from the bundled EPSG
+ * database, which `proj4()` accepts directly. For ProjJSON it falls back to a
+ * JSON string. Returns null for EPSG:4326 (no conversion needed) or when the
+ * code is not present in the database.
+ */
+export declare function resolveProj4Def(crs: number | unknown, _signal: AbortSignal): Promise<string | null>;
+/**
+ * Read pixel values at a given lng/lat from a GeoTIFF.
+ * Converts WGS84 → source CRS → pixel coords, fetches the tile, reads all bands.
+ */
+export declare function readPixelAtLngLat(geotiff: GeoTIFFType, lng: number, lat: number, proj4Def: string | null, pool: any, signal?: AbortSignal): Promise<PixelValue | null>;