"""
utm.py
HEALPix -> UTM raster resampling.
Every resampler in this package is built *from* a set of lon/lat samples
*to* HEALPix cells (``resample()``), and exposes the opposite direction as
``invert()`` (HEALPix cells -> those same sample locations). Going from a
HEALPix field to a regular UTM raster is therefore just a matter of choosing
the samples to be the pixel centers of the target UTM grid:
1. build the target grid (`UTMGrid`): pixel-center eastings/northings in a
projected CRS;
2. reproject the pixel centers to lon/lat (``pyproj``);
3. construct a resampler on those lon/lat points -- this is where the HEALPix
cells the raster needs are determined (`HealpixToUTM.cell_ids`);
4. read only those cells from the source dataset;
5. call ``resampler.invert(cell_data)`` and reshape to ``(ny, nx)``.
`HealpixToUTM` packages steps 2, 3 and 5. Its construction uses the geometry
only (grid and HEALPix level): it never sees the source dataset, so its cost
depends on the size of the raster, not on the size of the archive. Step 4 is
left to the caller, who selects ``op.cell_ids`` in its own store (a Zarr
archive, an in-memory array, ...). `healpix_to_utm` is the one-call
convenience wrapper for data already in memory.
Which ``invert()`` is used
--------------------------
====================== ==================================================
``method`` operator
====================== ==================================================
``"nearest"`` `GroupByResampler.invert` -- each pixel takes the
value of the HEALPix cell that contains it.
``"bilinear"`` `BilinearResampler.invert`
``"bicubic"`` `BicubicResampler.invert`
``"clough_tocher"`` `CloughTocherResampler.invert` -- Delaunay /
Clough-Tocher C1 cubic interpolant of the cell
centers, evaluated at the pixel centers (exact for
an affine field, no extrapolation).
a resampler class instantiated as ``cls(lon_deg=, lat_deg=, level=,
...)`` and used through ``invert()``.
====================== ==================================================
``"nearest"`` deliberately does **not** use `NearestResampler.invert`: that
method scatters each cell to its single nearest sample, so on a raster finer
than the HEALPix cells most pixels would receive nothing.
A pixel that depends on a cell without data (NaN, or absent from the cells
passed to ``resample``) is returned as NaN, and so are, for Clough-Tocher,
pixels outside the convex hull of the cell centers.
``pyproj`` is an optional dependency, only needed by this module
(``pip install healpix-resample[utm]``).
Nothing here is specific to UTM beyond the helpers that pick a UTM zone:
any projected CRS accepted by ``pyproj`` can be used for the target grid.
"""
from __future__ import annotations
from dataclasses import dataclass
from typing import Any, Optional, Tuple, Union
import numpy as np
import torch
import healpix_geo
from healpix_resample.base import T_Array
from healpix_resample.bicubic import BicubicResampler
from healpix_resample.bilinear import BilinearResampler
from healpix_resample.clough_tocher import CloughTocherResampler
from healpix_resample.groupby import GroupByResampler
def _pyproj():
try:
import pyproj
except ImportError as exc: # pragma: no cover - exercised only without pyproj
raise ImportError(
"healpix_resample.utm needs the optional dependency `pyproj` "
"(pip install healpix-resample[utm], or `pyproj` from conda-forge "
"in a conda/pixi environment)."
) from exc
return pyproj
def _as_crs(crs):
pyproj = _pyproj()
if isinstance(crs, pyproj.CRS):
return crs
if isinstance(crs, (int, np.integer)):
return pyproj.CRS.from_epsg(int(crs))
return pyproj.CRS.from_user_input(crs)
def _to_numpy(a) -> np.ndarray:
if isinstance(a, torch.Tensor):
return a.detach().cpu().numpy()
return np.asarray(a)
def _cell_size_m(level: int, radius: float = 6371000.0) -> float:
"""Side of a square with the area of one HEALPix cell at `level` (m)."""
return float(np.sqrt(4.0 * np.pi / (12.0 * 4.0 ** int(level))) * radius)
[docs]
def utm_crs_from_lonlat(lon_deg, lat_deg):
"""WGS84 / UTM CRS of the zone containing the centroid of the points.
The centroid is taken on the sphere (mean unit vector), so points
straddling the antimeridian are handled. The standard 6-degree zones
are used; the Norway / Svalbard exceptions are not applied.
Returns
-------
pyproj.CRS
``EPSG:326zz`` (northern hemisphere) or ``EPSG:327zz`` (southern).
"""
pyproj = _pyproj()
lon = np.radians(np.asarray(_to_numpy(lon_deg), dtype=np.float64).reshape(-1))
lat = np.radians(np.asarray(_to_numpy(lat_deg), dtype=np.float64).reshape(-1))
if lon.size == 0:
raise ValueError("utm_crs_from_lonlat: empty input.")
clat = np.cos(lat)
v = np.array([(clat * np.cos(lon)).mean(), (clat * np.sin(lon)).mean(), np.sin(lat).mean()])
lon_c = np.degrees(np.arctan2(v[1], v[0]))
lat_c = np.degrees(np.arctan2(v[2], np.hypot(v[0], v[1])))
zone = int(np.floor((lon_c + 180.0) / 6.0)) % 60 + 1
return pyproj.CRS.from_epsg((32600 if lat_c >= 0.0 else 32700) + zone)
[docs]
@dataclass(frozen=True)
class UTMGrid:
"""A regular raster in a projected (typically UTM) CRS.
Attributes
----------
crs : pyproj.CRS
Projected CRS of the grid.
x : numpy.ndarray
Pixel-center eastings, shape ``(nx,)`` (CRS units, metres for UTM),
ascending.
y : numpy.ndarray
Pixel-center northings, shape ``(ny,)``. Descending (north-up, the
usual raster convention) when built by `from_bounds` /
`from_cell_ids`.
"""
crs: Any
x: np.ndarray
y: np.ndarray
def __post_init__(self):
object.__setattr__(self, "crs", _as_crs(self.crs))
x = np.asarray(self.x, dtype=np.float64).reshape(-1)
y = np.asarray(self.y, dtype=np.float64).reshape(-1)
if x.size == 0 or y.size == 0:
raise ValueError("UTMGrid: x and y must be non-empty.")
object.__setattr__(self, "x", x)
object.__setattr__(self, "y", y)
@property
def shape(self) -> Tuple[int, int]:
"""``(ny, nx)``."""
return (int(self.y.size), int(self.x.size))
@classmethod
def from_bounds(cls, crs, bounds, resolution: float) -> "UTMGrid":
"""Grid covering ``bounds = (xmin, ymin, xmax, ymax)`` (outer pixel
*edges*) with square pixels of side `resolution`. The upper-left
corner is kept exactly; the extent is rounded up to a whole number
of pixels."""
xmin, ymin, xmax, ymax = (float(b) for b in bounds)
res = float(resolution)
if res <= 0:
raise ValueError("UTMGrid.from_bounds: resolution must be > 0.")
if xmax <= xmin or ymax <= ymin:
raise ValueError("UTMGrid.from_bounds: empty bounds.")
nx = max(1, int(np.ceil((xmax - xmin) / res - 1e-9)))
ny = max(1, int(np.ceil((ymax - ymin) / res - 1e-9)))
x = xmin + (np.arange(nx) + 0.5) * res
y = ymax - (np.arange(ny) + 0.5) * res
return cls(crs=crs, x=x, y=y)
@classmethod
def from_cell_ids(
cls,
cell_ids,
level: int,
resolution: Optional[float] = None,
*,
crs=None,
nest: bool = True,
ellipsoid: str = "WGS84",
) -> "UTMGrid":
"""Grid covering the bounding box of a set of HEALPix cells.
Parameters
----------
cell_ids : array-like
HEALPix cell ids at `level`.
resolution : float, optional
Pixel size in CRS units. Defaults to the HEALPix cell size at
`level` (square root of the cell area).
crs : optional
Target CRS (EPSG code, string or ``pyproj.CRS``). Defaults to
the UTM zone of the cells' centroid (`utm_crs_from_lonlat`).
The bounds are those of the cell *centers*, snapped outwards to a
multiple of `resolution`.
"""
pyproj = _pyproj()
ids = _to_numpy(cell_ids).astype(np.uint64).reshape(-1)
hp = healpix_geo.nested if nest else healpix_geo.ring
lon, lat = hp.healpix_to_lonlat(ids, int(level), ellipsoid=ellipsoid)
lon = np.asarray(lon, dtype=np.float64)
lat = np.asarray(lat, dtype=np.float64)
crs = utm_crs_from_lonlat(lon, lat) if crs is None else _as_crs(crs)
res = _cell_size_m(level) if resolution is None else float(resolution)
fwd = pyproj.Transformer.from_crs(pyproj.CRS.from_epsg(4326), crs, always_xy=True)
x, y = fwd.transform(lon, lat)
xmin = np.floor(np.min(x) / res) * res
ymin = np.floor(np.min(y) / res) * res
xmax = np.ceil(np.max(x) / res) * res
ymax = np.ceil(np.max(y) / res) * res
return cls.from_bounds(crs, (xmin, ymin, max(xmax, xmin + res), max(ymax, ymin + res)), res)
def lonlat(self) -> Tuple[np.ndarray, np.ndarray]:
"""WGS84 longitude / latitude of the pixel centers, each ``(ny, nx)``
(degrees, longitude in [-180, 180])."""
pyproj = _pyproj()
inv = pyproj.Transformer.from_crs(self.crs, pyproj.CRS.from_epsg(4326), always_xy=True)
X, Y = np.meshgrid(self.x, self.y)
lon, lat = inv.transform(X, Y)
return np.asarray(lon), np.asarray(lat)
def padded(self, pad: int) -> "UTMGrid":
"""Same grid extended by `pad` pixels on every side (needs a
regularly spaced axis of at least two pixels to extrapolate)."""
pad = int(pad)
if pad <= 0:
return self
def _extend(a, name):
if a.size < 2:
raise ValueError(f"UTMGrid.padded: cannot pad a single-pixel {name} axis.")
step = a[1] - a[0]
if not np.allclose(np.diff(a), step, rtol=1e-6, atol=0.0):
raise ValueError(f"UTMGrid.padded: the {name} axis is not regularly spaced.")
before = a[0] - step * np.arange(pad, 0, -1)
after = a[-1] + step * np.arange(1, pad + 1)
return np.concatenate([before, a, after])
return UTMGrid(crs=self.crs, x=_extend(self.x, "x"), y=_extend(self.y, "y"))
_METHODS = {
"nearest": GroupByResampler,
"bilinear": BilinearResampler,
"bicubic": BicubicResampler,
"clough_tocher": CloughTocherResampler,
}
[docs]
class HealpixToUTM:
"""Resample HEALPix cell data onto a UTM raster through ``invert()``.
The operator is **geometry-only**: it is built from the target grid and
the HEALPix level alone, without any data and without the list of cells
available in the source dataset. Construction determines which HEALPix
cells the raster needs (`cell_ids`); only those have to be read from the
source, which is what makes the operator usable on a store far larger
than memory (e.g. a global, metre-scale Zarr archive):
>>> op = HealpixToUTM(grid, level, method="bilinear")
>>> op.cell_ids # (K,) cells to read, sorted
>>> data = store.sel(cell_ids=op.cell_ids) # (B, K), read only those
>>> img = op.resample(data) # (B, ny, nx)
Parameters
----------
grid : UTMGrid
Target raster (pixel-center ``x``, ``y`` and CRS of the tile).
level : int
HEALPix level of the source data.
method : {"bilinear", "nearest", "bicubic", "clough_tocher"} or type
Which resampler's ``invert()`` to use -- see the module docstring.
A resampler class can be passed directly; it must accept
``lon_deg, lat_deg, level`` and implement ``invert()``.
nest : bool
HEALPix indexing scheme of the source cell ids.
ellipsoid : str
Passed through to the resampler (``healpix_geo``).
pad : int, optional
Number of extra pixels added around the grid while building the
operator, cropped from the output. Only useful for Clough-Tocher,
whose forward construction keeps a cell only if it lies inside the
convex hull of the *samples* (here: the pixel centers): without a
margin the cells surrounding the raster would be discarded and the
border pixels could not be interpolated. Default: two HEALPix cell
widths for ``"clough_tocher"``, 0 otherwise.
dtype, device, verbose
Passed to the resampler.
**resampler_kwargs
Extra keyword arguments for the resampler constructor (e.g.
``Npt``, ``threshold``).
Attributes
----------
grid : UTMGrid
cell_ids : numpy.ndarray
The HEALPix cells (at `level`) required to fill the raster, int64,
shape ``(K,)``, sorted in ascending order. This is the selection to apply to the source
dataset before calling `resample()`.
K : int
``len(cell_ids)``.
resampler
The underlying resampler (built on the padded pixel centers).
valid : numpy.ndarray
Boolean, shape ``(ny, nx)``: pixels the operator can fill when every cell of `cell_ids` carries
data. Pixels outside it are NaN in every output (only Clough-Tocher
can have such pixels: those outside the hull of the cell centers).
"""
[docs]
def __init__(
self,
grid: UTMGrid,
level: int,
*,
method: Union[str, type] = "bilinear",
nest: bool = True,
ellipsoid: str = "WGS84",
pad: Optional[int] = None,
dtype: torch.dtype = torch.float64,
device: Optional[Union[torch.device, str]] = None,
verbose: bool = False,
**resampler_kwargs,
) -> None:
if not isinstance(grid, UTMGrid):
raise TypeError("HealpixToUTM: `grid` must be a UTMGrid.")
self.grid = grid
self.level = int(level)
self.nest = bool(nest)
if isinstance(method, str):
if method not in _METHODS:
raise ValueError(
f"HealpixToUTM: unknown method {method!r}; expected one of "
f"{sorted(_METHODS)} or a resampler class."
)
resampler_cls = _METHODS[method]
else:
resampler_cls = method
self.method = method
# ---- pixel centers (optionally padded) -> lon/lat ------------------
if pad is None:
if resampler_cls is CloughTocherResampler and min(grid.shape) >= 2:
step = min(abs(grid.x[1] - grid.x[0]), abs(grid.y[1] - grid.y[0]))
pad = int(np.ceil(2.0 * _cell_size_m(self.level) / step))
else:
pad = 0
self.pad = int(pad)
work = grid.padded(self.pad)
self._work_shape = work.shape
lon, lat = work.lonlat()
# ---- resampler on the pixel centers --------------------------------
# No `out_cell_ids`: the resampler discovers by itself the cells
# surrounding the pixel centers, so the size of the source dataset
# never enters the construction.
kwargs = dict(
lon_deg=lon.reshape(-1),
lat_deg=lat.reshape(-1),
level=self.level,
nest=self.nest,
ellipsoid=ellipsoid,
dtype=dtype,
device=device,
verbose=verbose,
)
kwargs.update(resampler_kwargs)
self.resampler = resampler_cls(**kwargs)
dev = self.resampler.device
# ---- required cells, exposed sorted --------------------------------
rs_ids = np.asarray(self.resampler.get_cell_ids()).astype(np.int64).reshape(-1)
order = np.argsort(rs_ids, kind="stable")
self.cell_ids = rs_ids[order]
self.K = int(rs_ids.size)
# position, in the sorted `cell_ids`, of each resampler-order cell
rank = np.empty(self.K, dtype=np.int64)
rank[order] = np.arange(self.K)
self._rank = torch.as_tensor(rank, dtype=torch.long, device=dev)
# ---- pixels the operator can fill -----------------------------------
# invert(1) is the per-pixel weight sum: ~1 where the pixel is
# interpolated from cells, 0 where no cell reaches it, NaN where the
# operator itself declines (Clough-Tocher outside the cell hull).
cov = self.resampler.invert(torch.ones(self.K, dtype=self.resampler.dtype, device=dev))
self._valid_flat = torch.isfinite(cov) & (cov > 0.5)
self.valid = self._crop(self._valid_flat.reshape(self._work_shape)).cpu().numpy()
def _crop(self, a):
if self.pad == 0:
return a
p = self.pad
return a[..., p:-p, p:-p]
@torch.no_grad()
def resample(self, cell_data: T_Array, cell_ids: Optional[T_Array] = None) -> T_Array:
"""HEALPix cells -> UTM raster.
Args:
cell_data: values on HEALPix cells, shape (K,) or (B, K) (B is a
batch dimension: bands, time steps, ...). NumPy array or
torch tensor.
cell_ids: the cell ids `cell_data` is defined on, shape (K,).
If omitted, `cell_data` must be given on ``self.cell_ids``,
in that order (the natural case when the data were read
with that selection). If given, the cells may come in any
order and may be a superset or a subset of
``self.cell_ids``; required cells that are absent are
treated as NaN.
Returns:
(ny, nx) or (B, ny, nx), same array type as `cell_data`, in the
resampler's floating dtype. NaN cells (or absent ones) propagate
to the pixels they contribute to; pixels outside `valid` are NaN.
"""
rs = self.resampler
y = cell_data if isinstance(cell_data, torch.Tensor) else torch.as_tensor(np.asarray(cell_data))
y = y.to(rs.device, dtype=rs.dtype)
squeezed = y.ndim == 1
if squeezed:
y = y[None, :]
if y.ndim != 2:
raise ValueError(
f"HealpixToUTM.resample: expected cell_data of shape (K,) or "
f"(B, K), got {tuple(cell_data.shape)}."
)
if cell_ids is None:
if y.shape[-1] != self.K:
raise ValueError(
f"HealpixToUTM.resample: cell_data has {y.shape[-1]} cells "
f"but the operator needs K={self.K} (self.cell_ids); pass "
f"`cell_ids=` if the data are defined on other cells."
)
else:
ids = _to_numpy(cell_ids).astype(np.int64).reshape(-1)
if ids.size != y.shape[-1]:
raise ValueError(
f"HealpixToUTM.resample: cell_ids has {ids.size} entries but "
f"cell_data has {y.shape[-1]} cells."
)
if ids.size == 0:
raise ValueError("HealpixToUTM.resample: `cell_ids` is empty.")
src = np.argsort(ids, kind="stable")
ids_sorted = ids[src]
if np.any(ids_sorted[1:] == ids_sorted[:-1]):
raise ValueError("HealpixToUTM.resample: `cell_ids` must be unique.")
pos = np.clip(np.searchsorted(ids_sorted, self.cell_ids), 0, ids.size - 1)
found = ids_sorted[pos] == self.cell_ids
sel = torch.as_tensor(src[pos], dtype=torch.long, device=rs.device)
y = y[:, sel]
if not found.all():
y[:, torch.as_tensor(~found, device=rs.device)] = float("nan")
out = rs.invert(y[:, self._rank]) # (B, ny_work * nx_work)
out = torch.where(self._valid_flat[None, :], out, torch.full_like(out, float("nan")))
out = self._crop(out.reshape((out.shape[0],) + self._work_shape))
if squeezed:
out = out[0]
if not isinstance(cell_data, torch.Tensor):
out = out.cpu().numpy()
return out
[docs]
def healpix_to_utm(
cell_data: T_Array,
cell_ids: T_Array,
level: int,
*,
grid: Optional[UTMGrid] = None,
resolution: Optional[float] = None,
crs=None,
method: Union[str, type] = "bilinear",
nest: bool = True,
ellipsoid: str = "WGS84",
**kwargs,
) -> Tuple[T_Array, UTMGrid]:
"""Resample an in-memory HEALPix field onto a UTM raster in one call.
If `grid` is not given, it is built with `UTMGrid.from_cell_ids` from
the bounding box of the cells, using `resolution` (default: the HEALPix
cell size) and `crs` (default: the UTM zone of the cells' centroid).
This wrapper needs `cell_data` and `cell_ids` in memory. For a dataset
larger than memory, or to apply the same geometry to several fields,
build a `HealpixToUTM` first, read only its ``cell_ids`` from the
source, and call its ``resample()``.
Returns
-------
data : numpy.ndarray or torch.Tensor
Raster values, shape ``(ny, nx)`` or ``(B, ny, nx)``, same array
type as `cell_data`. Pixels that depend on a cell absent from
`cell_ids` are NaN.
grid : UTMGrid
The grid the data are defined on (``grid.x``, ``grid.y``,
``grid.crs``).
"""
if grid is None:
grid = UTMGrid.from_cell_ids(
cell_ids, level, resolution, crs=crs, nest=nest, ellipsoid=ellipsoid
)
elif resolution is not None or crs is not None:
raise ValueError("healpix_to_utm: pass either `grid` or `resolution`/`crs`, not both.")
op = HealpixToUTM(grid, level, method=method, nest=nest, ellipsoid=ellipsoid, **kwargs)
return op.resample(cell_data, cell_ids=cell_ids), grid