phenotypic.correction.StableDenoise#

class phenotypic.correction.StableDenoise(block_size: int = 8, stage_arg: Literal['all_stages', 'hard_thresholding'] = 'all_stages', *, gain: float = 1.0, mu: float = 0.0, sigma: float = 0.0, scale_factor: float | None = None)[source]

Bases: ImageCorrector

Denoise grayscale channels using variance-stabilized BM3D collaborative filtering.

Combine the Generalized Anscombe Transform (GAT) with BM3D denoising in a single corrector step. The GAT stabilizes Poisson-Gaussian noise variance so that BM3D operates optimally, then the inverse GAT restores the original intensity scale. Writing through the gray accessor triggers a detect_mat reset, so downstream reads reflect the denoised result.

For algorithm details, see What Enhancement Actually Does.

Parameters:

  • block_size (int) – BM3D patch side length in pixels. Larger values capture more context but increase computation. Default: 8.

  • stage_arg (Literal['all_stages', 'hard_thresholding']) – Processing stages. 'all_stages' runs hard thresholding followed by Wiener filtering for best quality; 'hard_thresholding' is faster. Default: 'all_stages'.

  • gain (float) – Camera gain in electrons per ADU. Default: 1.0.

  • mu (float) – Read-noise mean (baseline offset). Default: 0.0.

  • sigma (float) – Read-noise standard deviation. 0.0 assumes pure Poisson noise, appropriate for most plate scanners. Default: 0.0.

  • scale_factor (float | None) – Multiplier converting normalized [0, 1] data to photon counts. None auto-detects from image bit depth. Default: None.

Returns:

Input image with grayscale channel denoised via the accessor cascade. RGB is unchanged.

Return type:

Image

Raises:

ValueError – If gain is not positive, sigma is negative, scale_factor is not positive, or stage_arg is not a recognized value.

Best For:

  • Low-light or high-ISO plate images with photon-counting (Poisson-Gaussian) noise.

  • Improving intensity measurement accuracy before colony size or opacity quantification.

  • CCD/CMOS scanned plates where mixed noise models apply.

Consider Also:

  • BayesShrinkCorrector when all components (including RGB) need denoising simultaneously.

  • BM3DDenoiser for enhancer-only BM3D on the detection matrix without modifying grayscale.

  • VisuShrinkCorrector for a faster wavelet-based alternative when Poisson noise modelling is not required.

References

[1] M. Makitalo and A. Foi, “Optimal inversion of the generalized Anscombe transformation for Poisson-Gaussian noise,” IEEE Trans. Image Process., vol. 22, no. 1, pp. 91–103, Jan. 2013.

See also

/how_to/notebooks/correct_color_cast for combining denoising with color correction workflows.

Methods

__init__

Initialize GAT-stabilized BM3D corrector for gray and detect_mat.

apply

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

widget

Return (and optionally display) the root widget.
__init__(block_size: int = 8, stage_arg: Literal['all_stages', 'hard_thresholding'] = 'all_stages', *, gain: float = 1.0, mu: float = 0.0, sigma: float = 0.0, scale_factor: float | None = None)[source]

Initialize GAT-stabilized BM3D corrector for gray and detect_mat.

Parameters:

  • block_size (int) – BM3D patch size. Default 8.

  • stage_arg (Literal["all_stages", "hard_thresholding"]) – Denoising stages. ‘all_stages’ gives best quality; ‘hard_thresholding’ is faster.

  • gain (float) – Camera gain in electrons per ADU. Default 1.0.

  • mu (float) – Read noise mean (baseline offset). Default 0.0.

  • sigma (float) – Read noise standard deviation. Default 0.0 (pure Poisson noise).

  • scale_factor (float | None) – Converts normalized [0,1] data to counts. None (default) auto-detects from image metadata.

__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: Image, inplace: bool = False) → Image

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