itasc.cellpose.cellpose_runner¶

Local Cellpose-SAM runner, Qt-free, used by the napari Cellpose widget.

Functions

`device_label`()
`eval_model`(img, **eval_kwargs)	Evaluate the selected model, honoring custom transformer tile size.
`get_model`()	Lazy-load the selected Cellpose model once per process; cached by model path.
`infer_layout_from_ndim`(ndim)	Best-effort layout from array ndim.
`is_model_loaded`()
`layout_has_time`(layout)
`layout_has_z`(layout)
`run_cell_frame`(frame, z, params)	Single 2D-slice cell inference.
`run_cell_frame_joint`(cell_frame, ...)	Two-channel cell inference on one 2D z-slice, guided by the nucleus channel.
`run_cell_stack`(stack, params, *[, ...])	Process a (T, Z, Y, X) stack slice-by-slice in 2D.
`run_cell_stack_joint`(cell_stack, ...[, ...])	Two-channel cell inference over paired `(T, Z, Y, X)` cell + nucleus stacks.
`run_nucleus_frame`(frame, z, params)	Single-frame nucleus inference.
`run_nucleus_stack`(stack, params, *[, ...])	Process a (T, Z, Y, X) stack frame-by-frame.
`selected_pretrained_model`()	Return the Cellpose pretrained model id/path used by subsequent inference.
`set_pretrained_model`(pretrained_model)	Select the Cellpose pretrained model id/path and invalidate stale cache.
`to_tzyx`(arr, layout)	Normalize an input array to canonical `(T, Z, Y, X)` for its layout.
`write_outputs`(prob_3dt, dp_3dt, output_dir, ...)	Write the two canonical TIFFs under output_dir.

Classes

`CellParams`(diameter, min_size, gamma)
`NucleusParams`(do_3d, anisotropy, diameter, ...)

Exceptions

CancelledError

Raised by run_*_stack when cancel_cb returns True between frames.

itasc.cellpose.cellpose_runner.layout_has_time(layout)[source]¶

Return type:: bool
Parameters:: layout (str)

itasc.cellpose.cellpose_runner.layout_has_z(layout)[source]¶

Return type:: bool
Parameters:: layout (str)

itasc.cellpose.cellpose_runner.infer_layout_from_ndim(ndim)[source]¶

Best-effort layout from array ndim.

2 -> "2D" and 4 -> "3D+t" are unambiguous; 3 is ambiguous (2D+t vs 3D) so returns None and the caller keeps the user’s explicit choice.

Return type:: str | None
Parameters:: ndim (int)

itasc.cellpose.cellpose_runner.to_tzyx(arr, layout)[source]¶

Normalize an input array to canonical (T, Z, Y, X) for its layout.

Singleton T and/or Z axes are inserted so 2D/2D+t/3D/3D+t inputs all become 4-D; the runner then iterates uniformly over frames and z-slices.

Return type:

ndarray

Parameters:

arr (ndarray)
layout (str)

class itasc.cellpose.cellpose_runner.NucleusParams(do_3d, anisotropy, diameter, min_size, gamma, cellprob_threshold=0.0, flow_threshold=0.4, niter=0)[source]¶

Bases: object

Parameters:

do_3d (bool)
anisotropy (float)
diameter (float)
min_size (int)
gamma (float)
cellprob_threshold (float)
flow_threshold (float)
niter (int)

do_3d: bool¶

anisotropy: float¶

diameter: float¶

min_size: int¶

gamma: float¶

cellprob_threshold: float = 0.0¶

flow_threshold: float = 0.4¶

niter: int = 0¶

class itasc.cellpose.cellpose_runner.CellParams(diameter, min_size, gamma)[source]¶

Bases: object

Parameters:

diameter (float)
min_size (int)
gamma (float)

diameter: float¶

min_size: int¶

gamma: float¶

itasc.cellpose.cellpose_runner.device_label()[source]¶

Return type:: str

itasc.cellpose.cellpose_runner.is_model_loaded()[source]¶

Return type:: bool

itasc.cellpose.cellpose_runner.selected_pretrained_model()[source]¶

Return the Cellpose pretrained model id/path used by subsequent inference.

Return type:: str

itasc.cellpose.cellpose_runner.set_pretrained_model(pretrained_model)[source]¶

Select the Cellpose pretrained model id/path and invalidate stale cache.

None or a blank value restores the default Cellpose-SAM model ("cpsam"). A custom model is passed through to Cellpose as the pretrained_model argument exactly as a filesystem path string.

Return type:: None
Parameters:: pretrained_model (str | Path | None)

itasc.cellpose.cellpose_runner.get_model()[source]¶: Lazy-load the selected Cellpose model once per process; cached by model path.

