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

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

@@ -1,21 +1,28 @@
 import { GeoTIFF, GeoTIFFImage } from 'geotiff';
 import GeoImage from './GeoImage';
-import { GeoImageOptions, TileResult, TypedArray } from './types';
+import { GeoImageOptions, TileResult } from './types';
 export type Bounds = [minX: number, minY: number, maxX: number, maxY: number];
 declare class CogTiles {
-    cog: GeoTIFF;
+    cog?: GeoTIFF;
     cogZoomLookup: number[];
     cogResolutionLookup: number[];
+    cogMeshMaxErrorLookup: number[];
     cogOrigin: number[];
     zoomRange: number[];
     tileSize: number;
     bounds: [number, number, number, number];
     geo: GeoImage;
     options: GeoImageOptions;
+    private tileResultCache;
+    private readonly tileResultCacheMaxSize;
+    private getTileResultCacheKey;
+    /** Clears the TileResult cache. Call when the COG URL or meshMaxError changes. */
+    clearTileResultCache(): void;
     private rasterCache;
-    private readonly maxCacheSize;
-    private getCachedRaster;
-    private setCachedRaster;
+    private readonly rasterCacheMaxSize;
+    private reliefMaskCache;
+    private readonly reliefMaskCacheMaxSize;
+    private getTileCacheKey;
     private imageCache;
     private initializePromise?;
     private lastInitializedUrl?;
@@ -27,6 +34,26 @@ declare class CogTiles {
     getZoomLevelFromResolution(tileSize: number, resolution: number): number;
     getBoundsAsLatLon(): [number, number, number, number];
     getLatLon(input: number[]): [number, number];
+    /**
+     * Calculates the error multiplier based on zoom level and COG zoom range.
+     * - z >= maxZ: multiplier = 0.5 (fine meshes at high zoom, maximum precision)
+     * - z <= minZ: multiplier = 3.0 (coarse meshes at low zoom, maximum performance)
+     * - Otherwise: linear interpolation between 3.0 and 0.5
+     */
+    private getErrorMultiplierForZoom;
+    /**
+     * Calculates dynamic meshMaxError for a given zoom level and resolution.
+     * Formula: resolution * errorMultiplier, where multiplier scales from 3.0 (low zoom) to 0.5 (high zoom).
+     * Results are clamped to 0.5–100 meters to prevent pathological tessellation:
+     * - Min 0.5m ensures simplification always happens (no rounding to 0 with sub-meter pixels)
+     * - Max 100m prevents excessive simplification at low zoom with low-resolution COGs
+     */
+    private calculateDynamicMeshMaxError;
+    /**
+     * Gets the auto meshMaxError for a given overview index.
+     * Returns undefined if auto lookup has not been computed.
+     */
+    getMeshMaxErrorForImageIndex(imageIndex: number): number | undefined;
     /**
      * Builds lookup tables for zoom levels and estimated resolutions from a Cloud Optimized GeoTIFF (COG) object.
      *
@@ -43,6 +70,13 @@ declare class CogTiles {
      *   - The second array (`resolutionLookup`) maps each image index to its estimated resolution (m/pixel).
      */
     buildCogZoomResolutionLookup(cog: GeoTIFF): Promise<number[][]>;
+    /**
+     * Computes dynamic meshMaxError values for each overview based on COG resolution and zoom level.
+     * Called only for terrain COGs after buildCogZoomResolutionLookup() completes.
+     * Each overview's meshMaxError is calculated as: resolution * zoom-based multiplier, rounded to nearest integer.
+     * Multiplier ranges from 3.0 at minZ (coarse meshes) to 0.5 at maxZ (fine meshes).
+     */
+    private computeMeshMaxErrorLookup;
     /**
      * Determines the appropriate image index from the Cloud Optimized GeoTIFF (COG)
      * that best matches a given zoom level.
@@ -55,13 +89,13 @@ 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, signal?: AbortSignal): Promise<TypedArray[]>;
+    getTileFromImage(tileX: number, tileY: number, zoom: number, fetchSize?: number, signal?: AbortSignal): 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)
      */
     createEmptyTile(size?: number): Float32Array<ArrayBuffer>;
-    getTile(x: number, y: number, z: number, bounds?: Bounds, meshMaxError?: number, signal?: AbortSignal): Promise<TileResult | null>;
+    getTile(x: number, y: number, z: number, bounds?: Bounds, meshMaxError?: number, signal?: AbortSignal, skipTexture?: boolean): Promise<TileResult | null>;
     /**
      * Determines the data type (e.g., "Int32", "Float64") of a GeoTIFF image
      * by reading its TIFF tags.

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

@@ -1,11 +1,3 @@
-/**
- * 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.
- */
 export declare class KernelGenerator {
     /**
      * Compute terrain gradients (dzdx, dzdy) using Horn's method.

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

@@ -0,0 +1,2 @@
+export declare function toF32(n: number): number;
+export declare function isF32NoData(val: number, noData?: number | null): boolean;

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

@@ -53,6 +53,8 @@ export type GeoImageOptions = {
     useDataForOpacity?: boolean;
     useSingleColor?: boolean;
     blurredTexture?: boolean;
+    /** When true, skip generating a texture bitmap for this tile (mesh-only path). */
+    skipTexture?: boolean;
     clipLow?: number | null;
     clipHigh?: number | null;
     color?: ChromaColorInput;
@@ -76,6 +78,8 @@ export type GeoImageOptions = {
     useSwissRelief?: boolean;
     swissSlopeWeight?: number;
     useReliefGlaze?: boolean;
+    /** Strategy for detecting all-noData tiles. Options: 'full' | 'border+center' */
+    noDataCheck?: 'full' | 'border+center';
     disableLighting?: boolean;
 };
 export declare const DefaultGeoImageOptions: GeoImageOptions;
@@ -103,3 +107,12 @@ export interface TileResult {
     /** Optional: grayscale or color bitmap for Swiss relief or other overlays */
     bitmap?: Uint8ClampedArray | ImageBitmap;
 }
+/**
+ * Stores full TileResult including texture because:
+ * - Kernel computations (slope/hillshade/swiss relief → rawDerived) are expensive and cached
+ * - Texture generation from rawDerived is cheap (colorization only)
+ * - But caching texture avoids ImageBitmap regeneration overhead
+ * - For BitmapLayer: texture IS the primary output (must cache)
+ * Cache is cleared on URL/meshMaxError changes.
+ */
+export type CachedTileResult = TileResult;

package/dist/esm/types/layers/CogBitmapLayer.d.ts

@@ -17,7 +17,7 @@ export declare const urlType: {
 export type ClampToTerrainOptions = {
     terrainDrawMode?: string;
 };
-type MeshAndTexture = TileResult;
+type MeshAndTexture = TileResult | null;
 /** Props added by the CogBitmapLayer */
 type _CogBitmapLayerProps = {
     /** Image url that encodes raster data. * */
@@ -56,12 +56,12 @@ export default class CogBitmapLayer<ExtraPropsT extends object = object> extends
     initializeState(context: any): Promise<void>;
     init(): Promise<void>;
     updateState({ props, oldProps }: UpdateParameters<this>): void;
-    getTiledBitmapData(tile: TileLoadProps): Promise<TileResult>;
-    renderSubLayers(props: TileLayerProps<TileResult> & {
+    getTiledBitmapData(tile: TileLoadProps): Promise<TileResult | null>;
+    renderSubLayers(props: TileLayerProps<TileResult | null> & {
         id: string;
-        data: TileResult;
-        tile: Tile2DHeader<TileResult>;
+        data: TileResult | null;
+        tile: Tile2DHeader<TileResult | null>;
     }): BitmapLayer<{}> | null;
-    renderLayers(): TileLayer<TileResult, {}> | null;
+    renderLayers(): TileLayer<TileResult | null, {}> | null;
 }
 export {};

package/dist/esm/types/layers/CogTerrainLayer.d.ts

@@ -29,7 +29,7 @@ type TerrainLoadProps = {
 };
 type MeshAndTexture = [TileResult | null, TextureSource | null];
 /** All properties supported by CogTerrainLayer */
-export type CogTerrainLayerProps = _CogTerrainLayerProps & TileLayerProps<MeshAndTexture> & CompositeLayerProps;
+export type CogTerrainLayerProps = _CogTerrainLayerProps & TileLayerProps<MeshAndTexture | null> & CompositeLayerProps;
 /** Props added by the CogTerrainLayer */
 type _CogTerrainLayerProps = {
     /** Image url that encodes height data. * */
@@ -37,8 +37,8 @@ type _CogTerrainLayerProps = {
     isTiled?: boolean;
     /** Image url to use as texture. * */
     texture?: URLTemplate;
-    /** Martini error tolerance in meters, smaller number -> more detailed mesh. * */
-    meshMaxError?: number;
+    /** Martini error tolerance in meters, smaller number -> more detailed mesh. Set to 'auto' for dynamic per-zoom quantization. * */
+    meshMaxError?: number | 'auto';
     /** Bounding box of the terrain image, [minX, minY, maxX, maxY] in world coordinates. * */
     bounds?: Bounds | null;
     /** Color to use if texture is unavailable. * */
@@ -67,7 +67,7 @@ type _CogTerrainLayerProps = {
     workerUrl?: string;
 };
 /** Render mesh surfaces from height map images. */
-export default class CogTerrainLayer<ExtraPropsT extends object = object> extends CompositeLayer<ExtraPropsT & Required<_CogTerrainLayerProps & Required<TileLayerProps<MeshAndTexture>>>> {
+export default class CogTerrainLayer<ExtraPropsT extends object = object> extends CompositeLayer<ExtraPropsT & Required<_CogTerrainLayerProps & Required<TileLayerProps<MeshAndTexture | null>>>> {
     static defaultProps: DefaultProps<_CogTerrainLayerProps>;
     static layerName: string;
     terrainUrl: string;
@@ -84,13 +84,13 @@ export default class CogTerrainLayer<ExtraPropsT extends object = object> extend
     init(): Promise<void>;
     updateState({ props, oldProps }: UpdateParameters<this>): void;
     loadTerrain({ elevationData, bounds, elevationDecoder, meshMaxError, signal, }: TerrainLoadProps): Promise<MeshAttributes> | null;
-    getTiledTerrainData(tile: TileLoadProps): Promise<MeshAndTexture>;
-    renderSubLayers(props: TileLayerProps<MeshAndTexture> & {
+    getTiledTerrainData(tile: TileLoadProps): Promise<MeshAndTexture | null>;
+    renderSubLayers(props: TileLayerProps<MeshAndTexture | null> & {
         id: string;
-        data: MeshAndTexture;
-        tile: Tile2DHeader<MeshAndTexture>;
+        data: MeshAndTexture | null;
+        tile: Tile2DHeader<MeshAndTexture | null>;
     }): SimpleMeshLayer<any, {}> | null;
-    onViewportLoad(tiles?: Tile2DHeader<MeshAndTexture>[]): void;
+    onViewportLoad(tiles?: Tile2DHeader<MeshAndTexture | null>[]): void;
     renderLayers(): Layer | null | LayersList;
 }
 export {};

package/package.json

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