phenotypic.enhance.GaussianSubtract#

class phenotypic.enhance.GaussianSubtract(sigma: float = 50.0, mode: str = 'reflect', cval: float = 0.0, truncate: float = 4.0, preserve_range: bool = True)[source]#

Bases: ImageEnhancer

Background correction by Gaussian subtraction.

Estimates a smooth background via Gaussian blur and subtracts it from the image. For agar plate colony analysis, this removes gradual illumination gradients (vignetting, agar thickness, scanner shading) while retaining sharp colony features, improving downstream thresholding and edge detection.

Use cases (agar plates): - Correct uneven lighting across plates or across scan beds. - Enhance visibility of dark colonies on bright agar by flattening the

background.

  • Normalize batches captured with varying exposure/illumination profiles.

Tuning and effects: - sigma: Sets the spatial scale of the background. Choose a value larger than

the typical colony diameter so colonies are not treated as background. Too small will subtract colony signal and can invert contrast around edges.

  • mode/cval: Controls border handling; ‘reflect’ often avoids rim artifacts on circular plates. ‘constant’ may require matching cval to background.

  • truncate: Extent of the Gaussian in standard deviations; rarely needs change.

  • preserve_range: Keep original intensity range after filtering; useful when subsequent steps assume the same data range/bit depth.

Caveats: - If sigma is too low, colonies can be attenuated or produce halos. - Very large sigma can oversmooth and retain large shadows or plate rim effects. - Background subtraction may re-center intensities around zero; ensure later

steps handle negative values or re-normalize if needed.

Parameters:
sigma#

Gaussian std for background scale; use > colony diameter.

Type:

float

mode#

Border handling: ‘reflect’, ‘constant’, ‘nearest’, ‘mirror’, ‘wrap’.

Type:

str

cval#

Fill value if mode=’constant’.

Type:

float

truncate#

Gaussian support in standard deviations.

Type:

float

preserve_range#

Preserve input value range during filtering.

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__(sigma: float = 50.0, mode: str = 'reflect', cval: float = 0.0, truncate: float = 4.0, preserve_range: bool = True)[source]#
Parameters:

  • sigma (float) – Background scale. Set larger than colony diameter so colonies are preserved while slow illumination is removed.

  • mode (str) – Border handling; ‘reflect’ reduces artificial rims on plates.

  • cval (float) – Fill value when mode=’constant’.

  • truncate (float) – Gaussian support in standard deviations (advanced).

  • preserve_range (bool) – Keep the original intensity range; useful if subsequent steps or measurements assume a specific scaling.

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