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.
Decoded numeric tiles are cached per provider so changing the colormap or scale can redraw without reading the same Zarr slice again. The default per-layer budget assumes no more than five active layers: 8 MiB on devices with up to 2 GiB, 16 MiB up to 4 GiB, 32 MiB up to 8 GiB, and 64 MiB above that. Browsers that do not expose a device-memory hint use 32 MiB.
const provider = new ZarrTileProvider({
url: 'https://example.com/data.zarr',
variable: 'temperature',
cache: { maxBytes: 16 * 1024 * 1024 }
});
console.log(provider.tileCacheStats);
provider.clearTileCache();
Caching defaults to true. Set cache: false (or cache: { enabled: false }) to disable it.
The budget is per layer, so five layers configured
with 16 MiB can retain at most 80 MiB of decoded tile data in total.
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 | - |
| TileCacheOptions | Controls the in-memory cache used to recolor tiles without reading Zarr data again. |
| TileCacheStats | Runtime counters for a provider's decoded tile cache. |
| 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 | - |
| limitStoreRequests | Wrap a Zarrita store so all reads share one request-concurrency budget. |
| 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. |