itasc.segmentation.cell_divergence_segmentation

Unary-only cell segmentation from cached divergence maps.

Chains the simplified cell pipeline validated in scripts/experiment_divergence_icm.py into a single, Qt-free helper so the cell widget can drive both its live single-frame preview and its full-stack run through the same code path:

  1. Map cleanup — local-mean residual + threshold on foreground and

    contours (the nucleus/atom residual scheme applied symmetrically to both maps).

  2. Temporal smooth — bidirectional signal-adaptive EMA on the cleaned

    contours (full-stack only; needs the whole movie).

  3. Foreground mask — (foreground_clean > fg_threshold) | (nucleus > 0).

  4. Segmentation — unary-only geodesic Voronoi: initialize_icm assigns

    each foreground pixel to its nearest nucleus seed through the contour-aware cost field (per-pixel argmin of the unary).

The divergence maps themselves (cell_contours.tif + cell_foreground.tif) are produced upstream by DivergenceMapsWidget; this helper only consumes them.

The returned CellDivergenceResult carries every intermediate plus the weighted cost field, so the widget can drop each into a preview layer without recomputing.

Functions

clean_and_smooth_contours(contours, params)

Full-stack contour cleanup + temporal smoothing — pipeline stages 1+2.

compute_cell_foreground(foreground, params)

Foreground cleanup + fill mask, independent of contours and the geodesic.

segment_cells_divergence(contours, ...[, ...])

Run the unary-only divergence pipeline and return all intermediates.

Classes

CellDivergenceParams([fg_window, ...])

Parameters for the unary-only divergence cell pipeline.

CellDivergenceResult(foreground_raw, ...)

All pipeline intermediates plus the final labels.

CellForegroundResult(foreground_raw, ...)

Foreground-path intermediates — pipeline stages 1 + 3, foreground only.
class itasc.segmentation.cell_divergence_segmentation.CellDivergenceParams(fg_window=51, fg_strength=0.0, fg_threshold=0.1, contour_window=51, contour_strength=1.0, contour_threshold=0.0, contour_norm_pct=99.0, memory_tau=0.0, memory_floor=0.01, balance=0.98, feature_strength=100.0, n_workers=4)[source]

Bases: object

Parameters for the unary-only divergence cell pipeline.

Defaults match the values that held across pos00/pos01 in the prototype.

Parameters:
fg_window: int = 51

Local-mean window for the foreground residual (px, forced odd).

fg_strength: float = 0.0

0 = raw sigmoid, 1 = full subtraction.

Type:

Foreground residual strength

fg_threshold: float = 0.1

Cleaned-foreground cutoff producing the fill mask (sigmoid scale).

contour_window: int = 51

Local-mean window for the contour residual (px, forced odd).

contour_strength: float = 1.0

0 = raw, 1 = full local-mean subtraction.

Type:

Contour residual strength

contour_threshold: float = 0.0

Noise floor on the normalized contour [0, 1]; below → 0.

contour_norm_pct: float = 99.0

Percentile of the positive contour signal mapped to 1.0 in [0, 1].

memory_tau: float = 0.0

EMA crossover (~the contour value you call “weak”). 0 = off.

memory_floor: float = 0.01

Minimum per-frame alpha; ghost half-life (~69 frames @ 0.01).

balance: float = 0.98

Contour↔foreground split r in [0, 1] (1 = pure contour). See balance_strength_to_weights().

feature_strength: float = 100.0

Overall feature weight s >= 0 relative to the base cost of 1.

n_workers: int = 4

Parallel workers for geodesic computation (compute only).

class itasc.segmentation.cell_divergence_segmentation.CellDivergenceResult(foreground_raw, foreground_clean, contours_raw, contours_clean, foreground_mask, cost_field, labels)[source]

Bases: object

All pipeline intermediates plus the final labels.

Arrays are (T, Y, X) for a full-stack run and (Y, X) for a single-frame (frame given) run.

Parameters:
foreground_raw: ndarray

Raw input foreground map (sigmoid).

foreground_clean: ndarray

Foreground after residual cleanup (sigmoid scale).

contours_raw: ndarray

Raw input contour map (positive divergence).

contours_clean: ndarray

Contours after residual + normalize + floor (and temporal smoothing for a full-stack run).

foreground_mask: ndarray

(foreground_clean > fg_threshold) | (nucleus > 0).

Type:

Fill territory

cost_field: ndarray

Weighted geodesic cost over the mask; inf outside.

labels: ndarray | None

Cell labels — the unary argmin (tracked nucleus IDs). None when the geodesic label assignment was skipped (with_labels=False).

