phenotypic.enhance.SubtractGaussian#

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

Bases: ImageEnhancer

Remove background from detect_mat by subtracting a Gaussian-blurred estimate.

Estimates a smooth background via Gaussian blur and subtracts it, removing gradual illumination gradients (vignetting, agar thickness, scanner shading) while retaining sharp colony features. Improves downstream thresholding and edge detection.

For algorithm details, see What Enhancement Actually Does.

Parameters:

  • sigma (float) – Gaussian standard deviation defining the background scale. Must be larger than the typical colony diameter. Typical range: 20–100. Default: 50.0.

  • mode (str) – Border handling. Accepted values: 'reflect' (default), 'constant', 'nearest', 'mirror', 'wrap'.

  • cval (float) – Fill value when mode='constant'. Default: 0.0.

  • truncate (float) – Gaussian support in standard deviations. Default: 4.0.

  • preserve_range (bool) – Preserve the input value range during filtering. Default: True.

  • n_iter (int) – Number of successive subtraction passes. Multiple passes remove residual background from complex gradients. Typical range: 1–3. Default: 1.

Returns:

Input image with detect_mat background-subtracted and clipped to [0, 1]. rgb and gray are unchanged.

Return type:

Image

Best For:

  • Correcting uneven lighting across plates or scan beds.

  • Flattening background to enhance dark colonies on bright agar.

  • Normalizing batches captured with varying exposure or illumination profiles.

Consider Also:

  • SubtractRollingBall for parabolic background estimation that adapts to non-Gaussian intensity ramps.

  • OpeningSubtractBg for faster morphological background subtraction in high-throughput pipelines.

  • BilateralDenoise when the primary issue is noise rather than illumination gradients.

See also

Tutorial 3: Enhancing Before Detection for a visual walkthrough of background subtraction on plate images. What Enhancement Actually Does for background on illumination correction strategies.

Methods

__init__

apply

Applies the operation to an image, either in-place or on a copy.

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, n_iter: int = 1)[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.

  • n_iter (int) – Number of successive subtraction passes. Must be >= 1. One pass (default) removes a single background estimate. Multiple passes (2+) iteratively subtract residual background, useful for complex or multi-scale illumination gradients.

__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

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.

This Page