spacr.zstack¶

Z- and time-axis handling for the 3D (Beta) and 4D (Beta) mask settings.

This module holds the two non-xy axes: the z half (3D Beta, the first part of the file) and the t half built on top of it (4D Beta, the second part, from the 4D (Beta) banner onwards – it has its own long preamble there). Both are deliberately kept free of Cellpose, of any tracker library and of any model at all, so that the logic can be tested against synthetic label volumes on a CPU in milliseconds: every function here either takes a plain numpy array or takes a segment_fn callable that the caller supplies. spacr.object provides the Cellpose adapter.

The two halves live in one file rather than two because a 4-D acquisition is a z-stack per timepoint and the t code delegates to the z code for every one of them – segment_4d is a loop around segment_3d(), track_4d’s overlap backend is stitch_planes() applied along t, and TStackSpec carries a ZStackSpec inside it. Nothing in the z half below knows the t half exists, so a 3-D run is unaffected by any of it.

Four things drive the design of the z half, and each of them is a place where a naive 3-D implementation silently produces wrong science:

Anisotropy is the whole game.: Confocal z-spacing is routinely 3-10x the xy pixel size. A volume segmented as if it were isotropic merges objects along z, because a 3-plane gap that is really 3 um reads to the segmenter as 3 pixels. anisotropy here always means dz / dxy – the z step divided by the xy pixel size – which is the same convention Cellpose uses. It is a required input for volumetric segmentation: resolve_anisotropy() raises UnknownAnisotropyError rather than defaulting to 1.0, because 1.0 is a claim about the microscope, not a neutral value.
Stitching 2-D planes is not 3-D segmentation.: Both are legitimate and they give different answers. Per-plane segmentation followed by IoU linking (MODE_STITCH) sees each plane independently and cannot recover an object that is invisible in one plane; true volumetric segmentation (MODE_VOLUMETRIC) uses the z gradient but is far more sensitive to a wrong anisotropy. The mode is therefore explicit, never inferred, and ZStackResult records which one actually ran so it can be written next to the numbers it produced.
Objects touching the first or last plane are truncated.: Exactly as an object touching the xy field edge is truncated. Their volume is a lower bound and their shape statistics are meaningless. flag_truncated_z() marks them, mirroring the reasoning spacr.seg_qc already established for xy border objects (see seg_qc._score_labels, which counts border objects and then excludes them from every size statistic).
A single-plane volume is 2-D, not degenerate 3-D.: n_z == 1 short-circuits to MODE_SINGLE_PLANE, which calls segment_fn on the plain 2-D plane and returns a 2-D mask. It does not resample, does not stitch, and does not consult anisotropy.

Memory¶

A z-stack is n_z times a field, and volumetric segmentation transiently needs several copies of it. estimate_peak_bytes() gives the number for a given field; the pipeline processes one field at a time and never holds a plate. For a 2048x2048 field at 21 planes in float32 that is ~350 MB for the volume, and ~1.4 GB peak in MODE_VOLUMETRIC with resampling at anisotropy 5 (the isotropic copy is anisotropy times taller). This is why MODE_VOLUMETRIC is not the default.

Scope, stated plainly¶

The functions here are correct and tested, but the pipeline cannot yet feed them: spacr.io._rename_and_organize_image_files collapses z before any array reaches segmentation, and spacr.measure cannot consume a 3-D label mask. plan_from_settings() therefore returns None whenever the 3D settings are off – which is the default – so the 2-D path is untouched, and spacr.object raises ZAxisNotPresentError rather than quietly projecting when the settings are on but no z axis survived ingest.

Exceptions¶

`AmbiguousAxisOrderError`	It could not be established which axis is t and which is z.
`AmbiguousZAxisError`	The z axis could not be identified and was not supplied.
`TAxisNotPresentError`	The 4D settings are on but the array that arrived has no t (or no z).
`TStackError`	Base class for every 4-D configuration problem.
`TrackerIsTwoDError`	A backend that cannot link volumes was asked to link volumes.
`UnknownAnisotropyError`	Volumetric segmentation was asked for without a z/xy voxel ratio.
`UnknownDisplacementError`	A distance-based backend was asked for without a displacement gate.
`ZAxisNotPresentError`	The 3D settings are on but the array that arrived has no z axis.
`ZStackError`	Base class for every z-stack configuration problem.

