A Cesium integration library for visualizing Zarr datasets in 2D and 3D.
npm install zarr-cesium


CesiumJS providers for interactive 2D and 3D visualization of environmental geospatial data stored in Zarr.
- Documentation: https://noc-oi.github.io/zarr-cesium/docs
- Demo: https://noc-oi.github.io/zarr-cesium/
---
The Zarr-Cesium Visualization Toolkit provides CesiumJS data providers for rendering n-dimensional datasets stored in the Zarr format — streamed directly from cloud object stores (HTTP/S3/GCS) without preprocessing, conversion, or a backend server.
- Zarr v2 and v3 compatibility
Read datasets from any Zarr store, including public cloud object storage.
- Multiscale or single-scale datasets
Automatically handles multi-resolution datasets (from ndpyramid) or standard Zarr datasets.
- 2D & 3D visualization
Render gridded scalar, vector, and volumetric data directly in CesiumJS.
- CRS-aware
Supports EPSG:4326 (Geographic) and EPSG:3857 (Web Mercator) coordinate systems with automatic detection and transformation.
- On-demand streaming
Tiles and slices are fetched and decoded dynamically — no conversion to imagery tiles required.
- GPU-accelerated rendering
Uses WebGL and Cesium primitives for fast visualization of large datasets.
- Style and animation controls
Programmatic control of color maps, opacity, scale range, slice spacing, and vertical exaggeration.
---
The toolkit provides three Cesium provider classes, each specialized for a different data type:
| Provider Class | Purpose | Description |
| -------------------------- | -------------------- | ----------------------------------------------------------------------------------------- |
| ZarrLayerProvider | 2D scalar fields | Renders single-level variables as Cesium imagery layers (e.g., temperature, chlorophyll). |
| ZarrCubeProvider | 3D volumetric fields | Renders volumetric cubes with horizontal and vertical slices (e.g., ocean temperature). |
| ZarrCubeVelocityProvider | 3D vector fields | Visualizes vector flow (u/v components) using animated particle advection. |
---
``bash`
npm install zarr-cesium
To run the demo website locally, clone the repository:
`bash`
git clone https://github.com/noc-oi/zarr-cesium.git
cd zarr-cesium/demo
Create a .env file in the demo directory with your Cesium access token:
`env`
VITE_CESIUM_TOKEN=your_cesium_access_token_here
Install dependencies and start the development server:
`bash`
npm install
npm run dev
The demo site will be available at http://localhost:3000.
If you want to use your own Zarr datasets, you can modify the demo code in demo/src/application/data/layers-json.tsx to point to your data URLs. You may need to adjust variable names, bounds, and other parameters accordingly.
---
Renders 2D scalar fields as Cesium imagery overlays using WebGL. It supports both single-scale and multiscale Zarr datasets, and provides GPU-accelerated color mapping.
Example:
`ts
import { ZarrLayerProvider } from 'zarr-cesium';
import { Viewer } from '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);
`
For more details, see the Zarr-Cesium documentation.
https://github.com/user-attachments/assets/33fc6dd2-38fa-4b20-a346-0a175f90eba1
> Example of visualizing a Zarr dataset in a CesiumJS map using Zarr-Cesium. You can easily change the timestamp, colormap, and scale.
---
Renders 3D volumetric Zarr cubes as Cesium primitives — including vertical and horizontal slices. It supports both Zarr v2/v3 and multiscale datasets, with adjustable color mapping and vertical exaggeration.
Example:
`ts
import { ZarrCubeProvider } from 'zarr-cesium';
import { Viewer } from 'cesium';
const viewer = new Viewer('cesiumContainer');
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();
`
For more details, see the Zarr-Cesium documentation.
https://github.com/user-attachments/assets/8b066725-c6c7-4b7a-9fc0-d632b623937c
> 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.
---
Renders 3D velocity fields from U/V components as animated wind/current layers using cesium-wind-layer.
It supports both Zarr v2/v3 and multiscale datasets, with configurable slice spacing and particle animation parameters.
Example:
`ts
import { ZarrCubeVelocityProvider } from 'zarr-cesium';
import { Viewer } from 'cesium';
const viewer = new Viewer('cesiumContainer');
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();
``
For more details, see the Zarr-Cesium documentation.
https://github.com/user-attachments/assets/a54ddd70-9b00-4a3e-9cb9-41025cceffd0
> 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.
---
For more details on how to contribute to the development of this toolkit, please refer to the DEV-README.md file.
This tool is built with:
- CesiumJS
- Zarrita
- cesium-wind-layer
- jscolormaps
This work is part of the Atlantis project, a UK initiative supporting long-term ocean observations and marine science in the Atlantic. The project is led by the National Oceanography Centre (NOC).