phenotypic.correction.GridAligner#

class phenotypic.correction.GridAligner(axis: int = 0, mode: str = 'edge')[source]

Bases: GridCorrector

Correct grid rotation by aligning colony centroids to row or column axes.

Compute the optimal rotation angle from linear regression of colony centroid positions along the chosen axis, then rotate the entire image to minimize angular misalignment. Re-detection of objects after alignment is strongly recommended because pixel coordinates shift.

For algorithm details, see Grid vs Non-Grid Detection.

Parameters:

  • axis (int) – Alignment axis. 0 aligns rows (row-wise regression on column centroid positions); 1 aligns columns. Default: 0.

  • mode (str) – Edge-fill mode passed to the rotation function. 'edge' replicates border pixels; 'constant' fills with zeros. Default: 'edge'.

Returns:

Input image rotated so that colony centroids align with the specified axis. All image components are transformed.

Return type:

GridImage

Raises:

ValueError – If axis is not 0 or 1.

Best For:

  • Arrayed plates scanned at a slight angle where grid rows or columns are not axis-aligned.

  • High-throughput imaging setups with inconsistent plate orientation between scans.

  • Pre-processing before grid-based measurement to ensure accurate row and column assignment.

Consider Also:

  • ImagePadder to add safety margins before rotation so corner colonies are not clipped.

  • ImageCropper to remove excess background after alignment.

See also

How To: Correct Grid Rotation for a visual walkthrough of grid alignment on real plate images.

Methods

__init__

apply

Calculates the optimal rotation angle and applies it to a grid image for alignment along the specified axis.

widget

Return (and optionally display) the root widget.
__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: GridImage, inplace=False) → GridImage

Calculates the optimal rotation angle and applies it to a grid image for alignment along the specified axis.

The method performs alignment of a GridImage object along either nrows or columns based on the specified axis. It calculates the linear regression slope and intercept for the axis, determines geometric properties of the grid vertices, and computes rotation angles needed to align the image. The optimal angle is found by minimizing the error across all computed angles, and the image is rotated accordingly.

Raises:

ValueError – If the axis is not 0 (row-wise) or 1 (column-wise).

Parameters:

image (ImageGridHandler) – The arr grid image object to be aligned.

Returns:

The rotated grid image object after alignment.

Return type:

ImageGridHandler

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