itasc.cellpose.cellpose_runner.eval_model(img, **eval_kwargs)[source]¶

Evaluate the selected model, honoring custom transformer tile size.

Parameters:: img (ndarray)

itasc.cellpose.cellpose_runner.run_nucleus_frame(frame, z, params)[source]¶

Single-frame nucleus inference.

If z is None, runs full 3D over (Z, Y, X) and returns prob with shape (Z, Y, X) and dp with shape (3, Z, Y, X). If z is an integer, runs 2D on frame[z] and returns prob with shape (Y, X) and dp with shape (2, Y, X).

Return type:

tuple[ndarray, ndarray]

Parameters:

frame (ndarray)
z (int | None)
params (NucleusParams)

exception itasc.cellpose.cellpose_runner.CancelledError[source]¶

Bases: RuntimeError

Raised by run_*_stack when cancel_cb returns True between frames.

itasc.cellpose.cellpose_runner.run_cell_frame(frame, z, params)[source]¶

Single 2D-slice cell inference. Returns (prob (Y,X), dp (2,Y,X)).

Return type:

tuple[ndarray, ndarray]

Parameters:

frame (ndarray)
z (int)
params (CellParams)

itasc.cellpose.cellpose_runner.run_cell_frame_joint(cell_frame, nucleus_frame, z, params)[source]¶

Two-channel cell inference on one 2D z-slice, guided by the nucleus channel.

A single Cellpose-SAM pass runs over a two-channel image (cell + nucleus) so the nucleus channel informs the cell-body flow/probability fields. Returns (prob (Y, X), dp (2, Y, X)) — the same shapes as run_cell_frame(), so the two-channel result is a drop-in replacement for the single-channel one.

Channel order matches the classic [cytoplasm, nucleus] convention and the single-channel cell path (which places the cell channel at index 0): the cell channel is the primary “to-segment” channel (index 0), the nucleus is the auxiliary guide (index 1). channel_axis is passed explicitly (cpsam zero-pads to 3 channels internally); the same per-plane gamma is applied to both channels and cpsam normalises each channel independently.

Return type:

tuple[ndarray, ndarray]

Parameters:

cell_frame (ndarray)
nucleus_frame (ndarray)
z (int)
params (CellParams)

itasc.cellpose.cellpose_runner.run_nucleus_stack(stack, params, *, progress_cb=None, cancel_cb=None)[source]¶

Process a (T, Z, Y, X) stack frame-by-frame.

Returns (prob_3dt, dp_3dt). For do_3d=True dp has shape (T, 3, Z, Y, X); for do_3d=False dp has shape (T, Z, 2, Y, X).

Return type:

tuple[ndarray, ndarray]

Parameters:

stack (ndarray)
params (NucleusParams)
progress_cb (Callable[[int, int, str], None] | None)
cancel_cb (Callable[[], bool] | None)

itasc.cellpose.cellpose_runner.run_cell_stack(stack, params, *, progress_cb=None, cancel_cb=None)[source]¶

Process a (T, Z, Y, X) stack slice-by-slice in 2D.

Returns (prob_3dt (T, Z, Y, X), dp_3dt (T, Z, 2, Y, X)).

Return type:

tuple[ndarray, ndarray]

Parameters:

stack (ndarray)
params (CellParams)
progress_cb (Callable[[int, int, str], None] | None)
cancel_cb (Callable[[], bool] | None)

itasc.cellpose.cellpose_runner.run_cell_stack_joint(cell_stack, nucleus_stack, params, *, progress_cb=None, cancel_cb=None)[source]¶

Two-channel cell inference over paired (T, Z, Y, X) cell + nucleus stacks.

Like run_cell_stack() but each 2D slice is segmented from a two-channel image (cell + nucleus) so the nucleus channel guides the cell-body flow. Returns (prob_3dt (T, Z, Y, X), dp_3dt (T, Z, 2, Y, X)) — identical shapes to run_cell_stack(), so downstream flow-following is unaffected.

Return type:

tuple[ndarray, ndarray]

Parameters:

cell_stack (ndarray)
nucleus_stack (ndarray)
params (CellParams)
progress_cb (Callable[[int, int, str], None] | None)
cancel_cb (Callable[[], bool] | None)

itasc.cellpose.cellpose_runner.write_outputs(prob_3dt, dp_3dt, output_dir, channel)[source]¶

Write the two canonical TIFFs under output_dir.

Writes {channel}_prob.tif and {channel}_dp.tif. Axis labels are recorded as metadata so singleton T/Z axes (2D / 2D+t / single 3D-stack inputs) survive the TIFF round-trip and are not misread downstream.

Return type:

None

Parameters:

prob_3dt (ndarray)
dp_3dt (ndarray)
output_dir (Path)
channel (Literal['nucleus', 'cell'])