healpix_resample.BicubicResampler#

class healpix_resample.BicubicResampler(*args, Npt=16, area=None, sample_spacing_m=None, **kwargs)[source]#

Radial cubic-convolution HEALPix resampler.

Sits between BilinearResampler (Npt=4, inverse-distance weighted) and PSFResampler (iterative CG deconvolution): a fixed, non-iterative local interpolation using more neighbours than bilinear, built purely from comp_matrix() — no CG solve involved.

Weight function#

Keys’ cubic convolution kernel with a = -0.5 (the common default, matching PIL/cv2), applied to the radial distance u = self.d_m / s in place of a structured pixel offset:

w(u) = (a+2)|u|^3 - (a+3)|u|^2 + 1        for |u| <= 1
     = a|u|^3 - 5a|u|^2 + 8a|u| - 4a       for 1 < |u| < 2
     = 0                                   for |u| >= 2

Unlike the Gaussian/inverse-distance weights used by BilinearResampler and PSFResampler, this kernel is signed — it goes negative for 1 < |u| < 2, which is exactly what gives cubic convolution its sharpening property relative to bilinear.

Kernel scale#

Keys’ kernel is defined in units of the input grid spacing: its negative lobe 1 < |u| < 2 must fall on the second ring of samples. The scale of each link is therefore s = max(sigma_m, h), where h is the spacing of the link’s sample (sample_spacing_m below). When the samples are finer than the cells (downsampling) sigma_m wins, as before. When they are coarser (upsampling), scaling by the output cell size alone put the nearest samples in the negative lobe: the weights of a cell then cancelled, and the normalisation amplified them up to thousands of times, which gave values far outside the input range.

Two further consequences of the signed kernel:

  • A cell whose links still cancel strongly (sum|w| > 3 |sum w|, e.g. on scattered samples) uses only the positive lobe of its links (their absolute values if it has no positive weight), so its value stays a weighted average of its samples. _norm_col() / _norm_row() keep a last floor on the normalising sums (relative to the unsigned accumulated weight), see the inline comments on _norm_col().

  • invert() (inherited from KNeighborsResampler, hval @ self.MT) can genuinely overshoot/ring outside the local sample-value range — this is expected cubic-convolution behaviour, not a bug.

Parameters:
  • Npt (int) – Number of HEALPix neighbours per source sample used by the KNN. Keys’ kernel has support |u| < 2, roughly twice the reach of bilinear’s |u| < 1-ish support, so the natural analogue of the classic 4x4 bicubic stencil on a structured grid is Npt = 16 (default).

  • All other parameters are forwarded to `KNeighborsResampler`.

Parameters:
  • area (array-like or None) – Per-sample pixel area/weight, shape (N,). Only used by resample(conservative=True) – ignored by the default interpolation path. Defaults to 1.0 for every sample. See resample()’s docstring for the conservation guarantee and its one caveat specific to this class’s signed kernel.

  • sample_spacing_m (float, array-like or None) – Spacing of the input samples in metres, a scalar or one value per sample (N,); sets the kernel scale max(sigma_m, h) (see “Kernel scale”). None (default) estimates it as the distance of each sample to its nearest other sample (a scipy k-d tree on the unit vectors, queried in slices of batch_size when given). On a regular grid that is the grid spacing; pass it explicitly to skip the estimate on very large inputs.

__init__(*args, Npt=16, area=None, sample_spacing_m=None, **kwargs)[source]#

Pre-compute sparse operators.

Parameters:
  • lon_deg, lat_deg – unstructured sample coordinates in degrees, shape (N,); float32 or float64, the geometry is computed in float64

  • Npt – number of nearest HEALPix cells used per sample. A sample that does not find Npt kept cells within ring_search_max rings (samples much sparser than the cells) keeps the ones it found.

  • ring_search_init, ring_search_max – first and last HEALPix ring of the per-sample neighbour search; a ring_search_max below ring_search_init is raised to it

  • level – HEALPix level, nside = 2**level

  • sigma_m – Gaussian length scale (meters). If None, uses the HEALPix pixel scale sigma = sqrt(4*pi/(12*4**level))*R.

  • threshold – keep only HEALPix cells whose global weight sum >= threshold

  • nest – HEALPix indexing scheme

  • dtype/device – torch dtype/device for all matrices and computations

  • out_cell_ids – optional subset of level cells to restrict the output to (e.g. one chunk or one parent cell). If none of these cells has enough support among the samples, the operator is built with K = 0 instead of raising: resample() then returns cell_ids of size 0 and cell_data of shape (B, 0), except NearestResampler, whose fallback fills the requested cells with their nearest sample (see its max_distance_m).

  • batch_size – process the samples in slices of this size when building the operators (see healpix_weighted_nearest): the temporary memory of the neighbour search is then about 2 kB per sample of a slice instead of 2 kB per sample. None (default) processes all samples at once. The result is the same.

  • coarse_level_delta – number the cells of the neighbour search from their parents this many levels coarser (nested only; see healpix_weighted_nearest): the same cells, neighbours and ties as the fine-level search, in less time and memory. None (default): the fine-level search.

  • neighbours – the links (NeighbourLinks) of an earlier resampler on the same samples, level and search parameters (its neighbours attribute): the neighbour search is skipped and the distances computed again, so the resampler is the same, bit for bit. With Npt=1 it is ignored.

Raises:

RuntimeError – without out_cell_ids, when no cell passes threshold (lower threshold or widen the neighbourhood rings), or when cells pass it but no sample reaches any of them within ring_search_max rings.

Methods

__init__(*args[, Npt, area, sample_spacing_m])

Pre-compute sparse operators.

comp_matrix()

Build self.M (N,K), sparse CSC: links weighted by _link_weights() (and the tied links by _tie_weights()), normalised per cell (column).

get_cell_ids()

invert(hval)

Project HEALPix field back to the sample locations.

resample(val, *[, conservative])

Estimate the HEALPix field from unstructured samples.

Attributes

MT

Sparse CSR (K, N) operator, cells -> samples (invert()); built on first access.

M_cons

Sparse CSR (N, K) conservative operator (resample(conservative=True), same links as M, each sample's weights summing to 1); built on first access.