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

package/dist/esm/index.js

@@ -4967,6 +4967,8 @@ const DefaultGeoImageOptions = {
     useReliefGlaze: false,
     // --- Lighting control ---
     disableLighting: false,
+    // --- Animation / Caching ---
+    cacheAllBands: false,
 };
 
 class Martini {
@@ -7053,8 +7055,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;
@@ -7065,6 +7075,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.
@@ -7093,6 +7104,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 = [];
@@ -7101,6 +7120,7 @@ class CogTiles {
             this.tileSize = 256;
             this.zoomRange = [0, 0];
             this.bounds = [0, 0, 0, 0];
+            this.bandDescriptions = [];
             this.initializePromise = undefined;
             this.lastInitializedUrl = undefined;
         }
@@ -7126,6 +7146,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') {
@@ -7164,9 +7209,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];
     }
@@ -7374,6 +7433,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) {
@@ -7595,6 +7702,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();