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, exposed as a live view (its labels and image reflect the segmentation’s current state at access time).
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

One group of a MultiLabelSegmentation.

Returned by MultiLabelSegmentation.groups and MultiLabelSegmentation.get_group(). A LabelGroup is a live view over its owning segmentation, not a point-in-time copy: labels and image reflect the segmentation’s current state at access time.

It also remains the internal membership record: the ordered label values (label_ids) are read directly by the segmentation and the NRRD I/O layer. Label objects themselves live in the parent’s MultiLabelSegmentation _labels registry.

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

property name: str | None

Group name, or None if unnamed.

Read-only, matching native mitk.LabelGroup (a read-only snapshot). Rename via MultiLabelSegmentation.set_group_name().

property index: int

0-based position of this group within the owning segmentation.

Raises:: RuntimeError – If this group is not attached to a segmentation (e.g. a bare LabelGroup(...) obtained other than via seg.groups or seg.get_group(i)).

property labels: list[Label]

Label objects in this group, current at access time.

Raises:: RuntimeError – If this group is not attached to a segmentation.

property image: Any

The group’s live pixel Image.

Delegates to MultiLabelSegmentation.get_group_image(), so accessing it lazily zero-allocates the image exactly as that method does, and edits via .image.array persist on the segmentation.

Raises:: RuntimeError – If this group is not attached to a segmentation.

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:

groups (list[LabelGroup]) – Ordered list of label groups (each pre-populated with label IDs).
labels (dict[int, Label]) – Global label registry mapping value -> Label.
group_images (Sequence[Any | None] | None (default: None)) – Per-group pixel data. Filled with None if not given.
spacing (Sequence[float] | ndarray | None (default: None)) – Voxel spacing (3D).
origin (Sequence[float] | ndarray | None (default: None)) – World-space origin (3D).
direction (Sequence[Any] | ndarray | None (default: None)) – Direction cosine matrix (3x3).
properties (dict[str, Any] | None (default: None)) – Data-scope properties dict.

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 num_groups: int: Number of groups (alias for len(self.groups)).

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 label_values: list[int]: All label values across all groups, sorted ascending.

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.

Labels are keyed by value, so a miss raises KeyError (dict-like), matching native mitk.MultiLabelSegmentation.get_label. Use has_label() for an existence check that never raises.

Parameters:: value (int) – Integer label value.
Return type:: Label
Returns:: The Label with the given value.
Raises:: KeyError – If no label with value exists.

has_label(value)

Return whether a label with the given value exists.

Parameters:: value (int) – Integer label value.
Return type:: bool
Returns:: True if a label with value exists, else False. Never raises (including for the reserved UNLABELED_VALUE).

get_group_of_label(value)

Return the index of the group that owns a label.

Parameters:: value (int) – Integer label value.
Return type:: int
Returns:: The 0-based index of the owning group.
Raises:: KeyError – If no label with value exists in any group.

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.

set_group_name(index, name)

Set a group’s display name.

The group’s LabelGroup.name is read-only; this is the supported way to rename it, mirroring native set_group_name. Passing None to clear the name is a remote-only allowance – native mitk requires a string and rejects None.

Parameters:

index (int) – Group index.
name (str | None) – New group name, or None to clear it (remote-only).

Raises:

IndexError – If index is out of range.

Return type:

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.

get_labels(values)

Return the labels for the given values, in input order.

Missing values are skipped silently (matching native get_labels and preserving cross-mode parity). For a strict single lookup that raises, use get_label().

Parameters:: values (Iterable[int]) – Label values to look up.
Return type:: list[Label]
Returns:: The matching Label objects, in the order of values.

get_label_values_by_name(name, group=None)

Return the values of all labels whose name equals name.

Parameters:

name (str) – Label name to match exactly.
group (int | None (default: None)) – If given, restrict the search to that group.

Return type:

list[int]

Returns:

Matching label values, sorted ascending (consistent with label_values); an empty list if none match.

Raises:

IndexError – If group is out of range.

get_group_label_values(index)

Return the label values belonging to a group, in group order.

Parameters:: index (int) – Group index.
Return type:: list[int]
Returns:: The group’s label values, in group order.
Raises:: IndexError – If index is out of range.

add_label(label_or_name, /, color=<object object>, group=0)

Overloads:

