skimage2.restoration.rolling_ball#

skimage2.restoration.rolling_ball(image, *, radius=100, kernel=None, nansafe=False, num_threads=<DEPRECATED>, workers=None)[source]#

Estimate background intensity using the rolling-ball algorithm.

This function is a generalization of the rolling-ball algorithm [1] to estimate the background intensity of an n-dimensional image. This is typically useful for background subtraction in case of uneven exposure. Think of the image as a landscape (where altitude is determined by intensity), under which a ball of given radius is rolled. At each position, the ball’s apex gives the resulting background intensity.

Parameters:
imagendarray

The image to be filtered.

radiusint, optional

Radius of the ball-shaped kernel to be rolled under the image landscape. Used only if kernel is None.

kernelndarray, optional

An alternative way to specify the rolling ball, as an arbitrary kernel. It must have the same number of axes as image.

nansafebool, optional

If False (default), the function assumes that none of the values in image are np.nan, and uses a faster implementation.

workersint, optional

The maximum number of threads to use. If None, use the OpenMP default value; typically equal to the maximum number of virtual cores. Note: This is an upper limit to the number of threads. The exact number is determined by the system’s OpenMP library.

Added in version 0.26: Replaces deprecated parameter num_threads.

Returns:
backgroundndarray

The estimated background of the image.

Other Parameters:
num_threadsDEPRECATED

Deprecated in favor of workers.

Deprecated since version 0.26.

Notes

This implementation assumes that dark pixels correspond to the background. If you have a bright background, invert the image before passing it to this function, e.g., using skimage.util.invert().

For this method to give meaningful results, the radius of the ball (or typical size of the kernel, in the general case) should be larger than the typical size of the image features of interest.

This algorithm is sensitive to noise (in particular salt-and-pepper noise). If this is a problem in your image, you can apply mild Gaussian smoothing before passing the image to this function.

This algorithm’s complexity is polynomial in the radius, with degree equal to the image dimensionality (a 2D image is N^2, a 3D image is N^3, etc.), so it can take a long time as the radius grows beyond 30 or so ([2], [3]). It is an exact N-dimensional calculation; if all you need is an approximation, faster options to consider are top-hat filtering [4] or downscaling-then-upscaling to reduce the size of the input processed.

References

[1]

Sternberg, Stanley R. “Biomedical image processing.” Computer 1 (1983): 22-34. DOI:10.1109/MC.1983.1654163

Examples

>>> import numpy as np
>>> import _skimage2 as ski2
>>> image = ski2.data.coins()
>>> background = ski2.restoration.rolling_ball(image)
>>> filtered_image = image - background

>>> import numpy as np
>>> import _skimage2 as ski2
>>> image = ski2.data.coins()
>>> kernel = ski2.restoration.ellipsoid_kernel((101, 101), 75)
>>> background = ski2.restoration.rolling_ball(image, kernel=kernel)
>>> filtered_image = image - background