phenotypic.enhance.MedianFilter

class phenotypic.enhance.MedianFilter(mode: Literal['nearest', 'reflect', 'constant', 'mirror', 'wrap'] = 'nearest', shape: Literal['disk', 'square', 'diamond'] | None = None, radius: int = 5, cval: float = 0.0)

Bases: ImageEnhancer

Median filtering to reduce impulsive noise while preserving edges.

The median filter replaces each pixel with the median of its local neighborhood and is robust to outliers. For agar plate colony images, this is effective at removing speckle from condensation droplets, dust, or sensor noise without blurring colony edges as much as Gaussian smoothing would.

Use cases (agar plates): - Reduce “salt-and-pepper” artifacts and tiny bright/dark specks prior to

thresholding or edge detection.

• Preserve colony boundaries better than linear blur when colonies are small or closely packed.

Tuning and effects: - Footprint: This implementation uses the library default footprint when none

is provided (a small neighborhood). For stronger denoising, prefer RankMedianEnhancer where you can set shape and radius explicitly.

• mode/cval: Control how borders are handled. ‘reflect’ or ‘nearest’ avoids artificial artifacts at the plate boundary; ‘constant’ uses cval as fill.

Caveats: - Using a very large neighborhood (when configured via alternative median

functions) can remove small colonies or close thin gaps.

• Median filtering can flatten fine texture within pigmented colonies; use a light application or a rank filter with an appropriate footprint.

Parameters:

• mode (Literal['nearest', 'reflect', 'constant', 'mirror', 'wrap'])

• shape (Literal['disk', 'square', 'diamond'] | None)

• radius (int)

• cval (float)

mode

Boundary handling mode: ‘nearest’, ‘reflect’, ‘constant’, ‘mirror’, or ‘wrap’.

Type:

str

cval

Constant fill when mode=’constant’.

Type:

float

Methods

__init__	This class is designed to facilitate image processing tasks, particularly for analyzing microbe colonies on solid media agar.
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__(mode: Literal['nearest', 'reflect', 'constant', 'mirror', 'wrap'] = 'nearest', shape: Literal['disk', 'square', 'diamond'] | None = None, radius: int = 5, cval: float = 0.0)

This class is designed to facilitate image processing tasks, particularly for analyzing microbe colonies on solid media agar. By adjusting the mode, footprint, radius, and cval attributes, users can modify the processing behavior and results to suit their specific requirements for studying spatial arrangements, colony boundaries, and other morphological features.

Parameters:

• mode (Literal['nearest', 'reflect', 'constant', 'mirror', 'wrap'])

• shape (Literal['disk', 'square', 'diamond'] | None)

• radius (int)

• cval (float)

mode

Determines how boundaries of the image are handled during processing. For instance, “reflect” can help minimize edge artifacts when analyzing colonies near the edge of the image by mirroring boundary pixels, while “constant” fills with a value (cval), which might highlight isolated colonies. Adjusting this can significantly affect how edge regions are interpreted.

Type:

Literal[“nearest”, “reflect”, “constant”, “mirror”, “wrap”]

shape

Specifies the shape of the structuring element used in morphological operations. For instance, “disk” simulates circular neighborhood which works well for circular colonies, whereas “square” gives a grid-like neighborhood. This can directly impact how structures are identified or segmented.

Type:

Literal[“disk”, “square”, “diamond”] | None

radius

Size of the structuring element. Larger radii result in broader neighborhoods being considered, which may smooth or connect distant colonies, while smaller radii preserve finer details but may miss larger structural relationships. Only if shape is not None.

Type:

int

cval

Value used to fill borders when mode is set to “constant”. This directly affects colony recognition at the edges; for example, setting a high cval compared to colony intensity might obscure colonies near the borders.

Type:

float

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