chronozarr

chronozarr turns a georeferenced raster time series into an interactive dataset that anyone can open with a link. In a web browser, the series plays or scrubs like a video. You zoom and pan the map, and a click on a pixel shows its values over time. In Python, the same files return the exact numbers you stored. No tile server runs anywhere.

Live demo: 117 monthly Sentinel-2 composites of the Ucayali River in Peru, read directly from a storage bucket. Documentation: chronozarr.org.

Quickstart

This quickstart targets Python and npm 0.5.1. The release notes cover the new conversion options, custom coordinate systems, viewer bundle and compatibility with existing stores.

Install uv, then the chronozarr command:

uv tool install --python 3.13 'chronozarr[geo]==0.5.1'

chronozarr supports Python 3.11 and newer. --python 3.13 makes uv use 3.13 even when an older Python comes first on your computer. With pip, in an environment with Python 3.11 or newer:

python -m pip install 'chronozarr[geo]==0.5.1'

Use a folder with one GeoTIFF per date, with the date in each file name, such as ndvi_2024-01.tif. All files share one grid. To try it without your own files, export twelve months of the public demo as GeoTIFFs:

chronozarr export-cog https://data.chronozarr.org/ucayali_santa_maria_v03 sample --level 2 --times 2024-01..2024-12

Then convert the folder and share it:

chronozarr convert sample my_store --dry-run
chronozarr convert sample my_store
chronozarr share my_store      # a temporary public link that any computer can open
chronozarr preview my_store    # or: private, opens on this computer only

The dry run checks every file and writes nothing. convert writes the store. share prints a temporary link that you or a colleague open in a browser. It needs cloudflared, works only while the command runs and your computer is on, and anyone with the link can read the store. preview opens the store in your browser through a local server. Its link opens only on this computer.

The full quickstart has a sample dataset, the expected output of each command and the pip route.

Share a store

The recipient needs only a web browser. chronozarr.org serves the viewer page and stores no data. See Share a temporary link and Publish a permanent link.

Read the values

import xarray as xr

ds = xr.open_dataset("my_store", engine="chronozarr")

A store is a Zarr v3 group, so xarray, zarr-python and GDAL 3.13 also read it without chronozarr. They return the stored values: plain xarray and CarbonPlan's zarr-layer 0.11.0 do not apply its band scale and offset or its mask (GeoZarr review). See Analyze a store in Python.

JavaScript

npm install chronozarr@0.5.1

The npm package has a DOM-free reader, a MapLibre layer, a GeoLibre plugin and the production viewer for self-hosting. See the JavaScript reader.

Versions

Python and npm package 0.5.1 read both draft store formats: v0.3.0 for CRSs with an EPSG code and v0.4.0 for other CRSs. Package versions and store specification versions are independent. Existing v0.3 stores need no conversion. Readers from package 0.4.1 and earlier cannot open v0.4 stores; upgrade the reader to 0.5.1. To use a v0.2 store, convert it with chronozarr convert OLD_STORE NEW_STORE. See the 0.5.1 release notes.

Documentation

The pages are written in docs/ for chronozarr.org. Use the source installation guide when developing from a checkout. Package publication and site deployment are separate steps. To contribute, see CONTRIBUTING.md.

License

See LICENSE.