@gisatcz/deckgl-geolib

A Deck.gl extension for rendering Cloud-Optimized GeoTIFF (COG) data.

This library allows you to efficiently visualize high-resolution bitmap and terrain data directly from COG sources. It includes the CogBitmapLayer for 2D imagery and thematic layers and the CogTerrainLayer for 3D terrain meshes.

Features

• COG Rendering: Efficiently loads and displays COG files directly without a backend server.
• Bitmap and Terrain Layers: Supports visualizing both raster and elevation data.
• Customizable Rendering: Custom color scales, multichannel support, heatmaps, categorical classification, and opacity control.
• Terrain Texturing: Drape a styled visualization (elevation heatmap, external imagery) directly onto the 3D terrain mesh — no separate layer needed.
• Kernel Analysis: Compute slope and hillshade directly from elevation data using 3×3 neighborhood kernels (Horn's method / ESRI algorithm).
• Swiss Relief Shading: Apply hypsometric color blending with hillshade and slope for superior terrain perception. Supports both terrain baking and transparent glaze overlays on satellite imagery.
• Raw Value Picking: Access original raster values (elevation, band values, slope, hillshade) at hover/click locations with no extra network requests.

Installation

To use this library, you need to have deck.gl and its dependencies installed.

npm install @gisatcz/deckgl-geolib
# or
yarn add @gisatcz/deckgl-geolib

For more information, visit the npm package page.

Documentation

• Layer Showcase – Visual examples (RGB, Heatmaps, Terrain, Slope/Hillshade, Picking).
• API Reference – Detailed property configuration.
• Internal Architecture – Technical details about the core processing engines.

Usage

1. CogBitmapLayer

Used for displaying 2D rasters: Raw Observation (Satellite/Aerial), Data Structure (Multi-band/Single-band), and Analysis Output (Thematic/Categorical).

import { CogBitmapLayer } from '@gisatcz/deckgl-geolib';

const cogLayer = new CogBitmapLayer({
  id: 'cog_bitmap_name',
  rasterData:  'cog_bitmap_data_url.tif',
  isTiled: true,
  cogBitmapOptions: {
    type: 'image'
  }
});

2. CogTerrainLayer

Used for displaying 3D terrain from elevation data. Supports draping a styled texture derived from the elevation itself.

import { CogTerrainLayer } from '@gisatcz/deckgl-geolib';

const cogLayer = new CogTerrainLayer({
  id: 'cog_terrain_name',
  elevationData: 'cog_terrain_data_url.tif',
  isTiled: true,
  tileSize: 256,
  operation: 'terrain+draw',
  terrainOptions: {
    type: 'terrain',
    useHeatMap: true,
    useChannel: 1,
    colorScale: ['#440154', '#20908d', '#fde725'],
    colorScaleValueRange: [0, 3000],
  }
});

3. Kernel Analysis (Slope & Hillshade)

Compute slope or hillshade directly from elevation data and drape it as a texture on the terrain mesh.

import { CogTerrainLayer } from '@gisatcz/deckgl-geolib';

const slopeLayer = new CogTerrainLayer({
  id: 'cog_slope',
  elevationData: 'cog_terrain_data_url.tif',
  isTiled: true,
  tileSize: 256,
  operation: 'terrain+draw',
  terrainOptions: {
    type: 'terrain',
    useChannel: 1,
    useSlope: true,           // or useHillshade: true
    useHeatMap: true,
    colorScale: [[255, 255, 255], [235, 200, 150], [200, 80, 50], [100, 40, 30]],
    colorScaleValueRange: [0, 90], // degrees
  },
});

Data Preparation

For this library to work efficiently, your COG must be Web-Optimized and projected in Web Mercator (EPSG:3857).

Quick Checklist: 1. Projection: Web Mercator EPSG:3857 2. Tiling: 256x256 tiles 3. Compression: DEFLATE is recommended

Use the following rio-cogeo command to generate compatible files:

rio cogeo create \
  --cog-profile=deflate \
  --blocksize=256 \
  --overview-blocksize=256 \
  --web-optimized \
  --nodata=nan \
  --forward-band-tags \
  [input_file.tif] \
  [output_cog_file.tif]

Architecture & Development

This repository is a monorepo containing the core library and example applications.

• geoimage/: The core library source code.
• example/: A React application for testing the layers.

Building Locally

# 1. Install dependencies
yarn install

# 2. Build the library
yarn build

# 3. Run the example app
yarn start

_{Maintained by Gisat}