@gisatcz/deckgl-geolib 2.3.1-dev.1 → 2.4.0-dev.2

package/dist/esm/index.js

@@ -4515,37 +4515,46 @@ async function fromArrayBuffer(arrayBuffer, signal) {
 
 // types.ts
 const DefaultGeoImageOptions = {
+    // --- Shared / Data ---
     type: 'image',
-    tesselator: 'martini',
     format: undefined,
+    useChannel: null,
+    useChannelIndex: null,
+    noDataValue: undefined,
+    multiplier: 1.0,
+    numOfChannels: undefined,
+    planarConfig: undefined,
+    // --- Mesh generation (terrain only) ---
+    tesselator: 'martini',
+    terrainColor: [133, 133, 133, 255],
+    terrainSkirtHeight: 100,
+    // Default fallback for invalid/nodata elevations. Should be configured based on the dataset's actual range.
+    terrainMinValue: 0,
+    // --- Texture / Visualization ---
     useHeatMap: true,
     useColorsBasedOnValues: false,
+    useColorClasses: false,
     useAutoRange: false,
     useDataForOpacity: false,
     useSingleColor: false,
-    useColorClasses: false,
     blurredTexture: true,
     clipLow: null,
     clipHigh: null,
-    multiplier: 1.0,
     color: [255, 0, 255, 255],
     colorScale: chroma.brewer.YlOrRd,
     colorScaleValueRange: [0, 255],
     colorsBasedOnValues: undefined,
     colorClasses: undefined,
     alpha: 100,
-    useChannel: null,
-    useChannelIndex: null,
-    noDataValue: undefined,
-    numOfChannels: undefined,
     nullColor: [0, 0, 0, 0],
     unidentifiedColor: [0, 0, 0, 0],
     clippedColor: [0, 0, 0, 0],
-    terrainColor: [133, 133, 133, 255],
-    terrainSkirtHeight: 100,
-    // Default fallback for invalid/nodata elevations. Should be configured based on the dataset's actual range.
-    terrainMinValue: 0,
-    planarConfig: undefined,
+    // --- Kernel-specific (terrain only) ---
+    useSlope: false,
+    useHillshade: false,
+    hillshadeAzimuth: 315,
+    hillshadeAltitude: 45,
+    zFactor: 1,
 };
 
 class Martini {
@@ -5223,29 +5232,384 @@ function updateAttributesForNewEdge({ edge, edgeIndex, attributes, skirtHeight,
     newTriangles[triangle1Offset + 5] = positionsLength / 3 + vertex1Offset;
 }
 
+// DataUtils.ts
+function scale(num, inMin, inMax, outMin, outMax) {
+    if (inMax === inMin) {
+        return outMin;
+    }
+    return ((num - inMin) * (outMax - outMin)) / (inMax - inMin) + outMin;
+}
+
+class BitmapGenerator {
+    /**
+     * Main entry point: Generates an ImageBitmap from raw raster data.
+     */
+    static async generate(input, options) {
+        const optionsLocal = { ...options };
+        const { rasters, width, height } = input;
+        // NOTE: As of 2026-03, only interleaved rasters (rasters.length === 1) are produced by the main COG tile path.
+        // Planar (rasters.length > 1) is not currently supported in production, but this check is kept for future extension.
+        const isInterleaved = rasters.length === 1;
+        const canvas = document.createElement('canvas');
+        canvas.width = width;
+        canvas.height = height;
+        const c = canvas.getContext('2d');
+        const imageData = c.createImageData(width, height);
+        const size = width * height * 4;
+        const alpha255 = Math.floor(optionsLocal.alpha * 2.55);
+        // Normalize colors using chroma
+        optionsLocal.unidentifiedColor = this.getColorFromChromaType(optionsLocal.unidentifiedColor, alpha255);
+        optionsLocal.nullColor = this.getColorFromChromaType(optionsLocal.nullColor, alpha255);
+        optionsLocal.clippedColor = this.getColorFromChromaType(optionsLocal.clippedColor, alpha255);
+        optionsLocal.color = this.getColorFromChromaType(optionsLocal.color, alpha255);
+        optionsLocal.useChannelIndex ??= optionsLocal.useChannel == null ? null : optionsLocal.useChannel - 1;
+        // Derive channel count from data if not provided
+        // 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 (isInterleaved) {
+                const ratio = rasters[0].length / (width * height);
+                if (ratio === 1) {
+                    if (optionsLocal.useAutoRange) {
+                        optionsLocal.colorScaleValueRange = this.getMinMax(rasters[0], optionsLocal);
+                    }
+                    imageData.data.set(this.getColorValue(rasters[0], optionsLocal, size));
+                } // 3 or 4-band RGB(A) imagery: use per-pixel loop for direct color assignment
+                else if (ratio === 3 || ratio === 4) {
+                    let sampleIndex = 0;
+                    for (let i = 0; i < size; i += 4) {
+                        const rgbColor = [rasters[0][sampleIndex], rasters[0][sampleIndex + 1], rasters[0][sampleIndex + 2]];
+                        const isNoData = this.hasPixelsNoData(rgbColor, optionsLocal.noDataValue);
+                        imageData.data[i] = isNoData ? optionsLocal.nullColor[0] : rgbColor[0];
+                        imageData.data[i + 1] = isNoData ? optionsLocal.nullColor[1] : rgbColor[1];
+                        imageData.data[i + 2] = isNoData ? optionsLocal.nullColor[2] : rgbColor[2];
+                        imageData.data[i + 3] = isNoData ? optionsLocal.nullColor[3] : (ratio === 4 ? rasters[0][sampleIndex + 3] : alpha255);
+                        sampleIndex += ratio;
+                    }
+                }
+            }
+            else {
+                let sampleIndex = 0;
+                for (let i = 0; i < size; i += 4) {
+                    imageData.data[i] = rasters[0][sampleIndex];
+                    imageData.data[i + 1] = rasters[1][sampleIndex];
+                    imageData.data[i + 2] = rasters[2][sampleIndex];
+                    imageData.data[i + 3] = rasters.length === 4 ? rasters[3][sampleIndex] : alpha255;
+                    sampleIndex++;
+                }
+            }
+        }
+        else if (optionsLocal.useChannelIndex < numAvailableChannels && optionsLocal.useChannelIndex >= 0) {
+            const isInterleaved = rasters.length === 1 && numAvailableChannels > 1;
+            const channel = isInterleaved ? rasters[0] : (rasters[optionsLocal.useChannelIndex] ?? rasters[0]);
+            const samplesPerPixel = isInterleaved ? numAvailableChannels : 1;
+            if (optionsLocal.useAutoRange) {
+                optionsLocal.colorScaleValueRange = this.getMinMax(channel, optionsLocal, samplesPerPixel);
+            }
+            imageData.data.set(this.getColorValue(channel, optionsLocal, size, samplesPerPixel));
+        }
+        else {
+            // if user defined channel does not exist
+            /* eslint-disable no-console */
+            console.log(`Defined channel(${options.useChannel}) or channel index(${options.useChannelIndex}) does not exist, choose a different channel or set the useChannel property to null if you want to visualize RGB(A) imagery`);
+            const defaultColorData = this.getDefaultColor(size, optionsLocal.nullColor);
+            defaultColorData.forEach((value, index) => {
+                imageData.data[index] = value;
+            });
+        }
+        // Optimization: Skip Canvas -> PNG encoding -> Base64 string
+        // Return raw GPU-ready ImageBitmap directly
+        // Note: createImageBitmap(imageData) is cleaner, but using the canvas ensures broad compatibility
+        c.putImageData(imageData, 0, 0);
+        const map = await createImageBitmap(canvas);
+        // rasters[0] is the interleaved buffer on the CogTiles path (primary use case).
+        // For planar multi-band GeoTIFFs via GeoImage.getBitmap(), only the first band is exposed here.
+        // Full multi-band raw picking support is tracked in https://github.com/Gisat/deck.gl-geotiff/issues/98
+        return { map, raw: rasters[0], width, height };
+    }
+    static getColorValue(dataArray, options, arrayLength, samplesPerPixel = 1) {
+        // Normalize all colorScale entries for chroma.js compatibility
+        const colorScale = chroma.scale(options.colorScale?.map(c => Array.isArray(c) ? chroma(c) : c)).domain(options.colorScaleValueRange);
+        const colorsArray = new Uint8ClampedArray(arrayLength);
+        const optAlpha = Math.floor(options.alpha * 2.55);
+        const rangeMin = options.colorScaleValueRange[0];
+        const rangeMax = options.colorScaleValueRange.slice(-1)[0];
+        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);
+                }
+                else {
+                    lut.set(this.calculateSingleColor(i, colorScale, options, optAlpha), i * 4);
+                }
+            }
+            for (let i = 0, sampleIndex = (options.useChannelIndex ?? 0); i < arrayLength; i += 4, sampleIndex += samplesPerPixel) {
+                const lutIdx = dataArray[sampleIndex] * 4;
+                colorsArray[i] = lut[lutIdx];
+                colorsArray[i + 1] = lut[lutIdx + 1];
+                colorsArray[i + 2] = lut[lutIdx + 2];
+                colorsArray[i + 3] = lut[lutIdx + 3];
+            }
+            return colorsArray;
+        }
+        // 2. FLOAT / 16-BIT LUT (HEATMAP ONLY)
+        if (isFloatOrWide && options.useHeatMap && !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;
+                }
+            }
+            for (let i = 0, sampleIndex = (options.useChannelIndex ?? 0); i < arrayLength; i += 4, sampleIndex += samplesPerPixel) {
+                const val = dataArray[sampleIndex];
+                if (this.isInvalid(val, options)) {
+                    colorsArray.set(this.getInvalidColor(val, options), i);
+                }
+                else {
+                    const t = (val - rangeMin) / rangeSpan;
+                    const lutIdx = Math.min(LUT_SIZE - 1, Math.max(0, Math.floor(t * (LUT_SIZE - 1)))) * 4;
+                    colorsArray[i] = lut[lutIdx];
+                    colorsArray[i + 1] = lut[lutIdx + 1];
+                    colorsArray[i + 2] = lut[lutIdx + 2];
+                    colorsArray[i + 3] = lut[lutIdx + 3];
+                }
+            }
+            return colorsArray;
+        }
+        // 3. 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];
+            let color;
+            if ((options.clipLow != null && val <= options.clipLow) || (options.clipHigh != null && val >= options.clipHigh)) {
+                color = options.clippedColor;
+            }
+            else {
+                color = this.calculateSingleColor(val, colorScale, options, optAlpha);
+            }
+            if (options.useDataForOpacity && !this.isInvalid(val, options)) {
+                color[3] = scale(val, rangeMin, rangeMax, 0, 255);
+            }
+            colorsArray.set(color, i);
+            sampleIndex += samplesPerPixel;
+        }
+        return colorsArray;
+    }
+    static calculateSingleColor(val, colorScale, options, alpha) {
+        if (this.isInvalid(val, options)) {
+            return options.nullColor;
+        }
+        // Color mode priority (most specific wins):
+        // 1. useSingleColor
+        // 2. useColorClasses
+        // 3. useColorsBasedOnValues
+        // 4. useHeatMap
+        // Only the first enabled mode is used.
+        if (options.useSingleColor) {
+            return options.color;
+        }
+        else if (options.useColorClasses) {
+            const index = this.findClassIndex(val, options);
+            return index > -1 ? [...chroma(Array.isArray(options.colorClasses[index][0]) ? chroma(options.colorClasses[index][0]) : options.colorClasses[index][0]).rgb(), alpha] : options.unidentifiedColor;
+        }
+        else if (options.useColorsBasedOnValues) {
+            const match = options.colorsBasedOnValues?.find(([v]) => v === val);
+            return match ? [...chroma(Array.isArray(match[1]) ? chroma(match[1]) : match[1]).rgb(), alpha] : options.unidentifiedColor;
+        }
+        else if (options.useHeatMap) {
+            return [...colorScale(val).rgb(), alpha];
+        }
+        return options.unidentifiedColor;
+    }
+    static findClassIndex(val, options) {
+        if (!options.colorClasses)
+            return -1;
+        for (let i = 0; i < options.colorClasses.length; i++) {
+            const [, [min, max], bounds] = options.colorClasses[i];
+            const [incMin, incMax] = bounds || (i === options.colorClasses.length - 1 ? [true, true] : [true, false]);
+            if ((incMin ? val >= min : val > min) && (incMax ? val <= max : val < max))
+                return i;
+        }
+        return -1;
+    }
+    static getDefaultColor(size, nullColor) {
+        const colorsArray = new Uint8ClampedArray(size);
+        for (let i = 0; i < size; i += 4) {
+            [colorsArray[i], colorsArray[i + 1], colorsArray[i + 2], colorsArray[i + 3]] = nullColor;
+        }
+        return colorsArray;
+    }
+    static isInvalid(val, options) {
+        return Number.isNaN(val) || (options.noDataValue !== undefined && val === options.noDataValue);
+    }
+    static getInvalidColor(val, options) {
+        return options.nullColor;
+    }
+    static getMinMax(array, options, samplesPerPixel = 1) {
+        let max = -Infinity, min = Infinity;
+        for (let i = (options.useChannelIndex ?? 0); i < array.length; i += samplesPerPixel) {
+            const val = array[i];
+            if (!this.isInvalid(val, options)) {
+                if (val > max)
+                    max = val;
+                if (val < min)
+                    min = val;
+            }
+        }
+        return max === -Infinity ? (options.colorScaleValueRange || [0, 255]) : [min, max];
+    }
+    static getColorFromChromaType(color, alpha = 255) {
+        return (!Array.isArray(color) || color.length !== 4) ? [...chroma(color).rgb(), alpha] : color;
+    }
+    static hasPixelsNoData(pixels, noData) {
+        return noData !== undefined && pixels.every(p => p === noData);
+    }
+}
+
+/**
+ * KernelGenerator — 3×3 neighborhood kernel calculations on elevation rasters.
+ *
+ * Input contract: a Float32Array of 258×258 elevation values (row-major).
+ * Edge pixels (row/col 0 and 257) are used only as kernel neighbors and do
+ * not appear in the output.
+ * Output: Float32Array of 256×256 computed values.
+ */
+class KernelGenerator {
+    /**
+     * Calculates slope (0–90 degrees) for each pixel using Horn's method.
+     *
+     * @param src         Float32Array of 258×258 elevation values (row-major)
+     * @param cellSize    Cell size in meters per pixel
+     * @param zFactor     Vertical exaggeration factor (default 1)
+     * @param noDataValue Elevation value treated as noData; output is NaN for those pixels
+     */
+    static calculateSlope(src, cellSize, zFactor = 1, noDataValue) {
+        const OUT = 256;
+        const IN = 258;
+        const out = new Float32Array(OUT * OUT);
+        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) {
+                    out[r * OUT + c] = NaN;
+                    continue;
+                }
+                const z1 = src[base]; // nw
+                const z2 = src[base + 1]; // n
+                const z3 = src[base + 2]; // ne
+                const z4 = src[base + IN]; // w
+                const z6 = src[base + IN + 2]; // e
+                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 slopeRad = Math.atan(zFactor * Math.sqrt(dzdx * dzdx + dzdy * dzdy));
+                out[r * OUT + c] = slopeRad * (180 / Math.PI);
+            }
+        }
+        return out;
+    }
+    /**
+     * Calculates hillshade (0–255 grayscale) for each pixel.
+     * Follows the ESRI hillshade algorithm convention.
+     *
+     * @param src         Float32Array of 258×258 elevation values (row-major)
+     * @param azimuth     Sun azimuth in degrees (default 315 = NW)
+     * @param altitude    Sun altitude above horizon in degrees (default 45)
+     * @param cellSize    Cell size in meters per pixel
+     * @param zFactor     Vertical exaggeration factor (default 1)
+     * @param noDataValue Elevation value treated as noData; output is NaN for those pixels
+     */
+    static calculateHillshade(src, cellSize, azimuth = 315, altitude = 45, zFactor = 1, noDataValue) {
+        const OUT = 256;
+        const IN = 258;
+        const out = new Float32Array(OUT * OUT);
+        const zenithRad = (90 - altitude) * (Math.PI / 180);
+        let azimuthMath = 360 - azimuth + 90;
+        if (azimuthMath >= 360)
+            azimuthMath -= 360;
+        const azimuthRad = azimuthMath * (Math.PI / 180);
+        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) {
+                    out[r * OUT + c] = NaN;
+                    continue;
+                }
+                const z1 = src[base]; // nw
+                const z2 = src[base + 1]; // n
+                const z3 = src[base + 2]; // ne
+                const z4 = src[base + IN]; // w
+                const z6 = src[base + IN + 2]; // e
+                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 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) +
+                    Math.sin(zenithRad) * Math.sin(slopeRad) * Math.cos(azimuthRad - aspectRad));
+                out[r * OUT + c] = Math.max(0, Math.min(255, hillshade));
+            }
+        }
+        return out;
+    }
+}
+
 class TerrainGenerator {
-    static generate(input, options, meshMaxError) {
+    static async generate(input, options, meshMaxError) {
         const { width, height } = input;
+        const isKernel = width === 258;
         // 1. Compute Terrain Data (Extract Elevation)
         const terrain = this.computeTerrainData(input, options);
+        // For kernel tiles, the mesh uses the inner 257×257 sub-grid (rows 1–257, cols 1–257)
+        // so that row 0 / col 0 (kernel padding) is dropped while the bottom/right stitching
+        // overlap is preserved.
+        const meshTerrain = isKernel ? this.extractMeshRaster(terrain) : terrain;
+        const meshWidth = isKernel ? 257 : width;
+        const meshHeight = isKernel ? 257 : height;
         // 2. Tesselate (Generate Mesh)
         const { terrainSkirtHeight } = options;
         let mesh;
         switch (options.tesselator) {
             case 'martini':
-                mesh = this.getMartiniTileMesh(meshMaxError, width, terrain);
+                mesh = this.getMartiniTileMesh(meshMaxError, meshWidth, meshTerrain);
                 break;
             case 'delatin':
-                mesh = this.getDelatinTileMesh(meshMaxError, width, height, terrain);
+                mesh = this.getDelatinTileMesh(meshMaxError, meshWidth, meshHeight, meshTerrain);
                 break;
             default:
                 // Intentional: default to Martini for any unspecified or unrecognized tesselator.
-                mesh = this.getMartiniTileMesh(meshMaxError, width, terrain);
+                mesh = this.getMartiniTileMesh(meshMaxError, meshWidth, meshTerrain);
                 break;
         }
         const { vertices } = mesh;
         let { triangles } = mesh;
-        let attributes = this.getMeshAttributes(vertices, terrain, width, height, input.bounds);
+        let attributes = this.getMeshAttributes(vertices, meshTerrain, meshWidth, meshHeight, input.bounds);
         // Compute bounding box before adding skirt so that z values are not skewed
         const boundingBox = getMeshBoundingBox(attributes);
         if (terrainSkirtHeight) {
@@ -5266,14 +5630,91 @@ class TerrainGenerator {
             indices: { value: Uint32Array.from(triangles), size: 1 },
             attributes,
         };
-        const gridWidth = width === 257 ? 257 : width + 1;
-        const gridHeight = height === 257 ? 257 : height + 1;
-        return {
+        // For kernel tiles, raw holds the 257×257 mesh elevation (same as non-kernel).
+        // gridWidth/gridHeight reflect the mesh dimensions.
+        const gridWidth = meshWidth === 257 ? 257 : meshWidth + 1;
+        const gridHeight = meshHeight === 257 ? 257 : meshHeight + 1;
+        const tileResult = {
             map,
-            raw: terrain,
+            raw: meshTerrain,
             width: gridWidth,
-            height: gridHeight
+            height: gridHeight,
         };
+        // 3. Kernel path: compute slope or hillshade, store as rawDerived, generate texture
+        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);
+            const zFactor = options.zFactor ?? 1;
+            if (options.useSlope && options.useHillshade) {
+                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.
+                    // eslint-disable-next-line eqeqeq
+                    kernelTerrain[i] = sourceRaster[i] == noData ? noData : terrain[i];
+                }
+            }
+            else {
+                // Fallback: no usable noData metadata or mismatched lengths; mirror existing behavior.
+                kernelTerrain.set(terrain);
+            }
+            let kernelOutput;
+            if (options.useSlope) {
+                kernelOutput = KernelGenerator.calculateSlope(kernelTerrain, cellSize, zFactor, options.noDataValue);
+            }
+            else {
+                kernelOutput = KernelGenerator.calculateHillshade(kernelTerrain, cellSize, options.hillshadeAzimuth ?? 315, options.hillshadeAltitude ?? 45, zFactor, options.noDataValue);
+            }
+            tileResult.rawDerived = kernelOutput;
+            if (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' });
+            tileResult.texture = bitmapResult.map;
+        }
+        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;
+        const out = new Float32Array(MESH * MESH);
+        for (let r = 0; r < MESH; r++) {
+            for (let c = 0; c < MESH; c++) {
+                out[r * MESH + c] = terrain258[(r + 1) * IN + (c + 1)];
+            }
+        }
+        return out;
+    }
+    static hasVisualizationOptions(options) {
+        return !!(options.useHeatMap ||
+            options.useSingleColor ||
+            options.useColorsBasedOnValues ||
+            options.useColorClasses);
+    }
+    static cropRaster(src, srcWidth, _srcHeight, dstWidth, dstHeight) {
+        const out = new Float32Array(dstWidth * dstHeight);
+        for (let y = 0; y < dstHeight; y++) {
+            for (let x = 0; x < dstWidth; x++) {
+                out[y * dstWidth + x] = src[y * srcWidth + x];
+            }
+        }
+        return out;
     }
     /**
      * Decodes raw raster data into a Float32Array of elevation values.
@@ -5288,12 +5729,16 @@ class TerrainGenerator {
         const channel = isPlanar
             ? (rasters[optionsLocal.useChannelIndex ?? 0] ?? rasters[0])
             : rasters[0];
-        const terrain = new Float32Array((width === 257 ? width : width + 1) * (height === 257 ? height : height + 1));
+        const isKernel = width === 258;
+        const isStitched = width === 257;
+        // Kernel: 258×258 flat array. Stitched: 257×257. Default: (width+1)×(height+1) with backfill.
+        const outWidth = isKernel ? 258 : (isStitched ? 257 : width + 1);
+        const outHeight = isKernel ? 258 : (isStitched ? 257 : height + 1);
+        const terrain = new Float32Array(outWidth * outHeight);
         const samplesPerPixel = isPlanar ? 1 : (channel.length / (width * height));
         // If planar, we already selected the correct array, so start at index 0.
         // If interleaved, start at the index of the desired channel.
         let pixel = isPlanar ? 0 : (optionsLocal.useChannelIndex ?? 0);
-        const isStitched = width === 257;
         const fallbackValue = options.terrainMinValue ?? 0;
         for (let y = 0; y < height; y++) {
             for (let x = 0; x < width; x++) {
@@ -5308,13 +5753,13 @@ class TerrainGenerator {
                 if (Number.isNaN(elevationValue) || elevationValue < -34e37 || elevationValue > 3.4e38) {
                     elevationValue = fallbackValue;
                 }
-                // If stitched (257), fill linearly. If 256, fill with stride for padding.
-                const index = isStitched ? (y * width + x) : (y * (width + 1) + x);
+                // Kernel/Stitched: fill linearly. Default (256): fill with stride for padding.
+                const index = (isKernel || isStitched) ? (y * width + x) : (y * (width + 1) + x);
                 terrain[index] = elevationValue;
                 pixel += samplesPerPixel;
             }
         }
-        if (!isStitched) {
+        if (!isKernel && !isStitched) {
             // backfill bottom border
             for (let i = (width + 1) * width, x = 0; x < width; x++, i++) {
                 terrain[i] = terrain[i - width - 1];
@@ -5375,313 +5820,6 @@ class TerrainGenerator {
     }
 }
 
-// DataUtils.ts
-function scale(num, inMin, inMax, outMin, outMax) {
-    if (inMax === inMin) {
-        return outMin;
-    }
-    return ((num - inMin) * (outMax - outMin)) / (inMax - inMin) + outMin;
-}
-
-class BitmapGenerator {
-    static async generate(input, options) {
-        const optionsLocal = { ...options };
-        const { rasters, width, height } = input;
-        const channels = rasters.length;
-        const canvas = document.createElement('canvas');
-        canvas.width = width;
-        canvas.height = height;
-        const c = canvas.getContext('2d');
-        const imageData = c.createImageData(width, height);
-        let r;
-        let g;
-        let b;
-        let a;
-        const size = width * height * 4;
-        const alpha255 = Math.floor(optionsLocal.alpha * 2.55);
-        optionsLocal.unidentifiedColor = this.getColorFromChromaType(optionsLocal.unidentifiedColor, alpha255);
-        optionsLocal.nullColor = this.getColorFromChromaType(optionsLocal.nullColor, alpha255);
-        optionsLocal.clippedColor = this.getColorFromChromaType(optionsLocal.clippedColor, alpha255);
-        optionsLocal.color = this.getColorFromChromaType(optionsLocal.color, alpha255);
-        optionsLocal.useChannelIndex ??= optionsLocal.useChannel == null ? null : optionsLocal.useChannel - 1;
-        // Derive channel count from data if not provided
-        const numAvailableChannels = optionsLocal.numOfChannels ?? (rasters.length === 1 ? rasters[0].length / (width * height) : rasters.length);
-        if (optionsLocal.useChannelIndex == null) {
-            if (channels === 1) {
-                if (rasters[0].length / (width * height) === 1) {
-                    const channel = rasters[0];
-                    // AUTO RANGE
-                    if (optionsLocal.useAutoRange) {
-                        optionsLocal.colorScaleValueRange = this.getMinMax(channel, optionsLocal);
-                    }
-                    // SINGLE CHANNEL
-                    const colorData = this.getColorValue(channel, optionsLocal, size);
-                    imageData.data.set(colorData);
-                }
-                // RGB values in one channel
-                if (rasters[0].length / (width * height) === 3) {
-                    let pixel = 0;
-                    for (let idx = 0; idx < size; idx += 4) {
-                        const rgbColor = [rasters[0][pixel], rasters[0][pixel + 1], rasters[0][pixel + 2]];
-                        const rgbaColor = this.hasPixelsNoData(rgbColor, optionsLocal.noDataValue)
-                            ? optionsLocal.nullColor
-                            : [...rgbColor, Math.floor(optionsLocal.alpha * 2.55)];
-                        [imageData.data[idx], imageData.data[idx + 1], imageData.data[idx + 2], imageData.data[idx + 3]] = rgbaColor;
-                        pixel += 3;
-                    }
-                }
-                if (rasters[0].length / (width * height) === 4) {
-                    rasters[0].forEach((value, index) => {
-                        imageData.data[index] = value;
-                    });
-                }
-            }
-            if (channels === 3) {
-                // RGB
-                let pixel = 0;
-                const alphaConst = Math.floor(optionsLocal.alpha * 2.55);
-                for (let i = 0; i < size; i += 4) {
-                    r = rasters[0][pixel];
-                    g = rasters[1][pixel];
-                    b = rasters[2][pixel];
-                    a = alphaConst;
-                    imageData.data[i] = r;
-                    imageData.data[i + 1] = g;
-                    imageData.data[i + 2] = b;
-                    imageData.data[i + 3] = a;
-                    pixel += 1;
-                }
-            }
-            if (channels === 4) {
-                // RGBA
-                let pixel = 0;
-                const alphaConst = Math.floor(optionsLocal.alpha * 2.55);
-                for (let i = 0; i < size; i += 4) {
-                    r = rasters[0][pixel];
-                    g = rasters[1][pixel];
-                    b = rasters[2][pixel];
-                    a = alphaConst;
-                    imageData.data[i] = r;
-                    imageData.data[i + 1] = g;
-                    imageData.data[i + 2] = b;
-                    imageData.data[i + 3] = a;
-                    pixel += 1;
-                }
-            }
-        }
-        else if (optionsLocal.useChannelIndex < numAvailableChannels && optionsLocal.useChannelIndex >= 0) {
-            const isInterleaved = rasters.length === 1 && numAvailableChannels > 1;
-            const channel = isInterleaved ? rasters[0] : (rasters[optionsLocal.useChannelIndex] ?? rasters[0]);
-            const samplesPerPixel = isInterleaved ? numAvailableChannels : 1;
-            // AUTO RANGE
-            if (optionsLocal.useAutoRange) {
-                optionsLocal.colorScaleValueRange = this.getMinMax(channel, optionsLocal, samplesPerPixel);
-            }
-            const colorData = this.getColorValue(channel, optionsLocal, size, samplesPerPixel);
-            imageData.data.set(colorData);
-        }
-        else {
-            // if user defined channel does not exist
-            /* eslint-disable no-console */
-            console.log(`Defined channel(${options.useChannel}) or channel index(${options.useChannelIndex}) does not exist, choose a different channel or set the useChannel property to null if you want to visualize RGB(A) imagery`);
-            const defaultColorData = this.getDefaultColor(size, optionsLocal.nullColor);
-            defaultColorData.forEach((value, index) => {
-                imageData.data[index] = value;
-            });
-        }
-        // Optimization: Skip Canvas -> PNG encoding -> Base64 string
-        // Return raw GPU-ready ImageBitmap directly
-        // Note: createImageBitmap(imageData) is cleaner, but using the canvas ensures broad compatibility
-        c.putImageData(imageData, 0, 0);
-        const map = await createImageBitmap(canvas);
-        return {
-            map,
-            // rasters[0] is the interleaved buffer on the CogTiles path (primary use case).
-            // For planar multi-band GeoTIFFs via GeoImage.getBitmap(), only the first band is exposed here.
-            // Full multi-band raw picking support is tracked in https://github.com/Gisat/deck.gl-geotiff/issues/98
-            raw: rasters[0],
-            width,
-            height
-        };
-    }
-    static getMinMax(array, options, samplesPerPixel = 1) {
-        let maxValue = -Infinity;
-        let minValue = Infinity;
-        let foundValid = false;
-        let pixel = samplesPerPixel === 1 ? 0 : (options.useChannelIndex ?? 0);
-        for (let idx = pixel; idx < array.length; idx += samplesPerPixel) {
-            if (options.noDataValue === undefined || array[idx] !== options.noDataValue) {
-                if (array[idx] > maxValue)
-                    maxValue = array[idx];
-                if (array[idx] < minValue)
-                    minValue = array[idx];
-                foundValid = true;
-            }
-        }
-        if (!foundValid) {
-            return options.colorScaleValueRange || [0, 255];
-        }
-        return [minValue, maxValue];
-    }
-    static getColorValue(dataArray, options, arrayLength, samplesPerPixel = 1) {
-        const colorScale = chroma.scale(options.colorScale).domain(options.colorScaleValueRange);
-        let pixel = samplesPerPixel === 1 ? 0 : (options.useChannelIndex ?? 0);
-        const colorsArray = new Uint8ClampedArray(arrayLength);
-        const cbvInput = options.colorsBasedOnValues ?? [];
-        const classesInput = options.colorClasses ?? [];
-        const optUseColorsBasedOnValues = options.useColorsBasedOnValues && cbvInput.length > 0;
-        const optUseColorClasses = options.useColorClasses && classesInput.length > 0;
-        const dataValues = optUseColorsBasedOnValues ? cbvInput.map(([first]) => first) : [];
-        const colorValues = optUseColorsBasedOnValues ? cbvInput.map(([, second]) => [...chroma(second).rgb(), Math.floor(options.alpha * 2.55)]) : [];
-        const colorClasses = optUseColorClasses ? classesInput.map(([color]) => [...chroma(color).rgb(), Math.floor(options.alpha * 2.55)]) : [];
-        const dataIntervals = optUseColorClasses ? classesInput.map(([, interval]) => interval) : [];
-        const dataIntervalBounds = optUseColorClasses ? classesInput.map(([, , bounds], index) => {
-            if (bounds !== undefined)
-                return bounds;
-            if (index === classesInput.length - 1)
-                return [true, true];
-            return [true, false];
-        }) : [];
-        // Pre-calculate Loop Variables to avoid object lookup in loop
-        const optNoData = options.noDataValue;
-        const optClipLow = options.clipLow;
-        const optClipHigh = options.clipHigh;
-        const optClippedColor = options.clippedColor;
-        const optUseHeatMap = options.useHeatMap;
-        const optUseSingleColor = options.useSingleColor;
-        const optUseDataForOpacity = options.useDataForOpacity;
-        const optColor = options.color;
-        const optUnidentifiedColor = options.unidentifiedColor;
-        const optNullColor = options.nullColor;
-        const optAlpha = Math.floor(options.alpha * 2.55);
-        const rangeMin = options.colorScaleValueRange[0];
-        const rangeMax = options.colorScaleValueRange.slice(-1)[0];
-        // LOOKUP TABLE OPTIMIZATION (for 8-bit data)
-        // If the data is Uint8 (0-255), we can pre-calculate the result for every possible value.
-        const is8Bit = dataArray instanceof Uint8Array || dataArray instanceof Uint8ClampedArray;
-        // The LUT optimization is only applied for 8-bit data when `useDataForOpacity` is false.
-        // `useDataForOpacity` is excluded because it requires the raw data value for
-        // dynamic opacity scaling. All other visualization modes (HeatMap, Categorical,
-        // Classes, Single Color) are pre-calculated into the LUT for maximum performance.
-        if (is8Bit && !optUseDataForOpacity) {
-            // Create LUT: 256 values * 4 channels (RGBA)
-            const lut = new Uint8ClampedArray(256 * 4);
-            for (let i = 0; i < 256; i++) {
-                let r = optNullColor[0], g = optNullColor[1], b = optNullColor[2], a = optNullColor[3];
-                // Logic mirroring the pixel loop
-                if (optNoData === undefined || i !== optNoData) {
-                    if ((optClipLow != null && i <= optClipLow) || (optClipHigh != null && i >= optClipHigh)) {
-                        [r, g, b, a] = optClippedColor;
-                    }
-                    else {
-                        let c = [r, g, b, a];
-                        if (optUseHeatMap) {
-                            const rgb = colorScale(i).rgb();
-                            c = [rgb[0], rgb[1], rgb[2], optAlpha];
-                        }
-                        else if (optUseColorsBasedOnValues) {
-                            const index = dataValues.indexOf(i);
-                            c = (index > -1) ? colorValues[index] : optUnidentifiedColor;
-                        }
-                        else if (optUseColorClasses) {
-                            const index = this.findClassIndex(i, dataIntervals, dataIntervalBounds);
-                            c = (index > -1) ? colorClasses[index] : optUnidentifiedColor;
-                        }
-                        else if (optUseSingleColor) {
-                            c = optColor;
-                        }
-                        [r, g, b, a] = c;
-                    }
-                }
-                lut[i * 4] = r;
-                lut[i * 4 + 1] = g;
-                lut[i * 4 + 2] = b;
-                lut[i * 4 + 3] = a;
-            }
-            // Fast Apply Loop
-            let outIdx = 0;
-            const numPixels = arrayLength / 4;
-            for (let i = 0; i < numPixels; i++) {
-                const val = dataArray[pixel];
-                const lutIdx = Math.min(255, Math.max(0, val)) * 4;
-                colorsArray[outIdx++] = lut[lutIdx];
-                colorsArray[outIdx++] = lut[lutIdx + 1];
-                colorsArray[outIdx++] = lut[lutIdx + 2];
-                colorsArray[outIdx++] = lut[lutIdx + 3];
-                pixel += samplesPerPixel;
-            }
-            return colorsArray;
-        }
-        // Standard Loop (Float or non-optimized)
-        for (let i = 0; i < arrayLength; i += 4) {
-            let r = optNullColor[0], g = optNullColor[1], b = optNullColor[2], a = optNullColor[3];
-            const val = dataArray[pixel];
-            if ((!Number.isNaN(val)) && (optNoData === undefined || val !== optNoData)) {
-                if ((optClipLow != null && val <= optClipLow) || (optClipHigh != null && val >= optClipHigh)) {
-                    [r, g, b, a] = optClippedColor;
-                }
-                else {
-                    let c;
-                    if (optUseHeatMap) {
-                        const rgb = colorScale(val).rgb();
-                        c = [rgb[0], rgb[1], rgb[2], optAlpha];
-                    }
-                    else if (optUseColorsBasedOnValues) {
-                        const index = dataValues.indexOf(val);
-                        c = (index > -1) ? colorValues[index] : optUnidentifiedColor;
-                    }
-                    else if (optUseColorClasses) {
-                        const index = this.findClassIndex(val, dataIntervals, dataIntervalBounds);
-                        c = (index > -1) ? colorClasses[index] : optUnidentifiedColor;
-                    }
-                    else if (optUseSingleColor) {
-                        c = optColor;
-                    }
-                    if (c) {
-                        [r, g, b, a] = c;
-                    }
-                    if (optUseDataForOpacity) {
-                        a = scale(val, rangeMin, rangeMax, 0, 255);
-                    }
-                }
-            }
-            colorsArray[i] = r;
-            colorsArray[i + 1] = g;
-            colorsArray[i + 2] = b;
-            colorsArray[i + 3] = a;
-            pixel += samplesPerPixel;
-        }
-        return colorsArray;
-    }
-    static findClassIndex(number, intervals, bounds) {
-        for (let idx = 0; idx < intervals.length; idx += 1) {
-            const [min, max] = intervals[idx];
-            const [includeEqualMin, includeEqualMax] = bounds[idx];
-            if ((includeEqualMin ? number >= min : number > min)
-                && (includeEqualMax ? number <= max : number < max)) {
-                return idx;
-            }
-        }
-        return -1;
-    }
-    static getDefaultColor(size, nullColor) {
-        const colorsArray = new Uint8ClampedArray(size);
-        for (let i = 0; i < size; i += 4) {
-            [colorsArray[i], colorsArray[i + 1], colorsArray[i + 2], colorsArray[i + 3]] = nullColor;
-        }
-        return colorsArray;
-    }
-    static getColorFromChromaType(colorDefinition, alpha = 255) {
-        if (!Array.isArray(colorDefinition) || colorDefinition.length !== 4) {
-            return [...chroma(colorDefinition).rgb(), alpha];
-        }
-        return colorDefinition;
-    }
-    static hasPixelsNoData(pixels, noDataValue) {
-        return noDataValue !== undefined && pixels.every((pixel) => pixel === noDataValue);
-    }
-}
-
 class GeoImage {
     data;
     async setUrl(url) {
@@ -5709,6 +5847,7 @@ class GeoImage {
         let width;
         let height;
         let bounds;
+        let cellSizeMeters;
         if (typeof (input) === 'string') {
             // TODO not tested
             // input is type of object
@@ -5723,9 +5862,10 @@ class GeoImage {
             width = input.width;
             height = input.height;
             bounds = input.bounds;
+            cellSizeMeters = input.cellSizeMeters;
         }
         // Delegate to TerrainGenerator
-        return TerrainGenerator.generate({ width, height, rasters, bounds }, options, meshMaxError);
+        return await TerrainGenerator.generate({ width, height, rasters, bounds, cellSizeMeters }, options, meshMaxError);
     }
     async getBitmap(input, options) {
         let rasters = [];
@@ -6017,14 +6157,21 @@ class CogTiles {
     async getTile(x, y, z, bounds, meshMaxError) {
         let requiredSize = this.tileSize; // Default 256 for image/bitmap
         if (this.options.type === 'terrain') {
-            requiredSize = this.tileSize + 1; // 257 for stitching
+            const isKernel = this.options.useSlope || this.options.useHillshade;
+            requiredSize = this.tileSize + (isKernel ? 2 : 1); // 258 for kernel (3×3 border), 257 for normal stitching
         }
         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;
         return this.geo.getMap({
             rasters: [tileData[0]],
             width: requiredSize,
             height: requiredSize,
             bounds,
+            cellSizeMeters,
         }, this.options, meshMaxError);
     }
     /**
@@ -6418,6 +6565,12 @@ class CogTerrainLayer extends CompositeLayer {
             // Trigger a refresh of the tiles
             this.state.terrainCogTiles.options.useChannelIndex = null; // Clear cached index
         }
+        // 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.
+        if (props.cogTiles && props.cogTiles !== oldProps.cogTiles) {
+            this.setState({ terrainCogTiles: props.cogTiles });
+        }
         if (props.workerUrl) {
             log.removed('workerUrl', 'loadOptions.terrain.workerUrl')();
         }
@@ -6475,15 +6628,16 @@ class CogTerrainLayer extends CompositeLayer {
         }
         // const [mesh, texture] = data;
         const [meshResult] = data;
-        return new SubLayerClass({ ...props, tileSize: 256 }, {
+        const tileTexture = (!this.props.disableTexture && meshResult?.texture) ? meshResult.texture : null;
+        return new SubLayerClass({ ...props, tileSize: props.tileSize }, {
             data: DUMMY_DATA,
             mesh: meshResult?.map,
-            // texture,
+            texture: tileTexture,
             _instanced: false,
             pickable: props.pickable,
             coordinateSystem: COORDINATE_SYSTEM.CARTESIAN,
             // getPosition: (d) => [0, 0, 0],
-            getColor: color,
+            getColor: tileTexture ? [255, 255, 255] : color,
             wireframe,
             material,
         });
@@ -6532,6 +6686,9 @@ class CogTerrainLayer extends CompositeLayer {
                         // 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,
                     },
                 },
                 onViewportLoad: this.onViewportLoad.bind(this),