healpix-analyse

Signal analysis on HEALPix grids, for Earth Observation.

healpix-analyse answers the question what do you do with the values stored in HEALPix cells: spherical harmonic transforms and power spectra, convolutions and multiscale pyramids, local flat-sky FFTs, neighbourhood filters, morphology, and foundation-model embeddings. Its companion healpix-geo answers the other question — where those cells are.

Every operator is written in PyTorch, accepts NumPy arrays or tensors, works on the full sphere or on a partial-sky set of NESTED cells, and is differentiable through torch.autograd.

pip install git+https://github.com/GRID4EARTH/healpix-analyse.git

Start here

1. Installation — install it, and the extras for the examples.

2. Overview — what each module is for, in one line each.

3. Pick your task in the table below.

Find the page you need

You want to…	Use	Page
Compute a power spectrum on the full sphere	HEALPixSHT	HEALPixSHT — spherical harmonics on the full sky
…on ERA5, a lat/lon grid, or any iso-latitude grid	alm_latlon	alm_latlon — Part 1: Quickstart
Understand the SHT conventions and quadrature	—	alm_latlon — Part 2: Mathematical foundations
Convolve a map, equivariantly, on the sphere	HealPixConv	HealPixConv — gauge-equivariant convolution
Split a flow into divergence and curl	uv_to_curl_div	HEALPixSHT — spherical harmonics on the full sky
Convolve with a large kernel, cheaply	LargeConv	Large receptive-field convolution
Convolve with a wide kernel given as an image, a formula in metres or a raster	HealPixWideConv	Wide-kernel convolution — one kernel image, one call
Filter at every scale with one kernel per band	HealPixPyramidConv	Pyramidal convolution — compact multiscale spherical filtering
Change resolution (coarser / finer)	HealPixDown, HealPixUp	HealPixDown — HEALPix resolution reduction, HealPixUp — HEALPix resolution increase
Build an exactly invertible multiscale pyramid	HealPixDecomp	Local multiscale HEALPix decomposition
Get divergence and curl at every scale	divcurl	Multiscale divergence and curl
Move data between HEALPix levels or domains	resample	HEALPix-to-HEALPix resampling
FFT a local patch as if it were flat	LocalFFT	Local two-dimensional FFT on HEALPix patches
Convolve a patch with a big kernel, via FFT	HealPixFFTConv	FFT-accelerated convolution on local HEALPix patches
Average / take the median over a physical radius	neighbour_reduce	HEALPix neighbourhood reductions
Filter by metric distance, or with a Gaussian	radial_filter	Metric radial filtering on HEALPix
Filter by azimuth (sun, shadow, wind)	directional_filter	Directional filtering
Take East/North gradients	gradient	HEALPix scalar-field gradients
Dilate or erode a mask	morphology	Binary morphology
Label connected regions, measure their area	components	HEALPix connected components
Measure area, perimeter, Euler characteristic	minkowski	minkowski — Differentiable Minkowski Functionals
Embed Sentinel-2 with DINOv3	GetDINOV3SAT	GetDINOV3SAT — DINOv3 embeddings of HEALPix data

For the signature of any function, see the API reference.

Worked examples

• Sentinel-2 local FFT — real B04/B08 reflectance, reconstruction metrics, local radial spectra.

• Notebooks — the full notebook gallery.