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

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,158 +5232,6 @@ function updateAttributesForNewEdge({ edge, edgeIndex, attributes, skirtHeight,
     newTriangles[triangle1Offset + 5] = positionsLength / 3 + vertex1Offset;
 }
 
-class TerrainGenerator {
-    static generate(input, options, meshMaxError) {
-        const { width, height } = input;
-        // 1. Compute Terrain Data (Extract Elevation)
-        const terrain = this.computeTerrainData(input, options);
-        // 2. Tesselate (Generate Mesh)
-        const { terrainSkirtHeight } = options;
-        let mesh;
-        switch (options.tesselator) {
-            case 'martini':
-                mesh = this.getMartiniTileMesh(meshMaxError, width, terrain);
-                break;
-            case 'delatin':
-                mesh = this.getDelatinTileMesh(meshMaxError, width, height, terrain);
-                break;
-            default:
-                // Intentional: default to Martini for any unspecified or unrecognized tesselator.
-                mesh = this.getMartiniTileMesh(meshMaxError, width, terrain);
-                break;
-        }
-        const { vertices } = mesh;
-        let { triangles } = mesh;
-        let attributes = this.getMeshAttributes(vertices, terrain, width, height, input.bounds);
-        // Compute bounding box before adding skirt so that z values are not skewed
-        const boundingBox = getMeshBoundingBox(attributes);
-        if (terrainSkirtHeight) {
-            const { attributes: newAttributes, triangles: newTriangles } = addSkirt(attributes, triangles, terrainSkirtHeight);
-            attributes = newAttributes;
-            triangles = newTriangles;
-        }
-        const map = {
-            // Data return by this loader implementation
-            loaderData: {
-                header: {},
-            },
-            header: {
-                vertexCount: triangles.length,
-                boundingBox,
-            },
-            mode: 4, // TRIANGLES
-            indices: { value: Uint32Array.from(triangles), size: 1 },
-            attributes,
-        };
-        const gridWidth = width === 257 ? 257 : width + 1;
-        const gridHeight = height === 257 ? 257 : height + 1;
-        return {
-            map,
-            raw: terrain,
-            width: gridWidth,
-            height: gridHeight
-        };
-    }
-    /**
-     * Decodes raw raster data into a Float32Array of elevation values.
-     * Handles channel selection, value scaling, data type validation, and border stitching.
-     */
-    static computeTerrainData(input, options) {
-        const { width, height, rasters } = input;
-        const optionsLocal = { ...options };
-        optionsLocal.useChannelIndex ??= optionsLocal.useChannel == null ? null : optionsLocal.useChannel - 1;
-        // Detect if data is planar (multiple arrays) or interleaved (one array with multiple samples per pixel)
-        const isPlanar = rasters.length > 1;
-        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 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++) {
-                const multiplier = options.multiplier ?? 1;
-                let elevationValue = (options.noDataValue !== undefined &&
-                    options.noDataValue !== null &&
-                    channel[pixel] === options.noDataValue)
-                    ? fallbackValue
-                    : channel[pixel] * multiplier;
-                // Validate that the elevation value is within the valid range for Float32.
-                // Extreme values (like -1.79e308) can become -Infinity when cast, causing WebGL errors.
-                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);
-                terrain[index] = elevationValue;
-                pixel += samplesPerPixel;
-            }
-        }
-        if (!isStitched) {
-            // backfill bottom border
-            for (let i = (width + 1) * width, x = 0; x < width; x++, i++) {
-                terrain[i] = terrain[i - width - 1];
-            }
-            // backfill right border
-            for (let i = height, y = 0; y < height + 1; y++, i += height + 1) {
-                terrain[i] = terrain[i - 1];
-            }
-        }
-        return terrain;
-    }
-    static getMartiniTileMesh(meshMaxError, width, terrain) {
-        const gridSize = width === 257 ? 257 : width + 1;
-        const martini = new Martini(gridSize);
-        const tile = martini.createTile(terrain);
-        const { vertices, triangles } = tile.getMesh(meshMaxError);
-        return { vertices, triangles };
-    }
-    static getDelatinTileMesh(meshMaxError, width, height, terrain) {
-        const widthPlus = width === 257 ? 257 : width + 1;
-        const heightPlus = height === 257 ? 257 : height + 1;
-        const tin = new Delatin(terrain, widthPlus, heightPlus);
-        tin.run(meshMaxError);
-        // @ts-expect-error: Delatin instance properties 'coords' and 'triangles' are not explicitly typed in the library port
-        const { coords, triangles } = tin;
-        const vertices = coords;
-        return { vertices, triangles };
-    }
-    static getMeshAttributes(vertices, terrain, width, height, bounds) {
-        const gridSize = width === 257 ? 257 : width + 1;
-        const numOfVerticies = vertices.length / 2;
-        // vec3. x, y in pixels, z in meters
-        const positions = new Float32Array(numOfVerticies * 3);
-        // vec2. 1 to 1 relationship with position. represents the uv on the texture image. 0,0 to 1,1.
-        const texCoords = new Float32Array(numOfVerticies * 2);
-        const [minX, minY, maxX, maxY] = bounds || [0, 0, width, height];
-        // If stitched (257), the spatial extent covers 0..256 pixels, so we divide by 256.
-        // If standard (256), the spatial extent covers 0..256 pixels (with backfill), so we divide by 256.
-        const effectiveWidth = width === 257 ? width - 1 : width;
-        const effectiveHeight = height === 257 ? height - 1 : height;
-        const xScale = (maxX - minX) / effectiveWidth;
-        const yScale = (maxY - minY) / effectiveHeight;
-        for (let i = 0; i < numOfVerticies; i++) {
-            const x = vertices[i * 2];
-            const y = vertices[i * 2 + 1];
-            const pixelIdx = y * gridSize + x;
-            positions[3 * i] = x * xScale + minX;
-            positions[3 * i + 1] = -y * yScale + maxY;
-            positions[3 * i + 2] = terrain[pixelIdx];
-            texCoords[2 * i] = x / effectiveWidth;
-            texCoords[2 * i + 1] = y / effectiveHeight;
-        }
-        return {
-            POSITION: { value: positions, size: 3 },
-            TEXCOORD_0: { value: texCoords, size: 2 },
-            // NORMAL: {}, - optional, but creates the high poly look with lighting
-        };
-    }
-}
-
 // DataUtils.ts
 function scale(num, inMin, inMax, outMin, outMax) {
     if (inMax === inMin) {
@@ -5682,6 +5539,342 @@ class BitmapGenerator {
     }
 }
 
+/**
+ * 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 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, meshWidth, meshTerrain);
+                break;
+            case 'delatin':
+                mesh = this.getDelatinTileMesh(meshMaxError, meshWidth, meshHeight, meshTerrain);
+                break;
+            default:
+                // Intentional: default to Martini for any unspecified or unrecognized tesselator.
+                mesh = this.getMartiniTileMesh(meshMaxError, meshWidth, meshTerrain);
+                break;
+        }
+        const { vertices } = mesh;
+        let { triangles } = mesh;
+        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) {
+            const { attributes: newAttributes, triangles: newTriangles } = addSkirt(attributes, triangles, terrainSkirtHeight);
+            attributes = newAttributes;
+            triangles = newTriangles;
+        }
+        const map = {
+            // Data return by this loader implementation
+            loaderData: {
+                header: {},
+            },
+            header: {
+                vertexCount: triangles.length,
+                boundingBox,
+            },
+            mode: 4, // TRIANGLES
+            indices: { value: Uint32Array.from(triangles), size: 1 },
+            attributes,
+        };
+        // 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: meshTerrain,
+            width: gridWidth,
+            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.
+     * Handles channel selection, value scaling, data type validation, and border stitching.
+     */
+    static computeTerrainData(input, options) {
+        const { width, height, rasters } = input;
+        const optionsLocal = { ...options };
+        optionsLocal.useChannelIndex ??= optionsLocal.useChannel == null ? null : optionsLocal.useChannel - 1;
+        // Detect if data is planar (multiple arrays) or interleaved (one array with multiple samples per pixel)
+        const isPlanar = rasters.length > 1;
+        const channel = isPlanar
+            ? (rasters[optionsLocal.useChannelIndex ?? 0] ?? rasters[0])
+            : rasters[0];
+        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 fallbackValue = options.terrainMinValue ?? 0;
+        for (let y = 0; y < height; y++) {
+            for (let x = 0; x < width; x++) {
+                const multiplier = options.multiplier ?? 1;
+                let elevationValue = (options.noDataValue !== undefined &&
+                    options.noDataValue !== null &&
+                    channel[pixel] === options.noDataValue)
+                    ? fallbackValue
+                    : channel[pixel] * multiplier;
+                // Validate that the elevation value is within the valid range for Float32.
+                // Extreme values (like -1.79e308) can become -Infinity when cast, causing WebGL errors.
+                if (Number.isNaN(elevationValue) || elevationValue < -34e37 || elevationValue > 3.4e38) {
+                    elevationValue = fallbackValue;
+                }
+                // 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 (!isKernel && !isStitched) {
+            // backfill bottom border
+            for (let i = (width + 1) * width, x = 0; x < width; x++, i++) {
+                terrain[i] = terrain[i - width - 1];
+            }
+            // backfill right border
+            for (let i = height, y = 0; y < height + 1; y++, i += height + 1) {
+                terrain[i] = terrain[i - 1];
+            }
+        }
+        return terrain;
+    }
+    static getMartiniTileMesh(meshMaxError, width, terrain) {
+        const gridSize = width === 257 ? 257 : width + 1;
+        const martini = new Martini(gridSize);
+        const tile = martini.createTile(terrain);
+        const { vertices, triangles } = tile.getMesh(meshMaxError);
+        return { vertices, triangles };
+    }
+    static getDelatinTileMesh(meshMaxError, width, height, terrain) {
+        const widthPlus = width === 257 ? 257 : width + 1;
+        const heightPlus = height === 257 ? 257 : height + 1;
+        const tin = new Delatin(terrain, widthPlus, heightPlus);
+        tin.run(meshMaxError);
+        // @ts-expect-error: Delatin instance properties 'coords' and 'triangles' are not explicitly typed in the library port
+        const { coords, triangles } = tin;
+        const vertices = coords;
+        return { vertices, triangles };
+    }
+    static getMeshAttributes(vertices, terrain, width, height, bounds) {
+        const gridSize = width === 257 ? 257 : width + 1;
+        const numOfVerticies = vertices.length / 2;
+        // vec3. x, y in pixels, z in meters
+        const positions = new Float32Array(numOfVerticies * 3);
+        // vec2. 1 to 1 relationship with position. represents the uv on the texture image. 0,0 to 1,1.
+        const texCoords = new Float32Array(numOfVerticies * 2);
+        const [minX, minY, maxX, maxY] = bounds || [0, 0, width, height];
+        // If stitched (257), the spatial extent covers 0..256 pixels, so we divide by 256.
+        // If standard (256), the spatial extent covers 0..256 pixels (with backfill), so we divide by 256.
+        const effectiveWidth = width === 257 ? width - 1 : width;
+        const effectiveHeight = height === 257 ? height - 1 : height;
+        const xScale = (maxX - minX) / effectiveWidth;
+        const yScale = (maxY - minY) / effectiveHeight;
+        for (let i = 0; i < numOfVerticies; i++) {
+            const x = vertices[i * 2];
+            const y = vertices[i * 2 + 1];
+            const pixelIdx = y * gridSize + x;
+            positions[3 * i] = x * xScale + minX;
+            positions[3 * i + 1] = -y * yScale + maxY;
+            positions[3 * i + 2] = terrain[pixelIdx];
+            texCoords[2 * i] = x / effectiveWidth;
+            texCoords[2 * i + 1] = y / effectiveHeight;
+        }
+        return {
+            POSITION: { value: positions, size: 3 },
+            TEXCOORD_0: { value: texCoords, size: 2 },
+            // NORMAL: {}, - optional, but creates the high poly look with lighting
+        };
+    }
+}
+
 class GeoImage {
     data;
     async setUrl(url) {
@@ -5709,6 +5902,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 +5917,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 +6212,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 +6620,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 +6683,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 +6741,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),