Skip to main content

ZarrCubeVelocityProvider

The ZarrCubeVelocityProvider loads and visualizes 3D vector fields (U, V components) from Zarr datasets as animated particle layers in Cesium using the WindLayer from cesium-wind-layer

This provider enables real-time visualization of:

  • Ocean currents
  • Atmospheric wind fields
  • Depth/height-sliced velocity maps
  • Animated flow patterns through depth

It supports:

  • Zarr v2 and v3
  • Multiscale pyramids
  • Legacy ndpyramid, GeoZarr, and TopoZarr multiscale layouts
  • GPU-accelerated particle animations
  • Dynamic elevation slicing
  • CF-compliant time decoding for selectors
  • Vertical exaggeration
  • Colormap-based speed visualization
  • Flexible WindLayer configuration

When to Use ZarrCubeVelocityProvider​

Use this provider when you have:

  • Vector fields stored in Zarr
  • 3D volumes representing velocity over depth or height
  • Two variables: u (zonal) and v (meridional)
  • Desire to visualize with animated particles

Typical datasets:

  • Ocean model outputs (NEMO, ROMS, HYCOM)
  • Atmospheric reanalysis winds
  • Climate simulation velocity cubes
  • Any Zarr-based U/V dataset

If you want:

Basic Example​

import { Viewer } from 'cesium';
import { ZarrCubeVelocityProvider } from 'zarr-cesium';

const viewer = new Viewer('cesiumContainer');

const options = {
  urls: {
    u: 'https://example.com/uo.zarr',
    v: 'https://example.com/vo.zarr'
  },
  variables: { u: 'uo', v: 'vo' },
  bounds: { west: -10, south: 30, east: 10, north: 45 }
};
const windCube = new ZarrCubeVelocityProvider(viewer, options);

await windCube.load();

This creates a stack of animated particle layers, one per elevation slice.

Options​

interface VelocityOptions {
  urls: { u: string; v: string }; // Public Zarr stores for U and V components
  variables: { u: string; v: string }; // Zarr array names for U and V
  bounds: BoundsProps; // geographic rectangle
  dimensionNames?: DimensionNamesProps; // Custom dimension names. If not provided, defaults will be used or identified automatically based on CF conventions.
  selectors?: Record<string, ZarrSelectorsProps>; // Initial dimension slices
  multiscaleLevel?: number; // Index in the metadata's level list; defaults to 0
  zarrVersion?: 2 | 3; // Zarr version (auto-detected if not set)
  sliceSpacing?: number; // Vertical sampling interval
  verticalExaggeration?: number; // Vertical exaggeration factor
  belowSeaLevel?: boolean; // Whether to render layers below sea level
  flipElevation?: boolean; // Flip elevation axis
  opacity?: number; // Layer opacity (0–1)
  colormap?: ColorMapName; // Name from jsColormaps, based on matplotlib colormaps
  scale?: [number, number]; // Min/max for color scaling
  windOptions?: Partial<WindLayerOptions>; // Additional WindLayer configuration
  crs?: CRS; // Force CRS (auto-detected if not set)
  multiscaleFormat?: MultiscaleFormat; // 'auto' (default), 'legacy', 'geozarr', or 'topozarr'
}

Loading Data​

await windCube.load();

This loads:

  • u velocity cube
  • v velocity cube
  • Multiscale metadata
  • Dimension values (lon, lat, elevation)
  • Windowed spatial slice (based on bounds)
  • Elevation slice ranges and spacing

Then it automatically creates Cesium WindLayer instances (one per elevation slice) and adds them to the viewer.

How It Renders the Data​

The provider generates one WindLayer per elevation slice, spaced by sliceSpacing:

  • sliceSpacing = 1 → one layer per model level
  • sliceSpacing = 2 → one layer every two levels
  • sliceSpacing = n → coarse vertical sampling

Each level has:

  • a 2D U-field
  • a 2D V-field
  • a computed altitude
  • a WindLayer placed at the correct height

Particles animate based on u/v speed and direction.

WindLayer Integration​

Each layer receives a windData structure:

{
  u: { array: Float32Array, min: -0.5, max: 0.5 },
  v: { array: Float32Array, min: -0.5, max: 0.5 },
  width,
  height,
  unit: 'm s-1',
  bounds: this.bounds
}

