Quickstart#

All resamplers share the same two-step API: build once, resample many times.

Setup#

import numpy as np
from healpix_resample import BilinearResampler

1. Your data: N points with lon/lat coordinates and values#

# 1. Your data: N points with lon/lat coordinates and values
lon = np.random.uniform(-180, 180, 10000)
lat = np.random.uniform(-90,  90,  10000)
val = np.sin(np.deg2rad(lon)) * np.cos(np.deg2rad(lat))

2. Build the resampler (done once, reusable)#

nr = BilinearResampler(lon_deg=lon, lat_deg=lat, level=8)

/home/runner/work/healpix-resample/healpix-resample/healpix_resample/bilinear.py:74: UserWarning: Sparse CSR tensor support is in beta state. If you miss a functionality in the sparse tensor support, please submit a feature request to https://github.com/pytorch/pytorch/issues. (Triggered internally at /home/conda/feedstock_root/build_artifacts/libtorch_1772252348570/work/aten/src/ATen/SparseCsrTensorImpl.cpp:49.)
  self.M  = M_coo.to_sparse_csr()

3. Resample#

result = nr.resample(val)

print("HEALPix values shape:", result.cell_data.shape)   # (K,)
print("HEALPix cell IDs shape:", result.cell_ids.shape)  # (K,)

HEALPix values shape: (35005,)
HEALPix cell IDs shape: (35005,)

result.cell_data contains the values projected onto the HEALPix grid. result.cell_ids contains the corresponding HEALPix cell indices (nested scheme).

4. Project back to original points (optional)#

invert() reprojects the HEALPix field back to the original sample locations. This is useful to check reconstruction quality.

val_reconstructed = nr.invert(result.cell_data)

# Mean squared reconstruction error
mse = np.mean((val_reconstructed - val) ** 2)
print(f"Reconstruction MSE: {mse:.2e}")

Reconstruction MSE: 7.21e-02

Batch mode#

Pass a (B, N) array to process multiple fields at once (e.g. B time steps) without rebuilding the operator:

# 10 time steps, same spatial points
val_batch = np.stack([val * (1 + 0.1 * i) for i in range(10)])  # (10, N)

result_batch = nr.resample(val_batch)
print("Batch output shape:", result_batch.cell_data.shape)  # (10, K)

Batch output shape: (10, 35005)

Next steps#