itasc.segmentation.cell_label_icm

Unary-only cell label segmentation (contour-aware geodesic Voronoi).

  • initialize_icm: compute geodesic unary costs from the contour/foreground cost field and assign each foreground pixel to its nearest nucleus seed (per-pixel argmin). Returns a CellICMState caching the unary and a hard-anchored initial label array.

  • assemble_cost_field: build the per-frame geodesic cost field the walk traverses (shared with the cell widget’s preview).

  • commit_labels: write the label array to a TIFF file.

The spatial/temporal Potts pairwise terms and the iterated-conditional-modes refinement sweep have been removed — with the pairwise weights zeroed the ICM optimum is exactly the argmin of the unary, so the initialisation is the answer.

Functions

assemble_cost_field(contours_t, fg_t, ...[, ...])

Per-pixel geodesic cost over a single frame's foreground mask.

balance_strength_to_weights(balance, ...)

Map the (balance, feature_strength) knobs to raw cost-field weights.

commit_labels(labels, output_path)

Write label array to TIFF.

initialize_icm(nuc_tracks, fg_mask, ...[, ...])

Compute geodesic unaries and build labels (per-pixel argmin).

Classes

CellICMState(fg_mask, nuc_tracks, label_ids)

Cached energy-landscape data for the unary segmentation.

CellLabelICMParams([balance, ...])

Parameters for the unary-only geodesic cell segmentation.
class itasc.segmentation.cell_label_icm.CellLabelICMParams(balance=1.0, feature_strength=4.0, n_workers=1)[source]

Bases: object

Parameters for the unary-only geodesic cell segmentation.

Parameters:
balance: float = 1.0

1 = pure contour, 0 = pure foreground. See balance_strength_to_weights().

Type:

Contour↔foreground split r in [0, 1]

feature_strength: float = 4.0

Overall feature weight s >= 0 relative to the fixed base cost of 1: how strongly contour/foreground bend the walk away from a plain geodesic distance Voronoi. 0 = pure distance Voronoi.

n_workers: int = 1

Parallel worker processes for geodesic unary computation. 1 = sequential. Values > 1 use fork-based multiprocessing to compute frames in parallel.

class itasc.segmentation.cell_label_icm.CellICMState(fg_mask, nuc_tracks, label_ids, unary_dense=None)[source]

Bases: object

Cached energy-landscape data for the unary segmentation.

Created by initialize_icm(). All arrays are stored as their solver-ready dtypes (float32 / uint32 / bool).

Parameters:
fg_mask: ndarray

(T, Y, X) bool — foreground mask (includes nucleus pixels).

nuc_tracks: ndarray

(T, Y, X) uint32 — nucleus track IDs (0 = no nucleus).

label_ids: ndarray

(K,) uint32 — sorted global set of label (track) IDs.

unary_dense: ndarray | None = None

Deprecated. Previously held the dense (T, Y, X, K) unary cost volume; initial labels are now computed with a streaming argmin (_argmin_init_from_dict()) so this is left None to avoid the multi-gigabyte allocation.

property shape: tuple[int, int, int]
property n_labels: int
itasc.segmentation.cell_label_icm.assemble_cost_field(contours_t, fg_t, alpha_unary, fg_scores_t=None, gamma_unary=0.0)[source]

Per-pixel geodesic cost over a single frame’s foreground mask.

cost = 1 + alpha_unary * contour + gamma_unary * (1 - fg_score) inside the mask, inf elsewhere. This is the exact field the geodesic walk traverses; sharing it between _compute_frame_geodesic() and the cell widget’s live preview guarantees the preview shows the same array the solver uses rather than a re-derivation.

Return type:

ndarray

Parameters:
itasc.segmentation.cell_label_icm.balance_strength_to_weights(balance, feature_strength)[source]

Map the (balance, feature_strength) knobs to raw cost-field weights.

The geodesic cost field is 1 + alpha * contour + gamma * (1 - fg_score). Because the final labels come from a per-pixel argmin over geodesic distances, multiplying the whole field by any positive constant leaves the result unchanged — overall scale is a free gauge. That leaves exactly two observable degrees of freedom, exposed here as:

  • balance (r in [0, 1]) — the contour↔foreground split (1 = pure contour, 0 = pure foreground).

  • feature_strength (s >= 0) — how strongly either feature bends the walk away from a plain distance Voronoi, relative to the fixed base of 1 (0 = pure distance Voronoi).

with alpha = s * r and gamma = s * (1 - r).

Return type:

tuple[float, float]

Parameters:
itasc.segmentation.cell_label_icm.initialize_icm(nuc_tracks, fg_mask, contours, params, *, foreground_scores=None, cache_dir=None, progress_cb=None)[source]

Compute geodesic unaries and build labels (per-pixel argmin).

Parameters:
Return type:

tuple[CellICMState, ndarray]

Returns:

  • state (CellICMState)

  • init_labels ((T, Y, X) uint32)

itasc.segmentation.cell_label_icm.commit_labels(labels, output_path)[source]

Write label array to TIFF.

Labels are stored as uint16 when they fit (compact, backward compatible) and promoted to uint32 otherwise. Casting a track id above 65535 down to uint16 would silently wrap and merge distinct cells, so the dtype is chosen from the actual maximum label.

Return type:

None

Parameters: