Deck-gl-grid

A package with custom deck.gl layers for visualizing gridded data, developed by Oceanum.

Features

• GContourLayer: Renders contour lines for gridded data
• ImageLayer: Displays image data as a texture overlay
• MaskLayer: Creates masked regions using vector tile data
• ParticleLayer: Animates particles based on vector field data
• PartmeshLayer: Renders a mesh representation of vector field data
• PcolorLayer: Renders gridded data as colored cells

Installation

NPM

npm install @oceanum/deck-gl-grid

Yarn

yarn add @oceanum/deck-gl-grid

Dependencies

This package has the following peer dependencies:

"@deck.gl/core": "^9.1.0",
"@deck.gl/geo-layers": "^9.1.0",
"@deck.gl/layers": "^9.1.0",
"@deck.gl/react": "^9.1.0",
"@luma.gl/constants": "^9.1.0",
"@luma.gl/core": "^9.1.0",
"@luma.gl/engine": "^9.1.0",
"@luma.gl/shadertools": "^9.1.0",
"@luma.gl/webgl": "^9.1.0",
"react": "^19.0.0",
"react-dom": "^19.0.0"

Make sure these are installed in your project.

Building from Source

1. Clone the repository

git clone https://github.com/oceanum/deck-gl-grid.git
cd deck-gl-grid

1. Install dependencies

npm install

1. Build the package

npm run build

1. For pydeck compatibility

npm run build:pydeck

Usage

Importing the Layers

import {
  GContourLayer,
  ImageLayer,
  MaskLayer,
  ParticleLayer,
  PartmeshLayer,
  PcolorLayer
} from '@oceanum/deck-gl-grid';

Layer Examples

GContourLayer

The GContourLayer renders contour lines for gridded data.

const contourLayer = new GContourLayer({
  id: 'contour-layer',
  data: gridData,
  datakeys: {
    x: 'longitude',
    y: 'latitude',
    c: 'temperature' // Or use u/v for vector magnitude
  },
  colormap: COLORMAP_OBJECT, // Optional color mapping
  linewidth: 1,
  altitude: 0,
  opacity: 1.0,
  levels: [0, 5, 10, 15, 20], // Contour levels
});

PcolorLayer

The PcolorLayer renders gridded data as colored cells.

const pcolorLayer = new PcolorLayer({
  id: 'pcolor-layer',
  data: gridData,
  datakeys: {
    x: 'longitude',
    y: 'latitude',
    c: 'temperature'
  },
  colormap: COLORMAP_OBJECT,
  altitude: 0,
  opacity: 1.0,
});

ParticleLayer

The ParticleLayer animates particles based on vector field data.

const particleLayer = new ParticleLayer({
  id: 'particle-layer',
  data: vectorData,
  datakeys: {
    x: 'longitude',
    y: 'latitude',
    u: 'u_component',
    v: 'v_component'
  },
  colormap: COLORMAP_OBJECT, // Optional
  altitude: 0,
  opacity: 1.0,
  size: 3, // Particle size
  length: 12, // Particle trail length
  speed: 1.0, // Animation speed
  npart: 1000, // Number of particles
});

ImageLayer

The ImageLayer displays image data as a texture overlay.

const imageLayer = new ImageLayer({
  id: 'image-layer',
  data: imageData, // Can be from GeoTIFF or other sources
  datakeys: {
    x: 'longitude',
    y: 'latitude',
    b: 'band' // Optional band key
  },
  altitude: 0,
  opacity: 1.0,
});

MaskLayer

The MaskLayer creates masked regions using vector tile data.

const maskLayer = new MaskLayer({
  id: 'mask-layer',
  maskUrl: 'https://api.mapbox.com/v4/mapbox.country-boundaries-v1/{z}/{x}/{y}.vector.pbf?access_token=YOUR_MAPBOX_TOKEN',
  invert: false, // Whether to invert the mask
});

PartmeshLayer

The PartmeshLayer renders a mesh representation of vector field data.

const partmeshLayer = new PartmeshLayer({
  id: 'partmesh-layer',
  data: vectorData,
  datakeys: {
    x: 'longitude',
    y: 'latitude',
    u: 'u_component',
    v: 'v_component'
  },
  colormap: COLORMAP_OBJECT, // Optional
  altitude: 0,
  opacity: 1.0,
});

Data Format

The layers expect data in the following format:

{
  variables: {
    longitude: { data: [lon1, lon2, ...] },
    latitude: { data: [lat1, lat2, ...] },
    temperature: { data: [[val1, val2, ...], [val3, val4, ...], ...] },
    // For vector fields
    u_component: { data: [[u1, u2, ...], [u3, u4, ...], ...] },
    v_component: { data: [[v1, v2, ...], [v3, v4, ...], ...] }
  }
}

Alternatively, the data can be structured with coords and data_vars:

{
  coords: {
    longitude: { data: [lon1, lon2, ...] },
    latitude: { data: [lat1, lat2, ...] }
  },
  data_vars: {
    temperature: { data: [[val1, val2, ...], [val3, val4, ...], ...] },
    // For vector fields
    u_component: { data: [[u1, u2, ...], [u3, u4, ...], ...] },
    v_component: { data: [[v1, v2, ...], [v3, v4, ...], ...] }
  }
}

Colormap Format

Colormaps are defined as objects with scale and domain properties:

const COLORMAP = {
  scale: [
    '#6271b7', '#39619f', '#4a94a9', '#4d8d7b', '#53a553',
    '#359f35', '#a79d51', '#9f7f3a', '#a16c5c', '#813a4e'
  ],
  domain: [0, 10, 20, 30, 40, 50, 60, 70, 80, 90]
};

Using with pydeck

The package includes Python bindings for use with pydeck. Install the pydeck-grid package:

pip install pydeck-grid

Example usage:

import pydeck as pdk
from pydeck_grid import PcolorLayer

# Create a layer
layer = PcolorLayer(
    id="pcolor-layer",
    data=grid_data,
    get_position=["longitude", "latitude"],
    get_color=["temperature"],
    colormap={"scale": ["blue", "green", "red"], "domain": [0, 50, 100]},
    opacity=0.8
)

# Create a deck
deck = pdk.Deck(
    layers=[layer],
    initial_view_state=pdk.ViewState(
        latitude=0,
        longitude=0,
        zoom=2
    )
)

# Display the deck
deck.show()

Examples

See the stories directory for more examples of how to use each layer.

Development

Running the demo

npm start

Running Storybook

npm run storybook

License

MIT