healpix-resample is a lightweight, GPU-friendly Python
package for regridding data from unstructured longitude/latitude samples onto a
HEALPix grid — one sparse linear operator, several interpolation
strategies, and a consistent API across all of them.
Under the hood, every resampler builds a sparse PyTorch operator mapping input
samples to a subset of HEALPix cells at a chosen resolution level, so the same forward/inverse operator
can be reused, batched (B, N), and run on CPU or CUDA. The package manages the HEALPix authalic
definition and the Earth ellipsoid using the WGS84 reference system.
| Resampler | Strategy | Good for |
|---|---|---|
NearestResampler |
Single nearest sample per cell | Fast, simple, exact point indexing |
BilinearResampler |
4 nearest samples, inverse-distance weights | Smoother than nearest, cheap |
GridBilinearResampler |
Bilinear surface through the 4 grid nodes around each cell centre (regular lon/lat grids, 1-D axes) | Exact for linear fields, no neighbour search, fast at the input resolution |
BicubicResampler |
16 nearest samples, Keys' cubic convolution kernel | Sharper on fields with curvature, still non-iterative |
PSFResampler |
Gaussian PSF kernel + damped least-squares (Conjugate Gradient) | Best reconstruction quality, dense or irregular data |
ConservativeResampler |
Direct binning, area-weighted sum | Exact flux/mass conservation |
GroupByResampler |
Direct binning, configurable reduction (mean, sum, prod, amax, amin) |
Aggregating many samples per cell |
CellPointResampler |
Level-29 "cell-point" encoding | Exact point indexing, no interpolation |
BilinearResampler, BicubicResampler, and PSFResampler also support an optional area= +
conservative=True mode that redistributes each sample's value across its cell footprint instead of
just interpolating, so the global total is preserved exactly — combining smooth interpolation with
ConservativeResampler's exact-conservation guarantee. PSFResampler additionally supports
out_cell_ids= to restrict output to a specific cell subset, and resample(..., clip=(lo, hi)) to
impose hard bounds inside the fit (e.g. clip=(0.0, None) for a non-negative field), which removes the
negative values and overshoots the PSF deconvolution can produce at sharp edges.
healpix_resample.subset_for_parent_cell lets you process one coarse HEALPix region at a time for
datasets too large to load in full.
Every resampler handles NaN-valued samples consistently (excluded from the computation rather than propagated) and accepts both NumPy arrays and PyTorch tensors, returning whichever type you passed in.
pip install healpix-resampleThe notebooks also plot with healpix-plot, which comes with the notebooks extra:
pip install "healpix-resample[notebooks]"git clone https://github.com/GRID4EARTH/healpix-resample.git
cd healpix-resample
pip install -e .Or, using pixi (the environment this package is developed and tested in):
git clone https://github.com/GRID4EARTH/healpix-resample.git
cd healpix-resample
pixi install- Python 3.10+
- PyTorch (CPU or CUDA)
- NumPy
healpix-geo
import healpix_resample
print(healpix_resample.__file__)from healpix_resample import BilinearResampler
op = BilinearResampler(lon_deg=lon, lat_deg=lat, level=level, device="cuda")
result = op.resample(values)
healpix_values = result.cell_data # (K,) or (B, K)
healpix_cells = result.cell_ids # (K,) HEALPix cell ids, same order as cell_dataEvery resampler follows this same resample(val) -> ResampleResults(cell_data, cell_ids) pattern; swap
BilinearResampler for any of the other classes above to change interpolation strategy without changing
the rest of your code. See the full documentation —
in particular the real-data resampler tutorial, which downloads
one small frozen Zenodo archive and runs every resampler on the same Sentinel-2 scene. The compact
4resamplers tutorial remains available as a synthetic API reference.
Together with the user guide, these cover conservative mode, batched inputs, out_cell_ids, and
large-scale parent-cell processing.
Full documentation, including a user guide per resampler, tutorials, and the API reference, is available at grid4earth.eu/healpix-resample.
This project uses pixi to manage environments.
pixi run tests # run the test suite
pixi run -e docs build-docs # build the documentation locally (docs/_build)- Earth observation data remapping (e.g. Sentinel products)
- Oceanographic or atmospheric gridding
- Astronomical sky projections
- Large-scale geospatial data harmonization
Apache License 2.0 — see LICENSE.