maplibre-gl-raster 0.1.0

package/dist/types/index.d.ts

@@ -0,0 +1,649 @@
+import { default as colormapsPngUrl } from '@developmentseed/deck.gl-raster/gpu-modules/colormaps.png';
+import { GeoTIFF } from '@developmentseed/geotiff';
+import { IControl } from 'maplibre-gl';
+import { Map as Map_2 } from 'maplibre-gl';
+
+/**
+ * Options for {@link AddRasterOptions} consumers (RasterControl.addRaster).
+ */
+export declare interface AddRasterOptions {
+    /** Layer id; auto-generated when omitted. */
+    id?: string;
+    /** Display name; derived from the URL / file name when omitted. */
+    name?: string;
+    /** Initial visualization state overrides (mode/bands default from the
+     * loaded band count). */
+    state?: Partial<RasterLayerState>;
+    /** Fit the map to the raster's bounds once loaded. @default true */
+    zoomTo?: boolean;
+    /** Id of an existing map style layer to insert the raster beneath (e.g. a
+     * symbol layer so labels stay readable). Drawn on top when omitted or when
+     * the layer does not exist. */
+    beforeId?: string;
+}
+
+export declare type AutoStats = {
+    /** 1-indexed band → stats map. Null when stats are unknown. */
+    perBand: Map<number, BandStats> | null;
+    /** A reasonable global stats block to fall back on (averaged min/max,
+     * summed histogram bins). */
+    global: BandStats | null;
+};
+
+export declare type BandStats = {
+    min: number;
+    max: number;
+    /** Bin counts evenly distributed over [min, max]. Length = HISTOGRAM_BINS. */
+    histogram: number[];
+};
+
+export declare type BandSummary = {
+    /** 1-based band index. */
+    index: number;
+    /** Human label from `<Item name="DESCRIPTION" sample="N-1">…</Item>` or
+     * the `BAND_NAME` alias. */
+    name: string | null;
+    /** GDAL scale; defaults to 1. */
+    scale: number;
+    /** GDAL offset; defaults to 0. */
+    offset: number;
+    /** Per-band nodata (currently always the dataset-level value — TIFF
+     * doesn't carry per-band nodata in the common path). */
+    nodata: number | null;
+    /** Author-supplied min/max/mean/std/validPercent from `STATISTICS_*` items. */
+    stats: {
+        min: number | null;
+        max: number | null;
+        mean: number | null;
+        std: number | null;
+        validPercent: number | null;
+    } | null;
+};
+
+/**
+ * Clamps a value between a minimum and maximum.
+ *
+ * @param value - The value to clamp
+ * @param min - The minimum allowed value
+ * @param max - The maximum allowed value
+ * @returns The clamped value
+ *
+ * @example
+ * ```typescript
+ * clamp(5, 0, 10);  // returns 5
+ * clamp(-5, 0, 10); // returns 0
+ * clamp(15, 0, 10); // returns 10
+ * ```
+ */
+export declare function clamp(value: number, min: number, max: number): number;
+
+/**
+ * Creates a CSS class string from an object of class names.
+ *
+ * @param classes - Object with class names as keys and boolean values
+ * @returns A space-separated string of class names
+ *
+ * @example
+ * ```typescript
+ * classNames({ active: true, disabled: false, visible: true });
+ * // returns "active visible"
+ * ```
+ */
+export declare function classNames(classes: Record<string, boolean>): string;
+
+/** Alphabetical list of the named colormaps shipped in the sprite. */
+export declare const COLORMAP_NAMES: string[];
+
+/** Picker-ready options: name, display label, and the sprite row to
+ * preview. */
+export declare const COLORMAP_OPTIONS: ColormapOption[];
+
+/** Number of rows in the colormap sprite. */
+export declare const COLORMAP_ROW_COUNT: number;
+
+export declare type ColormapOption = {
+    name: string;
+    label: string;
+    rowIndex: number;
+    reversed?: boolean;
+};
+
+export { colormapsPngUrl }
+
+/** Compute auto-stats for a GeoTIFF. Prefers author-supplied min/max
+ * from GDAL_METADATA when present (cheap, exact, anchors the rescale
+ * window to whatever the author intended) and uses sampled tiles to
+ * populate the histogram bins around that range. Without GDAL stats,
+ * derives min/max from the same samples in a two-pass scan. Falls back
+ * to GDAL min/max with empty histograms only if sampling fails entirely.
+ *
+ * When `onProgress` is supplied AND GDAL priors are present, the
+ * histogram fills in tile-by-tile and `onProgress` fires with a partial
+ * AutoStats snapshot after each tile is binned. Without priors, the
+ * callback never fires (bin edges aren't stable until both passes
+ * finish); the caller still receives the final stats via the resolved
+ * Promise. Caller guards against stale results. */
+export declare function computeAutoStats(tiff: GeoTIFF, signal: AbortSignal, onProgress?: (partial: AutoStats) => void): Promise<AutoStats>;
+
+export declare type CrsSummary = {
+    /** EPSG code when the COG declares one; null for user-defined CRSes. */
+    code: number | null;
+    /** Display label: `"EPSG:3857"` or `"User-defined: <name>"`. */
+    label: string;
+    /** `GTCitationGeoKey` or projected / geodetic citation, when present. */
+    citation: string | null;
+    /** Geographic-or-projected bbox `[minX, minY, maxX, maxY]` in the CRS. */
+    bbox: [number, number, number, number];
+    /** `ModelPixelScale` `[scaleX, scaleY]` when present. */
+    pixelScale: [number, number] | null;
+};
+
+/**
+ * Debounces a function call.
+ *
+ * @param fn - The function to debounce
+ * @param delay - The delay in milliseconds
+ * @returns A debounced version of the function
+ *
+ * @example
+ * ```typescript
+ * const debouncedUpdate = debounce(() => updateMap(), 100);
+ * window.addEventListener('resize', debouncedUpdate);
+ * ```
+ */
+export declare function debounce<T extends (...args: unknown[]) => void>(fn: T, delay: number): (...args: Parameters<T>) => void;
+
+/**
+ * Formats a numeric value with appropriate decimal places based on step size.
+ *
+ * @param value - The value to format
+ * @param step - The step size to determine decimal places
+ * @returns The formatted value as a string
+ *
+ * @example
+ * ```typescript
+ * formatNumericValue(5, 1);     // returns "5"
+ * formatNumericValue(0.5, 0.1); // returns "0.5"
+ * formatNumericValue(0.55, 0.01); // returns "0.55"
+ * ```
+ */
+export declare function formatNumericValue(value: number, step: number): string;
+
+/** A single `<Item>` from `<GDALMetadata>`. `sample` is 1-based when present
+ * (GDAL writes 0-based; we normalize). `role` is the optional `role` attribute
+ * (e.g. `"description"`). */
+export declare type GdalItem = {
+    name: string;
+    value: string;
+    sample: number | null;
+    role: string | null;
+};
+
+/**
+ * Generates a unique ID string.
+ *
+ * @param prefix - Optional prefix for the ID
+ * @returns A unique ID string
+ *
+ * @example
+ * ```typescript
+ * generateId('control'); // returns "control-abc123"
+ * generateId();          // returns "abc123"
+ * ```
+ */
+export declare function generateId(prefix?: string): string;
+
+export declare type ImageSummary = {
+    width: number;
+    height: number;
+    bandCount: number;
+    dtype: string;
+    photometric: string;
+    compression: string;
+    predictor: string | null;
+    planarConfig: string;
+    tileWidth: number;
+    tileHeight: number;
+    nodata: number | null;
+};
+
+/**
+ * Open a GeoTIFF from a URL (http(s) or blob:). Equivalent to
+ * `GeoTIFF.fromUrl(url)` plus the CORS workaround above. Dedupes concurrent
+ * requests for the same URL so double-invoked effects don't kick off two
+ * parallel reads; entries are dropped once settled so the map stays bounded.
+ */
+export declare function loadGeoTIFF(url: string): Promise<GeoTIFF>;
+
+/** Upper bound on tiles read from the coarsest IFD during auto-stats. For
+ * properly-pyramided COGs the coarsest level is just a few tiles and the
+ * cap never trips. For COGs without a deep overview pyramid (so the
+ * coarsest is the primary at full size), the cap keeps layer-load from
+ * trying to download the entire image. */
+export declare const MAX_SAMPLE_TILES = 64;
+
+/** Structural subset of `GeoTIFF` we read from. Lets tests construct stubs
+ * without instantiating the whole class. The real `GeoTIFF` satisfies this. */
+declare type MetadataInput = Pick<GeoTIFF, 'image' | 'width' | 'height' | 'count' | 'tileWidth' | 'tileHeight' | 'nodata' | 'crs' | 'bbox' | 'cachedTags' | 'gkd' | 'offsets' | 'scales' | 'storedStats' | 'overviews'>;
+
+export declare type MetadataSummary = {
+    image: ImageSummary;
+    crs: CrsSummary;
+    overviews: OverviewSummary[];
+    bands: BandSummary[];
+    /** GDAL `<Item>` entries that aren't already shown under Bands
+     * (i.e. excludes `STATISTICS_*`, `DESCRIPTION`, `BAND_NAME`).
+     * Dataset-level items first, then per-band, in document order. */
+    gdalItems: GdalItem[];
+    rawGdalXml: string | null;
+};
+
+export declare type OverviewSummary = {
+    width: number;
+    height: number;
+    tileWidth: number;
+    tileHeight: number;
+    tileCount: {
+        x: number;
+        y: number;
+    };
+};
+
+/** Sentinel colormap name for the image's embedded color table. */
+export declare const PALETTE_COLORMAP = "palette";
+
+/**
+ * Linear-interpolated percentile from a histogram. `p` is in [0, 1]. Used
+ * to derive default rescale ranges (typically [0.02, 0.98]) without storing
+ * raw samples.
+ */
+export declare function percentileFromHistogram(stats: BandStats, p: number): number;
+
+/**
+ * A MapLibre GL control for visualizing local and remote raster datasets
+ * (GeoTIFF / Cloud Optimized GeoTIFF). A collapsible button expands into a
+ * panel with an "Add data" section (URL or local file), a layer list, and
+ * per-layer rendering settings (bands, rescale histograms, colormaps,
+ * nodata, stretch, gamma, opacity). Rendering uses a deck.gl COGLayer
+ * pipeline on a shared MapboxOverlay.
+ *
+ * @example
+ * ```typescript
+ * const control = new RasterControl({ collapsed: false });
+ * map.addControl(control, 'top-right');
+ * await control.addRaster('https://example.com/data/cog.tif');
+ * ```
+ */
+export declare class RasterControl implements IControl {
+    private _map?;
+    private _mapContainer?;
+    private _container?;
+    private _panel?;
+    private _options;
+    private _state;
+    private _eventHandlers;
+    private _layerManager?;
+    private _panelUI?;
+    private _onReady;
+    private _resizeHandler;
+    private _mapResizeHandler;
+    private _clickOutsideHandler;
+    /**
+     * Creates a new RasterControl instance.
+     *
+     * @param options - Configuration options for the control
+     */
+    constructor(options?: Partial<RasterControlOptions>);
+    /**
+     * Called when the control is added to the map.
+     * Implements the IControl interface.
+     *
+     * @param map - The MapLibre GL map instance
+     * @returns The control's container element
+     */
+    onAdd(map: Map_2): HTMLElement;
+    /**
+     * Called when the control is removed from the map.
+     * Implements the IControl interface.
+     */
+    onRemove(): void;
+    /**
+     * Gets the current state of the control.
+     *
+     * @returns The current plugin state
+     */
+    getState(): RasterControlState;
+    /**
+     * Updates the control state.
+     *
+     * @param newState - Partial state to merge with current state
+     */
+    setState(newState: Partial<RasterControlState>): void;
+    /**
+     * Toggles the collapsed state of the control panel.
+     */
+    toggle(): void;
+    /**
+     * Expands the control panel.
+     */
+    expand(): void;
+    /**
+     * Collapses the control panel.
+     */
+    collapse(): void;
+    /**
+     * Registers an event handler.
+     *
+     * @param event - The event type to listen for
+     * @param handler - The callback function
+     */
+    on(event: RasterControlEvent, handler: RasterControlEventHandler): void;
+    /**
+     * Removes an event handler.
+     *
+     * @param event - The event type
+     * @param handler - The callback function to remove
+     */
+    off(event: RasterControlEvent, handler: RasterControlEventHandler): void;
+    /**
+     * Gets the map instance.
+     *
+     * @returns The MapLibre GL map instance or undefined if not added to a map
+     */
+    getMap(): Map_2 | undefined;
+    /**
+     * Gets the control container element.
+     *
+     * @returns The container element or undefined if not added to a map
+     */
+    getContainer(): HTMLElement | undefined;
+    /**
+     * Adds a raster layer from a remote COG URL or a local GeoTIFF File.
+     *
+     * The returned promise resolves with the layer id once the GeoTIFF header
+     * loads (waiting for the control to be added to a map first, if needed)
+     * and rejects when loading fails.
+     *
+     * @param source - COG URL or a local GeoTIFF File
+     * @param options - Id/name/state overrides and zoom behavior
+     * @returns The new layer's id
+     */
+    addRaster(source: string | File, options?: AddRasterOptions): Promise<string>;
+    /**
+     * Removes a raster layer.
+     *
+     * @param id - The layer id
+     */
+    removeRaster(id: string): void;
+    /**
+     * Gets a snapshot of one raster layer.
+     *
+     * @param id - The layer id
+     * @returns Layer info, or undefined when unknown
+     */
+    getRaster(id: string): RasterLayerInfo | undefined;
+    /**
+     * Gets snapshots of all raster layers in draw order (first = bottom).
+     *
+     * @returns Layer info array
+     */
+    getRasters(): RasterLayerInfo[];
+    /**
+     * Merges a partial visualization state into a layer (bands, rescale,
+     * colormap, nodata, opacity, gamma, stretch, visible).
+     *
+     * @param id - The layer id
+     * @param patch - State fields to update
+     */
+    setRasterState(id: string, patch: Partial<RasterLayerState>): void;
+    /**
+     * Shows or hides a raster layer.
+     *
+     * @param id - The layer id
+     * @param visible - Whether the layer should render
+     */
+    setVisible(id: string, visible: boolean): void;
+    /**
+     * Selects the layer whose settings the panel edits.
+     *
+     * @param id - The layer id, or null to clear the selection
+     */
+    selectRaster(id: string | null): void;
+    /**
+     * Fits the map view to a layer's bounds.
+     *
+     * @param id - The layer id
+     */
+    zoomToRaster(id: string): void;
+    /**
+     * Moves a layer to a new position in the draw order.
+     *
+     * @param id - The layer id
+     * @param toIndex - Target index (0 = bottom)
+     */
+    reorderRaster(id: string, toIndex: number): void;
+    /** Re-emits LayerManager events through the control's event system. */
+    private _forwardLayerManagerEvents;
+    /**
+     * Emits an event to all registered handlers.
+     *
+     * @param event - The event type to emit
+     * @param extra - Optional layerId/error payload for raster events
+     */
+    private _emit;
+    /**
+     * Creates the main container element for the control.
+     * Contains a toggle button (29x29) matching navigation control size.
+     *
+     * @returns The container element
+     */
+    private _createContainer;
+    /**
+     * Creates the panel element with header and content areas.
+     * Panel is positioned as a dropdown below the toggle button.
+     *
+     * @returns The panel element
+     */
+    private _createPanel;
+    /**
+     * Setup event listeners for panel positioning and click-outside behavior.
+     */
+    private _setupEventListeners;
+    /**
+     * Detect which corner the control is positioned in.
+     *
+     * @returns The position: 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right'
+     */
+    private _getControlPosition;
+    /**
+     * Update the panel position based on button location and control corner.
+     * Positions the panel next to the button, expanding in the appropriate direction.
+     */
+    private _updatePanelPosition;
+}
+
+/**
+ * Event types emitted by the raster control
+ */
+export declare type RasterControlEvent = 'collapse' | 'expand' | 'statechange' | 'rasteradd' | 'rasterremove' | 'rasterchange' | 'rasterselect' | 'error';
+
+/**
+ * Event payload passed to registered handlers.
+ */
+export declare interface RasterControlEventData {
+    type: RasterControlEvent;
+    state: RasterControlState;
+    /** Affected layer id for raster* events. */
+    layerId?: string;
+    /** Error detail for 'error' events. */
+    error?: Error;
+}
+
+/**
+ * Event handler function type
+ */
+export declare type RasterControlEventHandler = (event: RasterControlEventData) => void;
+
+/**
+ * Options for configuring the RasterControl
+ */
+export declare interface RasterControlOptions {
+    /**
+     * Whether the control panel should start collapsed (showing only the toggle button)
+     * @default true
+     */
+    collapsed?: boolean;
+    /**
+     * Position of the control on the map
+     * @default 'top-right'
+     */
+    position?: 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right';
+    /**
+     * Title displayed in the control header
+     * @default 'Raster'
+     */
+    title?: string;
+    /**
+     * Width of the control panel in pixels
+     * @default 360
+     */
+    panelWidth?: number;
+    /**
+     * Custom CSS class name for the control container
+     */
+    className?: string;
+    /**
+     * Render the deck.gl overlay interleaved with the basemap's layers.
+     * @default true
+     */
+    interleaved?: boolean;
+    /**
+     * Prefills the "Add data" URL input with this COG URL. The raster is only
+     * loaded automatically when {@link autoLoad} is true; otherwise the user
+     * still clicks Load.
+     * @default ''
+     */
+    defaultUrl?: string;
+    /**
+     * When true and {@link defaultUrl} is set, the raster is loaded as soon as
+     * the control is added to the map (instead of prefilling the URL input).
+     * @default false
+     */
+    autoLoad?: boolean;
+}
+
+/**
+ * Internal state of the plugin control
+ */
+export declare interface RasterControlState {
+    /**
+     * Whether the control panel is currently collapsed
+     */
+    collapsed: boolean;
+    /**
+     * Current panel width in pixels
+     */
+    panelWidth: number;
+    /**
+     * Any custom state data
+     */
+    data?: Record<string, unknown>;
+}
+
+/**
+ * Public, read-only snapshot of a raster layer.
+ */
+export declare interface RasterLayerInfo {
+    /** Stable layer id. */
+    id: string;
+    /** Display name shown in the layer list. */
+    name: string;
+    /** Data source. */
+    source: RasterLayerSource;
+    /** Band count, known once the GeoTIFF header loads. */
+    bandCount: number | null;
+    /** 1-indexed band names parsed from GDAL_METADATA, when present. */
+    bandNames: globalThis.Map<number, string> | null;
+    /** Map style layer id the raster is inserted beneath, when set. */
+    beforeId: string | null;
+    /** Current visualization state. */
+    state: RasterLayerState;
+}
+
+/** Where a raster layer's data came from. */
+export declare type RasterLayerSource = {
+    kind: 'url';
+    url: string;
+} | {
+    kind: 'file';
+    fileName: string;
+    objectUrl: string;
+};
+
+/**
+ * Per-layer visualization state.
+ */
+export declare interface RasterLayerState {
+    /** Rendering mode. */
+    mode: RasterMode;
+    /** 1-indexed band selection: [r, g, b] in RGB mode, [band] in single mode. */
+    bands: number[];
+    /** Per-channel [min, max] rescale windows; null = auto (2-98% percentile
+     * from computed stats). */
+    rescale: [number, number][] | null;
+    /** Colormap name (single-band mode only). 'palette' uses the image's
+     * embedded color table; defaults to 'gray'. */
+    colormap: string;
+    /** Nodata handling. */
+    nodata: RasterNodata;
+    /** Layer transparency, 0 (invisible) to 1 (fully opaque). */
+    opacity: number;
+    /** Power-law gamma correction (1.0 = off). */
+    gamma: number;
+    /** Curve applied to rescaled values. */
+    stretch: RasterStretch;
+    /** Whether the layer is drawn on the map. */
+    visible: boolean;
+}
+
+/** Rendering mode: RGB composite (one band per channel) or single band
+ * through a colormap. */
+export declare type RasterMode = 'rgb' | 'single';
+
+/** Nodata handling: 'auto' reads the value declared by the COG (and treats
+ * NaN as nodata for float data), a number overrides it in source units, and
+ * 'off' renders every pixel. */
+export declare type RasterNodata = number | 'off' | 'auto';
+
+/** Curve applied to the rescaled [0, 1] value before gamma / colormap.
+ * "log" expands the low-value range (useful for skewed data with most
+ * variation near zero); "sqrt" is a gentler version. */
+export declare type RasterStretch = 'linear' | 'log' | 'sqrt';
+
+/**
+ * Parse band descriptions from the GDAL_METADATA XML tag. Looks for
+ * `<Item name="DESCRIPTION" sample="N">name</Item>` (and a few common
+ * aliases) and returns a 1-indexed band → name map. The geotiff package
+ * surfaces statistics from this XML but not descriptions, so we re-parse.
+ */
+export declare function readBandNames(tiff: GeoTIFF): Map<number, string> | null;
+
+/** Pure derivation from an already-loaded GeoTIFF: no fetches, no I/O. */
+export declare function summarizeGeoTIFF(tiff: MetadataInput): MetadataSummary;
+
+/**
+ * Throttles a function call.
+ *
+ * @param fn - The function to throttle
+ * @param limit - The minimum time between calls in milliseconds
+ * @returns A throttled version of the function
+ *
+ * @example
+ * ```typescript
+ * const throttledScroll = throttle(() => handleScroll(), 100);
+ * window.addEventListener('scroll', throttledScroll);
+ * ```
+ */
+export declare function throttle<T extends (...args: unknown[]) => void>(fn: T, limit: number): (...args: Parameters<T>) => void;
+
+export { }