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 the NOC-OI cesium-wind-layer fork.

Zarr-Cesium targets fork release v0.11.0. Compared with the upstream release, this version adds minVisibleRatio, which clamps camera-driven particle width, trail-length, and speed scaling (0.6 by default, or 1 to retain the overview scale at every zoom). It also resets the visible longitude/latitude ranges and pixel scale when zooming back to a globe overview, preventing regional-view styling from becoming stuck. Tagged releases include an installable package tarball, allowing Zarr-Cesium to use a fixed fork build.

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 and GeoZarr 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 }; // URLs; each is required unless its store is supplied
  stores?: { u?: Readable; v?: Readable }; // Custom U/V stores, including IcechunkStore
  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', or 'geozarr'
  requestOverrides?: RequestOverrides; // Static options shared by URL-backed U/V stores
  transformRequest?: TransformRequest; // Per-request auth, proxy, or signed URL transform
  onAuthError?: OnAuthError; // Called once for HTTP 400/401 responses
}

Icechunk and Custom Stores​

Supply one Zarrita-compatible Readable store for each component. When U and V are arrays in the same Icechunk repository, the same store can be used for both:

import { IcechunkStore } from 'icechunk-js';
import { ZarrCubeVelocityProvider } from 'zarr-cesium';

const store = await IcechunkStore.open(repositoryUrl, {
  branch: 'main',
  formatVersion: 'v1'
});

const velocity = new ZarrCubeVelocityProvider(viewer, {
  stores: { u: store, v: store },
  variables: { u: 'uo', v: 'vo' },
  bounds: { west: -50, south: -20, east: 10, north: 20 }
});

await velocity.load();

You can mix sources, for example urls.u with stores.v, provided both components have a source.

Private HTTP Stores​

URL-backed U and V stores share request configuration. The transformed fetch and its one-shot authentication callback are reused across both components:

const velocity = new ZarrCubeVelocityProvider(viewer, {
  urls: {
    u: 'https://data.example.com/private-u.zarr',
    v: 'https://data.example.com/private-v.zarr'
  },
  variables: { u: 'uo', v: 'vo' },
  bounds,
  transformRequest: async url => ({
    url,
    headers: { Authorization: `Bearer ${await getAccessToken()}` }
  }),
  onAuthError: status => refreshSession(status)
});

Use requestOverrides instead when credentials and headers are static.

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,
  minVisibleRatio,
  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 GeoZarr store whose level 0 is full resolution:

multiscaleFormat: 'geozarr',
multiscaleLevel: 0 // loads the GeoZarr 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 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 information, see the WindLayerOptions documentation in the NOC-OI fork.

Query Velocity Data​

Velocity queries return derived speed alongside aligned U and V components:

const point = await windCube.queryData({
  type: 'Point',
  coordinates: [-4.2, 50.1]
});

console.log(point.values);       // speed
console.log(point.components.u); // U component
console.log(point.components.v); // V component

const profile = await windCube.getVerticalProfile([-4.2, 50.1]);
const series = await windCube.getTimeSeries([-4.2, 50.1]);

Input positions use WGS84 longitude/latitude. A ranged time selector reads the source arrays, while an elevation range returns values across the loaded vertical subset. Pass { signal } to cancel a query.

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