Skip to main content

Getting Started

Installation​

npm install zarr-cesium

zarr-cesium supports CesiumJS 1.119 and newer, including CesiumJS 1.142+.

Basic Usage​

1. Initialize Cesium​

import { Viewer } from 'cesium';

const viewer = new Viewer('cesiumContainer');

Rendering 2D Scalar Data (ZarrLayerProvider)​

import { ZarrLayerProvider } from 'zarr-cesium';

const viewer = new Viewer('cesiumContainer');

const options = {
  url: 'https://example.com/data.zarr',
  variable: 'salinity',
  colormap: 'viridis',
  scale: [30, 40]
};
const layer = await ZarrLayerProvider.createLayer(viewer, options);

viewer.imageryLayers.add(layer);

Example of visualizing a Zarr dataset in a CesiumJS map using Zarr-Cesium. You can easily change the timestamp, colormap, and scale.

More details on this provider can be found in the ZarrLayerProvider documentation.

Icechunk and custom stores​

The 2D provider also accepts any Zarrita-compatible readable store. Install the backend client in your application and pass the opened store instead of a URL:

The Icechunk and private Zarr integrations were directly inspired by CarbonPlan's zarr-layer implementation.

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

const store = await IcechunkStore.open('https://example.com/data.icechunk', {
  branch: 'main',
  formatVersion: 'v1'
});

const layer = await ZarrLayerProvider.createLayer(viewer, {
  store,
  variable: 'temperature',
  colormap: 'viridis',
  scale: [0, 30]
});
viewer.imageryLayers.add(layer);

Querying rendered data​

All providers support point queries and convenience methods for common scientific profiles. The 2D and scalar-cube providers also support transects:

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

const series = await layer.imageryProvider.getTimeSeries([-4.2, 50.1]);
const profile = await cube.getVerticalProfile([-4.2, 50.1]);
const transect = await cube.getTransect([-5, 50], [-3, 51], undefined, {
  samples: 100
});

Input positions use WGS84 longitude/latitude. Pass an AbortSignal through query options to cancel long-running reads.

Rendering 3D Volumes (ZarrCubeProvider)​

import { ZarrCubeProvider } from 'zarr-cesium';

const cube = new ZarrCubeProvider(viewer, {
  url: 'https://example.com/ocean_temp.zarr',
  variable: 'temperature',
  bounds: { west: -20, south: 30, east: 10, north: 60 },
  colormap: 'plasma',
  verticalExaggeration: 50
});

await cube.load();

With elevationMode: 'height', each level is placed at elevation * verticalExaggeration. With elevationMode: 'depth', it is placed at (elevation - maximumElevation) * verticalExaggeration. Depth mode therefore moves the complete cube below sea level while preserving the original pairing between every elevation coordinate and its data-plane index.

Latitude orientation is inferred from coordinate values. Use latIsAscending only when the dataset metadata is missing or incorrect. Use flipElevation separately when the vertical placement of the source data planes must be reversed. Set elevationMode: 'depth' when positive vertical coordinates represent depths below sea level. Its default is 'height'. After loading, build slice controls from cube.cubeDimensionValues rather than the full cube.dimensionValues axes.

Example of visualizing a 4D Zarr dataset in a CesiumJS map as a 3D cube using Zarr-Cesium. You can easily change slices and view the cube in different ways, styles, and scales.

More details on this provider can be found in the ZarrCubeProvider documentation.

Rendering 3D Vector Fields (ZarrCubeVelocityProvider)​

import { ZarrCubeVelocityProvider } from 'zarr-cesium';

const velocity = new ZarrCubeVelocityProvider(viewer, {
  urls: {
    u: 'https://example.com/uo.zarr',
    v: 'https://example.com/vo.zarr'
  },
  variables: { u: 'uo', v: 'vo' },
  bounds: { west: -50, south: -20, east: 10, north: 20 },
  colormap: 'plasma',
  selectors: {
    elevation: { type: 'index', selected: [0, 22] }
  }
});

await velocity.load();

The provider passes the selected elevation-major U/V cube to one cube-aware WindLayer. U and V must resolve to matching longitude, latitude, and elevation coordinate grids. sliceSpacing controls which model levels receive particles, while the actual elevation coordinate values determine their rendered heights.

This uses cube-cesium-wind-layer, the NOC-OI fork of the original cesium-wind-layer, for GPU-accelerated particle flow animations. Its minVisibleRatio option prevents particle width, trail length, and speed from shrinking below a configured fraction while zooming.

Example of visualizing wind-speed vector data from Zarr in a CesiumJS map using Zarr-Cesium. This dataset is from Hurricane Florence, which occurred in 2018. You can easily change the timestamp, colormap, and particle speed.

More details on this provider can be found in the ZarrCubeVelocityProvider documentation.

Both 3D providers support the same private-store request hooks as the 2D provider. ZarrCubeProvider accepts store, while ZarrCubeVelocityProvider accepts stores.u and stores.v for Zarrita-compatible stores such as Icechunk. URL-backed stores accept requestOverrides, transformRequest, and onAuthError.

Next Steps​