@developmentseed/deck.gl-geotiff 0.5.0-beta.1 → 0.5.0

package/dist/multi-cog-layer.d.ts

@@ -0,0 +1,301 @@
+import type { CompositeLayerProps, Layer, LayersList, UpdateParameters } from "@deck.gl/core";
+import { CompositeLayer } from "@deck.gl/core";
+import type { _Tile2DHeader as Tile2DHeader, TileLayerProps, _TileLoadProps as TileLoadProps } from "@deck.gl/geo-layers";
+import { TileLayer } from "@deck.gl/geo-layers";
+import type { Corners, MultiTilesetDescriptor, RasterModule, UvTransform } from "@developmentseed/deck.gl-raster";
+import type { DecoderPool, GeoTIFF } from "@developmentseed/geotiff";
+import type { TileMatrixSet } from "@developmentseed/morecantile";
+import type { EpsgResolver } from "@developmentseed/proj";
+import { epsgResolver as defaultEpsgResolver } from "@developmentseed/proj";
+import type { ReprojectionFns } from "@developmentseed/raster-reproject";
+import type { Texture } from "@luma.gl/core";
+/** Data returned per band from tile fetching. */
+interface BandTileData {
+    /** GPU texture containing the band's raster data. */
+    texture: Texture;
+    /** UV transform for aligning this band's texture to the primary tile. */
+    uvTransform: UvTransform;
+    /** Width of the texture in pixels. */
+    width: number;
+    /** Height of the texture in pixels. */
+    height: number;
+    /** Byte length of the underlying texture data. */
+    byteLength: number;
+}
+/** Debug metadata for a secondary band, collected during tile fetching. */
+interface BandDebugInfo {
+    /** CRS corners of each secondary tile fetched (for drawing outlines). */
+    secondaryTileCorners: Corners[];
+    /** Secondary zoom level index selected. */
+    secondaryZ: number;
+    /** UV transform applied to this band. */
+    uvTransform: UvTransform;
+    /** Stitched texture width in pixels. */
+    stitchedWidth: number;
+    /** Stitched texture height in pixels. */
+    stitchedHeight: number;
+    /** Number of secondary tiles fetched. */
+    tileCount: number;
+    /** Meters per pixel at the selected secondary level. */
+    metersPerPixel: number;
+}
+/** Debug info for all bands of a single primary tile. */
+interface MultiTileDebugInfo {
+    /** Per-band debug metadata, keyed by source name. Only secondary bands. */
+    bands: Map<string, BandDebugInfo>;
+}
+/** Result of {@link MultiCOGLayer._getTileData} -- all band textures plus reprojection functions. */
+interface MultiTileResult {
+    /** Per-band texture data, keyed by source name. */
+    bands: Map<string, BandTileData>;
+    /** Forward transform from pixel coordinates to CRS coordinates. */
+    forwardTransform: (x: number, y: number) => [number, number];
+    /** Inverse transform from CRS coordinates to pixel coordinates. */
+    inverseTransform: (x: number, y: number) => [number, number];
+    /** Width of the primary tile in pixels. */
+    width: number;
+    /** Height of the primary tile in pixels. */
+    height: number;
+    /** Byte length of all band textures, required for deck.gl TileLayer cache management. */
+    byteLength: number;
+    /** Only present when `debug: true`. */
+    debugInfo?: MultiTileDebugInfo;
+}
+/**
+ * Configuration for a single COG source within a {@link MultiCOGLayer}.
+ */
+export interface MultiCOGSourceConfig {
+    /**
+     * URL or ArrayBuffer of the COG.
+     *
+     * @see {@link fetchGeoTIFF} for supported input types.
+     */
+    url: string | URL | ArrayBuffer;
+}
+/** Internal state for a single opened COG source. */
+interface SourceState {
+    geotiff: GeoTIFF;
+    tms: TileMatrixSet;
+}
+/**
+ * Props accepted by {@link MultiCOGLayer}.
+ *
+ * Extends {@link CompositeLayerProps} with multi-source COG configuration and
+ * optional tile-layer tuning knobs forwarded to the underlying
+ * {@link TileLayerProps | TileLayer}.
+ *
+ * @see {@link MultiCOGLayer}
+ * @see {@link MultiCOGSourceConfig}
+ */
+export type MultiCOGLayerProps = CompositeLayerProps & Pick<TileLayerProps, "debounceTime" | "maxCacheSize" | "maxCacheByteSize" | "maxRequests" | "refinementStrategy"> & {
+    /**
+     * Named sources -- each key becomes a band name used when compositing.
+     *
+     * @see {@link MultiCOGSourceConfig}
+     */
+    sources: Record<string, MultiCOGSourceConfig>;
+    /**
+     * Map source bands to RGB(A) output channels.
+     *
+     * @see {@link buildCompositeBandsProps}
+     */
+    composite?: {
+        r: string;
+        g?: string;
+        b?: string;
+        a?: string;
+    };
+    /**
+     * Post-processing render pipeline modules applied after compositing.
+     *
+     * @see {@link RasterModule}
+     */
+    renderPipeline?: RasterModule[];
+    /**
+     * EPSG code resolver used to look up projection definitions for numeric
+     * CRS codes found in GeoTIFF metadata.
+     *
+     * @default defaultEpsgResolver
+     * @see {@link EpsgResolver}
+     */
+    epsgResolver?: EpsgResolver;
+    /**
+     * Decoder pool for parallel image chunk decompression.
+     *
+     * @see {@link DecoderPool}
+     */
+    pool?: DecoderPool;
+    /**
+     * Maximum reprojection error in pixels for mesh refinement.
+     * Lower values create denser meshes with higher accuracy.
+     *
+     * @default 0.125
+     */
+    maxError?: number;
+    /**
+     * AbortSignal to cancel loading of all sources.
+     */
+    signal?: AbortSignal;
+    /**
+     * Called once all configured sources have been opened and the
+     * {@link MultiTilesetDescriptor} has been built.
+     *
+     * `geographicBounds` is computed from the primary (finest-resolution)
+     * source and reprojected to WGS84; it matches the shape returned by
+     * {@link COGLayerProps.onGeoTIFFLoad} and is suitable for passing to
+     * MapLibre's `fitBounds`.
+     */
+    onGeoTIFFLoad?: (sources: Map<string, GeoTIFF>, options: {
+        primaryKey: string;
+        geographicBounds: {
+            west: number;
+            south: number;
+            east: number;
+            north: number;
+        };
+    }) => void;
+    /**
+     * Enable debug overlay showing tile boundaries and metadata labels
+     * for all tilesets.
+     *
+     * @default false
+     */
+    debug?: boolean;
+    /**
+     * Opacity of the reprojection mesh debug overlay. Only used when
+     * `debug` is `true`. Forwarded to the underlying {@link RasterLayer}.
+     *
+     * @default 0.5
+     */
+    debugOpacity?: number;
+    /**
+     * Controls how much detail is shown in debug text labels.
+     *
+     * - `1`: tile index and resolution only
+     * - `2`: adds UV transform and tile count
+     * - `3`: adds stitched dimensions and meters/pixel
+     *
+     * @default 1
+     */
+    debugLevel?: 1 | 2 | 3;
+};
+/**
+ * A deck.gl {@link CompositeLayer} that opens multiple Cloud-Optimized GeoTIFFs
+ * (COGs) in parallel, builds a {@link TilesetDescriptor} for each, and groups
+ * them into a single {@link MultiTilesetDescriptor}.
+ *
+ * The finest-resolution source is automatically selected as the primary
+ * tileset, which drives the tile grid. Secondary sources are sampled at the
+ * closest matching resolution.
+ *
+ * @see {@link MultiCOGLayerProps} for accepted props.
+ * @see {@link createMultiTilesetDescriptor} for the grouping logic.
+ * @see {@link TileMatrixSetAdaptor} for the per-source tileset adapter.
+ */
+export declare class MultiCOGLayer extends CompositeLayer<MultiCOGLayerProps> {
+    static layerName: string;
+    static defaultProps: {
+        epsgResolver: {
+            type: "accessor";
+            value: typeof defaultEpsgResolver;
+        };
+        maxError: {
+            type: "number";
+            value: number;
+        };
+        debug: {
+            type: "boolean";
+            value: boolean;
+        };
+        debugOpacity: {
+            type: "number";
+            value: number;
+        };
+        debugLevel: {
+            type: "number";
+            value: number;
+        };
+    };
+    state: {
+        sources: Map<string, SourceState> | null;
+        multiDescriptor: MultiTilesetDescriptor | null;
+        forwardTo4326: ReprojectionFns["forwardReproject"] | null;
+        inverseFrom4326: ReprojectionFns["inverseReproject"] | null;
+        forwardTo3857: ReprojectionFns["forwardReproject"] | null;
+        inverseFrom3857: ReprojectionFns["inverseReproject"] | null;
+    };
+    initializeState(): void;
+    updateState({ changeFlags, props, oldProps, }: UpdateParameters<this>): void;
+    /**
+     * Open all configured COG sources in parallel, compute shared projection
+     * functions, and build the {@link MultiTilesetDescriptor}.
+     *
+     * All sources are assumed to share the same CRS; the projection of the
+     * first source is used for the shared coordinate converters.
+     *
+     * @returns Resolves when all sources have been opened and state has been set.
+     */
+    _parseAllSources(): Promise<void>;
+    /**
+     * Fetch tile data for all configured sources at the given tile index.
+     *
+     * Primary-grid sources are fetched directly at (x, y, z). Secondary
+     * sources are resolved to covering tiles at the closest matching zoom
+     * level, fetched (potentially multiple tiles), stitched if necessary,
+     * and returned with the appropriate UV transform.
+     *
+     * @param tile - Tile load props from the TileLayer, containing index and signal.
+     * @returns Per-band textures, UV transforms, and reprojection functions.
+     */
+    _getTileData(tile: TileLoadProps): Promise<MultiTileResult>;
+    /**
+     * Fetch a single tile for a source that shares the primary tile grid.
+     *
+     * @returns A `[name, BandTileData, null]` tuple with identity UV transform
+     *   and no debug info (primary bands don't need it).
+     */
+    private _fetchPrimaryBand;
+    /**
+     * Fetch covering tiles for a secondary source and stitch them into a
+     * single texture using {@link assembleTiles}.
+     *
+     * @returns A `[name, BandTileData, BandDebugInfo | null]` tuple with the
+     *   computed UV transform and optional debug metadata.
+     */
+    private _fetchSecondaryBand;
+    /**
+     * Create sub-layers for a single loaded tile.
+     *
+     * Builds a {@link RasterLayer} with reprojection functions and a render
+     * pipeline that starts with a {@link CompositeBands} module binding all
+     * band textures, followed by any user-provided pipeline modules.
+     */
+    _renderSubLayers(props: TileLayerProps<MultiTileResult> & {
+        id: string;
+        data?: MultiTileResult;
+        _offset: number;
+        tile: Tile2DHeader<MultiTileResult>;
+    }, forwardTo4326: ReprojectionFns["forwardReproject"], inverseFrom4326: ReprojectionFns["inverseReproject"], forwardTo3857: ReprojectionFns["forwardReproject"], inverseFrom3857: ReprojectionFns["inverseReproject"]): Layer | LayersList | null;
+    /**
+     * Render debug overlay layers for a single tile: colored outlines for
+     * primary and secondary tile boundaries, and tiered text labels.
+     *
+     * @param tileId - Base id for sub-layer naming.
+     * @param tile - The tile header with index info.
+     * @param data - The fetched multi-tile result containing debug info.
+     * @param forwardTo4326 - Projection function for converting CRS corners to WGS84.
+     * @returns Array of PathLayer and TextLayer sub-layers.
+     */
+    private _renderDebugLayers;
+    /**
+     * Build the tile layer that drives tile traversal and rendering.
+     *
+     * Creates a {@link RasterTileset2D} factory from the primary tileset,
+     * then returns a {@link TileLayer} wired up with tile fetching and
+     * sub-layer rendering.
+     */
+    renderTileLayer(multiDescriptor: MultiTilesetDescriptor, forwardTo4326: ReprojectionFns["forwardReproject"], inverseFrom4326: ReprojectionFns["inverseReproject"], forwardTo3857: ReprojectionFns["forwardReproject"], inverseFrom3857: ReprojectionFns["inverseReproject"]): TileLayer;
+    renderLayers(): Layer | LayersList | null;
+}
+export {};
+//# sourceMappingURL=multi-cog-layer.d.ts.map

