# chronozarr

> An open Zarr v3 layout for raster time series.

## Docs

- [chronozarr v0.2](/specification): **Status:** Draft
**Date:** 2026-09-30
**Spec version string:** `0.2.0`
**Supersedes:** chronozarr v0.1 (`0.1.0`); `CHRONOFABRIC.md` (ChronoFabric v1: Zarr v2, one array per cell, `manifest.json`)
- [Examples](/examples): The [live chronozarr demo](https://chronozarr.org/demo/) explores a Sentinel-2 time series
of the Ucayali River, Peru. The homepage previews are generated from that store's
level-3 RGB bands. They use a fixed display stretch and are illustrative images,
not level-0 measurements.
- [Getting started](/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.
- [How it works](/how-it-works): chronozarr is a layout convention plus readers. Every object is an ordinary Zarr
v3 object; the convention specifies a time axis, a multiscale pyramid, coordinates,
and optional temporal encoding.
- [Integrate](/integrate): Choose the interface that fits your application.
- [Publish a store](/publishing): A store is a directory of static objects. Upload it to an HTTPS host, keep its
relative paths intact, then share the root URL. No application server is required.
- [chronozarr](/reference/javascript): Browser and Node reader for [chronozarr](https://github.com/chronozarr/chronozarr) stores, plus a MapLibre GL JS custom layer that draws one.
- [chronozarr on MapLibre](/reference/maplibre): `ChronozarrLayer` draws a chronozarr store on a MapLibre GL JS map as a custom layer. It opens the store with
`js/chronozarr/decoder.js`, picks the pyramid level from the map zoom, uploads the raw chunks of the visible cells
as integer (or float) textures, and reconstructs star-delta timesteps and runs the product band math in the
fragment shader. Each cell is a small mesh whose vertices were projected from the store's CRS to Web Mercator, so
the raster lands on the basemap with no resampling step. No dependencies: MapLibre is the host page's.
- [Command line](/reference/cli): Install `chronozarr`, then run `chronozarr COMMAND --help` for all options.
- [Python and xarray](/reference/python): `da` has dimensions `(time, band, y, x)`, supported stored dtype, and projected
pixel-centre coordinates. The output must be new or empty. Encoding defaults to
`auto`; sharding defaults off. Use `encoding="none"` for direct ordinary Zarr reads.
- [Appending: what one new date costs](/guides/append): `chronozarr append STORE INPUT` adds timesteps to the end of a store in place (spec section 14, publishing in [hosting.md](/guides/hosting) section 7). Before it existed the only way to add a date was a re-encode under a new prefix: rewrite and re-upload every object. This page measures the append against that and against the layout choices that decide its cost.
- [Measured comparisons: zarr-layer, and one COG per date](/guides/comparisons): Two comparisons of a chronozarr store, measured on 2026-10-01 on one machine (Apple M3 Max, macOS, Node 24.16.0, Chromium 153 through Playwright 1.63.0 with the Metal GPU backend). All code, raw results and a lockfile are in `bench/`; the exact commands are in the last section.
- [Embedding the viewer](/guides/embedding): `https://chronozarr.org/demo/?store=<url>` opens any chronozarr store. Add `embed=1` and the same page is a compact viewer for an `<iframe>`, with a small `postMessage` contract so the host page can move it in time, read what the user clicks, and follow the camera. There is nothing to install in the host page: it talks to the iframe with `contentWindow.postMessage` and listens for `message` events.
- [chronozarr compared with other formats](/guides/format-comparison): As of 2026-09-30. Statements about other projects come from their documentation and source and can go stale; check the project if a decision depends on one. Statements about chronozarr are measured or read from [spec/CHRONOZARR.md](/specification) and the tests in this repository.
- [Hosting a chronozarr store](/guides/hosting): A chronozarr store is a directory of static files. Any host that returns a file by path, answers byte-range requests and sends CORS headers serves it. There is nothing to run. This page turns the requirements in [spec/CHRONOZARR.md](/specification) section 9 into a checklist, an upload procedure, and recipes for four hosts: S3 with CloudFront, Cloudflare R2, Google Cloud Storage, and Source Cooperative.
- [PNG frames to a store](/guides/png-frames): A sequence of georeferenced PNGs, one per date, becomes a scrubbable chronozarr store with
`chronozarr convert`. There is no GeoTIFF step. The frames are what exporters hand over: Earth Engine
thumbnails, QGIS "Save as image" (with its world file option), matplotlib figures, drone and
orthomosaic pipelines. `convert` reads them with GDAL, so everything it does for COGs applies:
manifest, time order, `--dry-run`, `--resume`, validity rules, the pyramid.
- [User zero: monthly water-mask stacks](/guides/water-masks): Two derived chronozarr stores, built from the Sentinel-2 monthly mosaics that already sit in
`data/mosaics/`, to see what a fluvial geomorphologist can do with the viewer: scrub months, click a
pixel, chart it. Nothing was downloaded.