viz.enhance.enhance_rho

viz.enhance.enhance_rho(image, center, *, power=-1.0, subpixels=10, mask=None)

Compensate a radial brightness profile proportional to rho**power.

Parameters

image : (array - like, shape(height, width))

Nonempty, real, two-dimensional image. Nonfinite and masked pixels are treated as missing.

center : tuple of float

Zero-based (x, y) nucleus coordinates within the image. Fractional positions are supported.

power : float = -1.0

Finite exponent of the assumed brightness profile. Multiply by the midpoint mean of rho**(-power), with radius in pixels. Default -1 retains multiplication by mean radius; -2 uses mean squared radius. 0 leaves valid pixel values unchanged.

subpixels : int = 10

Midpoint samples per pixel axis. The default 10 follows the CometCIEF source’s 10-by-10 quadrature; 1 uses pixel centers.

mask : array - like or None = None

Additional boolean-convertible mask with the same shape as image.

Returns

: (ndarray, shape(height, width))

Float64 image. The input is never modified. Missing inputs, any nonfinite midpoint correction, and overflowed products become NaN.

Raises

: TypeError

If image or center is not real numeric data.

: ValueError

If image/mask geometry, center, power, or subpixels is invalid.

Notes

Each output is image * mean(rho**(-power)) over its midpoint grid, not image * mean(rho)**(-power). This is a discrete midpoint average, not analytic pixel-area integration.

At a sampled rho=0, negative power gives zero correction, power=0 gives unity, and positive power is singular (NaN). A grid that avoids zero can return a finite value; near-nucleus results for positive powers depend strongly on sampling. For power >= 2, the continuous area integral diverges in pixels containing the nucleus even if the discrete midpoint mean is finite. No radius floor is added.

The source routine first rescales the whole image to mean 100; this API omits that presentation-only step so calibrated data remains composable. No clipping or uncertainty propagation is applied.

Examples

Compensate a 1/rho**1.5 profile:

>>> image = np.ones((3, 3))
>>> result = enhance_rho(image, (1, 1), power=-1.5, subpixels=1)
>>> bool(result[1, 2] == 1.0)
True