Metadata-Version: 2.4
Name: healpix-convert
Version: 2026.10.1
Summary: Convert datasets into the HEALPix-based DGGS format
Author: healpix-convert Developers
License-Expression: Apache-2.0
Project-URL: Documentation, https://grid4earth.eu/healpix-convert/
Project-URL: Repository, https://github.com/GRID4EARTH/healpix-convert
Project-URL: Issues, https://github.com/GRID4EARTH/healpix-convert/issues
Project-URL: Changelog, https://github.com/GRID4EARTH/healpix-convert/releases
Keywords: healpix
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Scientific/Engineering :: Atmospheric Science
Classifier: Topic :: Scientific/Engineering :: GIS
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: xarray>=2025.11.0
Requires-Dist: numpy>=2
Requires-Dist: healpix-geo>=0.0.11
Requires-Dist: healpix-resample>=2026.7.0
Requires-Dist: dask>=2025.2.0
Requires-Dist: distributed>=2025.2.0
Requires-Dist: pyproj>=3.7.2
Requires-Dist: affine>=2.4.0
Requires-Dist: shapely>=2.1.0
Requires-Dist: torch>=2.9.1
Requires-Dist: zarr>=3.1.3
Requires-Dist: pydantic>=2.12.5
Requires-Dist: structlog>=25.5.0
Requires-Dist: rasterix>=0.1
Requires-Dist: s3fs>=2026.1.0
Provides-Extra: cams
Requires-Dist: requests; extra == "cams"
Provides-Extra: climatedt
Requires-Dist: cfgrib; extra == "climatedt"
Requires-Dist: destinelab; extra == "climatedt"
Requires-Dist: polytope-client; extra == "climatedt"
Provides-Extra: era5
Requires-Dist: cdsapi; extra == "era5"
Requires-Dist: cfgrib; extra == "era5"
Dynamic: license-file

# healpix-convert

This package allows converting various datasets into the
[HEALPix](https://healpix.sourceforge.io/)-based DGGS format proposed by
**GRID4EARTH**.

It takes input data stored in Zarr format (one or more EOPF-compliant Zarr
datasets), then reprojects and resamples it onto a HEALPix grid, outputting a
new Zarr dataset compliant with the DGGS Zarr and CF-Healpix conventions.

**Note: this repository is currently under heavy development. API is not stable yet.**

Documentation: <https://grid4earth.eu/healpix-convert/>

## Supported data products

- ERA5
- ClimateDT
- CAMS

## Key features

- **Multiple resampling methods** — nearest, bilinear, k-nearest neighbors, PSF, cell-point
- **Multi-stage workflow** — first prepare the output dataset, then run data conversion in parallel jobs
- **Dask-native** — parallel conversion out of the box with a distributed Dask cluster
- **Cloud-ready** — read from and write to S3 object stores
- **STAC metadata** — input STAC discovery attributes are propagated and merged in the output
- **Zarr conventions** — [Zarr conventions](https://github.com/zarr-conventions) are used for structuring metadata in the output dataset

## Installation

### From PyPI

```sh
$ python -m pip install healpix-convert
```

The ERA5, CAMS and ClimateDT converters need extra packages to download and
read their input data. Install them with the matching extra:

```sh
$ python -m pip install "healpix-convert[era5]"       # cdsapi, cfgrib
$ python -m pip install "healpix-convert[cams]"       # requests
$ python -m pip install "healpix-convert[climatedt]"  # cfgrib, polytope-client, destinelab
```

healpix-convert depends on PyTorch (through healpix-resample). On x86-64 Linux,
pip installs the CUDA build of PyTorch: with its NVIDIA libraries, that is
about 3 GB to download. For a CPU-only environment, install PyTorch from its
CPU index first:

```sh
$ python -m pip install torch --index-url https://download.pytorch.org/whl/cpu
$ python -m pip install healpix-convert
```

There is no conda-forge package yet.

### From source (development)

First clone this repository:

```sh
$ git clone https://github.com/GRID4EARTH/healpix-convert
$ cd healpix-convert
```

Then install it, e.g., using pip:

```sh
$ python -m pip install .
```

Note: we recommend installing it in an isolated development environment.

If you have [pixi](https://pixi.prefix.dev) installed, you can install a
complete development environment by simply using the command below:

```sh
$ pixi install -e dev
```

## Basic usage

See the [quickstart](https://grid4earth.eu/healpix-convert/tutorials/quickstart.html)
in the documentation, and the examples in the `notebooks` folder.
