HEALPix → UTM#

healpix_resample.utm resamples a field defined on HEALPix cells onto a regular raster in a projected CRS (typically a UTM zone).

Every resampler of this package maps lon/lat samples to HEALPix cells with resample(), and maps HEALPix cells back to those samples with invert(). HEALPix → UTM is therefore the invert() of a resampler whose samples are the pixel centers of the target UTM grid:

  1. build the target grid — UTMGrid: the pixel-center x, y and the CRS of the tile;

  2. reproject its pixel centers to lon/lat (pyproj);

  3. construct a resampler on those points — this determines which HEALPix cells the raster needs;

  4. read only those cells from the source dataset;

  5. resampler.invert(cell_data), reshaped to (ny, nx).

HealpixToUTM does steps 2, 3 and 5. It is built from the geometry alone (grid and HEALPix level) and never sees the source dataset, so it can be used on a store far larger than memory: its cost depends on the size of the raster, not on the size of the archive. pyproj is an optional dependency:

pip install healpix-resample[utm]   # or pyproj from conda-forge in a conda/pixi environment

A complete, runnable example is in the HEALPix → UTM tutorial.


Usage#

from healpix_resample import HealpixToUTM, UTMGrid

# target raster: pixel centers and CRS of the tile (y decreasing = north-up)
grid = UTMGrid(crs=32630, x=x, y=y)
# or from the outer pixel edges (xmin, ymin, xmax, ymax):
grid = UTMGrid.from_bounds(32630, (400000, 5358000, 402000, 5360000), resolution=10.0)

op = HealpixToUTM(grid, level, method="bilinear")   # geometry only, no data
op.cell_ids                         # (K,) int64, sorted: the cells the raster needs

data = ds.sel(cell_ids=op.cell_ids)["var"].values   # (B, K): read only those cells
img = op.resample(data)             # (B, ny, nx); (ny, nx) for data of shape (K,)

grid.x, grid.y, grid.crs            # coordinates of the output
op.valid                            # (ny, nx) bool: pixels the operator can fill

The operator can be reused for any other data defined on the same cells (other variables, other dates).

If the data are defined on other cells than exactly op.cell_ids — a superset, a different order, or a store where some required cells are missing — pass their ids: op.resample(data, cell_ids=ids). Required cells that are absent are treated as NaN.

For data already in memory, healpix_to_utm does everything in one call, and can derive the grid from the cells (bounding box of the cell centers, UTM zone of their centroid unless crs= is given, resolution defaulting to the HEALPix cell size):

from healpix_resample import healpix_to_utm

img, grid = healpix_to_utm(cell_data, cell_ids, level, resolution=10.0, method="bilinear")

Cell ids are in the nested scheme by default (nest=False for ring). NumPy arrays and torch tensors are both accepted, and the output has the type of the input.


Methods#

method

Operator used

Behaviour

"nearest"

GroupByResampler.invert

Each pixel takes the value of the HEALPix cell containing its center.

"bilinear" (default)

BilinearResampler.invert

Weighted average of the 4 nearest cells.

"bicubic"

BicubicResampler.invert

Weighted average of the 16 nearest cells (signed cubic-convolution kernel).

"clough_tocher"

CloughTocherResampler.invert

Delaunay triangulation of the cell centers + C1 cubic interpolant. Exact for an affine field; the most accurate on smooth fields.

a resampler class

cls(...).invert

Any class accepting lon_deg, lat_deg, level and implementing invert().

Extra keyword arguments (Npt, threshold, device, dtype, …) are passed to the resampler.

"nearest" does not use NearestResampler.invert: that method sends each cell to its single nearest sample, so on a raster finer than the cells most pixels would receive nothing.


Notes#

  • No extrapolation. A pixel that depends on a cell without data — a NaN value, or a cell absent from the cell_ids passed to resample — is NaN. With "clough_tocher", pixels outside the convex hull of the cell centers are NaN as well.

  • Each method needs its own cells. op.cell_ids depends on method (the neighbourhood differs), so read the data with the cell_ids of the operator that will be applied.

  • pad (Clough-Tocher only, automatic by default): the operator is built on a grid extended by two cell widths and cropped afterwards. CloughTocherResampler keeps a cell only when it lies inside the hull of its samples — here the pixel centers — so without this margin the cells surrounding the raster would be discarded and its border could not be interpolated.

  • The weighted-average methods ("bilinear", "bicubic") are not affine-exact.

  • Any projected CRS understood by pyproj works for the target grid; only the default-CRS helper is UTM-specific (standard 6° zones, without the Norway/Svalbard exceptions).

  • Like CloughTocherResampler itself, "clough_tocher" is meant for regional extents (it works in a local gnomonic plane) — which is also the domain of validity of a single UTM zone.