phenotypic.refine.WhiteTophatModifier#

class phenotypic.refine.WhiteTophatModifier(footprint_shape='disk', footprint_radius: int | None = None)[source]#

Bases: ObjectRefiner

Suppress small bright structures in the mask using white tophat.

Intuition:

White tophat highlights small, bright features relative to their local background. On agar plates, glare, dust, or bright halos can create thin connections or speckles that pollute colony masks. This modifier detects those bright micro-structures and subtracts them from the binary mask to improve separation and mask quality.

Why this is useful for agar plates:

Bright artifacts can bridge adjacent colonies or inflate perimeters. Removing those tiny bright elements yields cleaner, more compact masks that better match colony boundaries under uneven illumination.

Use cases:

  • Reducing glare-induced bridges between neighboring colonies.

  • Removing bright speckles/dust that become embedded in masks after thresholding.

Caveats:

  • Large footprints may remove real bright edges of colonies (e.g., highly reflective rims), slightly eroding edge sharpness.

  • If the footprint is too small, bright artifacts may remain.

Parameters:

footprint_radius (int)

footprint_shape#

Shape for the footprint used in the tophat transform. Supported: ‘disk’, ‘square’. Disk tends to preserve round features, while square can be more aggressive along axes.

Type:

str

footprint_radius#

Radius of the footprint. Larger values remove broader bright features but risk shrinking thin colony appendages. None auto-scales with image size.

Type:

int | None

Examples

Suppress small bright structures in the mask using white tophat
>>> from phenotypic.refine import WhiteTophatModifier
>>> op = WhiteTophatModifier(shape='disk', radius=5)
>>> image = op.apply(image, inplace=True)

Methods

__init__

Initialize the modifier.

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__(footprint_shape='disk', footprint_radius: int | None = None)[source]#

Initialize the modifier.

Parameters:

  • footprint_shape (str) –

    Footprint geometry for white tophat. - ‘disk’: Balanced in all directions; gentle on round colonies. - ‘square’: Slightly stronger along rows/columns; may remove

    more rectilinear glare or sensor artifacts.

  • footprint_radius (int | None) – Radius in pixels. Increasing removes larger bright structures and can improve background suppression, but may thin colony edges. None auto-selects ~0.4% of the smaller image dimension.

Raises:

ValueError – If shape is not one of the supported values (raised during operation).

__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.