MultiLabel Segmentation

MultiLabelSegmentation – 4D label volume with group semantics.

This module provides:

  • MultiLabelSegmentation: Container of label groups backed by a 4D numpy array. Label values are globally unique across all groups; value 0 is reserved. Supports group-level image access, label properties editing, and value remapping.

  • LabelGroup: A named collection of labels within a MultiLabelSegmentation.

  • Label: A single label with value, name, color, opacity, visibility, and lock state.

class mitk_workbench_remote.multilabel.Label(value=None, name='', *, color=(1.0, 1.0, 1.0), opacity=1.0, visible=True, locked=False, tracking_id=None, tracking_uid=None, description=None)

Bases: object

A single label within a MultiLabelSegmentation.

Label value 0 is reserved as UNLABELED_VALUE and is rejected. When created with value=None, the value is assigned by MultiLabelSegmentation.add_label() via _assign_value().

Parameters:

  • value (int | None (default: None)) – Integer label value (>= 1), or None for deferred assignment.

  • name (str (default: '')) – Human-readable label name.

  • color (tuple[float, float, float] (default: (1.0, 1.0, 1.0))) – RGB color tuple with components in [0.0, 1.0].

  • opacity (float (default: 1.0)) – Opacity in [0.0, 1.0].

  • visible (bool (default: True)) – Whether the label is visible.

  • locked (bool (default: False)) – Whether the label is locked for editing.

  • tracking_id (str | None (default: None)) – Optional external tracking identifier.

  • tracking_uid (str | None (default: None)) – Optional external tracking UID.

  • description (str | None (default: None)) – Optional free-text description.

Raises:

ValueError – If value == 0 (reserved) or color components out of range.

property value: int | None

Integer label value, or None if not yet assigned.

property name: str

Human-readable label name.

property color: tuple[float, float, float]

RGB color tuple with components in [0.0, 1.0].

property opacity: float

Opacity in [0.0, 1.0].

property visible: bool

Whether this label is visible.

property locked: bool

Whether this label is locked for editing.

property tracking_id: str | None

Optional external tracking identifier.

property tracking_uid: str | None

Optional external tracking UID.

property description: str | None

Optional free-text description.

class mitk_workbench_remote.multilabel.LabelGroup(name=None)

Bases: object

A named collection of label values within a MultiLabelSegmentation.

Label objects themselves are stored in the parent MultiLabelSegmentation._labels registry; this class only tracks the ordered list of label values belonging to the group.

Parameters:

name (str | None (default: None)) – Optional group name.

property name: str | None

Group name, or None if unnamed.

property label_ids: list[int]

Ordered list of label values in this group. Returns a copy.

class mitk_workbench_remote.multilabel.MultiLabelSegmentation(*, groups, labels, group_images=None, spacing=None, origin=None, direction=None, properties=None, _shape=None)

Bases: object

Container of label groups backed by per-group spatial images.

Label values are globally unique across all groups. Value 0 is reserved as UNLABELED_VALUE. Group pixel data is stored as individual Image objects (None until set or lazily allocated by get_group_image()).

Use create() to build a new segmentation from scratch. The constructor is the primary path for I/O deserialization.

Parameters:
Raises:

ValueError – On shape/geometry inconsistency or duplicate/missing label IDs.

UNLABELED_VALUE: int = 0
classmethod create(*, groups=None, reference=None, shape=None, spacing=None, origin=None, direction=None)

Create a new empty segmentation.

Either reference or shape must be supplied.

Parameters:

  • groups (list[LabelGroup] | None (default: None)) – Initial groups. Defaults to an empty list.

  • reference (Any | None (default: None)) – An Image from which geometry is inherited (overrideable via spacing/origin/direction).

  • shape (tuple[int, ...] | None (default: None)) – Spatial shape (x, y, z) used when reference is not given.

  • spacing (Sequence[float] | None (default: None)) – Override spacing (defaults to reference geometry or (1, 1, 1)).

  • origin (Sequence[float] | None (default: None)) – Override origin (defaults to reference geometry or (0, 0, 0)).

  • direction (ndarray | None (default: None)) – Override direction (defaults to reference geometry or identity).

Return type:

MultiLabelSegmentation

Returns:

A new MultiLabelSegmentation with no pixel data.

Raises:

ValueError – If neither reference nor shape is given.

property groups: list[LabelGroup]

Ordered list of label groups (copy).

property labels: list[Label]

All Label objects across all groups, sorted by value.

Raises:

ValueError – If any label still has value is None. By construction, add_label assigns a value before storing, so a None here indicates internal-state corruption — aliasing it onto the reserved UNLABELED_VALUE (0) would hide a real bug.

property spacing: tuple[float, ...]

Voxel spacing (3D).

property origin: tuple[float, ...]

World-space origin (3D).

property direction: ndarray