Classes¶

`AxisOrder`	Which axis of the incoming array is which.
`TStackResult`	The labels a 4-D run produced, plus how it produced them.
`TStackSpec`	Everything the 4-D plumbing needs to know about one acquisition.
`TrackBackend`	What one tracking backend can and cannot be driven to do here.
`TrackResult`	The outcome of linking a 4-D label array across time.
`ZStackResult`	The labels a z-aware run produced, plus how it produced them.
`ZStackSpec`	Everything the z plumbing needs to know about one acquisition.

Functions¶

`as_t_first`(→ numpy.ndarray)	Return a view of `array` with t at axis 0 and z at axis 1.
`describe_3d_measurement`(→ Dict[str, str])	What one measurement column means in a 3-D run.
`detect_axes`(→ Optional[AxisOrder])	Work out which leading axis is t and which is z, or refuse to.
`detect_z_axis`(→ Optional[int])	Identify which axis of a 3-D array is z.
`estimate_peak_bytes`(→ int)	Peak bytes one field needs, so a plate can be sized before it is run.
`estimate_peak_bytes_4d`(→ int)	Peak bytes a 4-D run needs, so an acquisition can be sized before it runs.
`flag_truncated_t`(→ numpy.ndarray)	Track ids present in the first or last timepoint, and so cut off in t.
`flag_truncated_z`(→ numpy.ndarray)	Labels that touch the first or last z plane, and are therefore cut off.
`format_4d`(→ str)	Render a `TStackResult` or `TrackResult` as text.
`iter_volumes`(→ Iterator[numpy.ndarray])	Yield one `(Z, Y, X[, C])` volume per timepoint, lazily.
`plan_4d_from_settings`(→ Optional[TStackSpec])	Build a `TStackSpec` from a settings dict, or `None` when off.
`plan_from_settings`(→ Optional[ZStackSpec])	Build a `ZStackSpec` from a settings dict, or `None` when off.
`project`(volume[, mode, z_axis])	Collapse the z axis of `volume` to a single plane.
`project_labels`(→ numpy.ndarray)	Collapse a `(Z, Y, X)` label volume to `(Y, X)`, honestly.
`relabel_volume`(→ numpy.ndarray)	Renumber labels to a contiguous `1..N` with no gaps, background 0.
`report_3d_measurements`(→ Dict[str, List[str]])	Sort a real measurement table's columns by how 3-D treats them.
`resample_isotropic`(→ numpy.ndarray)	Stretch the z axis by `anisotropy` so the voxels become cubic.
`resolve_anisotropy`(→ float)	Return `dz / dxy`, derived from the voxel size when available.
`resolve_axis_order`(→ AxisOrder)	Return the `AxisOrder` for `array`, or explain why it cannot.
`restore_anisotropic`(→ numpy.ndarray)	Undo `resample_isotropic()`, back to `n_z` planes.
`segment_3d`(→ ZStackResult)	Segment a volume in the requested mode and record how it was done.
`segment_4d`(→ TStackResult)	Segment every timepoint independently, in 3-D, and stack the results.
`stitch_planes`(→ numpy.ndarray)	Link per-plane 2-D labels into 3-D objects by IoU between neighbours.
`track_4d`(→ TrackResult)	Link objects across time, in 3-D, and renumber them by track.
`volume_stats`(labels[, voxel_size])	Per-object volume, surface, z extent and truncation flag.
`volume_tracks`(labels_4d[, spec])	One row per object per timepoint: where it is, how big, how truncated.

Module Contents¶

exception spacr.zstack.AmbiguousAxisOrderError[source]¶

Bases: TStackError

It could not be established which axis is t and which is z.

Guessing here chooses between tracking through time and “tracking” down a z-stack, and the second produces smooth plausible trajectories that mean nothing, so the shape is reported back to the user instead.