phenotypic.correction.ImagePadder#

Bases: ImageCorrector

Extend image dimensions by adding pixels to any combination of edges.

Pad the image on the left, right, top, and/or bottom using a configurable fill mode. All image components (RGB, gray, detect_mat, objmap) are padded in sync; the object map is always zero-padded to preserve label integrity. When applied to a GridImage, grid structure is preserved and positions are recalculated automatically.

For usage context, see How To: Crop and Pad Images for Batch Consistency.

Parameters:

left (int | None) – Pixels to add on the left edge. None means no padding. Typical range: 50–200. Default: None.
right (int | None) – Pixels to add on the right edge. None means no padding. Typical range: 50–200. Default: None.
top (int | None) – Pixels to add on the top edge. None means no padding. Typical range: 50–200. Default: None.
bottom (int | None) – Pixels to add on the bottom edge. None means no padding. Typical range: 50–200. Default: None.
mode (str) – Fill strategy passed to np.pad. Accepted values: 'constant', 'reflect', 'edge', 'symmetric', 'wrap', 'linear_ramp', 'maximum', 'mean', 'median', 'minimum', 'empty'. 'edge' is safest for colony analysis; 'reflect' reduces convolution boundary artifacts. Default: 'constant'.
constant_value (int | float) – Fill value when mode='constant'. 0 for black borders, 255 for white. Default: 0.

Returns:

Input image with all components padded by the specified amounts. GridImage grid positions are recalculated.

Return type:

Image

Raises:

ValueError – If any padding value is negative.
ValueError – If mode is not a valid np.pad mode.

Best For:

Adding safety margins before rotation so corner colonies are not clipped.
Standardizing image dimensions across a batch for pipelines that require uniform size.
Creating border space when colonies grow near plate edges, improving grid detection accuracy.

Consider Also:

ImageCropper when the image needs to be reduced rather than extended.
GridAligner for correcting plate rotation after padding.

See also

How To: Crop and Pad Images for Batch Consistency for a visual walkthrough of padding and cropping plate images. How To: Correct Grid Rotation for combining padding with rotation correction.

Methods

`__init__`	Initialize an ImagePadder with pixel margins to add on each edge.
`apply`	Applies the operation to an image, either in-place or on a copy.
`widget`	Return (and optionally display) the root widget.

Initialize an ImagePadder with pixel margins to add on each edge.

Creates a padder that adds the specified number of pixels to each edge of the image. All margin parameters are optional and default to None (no padding from that edge).

Parameters:

left (int | None, optional) – Pixels to add on left edge. Must be non-negative. If None, no left padding (equivalent to 0). Defaults to None.
right (int | None, optional) – Pixels to add on right edge. Must be non-negative. If None, no right padding (equivalent to 0). Defaults to None.
top (int | None, optional) – Pixels to add on top edge. Must be non-negative. If None, no top padding (equivalent to 0). Defaults to None.
bottom (int | None, optional) – Pixels to add on bottom edge. Must be non-negative. If None, no bottom padding (equivalent to 0). Defaults to None.
mode (str, optional) – Padding mode for np.pad. Options include ‘constant’ (uniform value), ‘reflect’ (mirror at boundary), ‘edge’ (replicate edge pixels), ‘symmetric’ (symmetric reflection), ‘wrap’ (periodic), and others. Defaults to ‘constant’.
constant_value (int | float, optional) – Value for constant mode padding. Only used when mode=’constant’. Typical values: 0 for black (default), 255 for white. Defaults to 0.

Raises:

ValueError – If any padding parameter is negative. All padding margins must be non-negative integers (or None).
ValueError – If mode is not a valid np.pad mode.

Examples

Create a padder for symmetric margins:

>>> from phenotypic.correction import ImagePadder
>>> # Add 50 pixels to all four edges
>>> padder = ImagePadder(left=50, right=50, top=50, bottom=50)

Create a padder for asymmetric margins:

>>> from phenotypic.correction import ImagePadder
>>> # Add padding on top and right, keep left and bottom minimal
>>> padder = ImagePadder(top=100, right=75, left=0, bottom=0)

Create a padder with reflection to avoid artifacts:

>>> from phenotypic.correction import ImagePadder
>>> padder = ImagePadder(
...     left=80, right=80, top=80, bottom=80,
...     mode='reflect'
... )
>>> # Reflection preserves edge patterns, good for convolutions

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

phenotypic.correction.ImagePadder#

This Page