zarr-maps-tiling
Framework-independent utilities for loading, slicing, styling, and rendering tiled Zarr data.
The package contains the shared data pipeline used by zarr-maps-leaflet, zarr-maps-ol, and zarr-cesium. It does not
depend on Cesium, Leaflet, or OpenLayers.
import { initZarrDataset, calculateSliceArgs } from 'zarr-maps-tiling';
import { colormapBuilder } from 'zarr-maps-colormap';
ZarrTileProvider accepts either a URL or a custom Zarrita Readable store. This supports
Icechunk and other storage backends without coupling the tiling package to a specific client:
const store = await IcechunkStore.open(url, { branch: 'main', formatVersion: 'v1' });
const provider = new ZarrTileProvider({ store, variable: 'temperature' });
Private HTTP stores can use requestOverrides for static fetch options or transformRequest
for per-object headers, credentials, proxies, and signed URLs. onAuthError is called once for
HTTP 400/401 responses so applications can refresh expired credentials.
From the zarr-maps repository root, build all packages with:
npm run build
Classes
| Class | Description |
|---|---|
| ZarrTileProvider | Provides Zarr dataset access and rendering capabilities for web-map layers. |
Interfaces
| Interface | Description |
|---|---|
| BoundsProps | Geographic bounding box definition (degrees). |
| DataSliceProps | Describes a slice of a multidimensional array. |
| DimensionNamesProps | Describes the mapping between dataset dimensions and their standardized names. |
| DimensionValues | Mapping of dimension names to their corresponding coordinate arrays. |
| DimIndicesProps | Maps dimension keys to their indices and associated coordinate arrays. |
| FullTransectResult | A distance-by-elevation transect. Values are indexed [elevation][position]. |
| QueryBackend | Minimal interface required by the framework-neutral convenience queries. |
| QueryMultiPolygonGeometry | GeoJSON multipolygon geometry, reserved for region-query support. |
| QueryOptions | Controls a shared Zarr data query. |
| QueryPointGeometry | GeoJSON point geometry expressed as WGS84 longitude and latitude. |
| QueryPolygonGeometry | GeoJSON polygon geometry, reserved for region-query support. |
| QueryResult | Values and coordinates returned from a shared Zarr query. |
| RequestOverrides | Serializable static fetch options suitable for application state and FetchStore. |
| RequestParameters | - |
| TransectQueryOptions | Sampling controls for one-level and full-depth transects. |
| TransectResult | A one-level transect. Values preserve no-data gaps as null. |
| XYLimits | Describes the XY coordinate boundaries of a dataset. |
| XYLimitsProps | Alias of XYLimits with explicit type name for Zarr coordinate bounds. |
| ZarrLevelMetadata | Metadata for a single multiscale level in a Zarr dataset. |
| ZarrSelectors | Describes a selector for a Zarr dataset dimension. |
| ZarrSelectorsProps | - |
| ZarrTileOptions | Framework-neutral options for the shared 2D Zarr tile renderer. |
Type Aliases
| Type Alias | Description |
|---|---|
| BrowserName | Browser names used for WebGL compatibility handling. |
| CalendarDate | Represents a date in a calendar system. |
| CFCalendar | Supported CF calendar types. |
| CRS | Supported Coordinate Reference Systems. |
| MultiscaleFormat | Supported conventions for discovering multiscale Zarr levels. |
| OnAuthError | - |
| QueryGeometry | Geometry accepted by the shared query API. Only points are implemented currently. |
| QueryPosition | WGS84 longitude/latitude coordinate used by convenience query APIs. |
| SliceArgs | Represents a multidimensional slice argument for Zarr array indexing. |
| TransformRequest | - |
Functions
| Function | Description |
|---|---|
| calculateElevationSlice | Determines the index range of the elevation axis to load from a Zarr cube. |
| calculateHeightMeters | Converts elevation index to Cesium height (meters), applying vertical exaggeration and optional below-sea-level offset. |
| calculateNearestIndex | Finds the index of the value in values nearest to target. |
| calculateSliceArgs | Constructs Zarr slice arguments for extracting a subregion of a multidimensional array. |
| calculateSliceArgsRequestImage | Constructs Zarr slice arguments for extracting a subregion of a multidimensional array. |
| calculateXYFromBounds | Converts geographic bounds (lat/lon) to pixel-space indices for slicing Zarr arrays. Supports both EPSG:4326 and EPSG:3857 projections. |
| createColorRampTexture | Creates a flexible 1D color-ramp texture supporting either normalized (0–1) or integer (0–255) color definitions. |
| createProgram | Creates and links a WebGL program using the specified vertex and fragment shaders. |
| createShader | Creates and compiles a WebGL shader from source code. |
| decodeCFTime | Decodes CF-compliant time coordinate values into ISO date strings. |
| detectBrowser | Detects the current browser based on the user agent string. |
| detectCRS | Detects the coordinate reference system (CRS) of a Zarr dataset based on metadata or coordinate range. Defaults to EPSG:4326 (WGS84) if uncertain. |
| extractNoDataMetadata | Extracts no-data related metadata from a Zarr array's attributes. |
| getCubeDimensions | Computes cube dimension ordering and strides based on dimension indices. Useful for reshaping 3D Zarr arrays into Cesium-renderable layouts. |
| getFullTransect | Queries all elevation levels along a line between two WGS84 positions. |
| getTimeSeries | Queries every time coordinate at one point and the selected elevation. |
| getTransect | Queries one scalar level along a line between two WGS84 positions. |
| getVerticalProfile | Queries every elevation coordinate at one point and the selected time. |
| getXYLimits | Retrieve the geographic coordinate limits (min/max latitude/longitude) for a Zarr array. |
| getZarrData | Reads an array with the same Zarrita module instance that opened it. Zarrita 0.7 keeps array decoding context module-local, so consumers must not call a separately resolved copy of zarrita.get on arrays returned here. |
| identifyDimensionIndices | Identify the indices of common dimensions (lat, lon, time, elevation) in a Zarr array, optionally using CF-compliant standard names or custom dimension mappings. |
| initZarrDataset | Opens a Zarr variable (single-scale or multiscale pyramid) and prepares its metadata. |
| latDegToMercY | - |
| loadDimensionValues | Loads the coordinate values for a specific dimension. |
| lonDegToMercX | - |
| openLevelArray | Opens and caches a specific multiscale level array. Keeps a small LRU-style cache of up to three levels. |
| parseCFUnits | Parses a CF-compliant units string into its components. |
| resolveNoDataRange | Resolves the no-data value range for masking dataset values. |
| sampleTransectPositions | Builds evenly spaced WGS84 samples along the shortest longitude path. |
| updateImgData | Updates an ImageData object with a new pixel color derived from a numeric value and a ColorScaleProps colormap. |