phenotypic.refine.MaskOpener#

class phenotypic.refine.MaskOpener(footprint: Literal['auto'] | numpy.ndarray | int | None = None)[source]#

Bases: ObjectRefiner

Morphologically open binary masks to remove thin connections and specks.

Intuition:

Binary opening (erosion followed by dilation) removes small isolated pixels and breaks narrow bridges between objects. On agar plates, this helps separate touching colonies and suppresses tiny artifacts from dust or condensation without overly shrinking well-formed colonies.

Why this is useful for agar plates:

Colonies may develop halos or be linked by faint film on the agar. A gentle opening step can restore separated masks, improving count and phenotype accuracy.

Use cases:

  • After thresholding, to split colonies connected by 1–2-pixel bridges.

  • To remove tiny noise specks before measuring morphology.

Caveats:

  • Too large a footprint erodes small colonies or weakly-stained edges, lowering recall and edge sharpness.

  • Opening can remove thin filaments that are biologically meaningful in spreading/filamentous phenotypes.

footprint#

Structuring element used for opening. A larger or denser footprint removes more thin connections and specks but risks eroding colony boundaries.

Type:

Literal[“auto”] | np.ndarray | int | None

Examples

Morphologically open masks to separate touching colonies
>>> from phenotypic.refine import MaskOpener
>>> op = MaskOpener(footprint='auto')
>>> image = op.apply(image, inplace=True)
Raises:

AttributeError – If an invalid footprint type is provided (checked during operation).

Parameters:

footprint (Literal['auto'] | np.ndarray | int | None)

Methods

__init__

Initialize the opener.

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: Literal['auto'] | numpy.ndarray | int | None = None)[source]#

Initialize the opener.

Parameters:

footprint (Literal["auto"] | np.ndarray | int | None) –

Structuring element for opening. Use: - “auto” to select a diamond footprint scaled to image size

(larger plates → slightly larger radius),

  • a NumPy array to pass a custom footprint,

  • an int radius to build a diamond footprint of that size,

  • or None to use the library default.

Larger radii disconnect wider bridges and suppress more speckles, but erode edges and can remove small colonies.

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