phenotypic.enhance.SubtractRollingBall#

class phenotypic.enhance.SubtractRollingBall(radius: int = 100, kernel: numpy.ndarray | None = None, nansafe: bool = False)[source]

Bases: ImageEnhancer

Remove background from detect_mat with ImageJ-style rolling-ball subtraction.

Models the background as the surface traced by rolling a parabolic ball under the image intensity landscape, then subtracts it. Effectively removes slow illumination gradients and agar shading while preserving colony structures. Handles non-Gaussian intensity ramps better than SubtractGaussian.

For algorithm details, see What Enhancement Actually Does.

Parameters:

  • radius (int) – Rolling-ball radius in pixels. Must be larger than the typical colony diameter to avoid subtracting colony signal. Typical range: 50–200. Default: 100.

  • kernel (np.ndarray) – Optional custom ball/shape array. When provided, overrides radius. Default: None.

  • nansafe (bool) – If True, treat NaNs as missing data to avoid artifacts when using masked images. Default: False.

Returns:

Input image with detect_mat background-subtracted. rgb and gray are unchanged.

Return type:

Image

Best For:

  • Scanner vignetting, lid glare, or agar thickness variations.

  • Flattening backgrounds to improve segmentation of dark colonies on bright agar.

  • Images with non-linear illumination gradients where Gaussian subtraction leaves residual background.

Consider Also:

  • SubtractGaussian for faster Gaussian-based subtraction with continuous sigma control.

  • OpeningSubtractBg for OpenCV-accelerated morphological background removal in high-throughput pipelines.

  • WhiteTophatEnhance when you want to isolate small bright structures rather than subtract background.

See also

Tutorial 3: Enhancing Before Detection for a visual walkthrough of background subtraction on plate images. What Enhancement Actually Does for background on rolling-ball and other illumination correction strategies.

Methods

__init__

apply

Applies the operation to an image, either in-place or on a copy.

widget

Return (and optionally display) the root widget.
__init__(radius: int = 100, kernel: numpy.ndarray | None = None, nansafe: bool = False)[source]
Parameters:

  • radius (int) – Rolling-ball width (pixels). Use a value larger than colony diameter to avoid removing colony signal. Default 100.

  • kernel (np.ndarray) – Optional custom ball/shape; when provided it overrides width.

  • nansafe (bool) – If True, treat NaNs as missing data to avoid artifacts when using masked images (e.g., outside the plate).

__del__()

Automatically stop tracemalloc when the object is deleted.

__getstate__()

Prepare the object for pickling by disposing of any widgets.

This ensures that UI components (which may contain unpickleable objects like input functions or thread locks) are cleaned up before serialization.

Note

This method modifies the object state by calling dispose_widgets(). Any active widgets will be detached from the object.

apply(image, inplace=False)

Applies the operation to an image, either in-place or on a copy.

Parameters:

  • image (Image) – The arr image to apply the operation on.

  • inplace (bool) – If True, modifies the image in place; otherwise, operates on a copy of the image.

Returns:

The modified image after applying the operation.

Return type:

Image

widget(image: Image | None = None, show: bool = False) → Widget

Return (and optionally display) the root widget.

Parameters:

  • image (Image | None) – Optional image to visualize. If provided, visualization controls will be added to the widget.

  • show (bool) – Whether to display the widget immediately. Defaults to False.

Returns:

The root widget.

Return type:

ipywidgets.Widget

Raises:

ImportError – If ipywidgets or IPython are not installed.

This Page