phenotypic.enhance.RollingBallRemoveBG#

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

Bases: ImageEnhancer

Rolling-ball background removal (ImageJ-style) for agar plates.

Models the background as the surface traced by rolling a ball under the image intensity landscape, then subtracts it. For colony images, this effectively removes slow illumination gradients and agar shading while preserving colony structures.

Use cases (agar plates): - Correct uneven backgrounds from scanner vignetting, lid glare, or agar

thickness variations.

  • Improve segmentation of dark colonies on bright agar by flattening the background.

Tuning and effects: - radius: Core scale of the rolling ball. Set larger than typical colony

diameter so colonies are not smoothed into the background. Too small a radius will erode colonies and create halos.

  • kernel: Custom structuring element defining the ball shape. Providing a kernel overrides radius and allows non-spherical shapes if needed.

  • nansafe: Enable if your images contain masked/NaN regions (e.g., plate outside masked to NaN). When False, NaNs may propagate or cause artifacts.

Caveats: - Overly small radius removes real features and can bias size/area metrics. - May introduce edge effects near the plate boundary; consider masking the

plate region or using nansafe with an appropriate mask.

Parameters:

  • radius (int)

  • kernel (np.ndarray)

  • nansafe (bool)

radius#

Ball radius (in pixels) controlling the background scale; choose > colony diameter.

Type:

int

kernel#

Optional custom kernel; overrides radius when set.

Type:

np.ndarray

nansafe#

Handle NaNs during computation to respect masked regions.

Type:

bool

Methods

__init__

apply

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

dispose_widgets

Drop references to the UI widgets.

sync_widgets_from_state

Push internal state into widgets.

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 radius (pixels). Use a value larger than colony diameter to avoid removing colony signal. Default 100.

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

  • 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

dispose_widgets() → None#

Drop references to the UI widgets.

Return type:

None

sync_widgets_from_state() → None#

Push internal state into widgets.

Return type:

None

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.