phenotypic.enhance.HomomorphicFilter#

class phenotypic.enhance.HomomorphicFilter(sigma: float = 200.0, gamma_low: float = 0.5, gamma_high: float = 1.5, eps: float = 1e-06)[source]

Bases: ImageEnhancer

Correct uneven illumination in detect_mat using frequency-domain filtering.

Separates illumination (low-frequency) and reflectance (high-frequency) components in the log domain, applies differential gains to suppress brightness gradients while boosting colony detail, then returns to the linear domain. Particularly effective for plates with vignetting, scanner lighting bands, or shadow gradients.

For how enhancement fits into the pipeline, see What Enhancement Actually Does.

Parameters:

  • sigma (float) – Gaussian sigma for illumination/reflectance cutoff. Controls the spatial scale of the estimated illumination field. Must be large enough that only the gradient is captured, not individual colonies. Typical range: 40–300 (resolution-dependent). Default: 200.0.

  • gamma_low (float) – Gain for illumination component. Values < 1.0 suppress illumination variation. Typical range: 0.3–0.8. Default: 0.5.

  • gamma_high (float) – Gain for reflectance component. Values > 1.0 enhance colony contrast and surface detail. Typical range: 1.0–2.5. Default: 1.5.

  • eps (float) – Small constant to avoid log(0). Rarely needs adjustment. Default: 1e-6.

Returns:

Input image with detect_mat illumination-corrected and clipped to [0.0, 1.0]. rgb and gray are unchanged.

Return type:

Image

Raises:

ValueError – If sigma is not positive.

Best For:

  • Plates with visible vignetting or radial brightness falloff.

  • Flatbed scanner images with horizontal brightness bands.

  • Uneven agar thickness causing variable background brightness.

  • Pre-conditioning before global thresholding on unevenly lit plates.

Consider Also:

  • SubtractGaussian for a simpler spatial-domain background subtraction when the gradient is smooth.

  • CLAHE when the problem is local contrast rather than large-scale illumination.

  • SubtractRollingBall for morphological background estimation.

See also

How To: Enhance Low-Contrast Images for a comparison of contrast and illumination correction methods.

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 = 200.0, gamma_low: float = 0.5, gamma_high: float = 1.5, eps: float = 1e-06)[source]
Parameters:

  • sigma (float) – Gaussian sigma for the illumination/reflectance cutoff. Larger values capture broader illumination gradients. Start with a value several times the largest colony diameter.

  • gamma_low (float) – Gain for low frequencies (illumination). < 1 suppresses illumination variation; 1.0 leaves it unchanged.

  • gamma_high (float) – Gain for high frequencies (reflectance). > 1 enhances colony detail; 1.0 leaves it unchanged.

  • eps (float) – Offset to avoid log(0). Rarely needs adjustment.

__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