class itasc.segmentation.cell_divergence_segmentation.CellForegroundResult(foreground_raw, foreground_clean, foreground_mask)[source]

Bases: object

Foreground-path intermediates — pipeline stages 1 + 3, foreground only.

Arrays are (T, Y, X) for a full-stack run and (Y, X) for a single-frame (frame given) run.

Parameters:
foreground_raw: ndarray

Raw input foreground map (sigmoid), clipped to [0, 1].

foreground_clean: ndarray

Foreground after residual cleanup (sigmoid scale).

foreground_mask: ndarray

(foreground_clean > fg_threshold) unioned with the nucleus seeds when nuc is supplied.

Type:

Fill territory

itasc.segmentation.cell_divergence_segmentation.clean_and_smooth_contours(contours, params)[source]

Full-stack contour cleanup + temporal smoothing — pipeline stages 1+2.

Returns the (T, Y, X) cleaned (residual → global-percentile normalize → floor) and, when memory_tau > 0 and there is more than one frame, temporally smoothed contour stack — exactly the contours_clean the full run feeds the segmenter.

The widget’s live preview computes this once over the whole movie, caches it, and slices the current frame back into segment_cells_divergence() via contours_clean_override so the previewed cost field / labels for a frame match the full run (which the per-frame path cannot, since both the global percentile and the bidirectional EMA need every frame).

Return type:

ndarray

Parameters:
itasc.segmentation.cell_divergence_segmentation.compute_cell_foreground(foreground, params, nuc=None, *, frame=None)[source]

Foreground cleanup + fill mask, independent of contours and the geodesic.

Drives the cell widget’s dedicated foreground-tuning stage. It runs exactly the foreground half of segment_cells_divergence() — the local-mean residual cleanup (stage 1) and the fill-mask threshold (stage 3) — with no contour cleanup, cost field, or geodesic walk, so foreground tuning stays cheap and does not require the contour map.

nuc is optional: when given, its seeds are unioned into the mask exactly as the full run does ((foreground_clean > fg_threshold) | (nuc > 0)), so the previewed mask matches the territory segmentation will fill; when None the mask is the bare threshold, letting the foreground be tuned before nucleus tracking exists.

frame selects a single frame (2-D result); None processes the whole stack (3-D result).

Return type:

CellForegroundResult

Parameters:
itasc.segmentation.cell_divergence_segmentation.segment_cells_divergence(contours, foreground, nuc, params, *, frame=None, with_labels=True, contours_clean_override=None, foreground_mask_override=None, progress_cb=None)[source]

Run the unary-only divergence pipeline and return all intermediates.

Parameters:

  • contours (ndarray) – Cached divergence maps (raw positive divergence and the sigmoid foreground, respectively).

  • foreground (ndarray) – Cached divergence maps (raw positive divergence and the sigmoid foreground, respectively).

  • nuc (ndarray) – Tracked nucleus seeds.

  • params (CellDivergenceParams)

  • frame (int | None) – When given, only that frame is processed and temporal smoothing is skipped (it needs the whole stack); the result arrays are 2-D. When None, the whole stack is processed including temporal smoothing.

  • with_labels (bool) – When False, the geodesic Voronoi label assignment (the single slowest step) is skipped: every cleanup intermediate plus the weighted cost field is still returned, but result.labels is None. The live preview uses this to stay responsive — the cost field already explains every boundary the labels would land on.

  • contours_clean_override (ndarray | None) – Single-frame-only. When given (with frame set), this pre-cleaned — and, when temporal smoothing is on, pre-smoothed — contour frame is used as contours_clean instead of re-running the per-frame cleanup. The widget passes a frame sliced from clean_and_smooth_contours() so the single-frame cost field / labels match the full run exactly (the per-frame path cannot, as it lacks the whole-movie percentile and EMA). Ignored when frame is None.

  • foreground_mask_override (ndarray | None) – Precomputed fill mask to segment inside, replacing the internally derived (foreground_clean > fg_threshold) | (nuc > 0). The cell widget’s Foreground stage writes this mask to disk and the Segmentation stage feeds it back here, so the territory the walk fills is exactly the one tuned in the Foreground stage (not re-derived from the current knobs). (T, Y, X) for a full-stack run, (Y, X) (or a (T, Y, X) stack sliced at frame) for a single-frame run. foreground_clean is still computed for the cost field’s foreground score regardless.

  • progress_cb (Callable[[str], None] | None) – Receives short status strings.

Return type:

CellDivergenceResult