ZarrCubeProvider
Provides rendering of volumetric (3D) Zarr datasets as Cesium primitives.
Remarks
This class handles loading Zarr cubes, slicing them along latitude, longitude, and elevation axes, and rendering those slices as textured Cesium primitives (both horizontal and vertical).
It supports configurable color scales, opacity, vertical exaggeration, and multiple visualization modes.
Example
const cubeProvider = new ZarrCubeProvider(viewer, {
url: 'https://example.com/mycube.zarr',
variable: 'temperature',
bounds: { west: -20, south: 30, east: 10, north: 60 },
showHorizontalSlices: true,
showVerticalSlices: true,
colormap: 'viridis'
});
await cubeProvider.load();
Accessors
queryDimensionValues
Get Signature
get queryDimensionValues(): DimensionValues;
Coordinate values addressable by queries against the loaded cube subset.
Returns
queryIndexOffsets
Get Signature
get queryIndexOffsets(): Record<string, number>;
Global coordinate offsets represented by index zero of the in-memory subset.
Returns
Record<string, number>
Offsets used by shared profile and transect query helpers.
Constructors
Constructor
new ZarrCubeProvider(viewer, options): ZarrCubeProvider;
Creates a new instance of ZarrCubeProvider.
Parameters
| Parameter | Type | Description |
|---|---|---|
viewer | CesiumHost | Cesium viewer or widget instance to which primitives will be added. |
options | CubeOptions | Configuration for the cube visualization (see CubeOptions). |
Returns
ZarrCubeProvider
Throws
If neither options.url nor options.store is provided.
Methods
clear()
clear(): void;
Removes all currently rendered slice primitives from the scene.
Returns
void
Remarks
Loaded Zarr data and current selectors remain available, so slices can be recreated with updateSlices.
destroy()
destroy(): void;
Removes all Cesium primitives owned by this provider.
Returns
void
Remarks
The currently loaded array remains in memory. Call load or updateSelectors to render it again.
getFullTransect()
getFullTransect(
start,
end,
selectors?,
options?): Promise<FullTransectResult>;
Samples every loaded elevation along a WGS84 line.
Parameters
| Parameter | Type | Description |
|---|---|---|
start | QueryPosition | Starting [longitude, latitude] coordinate in degrees. |
end | QueryPosition | Ending [longitude, latitude] coordinate in degrees. |
selectors? | ZarrSelectors | Fixed selectors for dimensions other than elevation. |
options? | TransectQueryOptions | Sample count, concurrency, and cancellation controls. |
Returns
Promise<FullTransectResult>
A distance-by-elevation value matrix.
getSlices()
getSlices(): object;
Get the current slice indices for latitude, longitude, and elevation.
Returns
object
An object containing the current slice indices for latitude, longitude, and elevation.
elevationSliceIndex
elevationSliceIndex: number;
latSliceIndex
latSliceIndex: number;
lonSliceIndex
lonSliceIndex: number;
getTimeSeries()
getTimeSeries(
position,
selectors?,
options?): Promise<QueryResult>;
Queries all available time coordinates at one WGS84 position.
Parameters
| Parameter | Type | Description |
|---|---|---|
position | QueryPosition | [longitude, latitude] in degrees. |
selectors? | ZarrSelectors | Fixed selectors for dimensions other than time. |
options? | QueryOptions | Query cancellation and coordinate-output controls. |
Returns
Promise<QueryResult>
A result ordered by the time coordinate.
getTransect()
getTransect(
start,
end,
selectors?,
options?): Promise<TransectResult>;
Samples one selected elevation along a WGS84 line.
Parameters
| Parameter | Type | Description |
|---|---|---|
start | QueryPosition | Starting [longitude, latitude] coordinate in degrees. |
end | QueryPosition | Ending [longitude, latitude] coordinate in degrees. |
selectors? | ZarrSelectors | Dimension selectors applied to every sample. |
options? | TransectQueryOptions | Sample count, concurrency, and cancellation controls. |
Returns
Promise<TransectResult>
Positions, distances, and values along the transect.
getVerticalProfile()
getVerticalProfile(
position,
selectors?,
options?): Promise<QueryResult>;
Queries all loaded elevation coordinates at one WGS84 position.
Parameters
| Parameter | Type | Description |
|---|---|---|
position | QueryPosition | [longitude, latitude] in degrees. |
selectors? | ZarrSelectors | Fixed selectors for dimensions other than elevation. |
options? | QueryOptions | Query cancellation and coordinate-output controls. |
Returns
Promise<QueryResult>
A result ordered by elevation.
load()
load(force): Promise<void>;
Loads the Zarr dataset and initializes the cube data and metadata.
Parameters
| Parameter | Type | Default value | Description |
|---|---|---|---|
force | boolean | false | Recreate slice primitives even when their indices did not change. |
Returns
Promise<void>
A promise that resolves after metadata, coordinates, the selected subset, and its Cesium primitives have loaded.
Throws
When the custom or URL-backed store, selected array, dimensions, or data chunks cannot be read.
Remarks
Calling load again replaces the in-memory subset. Use
updateSelectors for normal runtime changes.
queryData()
queryData(
geometry,
selectors?,
options?): Promise<QueryResult>;
Queries a voxel or vertical profile from the cube subset currently held in memory. A scalar elevation selector returns one voxel; an elevation range returns a profile.
Parameters
| Parameter | Type | Description |
|---|---|---|
geometry | QueryGeometry | WGS84 point geometry in [longitude, latitude] degrees. |
selectors? | Record<string, ZarrSelectorsProps> | Optional time/elevation overrides for this query. |
options? | QueryOptions | Cancellation and coordinate-output controls. |
Returns
Promise<QueryResult>
Queried values with coordinates expressed using dataset dimension names.
Throws
If called before load, for unsupported geometries, or for selector indices outside the loaded subset.
updateSelectors()
updateSelectors(options): Promise<void>;
Updates the dimension selectors, multiscale level, and bounds.
Parameters
| Parameter | Type | Description |
|---|---|---|
options | { bounds?: BoundsProps; multiscaleLevel?: number; selectors?: { [key: string]: ZarrSelectorsProps; }; } | Partial data-selection update. Changed selectors, level, or bounds cause the current primitives to be destroyed and reloaded. |
options.bounds? | BoundsProps | - |
options.multiscaleLevel? | number | - |
options.selectors? | { [key: string]: ZarrSelectorsProps; } | - |
Returns
Promise<void>
A promise that resolves after any required reload completes.
Remarks
Bounds are validated against geographic latitude limits.
updateSlices()
updateSlices(options): void;
Updates the rendered slices based on the provided indices.
Parameters
| Parameter | Type | Description |
|---|---|---|
options | { elevationIndex?: number; elevationMode?: ElevationMode; force?: boolean; latIndex?: number; lonIndex?: number; verticalExaggeration?: number; } | Slice update options. latIndex, lonIndex, and elevationIndex are local indices within the loaded subset. verticalExaggeration and elevationMode control height placement, while force recreates unchanged primitives. |
options.elevationIndex? | number | - |
options.elevationMode? | ElevationMode | - |
options.force? | boolean | - |
options.latIndex? | number | - |
options.lonIndex? | number | - |
options.verticalExaggeration? | number | - |
Returns
void
Remarks
Has no effect until load has completed.
updateStyle()
updateStyle(options): void;
Updates cube styling and recreates the visible slices when a value changes.
Parameters
| Parameter | Type | Description |
|---|---|---|
options | { colormap?: string; opacity?: number; scale?: [number, number]; } | Partial style update: opacity, numeric color range, and/or colormap. |
options.colormap? | string | - |
options.opacity? | number | - |
options.scale? | [number, number] | - |
Returns
void
Remarks
This reuses the loaded data and does not refetch Zarr chunks.
Properties
bounds
bounds: BoundsProps;
Configuration defining the geographic bounds of the cube.
cubeDimensions
cubeDimensions: [number, number, number] | null = null;
Size of the cube in [longitude, latitude, elevation].
cubeDimensionValues
cubeDimensionValues: DimensionValues = {};
Coordinate values represented by the currently loaded cube subset.
dimensionValues
dimensionValues: DimensionValues = {};
Values of the cube’s coordinate dimensions (latitude, longitude, elevation, etc.).
elevationShape
elevationShape: number = 0;
Shape (size) of the elevation dimension.
elevationSliceIndex
elevationSliceIndex: number = -1;
Current index of the elevation slice being visualized.
id
id: string = '';
Unique identifier for the cube provider instance.
latSliceIndex
latSliceIndex: number = -1;
Current index of the latitude slice being visualized.
levelInfos
levelInfos: string[] = [];
Information about multiscale levels in the Zarr dataset.
lonSliceIndex
lonSliceIndex: number = -1;
Current index of the longitude slice being visualized.
multiscaleLevel
multiscaleLevel: number = 0;
Current multiscale level to load.
selectors
selectors: object;
User-defined selectors for slicing dimensions.
Index Signature
[key: string]: ZarrSelectorsProps