@gisatcz/deckgl-geolib 2.5.1-dev.1 → 2.6.0-dev.2

package/dist/cjs/index.js

@@ -4969,6 +4969,8 @@ const DefaultGeoImageOptions = {
     useReliefGlaze: false,
     // --- Lighting control ---
     disableLighting: false,
+    // --- Animation / Caching ---
+    cacheAllBands: false,
 };
 
 class Martini {
@@ -7055,8 +7057,16 @@ class TileReader {
     }
 }
 
+// ── Global Multi-Band Cache ──
+// Survives across CogTiles instance recreations (e.g., during React re-renders).
+// Keyed by ${url}_${z}_${x}_${y}_${meshMaxError}_${skipTextureFlag}_band_${channel}
+// to account for dataset changes, tessellation options, and rendering modes.
+// Maps to pre-computed terrain meshes (same structure as single-band cache).
+const GLOBAL_MULTI_BAND_CACHE = new Map();
 const CogTilesGeoImageOptionsDefaults = {
     blurredTexture: true,
+    // When true, log per-tile per-band min/max values for debugging (disabled by default)
+    debugTileStats: false,
 };
 class CogTiles {
     cog;
@@ -7067,6 +7077,7 @@ class CogTiles {
     zoomRange = [0, 0];
     tileSize = 256;
     bounds = [0, 0, 0, 0];
+    bandDescriptions = [];
     geo = new GeoImage();
     options;
     // TileResult cache — keyed by z/x/y/meshMaxError.
@@ -7095,6 +7106,14 @@ class CogTiles {
         // safely reinitialized against a different source.
         if (this.lastInitializedUrl !== undefined && this.lastInitializedUrl !== url) {
             this.cache.clearAll();
+            // Clear multi-band cache entries for the old URL to prevent stale data
+            const keysToDelete = [];
+            GLOBAL_MULTI_BAND_CACHE.forEach((_, key) => {
+                if (key.startsWith(this.lastInitializedUrl)) {
+                    keysToDelete.push(key);
+                }
+            });
+            keysToDelete.forEach(key => GLOBAL_MULTI_BAND_CACHE.delete(key));
             this.cog = undefined;
             this.cogOrigin = [0, 0];
             this.cogZoomLookup = [];
@@ -7103,6 +7122,7 @@ class CogTiles {
             this.tileSize = 256;
             this.zoomRange = [0, 0];
             this.bounds = [0, 0, 0, 0];
+            this.bandDescriptions = [];
             this.initializePromise = undefined;
             this.lastInitializedUrl = undefined;
         }
@@ -7128,6 +7148,31 @@ class CogTiles {
                 this.options.format ??= await getDataTypeFromTags(fileDirectory);
                 this.options.numOfChannels = fileDirectory.getValue('SamplesPerPixel');
                 this.options.planarConfig = fileDirectory.getValue('PlanarConfiguration');
+                // Load per-band descriptions from GDAL_METADATA tag
+                const numBands = this.options.numOfChannels ?? 1;
+                const descriptions = Array(numBands).fill('');
+                if (image.fileDirectory.hasTag('GDAL_METADATA')) {
+                    const gdalMetadataStr = await image.fileDirectory.loadValue('GDAL_METADATA');
+                    // Parse XML GDAL metadata to extract per-band descriptions.
+                    // Regex is flexible with attribute order; GDAL generates items with name="DESCRIPTION"
+                    // before sample="N", but [^>]* allows other attributes to appear in any order.
+                    // Format: <Item name="DESCRIPTION" sample="0" role="description">20170101</Item>
+                    const bandDescRegex = /<Item[^>]*name="DESCRIPTION"[^>]*sample="(\d+)"[^>]*>([^<]*)<\/Item>/g;
+                    let match;
+                    while ((match = bandDescRegex.exec(gdalMetadataStr)) !== null) {
+                        const bandIdx = parseInt(match[1], 10);
+                        const desc = match[2];
+                        if (bandIdx < numBands) {
+                            descriptions[bandIdx] = desc;
+                        }
+                    }
+                    // Debug: Log if no descriptions were found in metadata
+                    if (descriptions.every(d => d === '')) {
+                        // eslint-disable-next-line no-console
+                        console.debug('[CogTiles] GDAL_METADATA present but no DESCRIPTION items found');
+                    }
+                }
+                this.bandDescriptions = descriptions;
                 [this.cogZoomLookup, this.cogResolutionLookup] = await buildCogZoomResolutionLookup(this.cog);
                 // Only compute quantized meshMaxError lookup for terrain COGs
                 if (this.options.type === 'terrain') {
@@ -7166,9 +7211,23 @@ class CogTiles {
         return this.bounds;
     }
     /**
-     * Gets the auto meshMaxError for a given overview index.
-     * Returns undefined if auto lookup has not been computed.
+     * Gets the number of channels/bands in the COG.
+     * Returns the value from COG metadata, or 1 if not initialized.
+     */
+    getNumChannels() {
+        return this.options.numOfChannels || 1;
+    }
+    /**
+     * Returns per-band descriptions loaded from GDAL_METADATA during initialization.
+     * Index is 0-based. Returns an empty string for bands without a description.
      */
+    getBandDescriptions() {
+        return this.bandDescriptions;
+    }
+    /**
+      * Gets the auto meshMaxError for a given overview index.
+      * Returns undefined if auto lookup has not been computed.
+      */
     getMeshMaxErrorForImageIndex(imageIndex) {
         return this.cogMeshMaxErrorLookup[imageIndex];
     }
@@ -7376,6 +7435,54 @@ class CogTiles {
     }
     async getTerrainTile(x, y, z, bounds, resolvedMeshMaxError, cellSizeMeters, signal, skipTexture) {
         const skipTextureFlag = skipTexture ?? this.options.skipTexture ?? false;
+        // ── Multi-Band Cache Check ──
+        // If cacheAllBands is enabled, check if this tile+band combination is in the cache.
+        // If so, return it instantly. If not, fetch all bands and populate the cache.
+        if (this.options.cacheAllBands) {
+            if (signal?.aborted) {
+                return null; // Early exit if already aborted
+            }
+            const currentChannel = this.options.useChannel || 1; // 1-based
+            // Cache key includes URL, meshMaxError, and skipTexture to account for dataset/option changes
+            const multiBandCacheKey = `${this.lastInitializedUrl}_${z}_${x}_${y}_${resolvedMeshMaxError}_${skipTextureFlag}_band_${currentChannel}`;
+            // Check if this specific band is already cached
+            if (GLOBAL_MULTI_BAND_CACHE.has(multiBandCacheKey)) {
+                const cached = GLOBAL_MULTI_BAND_CACHE.get(multiBandCacheKey);
+                if (cached) {
+                    return cached;
+                }
+            }
+            // Not in cache — fetch all bands for this tile and populate the cache
+            try {
+                // Pass NO signal to getTileAllBands to avoid early abortion
+                // The tile lifecycle is managed by TileLayer, we want this fetch to complete
+                const allBands = await this.getTileAllBands(x, y, z, resolvedMeshMaxError, undefined, bounds);
+                // Only cache and return if we got valid data
+                if (allBands && allBands.length > 0) {
+                    if (signal?.aborted) {
+                        return null; // Check abort after fetch completes
+                    }
+                    // Cache all bands (indexed by 1-based channel: band 1, band 2, ..., band N)
+                    allBands.forEach((bandResult, idx) => {
+                        const bandChannel = idx + 1; // Convert 0-based index to 1-based channel
+                        const cacheKey = `${this.lastInitializedUrl}_${z}_${x}_${y}_${resolvedMeshMaxError}_${skipTextureFlag}_band_${bandChannel}`;
+                        GLOBAL_MULTI_BAND_CACHE.set(cacheKey, bandResult);
+                    });
+                    // Return the requested band
+                    const requestedBandIndex = (currentChannel || 1) - 1; // Convert 1-based to 0-based
+                    if (requestedBandIndex < 0 || requestedBandIndex >= allBands.length) {
+                        console.error(`[CogTiles] Requested band index ${requestedBandIndex} out of range (0-${allBands.length - 1})`);
+                        return null;
+                    }
+                    return allBands[requestedBandIndex];
+                }
+                // If getTileAllBands returned empty, fall through to normal fetch
+            }
+            catch (error) {
+                // If multi-band fetch fails, fall through to normal tile fetch
+                console.warn('[CogTiles] Multi-band fetch failed, falling back to single-band:', error);
+            }
+        }
         const cacheKey = this.cache.getTileResultCacheKey(x, y, z, resolvedMeshMaxError, skipTextureFlag);
         const existing = this.cache.getTileResult(cacheKey);
         if (existing) {
@@ -7597,6 +7704,114 @@ class CogTiles {
             cellSizeMeters,
         }, this.options, meshMaxError ?? 4.0);
     }
+    async getTileAllBands(x, y, z, meshMaxError, signal, bounds) {
+        if (!this.cog) {
+            return [];
+        }
+        // Compute cell size for this tile
+        const latRad = Math.atan(Math.sinh(Math.PI * (1 - 2 * (y + 0.5) / Math.pow(2, z))));
+        const tileWidthMeters = (EARTH_CIRCUMFERENCE / Math.pow(2, z)) * Math.cos(latRad);
+        const cellSizeMeters = tileWidthMeters / this.tileSize;
+        // Resolve meshMaxError
+        let resolvedMeshMaxError;
+        if (!meshMaxError || meshMaxError === 0) {
+            const imageIndex = this.getImageIndexForZoomLevel(z);
+            const autoMeshMaxError = this.getMeshMaxErrorForImageIndex(imageIndex);
+            resolvedMeshMaxError = autoMeshMaxError ?? 4.0;
+        }
+        else {
+            resolvedMeshMaxError = meshMaxError;
+        }
+        // Create a fresh local AbortController for this fetch
+        const controller = new AbortController();
+        if (signal && !signal.aborted) {
+            signal.addEventListener('abort', () => controller.abort(), { once: true });
+        }
+        const localSignal = controller.signal;
+        try {
+            const imageIndex = this.getImageIndexForZoomLevel(z);
+            let imagePromise = this.cache.getImage(imageIndex);
+            if (!imagePromise) {
+                imagePromise = this.cog.getImage(imageIndex);
+                this.cache.setImage(imageIndex, imagePromise);
+            }
+            const targetImage = await imagePromise;
+            const imageResolution = this.cogResolutionLookup[imageIndex];
+            const imageHeight = targetImage.getHeight();
+            const imageWidth = targetImage.getWidth();
+            const [imgOriginX, imgOriginY] = this.cogOrigin;
+            const TILE_SIZE = this.tileSize;
+            const ORIGIN_X = webMercatorOrigin[0];
+            const ORIGIN_Y = webMercatorOrigin[1];
+            // ── Martini Grid Size Fix ──
+            // Martini requires 2^n + 1 grid (e.g., 257x257), but we fetch at TILE_SIZE (256).
+            // Add padding for relief kernels (2) or just 1 for basic terrain.
+            const isKernel = this.options.useSlope || this.options.useHillshade || this.options.useSwissRelief;
+            const FETCH_SIZE = this.tileSize + (isKernel ? 2 : 1);
+            const tileGridResolution = (EARTH_CIRCUMFERENCE / TILE_SIZE) / (2 ** z);
+            const tileMinXMeters = ORIGIN_X + (x * TILE_SIZE * tileGridResolution);
+            const tileMaxYMeters = ORIGIN_Y - (y * TILE_SIZE * tileGridResolution);
+            const windowMinX = (tileMinXMeters - imgOriginX) / imageResolution;
+            const windowMinY = (imgOriginY - tileMaxYMeters) / imageResolution;
+            const startX = Math.round(windowMinX);
+            const startY = Math.round(windowMinY);
+            const endX = startX + FETCH_SIZE;
+            const endY = startY + FETCH_SIZE;
+            const validReadX = Math.max(0, startX);
+            const validReadY = Math.max(0, startY);
+            const validReadMaxX = Math.min(imageWidth, endX);
+            const validReadMaxY = Math.min(imageHeight, endY);
+            const readWidth = validReadMaxX - validReadX;
+            const readHeight = validReadMaxY - validReadY;
+            // If no overlap, return empty array
+            if (readWidth <= 0 || readHeight <= 0) {
+                return [];
+            }
+            const missingLeft = validReadX - startX;
+            const missingTop = validReadY - startY;
+            const window = [validReadX, validReadY, validReadMaxX, validReadMaxY];
+            const validRasterData = await targetImage.readRasters({ window, signal: localSignal });
+            if (signal?.aborted)
+                return [];
+            const results = [];
+            const numBands = validRasterData.length;
+            for (let bandIndex = 0; bandIndex < numBands; bandIndex += 1) {
+                const sourceBandArray = validRasterData[bandIndex];
+                const processedBandRaster = this.tileReader.createTileBuffer(this.options.format || 'Float32', FETCH_SIZE);
+                if (this.options.noDataValue !== undefined) {
+                    processedBandRaster.fill(this.options.noDataValue);
+                }
+                for (let row = 0; row < readHeight; row += 1) {
+                    const destRow = missingTop + row;
+                    const destRowOffset = destRow * FETCH_SIZE;
+                    const srcRowOffset = row * readWidth;
+                    for (let col = 0; col < readWidth; col += 1) {
+                        const destCol = missingLeft + col;
+                        if (destRow < FETCH_SIZE && destCol < FETCH_SIZE) {
+                            processedBandRaster[destRowOffset + destCol] = sourceBandArray[srcRowOffset + col];
+                        }
+                    }
+                }
+                const generatorOptions = { ...this.options, useChannel: 1, useChannelIndex: 0, numOfChannels: 1 };
+                const tileResult = await this.geo.getMap({
+                    rasters: [processedBandRaster],
+                    width: FETCH_SIZE,
+                    height: FETCH_SIZE,
+                    bounds: bounds ?? [0, 0, 0, 0],
+                    cellSizeMeters,
+                }, generatorOptions, resolvedMeshMaxError);
+                if (tileResult)
+                    results.push(tileResult);
+            }
+            return results;
+        }
+        catch (error) {
+            if (signal?.aborted)
+                return [];
+            console.error('[CogTiles.getTileAllBands] Error fetching all bands:', error);
+            return [];
+        }
+    }
     // Expose legacy API for clearing tile result cache (used by external layers)
     clearTileResultCache() {
         this.cache.clearTileResultCache();
@@ -8097,6 +8312,151 @@ class CogTerrainLayer extends core.CompositeLayer {
     }
 }
 
+/**
+ * Terrain coordinate extraction utility for CogTerrainLayer
+ * Enables precise lat/lon/elevation extraction from 3D terrain picks
+ */
+/**
+ * Extracts precise geographic coordinates and elevation from a CogTerrainLayer pick result
+ *
+ * @param pickResult - DeckGL pickObject result from terrain-layer pick
+ * @returns TerrainCoordinate with lon/lat/elevation, or null if extraction fails
+ *
+ * @requires deck.gl >=9.3.0 (for `pickable: '3d'` support)
+ * @note Requires `pickable: '3d'` on CogTerrainLayer. With 3D picking enabled,
+ * deck.gl's terrain layer provides info.coordinate as a 3-element array [lon, lat, elevation]
+ * where elevation is read directly from the terrain mesh at the picked point.
+ * This gives accurate 3D coordinates regardless of camera pitch or bearing.
+ *
+ * @example
+ * ```ts
+ * const cogLayer = new CogTerrainLayer({
+ *   // ...
+ *   pickable: '3d',  // Requires deck.gl >=9.3.0
+ *   onClick: (info) => {
+ *     const coord = extractTerrainCoordinate(info);
+ *     if (coord) {
+ *       console.log(`Clicked at ${coord.latitude}, ${coord.longitude}, elevation: ${coord.elevation}m`);
+ *     }
+ *   }
+ * });
+ * ```
+ */
+function extractTerrainCoordinate(pickResult) {
+    try {
+        // With pickable: '3d', info.coordinate is a 3-element array [lon, lat, elevation]
+        if (!pickResult?.coordinate || pickResult.coordinate.length < 3) {
+            return null;
+        }
+        const [longitude, latitude, elevation] = pickResult.coordinate;
+        if (longitude === undefined || latitude === undefined || elevation === undefined) {
+            return null;
+        }
+        return {
+            longitude,
+            latitude,
+            elevation,
+        };
+    }
+    catch {
+        // Silently return null on any error
+        return null;
+    }
+}
+/**
+ * Samples terrain coordinates in a grid around a pick point for debugging
+ * Useful for understanding terrain data layout and accuracy
+ *
+ * @param pickResult - DeckGL pickObject result from terrain-layer pick
+ * @param gridSize - Odd number for grid dimensions (default: 3 for 3x3 grid).
+ *                   gridSize=3 → 3×3 grid (offset±1), gridSize=5 → 5×5 grid (offset±2).
+ *                   Uses WebMercator projection for accurate latitude mapping.
+ * @returns Array of TerrainCoordinate samples, or empty array if extraction fails
+ *
+ * @example
+ * ```ts
+ * const samples = sampleTerrainTileCoordinates(info, 5); // 5x5 grid around click
+ * samples.forEach(coord => {
+ *   console.log(`Sample: ${coord.latitude}, ${coord.longitude}, elev: ${coord.elevation}m`);
+ * });
+ * ```
+ */
+function sampleTerrainTileCoordinates(pickResult, gridSize = 3) {
+    try {
+        // Validate input has required structure
+        if (!pickResult?.tile?.content) {
+            return [];
+        }
+        const tileResult = pickResult.tile.content[0];
+        if (!tileResult?.raw) {
+            return [];
+        }
+        const { raw, width, height } = tileResult;
+        const bbox = pickResult.tile.bbox;
+        if (!bbox) {
+            return [];
+        }
+        const west = bbox.west ?? bbox[0];
+        const south = bbox.south ?? bbox[1];
+        const east = bbox.east ?? bbox[2];
+        const north = bbox.north ?? bbox[3];
+        if (west === undefined || south === undefined || east === undefined || north === undefined) {
+            return [];
+        }
+        const coordinate = pickResult.coordinate;
+        if (!coordinate || coordinate.length < 2) {
+            return [];
+        }
+        const [centerLon, centerLat] = coordinate;
+        // Calculate grid offset (in pixels): gridSize must be odd; gridSize=3 → offset=1, gridSize=5 → offset=2
+        const offset = Math.floor(gridSize / 2);
+        // Get center pixel from clicked coordinate using WebMercator projection
+        const centerNormX = (centerLon - west) / (east - west);
+        // WebMercator non-linear latitude projection
+        const centerLatRad = centerLat * Math.PI / 180;
+        const northRad = north * Math.PI / 180;
+        const southRad = south * Math.PI / 180;
+        const mercatorCenterY = Math.log(Math.tan(Math.PI / 4 + centerLatRad / 2));
+        const mercatorNorth = Math.log(Math.tan(Math.PI / 4 + northRad / 2));
+        const mercatorSouth = Math.log(Math.tan(Math.PI / 4 + southRad / 2));
+        const centerNormY = (mercatorNorth - mercatorCenterY) / (mercatorNorth - mercatorSouth);
+        const centerPixelX = Math.floor(centerNormX * (width - 1));
+        const centerPixelY = Math.floor(centerNormY * (height - 1));
+        const samples = [];
+        // Sample grid around clicked point
+        for (let dy = -offset; dy <= offset; dy++) {
+            for (let dx = -offset; dx <= offset; dx++) {
+                const pixelX = centerPixelX + dx;
+                const pixelY = centerPixelY + dy;
+                // Stay within tile bounds
+                if (pixelX < 0 || pixelX >= width || pixelY < 0 || pixelY >= height) {
+                    continue;
+                }
+                const pixelIndex = pixelY * width + pixelX;
+                const elevation = raw[pixelIndex];
+                if (elevation === undefined || elevation === null) {
+                    continue;
+                }
+                // Convert pixel to geographic coordinates using WebMercator projection
+                const lon = west + (pixelX / (width - 1)) * (east - west);
+                // Inverse WebMercator transform for latitude
+                const normV = pixelY / (height - 1);
+                const mercatorY = mercatorNorth - normV * (mercatorNorth - mercatorSouth);
+                const lat = (2 * Math.atan(Math.exp(mercatorY)) - Math.PI / 2) * 180 / Math.PI;
+                samples.push({
+                    longitude: lon,
+                    latitude: lat,
+                    elevation,
+                });
+            }
+        }
+        return samples;
+    }
+    catch {
+        return [];
+    }
+}
+
 // src/index.ts
 // Initialize global error suppression for deck.gl AbortErrors
 suppressGlobalAbortErrors();
@@ -15314,5 +15674,7 @@ exports.CogBitmapLayer = CogBitmapLayer;
 exports.CogTerrainLayer = CogTerrainLayer;
 exports.CogTiles = CogTiles;
 exports.GeoImage = GeoImage;
+exports.extractTerrainCoordinate = extractTerrainCoordinate;
+exports.sampleTerrainTileCoordinates = sampleTerrainTileCoordinates;
 exports.suppressGlobalAbortErrors = suppressGlobalAbortErrors;
 //# sourceMappingURL=index.js.map