healpix_resample.BicubicResampler#

class healpix_resample.BicubicResampler(*args, Npt=16, area=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 / self.sigma_m 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.

Two consequences of the signed kernel, both handled in comp_matrix():

  • The per-cell/per-sample weight sums used to normalize M/MT can, in principle, be arbitrarily close to zero from cancellation between the positive central lobe and the negative outer lobe — even when every individual link weight is well-behaved in magnitude. We guard the normalizing division with a small floor (relative to the unsigned accumulated weight for that row/column) rather than dropping or re-flagging affected cells; see the inline comments in comp_matrix().

  • 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.

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

Pre-compute sparse operators.

Parameters:

  • lon_deg, lat_deg – unstructured sample coordinates in degrees, shape (N,)

  • Npt – number of nearest HEALPix cells used per sample

  • 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

Methods

__init__(*args[, Npt, area])

Pre-compute sparse operators.

comp_matrix()

get_cell_ids()

invert(hval)

Project HEALPix field back to the sample locations.

resample(val, *[, conservative])

Estimate the HEALPix field from unstructured samples.