Metadata-Version: 2.5
Name: chronozarr
Version: 0.4.1
Summary: Turn a raster time series into static files that a browser plays and Python reads with the stored values
Project-URL: Homepage, https://chronozarr.org
Project-URL: Documentation, https://chronozarr.org/quickstart
Project-URL: Specification, https://chronozarr.org/specification
Project-URL: Repository, https://github.com/chronozarr/chronozarr
Project-URL: Issues, https://github.com/chronozarr/chronozarr/issues
Author: James H. Gearon
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: cloud-native,earth observation,raster,remote sensing,sentinel-2,time series,xarray,zarr
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: GIS
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Requires-Python: >=3.11
Requires-Dist: click>=8.1
Requires-Dist: numcodecs>=0.14
Requires-Dist: numpy>=1.26
Requires-Dist: xarray>=2024.1
Requires-Dist: zarr>=3.1
Provides-Extra: dask
Requires-Dist: dask>=2024.1; extra == 'dask'
Provides-Extra: geemap
Requires-Dist: geemap>=0.37.2; extra == 'geemap'
Requires-Dist: leafmap>=0.63.1; extra == 'geemap'
Provides-Extra: geo
Requires-Dist: rasterio>=1.3; extra == 'geo'
Provides-Extra: ingest
Requires-Dist: planetary-computer>=1.0; extra == 'ingest'
Requires-Dist: pystac-client>=0.8; extra == 'ingest'
Requires-Dist: pystac>=1.10; extra == 'ingest'
Requires-Dist: pyyaml>=6.0; extra == 'ingest'
Requires-Dist: rasterio>=1.3; extra == 'ingest'
Provides-Extra: leafmap
Requires-Dist: leafmap>=0.63.1; extra == 'leafmap'
Provides-Extra: netcdf
Requires-Dist: h5netcdf>=1.3; extra == 'netcdf'
Requires-Dist: h5py>=3.10; extra == 'netcdf'
Provides-Extra: notebook
Requires-Dist: anywidget>=0.9; extra == 'notebook'
Requires-Dist: ipython>=8; extra == 'notebook'
Provides-Extra: publish
Requires-Dist: boto3>=1.34; extra == 'publish'
Provides-Extra: publish-azure
Requires-Dist: azure-identity>=1.15; extra == 'publish-azure'
Requires-Dist: azure-storage-blob>=12.19; extra == 'publish-azure'
Provides-Extra: publish-gcs
Requires-Dist: google-cloud-storage>=2.16; extra == 'publish-gcs'
Provides-Extra: s3
Requires-Dist: boto3>=1.34; extra == 's3'
Description-Content-Type: text/markdown

# chronozarr

[![CI](https://github.com/chronozarr/chronozarr/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/chronozarr/chronozarr/actions/workflows/ci.yml)
[![PyPI](https://img.shields.io/pypi/v/chronozarr)](https://pypi.org/project/chronozarr/)
[![npm](https://img.shields.io/npm/v/chronozarr)](https://www.npmjs.com/package/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](https://chronozarr.org/demo/): 117 monthly Sentinel-2 composites of the Ucayali River in Peru, read directly from a storage bucket. Documentation: [chronozarr.org](https://chronozarr.org).

## Quickstart

Install [uv](https://docs.astral.sh/uv/getting-started/installation/), then the `chronozarr` command:

```bash
uv tool install --python 3.13 'chronozarr[geo]==0.4.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:

```bash
python -m pip install 'chronozarr[geo]==0.4.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:

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

Then convert the folder, look at it, and share it:

```bash
chronozarr convert sample my_store --dry-run
chronozarr convert sample my_store
chronozarr preview my_store
chronozarr share my_store
```

The dry run checks every file and writes nothing. `convert` writes the store. `preview` opens it in your browser. `share` prints a temporary link that a colleague opens in a browser; it needs [`cloudflared`](https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/downloads/) and works only while the command runs.

The [full quickstart](https://chronozarr.org/quickstart) has a sample dataset, the expected output of each command and the pip route.

## Share a store

| Link | Command | Lasts | Needs |
|---|---|---|---|
| Temporary | `chronozarr share my_store` | While the command runs | `cloudflared`, your computer on and online |
| Permanent | `chronozarr publish my_store --destination s3://BUCKET/PREFIX` | As long as you keep the files | Cloud storage that you control: S3, R2, Google Cloud Storage or Azure |

The recipient needs only a web browser. chronozarr.org serves the viewer page and stores no data. See [Share a temporary link](https://chronozarr.org/guides/share) and [Publish a permanent link](https://chronozarr.org/guides/publish).

## Read the values

```python
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. See [Analyze a store in Python](https://chronozarr.org/guides/analyze).

## JavaScript

```bash
npm install chronozarr@0.4.1
```

The npm package has a DOM-free reader, a MapLibre layer, a GeoLibre plugin and the full viewer for self-hosting. See the [JavaScript reader](https://chronozarr.org/reference/javascript).

## Versions

The Python and npm packages are 0.4.1. The store format specification is v0.3.0, a draft. A package upgrade does not change existing v0.3 stores. To use a v0.2 store, convert it with `chronozarr convert OLD_STORE NEW_STORE`. [Release notes for 0.4.1](https://github.com/chronozarr/chronozarr/blob/main/docs/release-0.4.1.md).

## Documentation

| Topic | Page |
|---|---|
| What chronozarr is, and how it compares | [What is chronozarr?](https://chronozarr.org/what-is-chronozarr) |
| Every input type | [Convert your data](https://chronozarr.org/guides/convert) |
| Sentinel-2 for your own area and dates (a repository checkout) | [Sentinel-2 for your area](https://chronozarr.org/guides/sentinel-2) |
| SWOT, NISAR and model output | [Examples](https://chronozarr.org/guides/examples) |
| Every command | [Command line](https://chronozarr.org/reference/cli) |
| Python functions | [Python API](https://chronozarr.org/reference/python) |
| Format rules | [Specification](https://chronozarr.org/specification) |
| Measured speed, memory and correctness | [Performance and evidence](https://chronozarr.org/performance) |
| Problems and fixes | [Troubleshooting](https://chronozarr.org/troubleshooting) |

The pages are written in [`docs/`](https://github.com/chronozarr/chronozarr/tree/main/docs) and published to chronozarr.org. To contribute, see [CONTRIBUTING.md](https://github.com/chronozarr/chronozarr/blob/main/CONTRIBUTING.md).

## License

See [LICENSE](https://github.com/chronozarr/chronozarr/blob/main/LICENSE).
