phenotypic.enhance.CLAHE#

class phenotypic.enhance.CLAHE(Contrast Limited Adaptive Histogram Equalization)[source]#

Bases: ImageEnhancer

Applies adaptive histogram equalization while limiting local contrast amplification to control noise. For colony images on solid-media agar plates, this operation is helpful when illumination is uneven (vignetting, shadows from lids) or when colonies are low-contrast/translucent. By boosting local contrast tile-by-tile, faint colonies become easier to separate from agar background in later thresholding or edge-based steps.

Use cases (agar plates): - Improve visibility of small, faint, or translucent colonies that blend

into agar.

  • Compensate for gradual illumination roll-off across the plate or scanner/lens vignetting.

  • Preconditioning before global/otsu thresholding to reduce sensitivity to global intensity shifts.

Tuning and effects: - kernel_size (tile size): Smaller tiles emphasize very local contrast and

can reveal tiny colonies, but may also accentuate agar texture and noise. Larger tiles produce smoother results and are safer for noisy images. If left as None, a size proportional to the image dimensions is chosen.

  • clip_limit: Controls how much local contrast is allowed. Lower values suppress noise amplification and halos but may leave faint colonies under- enhanced. Higher values make colonies pop more strongly but can create ringing around dust, condensation droplets, or plate edges.

Caveats: - Can amplify non-biological artifacts (scratches, dust, glare); consider a

mild blur or artifact suppression before CLAHE if this occurs.

  • Different tiles adjust differently; ensure consistent parameters across a batch to avoid biasing downstream measurements.

  • Excessive enhancement may distort intensity-based phenotypes (e.g., pigment quantification). Prefer using it only in the enh_gray pipeline channel.

Parameters:

  • kernel_size (int | None)

  • clip_limit (float)

kernel_size#

Tile size for local equalization. None selects an automatic size based on image dimensions.

Type:

int | None

clip_limit#

Normalized contrast limit per tile; smaller values reduce amplification, larger values increase it. Default 0.01.

Type:

float

Methods

__init__

apply

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

dispose_widgets

Drop references to the UI widgets.

sync_widgets_from_state

Push internal state into widgets.

widget

Return (and optionally display) the root widget.
__init__(kernel_size: int | None = None, clip_limit: float = 0.01)[source]#
Parameters:

  • kernel_size (int | None) – Tile size for adaptive equalization. Smaller tiles enhance very local contrast (revealing tiny colonies) but can amplify agar texture; larger tiles produce smoother, gentler effects. None selects an automatic size based on image dimensions.

  • clip_limit (float) – Maximum local contrast amplification. Lower values reduce noise/halo amplification; higher values make faint colonies stand out more but can emphasize dust or condensation.

__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

dispose_widgets() → None#

Drop references to the UI widgets.

Return type:

None

sync_widgets_from_state() → None#

Push internal state into widgets.

Return type:

None

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.