Skip to content

CopickSegmentation

copick.models.CopickSegmentation

Encapsulates all data pertaining to a specific segmentation. This includes the Zarr-store for the segmentation and other metadata.

Attributes:

  • run (CopickRun) –

    Reference to the run this segmentation belongs to.

  • meta (CopickSegmentationMeta) –

    Metadata for this segmentation.

  • zarr (MutableMapping) –

    Zarr store for this segmentation. Either populated from storage or lazily loaded when CopickSegmentation.zarr is accessed for the first time.

  • from_tool (bool) –

    Flag to indicate if this segmentation was generated by a tool.

  • from_user (bool) –

    Flag to indicate if this segmentation was generated by a user.

  • user_id (str) –

    Unique identifier for the user or tool name.

  • session_id (str) –

    Unique identifier for the segmentation session

  • is_multilabel (bool) –

    Flag to indicate if this is a multilabel segmentation.

  • is_instance (bool) –

    Flag to indicate if this is an instance segmentation: voxel values are instance IDs of the object name, 0 for background.

  • is_panoptic (bool) –

    Flag to indicate if this is a panoptic segmentation: a (2, Z, Y, X) volume holding each voxel's object label and its instance ID within that object.

  • segmentation_type (str) –

    "binary", "multilabel", "instance" or "panoptic".

  • directory (str) –

    The run-level directory holding the store.

  • voxel_size (float) –

    Voxel size of the tomogram this segmentation belongs to.

  • name (str) –

    Pickable Object name or multilabel name of the segmentation.

  • color –

    Color of the pickable object this segmentation belongs to.

directory 

directory: str

The run-level directory holding this segmentation's store (Segmentations for binary and multilabel, InstanceSegmentations and PanopticSegmentations for the newer types).

__init__ 

__init__(run: CopickRun, meta: CopickSegmentationMeta)

Parameters:

delete 

delete() -> None

Delete the segmentation record.

zarr 

zarr() -> MutableMapping

Override to return the Zarr store for this segmentation. Also needs to handle creating the store if it doesn't exist.

numpy 

numpy(zarr_group: str = '0', x: slice = slice(None, None), y: slice = slice(None, None), z: slice = slice(None, None), channel: Optional[Union[str, int]] = None) -> np.ndarray

Returns the content of the Zarr-File for this segmentation as a numpy array. Multiscale group and slices are supported.

Parameters:

  • zarr_group (str, default: '0' ) –

    Zarr group to access.

  • x (slice, default: slice(None, None) ) –

    Slice for the x-axis.

  • y (slice, default: slice(None, None) ) –

    Slice for the y-axis.

  • z (slice, default: slice(None, None) ) –

    Slice for the z-axis.

  • channel (Optional[Union[str, int]], default: None ) –

    Panoptic segmentations only: "label" (0) or "instance" (1) returns that channel as a (Z, Y, X) array; None returns both, (2, Z, Y, X).

Returns:

  • ndarray –

    np.ndarray: The segmentation as a numpy array.

from_numpy 

from_numpy(data: ndarray, levels: int = 1, dtype: Optional[dtype] = None) -> None

Set the segmentation from a numpy array and compute multiscale pyramid. By default, no pyramid is computed for segmentations.

Parameters:

  • data (ndarray) –

    The segmentation as a numpy array: (Z, Y, X), or (2, Z, Y, X) for a panoptic segmentation (np.stack([labels, instance_ids])).

  • levels (int, default: 1 ) –

    Number of levels in the multiscale pyramid.

  • dtype (Optional[dtype], default: None ) –

    Data type of the segmentation. None (the default) chooses the smallest unsigned integer type that holds every value, starting at np.uint8 (np.uint16 for instance and panoptic segmentations). A value that would not survive the cast raises ValueError; nothing is wrapped or truncated.

Raises:

  • ValueError –

    For a panoptic segmentation, also if the shape is not (2, Z, Y, X), a label is neither 0 nor a pickable object's label, or a background voxel carries an instance ID.

set_region 

set_region(data: ndarray, zarr_group: str = '0', x: slice = slice(None, None), y: slice = slice(None, None), z: slice = slice(None, None), channel: Optional[Union[str, int]] = None) -> None

Set a region of the segmentation from a numpy array.

Parameters:

  • data (ndarray) –

    The segmentation's subregion as a numpy array. Values that do not fit the stored dtype raise ValueError instead of wrapping.

  • zarr_group (str, default: '0' ) –

    Zarr group to access.

  • x (slice, default: slice(None, None) ) –

    Slice for the x-axis.

  • y (slice, default: slice(None, None) ) –

    Slice for the y-axis.

  • z (slice, default: slice(None, None) ) –

    Slice for the z-axis.

  • channel (Optional[Union[str, int]], default: None ) –

    Panoptic segmentations only: write just this channel ("label" or "instance"); None writes both from a (2, z, y, x) array. The result is checked like from_numpy's.

instance_ids 

instance_ids(zarr_group: str = '0', object_name: Optional[str] = None) -> np.ndarray

The instance IDs present: the unique non-zero values of an instance segmentation, or of a panoptic segmentation's instance channel where the label is object_name's.

The volume is read one chunk at a time, so memory stays bounded by the chunk size.

Parameters:

  • zarr_group (str, default: '0' ) –

    Zarr group (pyramid level) to read. Level 0 holds every instance.

  • object_name (Optional[str], default: None ) –

    Required for a panoptic segmentation, whose instance IDs are per object.

Returns:

  • ndarray –

    Sorted int64 array of instance IDs.

Raises:

  • ValueError –

    If this is neither an instance nor a panoptic segmentation, or object_name is missing (panoptic) or another object than this instance segmentation's.

segments 

segments(zarr_group: str = '0') -> List[Tuple[str, int]]

The segments of a panoptic segmentation: each (object_name, instance_id) present, where instance 0 is a region of that object not split into instances.

Parameters:

  • zarr_group (str, default: '0' ) –

    Zarr group (pyramid level) to read.

Raises:

  • ValueError –

    If this is not a panoptic segmentation.

label_volume 

label_volume(zarr_group: str = '0') -> np.ndarray

A panoptic segmentation's label channel: the multilabel segmentation it contains.

instance_volume 

instance_volume(object_name: str, zarr_group: str = '0') -> np.ndarray

A panoptic segmentation's instances of one object: the instance segmentation it contains for object_name (instance IDs where the label is that object's, 0 elsewhere).