package/dist/multi-cog-layer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"multi-cog-layer.d.ts","sourceRoot":"","sources":["../src/multi-cog-layer.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,mBAAmB,EACnB,KAAK,EAEL,UAAU,EACV,gBAAgB,EACjB,MAAM,eAAe,CAAC;AACvB,OAAO,EAAqB,cAAc,EAAE,MAAM,eAAe,CAAC;AAClE,OAAO,KAAK,EACV,aAAa,IAAI,YAAY,EAC7B,cAAc,EACd,cAAc,IAAI,aAAa,EAEhC,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAEhD,OAAO,KAAK,EACV,OAAO,EACP,sBAAsB,EACtB,YAAY,EAGZ,WAAW,EACZ,MAAM,iCAAiC,CAAC;AAczC,OAAO,KAAK,EACV,WAAW,EACX,OAAO,EAGR,MAAM,0BAA0B,CAAC;AAMlC,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,8BAA8B,CAAC;AAElE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAC;AAC1D,OAAO,EACL,YAAY,IAAI,mBAAmB,EAGpC,MAAM,uBAAuB,CAAC;AAC/B,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,mCAAmC,CAAC;AACzE,OAAO,KAAK,EAAU,OAAO,EAAiB,MAAM,eAAe,CAAC;AAmCpE,iDAAiD;AACjD,UAAU,YAAY;IACpB,qDAAqD;IACrD,OAAO,EAAE,OAAO,CAAC;IACjB,yEAAyE;IACzE,WAAW,EAAE,WAAW,CAAC;IACzB,sCAAsC;IACtC,KAAK,EAAE,MAAM,CAAC;IACd,uCAAuC;IACvC,MAAM,EAAE,MAAM,CAAC;IACf,kDAAkD;IAClD,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,2EAA2E;AAC3E,UAAU,aAAa;IACrB,yEAAyE;IACzE,oBAAoB,EAAE,OAAO,EAAE,CAAC;IAChC,2CAA2C;IAC3C,UAAU,EAAE,MAAM,CAAC;IACnB,yCAAyC;IACzC,WAAW,EAAE,WAAW,CAAC;IACzB,wCAAwC;IACxC,aAAa,EAAE,MAAM,CAAC;IACtB,yCAAyC;IACzC,cAAc,EAAE,MAAM,CAAC;IACvB,yCAAyC;IACzC,SAAS,EAAE,MAAM,CAAC;IAClB,wDAAwD;IACxD,cAAc,EAAE,MAAM,CAAC;CACxB;AAED,yDAAyD;AACzD,UAAU,kBAAkB;IAC1B,2EAA2E;IAC3E,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC;CACnC;AAED,qGAAqG;AACrG,UAAU,eAAe;IACvB,mDAAmD;IACnD,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC;IACjC,mEAAmE;IACnE,gBAAgB,EAAE,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC7D,mEAAmE;IACnE,gBAAgB,EAAE,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC7D,2CAA2C;IAC3C,KAAK,EAAE,MAAM,CAAC;IACd,4CAA4C;IAC5C,MAAM,EAAE,MAAM,CAAC;IACf,yFAAyF;IACzF,UAAU,EAAE,MAAM,CAAC;IACnB,uCAAuC;IACvC,SAAS,CAAC,EAAE,kBAAkB,CAAC;CAChC;AAED;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC;;;;OAIG;IACH,GAAG,EAAE,MAAM,GAAG,GAAG,GAAG,WAAW,CAAC;CACjC;AAED,qDAAqD;AACrD,UAAU,WAAW;IACnB,OAAO,EAAE,OAAO,CAAC;IACjB,GAAG,EAAE,aAAa,CAAC;CACpB;AAED;;;;;;;;;GASG;AACH,MAAM,MAAM,kBAAkB,GAAG,mBAAmB,GAClD,IAAI,CACF,cAAc,EACZ,cAAc,GACd,cAAc,GACd,kBAAkB,GAClB,aAAa,GACb,oBAAoB,CACvB,GAAG;IACF;;;;OAIG;IACH,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,oBAAoB,CAAC,CAAC;IAE9C;;;;OAIG;IACH,SAAS,CAAC,EAAE;QAAE,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAE9D;;;;OAIG;IACH,cAAc,CAAC,EAAE,YAAY,EAAE,CAAC;IAEhC;;;;;;OAMG;IACH,YAAY,CAAC,EAAE,YAAY,CAAC;IAE5B;;;;OAIG;IACH,IAAI,CAAC,EAAE,WAAW,CAAC;IAEnB;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAElB;;OAEG;IACH,MAAM,CAAC,EAAE,WAAW,CAAC;IAErB;;;;;;;;OAQG;IACH,aAAa,CAAC,EAAE,CACd,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,OAAO,EAAE;QACP,UAAU,EAAE,MAAM,CAAC;QACnB,gBAAgB,EAAE;YAChB,IAAI,EAAE,MAAM,CAAC;YACb,KAAK,EAAE,MAAM,CAAC;YACd,IAAI,EAAE,MAAM,CAAC;YACb,KAAK,EAAE,MAAM,CAAC;SACf,CAAC;KACH,KACE,IAAI,CAAC;IAEV;;;;;OAKG;IACH,KAAK,CAAC,EAAE,OAAO,CAAC;IAEhB;;;;;OAKG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IAEtB;;;;;;;;OAQG;IACH,UAAU,CAAC,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;CACxB,CAAC;AAUJ;;;;;;;;;;;;GAYG;AACH,qBAAa,aAAc,SAAQ,cAAc,CAAC,kBAAkB,CAAC;IACnE,OAAgB,SAAS,SAAmB;IAC5C,OAAgB,YAAY;;;;;;;;;;;;;;;;;;;;;MAAgB;IAEpC,KAAK,EAAE;QACb,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,WAAW,CAAC,GAAG,IAAI,CAAC;QACzC,eAAe,EAAE,sBAAsB,GAAG,IAAI,CAAC;QAC/C,aAAa,EAAE,eAAe,CAAC,kBAAkB,CAAC,GAAG,IAAI,CAAC;QAC1D,eAAe,EAAE,eAAe,CAAC,kBAAkB,CAAC,GAAG,IAAI,CAAC;QAC5D,aAAa,EAAE,eAAe,CAAC,kBAAkB,CAAC,GAAG,IAAI,CAAC;QAC1D,eAAe,EAAE,eAAe,CAAC,kBAAkB,CAAC,GAAG,IAAI,CAAC;KAC7D,CAAC;IAEO,eAAe,IAAI,IAAI;IAWvB,WAAW,CAAC,EACnB,WAAW,EACX,KAAK,EACL,QAAQ,GACT,EAAE,gBAAgB,CAAC,IAAI,CAAC,GAAG,IAAI;IAahC;;;;;;;;OAQG;IACG,gBAAgB,IAAI,OAAO,CAAC,IAAI,CAAC;IAoFvC;;;;;;;;;;OAUG;IACG,YAAY,CAAC,IAAI,EAAE,aAAa,GAAG,OAAO,CAAC,eAAe,CAAC;IA0GjE;;;;;OAKG;YACW,iBAAiB;IAyC/B;;;;;;OAMG;YACW,mBAAmB;IAmGjC;;;;;;OAMG;IACH,gBAAgB,CACd,KAAK,EAAE,cAAc,CAAC,eAAe,CAAC,GAAG;QACvC,EAAE,EAAE,MAAM,CAAC;QACX,IAAI,CAAC,EAAE,eAAe,CAAC;QACvB,OAAO,EAAE,MAAM,CAAC;QAChB,IAAI,EAAE,YAAY,CAAC,eAAe,CAAC,CAAC;KACrC,EACD,aAAa,EAAE,eAAe,CAAC,kBAAkB,CAAC,EAClD,eAAe,EAAE,eAAe,CAAC,kBAAkB,CAAC,EACpD,aAAa,EAAE,eAAe,CAAC,kBAAkB,CAAC,EAClD,eAAe,EAAE,eAAe,CAAC,kBAAkB,CAAC,GACnD,KAAK,GAAG,UAAU,GAAG,IAAI;IAsG5B;;;;;;;;;OASG;IACH,OAAO,CAAC,kBAAkB;IA0I1B;;;;;;OAMG;IACH,eAAe,CACb,eAAe,EAAE,sBAAsB,EACvC,aAAa,EAAE,eAAe,CAAC,kBAAkB,CAAC,EAClD,eAAe,EAAE,eAAe,CAAC,kBAAkB,CAAC,EACpD,aAAa,EAAE,eAAe,CAAC,kBAAkB,CAAC,EAClD,eAAe,EAAE,eAAe,CAAC,kBAAkB,CAAC,GACnD,SAAS;IAmDH,YAAY,IAAI,KAAK,GAAG,UAAU,GAAG,IAAI;CA2BnD"}