Skip to main content

healpix-resample

PyPI Docs License: Apache 2.0

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

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.

Installation

From PyPI

pip install healpix-resample

The notebooks also plot with healpix-plot, which comes with the notebooks extra:

pip install "healpix-resample[notebooks]"

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

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.

Metadata

Release files for healpix-resample 2026.11.2

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for healpix-resample 2026.11.2
File Size Uploaded Provenance Actions
healpix_resample-2026.11.2.tar.gz 68.2 MB With provenance Details for healpix_resample-2026.11.2.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for healpix-resample 2026.11.2
File Interpreter ABI Platform Actions
healpix_resample-2026.11.2-py3-none-any.whl Python 3 none any Details for healpix_resample-2026.11.2-py3-none-any.whl

Total release size: 68.3 MB

Release files / healpix_resample-2026.11.2.tar.gz

Download URL healpix_resample-2026.11.2.tar.gz
Size 68.2 MB
Tags Source
SHA-256 checksum
How to use checksums
f68f2643bd99bbc28ff74a50c551f735b87653d8cf93ad712e6449e04d8bc3e7
BLAKE2b-256 checksum
How to use checksums
9489e10c36af89bf82c2fc2de0430cb66fe29f7e05cbaf9932cd490163973037
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 4, 2026.

Transparency log

Release files / healpix_resample-2026.11.2-py3-none-any.whl

Download URL healpix_resample-2026.11.2-py3-none-any.whl
Size 127.6 kB
Tags Python 3
SHA-256 checksum
How to use checksums
8b75a622082c11c57734d78216c69d255bf9eb62977dcad07750c44076e22378
BLAKE2b-256 checksum
How to use checksums
887f44885e17fbdd41baf0b4199be778bd15bca68b691676cc28bbf0a9433e5a
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 4, 2026.

Transparency log

Security for healpix-resample 2026.11.2

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for healpix_resample-2026.11.2.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 4, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page