healpix-resample

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.

Resamplers at a glance

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.

Installation

From PyPI

pip install healpix-resample

From source (editable, for development)

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

Requirements

• Python 3.10+
• PyTorch (CPU or CUDA)
• NumPy
• healpix-geo

Verifying the installation

import healpix_resample
print(healpix_resample.__file__)

Quickstart

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_data

Every 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.

Documentation

Full documentation, including a user guide per resampler, tutorials, and the API reference, is available at grid4earth.eu/healpix-resample.

Development

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)

Target applications

• Earth observation data remapping (e.g. Sentinel products)
• Oceanographic or atmospheric gridding
• Astronomical sky projections
• Large-scale geospatial data harmonization

License

Apache License 2.0 — see LICENSE.