viz.rvsf.radially_variable_filter

viz.rvsf.radially_variable_filter(
    image,
    center,
    *,
    a,
    b,
    n,
    log=False,
    subpixels=10,
    mask=None,
)

Apply CometCIEF’s radially variable eight-neighbor filter.

The kernel half-width at radius rho is a + b * rho**n pixels. Larger widths reveal broader structure. The input is never modified.

Parameters

image : (array - like, shape(height, width)): Nonempty, real 2-D image. Masked-array masks and nonfinite pixels are excluded. Pass CCDData pixels and its mask separately.
center : tuple of float: Zero-based (x, y) nucleus coordinates within the image. Fractional positions are supported. Subtract one from CometCIEF coordinates.
a : float: Finite, nonnegative kernel coefficients. a sets the central half-width and b controls growth with radius.
b : float: Finite, nonnegative kernel coefficients. a sets the central half-width and b controls growth with radius.
n : float: Finite, positive radial exponent. Choose it for the image structure.
log : bool = False: Apply log10(image) before filtering. Every unmasked finite pixel must be positive; otherwise raise ValueError.
subpixels : int = 10: Midpoint samples per pixel axis. The default 10 reproduces the source’s 10-by-10 width sampling. Use 1 for pixel-center sampling.
mask : array - like or None = None: Additional boolean-convertible exclusion mask with the same shape as image.

Returns

: ndarray: Float64 image with the same shape. Pixels whose stencil touches missing data or the image exterior are NaN. No flux normalization, clipping, or uncertainty propagation is performed.

Notes

For every midpoint, the half-width is rounded to the nearest pixel; half-integers round up. Four axial and four diagonal neighbors then give 1024*I - 192*sum(axial) - 64*sum(diagonal). The filter values are averaged over the pixel. The coefficients sum to zero, so a constant image gives zero wherever the stencil is valid.

All eight neighbors contribute even when the width rounds to zero. This preserves the zero response for constant images at small widths; the legacy Fortran code instead drops collapsed axial neighbors. Missing neighbors produce NaN rather than artificial bright borders.

The filter changes intensities and can produce negative lobes around stars and jets. Use the original calibrated image for photometry.

References

Samarasinha, Martin, and Larson (2013), Cometary Coma Image Enhancement Facility, https://cie.psi.edu/. The source attributes this algorithm to Steve Larson. For rotational differences, use larson_sekanina.

Examples

A constant image has no local structure:

>>> from astroimred.viz import radially_variable_filter
>>> data = np.ones((7, 7))
>>> result = radially_variable_filter(data, (3, 3), a=1, b=0, n=1)
>>> bool(result[3, 3] == 0)
True