torchcell.sga.quantify_plate_image

quantify_plate_image(path: str, n_rows: int = 14, n_cols: int = 22, overlay_path: str | None = None, circularity_flag: float = 0.8, polarity: str = 'auto', grid_mode: str = 'roi', multi_area_frac: float = 0.3, multi_min_area: int = 25, seg_method: str = 'threshold', return_masks: bool = False, gel_detect: bool = True, edge_policy: str = 'flag', node_tol: float = 0.55) → DataFrame

Quantify colonies on a standardized plate image into a gitter-style table.

polarity: ‘auto’ (default) detects bright-colony dark-field vs dark-colony transillumination from the agar level; force with ‘bright’/’dark’.

grid_mode: ‘roi’ (default) segments the plate first and looks for colonies inside it — correct for a dark-field capture where the plate is the brightest object. Use ‘lattice’ for a BACKLIT capture (plate on a light panel), where plate and panel are equally bright and plate segmentation fails; the colony lattice then defines the region itself. See _detect_blobs_backlit.

multi_area_frac / multi_min_area: a cell is flagged ‘M’ (multiple colonies -> rejected downstream) when it holds a second blob of at least multi_min_area px AND at least multi_area_frac of the kept blob’s area. Competing colonies both grow smaller, so such a cell is not a faithful fitness readout.

seg_method (backlit grid_mode='lattice' only): ‘threshold’ (default) is the border/bright-referenced intensity cut; ‘watershed’ is a marker-controlled watershed (colony-center seed + agar seed, flooding the intensity gradient) that keeps a glare-lit dome inside the colony and separates touching colonies, at the cost of leaking where a dark plate-frame stripe abuts a colony with no agar gap. The dark-field grid_mode='roi' path always uses the median threshold.

Returns columns: row, col, size, circularity, flags, cx, cy — where cx, cy are the MEASURED colony centroids (not the grid node), so an overlay drawn at them lands on the real colony. flags is a string of single-char codes: ‘C’ low circularity, ‘S’ spill/gash, ‘M’ multiple colonies in the cell.