@gisatcz/deckgl-geolib 2.4.1-dev.1 → 2.5.0-dev.2

package/dist/esm/index.js

@@ -4876,7 +4876,7 @@ const DefaultGeoImageOptions = {
     planarConfig: undefined,
     // --- Mesh generation (terrain only) ---
     tesselator: 'martini',
-    terrainColor: [133, 133, 133, 255],
+    terrainColor: [200, 200, 200, 255],
     terrainSkirtHeight: 100,
     // Default fallback for invalid/nodata elevations. Should be configured based on the dataset's actual range.
     terrainMinValue: 0,
@@ -4893,9 +4893,23 @@ const DefaultGeoImageOptions = {
     color: [255, 0, 255, 255],
     colorScale: chroma.brewer.YlOrRd,
     colorScaleValueRange: [0, 255],
+    //     colorScale: [
+    //     [75, 120, 90],    // Brightened forest green
+    //     [100, 145, 100],  // Soft meadow green
+    //     [130, 170, 110],  // Bright moss
+    //     [185, 210, 145],  // Sunny sage
+    //     [235, 235, 185],  // Pale primrose (transitional)
+    //     [225, 195, 160],  // Sand / light terracotta (matches slope)
+    //     [195, 160, 130],  // Warm clay brown
+    //     [170, 155, 150],  // Warm slate grey
+    //     [245, 245, 240],  // Bright mist
+    //     [255, 255, 255],  // Pure peak white
+    // ],
+    // colorScaleValueRange: [0, 6500],
     colorsBasedOnValues: undefined,
     colorClasses: undefined,
     alpha: 100,
+    maxGlazeAlpha: 128,
     nullColor: [0, 0, 0, 0],
     unidentifiedColor: [0, 0, 0, 0],
     clippedColor: [0, 0, 0, 0],
@@ -4905,6 +4919,11 @@ const DefaultGeoImageOptions = {
     hillshadeAzimuth: 315,
     hillshadeAltitude: 45,
     zFactor: 1,
+    useSwissRelief: false,
+    swissSlopeWeight: 0.5,
+    useReliefGlaze: false,
+    // --- Lighting control ---
+    disableLighting: false,
 };
 
 class Martini {
@@ -5591,6 +5610,27 @@ function scale(num, inMin, inMax, outMin, outMax) {
 }
 
 class BitmapGenerator {
+    /**
+     * Cache for Swiss relief color LUTs to avoid regenerating on every tile.
+     * Key: colorScale config + range, Value: pre-computed RGBA LUT
+     */
+    static _swissColorLUTCache = new Map();
+    /**
+     * Cache for 8-bit (256-entry) color LUTs.
+     * Shared process-wide across all tiles and datasets when options are fixed (i.e. !useAutoRange).
+     * Key: serialised coloring options, Value: pre-computed 256×RGBA LUT
+     */
+    static _8bitLUTCache = new Map();
+    /**
+     * Cache for float/16-bit (1024-entry) heatmap LUTs.
+     * Shared process-wide across all tiles and datasets when !useAutoRange.
+     * Key: serialised coloring options + range, Value: pre-computed 1024×RGBA LUT
+     */
+    static _floatLUTCache = new Map();
+    /** Build a cache key that captures all options affecting LUT colour output. */
+    static getLUTCacheKey(options, rangeMin, rangeMax, optAlpha) {
+        return `${rangeMin}_${rangeMax}_${optAlpha}_${JSON.stringify(options.colorScale)}_${options.useSingleColor}_${JSON.stringify(options.color)}_${options.useColorClasses}_${JSON.stringify(options.colorClasses)}_${options.useColorsBasedOnValues}_${JSON.stringify(options.colorsBasedOnValues)}_${options.useHeatMap}_${options.clipLow ?? ''}_${options.clipHigh ?? ''}_${JSON.stringify(options.clippedColor)}_${JSON.stringify(options.nullColor)}_${JSON.stringify(options.unidentifiedColor)}`;
+    }
     /**
      * Main entry point: Generates an ImageBitmap from raw raster data.
      */
@@ -5617,7 +5657,31 @@ class BitmapGenerator {
         // If planar support is added, this logic must be updated to handle both layouts correctly.
         const numAvailableChannels = optionsLocal.numOfChannels ??
             (rasters.length === 1 ? rasters[0].length / (width * height) : rasters.length);
-        if (optionsLocal.useChannelIndex == null) {
+        if (optionsLocal.useReliefGlaze) {
+            if (rasters.length >= 1) {
+                // Relief glaze: pure black/white overlay with variable alpha
+                imageData.data.set(this.getReliefGlazeRGBA(rasters, optionsLocal, size));
+            }
+            else {
+                // Missing relief mask: fill with transparent
+                const transparentData = new Uint8ClampedArray(size);
+                transparentData.fill(0);
+                imageData.data.set(transparentData);
+            }
+        }
+        else if (optionsLocal.useSwissRelief) {
+            if (rasters.length === 2) {
+                // Normal Swiss relief rendering: hypsometric color × relief mask
+                imageData.data.set(this.getColorValue(rasters, optionsLocal, size));
+            }
+            else { // Missing mask: fill with null color (fully transparent or a fallback)
+                const defaultColorData = this.getDefaultColor(size, optionsLocal.nullColor);
+                defaultColorData.forEach((value, index) => {
+                    imageData.data[index] = value;
+                });
+            }
+        }
+        else if (optionsLocal.useChannelIndex == null) {
             if (isInterleaved) {
                 const ratio = rasters[0].length / (width * height);
                 if (ratio === 1) {
@@ -5685,23 +5749,90 @@ class BitmapGenerator {
         const optAlpha = Math.floor((options.alpha ?? 100) * 2.55);
         const rangeMin = options.colorScaleValueRange?.[0] ?? 0;
         const rangeMax = options.colorScaleValueRange?.[1] ?? 255;
-        const is8Bit = dataArray instanceof Uint8Array || dataArray instanceof Uint8ClampedArray;
-        const isFloatOrWide = !is8Bit && (dataArray instanceof Float32Array || dataArray instanceof Uint16Array || dataArray instanceof Int16Array);
-        // 1. 8-BIT COMPREHENSIVE LUT
-        // Single-band 8-bit (grayscale or indexed): use LUT for fast mapping
-        if (is8Bit && !options.useDataForOpacity) {
-            const lut = new Uint8ClampedArray(256 * 4);
-            for (let i = 0; i < 256; i++) {
-                if ((options.clipLow != null && i <= options.clipLow) ||
-                    (options.clipHigh != null && i >= options.clipHigh)) {
-                    lut.set(options.clippedColor, i * 4);
+        const isMultiRaster = Array.isArray(dataArray);
+        const primaryBuffer = isMultiRaster ? dataArray[0] : dataArray;
+        const isSwiss = options.useSwissRelief && isMultiRaster && dataArray.length >= 2;
+        const is8Bit = primaryBuffer instanceof Uint8Array || primaryBuffer instanceof Uint8ClampedArray;
+        const isFloatOrWide = !is8Bit && (primaryBuffer instanceof Float32Array || primaryBuffer instanceof Uint16Array || primaryBuffer instanceof Int16Array);
+        // 1. SWISS MODE BRANCH
+        if (isSwiss) {
+            const reliefMask = dataArray[1];
+            const rangeSpan = (rangeMax - rangeMin) || 1;
+            // Only use LUT optimization for useHeatMap mode; other modes use calculateSingleColor per-pixel
+            let lut = null;
+            if (options.useHeatMap) {
+                const LUT_SIZE = 1024;
+                // Cache LUT: generate key from colorScale config + range + alpha
+                const cacheKey = `${rangeMin}_${rangeMax}_${optAlpha}_${JSON.stringify(options.colorScale)}`;
+                lut = this._swissColorLUTCache.get(cacheKey) || null;
+                if (!lut) {
+                    // LUT not cached, generate it
+                    lut = new Uint8ClampedArray(LUT_SIZE * 4);
+                    for (let i = 0; i < LUT_SIZE; i++) {
+                        const domainVal = rangeMin + (i / (LUT_SIZE - 1)) * rangeSpan;
+                        const rgb = colorScale(domainVal).rgb();
+                        lut[i * 4] = rgb[0];
+                        lut[i * 4 + 1] = rgb[1];
+                        lut[i * 4 + 2] = rgb[2];
+                        lut[i * 4 + 3] = optAlpha;
+                    }
+                    this._swissColorLUTCache.set(cacheKey, lut);
+                }
+            }
+            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);
+                if (Number.isNaN(elevationVal) || isNoData) {
+                    colorsArray.set(options.nullColor, i);
+                    continue;
+                }
+                let baseColor;
+                if (lut) {
+                    // LUT-optimized path for useHeatMap
+                    const t = (elevationVal - rangeMin) / rangeSpan;
+                    const lutIdx = Math.min(1023, Math.max(0, Math.floor(t * 1023))) * 4;
+                    baseColor = [lut[lutIdx], lut[lutIdx + 1], lut[lutIdx + 2], lut[lutIdx + 3]];
                 }
                 else {
-                    lut.set(this.calculateSingleColor(i, colorScale, options, optAlpha), i * 4);
+                    // Per-pixel calculation for useSingleColor, useColorClasses, useColorsBasedOnValues
+                    baseColor = this.calculateSingleColor(elevationVal, colorScale, options, optAlpha);
+                }
+                // Apply relief mask as multiplier (Ambient Fill approach)
+                const maskVal = reliefMask[sampleIndex];
+                const multiplier = 0.4 + 0.6 * (maskVal / 255);
+                colorsArray[i] = Math.floor(baseColor[0] * multiplier);
+                colorsArray[i + 1] = Math.floor(baseColor[1] * multiplier);
+                colorsArray[i + 2] = Math.floor(baseColor[2] * multiplier);
+                colorsArray[i + 3] = baseColor[3];
+            }
+            return colorsArray;
+        }
+        // 2. 8-BIT COMPREHENSIVE LUT
+        // Single-band 8-bit (grayscale or indexed): use LUT for fast mapping.
+        // The LUT covers all 256 possible values and is fixed for a given set of coloring options,
+        // so cache it across tiles (skip cache only when useAutoRange recomputes the range per tile).
+        if (is8Bit && !options.useDataForOpacity) {
+            const cacheKey = !options.useAutoRange ? this.getLUTCacheKey(options, rangeMin, rangeMax, optAlpha) : null;
+            let lut = cacheKey ? (this._8bitLUTCache.get(cacheKey) ?? null) : null;
+            if (!lut) {
+                lut = new Uint8ClampedArray(256 * 4);
+                for (let i = 0; i < 256; i++) {
+                    if ((options.clipLow != null && i <= options.clipLow) ||
+                        (options.clipHigh != null && i >= options.clipHigh)) {
+                        lut.set(options.clippedColor, i * 4);
+                    }
+                    else {
+                        lut.set(this.calculateSingleColor(i, colorScale, options, optAlpha), i * 4);
+                    }
                 }
+                if (cacheKey)
+                    this._8bitLUTCache.set(cacheKey, lut);
             }
             for (let i = 0, sampleIndex = (options.useChannelIndex ?? 0); i < arrayLength; i += 4, sampleIndex += samplesPerPixel) {
-                const lutIdx = dataArray[sampleIndex] * 4;
+                const lutIdx = primaryBuffer[sampleIndex] * 4;
                 colorsArray[i] = lut[lutIdx];
                 colorsArray[i + 1] = lut[lutIdx + 1];
                 colorsArray[i + 2] = lut[lutIdx + 2];
@@ -5709,27 +5840,36 @@ class BitmapGenerator {
             }
             return colorsArray;
         }
-        // 2. FLOAT / 16-BIT LUT (HEATMAP ONLY)
-        if (isFloatOrWide && options.useHeatMap && !options.useDataForOpacity) {
+        // 3. FLOAT / 16-BIT LUT (HEATMAP ONLY)
+        // Guard: only activate when heatmap is the highest-priority active mode.
+        // If a more specific mode (useSingleColor, useColorClasses, useColorsBasedOnValues) is set,
+        // fall through to the general loop so calculateSingleColor can honour the priority chain.
+        if (isFloatOrWide && options.useHeatMap && !options.useSingleColor && !options.useColorClasses && !options.useColorsBasedOnValues && !options.useDataForOpacity) {
             const LUT_SIZE = 1024;
-            const lut = new Uint8ClampedArray(LUT_SIZE * 4);
             const rangeSpan = (rangeMax - rangeMin) || 1;
-            for (let i = 0; i < LUT_SIZE; i++) {
-                const domainVal = rangeMin + (i / (LUT_SIZE - 1)) * rangeSpan;
-                if ((options.clipLow != null && domainVal <= options.clipLow) ||
-                    (options.clipHigh != null && domainVal >= options.clipHigh)) {
-                    lut.set(options.clippedColor, i * 4);
-                }
-                else {
-                    const rgb = colorScale(domainVal).rgb();
-                    lut[i * 4] = rgb[0];
-                    lut[i * 4 + 1] = rgb[1];
-                    lut[i * 4 + 2] = rgb[2];
-                    lut[i * 4 + 3] = optAlpha;
+            const cacheKey = !options.useAutoRange ? this.getLUTCacheKey(options, rangeMin, rangeMax, optAlpha) : null;
+            let lut = cacheKey ? (this._floatLUTCache.get(cacheKey) ?? null) : null;
+            if (!lut) {
+                lut = new Uint8ClampedArray(LUT_SIZE * 4);
+                for (let i = 0; i < LUT_SIZE; i++) {
+                    const domainVal = rangeMin + (i / (LUT_SIZE - 1)) * rangeSpan;
+                    if ((options.clipLow != null && domainVal <= options.clipLow) ||
+                        (options.clipHigh != null && domainVal >= options.clipHigh)) {
+                        lut.set(options.clippedColor, i * 4);
+                    }
+                    else {
+                        const rgb = colorScale(domainVal).rgb();
+                        lut[i * 4] = rgb[0];
+                        lut[i * 4 + 1] = rgb[1];
+                        lut[i * 4 + 2] = rgb[2];
+                        lut[i * 4 + 3] = optAlpha;
+                    }
                 }
+                if (cacheKey)
+                    this._floatLUTCache.set(cacheKey, lut);
             }
             for (let i = 0, sampleIndex = (options.useChannelIndex ?? 0); i < arrayLength; i += 4, sampleIndex += samplesPerPixel) {
-                const val = dataArray[sampleIndex];
+                const val = primaryBuffer[sampleIndex];
                 if (this.isInvalid(val, options)) {
                     colorsArray.set(this.getInvalidColor(val, options), i);
                 }
@@ -5744,10 +5884,10 @@ class BitmapGenerator {
             }
             return colorsArray;
         }
-        // 3. FALLBACK LOOP (Categorical Float, Opacity, or Single Color)
+        // 4. FALLBACK LOOP (Categorical Float, Opacity, or Single Color)
         let sampleIndex = options.useChannelIndex ?? 0;
         for (let i = 0; i < arrayLength; i += 4) {
-            const val = dataArray[sampleIndex];
+            const val = primaryBuffer[sampleIndex];
             let color;
             if ((options.clipLow != null && val <= options.clipLow) || (options.clipHigh != null && val >= options.clipHigh)) {
                 color = options.clippedColor;
@@ -5763,6 +5903,50 @@ class BitmapGenerator {
         }
         return colorsArray;
     }
+    /**
+     * Generate relief glaze RGBA output.
+     * Maps relief mask (0-255) to pure black/white glaze with variable alpha.
+     * - reliefValue < 128: Pure black (0,0,0) darkens shadows
+     * - reliefValue > 128: Pure white (255,255,255) brightens highlights
+     * - reliefValue == 128: Transparent (no effect)
+     *
+     * High-performance implementation using pre-computed alpha LUT to avoid 65k Math.pow calls.
+     *
+     * @param rasters Array of [relief mask raster] (single raster expected)
+     * @param options GeoImageOptions (alpha used for opacity scaling)
+     * @param arrayLength Total RGBA array length
+     * @returns Uint8ClampedArray of RGBA values
+     */
+    static getReliefGlazeRGBA(rasters, options, arrayLength) {
+        const reliefMask = rasters[0];
+        const opacityFactor = (options.maxGlazeAlpha ?? 128) / 255;
+        // Pre-compute alpha lookup table (256 entries, one per relief value 0-255)
+        const alphaLookup = new Uint8Array(256);
+        for (let v = 0; v < 256; v++) {
+            if (v === 0) {
+                alphaLookup[v] = 0; // noData: fully transparent
+            }
+            else {
+                const alphaDist = Math.abs(v - 128) / 128;
+                const bias = v < 128 ? 0.6 : 0.8;
+                alphaLookup[v] = Math.floor(Math.pow(alphaDist, bias) * 255 * opacityFactor);
+            }
+        }
+        const glazeArray = new Uint8ClampedArray(arrayLength);
+        let maskIndex = 0;
+        for (let i = 0; i < arrayLength; i += 4) {
+            const reliefValue = reliefMask[maskIndex];
+            // Pure black for shadows, pure white for highlights (no muddy grays)
+            const glaze = reliefValue < 128 ? 0 : 255;
+            const alpha = alphaLookup[reliefValue];
+            glazeArray[i] = glaze; // R
+            glazeArray[i + 1] = glaze; // G
+            glazeArray[i + 2] = glaze; // B
+            glazeArray[i + 3] = alpha; // A
+            maskIndex++;
+        }
+        return glazeArray;
+    }
     static calculateSingleColor(val, colorScale, options, alpha) {
         if (this.isInvalid(val, options)) {
             return options.nullColor;
@@ -5843,6 +6027,21 @@ class BitmapGenerator {
  * Output: Float32Array of 256×256 computed values.
  */
 class KernelGenerator {
+    /**
+     * Compute terrain gradients (dzdx, dzdy) using Horn's method.
+     * @param z1-z9 - 3×3 neighborhood elevation values (z5 is center)
+     * @param cellSizeFactor - Pre-computed 1 / (8 * cellSize)
+     * @param geographicConvention - If true, use north-minus-south for dzdy (hillshade). If false, use south-minus-north (slope).
+     */
+    static computeGradients(z1, z2, z3, z4, /* z5 not needed */ z6, z7, z8, z9, cellSizeFactor, geographicConvention = true) {
+        const dzdx = ((z3 + 2 * z6 + z9) - (z1 + 2 * z4 + z7)) * cellSizeFactor;
+        // Geographic convention (hillshade): north minus south (top rows minus bottom rows)
+        // Slope convention: south minus north (reversed)
+        const dzdy = geographicConvention
+            ? ((z1 + 2 * z2 + z3) - (z7 + 2 * z8 + z9)) * cellSizeFactor
+            : ((z7 + 2 * z8 + z9) - (z1 + 2 * z2 + z3)) * cellSizeFactor;
+        return { dzdx, dzdy };
+    }
     /**
      * Calculates slope (0–90 degrees) for each pixel using Horn's method.
      *
@@ -5855,12 +6054,18 @@ class KernelGenerator {
         const OUT = 256;
         const IN = 258;
         const out = new Float32Array(OUT * OUT);
+        // Hoist division out of loop: multiplication is ~2-3x faster than division
+        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
-                if (noDataValue !== undefined && z5 === noDataValue) {
+                const isNoData = noDataValue !== undefined && (isNaNNoData ? Number.isNaN(z5) : z5 === noDataValue);
+                if (isNoData) {
                     out[r * OUT + c] = NaN;
                     continue;
                 }
@@ -5872,10 +6077,9 @@ class KernelGenerator {
                 const z7 = src[base + 2 * IN]; // sw
                 const z8 = src[base + 2 * IN + 1]; // s
                 const z9 = src[base + 2 * IN + 2]; // se
-                const dzdx = ((z3 + 2 * z6 + z9) - (z1 + 2 * z4 + z7)) / (8 * cellSize);
-                const dzdy = ((z7 + 2 * z8 + z9) - (z1 + 2 * z2 + z3)) / (8 * cellSize);
+                const { dzdx, dzdy } = this.computeGradients(z1, z2, z3, z4, z6, z7, z8, z9, cellSizeFactor, false);
                 const slopeRad = Math.atan(zFactor * Math.sqrt(dzdx * dzdx + dzdy * dzdy));
-                out[r * OUT + c] = slopeRad * (180 / Math.PI);
+                out[r * OUT + c] = slopeRad * RAD_TO_DEG;
             }
         }
         return out;
@@ -5900,11 +6104,15 @@ class KernelGenerator {
         if (azimuthMath >= 360)
             azimuthMath -= 360;
         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
-                if (noDataValue !== undefined && z5 === noDataValue) {
+                const isNoData = noDataValue !== undefined && (isNaNNoData ? Number.isNaN(z5) : z5 === noDataValue);
+                if (isNoData) {
                     out[r * OUT + c] = NaN;
                     continue;
                 }
@@ -5916,9 +6124,7 @@ class KernelGenerator {
                 const z7 = src[base + 2 * IN]; // sw
                 const z8 = src[base + 2 * IN + 1]; // s
                 const z9 = src[base + 2 * IN + 2]; // se
-                const dzdx = ((z3 + 2 * z6 + z9) - (z1 + 2 * z4 + z7)) / (8 * cellSize);
-                // dzdy: north minus south (geographic convention — top rows minus bottom rows in raster)
-                const dzdy = ((z1 + 2 * z2 + z3) - (z7 + 2 * z8 + z9)) / (8 * cellSize);
+                const { dzdx, dzdy } = this.computeGradients(z1, z2, z3, z4, z6, z7, z8, z9, cellSizeFactor, true);
                 const slopeRad = Math.atan(zFactor * Math.sqrt(dzdx * dzdx + dzdy * dzdy));
                 const aspectRad = Math.atan2(dzdy, -dzdx);
                 const hillshade = 255 * (Math.cos(zenithRad) * Math.cos(slopeRad) +
@@ -5928,6 +6134,139 @@ class KernelGenerator {
         }
         return out;
     }
+    /**
+     * Calculates a weighted multi-directional hillshade (0–255).
+     * Combines three light sources to reveal structure in shadows.
+     */
+    static calculateMultiHillshade(src, cellSize, zFactor = 1, noDataValue) {
+        const OUT = 256;
+        const IN = 258;
+        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
+            { az: 225, alt: 35, weight: 0.25 }, // Secondary West/SW
+            { az: 0, alt: 35, weight: 0.15 } // Secondary North
+        ].map(l => {
+            const zenithRad = (90 - l.alt) * (Math.PI / 180);
+            let azMath = 360 - l.az + 90;
+            if (azMath >= 360)
+                azMath -= 360;
+            return {
+                zCos: Math.cos(zenithRad),
+                zSin: Math.sin(zenithRad),
+                aRad: azMath * (Math.PI / 180),
+                w: l.weight
+            };
+        });
+        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];
+                const isNoData = noDataValue !== undefined && (isNaNNoData ? Number.isNaN(z5) : z5 === noDataValue);
+                if (isNoData) {
+                    out[r * OUT + c] = NaN;
+                    continue;
+                }
+                // Neighbors
+                const z1 = src[base], z2 = src[base + 1], z3 = src[base + 2];
+                const z4 = src[base + IN], z6 = src[base + IN + 2];
+                const z7 = src[base + 2 * IN], z8 = src[base + 2 * IN + 1], z9 = src[base + 2 * IN + 2];
+                const { dzdx, dzdy } = this.computeGradients(z1, z2, z3, z4, z6, z7, z8, z9, cellSizeFactor, true);
+                const slopeRad = Math.atan(zFactor * Math.sqrt(dzdx * dzdx + dzdy * dzdy));
+                const aspectRad = Math.atan2(dzdy, -dzdx);
+                const cosSlope = Math.cos(slopeRad);
+                const sinSlope = Math.sin(slopeRad);
+                // Accumulate light from all three directions
+                let multiHillshade = 0;
+                for (const L of lights) {
+                    const intensity = L.zCos * cosSlope + L.zSin * sinSlope * Math.cos(L.aRad - aspectRad);
+                    multiHillshade += Math.max(0, intensity) * L.w;
+                }
+                out[r * OUT + c] = Math.min(255, multiHillshade * 255);
+            }
+        }
+        return out;
+    }
+}
+
+/**
+ * Composes Swiss relief by combining slope and hillshade kernels via LUT.
+ * Outputs a single 0-255 relief mask suitable for baking into hypsometry (terrain)
+ * or creating transparent glaze overlays (bitmap).
+ */
+class ReliefCompositor {
+    /**
+     * Precompute and cache a 256x256 LUT for Swiss relief compositing.
+     * LUT[hillshade][slope] = (hillshade * (1.0 - (slope * weight)))
+     * All values normalized to [0,1].
+     * Only computed on first use of Swiss relief mode.
+     */
+    static _swissReliefLUT = null;
+    static _lastWeight = null;
+    static getSwissReliefLUT(weight = 0.5) {
+        // Check if LUT exists AND if the weight matches the previous calculation
+        if (this._swissReliefLUT && this._lastWeight === weight) {
+            return this._swissReliefLUT;
+        }
+        const ambient = 0.010; // 1% minimum brightness to prevent pitch black northwest slopes
+        const lut = new Float32Array(256 * 256); // 65536 values
+        for (let h = 0; h < 256; h++) {
+            const hillshade = h / 255;
+            for (let s = 0; s < 256; s++) {
+                const slope = s / 255;
+                // 1. Calculate the 'Swiss Contrast'
+                const contrast = 1.0 - (slope * weight);
+                // Swiss Formula: (Hillshade) * (1.0 - (Slope * Weight))
+                // This results in 0.0 to 1.0 multiplier
+                lut[(h << 8) | s] = Math.max(ambient, hillshade * contrast);
+            }
+        }
+        this._swissReliefLUT = lut;
+        this._lastWeight = weight;
+        return lut;
+    }
+    /**
+     * Compute Swiss relief compositing: slope + hillshade → 0-255 relief mask.
+     *
+     * @param elevation - Padded elevation raster (258×258 for kernel input)
+     * @param options - GeoImageOptions (must include zFactor, noDataValue, swissSlopeWeight)
+     * @param cellSize - Grid cell size in meters
+     * @param width - Output width (typically 256)
+     * @param height - Output height (typically 256)
+     * @returns Uint8ClampedArray of 0-255 relief values
+     */
+    static composeSwissRelief(elevation, options, cellSize, width, height) {
+        const weight = options.swissSlopeWeight ?? 0.5;
+        // 1. Compute slope and hillshade kernels
+        const rawSlope = KernelGenerator.calculateSlope(elevation, cellSize, options.zFactor ?? 1, options.noDataValue);
+        const rawHillshade = KernelGenerator.calculateMultiHillshade(elevation, cellSize, options.zFactor ?? 1, options.noDataValue);
+        // 2. Fetch pre-computed LUT
+        const lut = this.getSwissReliefLUT(weight);
+        // 3. Compose relief mask: quantize slope/hillshade, apply LUT
+        // reliefMask = 0 is reserved as noData sentinel → fully transparent in glaze output
+        const reliefMask = new Uint8ClampedArray(width * height);
+        // Hoist division out of loop: multiplication is faster than division
+        const SLOPE_SCALE = 255 / 90; // ~2.833...
+        for (let i = 0; i < width * height; i++) {
+            // noData pixels: slope is NaN (set by KernelGenerator when z5 === noDataValue)
+            if (isNaN(rawSlope[i])) {
+                reliefMask[i] = 0; // sentinel: transparent in glaze
+                continue;
+            }
+            // Quantize Slope: Normalize 0-90° to 0-255 integer (avoid division in loop)
+            const sIdx = Math.max(0, Math.min(255, (rawSlope[i] * SLOPE_SCALE) | 0));
+            // Quantize Hillshade: Ensure 0-255 integer
+            const hIdx = Math.max(0, Math.min(255, rawHillshade[i])) | 0;
+            // LUT Lookup: Result is 0.0 - 1.0 (float)
+            // Clamp to 1 to ensure output stays in 1-255 (0 is reserved for noData)
+            reliefMask[i] = Math.max(1, (lut[(hIdx << 8) | sIdx] * 255) | 0);
+        }
+        return reliefMask;
+    }
 }
 
 class TerrainGenerator {
@@ -5991,7 +6330,20 @@ class TerrainGenerator {
             height: gridHeight,
         };
         // 3. Kernel path: compute slope or hillshade, store as rawDerived, generate texture
-        if (isKernel && (options.useSlope || options.useHillshade)) {
+        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.
+            const kernelTerrain = this.preserveNoDataForKernel(terrain, input.rasters[0], options.noDataValue);
+            // Compose Swiss relief using ReliefCompositor
+            const swissReliefResult = ReliefCompositor.composeSwissRelief(kernelTerrain, options, cellSize, 256, 256);
+            tileResult.rawDerived = swissReliefResult;
+            if (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;
+            }
+        }
+        else if (isKernel && (options.useSlope || options.useHillshade)) {
             // Use pre-computed geographic cellSize (meters/pixel) from tile indices.
             // Falls back to bounds-derived estimate if not provided.
             const cellSize = input.cellSizeMeters ?? ((input.bounds[2] - input.bounds[0]) / 256);
@@ -6001,23 +6353,7 @@ class TerrainGenerator {
                 console.warn('[TerrainGenerator] useSlope and useHillshade are mutually exclusive; useSlope takes precedence.');
             }
             // Build a separate raster for kernel computation that preserves noData samples.
-            const kernelTerrain = new Float32Array(terrain.length);
-            const sourceRaster = input.rasters[0];
-            const noData = options.noDataValue;
-            if (noData !== undefined &&
-                noData !== null &&
-                sourceRaster &&
-                sourceRaster.length === terrain.length) {
-                for (let i = 0; i < terrain.length; i++) {
-                    // If the source raster marks this sample as noData, keep it as noData for the kernel.
-                    // Otherwise, use the processed terrain elevation value.
-                    kernelTerrain[i] = sourceRaster[i] == noData ? noData : terrain[i];
-                }
-            }
-            else {
-                // Fallback: no usable noData metadata or mismatched lengths; mirror existing behavior.
-                kernelTerrain.set(terrain);
-            }
+            const kernelTerrain = this.preserveNoDataForKernel(terrain, input.rasters[0], options.noDataValue);
             let kernelOutput;
             if (options.useSlope) {
                 kernelOutput = KernelGenerator.calculateSlope(kernelTerrain, cellSize, zFactor, options.noDataValue);
@@ -6039,7 +6375,6 @@ class TerrainGenerator {
         }
         return tileResult;
     }
-    /** Extracts rows 1–257, cols 1–257 from a 258×258 terrain array → 257×257 for mesh generation. */
     static extractMeshRaster(terrain258) {
         const MESH = 257;
         const IN = 258;
@@ -6052,11 +6387,38 @@ class TerrainGenerator {
         return out;
     }
     static hasVisualizationOptions(options) {
-        return !!(options.useHeatMap ||
-            options.useSingleColor ||
+        return !!(options.useSingleColor ||
+            options.useHeatMap ||
+            options.useSwissRelief ||
             options.useColorsBasedOnValues ||
             options.useColorClasses);
     }
+    /**
+     * Preserve noData values in a separate raster for kernel computation.
+     * If the source raster marks a sample as noData, keep it as noData.
+     * Otherwise, use the processed terrain elevation value.
+     */
+    static preserveNoDataForKernel(terrain, sourceRaster, noDataValue) {
+        const kernelTerrain = new Float32Array(terrain.length);
+        if (noDataValue !== undefined &&
+            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;
+                kernelTerrain[i] = isNoData ? noDataValue : terrain[i];
+            }
+        }
+        else {
+            // Fallback: no usable noData metadata or mismatched lengths; mirror existing behavior.
+            kernelTerrain.set(terrain);
+        }
+        return kernelTerrain;
+    }
     static cropRaster(src, srcWidth, _srcHeight, dstWidth, dstHeight) {
         const out = new Float32Array(dstWidth * dstHeight);
         for (let y = 0; y < dstHeight; y++) {
@@ -6181,7 +6543,7 @@ class GeoImage {
         this.data = data;
     }
     async getMap(input, options, meshMaxError) {
-        const mergedOptions = { ...DefaultGeoImageOptions, ...options };
+        const mergedOptions = GeoImage.resolveVisualizationMode({ ...DefaultGeoImageOptions, ...options }, options);
         switch (mergedOptions.type) {
             case 'image':
                 return this.getBitmap(input, mergedOptions);
@@ -6191,6 +6553,56 @@ class GeoImage {
                 return null;
         }
     }
+    /**
+     * Resolves the active visualization (coloring) mode after merging user options with defaults.
+     *
+     * Solves three key issues:
+     *
+     * 1. **Mutual exclusivity**: `DefaultGeoImageOptions` sets `useHeatMap: true`. If a user
+     *    explicitly enables a coloring mode without explicitly setting `useHeatMap: false`,
+     *    enforce that only the explicitly-enabled modes are active (all others forced to false).
+     *    This prevents the default `useHeatMap: true` from interfering with user-chosen modes.
+     *
+     * 2. **Bitmap default**: for `type === 'image'` with no user-specified coloring mode,
+     *    keep `useHeatMap: true` from defaults. This provides sensible data-driven visualization.
+     *
+     * 3. **Terrain default**: for `type === 'terrain'` with no user-specified coloring mode and
+     *    no kernel-texture mode (`useSwissRelief` / `useSlope` / `useHillshade`), enable
+     *    `useSingleColor` with `color = terrainColor`. This renders the mesh in the documented
+     *    default colour (grey) without a data-driven texture overlay. When a kernel mode IS
+     *    present but no coloring mode is specified, keep `useHeatMap: true` so the kernel output
+     *    is still colourised.
+     */
+    static resolveVisualizationMode(mergedOptions, userOptions) {
+        const coloringModes = ['useSingleColor', 'useColorClasses', 'useColorsBasedOnValues', 'useHeatMap'];
+        const userExplicitColoringModes = coloringModes.filter(m => userOptions[m] === true);
+        const resolved = { ...mergedOptions };
+        if (userExplicitColoringModes.length > 0) {
+            // Enforce mutual exclusivity: disable all coloring modes, then enable only those
+            // explicitly set by the user. This prevents the default useHeatMap from interfering.
+            for (const mode of coloringModes) {
+                resolved[mode] = false;
+            }
+            for (const mode of userExplicitColoringModes) {
+                resolved[mode] = true;
+            }
+        }
+        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.
+                // 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.
+        }
+        // For 'image' with no explicit coloring mode: keep useHeatMap: true from DefaultGeoImageOptions.
+        return resolved;
+    }
     // GetHeightmap uses only "useChannel" and "multiplier" options
     async getHeightmap(input, options, meshMaxError) {
         let rasters = [];
@@ -6534,19 +6946,37 @@ class CogTiles {
     async getTile(x, y, z, bounds, meshMaxError) {
         let requiredSize = this.tileSize; // Default 256 for image/bitmap
         if (this.options.type === 'terrain') {
-            const isKernel = this.options.useSlope || this.options.useHillshade;
+            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);
         // Compute true ground cell size in meters from tile indices.
         // Tile y in slippy-map convention → center latitude → Web Mercator distortion correction.
         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;
+        }
         return this.geo.getMap({
-            rasters: [tileData[0]],
-            width: requiredSize,
-            height: requiredSize,
+            rasters,
+            width: tileWidth,
+            height: tileHeight,
             bounds,
             cellSizeMeters,
         }, this.options, meshMaxError);
@@ -6759,13 +7189,20 @@ class CogBitmapLayer extends CompositeLayer {
         }
     }
     async getTiledBitmapData(tile) {
-        // TODO - pass signal to getTile
-        // abort request if signal is aborted
-        const tileData = await this.state.bitmapCogTiles.getTile(tile.index.x, tile.index.y, tile.index.z);
-        if (tileData && !this.props.pickable) {
-            tileData.raw = null;
+        try {
+            // TODO - pass signal to getTile
+            // abort request if signal is aborted
+            const tileData = await this.state.bitmapCogTiles.getTile(tile.index.x, tile.index.y, tile.index.z);
+            if (tileData && !this.props.pickable) {
+                tileData.raw = null;
+            }
+            return tileData;
+        }
+        catch (error) {
+            // Log the error and rethrow so TileLayer can surface the failure via onTileError
+            log.warn(`Failed to load bitmap tile at ${tile.index.z}/${tile.index.x}/${tile.index.y}:`, error)();
+            throw error;
         }
-        return tileData;
     }
     renderSubLayers(props) {
         const SubLayerClass = this.getSubLayerClass('image', BitmapLayer);
@@ -7008,15 +7445,28 @@ class CogTerrainLayer extends CompositeLayer {
     }
     renderSubLayers(props) {
         const SubLayerClass = this.getSubLayerClass('mesh', SimpleMeshLayer);
-        const { color, wireframe, material } = this.props;
+        const { color, wireframe, terrainOptions } = this.props;
         const { data } = props;
         if (!data) {
             return null;
         }
-        // const [mesh, texture] = data;
         const [meshResult] = data;
         const tileTexture = (!this.props.disableTexture && meshResult?.texture) ? meshResult.texture : null;
+        const isSwiss = terrainOptions?.useSwissRelief;
+        const disableLighting = terrainOptions?.disableLighting;
+        const shouldDisableLighting = isSwiss || disableLighting;
+        const lightingProps = shouldDisableLighting ? {
+            material: {
+                ambient: 1.0,
+                diffuse: 0.0,
+                shininess: 0.0,
+                specularColor: [0, 0, 0]
+            }
+        } : {
+            material: this.props.material
+        };
         return new SubLayerClass({ ...props, tileSize: props.tileSize }, {
+            ...lightingProps,
             data: DUMMY_DATA,
             mesh: meshResult?.map,
             texture: tileTexture,
@@ -7026,7 +7476,6 @@ class CogTerrainLayer extends CompositeLayer {
             // getPosition: (d) => [0, 0, 0],
             getColor: tileTexture ? [255, 255, 255] : color,
             wireframe,
-            material,
         });
     }
     // Update zRange of viewport
@@ -7073,13 +7522,14 @@ class CogTerrainLayer extends CompositeLayer {
                 updateTriggers: {
                     getTileData: {
                         elevationData: urlTemplateToUpdateTrigger(elevationData),
-                        // texture: urlTemplateToUpdateTrigger(texture),
                         meshMaxError,
                         elevationDecoder,
-                        // When cogTiles instance is swapped (e.g. mode switch), refetch tiles.
-                        // deck.gl keeps old tile content visible until new tiles are ready.
                         terrainCogTiles: this.state.terrainCogTiles,
                     },
+                    renderSubLayers: {
+                        disableTexture: this.props.disableTexture,
+                        terrainOptions: this.props.terrainOptions,
+                    },
                 },
                 onViewportLoad: this.onViewportLoad.bind(this),
                 zRange: this.state.zRange || null,