Installation

Requirements

• Python ≥ 3.10

• PyTorch (CPU or GPU)

• healpix-geo — all HEALPix geometry comes from here

• pyproj — ellipsoidal distances

Those four are installed for you by any of the commands below.

Install

pip install git+https://github.com/GRID4EARTH/healpix-analyse.git

From source, for development:

git clone git@github.com:GRID4EARTH/healpix-analyse.git
cd healpix-analyse
pip install -e .

Or with Pixi, which pins a full reproducible environment:

pixi install
pixi run python -c "import healpix_analyse; print('ok')"

Extras

Nothing below is needed for the core operators; install an extra only for what you actually want to run.

Extra	pip install -e ".[…]"	What it is for
dino	dino	DINOv3 embeddings via torch-hub (GetDINOV3SAT — DINOv3 embeddings of HEALPix data)
dino-hf	dino-hf	the same, loading the weights from Hugging Face instead
examples	examples	the Sentinel-2 example scripts: xarray, zarr, obstore, UMAP, scikit-learn, matplotlib, cartopy
notebooks	notebooks	JupyterLab, to run the notebooks
docs	docs	Sphinx, to build this documentation
test	test	pytest

Two packages are deliberately not dependencies:

• healpy is not used by healpix-analyse. It appears in this documentation only where an example cross-checks a result against it, and in a few legacy pixel-query helpers; the geometry itself is healpix-geo’s.

• healpix-plot is not on PyPI, so it cannot be listed as a dependency. The pixi environments pull it from git; otherwise install it yourself:

  pip install git+https://github.com/GRID4EARTH/healpix-plot
  

The DINOv3 weights are a separate matter: they are gated by Meta and this package never downloads or redistributes them. See GetDINOV3SAT — DINOv3 embeddings of HEALPix data.

Check that it worked

import numpy as np
from healpix_geo import nested
from healpix_analyse.down import HealPixDown

depth = 4
ids = np.arange(12 * 4 ** depth, dtype=np.int64)
print(len(ids), "cells at level", depth)
print(nested.healpix_to_lonlat(ids.astype(np.uint64), depth)[0][:3], "…")