Getting started

This example builds a small synthetic time series, writes it, and checks an exact level-0 roundtrip. You do not need a bucket or satellite imagery to try it.

Install

Python 3.11 or later:

uv pip install chronozarr

Create a raster time series

Save this as quickstart.py. The coordinates describe 10-metre pixels in UTM zone 31N. The data is synthetic; it demonstrates the layout rather than a measured phenomenon.

from pathlib import Path
import tempfile
 
import numpy as np
import xarray as xr
import chronozarr
 
values = np.arange(3 * 1 * 64 * 64, dtype=np.uint16).reshape(3, 1, 64, 64)
da = xr.DataArray(
    values,
    dims=("time", "band", "y", "x"),
    coords={
        "time": np.array(["2024-01-01", "2024-02-01", "2024-03-01"], dtype="datetime64[ns]"),
        "band": ["example"],
        "y": 5000000 - (np.arange(64) + 0.5) * 10,
        "x": 500000 + (np.arange(64) + 0.5) * 10,
    },
)
 
# A new output directory each run; encode does not overwrite a populated store.
path = Path(tempfile.mkdtemp(prefix="chronozarr-quickstart-")) / "my_store"
chronozarr.encode(da, path, crs="EPSG:32631", encoding="none", nodata=None)
store = chronozarr.open_store(path)
np.testing.assert_array_equal(store.read(t=1), values[1])
print(path)
print(store.to_xarray(lod=0))

uv run python quickstart.py
chronozarr validate /path/printed/by/the/script/my_store
chronozarr info /path/printed/by/the/script/my_store

Here encoding="none" makes every timestep readable by ordinary compatible Zarr v3 clients. The normal writer default, auto, samples the data and enables star-delta only where it saves enough compressed bytes. nodata=None keeps zero as a valid value.

Read with xarray

# Reconstruct temporal encoding and return physical values by default.
ds = xr.open_dataset(path, engine="chronozarr")
 
# This example has encoding none, so a plain Zarr reader also sees true values.
plain = xr.open_zarr(path, group="0", zarr_format=3, chunks=None)

store.to_xarray() loads the requested level into memory. The xarray backend is lazy; install chronozarr[dask] if you want dask chunks. See Python and xarray.

Convert an existing stack

chronozarr encode scenes.nc my_store
chronozarr convert manifest.csv my_store

A COG manifest has uri,datetime columns and optional bands. GeoTIFF input needs chronozarr[geo]; NetCDF input may need chronozarr[netcdf]. For PNG input, follow the georeferencing guide.

Next, publish the store, or open it in a notebook.