self, label (Label), group (int) → Label
self, name (str), color (tuple[float, float, float]), group (int) → Label

Add a label to a group and return it (with its value assigned).

Two spellings, dispatched on the first argument’s type:

add_label(label, group=0) – add an existing Label.
add_label(name, color, group=0) – build and add a label from a name and RGB color.

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

Unlike native mitk – which clones the label and reassigns its value on a collision – this stores the given object and raises on collision.

Parameters:

label_or_name (Label | str) – A Label, or a label name (str) for the convenience spelling.
color (Any (default: <object object at 0x77b8344db6b0>)) – RGB color, required only in the (name, color) spelling.
group (int (default: 0)) – Target group index (default 0).

Returns:

The added label.

Raises:

TypeError – If the first argument is neither a Label nor a str, or the str spelling is used without a color.
ValueError – If the value is 0 (reserved) or already exists.
IndexError – If group is out of range.

remove_labels(values)

Remove several labels (and their pixels).

Atomic: every value is validated to exist first (KeyError naming the first missing value) before any label is removed.

Parameters:: values (Iterable[int]) – Label values to remove.
Raises:: KeyError – If any value is not present in any group.
Return type:: None

erase_label(value)

Zero every pixel equal to value in its group image; keep the label.

Unlike remove_label(), the label metadata is retained. If the group’s image has not been allocated yet this is a no-op on pixels (it does not force allocation). After erasing, validate() reports the label as declared-but-unpainted, which is the intended state.

Parameters:: value (int) – Label value whose pixels to clear.
Raises:: KeyError – If value is not present in any group.
Return type:: None

erase_labels(values)

erase_label() for several values, with the same atomic validation.

Parameters:: values (Iterable[int]) – Label values whose pixels to clear.
Raises:: KeyError – If any value is not present in any group.
Return type:: None

rename_label(value, name, color)

Set a label’s name and color in one call.

Both name and color are required, matching native rename_label.

Parameters:

value (int) – Label value to rename.
name (str) – New label name.
color (tuple[float, float, float]) – New RGB color, components in [0.0, 1.0].

Raises:

KeyError – If value is not present.
ValueError – If any color component is out of [0.0, 1.0].

Return type:

None

merge_labels(target, sources)

Reassign each source label’s pixels to target, then remove the sources.

Simplified vs native mitk.MultiLabelSegmentation.merge_labels: it does not implement lock handling, merge/overwrite styles, or native’s TransferLabelContent semantics, and – unlike native, which retains the source labels – it removes them. On use it emits MitkApiDivergenceWarning. It exists so callers do not break under get_data(as_type=AUTO); for full fidelity use the mitk bindings.

In the target group, overlaps are best-effort (the target value wins), which can overwrite another target-group label’s last pixels and leave it declared but unpainted – part of the documented divergence.

Parameters:

target (int) – Label value that the sources are merged into.
sources (Iterable[int]) – Label values to merge into target and then remove.

Raises:

KeyError – If target or any source is not present.

Return type:

None

remove_label(value)

Remove a label and zero its pixels in its group image.

Matches native mitk.MultiLabelSegmentation.remove_label: MITK does not model a “remove the label but keep its orphan pixels” state. To clear a label’s pixels while keeping the label, use erase_label(); to reassign pixels to another label, remap them first, then remove.

Parameters:: value (int) – Label value to remove.
Raises:: KeyError – If value is not present in any group.
Return type:: None

add_group(name=None, image=None, labels=None)

Append a new group and return its index.

Optionally seed the group with pixel image and/or a list of labels. image and labels are positional-or-keyword to mirror native add_group(name, image, labels), so the same call works in both modes.

Parameters:

name (str | None (default: None)) – Optional group name.
image (Any | None (default: None)) – Optional pixel data (ndarray / Image / converter type, same acceptance as set_group_image()).
labels (list[Label] | None (default: None)) – Optional labels to add to the new group (each via add_label(); value assignment and collision handling are identical).

Return type:

int

Returns:

Index of the newly added group.

Raises:

TypeError – If image cannot be resolved to an ndarray (not an ndarray, Image, or a type with a registered converter).
ValueError – On shape/geometry mismatch of image or a duplicate label value.

On any failure the half-seeded group is rolled back, so a raised add_group never leaves a dangling group behind.

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.