@gisatcz/deckgl-geolib 2.5.0-dev.5 → 2.5.0

package/dist/esm/index.js

@@ -4928,6 +4928,9 @@ const DefaultGeoImageOptions = {
     useDataForOpacity: false,
     useSingleColor: false,
     blurredTexture: true,
+    skipTexture: false,
+    /** Strategy for noData detection: 'full' | 'border+center' */
+    noDataCheck: 'full',
     clipLow: null,
     clipHigh: null,
     color: [255, 0, 255, 255],
@@ -5655,6 +5658,19 @@ function scale(num, inMin, inMax, outMin, outMax) {
     return ((num - inMin) * (outMax - outMin)) / (inMax - inMin) + outMin;
 }
 
+function toF32(n) {
+    return Math.fround(n);
+}
+function isF32NoData(val, noData) {
+    if (noData === undefined || noData === null)
+        return false;
+    const a = toF32(val);
+    const b = toF32(noData);
+    if (Number.isNaN(b))
+        return Number.isNaN(a);
+    return a === b;
+}
+
 class BitmapGenerator {
     /**
      * Cache for Swiss relief color LUTs to avoid regenerating on every tile.
@@ -5828,9 +5844,7 @@ class BitmapGenerator {
             for (let i = 0, sampleIndex = (options.useChannelIndex ?? 0); i < arrayLength; i += 4, sampleIndex += samplesPerPixel) {
                 const elevationVal = primaryBuffer[sampleIndex];
                 // NaN-aware noData check for Swiss relief
-                const isNoData = options.noDataValue !== undefined && (Number.isNaN(options.noDataValue)
-                    ? Number.isNaN(elevationVal)
-                    : elevationVal === options.noDataValue);
+                const isNoData = isF32NoData(elevationVal, options.noDataValue);
                 if (Number.isNaN(elevationVal) || isNoData) {
                     colorsArray.set(options.nullColor, i);
                     continue;
@@ -6038,7 +6052,7 @@ class BitmapGenerator {
         return colorsArray;
     }
     static isInvalid(val, options) {
-        return Number.isNaN(val) || (options.noDataValue !== undefined && val === options.noDataValue);
+        return Number.isNaN(val) || isF32NoData(val, options.noDataValue);
     }
     static getInvalidColor(val, options) {
         return options.nullColor;
@@ -6060,7 +6074,7 @@ class BitmapGenerator {
         return (!Array.isArray(color) || color.length !== 4) ? [...chroma(color).rgb(), alpha] : color;
     }
     static hasPixelsNoData(pixels, noData) {
-        return noData !== undefined && pixels.every(p => p === noData);
+        return noData !== undefined && pixels.every(p => isF32NoData(p, noData));
     }
 }
 
@@ -6104,13 +6118,12 @@ class KernelGenerator {
         const cellSizeFactor = 1 / (8 * cellSize);
         // Cache constant for radians to degrees conversion
         const RAD_TO_DEG = 180 / Math.PI;
-        const isNaNNoData = noDataValue !== undefined && Number.isNaN(noDataValue);
         for (let r = 0; r < OUT; r++) {
             for (let c = 0; c < OUT; c++) {
                 // 3×3 neighborhood in the 258×258 input, centered at (r+1, c+1)
                 const base = r * IN + c;
                 const z5 = src[base + IN + 1]; // center pixel
-                const isNoData = noDataValue !== undefined && (isNaNNoData ? Number.isNaN(z5) : z5 === noDataValue);
+                const isNoData = isF32NoData(z5, noDataValue);
                 if (isNoData) {
                     out[r * OUT + c] = NaN;
                     continue;
@@ -6152,12 +6165,11 @@ class KernelGenerator {
         const azimuthRad = azimuthMath * (Math.PI / 180);
         // Hoist division out of loop: multiplication is ~2-3x faster than division
         const cellSizeFactor = 1 / (8 * cellSize);
-        const isNaNNoData = noDataValue !== undefined && Number.isNaN(noDataValue);
         for (let r = 0; r < OUT; r++) {
             for (let c = 0; c < OUT; c++) {
                 const base = r * IN + c;
                 const z5 = src[base + IN + 1]; // center pixel
-                const isNoData = noDataValue !== undefined && (isNaNNoData ? Number.isNaN(z5) : z5 === noDataValue);
+                const isNoData = isF32NoData(z5, noDataValue);
                 if (isNoData) {
                     out[r * OUT + c] = NaN;
                     continue;
@@ -6190,7 +6202,6 @@ class KernelGenerator {
         const out = new Float32Array(OUT * OUT);
         // Hoist division out of loop: multiplication is ~2-3x faster than division
         const cellSizeFactor = 1 / (8 * cellSize);
-        const isNaNNoData = noDataValue !== undefined && Number.isNaN(noDataValue);
         // Setup 3 light sources: NW (Main), W (Fill), N (Fill)
         const lights = [
             { az: 315, alt: 45, weight: 0.60 }, // Primary NW
@@ -6212,7 +6223,7 @@ class KernelGenerator {
             for (let c = 0; c < OUT; c++) {
                 const base = r * IN + c;
                 const z5 = src[base + IN + 1];
-                const isNoData = noDataValue !== undefined && (isNaNNoData ? Number.isNaN(z5) : z5 === noDataValue);
+                const isNoData = isF32NoData(z5, noDataValue);
                 if (isNoData) {
                     out[r * OUT + c] = NaN;
                     continue;
@@ -6380,6 +6391,7 @@ class TerrainGenerator {
             height: gridHeight,
         };
         // 3. Kernel path: compute slope or hillshade, store as rawDerived, generate texture
+        const shouldSkipTexture = !!options.skipTexture;
         if (isKernel && options.useSwissRelief) {
             const cellSize = input.cellSizeMeters ?? ((input.bounds[2] - input.bounds[0]) / 256);
             // Build a separate raster for kernel computation that preserves noData samples.
@@ -6387,7 +6399,7 @@ class TerrainGenerator {
             // Compose Swiss relief using ReliefCompositor
             const swissReliefResult = ReliefCompositor.composeSwissRelief(kernelTerrain, options, cellSize, 256, 256);
             tileResult.rawDerived = swissReliefResult;
-            if (this.hasVisualizationOptions(options)) {
+            if (!shouldSkipTexture && this.hasVisualizationOptions(options)) {
                 const cropped = this.cropRaster(meshTerrain, gridWidth, gridHeight, 256, 256);
                 const bitmapResult = await BitmapGenerator.generate({ width: 256, height: 256, rasters: [cropped, swissReliefResult] }, { ...options, type: 'image' });
                 tileResult.texture = bitmapResult.map;
@@ -6412,15 +6424,38 @@ class TerrainGenerator {
                 kernelOutput = KernelGenerator.calculateHillshade(kernelTerrain, cellSize, options.hillshadeAzimuth ?? 315, options.hillshadeAltitude ?? 45, zFactor, options.noDataValue);
             }
             tileResult.rawDerived = kernelOutput;
-            if (this.hasVisualizationOptions(options)) {
+            if (!shouldSkipTexture && this.hasVisualizationOptions(options)) {
                 const bitmapResult = await BitmapGenerator.generate({ width: 256, height: 256, rasters: [kernelOutput] }, { ...options, type: 'image' });
                 tileResult.texture = bitmapResult.map;
             }
         }
-        else if (this.hasVisualizationOptions(options)) {
-            // 4. Non-kernel path: crop 257→256, generate texture from elevation
-            const cropped = this.cropRaster(meshTerrain, gridWidth, gridHeight, 256, 256);
-            const bitmapResult = await BitmapGenerator.generate({ width: 256, height: 256, rasters: [cropped] }, { ...options, type: 'image' });
+        else if (!shouldSkipTexture && this.hasVisualizationOptions(options)) {
+            // 4. Non-kernel path: build texture raster from the ORIGINAL source data, preserving
+            // noData sentinels so BitmapGenerator renders those pixels as transparent (via nullColor).
+            // meshTerrain substitutes noData with terrainMinValue for mesh stability — we intentionally
+            // avoid using it for texture generation to prevent fill values being coloured.
+            const multiplier = options.multiplier ?? 1;
+            const noDataValue = options.noDataValue;
+            const srcRaster = input.rasters[0];
+            const srcWidth = input.width;
+            const srcHeight = input.height;
+            // Determine samplesPerPixel for interleaved buffers (fallback to 1)
+            const samplesPerPixel = Math.max(1, Math.round((srcRaster.length) / (srcWidth * srcHeight)));
+            const channelIndex = options.useChannelIndex ?? (options.useChannel != null ? options.useChannel - 1 : 0);
+            const textureRaster = new Float32Array(256 * 256);
+            for (let ty = 0; ty < 256; ty++) {
+                for (let tx = 0; tx < 256; tx++) {
+                    // Guard: if srcWidth < 256 (shouldn't happen), clamp indices
+                    const srcX = Math.min(tx, srcWidth - 1);
+                    const srcY = Math.min(ty, srcHeight - 1);
+                    const srcIdx = (srcY * srcWidth + srcX) * samplesPerPixel + channelIndex;
+                    const v = srcRaster[srcIdx];
+                    const isNoData = isF32NoData(v, noDataValue);
+                    textureRaster[ty * 256 + tx] = isNoData ? noDataValue * multiplier : v * multiplier;
+                }
+            }
+            const bitmapOptions = { ...options, type: 'image', useChannelIndex: 0, numOfChannels: 1, noDataValue: noDataValue !== undefined ? noDataValue * multiplier : undefined };
+            const bitmapResult = await BitmapGenerator.generate({ width: 256, height: 256, rasters: [textureRaster] }, bitmapOptions);
             tileResult.texture = bitmapResult.map;
         }
         return tileResult;
@@ -6454,12 +6489,9 @@ class TerrainGenerator {
             noDataValue !== null &&
             sourceRaster &&
             sourceRaster.length === terrain.length) {
-            const preserveNaNNoData = Number.isNaN(noDataValue);
             for (let i = 0; i < terrain.length; i++) {
                 const sourceValue = sourceRaster[i];
-                const isNoData = preserveNaNNoData
-                    ? Number.isNaN(sourceValue)
-                    : sourceValue === noDataValue;
+                const isNoData = isF32NoData(sourceValue, noDataValue);
                 kernelTerrain[i] = isNoData ? noDataValue : terrain[i];
             }
         }
@@ -6505,9 +6537,7 @@ class TerrainGenerator {
         for (let y = 0; y < height; y++) {
             for (let x = 0; x < width; x++) {
                 const multiplier = options.multiplier ?? 1;
-                let elevationValue = (options.noDataValue !== undefined &&
-                    options.noDataValue !== null &&
-                    channel[pixel] === options.noDataValue)
+                let elevationValue = isF32NoData(channel[pixel], options.noDataValue)
                     ? fallbackValue
                     : channel[pixel] * multiplier;
                 // Validate that the elevation value is within the valid range for Float32.
@@ -6640,15 +6670,16 @@ class GeoImage {
         else if (mergedOptions.type === 'terrain') {
             // Terrain with no explicit coloring mode.
             const hasKernelMode = userOptions.useSwissRelief || userOptions.useSlope || userOptions.useHillshade;
-            if (!hasKernelMode) {
-                // No kernel mode: enable useSingleColor with terrainColor as the default.
+            // If skipTexture is requested, force single-color mesh rendering regardless of kernel modes.
+            if (!hasKernelMode || mergedOptions.skipTexture) {
+                // No kernel mode OR skipTexture: enable useSingleColor with terrainColor as the default.
                 // This renders the mesh in the documented colour without a data-driven texture.
                 resolved.useHeatMap = false;
                 resolved.useSingleColor = true;
                 resolved.color = mergedOptions.terrainColor;
             }
             // When a kernel mode is present without an explicit coloring mode, keep
-            // useHeatMap: true from defaults so the kernel output is colourised.
+            // useHeatMap: true from defaults so the kernel output is colourised (unless skipTexture).
         }
         // For 'image' with no explicit coloring mode: keep useHeatMap: true from DefaultGeoImageOptions.
         return resolved;
@@ -6712,35 +6743,44 @@ class CogTiles {
     cog;
     cogZoomLookup = [];
     cogResolutionLookup = [];
+    cogMeshMaxErrorLookup = [];
     cogOrigin = [0, 0];
     zoomRange = [0, 0];
     tileSize = 256;
     bounds = [0, 0, 0, 0];
     geo = new GeoImage();
     options;
-    // Cache fetched rasters in an LRU-style Map keyed by `${z}/${x}/${y}/${fetchSize}`,
-    // with each value holding the cached raster for that tile request.
+    // TileResult cache — keyed by z/x/y/meshMaxError.
+    // Each entry owns an AbortController and a caller reference count.
+    // The pipeline is aborted only when ALL callers have cancelled (ref-count → 0),
+    // so concurrent deck.gl requests for the same tile share one in-flight fetch/tessellation
+    // and individual tile cancellations (e.g. from panning) do not poison other callers.
+    // Once the promise settles (resolved or rejected), controller/callerCount are irrelevant;
+    // future cache hits just await the already-resolved promise directly.
+    tileResultCache = new Map();
+    tileResultCacheMaxSize = 32;
+    getTileResultCacheKey(x, y, z, meshMaxError, skipTexture) {
+        return `${z}/${x}/${y}/${meshMaxError}/${skipTexture ? '1' : '0'}`;
+    }
+    /** Clears the TileResult cache. Call when the COG URL or meshMaxError changes. */
+    clearTileResultCache() {
+        // Abort any in-flight pipelines so their network requests are cancelled
+        for (const entry of this.tileResultCache.values()) {
+            if (!entry.settled)
+                entry.controller.abort();
+        }
+        this.tileResultCache.clear();
+    }
+    // Raw raster cache for ordinary bitmap layers — saves network fetch + decompression on revisit.
+    // BitmapGenerator is cheap to re-run from cached raster; no need to hold ImageBitmaps in memory.
     rasterCache = new Map();
-    maxCacheSize = 256;
-    // LRU cache helpers
-    getCachedRaster(key) {
-        const value = this.rasterCache.get(key);
-        if (value !== undefined) {
-            // Refresh order: delete and re-set
-            this.rasterCache.delete(key);
-            this.rasterCache.set(key, value);
-        }
-        return value;
-    }
-    setCachedRaster(key, value) {
-        this.rasterCache.set(key, value);
-        if (this.rasterCache.size > this.maxCacheSize) {
-            // Evict oldest
-            const oldestKey = this.rasterCache.keys().next().value;
-            if (typeof oldestKey === 'string') {
-                this.rasterCache.delete(oldestKey);
-            }
-        }
+    rasterCacheMaxSize = 64;
+    // Relief mask cache for bitmap + glaze layers — saves network fetch + kernel convolution on revisit.
+    // Stores the Float32Array output of composeSwissRelief; BitmapGenerator re-runs from it cheaply.
+    reliefMaskCache = new Map();
+    reliefMaskCacheMaxSize = 64;
+    getTileCacheKey(x, y, z) {
+        return `${z}/${x}/${y}`;
     }
     // Cache GeoTIFFImage Promises by index to prevent redundant HTTP requests from geotiff 3.0.4+ eager loading
     // Stores Promises (not resolved values) so concurrent requests share the same getImage() call
@@ -6753,15 +6793,33 @@ class CogTiles {
         this.options = { ...CogTilesGeoImageOptionsDefaults, ...options };
     }
     async initializeCog(url) {
-        // Return existing initialization promise if already in progress (prevents concurrent duplicates)
-        if (this.initializePromise)
+        // Reuse existing initialization while it is in progress, or when the same URL
+        // was already initialized on this instance.
+        if (this.initializePromise && (!this.cog || this.lastInitializedUrl === url)) {
             return this.initializePromise;
-        // Clear cache only if URL changed (preserves cache on idempotent re-init)
-        if (this.lastInitializedUrl !== url) {
+        }
+        // Fully reset COG-derived state when the URL changes so the instance can be
+        // safely reinitialized against a different source.
+        if (this.lastInitializedUrl !== undefined && this.lastInitializedUrl !== url) {
+            this.clearTileResultCache();
             this.rasterCache.clear();
+            this.reliefMaskCache.clear();
+            this.imageCache.clear();
+            this.cog = undefined;
+            this.cogOrigin = [0, 0];
+            this.cogZoomLookup = [];
+            this.cogResolutionLookup = [];
+            this.cogMeshMaxErrorLookup = [];
+            this.tileSize = 256;
+            this.zoomRange = [0, 0];
+            this.bounds = [0, 0, 0, 0];
+            this.initializePromise = undefined;
+            this.lastInitializedUrl = undefined;
+        }
+        // If COG already loaded and URL matches, return the existing promise
+        if (this.cog && this.lastInitializedUrl === url) {
+            return this.initializePromise ?? Promise.resolve();
         }
-        if (this.cog)
-            return;
         this.initializePromise = (async () => {
             try {
                 // fromUrl's type declaration only exposes RemoteSourceOptions, but the implementation
@@ -6781,6 +6839,10 @@ class CogTiles {
                 this.options.numOfChannels = fileDirectory.getValue('SamplesPerPixel');
                 this.options.planarConfig = fileDirectory.getValue('PlanarConfiguration');
                 [this.cogZoomLookup, this.cogResolutionLookup] = await this.buildCogZoomResolutionLookup(this.cog);
+                // Only compute quantized meshMaxError lookup for terrain COGs
+                if (this.options.type === 'terrain') {
+                    this.computeMeshMaxErrorLookup();
+                }
                 this.tileSize = image.getTileWidth();
                 // 1. Validation: Ensure the image is tiled
                 if (!this.tileSize || !image.getTileHeight()) {
@@ -6833,8 +6895,39 @@ class CogTiles {
         lat = (180 / Math.PI) * (2 * Math.atan(Math.exp((lat * Math.PI) / 180)) - Math.PI / 2);
         return [lon, lat];
     }
-    // return cartographicPositionAdjusted;
-    // }
+    /**
+     * Calculates the error multiplier based on zoom level and COG zoom range.
+     * - z >= maxZ: multiplier = 0.5 (fine meshes at high zoom, maximum precision)
+     * - z <= minZ: multiplier = 3.0 (coarse meshes at low zoom, maximum performance)
+     * - Otherwise: linear interpolation between 3.0 and 0.5
+     */
+    getErrorMultiplierForZoom(z, minZ, maxZ) {
+        if (z >= maxZ)
+            return 0.5;
+        if (z <= minZ)
+            return 3.0;
+        // Linear interpolation: 3.0 - ((z - minZ) / (maxZ - minZ)) * 2.5
+        return 3.0 - ((z - minZ) / (maxZ - minZ)) * 2.5;
+    }
+    /**
+     * Calculates dynamic meshMaxError for a given zoom level and resolution.
+     * Formula: resolution * errorMultiplier, where multiplier scales from 3.0 (low zoom) to 0.5 (high zoom).
+     * Results are clamped to 0.5–100 meters to prevent pathological tessellation:
+     * - Min 0.5m ensures simplification always happens (no rounding to 0 with sub-meter pixels)
+     * - Max 100m prevents excessive simplification at low zoom with low-resolution COGs
+     */
+    calculateDynamicMeshMaxError(z, resolution, minZ, maxZ) {
+        const multiplier = this.getErrorMultiplierForZoom(z, minZ, maxZ);
+        const errorValue = resolution * multiplier;
+        return Math.max(0.5, Math.min(100, errorValue));
+    }
+    /**
+     * Gets the auto meshMaxError for a given overview index.
+     * Returns undefined if auto lookup has not been computed.
+     */
+    getMeshMaxErrorForImageIndex(imageIndex) {
+        return this.cogMeshMaxErrorLookup[imageIndex];
+    }
     /**
      * Builds lookup tables for zoom levels and estimated resolutions from a Cloud Optimized GeoTIFF (COG) object.
      *
@@ -6875,6 +6968,20 @@ class CogTiles {
         }
         return [zoomLookup, resolutionLookup];
     }
+    /**
+     * Computes dynamic meshMaxError values for each overview based on COG resolution and zoom level.
+     * Called only for terrain COGs after buildCogZoomResolutionLookup() completes.
+     * Each overview's meshMaxError is calculated as: resolution * zoom-based multiplier, rounded to nearest integer.
+     * Multiplier ranges from 3.0 at minZ (coarse meshes) to 0.5 at maxZ (fine meshes).
+     */
+    computeMeshMaxErrorLookup() {
+        const minZ = this.cogZoomLookup[this.cogZoomLookup.length - 1];
+        const maxZ = this.cogZoomLookup[0];
+        this.cogMeshMaxErrorLookup = this.cogResolutionLookup.map((resolution, idx) => {
+            const zoom = this.cogZoomLookup[idx];
+            return this.calculateDynamicMeshMaxError(zoom, resolution, minZ, maxZ);
+        });
+    }
     /**
      * Determines the appropriate image index from the Cloud Optimized GeoTIFF (COG)
      * that best matches a given zoom level.
@@ -6923,12 +7030,6 @@ class CogTiles {
             signal.addEventListener('abort', () => controller.abort(), { once: true });
         }
         const localSignal = controller.signal;
-        // Check if raster is already cached
-        const cacheKey = `${zoom}/${tileX}/${tileY}/${fetchSize ?? this.tileSize}`;
-        const cachedRaster = this.getCachedRaster(cacheKey);
-        if (cachedRaster) {
-            return [cachedRaster];
-        }
         try {
             const imageIndex = this.getImageIndexForZoomLevel(zoom);
             // Cache Promises to share in-flight requests across concurrent tiles at the same overview
@@ -7027,28 +7128,42 @@ class CogTiles {
                         validImageData[i * numChannels + band] = tileBuffer[i];
                     }
                 }
-                // Mark raster as cached after successful fetch
-                this.setCachedRaster(cacheKey, validImageData); // for partial overlap
                 return [validImageData];
             }
             // Case B: Perfect Match (Optimization)
             // If the read window is exactly 256x256 and aligned, we can read directly interleaved.
             const tileData = await targetImage.readRasters({ window, interleave: true, signal: localSignal });
-            // Mark raster as cached after successful fetch
-            this.setCachedRaster(cacheKey, tileData); // for perfect match
             return [tileData];
         }
         catch (error) {
-            // If the signal was aborted (or geotiff.js threw AggregateError wrapping an abort),
-            // re-throw as a standard AbortError so deck.gl handles tile cancellation gracefully
-            // and suppressGlobalAbortErrors() can suppress the unhandled rejection noise.
+            // If it's a single-error AggregateError, unwrap to the inner error for clearer diagnostics
+            if (error instanceof AggregateError && error.errors.length === 1) {
+                const innerError = error.errors[0];
+                // Check if the unwrapped error is an abort — if so, throw it as AbortError
+                if (innerError instanceof DOMException && innerError.name === 'AbortError') {
+                    throw innerError;
+                }
+                if (innerError instanceof Error && innerError.message === 'Request was aborted') {
+                    throw new DOMException('Tile request aborted', 'AbortError');
+                }
+                // Unwrap single error for better diagnostics (throw the real error, not the wrapper)
+                throw innerError;
+            }
+            // Handle regular abort cases
             const isAbortRelated = localSignal.aborted
-                || (error instanceof AggregateError && error.errors?.some((e) => e?.name === 'AbortError' || e?.message?.includes('aborted') || e?.message?.includes('abort')))
                 || (error instanceof DOMException && error.name === 'AbortError')
                 || (error instanceof Error && error.message === 'Request was aborted');
             if (isAbortRelated) {
                 throw new DOMException('Tile request aborted', 'AbortError');
             }
+            // For multi-error AggregateError, check if ANY error is abort-related
+            if (error instanceof AggregateError) {
+                const hasAbort = error.errors.some((e) => (e instanceof DOMException && e.name === 'AbortError')
+                    || (e instanceof Error && e.message === 'Request was aborted'));
+                if (hasAbort) {
+                    throw new DOMException('Tile request aborted', 'AbortError');
+                }
+            }
             throw error;
         }
     }
@@ -7066,44 +7181,285 @@ class CogTiles {
         }
         return tileData;
     }
-    async getTile(x, y, z, bounds, meshMaxError, signal) {
-        let requiredSize = this.tileSize; // Default 256 for image/bitmap
-        if (this.options.type === 'terrain') {
-            const isKernel = this.options.useSlope || this.options.useHillshade || this.options.useSwissRelief;
-            requiredSize = this.tileSize + (isKernel ? 2 : 1); // 258 for kernel (3×3 border), 257 for normal stitching
-        }
-        else if (this.options.type === 'image' && this.options.useReliefGlaze) {
-            // Bitmap layer with relief glaze mode needs kernel padding for slope/hillshade computation
-            requiredSize = this.tileSize + 2; // 258 for kernel
-        }
-        const tileData = await this.getTileFromImage(x, y, z, requiredSize, signal);
-        // Compute true ground cell size in meters from tile indices.
-        // Tile y in slippy-map convention → center latitude → Web Mercator distortion correction.
+    async getTile(x, y, z, bounds, meshMaxError, signal, skipTexture) {
+        // cellSizeMeters is derived purely from tile coordinates — compute once for all paths
         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;
-        let rasters = [tileData[0]];
-        let tileWidth = requiredSize;
-        let tileHeight = requiredSize;
-        // Relief glaze computation for bitmap layers
-        // Note: For multi-band support (band selection via useChannelIndex), see issue #98
-        if (this.options.type === 'image' && this.options.useReliefGlaze) {
-            const elevation = tileData[0];
-            // Pass full 258×258 padded elevation directly — KernelGenerator expects IN=258 and outputs 256×256
-            const reliefMask = ReliefCompositor.composeSwissRelief(elevation, this.options, cellSizeMeters, this.tileSize, this.tileSize);
-            // For glaze-only mode, pass ONLY the 256×256 relief mask
-            rasters = [reliefMask];
-            tileWidth = this.tileSize;
-            tileHeight = this.tileSize;
-        }
-        // Guard against abort race condition: if signal aborted after cache hit but before expensive geo.getMap()
-        if (signal?.aborted) {
-            return null;
+        const isTerrain = this.options.type === 'terrain';
+        const isGlaze = this.options.type === 'image' && this.options.useReliefGlaze;
+        // Resolve meshMaxError: if not provided or 0, use auto quantized value; otherwise use explicit value
+        let resolvedMeshMaxError = meshMaxError;
+        if (isTerrain && (!meshMaxError || meshMaxError === 0)) {
+            const imageIndex = this.getImageIndexForZoomLevel(z);
+            const autoMeshMaxError = this.getMeshMaxErrorForImageIndex(imageIndex);
+            resolvedMeshMaxError = autoMeshMaxError ?? 4.0;
+        }
+        else {
+            resolvedMeshMaxError = meshMaxError ?? 4.0;
+        }
+        // ── PATH A: Terrain ──────────────────────────────────────────────────────────
+        // Full TileResult (mesh + raw + texture) cached with ref-counted abort so that
+        // panning cancels in-flight fetches only when ALL callers have cancelled.
+        if (isTerrain) {
+            const skipTextureFlag = skipTexture ?? this.options.skipTexture ?? false;
+            const cacheKey = this.getTileResultCacheKey(x, y, z, resolvedMeshMaxError, skipTextureFlag);
+            const existing = this.tileResultCache.get(cacheKey);
+            if (existing) {
+                // LRU touch — move the key to the end of the Map to mark as recently used
+                this.tileResultCache.delete(cacheKey);
+                this.tileResultCache.set(cacheKey, existing);
+            }
+            if (existing) {
+                if (existing.settled) {
+                    if (signal?.aborted)
+                        return null;
+                    return existing.promise;
+                }
+                existing.callerCount += 1;
+                if (signal && !signal.aborted) {
+                    signal.addEventListener('abort', () => {
+                        existing.callerCount -= 1;
+                        if (existing.callerCount <= 0 && !existing.settled) {
+                            existing.controller.abort();
+                        }
+                    }, { once: true });
+                }
+                const result = await existing.promise;
+                if (signal?.aborted)
+                    return null;
+                return result;
+            }
+            const controller = new AbortController();
+            const pipeline = (async () => {
+                const isKernel = this.options.useSlope || this.options.useHillshade || this.options.useSwissRelief;
+                const requiredSize = this.tileSize + (isKernel ? 2 : 1);
+                const tileData = await this.getTileFromImage(x, y, z, requiredSize, controller.signal);
+                // === Step F: detect all-noData tiles before tessellation ===
+                const raster = tileData[0];
+                const noData = this.options.noDataValue;
+                if (noData !== undefined && raster) {
+                    const numChannels = this.options.numOfChannels || 1;
+                    let useChannelIndex = this.options.useChannelIndex ?? (this.options.useChannel ? (this.options.useChannel - 1) : 0);
+                    if (useChannelIndex == null)
+                        useChannelIndex = 0;
+                    const checkStrategy = this.options.noDataCheck ?? 'full';
+                    const width = requiredSize;
+                    const height = requiredSize;
+                    const isNoValue = (v) => (Number.isNaN(noData) ? Number.isNaN(v) : v === noData);
+                    let allNoData = true;
+                    if (checkStrategy === 'full') {
+                        // Full linear scan (safe)
+                        if (numChannels > 1) {
+                            for (let i = useChannelIndex; i < raster.length; i += numChannels) {
+                                const v = raster[i];
+                                if (!isNoValue(v)) {
+                                    allNoData = false;
+                                    break;
+                                }
+                            }
+                        }
+                        else {
+                            for (let i = 0; i < raster.length; i++) {
+                                const v = raster[i];
+                                if (!isNoValue(v)) {
+                                    allNoData = false;
+                                    break;
+                                }
+                            }
+                        }
+                    }
+                    else if (checkStrategy === 'border+center') {
+                        // Border scan: iterate over top/bottom rows and left/right cols
+                        const stepX = numChannels;
+                        // Top row
+                        for (let x = 0; x < width; x++) {
+                            const idx = x * stepX + useChannelIndex;
+                            const v = raster[idx];
+                            if (!isNoValue(v)) {
+                                allNoData = false;
+                                break;
+                            }
+                        }
+                        // Bottom row
+                        if (allNoData) {
+                            for (let x = 0; x < width; x++) {
+                                const idx = ((height - 1) * width + x) * stepX + useChannelIndex;
+                                const v = raster[idx];
+                                if (!isNoValue(v)) {
+                                    allNoData = false;
+                                    break;
+                                }
+                            }
+                        }
+                        // Left/Right cols
+                        if (allNoData) {
+                            for (let y = 1; y < height - 1; y++) {
+                                const leftIdx = (y * width) * stepX + useChannelIndex;
+                                const rightIdx = (y * width + (width - 1)) * stepX + useChannelIndex;
+                                const vl = raster[leftIdx];
+                                const vr = raster[rightIdx];
+                                if (!isNoValue(vl) || !isNoValue(vr)) {
+                                    allNoData = false;
+                                    break;
+                                }
+                            }
+                        }
+                        // Center probe + 4 quadrant probes
+                        if (allNoData) {
+                            const probes = [
+                                [Math.floor(width / 2), Math.floor(height / 2)],
+                                [Math.floor(width / 4), Math.floor(height / 4)],
+                                [Math.floor((3 * width) / 4), Math.floor(height / 4)],
+                                [Math.floor(width / 4), Math.floor((3 * height) / 4)],
+                                [Math.floor((3 * width) / 4), Math.floor((3 * height) / 4)],
+                            ];
+                            for (const [px, py] of probes) {
+                                const idx = (py * width + px) * stepX + useChannelIndex;
+                                const v = raster[idx];
+                                if (!isNoValue(v)) {
+                                    allNoData = false;
+                                    break;
+                                }
+                            }
+                        }
+                    }
+                    else {
+                        // Unknown strategy — fallback to full
+                        for (let i = 0; i < raster.length; i++) {
+                            const v = raster[i];
+                            if (!isNoValue(v)) {
+                                allNoData = false;
+                                break;
+                            }
+                        }
+                    }
+                    if (allNoData) {
+                        // Do not cache all-noData result; remove cache entry so future requests re-evaluate if COG/metadata changes.
+                        this.tileResultCache.delete(cacheKey);
+                        return null;
+                    }
+                }
+                // Create generator options with skipTextureFlag applied (don't mutate shared this.options)
+                const generatorOptions = {
+                    ...this.options,
+                    skipTexture: skipTextureFlag,
+                };
+                return this.geo.getMap({
+                    rasters: [tileData[0]],
+                    width: requiredSize,
+                    height: requiredSize,
+                    bounds: bounds ?? [0, 0, 0, 0],
+                    cellSizeMeters,
+                }, generatorOptions, resolvedMeshMaxError);
+            })();
+            const entry = {
+                promise: pipeline,
+                controller,
+                callerCount: 1,
+                settled: false,
+            };
+            if (signal && !signal.aborted) {
+                signal.addEventListener('abort', () => {
+                    entry.callerCount -= 1;
+                    if (entry.callerCount <= 0 && !entry.settled) {
+                        entry.controller.abort();
+                    }
+                }, { once: true });
+            }
+            entry.promise = pipeline;
+            this.tileResultCache.set(cacheKey, entry);
+            if (this.tileResultCache.size > this.tileResultCacheMaxSize) {
+                const oldestKey = this.tileResultCache.keys().next().value;
+                if (typeof oldestKey === 'string') {
+                    const evicted = this.tileResultCache.get(oldestKey);
+                    if (evicted && !evicted.settled)
+                        evicted.controller.abort();
+                    this.tileResultCache.delete(oldestKey);
+                }
+            }
+            try {
+                const result = await pipeline;
+                entry.settled = true;
+                if (signal?.aborted)
+                    return null;
+                return result;
+            }
+            catch (error) {
+                entry.settled = true;
+                this.tileResultCache.delete(cacheKey);
+                throw error;
+            }
         }
+        // ── PATH B: Bitmap + glaze ────────────────────────────────────────────────────
+        // Relief mask (output of composeSwissRelief) cached — saves fetch + kernel on revisit.
+        // BitmapGenerator re-runs cheaply from the cached Float32Array.
+        // Signal is passed so cancelled tiles abort cleanly; cache entry is deleted on abort/error
+        // so the next request retries fresh.
+        if (isGlaze) {
+            const maskKey = this.getTileCacheKey(x, y, z);
+            let maskPromise = this.reliefMaskCache.get(maskKey);
+            if (maskPromise) {
+                // LRU touch — move the key to the end of the Map to mark as recently used
+                this.reliefMaskCache.delete(maskKey);
+                this.reliefMaskCache.set(maskKey, maskPromise);
+            }
+            if (!maskPromise) {
+                maskPromise = (async () => {
+                    const tileData = await this.getTileFromImage(x, y, z, this.tileSize + 2, signal);
+                    return ReliefCompositor.composeSwissRelief(tileData[0], this.options, cellSizeMeters, this.tileSize, this.tileSize);
+                })();
+                this.reliefMaskCache.set(maskKey, maskPromise);
+                maskPromise.catch(() => this.reliefMaskCache.delete(maskKey));
+                if (this.reliefMaskCache.size > this.reliefMaskCacheMaxSize) {
+                    const oldestKey = this.reliefMaskCache.keys().next().value;
+                    if (typeof oldestKey === 'string')
+                        this.reliefMaskCache.delete(oldestKey);
+                }
+            }
+            if (signal?.aborted)
+                return null;
+            const reliefMask = await maskPromise;
+            if (signal?.aborted)
+                return null;
+            return this.geo.getMap({
+                rasters: [reliefMask],
+                width: this.tileSize,
+                height: this.tileSize,
+                bounds: bounds ?? [0, 0, 0, 0],
+                cellSizeMeters,
+            }, this.options, meshMaxError ?? 4.0);
+        }
+        // ── PATH C: Ordinary bitmap ───────────────────────────────────────────────────
+        // Raw raster cached — saves fetch + decompression on revisit.
+        // BitmapGenerator re-runs cheaply from the cached TypedArray.
+        // Signal is passed so cancelled tiles abort cleanly; cache entry deleted on abort/error.
+        const rasterKey = this.getTileCacheKey(x, y, z);
+        let rasterPromise = this.rasterCache.get(rasterKey);
+        if (rasterPromise) {
+            // LRU touch — move the key to the end of the Map to mark as recently used
+            this.rasterCache.delete(rasterKey);
+            this.rasterCache.set(rasterKey, rasterPromise);
+        }
+        if (!rasterPromise) {
+            rasterPromise = this.getTileFromImage(x, y, z, this.tileSize, signal);
+            this.rasterCache.set(rasterKey, rasterPromise);
+            rasterPromise.catch(() => this.rasterCache.delete(rasterKey));
+            if (this.rasterCache.size > this.rasterCacheMaxSize) {
+                const oldestKey = this.rasterCache.keys().next().value;
+                if (typeof oldestKey === 'string')
+                    this.rasterCache.delete(oldestKey);
+            }
+        }
+        if (signal?.aborted)
+            return null;
+        const tileData = await rasterPromise;
+        if (signal?.aborted)
+            return null;
         return this.geo.getMap({
-            rasters,
-            width: tileWidth,
-            height: tileHeight,
+            rasters: [tileData[0]],
+            width: this.tileSize,
+            height: this.tileSize,
             bounds: bounds ?? [0, 0, 0, 0],
             cellSizeMeters,
         }, this.options, meshMaxError ?? 4.0);
@@ -7316,7 +7672,16 @@ class CogBitmapLayer extends CompositeLayer {
         }
     }
     async getTiledBitmapData(tile) {
-        const resolvedTileData = await this.state.bitmapCogTiles.getTile(tile.index.x, tile.index.y, tile.index.z, undefined, undefined, tile.signal);
+        let resolvedTileData;
+        try {
+            resolvedTileData = await this.state.bitmapCogTiles.getTile(tile.index.x, tile.index.y, tile.index.z, undefined, undefined, tile.signal);
+        }
+        catch (error) {
+            if (error instanceof DOMException && error.name === 'AbortError') {
+                return null;
+            }
+            throw error;
+        }
         if (resolvedTileData && !this.props.pickable) {
             resolvedTileData.raw = null;
         }
@@ -7413,6 +7778,12 @@ const urlType = {
         return true;
     },
 };
+const meshMaxErrorValidation = {
+    type: 'object',
+    value: 'auto',
+    validate: (value) => typeof value === 'number' || value === 'auto',
+    equal: (v1, v2) => v1 === v2,
+};
 const DUMMY_DATA = [1];
 const defaultProps = {
     ...TileLayer.defaultProps,
@@ -7421,7 +7792,9 @@ const defaultProps = {
     // Image url to use as texture
     texture: { ...urlType, optional: true },
     // Martini error tolerance in meters, smaller number -> more detailed mesh
-    meshMaxError: { type: 'number', value: 4.0 },
+    // Set to a number for fixed tessellation across all zooms, or 'auto' (default)
+    // for zoom-adaptive meshMaxError based on COG resolution
+    meshMaxError: meshMaxErrorValidation,
     // Bounding box of the terrain image, [minX, minY, maxX, maxY] in world coordinates
     bounds: {
         type: 'array', value: null, optional: true, compare: true,
@@ -7499,6 +7872,11 @@ class CogTerrainLayer extends CompositeLayer {
             || props.meshMaxError !== oldProps.meshMaxError
             || props.elevationDecoder !== oldProps.elevationDecoder
             || props.bounds !== oldProps.bounds;
+        // When meshMaxError changes, cached meshes are stale — clear so new tiles are tessellated
+        // at the correct error tolerance
+        if (props.meshMaxError !== oldProps.meshMaxError && this.state.terrainCogTiles) {
+            this.state.terrainCogTiles.clearTileResultCache();
+        }
         if (!this.state.isTiled && shouldReload) ;
         // Update the useChannel option for terrainCogTiles when terrainOptions.useChannel changes.
         if (props?.terrainOptions?.useChannel !== oldProps.terrainOptions?.useChannel) {
@@ -7506,6 +7884,13 @@ class CogTerrainLayer extends CompositeLayer {
             // Trigger a refresh of the tiles
             this.state.terrainCogTiles.options.useChannelIndex = null; // Clear cached index
         }
+        // Update skipTexture when wireframe/operation/disableTexture changes so cache keys are correct
+        const newSkipTexture = !!(props?.wireframe || props?.operation === 'terrain' || props?.disableTexture);
+        const oldSkipTexture = !!(oldProps?.wireframe || oldProps?.operation === 'terrain' || oldProps?.disableTexture);
+        if (newSkipTexture !== oldSkipTexture && this.state.terrainCogTiles) {
+            this.state.terrainCogTiles.options.skipTexture = newSkipTexture;
+            this.state.terrainCogTiles.clearTileResultCache();
+        }
         // When the external cogTiles instance is swapped (e.g. mode switch), update state so
         // renderLayers picks up the new reference and the TileLayer updateTrigger fires a refetch
         // while keeping old tile content visible until new tiles are ready.
@@ -7552,11 +7937,25 @@ class CogTerrainLayer extends CompositeLayer {
             topRight = [bbox.right, bbox.top];
         }
         const bounds = [bottomLeft[0], bottomLeft[1], topRight[0], topRight[1]];
-        const resolvedTerrain = await this.state.terrainCogTiles.getTile(tile.index.x, tile.index.y, tile.index.z, bounds, this.props.meshMaxError, tile.signal);
+        let resolvedTerrain = null;
+        try {
+            const skipTexture = !!(this.props.wireframe || this.props.operation === 'terrain' || this.props.disableTexture);
+            // Convert 'auto' to undefined so CogTiles.getTile uses the quantized meshMaxError for the zoom level
+            const meshMaxErrorValue = this.props.meshMaxError === 'auto' ? undefined : this.props.meshMaxError;
+            resolvedTerrain = await this.state.terrainCogTiles.getTile(tile.index.x, tile.index.y, tile.index.z, bounds, meshMaxErrorValue, tile.signal, skipTexture);
+        }
+        catch (error) {
+            // Tile was cancelled (AbortError) — return null so deck.gl discards it cleanly
+            if (error instanceof DOMException && error.name === 'AbortError') {
+                return null;
+            }
+            throw error;
+        }
         if (resolvedTerrain && !this.props.pickable) {
             resolvedTerrain.raw = null;
         }
-        return Promise.all([resolvedTerrain, null]);
+        // Return a tuple [TileResult|null, Texture|null] when data is available, otherwise null
+        return resolvedTerrain ? [resolvedTerrain, null] : null;
     }
     renderSubLayers(props) {
         const SubLayerClass = this.getSubLayerClass('mesh', SimpleMeshLayer);
@@ -7640,6 +8039,7 @@ class CogTerrainLayer extends CompositeLayer {
                         meshMaxError,
                         elevationDecoder,
                         terrainCogTiles: this.state.terrainCogTiles,
+                        skipTexture: !!(this.props.wireframe || this.props.operation === 'terrain' || this.props.disableTexture),
                     },
                     renderSubLayers: {
                         disableTexture: this.props.disableTexture,