phenotypic.detect.ManualGridDetector#

class phenotypic.detect.ManualGridDetector(coord1: tuple[int, int] = (0, 0), coord2: tuple[int, int] | None = None, shape: Literal['square', 'diamond', 'disk'] = 'disk', width: int = 15)[source]

Bases: GridObjectDetector, FootprintMixin

Detect colonies by stamping footprint masks at evenly-spaced grid positions derived from reference coordinates.

Compute a regular grid of colony positions from one or two user-supplied pixel coordinates, then stamp a morphological footprint at each position to produce objmask and objmap. This purely geometric approach bypasses intensity-based detection entirely, making it ideal when colony positions follow a known pattern but automatic grid detection is unreliable. For a full comparison see Detection Strategies Compared.

In one-coordinate mode, coord1 defines the top-left cell centre and symmetric margins are assumed: row spacing = (H - 2*y) / (nrows - 1), column spacing = (W - 2*x) / (ncols - 1). In two-coordinate mode, coord1 and coord2 define cells (0, 0) and (1, 1); row and column spacing are derived from their difference and extrapolated across all grid cells.

Parameters:

  • coord1 (tuple[int, int]) – (y, x) pixel position of the top-left grid cell centre (row 0, column 0). This is the anchor point from which all other positions are calculated. Default (0, 0).

  • coord2 (tuple[int, int] | None) – Optional (y, x) pixel position of the diagonally adjacent cell (row 1, column 1). When provided, row and column spacing are derived from the difference between coord2 and coord1. When omitted, spacing is computed from image dimensions assuming symmetric margins.

  • shape (Literal['square', 'diamond', 'disk']) – Morphological footprint shape stamped at each grid position. "disk" (default) preserves round colony geometry. "square" covers rectangular well regions. "diamond" offers a compromise between the two.

  • width (int) – Diameter of the footprint in pixels (default 15). Larger values cover more area per grid cell; smaller values produce tighter, more precise masks. Typical range: 5–50, depending on image resolution and colony size.

Returns:

Input image with objmask set to the union of all stamped footprints and objmap set to uniquely labelled regions (1-indexed, row-major order).

Return type:

GridImage

Raises:

GridImageInputError – If a plain Image is passed instead of a GridImage.

Best For:

  • Plates where automatic grid finders fail due to low contrast, missing wells, or non-standard plate formats.

  • Template-based detection when colony positions are known a priori from plate layout metadata or robotic spotting coordinates.

  • Generating ground-truth masks for testing or validating other detection pipelines.

  • Quick prototyping when full detection is unnecessary and grid geometry is well-characterised.

Consider Also:

  • RoundPeaksDetector when grid positions can be inferred automatically from intensity profiles.

  • WatershedDetector when colonies are not on a regular grid and must be separated by region growing.

  • InoculumDetector when inoculation sites must be detected from image content rather than geometric templates.

See also

Tutorial 2: Detecting Colonies

Step-by-step tutorial for basic colony detection.

How To: Choose a Detection Algorithm

Guide for selecting the right detector for your plate images.

Detection Strategies Compared

In-depth comparison of all detection strategies.

Methods

__init__

apply

Detect colonies using sinusoidal cross-correlation grid estimation.

napari

Interactively pick 1--2 anchor coordinates using a napari viewer.

widget

Return (and optionally display) the root widget.
napari(image: GridImage) → ManualGridDetector[source]

Interactively pick 1–2 anchor coordinates using a napari viewer.

Opens a blocking napari viewer displaying the plate image layers (RGB, grayscale, detection matrix). Click up to two points to define the grid anchor positions, then click Confirm in the dock widget. The picked coordinates update coord1 and coord2 on this detector instance.

Parameters:

image (GridImage) – The GridImage to display for coordinate selection.

Returns:

Self, for method chaining.

Return type:

ManualGridDetector

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

Detect colonies using sinusoidal cross-correlation grid estimation.

This method performs the core detection workflow: 1. Extract grid dimensions (if GridImage) 2. Threshold the detection matrix with adaptive kernel sizing 3. Remove noise if requested 4. Label connected components 5. Determine or estimate grid edges (via sinusoidal cross-correlation) 6. Assign dominant colonies to grid cells 7. Create final object map

Parameters:

image – Image object to process. Can be a regular Image or GridImage.

Returns:

The processed image with updated objmask and objmap.

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