User Guide#
Everything you need to understand how healpix-resample works and how to configure it.
Output format#
All resamplers return a ResampleResults dataclass:
Field |
Shape |
Description |
|---|---|---|
|
|
Resampled values on HEALPix cells |
|
|
HEALPix cell indices (nested scheme) |
|
|
CG convergence history (PSFResampler only) |
|
scalar |
Number of CG iterations (PSFResampler only) |
Key parameters (all resamplers)#
Parameter |
Default |
Description |
|---|---|---|
|
— |
HEALPix resolution. |
|
|
Minimum weight sum to keep a cell |
|
auto |
Gaussian scale in metres (defaults to pixel size) |
|
|
Restrict output to a specific subset of cells |
|
|
Geodetic ellipsoid |
|
auto |
|
|
|
PyTorch dtype. Use |
When no requested cell has support#
With out_cell_ids, it can happen that none of the requested cells passes threshold, typically
for a chunk at the edge of the input whose nearby samples all lie just outside it. This is not an
error: the KNN-based resamplers (BilinearResampler, BicubicResampler, PSFResampler) are built
with K = 0 and resample() returns an empty result, cell_ids of size 0 and cell_data of shape
(B, 0), so a chunked caller simply keeps its fill value for that chunk. NearestResampler instead
fills every requested cell with its nearest sample (its out_cell_ids fallback), unless
max_distance_m is set: then the cells whose nearest sample is farther than that are left out.
Sparse samples and the neighbour search#
Each sample looks for its Npt nearest kept cells in HEALPix rings growing from ring_search_init up
to ring_search_max. When the samples are much sparser than the cells (coarse input to a fine
level), a sample may not find Npt cells within ring_search_max rings: it then keeps the cells it
found, fewer than Npt. If no sample reaches any kept cell at all, the constructor raises a
RuntimeError asking for a larger ring_search_max or a coarser level, instead of returning an
empty operator.
Longitudes and latitudes can be float32 or float64: the geometry is always computed in float64.
Without out_cell_ids, every sample supports its own cell, so an empty result means the
configuration is wrong: the constructor raises RuntimeError("No HEALPix cell passed the threshold ..."); lower threshold or widen the neighbourhood rings.
GPU usage#
Pass device="cuda" to any resampler to run on GPU. The operators M and MT stay in GPU memory between calls to resample(), so the cost is paid only once at construction time.
from healpix_resample import BilinearResampler
import torch
nr = BilinearResampler(
lon_deg=lon, lat_deg=lat,
level=13,
device="cuda",
dtype=torch.float32,
)
result = nr.resample(val) # runs on GPU
What next#
4-point weighted interpolation.
Fastest option. One cell per sample, no interpolation.
16-point radial cubic-convolution interpolation. Smoother than bilinear, no CG solve.
Delaunay triangulation + Clough-Tocher C1 cubic. Genuine bivariate interpolant, no extrapolation outside the sample convex hull.
Gaussian kernel + conjugate gradient. Best quality.
First-order overlap-area conservative remapping from a lat/lon grid (the ESMF/xESMF formulation), and how it differs from the other two conservative modes.
Process one coarse HEALPix cell at a time for large-scale/global datasets.
Resample HEALPix cell data onto a UTM raster through each resampler’s invert().
BitmaskResampler (independent flags) and CategoricalResampler (mutually-exclusive classes, argmax).