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();

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'
});

await velocity.load();

This uses the NOC-OI fork of 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​