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

package/dist/esm/types/core/CogTiles.d.ts

@@ -50,7 +50,7 @@ declare class CogTiles {
      * @returns {number} The index of the image in the COG that best matches the specified zoom level.
      */
     getImageIndexForZoomLevel(zoom: number): number;
-    getTileFromImage(tileX: number, tileY: number, zoom: number, fetchSize?: number): Promise<(Float32Array<ArrayBuffer> | Int8Array<ArrayBuffer> | Uint8Array<ArrayBuffer> | Int16Array<ArrayBuffer> | Uint16Array<ArrayBuffer> | Int32Array<ArrayBuffer> | Uint32Array<ArrayBuffer> | Float64Array<ArrayBuffer>)[] | import("geotiff").TypedArrayWithDimensions[]>;
+    getTileFromImage(tileX: number, tileY: number, zoom: number, fetchSize?: number): Promise<(Uint8Array<ArrayBuffer> | Float32Array<ArrayBuffer> | Int8Array<ArrayBuffer> | Int16Array<ArrayBuffer> | Uint16Array<ArrayBuffer> | Int32Array<ArrayBuffer> | Uint32Array<ArrayBuffer> | Float64Array<ArrayBuffer>)[] | import("geotiff").TypedArrayWithDimensions[]>;
     /**
      * Creates a blank tile buffer filled with the "No Data" value.
      * @param size The width/height of the square tile (e.g., 256 or 257)
@@ -81,6 +81,6 @@ declare class CogTiles {
      * @param {number} multiplier - Optional multiplier for interleaved buffers (e.g., numChannels).
      * @returns {TypedArray} A typed array buffer of length (tileSize * tileSize * multiplier).
      */
-    createTileBuffer(dataType: string, tileSize: number, multiplier?: number): Float32Array<ArrayBuffer> | Int8Array<ArrayBuffer> | Uint8Array<ArrayBuffer> | Int16Array<ArrayBuffer> | Uint16Array<ArrayBuffer> | Int32Array<ArrayBuffer> | Uint32Array<ArrayBuffer> | Float64Array<ArrayBuffer>;
+    createTileBuffer(dataType: string, tileSize: number, multiplier?: number): Uint8Array<ArrayBuffer> | Float32Array<ArrayBuffer> | Int8Array<ArrayBuffer> | Int16Array<ArrayBuffer> | Uint16Array<ArrayBuffer> | Int32Array<ArrayBuffer> | Uint32Array<ArrayBuffer> | Float64Array<ArrayBuffer>;
 }
 export default CogTiles;

package/dist/esm/types/core/GeoImage.d.ts

@@ -11,6 +11,27 @@ export default class GeoImage {
         bounds: Bounds;
         cellSizeMeters?: number;
     }, options: GeoImageOptions, meshMaxError: number): Promise<TileResult | 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: GeoImageOptions, userOptions: GeoImageOptions): GeoImageOptions;
     getHeightmap(input: string | {
         bounds: Bounds;
         width: number;
@@ -22,5 +43,7 @@ export default class GeoImage {
         width: number;
         height: number;
         rasters: any[];
+        bounds?: Bounds;
+        cellSizeMeters?: number;
     }, options: GeoImageOptions): Promise<TileResult>;
 }

package/dist/esm/types/core/lib/BitmapGenerator.d.ts

@@ -1,5 +1,24 @@
 import { GeoImageOptions, TypedArray, TileResult } from '../types';
 export declare class BitmapGenerator {
+    /**
+     * Cache for Swiss relief color LUTs to avoid regenerating on every tile.
+     * Key: colorScale config + range, Value: pre-computed RGBA LUT
+     */
+    private static _swissColorLUTCache;
+    /**
+     * 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
+     */
+    private static _8bitLUTCache;
+    /**
+     * 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
+     */
+    private static _floatLUTCache;
+    /** Build a cache key that captures all options affecting LUT colour output. */
+    private static getLUTCacheKey;
     /**
      * Main entry point: Generates an ImageBitmap from raw raster data.
      */
@@ -8,7 +27,22 @@ export declare class BitmapGenerator {
         height: number;
         rasters: TypedArray[];
     }, options: GeoImageOptions): Promise<TileResult>;
