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:
build the target grid —
UTMGrid: the pixel-centerx,yand the CRS of the tile;reproject its pixel centers to lon/lat (
pyproj);construct a resampler on those points — this determines which HEALPix cells the raster needs;
read only those cells from the source dataset;
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#
|
Operator used |
Behaviour |
|---|---|---|
|
|
Each pixel takes the value of the HEALPix cell containing its center. |
|
|
Weighted average of the 4 nearest cells. |
|
|
Weighted average of the 16 nearest cells (signed cubic-convolution kernel). |
|
|
Delaunay triangulation of the cell centers + C1 cubic interpolant. Exact for an affine field; the most accurate on smooth fields. |
a resampler class |
|
Any class accepting |
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_idspassed toresample— isNaN. With"clough_tocher", pixels outside the convex hull of the cell centers areNaNas well.Each method needs its own cells.
op.cell_idsdepends onmethod(the neighbourhood differs), so read the data with thecell_idsof 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.CloughTocherResamplerkeeps 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
pyprojworks for the target grid; only the default-CRS helper is UTM-specific (standard 6° zones, without the Norway/Svalbard exceptions).Like
CloughTocherResampleritself,"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.