phenotypic.enhance.BilateralDenoise#

class phenotypic.enhance.BilateralDenoise(sigma_color: float | None = None, sigma_spatial: float = 15, *, win_size: int | None = None, mode: str = 'constant', cval: float = 0, clip: bool = True)[source]

Bases: ImageEnhancer

Denoise detect_mat with edge-preserving bilateral filtering.

Averages pixel values based on both spatial proximity and intensity similarity, preserving sharp colony boundaries while smoothing uniform regions such as agar background. Effectively removes scanner noise, agar grain, dust speckles, and condensation artifacts without blurring colony edges.

For algorithm details, see What Enhancement Actually Does.

Parameters:

  • sigma_color (float | None) – Intensity similarity weighting. Small values (0.02–0.05) preserve subtle boundaries; medium values (0.05–0.15) balance denoising and edge preservation; large values (0.2–0.5) smooth aggressively. None (default) auto-estimates from image statistics.

  • sigma_spatial (float) – Spatial distance weighting in pixels. Small values (1–5) apply local denoising; medium values (10–20) smooth regionally; large values (30–50) smooth wide areas. Keep below the minimum colony diameter. Default: 15.

  • win_size (int | None) – Window size for filter computation. None (default) auto-calculates from sigma_spatial.

  • mode (str) – Boundary handling. Accepted values: 'constant', 'edge', 'symmetric', 'reflect', 'wrap'. Default: 'constant'.

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

  • clip (bool) – Clip output to [0, 1]. Default: True. Set to False when using with variance-stabilizing transforms (e.g., GAT).

Returns:

Input image with detect_mat smoothed by bilateral filtering. rgb and gray are unchanged.

Return type:

Image

Best For:

  • Noisy or grainy agar scans from high-ISO photography or old scanners.

  • Plates with surface condensation, dust speckles, or uneven agar texture.

  • Preprocessing before thresholding when colony edges must remain sharp.

  • Low-quality captures where colony morphology must be preserved.

Consider Also:

  • NonLocalMeansDenoiser for stronger denoising of repetitive textures at higher computational cost.

  • BM3DDenoiser for state-of-the-art structured noise removal.

  • SubtractGaussian when the primary problem is illumination gradients rather than pixel-level noise.

See also

Tutorial 3: Enhancing Before Detection for a visual walkthrough of denoising pipelines on plate images. How To: Denoise Low-Light Images for edge-preserving denoising strategies on low-light plate images.

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_color: float | None = None, sigma_spatial: float = 15, *, win_size: int | None = None, mode: str = 'constant', cval: float = 0, clip: bool = True)[source]
Parameters:

  • sigma_color (float | None) – Standard deviation for grayvalue/color similarity. Controls how permissive the filter is when averaging nearby pixels. Small values (0.02–0.05 for float images) enforce strict color matching, preserving edges but leaving more noise. Medium values (0.05–0.15) provide balanced denoising and edge preservation—recommended for most fungal colony imaging. Large values (0.2–0.5) aggressively average across brightness ranges, risking boundary blur. If None (default), automatically estimated from the standard deviation of the image. For uint8 images (0–255), scale values proportionally: 0.05 float corresponds roughly to 13 in uint8 scale. Recommended: leave as None for automatic estimation, or set to 0.08–0.12 for typical colony plates.

  • sigma_spatial (float) – Standard deviation for spatial distance in pixels. Controls the extent of the neighborhood influencing each pixel. Small values (1–5) apply highly local denoising, preserving fine texture. Medium values (10–20) smooth regionally without over-smoothing—suitable for general use. Large values (30–50) smooth broad areas, helpful for correcting illumination variations but risking loss of small colonies or merging of adjacent growth. Recommended: 15 for balanced results; adjust based on colony size (keep smaller than minimum colony diameter).

  • win_size (int | None) – Window size for bilateral filter computation. If None (default), automatically calculated as max(5, 2 * ceil(3 * sigma_spatial) + 1). Generally safe to leave as None; adjust only if you have specific performance or memory constraints.

  • mode (str) – How to handle image boundaries. Options: ‘constant’ (default, pad with cval), ‘edge’ (replicate edge), ‘symmetric’, ‘reflect’, ‘wrap’. ‘constant’ with cval=0 works well for agar plate backgrounds (black edges). ‘reflect’ mirrors edges, useful for non-border regions.

  • cval (float) – Constant fill value for boundaries when mode=’constant’. Default is 0 (black), appropriate for agar backgrounds.

  • clip (bool) – Whether to clip output to [0, 1] range. Default True. Set to False when using with variance-stabilizing transforms (e.g., GAT) that require preserving the original scale of transformed data.

__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