Direction cosine matrix (3x3, float64).

property properties: dict[str, Any]

Data-scope properties dict.

property property_keys: list[str]

List of property keys.

get_property(key)

Get a property by key.

Parameters:

key (str) – Property key.

Return type:

Any

Returns:

The property value, or None if not found.

set_property(key, value)

Set a property by key.

Parameters:

  • key (str) – Property key.

  • value (Any) – Property value.

Return type:

None

remove_property(key)

Remove a property by key.

Parameters:

key (str) – Property key.

Raises:

KeyError – If the key does not exist.

Return type:

None

to_mitk()

Convert to a mitk.MultiLabelSegmentation (native MITK Python binding).

Requires the mitk package, which is typically only available inside a MITK-provided Python environment. Geometry, pixel data, and all label metadata (groups, labels, colors, lock state, etc.) are transferred via NRRD round-trip.

Note: data-scope properties stored in properties are not transferred, because the remote library’s NRRD writer does not embed arbitrary properties. For a full round-trip including data-scope properties, use DataNode.get_data() / DataNode.set_data() with as_type=DataRepresentation.MITK.

Return type:

Any

Returns:

A mitk.MultiLabelSegmentation instance.

Raises:

ImportError – If mitk is not installed.

classmethod from_mitk(mitk_seg)

Create from a mitk.MultiLabelSegmentation (native MITK Python binding).

Geometry, pixel data, and all label metadata are transferred via NRRD round-trip.

Parameters:

mitk_seg (Any) – A native MITK MultiLabelSegmentation object.

Return type:

MultiLabelSegmentation

Returns:

A new MultiLabelSegmentation instance.

Raises:

ImportError – If mitk is not installed.

get_label(value)

Look up a label by value.

Parameters:

value (int) – Integer label value.

Return type:

Label | None

Returns:

The Label, or None if not found.

get_group(index)

Return the group at the given index.

Parameters:

index (int) – Group index.

Return type:

LabelGroup

Returns:

The LabelGroup.

Raises:

IndexError – If index is out of range.

get_group_by_name(name)

Find a group by name using a linear search.

Parameters:

name (str) – Group name to search for.

Return type:

LabelGroup | None

Returns:

The first matching LabelGroup, or None.

get_group_labels(index)

Return all Label objects belonging to a group.

Parameters:

index (int) – Group index.

Return type:

list[Label]

Returns:

Ordered list of Label objects.

Raises:

IndexError – If index is out of range.

add_label(label, group)

Add a label to the specified group.

If label.value is None, the next free integer >= 1 is assigned.

Parameters:

  • label (Label) – The label to add.

  • group (int) – Target group index.

Return type:

Label

Returns:

The label (with its value assigned).

Raises:

  • ValueError – If the value is 0 or already exists in any group.

  • IndexError – If group is out of range.

remove_label(value, *, clear_pixels=True)

Remove a label by value.

Parameters:

  • value (int) – Label value to remove.

  • clear_pixels (bool (default: True)) – If True (default), zero out pixels equal to value in the group’s image before removing the label.

Raises:

ValueError – If value is not found in any group.

Return type:

None

add_group(name=None)

Append a new empty group and return its index.

Parameters:

name (str | None (default: None)) – Optional group name.

Return type:

int

Returns:

Index of the newly added group.

get_group_image(index)

Return the pixel data for a group as an Image.

If no data has been set for this group, a zero-filled Image is created and cached. Edits to the returned Image’s array are reflected in subsequent calls.

Parameters:

index (int) – Group index.

Return type:

Any

Returns:

An Image with this group’s pixels.

Raises:

  • IndexError – If index is out of range.

  • ValueError – If shape is unknown and no pixel data has been set yet.

set_group_image(index, data)

Set pixel data for a group.

Parameters:

  • index (int) – Group index.

  • data (Any) – An Image, ndarray, or any type handled by the converter registry.

Raises:

  • IndexError – If index is out of range.

  • ValueError – If the array shape does not match the segmentation’s shape, ndim < 3, or dtype is not integer-compatible.

Return type:

None

import_group_image(index, data, *, value_map)

Import and remap pixel data into a group.

Source pixel values are remapped according to value_map. Unmapped values pass through unchanged. Value 0 always maps to 0.

Parameters:

  • index (int) – Target group index.

  • data (Any) – Source pixel data (any type accepted by set_group_image()).

  • value_map (dict[int, int | str]) – Mapping from source integer values to target label values. Targets may be an integer label value or a label name string.

Raises:

  • IndexError – If index is out of range.

  • ValueError – If a target label name does not exist in the group, or a target integer value does not belong to the group.

Return type:

None

validate()

Check internal consistency between pixel data and label metadata.

Return type:

list[str]

Returns:

A list of warning strings. An empty list means the segmentation is internally consistent.