flowchart TB I["Selected image and model/algorithm parameters"] --> C["Local evidence or predictions"] C --> R["Reconcile components or overlapping instances"] R --> L["Globally identified uint64 labels"] L --> P["Label pyramid and metadata"]
Segmentation examples
Choose a segmentation route by the acquisition and the desired definition of an object. An intensity component, a model instance and a fitted shell can all produce labels, but they make different assumptions and need different seam handling. Start from the complete example closest to your case.
| Route | Examples | Main decisions |
|---|---|---|
| Classical intensity segmentation | scikit-image-style pipeline, classical 3D centers | Threshold, connectivity, seed selection and physical scale |
| StarDist | 2D, 3D | Model, normalization, overlap and instance reconstruction |
| Cellpose | 2D, 3D | Model/backend, expected scale and volumetric inference procedure |
| YOLO workflows | 2D, 3D | Training/inference contract and detection-to-instance construction |
| Shape-driven objects | Shell objects | Physical radii, image evidence and per-object windows |
A classical pipeline exposes the global stages
The scikit-image-style example smooths, computes an Otsu threshold, performs binary opening/closing, labels connected components and measures retained objects. These are not all local filters. Gaussian and morphology stages need bounded image neighborhoods. Threshold estimation needs evidence across the image. Connected components need reconciliation of block-local labels across seams.
LabelComponentsOp emits local component evidence. RelabelComponentsOp reconciles it and produces global identities. Treating each core as a separate image would split any object crossing a seam, even if the preceding smoothed intensities were correct. The component merge is the algorithmic reason that this stage cannot be implemented by merely adding a few more pixels to an independent per-tile labeler.
The prepared fixture and reference scripts make the workflow useful for execution checks. Keep the reference’s connectivity, threshold convention and size-filter units matched; an output-count comparison is not meaningful when those definitions differ.
Learned instances need their own overlap policy
Model inference commonly uses patches and overlap. The model’s input context, normalization and reconstruction rules are part of the inference contract. A model trained on 2D cells is not automatically a 3D instance model when applied slice by slice. The volumetric examples document the route they actually use, including any grouping or reconstruction after prediction.
Check the chosen model’s scale against the selected OME level. Changing level without adjusting a model’s expected object size can change segmentation even when it improves runtime. Likewise, per-patch normalization can behave differently from a supplied global normalization. Follow the example’s real configuration rather than assuming that a model name determines those choices.
Fitted shapes are a different object definition
The shell example detects candidates, evaluates image evidence around each candidate and fits a star-convex radial representation. ShellFitOp reads a bounded fitting window; StarConvexLabelsOp paints the resulting shapes with an explicit overlap rule. Per-object windows and ownership prevent computing and emitting the same fit independently from every overlapping block.
This route is useful when a radial shell is a reasonable model of the object. It is not a generic substitute for an arbitrary membrane segmentation. Inspect the fitted surface and residual evidence, especially near touching objects, incomplete shells and objects larger than the declared window.
Publishing
Retain the planned label image through Hints::keep_images until publication has consumed it. ome_zarr::publish_label and LabelPublication install a uint64 level-zero label array, construct nearest-label pyramid levels, write label metadata and update the registry. A label table, when present, must refer to the same identities as the raster. This is why generic numeric averaging is not a valid label-pyramid operation: averages can create an ID that no object owns.
The output’s physical frame must match the selected source level or the explicit output lattice. A correct label image with wrong spacing is still wrong for physical volumes, distances and cross-channel overlays. Preserve that metadata when moving a completed work array into its published location.
Validate true image boundaries and seam-crossing objects, not only objects in the middle of patches. Compare multiple grids, matched objects and spatial overlap. A plausible large-image rendering is useful quality control, but it cannot replace a small case with known expected objects.