papyri
{ } Raw JSON

bundles / skimage 0.26.1rc0.dev0+git20260530.b607368ff / skimage / restoration / _rolling_ball / rolling_ball

function

skimage.restoration._rolling_ball:rolling_ball

source: /dev/scikit-image/src/skimage/restoration/_rolling_ball.py :11

Signature

def   rolling_ball ( image ,  * ,  radius = 100 ,  kernel = None ,  nansafe = False ,  num_threads = <DEPRECATED> ,  workers = None )

Summary

Estimate background intensity using the rolling-ball algorithm.

Extended Summary

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

image : ndarray

The image to be filtered.

radius : int, optional

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

kernel : ndarray, optional

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

nansafe : bool, optional

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

workers : int, 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.

Returns

background : ndarray

The estimated background of the image.

Other Parameters

num_threads : DEPRECATED

Deprecated in favor of workers.

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.

Examples

import numpy as np
import skimage as ski
image = ski.data.coins()
background = ski.restoration.rolling_ball(image)
filtered_image = image - background
✓
import numpy as np
import skimage as ski
image = ski.data.coins()
kernel = ski.restoration.ellipsoid_kernel((101, 101), 75)
background = ski.restoration.rolling_ball(image, kernel=kernel)
filtered_image = image - background
✓

Aliases

  • skimage.restoration.rolling_ball