Plus user-configurable particle system settings:

{
  speedFactor,
  lineWidth,
  lineLength,
  particlesTextureSize,
  flipY
  ...
}

Supported CRS​

Zarr datasets may store coordinate values in:

  • EPSG:4326 (lat, lon degrees)
  • EPSG:3857 (Web Mercator meters)

The provider detects the CRS automatically using:

  • Zarr metadata
  • consolidated metadata
  • coordinate ranges (West/East > 360 → Web Mercator)

For example, you can set the CRS explicitly:

// set CRS to Web Mercator in LayerOptions
crs: 'EPSG:3857';

Multiscale Support​

If the dataset defines Zarr multiscale pyramids, e.g.:

"multiscales": [
  { "datasets": [ {"path": "0"}, {"path": "1"}, {"path": "2"} ] }
]

Then:

  • The provider loads the requested multiscaleLevel
  • multiscaleFormat: 'auto' detects legacy and GeoZarr-style level paths
  • Set multiscaleFormat explicitly if the metadata does not identify its layout
  • multiscaleLevel follows the order stored in the metadata
  • Resolution, W×H×Z, and bounding box adapt
  • Switching levels triggers a reload

For a TopoZarr store, whose level 0 is normally full resolution:

multiscaleFormat: 'topozarr',
multiscaleLevel: 0 // loads TopoZarr's full-resolution level

Legacy ndpyramid stores commonly use the opposite order, with level 0 as the coarsest resolution. Inspect windCube.levelInfos when choosing a level. GeoZarr/TopoZarr metadata supplies levels through multiscales.layout[].asset, whereas legacy metadata uses multiscales[0].datasets[].path.

Runtime API​

Update Dimension Selectors​

await windCube.updateSelectors({
  selectors: { time: { type: 'index', selected: 5 } },
  multiscaleLevel: 1,
  bounds: { west: -20, south: 25, east: 20, north: 60 }
});

This reloads U and V cubes, destroys old wind layers, and creates new ones.

CF time coordinates are decoded to ISO strings in windCube.dimensionValues. Selectors may therefore use either an array index or a decoded time value, for example { type: 'value', selected: '2020-01-01T00:00:00.000Z' }.

All the parameters are optional. If not provided, the current value is retained.

To get the current selectors, multiscale level, all multiscale levels, and dimensions values, use:

const selectors = windCube.selectors;
const multiscaleLevel = windCube.multiscaleLevel;
const allMultiscaleLevels = windCube.levelInfos;
const dimNames = windCube.dimensionValues;

This returns a mapping of dimension names to their list of values, e.g.:

dimNames = {
  time: ['2020-01-01T00:00Z', '2020-01-02T00:00Z', ...],
  elevation: [0, 10, 20, 30, ...]
}

And the current selector values, e.g.:

selectors = {
  time: { type: 'index', selected: 3 },
  depth: { type: 'index', selected: [0, 50] }
};

And the multiscale level information:

levelInfos = ["0", "1", "2", ...];
multiscaleLevel = 1; // index of current level. In this case, that level would be "1"

And with that, you can build UI controls (sliders, dropdowns) to update the layer dynamically.

Update Slice Rendering​

Control vertical sampling or exaggeration:

await windCube.updateSlices({
  sliceSpacing: 2,
  verticalExaggeration: 8,
  belowSeaLevel: true
});

This:

  • Removes all current WindLayers
  • Recomputes heights
  • Rebuilds wind layers with new parameters

All the parameters are optional. If not provided, the current value is retained.

Update Style​

Adjust how particles are visualized:

windCube.updateStyle({
  opacity: 0.4,
  scale: [-1, 1],
  colormap: 'plasma',
  windOptions: {
    particleDensity: 5,
    particleScale: 2.0,
    maxParticles: 20000
  }
});

This applies instantly to all existing layers.

The full list of supported colormaps is available in the Colormaps section.

The windOptions allows fine-tuning of particle system parameters. For more info, see the WindLayerOptions information on cesium-wind-layer github repo

Remove Layers, Clearing & Destroying​

Remove all velocity layers:

windCube.destroy();

Used internally when:

  • Bounds change
  • Multiscale level changes
  • Slice spacing changes
  • Elevation selectors change
  • Vertical exaggeration changes