phenotypic.refine.MaskFill#

class phenotypic.refine.MaskFill(structure: numpy.ndarray | None = None, origin: int = 0)[source]#

Bases: ObjectRefiner

Fill holes inside binary object masks to produce solid colonies.

Intuition:

Thresholding on agar-plate images can leave small voids inside colony masks due to illumination gradients, pigment heterogeneity, or glare. Filling these holes produces contiguous masks that better match the true colony footprint and improve area-based phenotypes.

Why this is useful for agar plates:

Many colonies exhibit darker centers or radial texture. Hole filling mitigates these within-colony gaps so that downstream measurements (area, perimeter, intensity summaries) are less biased.

Use cases:

  • After global or adaptive thresholding where donut-like masks appear.

  • Prior to morphological measurements that assume simply connected shapes.

Caveats:

  • Over-aggressive filling with a large structuring element can bridge adjacent colonies through narrow gaps, hurting separation.

  • If masks contain genuine cavities that should remain (e.g., hollow artifacts), filling may misrepresent structure.

Parameters:

  • structure (Optional[np.ndarray])

  • origin (int)

structure#

Structuring element used to define the neighborhood for filling. A larger or denser structure tends to close larger holes but can also smooth away fine boundaries.

Type:

Optional[np.ndarray]

origin#

Center offset for the structuring element. Adjusting the origin subtly shifts how neighborhoods are evaluated, which can influence edge behavior at colony boundaries.

Type:

int

Examples

Fill holes in colony masks to produce solid shapes
>>> from phenotypic.refine import MaskFill
>>> op = MaskFill()
>>> image = op.apply(image, inplace=True)

Methods

__init__

Initialize the filler and validate inputs.

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__(structure: numpy.ndarray | None = None, origin: int = 0)[source]#

Initialize the filler and validate inputs.

Parameters:

  • structure (Optional[np.ndarray]) – Binary structuring element. Larger or more connected structures fill bigger holes and may reduce small-scale texture within colony masks. If provided, must be a binary array; otherwise a ValueError is raised.

  • origin (int) – Origin offset for the structuring element. Typically left at 0; changing it slightly alters how neighborhoods are centered, which may affect edge sharpness at boundaries.

Raises:

ValueError – If structure is provided and is not a binary mask.

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