-    static getColorValue(dataArray: TypedArray | any[], options: GeoImageOptions, arrayLength: number, samplesPerPixel?: number): Uint8ClampedArray<ArrayBuffer>;
+    static getColorValue(dataArray: TypedArray | TypedArray[], options: GeoImageOptions, arrayLength: number, samplesPerPixel?: number): Uint8ClampedArray<ArrayBuffer>;
+    /**
+     * 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: TypedArray[], options: GeoImageOptions, arrayLength: number): Uint8ClampedArray;
     private static calculateSingleColor;
     private static findClassIndex;
     private static getDefaultColor;

package/dist/esm/types/core/lib/KernelGenerator.d.ts

@@ -7,6 +7,13 @@
  * Output: Float32Array of 256×256 computed values.
  */
 export declare 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).
+     */
+    private static computeGradients;
     /**
      * Calculates slope (0–90 degrees) for each pixel using Horn's method.
      *
@@ -28,4 +35,9 @@ export declare class KernelGenerator {
      * @param noDataValue Elevation value treated as noData; output is NaN for those pixels
      */
     static calculateHillshade(src: Float32Array, cellSize: number, azimuth?: number, altitude?: number, zFactor?: number, noDataValue?: number): Float32Array;
+    /**
+     * Calculates a weighted multi-directional hillshade (0–255).
+     * Combines three light sources to reveal structure in shadows.
+     */
+    static calculateMultiHillshade(src: Float32Array, cellSize: number, zFactor?: number, noDataValue?: number): Float32Array;
 }

package/dist/esm/types/core/lib/ReliefCompositor.d.ts

@@ -0,0 +1,28 @@
+import { GeoImageOptions } from '../types';
+/**
+ * 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).
+ */
+export declare 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.
+     */
+    private static _swissReliefLUT;
+    private static _lastWeight;
+    static getSwissReliefLUT(weight?: number): Float32Array;
+    /**
+     * 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: Float32Array, options: GeoImageOptions, cellSize: number, width: number, height: number): Uint8ClampedArray;
+}

package/dist/esm/types/core/lib/TerrainGenerator.d.ts

@@ -7,9 +7,14 @@ export declare class TerrainGenerator {
         bounds: Bounds;
         cellSizeMeters?: number;
     }, options: GeoImageOptions, meshMaxError: number): Promise<TileResult>;
-    /** Extracts rows 1–257, cols 1–257 from a 258×258 terrain array → 257×257 for mesh generation. */
     private static extractMeshRaster;
     private static hasVisualizationOptions;
+    /**
+     * 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.
+     */
+    private static preserveNoDataForKernel;
     private static cropRaster;
     /**
      * Decodes raw raster data into a Float32Array of elevation values.

package/dist/esm/types/core/types.d.ts

@@ -41,7 +41,10 @@ export type GeoImageOptions = {
     colorScaleValueRange?: number[];
     colorsBasedOnValues?: Array<[number, ChromaColorInput]>;
     colorClasses?: Array<[ChromaColorInput, [number, number], [boolean?, boolean?]?]>;
+    /** General layer opacity (0-100). Used for all rendering modes except glaze. */
     alpha?: number;
+    /** Intensity ceiling for the relief glaze (0-255). 0 is fully transparent; 255 is maximum theoretical opacity. Recommended range for satellite overlays: 120-160. Only used with useReliefGlaze. */
+    maxGlazeAlpha?: number;
     nullColor?: ChromaColorInput;
     unidentifiedColor?: ChromaColorInput;
     clippedColor?: ChromaColorInput;
@@ -51,6 +54,10 @@ export type GeoImageOptions = {
     hillshadeAzimuth?: number;
     hillshadeAltitude?: number;
     zFactor?: number;
+    useSwissRelief?: boolean;
+    swissSlopeWeight?: number;
+    useReliefGlaze?: boolean;
+    disableLighting?: boolean;
 };
 export declare const DefaultGeoImageOptions: GeoImageOptions;
 export type TypedArray = Int8Array | Uint8Array | Uint8ClampedArray | Int16Array | Uint16Array | Int32Array | Uint32Array | Float32Array | Float64Array;
@@ -74,4 +81,6 @@ export interface TileResult {
     width: number;
     height: number;
     texture?: ImageBitmap;
+    /** Optional: grayscale or color bitmap for Swiss relief or other overlays */
+    bitmap?: Uint8ClampedArray | ImageBitmap;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gisatcz/deckgl-geolib",
-  "version": "2.4.1-dev.1",
+  "version": "2.5.0-dev.2",
   "description": "Deck.gl extension for rendering Cloud-Optimized GeoTIFF (COG) data",
   "keywords": [
     "deck.gl",