phenotypic.enhance.CoherenceEnhancingDiffusion

class phenotypic.enhance.CoherenceEnhancingDiffusion(num_iter: int = 20, sigma: float = 1.5, rho: float | None = None, dt: float = 0.1, *, alpha: float = 0.001, C: float = 99.0)

Bases: ImageEnhancer

Enhance filamentous structures via anisotropic coherence-enhancing diffusion.

Smooths detect_mat preferentially along coherent structures (lines, ridges, edges) while preserving boundaries perpendicular to them. Uses the structure tensor to estimate local orientation and applies directional diffusion that follows elongated features such as fungal hyphae, streak inoculations, and branching colony morphologies.

For algorithm details, see What Enhancement Actually Does.

Parameters:

• num_iter (int) – Number of diffusion iterations. Typical range: 5–100. Small values (5–10) give subtle enhancement; medium values (15–30) are typical; large values (50–100) provide heavy smoothing. Default: 20.

• sigma (float) – Noise/derivative scale for Gaussian gradient computation. Match to the width of structures to enhance. Typical range: 0.5–5.0. Default: 1.5.

• rho (float | None) – Integration scale for structure tensor smoothing. Must be >= sigma. None (default) uses sigma (single-scale mode). Typical values: 2–3x sigma.

• dt (float) – Time step per iteration. Must satisfy the 2D forward-Euler stability bound (<=0.125). Typical range: 0.05–0.125. Default: 0.1.

• alpha (float) – Minimum diffusivity (0 < alpha < 1). Small values (0.001) maximize anisotropy; larger values (0.01–0.1) add isotropic smoothing. Default: 0.001.

• C (float) – Contrast percentile (0 < C <= 100) for the adaptive coherence threshold. Higher values restrict anisotropy to the most coherent structures. Default: 99.

Returns:

Input image with detect_mat smoothed along coherent structures. rgb and gray are unchanged.

Return type:

Image

Best For:

• Filamentous fungal hyphae (Aspergillus, Penicillium, molds) where branching structures need enhancement.

• Streak inoculation patterns where colonies grow along lines.

• Preprocessing before ridge detection (Frangi, Sato, Meijering) to reduce noise without losing tubular structures.

• Faint elongated features in low-contrast or noisy scans.

Consider Also:

• BilateralDenoise for isotropic edge-preserving denoising of round colonies without directional features.

• SatoRidgeFilter for direct ridge detection without a diffusion preprocessing step.

• MeijeringRidgeFilter for detecting very fine neurite-like filaments.

References

[1] J. Weickert, “Coherence-enhancing diffusion filtering,” Int. J. Comput. Vis., vol. 31, no. 2/3, pp. 111–127, Apr. 1999.

See also

Tutorial 3: Enhancing Before Detection for a visual walkthrough of enhancement pipelines on plate images. What Enhancement Actually Does for background on anisotropic diffusion and structure tensor analysis.

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__(num_iter: int = 20, sigma: float = 1.5, rho: float | None = None, dt: float = 0.1, *, alpha: float = 0.001, C: float = 99.0)

Parameters:

• num_iter (int) – Number of diffusion iterations. Controls the total amount of smoothing applied. Small values (5-10) give subtle enhancement; medium values (15-30) are typical; large values (50-100) provide heavy smoothing. Computational cost scales linearly with iterations. Recommended: 20 for balanced enhancement.

• sigma (float) – Noise/derivative scale (Gaussian derivative σ). Controls the scale at which image gradients are computed for orientation estimation. Match to the width of structures you want to enhance: ~1.5 for fine hyphae (~3px wide), ~3.0 for coarser structures. Recommended: 1.5.

• rho (float | None) – Integration scale for structure tensor smoothing. Controls the neighborhood over which gradient products are averaged. Must be >= sigma. When None (default), equals sigma (single-scale mode). Larger values produce smoother orientation fields. Typical: 2-3x sigma.

• dt (float) – Time step for each diffusion iteration. Must satisfy the 2D forward-Euler stability bound of 1/8 (0.125). Smaller values require more iterations for equivalent smoothing. Recommended: 0.1 for stable, efficient diffusion.

• alpha (float) – Minimum diffusivity parameter (0 < alpha < 1). Ensures some diffusion even in uniform regions, preventing numerical issues. Small values (0.001) maximize anisotropy; larger values (0.01-0.1) add more isotropic smoothing. Recommended: 0.001 for strong directional bias.

• C (float) – Contrast percentile for the diffusivity function (0 < C <= 100). The Cth percentile of the coherence histogram (lambda1 - lambda2)^2 from the original image is used as the contrast threshold, adapting to image content. Higher values restrict anisotropy to the most coherent structures. Default: 99.

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