itasc.cellpose.divergence_maps

Divergence-based foreground & contour maps from Cellpose prob/dp outputs.

Replaces the (cellprob x z) mask sweep with a direct computation:

foreground = reduce_z(sigmoid(prob)) contours = reduce_z(clip(div(filter(dp)), 0, inf))

See notes/divergence_maps_spec.md for the rationale.

Functions

build_divergence_maps(prob_path, dp_path, ...)

Compute and write contours and foreground from Cellpose prob/dp.

contour_from_dp(dp_tzcyx, *, ...)

Per (t, z): filter -> divergence -> clip(>=0); then reduce across z.

divergence_2d(flow_yx)

Divergence of a (2, Y, X) flow field with channels [dy, dx].

foreground_from_prob(prob_tzyx, *, reduction)

sigmoid(prob) reduced across z, optionally smoothed.

sigmoid(x)

Numerically stable sigmoid on float32 logits.

Classes

DivergenceMapsReport(frames, ...[, ...])

Summary returned by build_divergence_maps().
exception itasc.cellpose.divergence_maps.CancelledError[source]

Bases: Exception

Raised when a cooperative cancel signal is observed mid-computation.

class itasc.cellpose.divergence_maps.DivergenceMapsReport(frames, foreground_z_reduction, contour_z_reduction, smoothing_sigma, median_radius, contours_path, foreground_path, foreground_smoothing_sigma=0.0, foreground_median_radius=0)[source]

Bases: object

Summary returned by build_divergence_maps().

Parameters:

  • frames (int)

  • foreground_z_reduction (Literal['mean', 'max'])

  • contour_z_reduction (Literal['mean', 'max'])

  • smoothing_sigma (float)

  • median_radius (int)

  • contours_path (Path)

  • foreground_path (Path)

  • foreground_smoothing_sigma (float)

  • foreground_median_radius (int)

frames: int
foreground_z_reduction: Literal['mean', 'max']
contour_z_reduction: Literal['mean', 'max']
smoothing_sigma: float
median_radius: int
contours_path: Path
foreground_path: Path
foreground_smoothing_sigma: float
foreground_median_radius: int
itasc.cellpose.divergence_maps.build_divergence_maps(prob_path, dp_path, contours_out, foreground_out, *, foreground_z_reduction, contour_z_reduction, smoothing_sigma, median_radius, foreground_smoothing_sigma=0.0, foreground_median_radius=0, progress_cb=None, cancel=None)[source]

Compute and write contours and foreground from Cellpose prob/dp.

Output stacks are T x Y x X float32. progress_cb is called for each foreground frame, contour z-slice, and output write. smoothing_sigma / median_radius filter the flow before divergence (contours); the foreground_* knobs filter the reduced foreground map independently.

Return type:

DivergenceMapsReport

Parameters:
itasc.cellpose.divergence_maps.contour_from_dp(dp_tzcyx, *, smoothing_sigma, median_radius, reduction)[source]

Per (t, z): filter -> divergence -> clip(>=0); then reduce across z.

dp_tzcyx: shape (T, Z, 2, Y, X) with channels [dy, dx]. Returns (T, Y, X) float32.

Return type:

ndarray

Parameters:
itasc.cellpose.divergence_maps.divergence_2d(flow_yx)[source]

Divergence of a (2, Y, X) flow field with channels [dy, dx].

Return type:

ndarray

Parameters:

flow_yx (ndarray)

itasc.cellpose.divergence_maps.foreground_from_prob(prob_tzyx, *, reduction, smoothing_sigma=0.0, median_radius=0)[source]

sigmoid(prob) reduced across z, optionally smoothed.

Returns (T, Y, X) float32 in [0, 1]. When smoothing_sigma or median_radius is set, each reduced frame is median- then gaussian- filtered (defaults of 0 leave the foreground untouched).

Return type:

ndarray

Parameters:
itasc.cellpose.divergence_maps.sigmoid(x)[source]

Numerically stable sigmoid on float32 logits.

Return type:

ndarray

Parameters:

x (ndarray)