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

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

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.0
File Size Uploaded Provenance Actions
healpix_resample-2026.11.0.tar.gz 67.9 MB With provenance Details for healpix_resample-2026.11.0.tar.gz

Built distribution (wheel)

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

Total release size: 68.0 MB

Release files / healpix_resample-2026.11.0.tar.gz

Download URL healpix_resample-2026.11.0.tar.gz
Size 67.9 MB
Tags Source
SHA-256 checksum
How to use checksums
8f2292c853aabf49bf4ab7ab5625e1e1e4e563ec44581b7685c18a810bae820a
BLAKE2b-256 checksum
How to use checksums
ef7152dffd1fa3b2cf727596dba76bad70aea57e4229095880a5935d8388b639
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 1, 2026.

Transparency log

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

Download URL healpix_resample-2026.11.0-py3-none-any.whl
Size 120.7 kB
Tags Python 3
SHA-256 checksum
How to use checksums
0f8bdd173a6cc7c5f97fb7e8636760598f49573b5775b58b1015c1d0658dee4f
BLAKE2b-256 checksum
How to use checksums
aa0528d7e9556805a353f1c83db1ad70ebad4a28ffd5d22bd5c30ea25f58fc95
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 1, 2026.

Transparency log

Security for healpix-resample 2026.11.0

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.0.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 1, 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