mitk.MultiLabelSegmentation

mitk.MultiLabelSegmentation#

class mitk.MultiLabelSegmentation#

Bases: pybind11_object

Multi-label, multi-group segmentation data structure.

A MultiLabelSegmentation represents one or more labeled regions over a shared spatial geometry. It is organized into groups (see LabelGroup): each group has its own backing label image and its own list of Label instances. Labels in distinct groups may overlap spatially because they live in separate images.

Construction is overloaded:

MultiLabelSegmentation() constructs an empty segmentation.
MultiLabelSegmentation(reference_image) constructs an empty segmentation with the geometry of reference_image.
MultiLabelSegmentation(time_geometry) / MultiLabelSegmentation(base_geometry) use an explicit geometry.
MultiLabelSegmentation(path) loads from disk.

The same surface is reachable via load() and initialize().

__init__(*args, **kwargs)#

Overloaded function.

__init__(self: mitk.MultiLabelSegmentation) -> None

Construct an empty segmentation with no geometry and no labels.

__init__(self: mitk.MultiLabelSegmentation, reference_image: mitk.Image) -> None

Construct a segmentation from a reference image.

The segmentation inherits its geometry from reference_image and additionally:

establishes a source-image relation via mitk.relations.segmentation.connect_source_image(), and
transfers the reference image’s patient identity, study identity, and frame-of-reference UID via the corresponding mitk.dicom.segmentation inherit_* functions.

These steps are the common-case expectation when creating a derived seg. Failures are logged via MITK_WARN and swallowed; the constructor always returns a usable seg. Callers that want explicit control should use the underlying mitk.relations.segmentation / mitk.dicom.segmentation functions directly.

Parameters:: reference_image – The image the segmentation derives from.

__init__(self: mitk.MultiLabelSegmentation, time_geometry: mitk.TimeGeometry) -> None

Construct a segmentation from an explicit time geometry.

Parameters:: time_geometry – The TimeGeometry to use.

__init__(self: mitk.MultiLabelSegmentation, base_geometry: mitk.BaseGeometry) -> None

Construct a static (1-time-step) segmentation from a 3D geometry.

A ProportionalTimeGeometry with a single time step is built to wrap base_geometry.

Parameters:: base_geometry – The 3D spatial geometry to use.

__init__(self: mitk.MultiLabelSegmentation, path: os.PathLike | str | bytes) -> None

Load a segmentation from disk.

If the file is a plain image (not a multi-label segmentation format), the image is interpreted as a single-group labeled image (each unique non-zero pixel value becomes one Label).

Parameters:: path – Path to the segmentation file (str or pathlib.Path).
Raises:: ValueError – If the file cannot be loaded.

Methods

`__init__`(args, *kwargs)	Overloaded function.
`add_group`(self[, image, labels])	Append a new group to the segmentation.
`add_label`(args, *kwargs)	Overloaded function.
`clear_group_image`(self, index[, time_step])	Zero out the pixels of one group's backing image.
`clear_group_images`(self[, time_step])	Zero out the pixels of every group's backing image.
`clone`(self)	Return a deep copy of the segmentation.
`create_filtered_group_image`(self, group, labels)	Return a copy of a group's image filtered to the given labels.
`create_label_class_map`(self, group[, labels])	Build a class-name map for one group.
`create_label_mask`(self, label[, binary])	Extract a mask image for a single label.
`erase_label`(self, value)	Clear the pixels of a label without removing its metadata.
`erase_labels`(self, values)	Clear the pixels of multiple labels at once.
`from_labeled_image`(image)	Construct a segmentation from a pre-labeled image.
`get_direction`(self[, time_step])	Return the direction cosine matrix at the given time step.
`get_direction_cosines`(self[, time_step])	Return the direction cosines as a flat 9-element tuple.
`get_geometry`(self[, time_step])	Return the full `BaseGeometry` for the given time step.
`get_group`(self, index)	Return the `LabelGroup` snapshot at index.
`get_group_by_name`(self, name)	Find a group by its display name.
`get_group_class_names`(self, index)	Return the list of class-name strings for the group at index.
`get_group_image`(self, index)	Return the backing `Image` of the group at index.
`get_group_label_values`(self, index)	Return the integer label values for the group at index.
`get_group_labels`(self, index)	Return the `LabelVector` for the group at index.
`get_group_name`(self, index)	Return the display name of the group at index.
`get_group_of_label`(self, value)	Return the group index that owns the label with pixel value value.
`get_label`(self, value)	Return the `Label` with the given pixel value.
`get_label_values_at`(self, coordinates[, ...])	Return the label values present at the given world-space coordinates.
`get_label_values_by_name`(self, name[, group])	Return the label values whose name matches name.
`get_labels`(self, values)	Return the labels for a sequence of label values.
`get_origin`(self[, time_step])	Return the origin at the given time step.
`get_property`(self, key[, raw])	Return the property value for key, or `None` if not set.
`get_spacing`(self[, time_step])	Return the voxel spacing at the given time step.
`initialize`(args, *kwargs)	Overloaded function.
`load`(path)	Load a segmentation from disk (explicit factory).
`merge_labels`(self, target, sources, ...)	Merge multiple source labels into a single target label.
`property_is_owned`(self, key)	Return True if the property key is owned (writable) by this object.
`relabel_to`(self, label_mapping, dest_seg, ...)	Apply a label-value mapping to produce a new (or updated) segmentation.
`remove_group`(self, index)	Remove the group at index.
`remove_label`(self, value)	Remove a label entirely (metadata and pixels).
`remove_labels`(self, values)	Remove multiple labels at once.
`remove_property`(self, key)	Remove the property key if it exists.
`rename_label`(self, value, name, color)	Change a label's display name and color.
`save`(self, path)	Save the segmentation to a file.
`set_direction`(self, direction[, time_step])	Set the direction cosine matrix at the given time step.
`set_group_image`(self, index, image)	Replace the backing image of the group at index.
`set_group_name`(self, index, name)	Set the display name of the group at index.
`set_origin`(self, origin[, time_step])	Set the origin at the given time step.
`set_property`(self, key, value)	Set the property key to value.
`set_spacing`(self, spacing[, time_step])	Set the voxel spacing at the given time step.
`split_labels_by_class_name`(self, group[, labels])	Partition a group's labels by class name.
`split_labels_by_group`(self, labels)	Partition a list of label values by their owning group.
`update_group_image`(self, index, source, ...)	Copy a single time step into one group's backing image.

Attributes

`UNLABELED_VALUE`
`direction`	Direction cosine matrix at time step 0 as a 3x3 NumPy array.
`direction_cosines`	Direction cosines at time step 0 as a flat 9-element tuple.
`groups`	List of `LabelGroup` snapshots for every group.
`label_class_names`	Sorted list of unique class names assigned to labels in this segmentation.
`label_values`	Sorted list of all label pixel values across all groups.
`labels`	All labels across all groups, as a `LabelVector`.
`ndim`	Number of dimensions of the object.
`num_groups`	Number of label groups in this segmentation.
`origin`	Origin at time step 0 as a 3-tuple `(ox, oy, oz)`.
`property_keys`	List of all property keys currently set on this object.
`spacing`	Voxel spacing at time step 0 as a 3-tuple `(sx, sy, sz)`.
`time_geometry`	The full `TimeGeometry` of this object.
`time_steps`	Number of time steps.

UNLABELED_VALUE = 0#

add_group(self: mitk.MultiLabelSegmentation, image: mitk.Image = None, labels: list | None = None) → int#

Append a new group to the segmentation.

Parameters:

image – Optional Image to use as the group’s backing image. If omitted, a fresh blank image is allocated.
labels – Optional list of Label objects to populate the new group with.

Returns:

The index of the new group.

add_label(*args, **kwargs)#

Overloaded function.

add_label(self: mitk.MultiLabelSegmentation, label: mitk.Label, group: typing.SupportsInt = 0) -> mitk.Label

Add an existing Label to the segmentation.

The input label is cloned; the segmentation stores the copy. Edits applied to the original label after this call do not affect the segmentation. To modify the in-segmentation label, work with the returned Label instance instead.

Parameters:

label – The label to clone and add. If its pixel value collides with an existing label, a new value is assigned to the clone.
group – Target group index (default 0).

Returns:

The cloned label as stored in the segmentation (its assigned pixel value may differ from the input). Use this object for further edits.

add_label(self: mitk.MultiLabelSegmentation, name: str, color: tuple[typing.SupportsFloat, typing.SupportsFloat, typing.SupportsFloat], group: typing.SupportsInt = 0) -> mitk.Label

Add a new label by name and color.

Parameters:

name – Label name.
color – (r, g, b) tuple of floats in [0, 1].
group – Target group index (default 0).

Returns:

The newly created label.

clear_group_image(self: mitk.MultiLabelSegmentation, index: SupportsInt, time_step: SupportsInt | None = None) → None#

Zero out the pixels of one group’s backing image.

The group and its labels are preserved; only pixel data is cleared.

Parameters:

index – Group index.
time_step – If given, only that time step is cleared. Otherwise all time steps are cleared.

clear_group_images(self: mitk.MultiLabelSegmentation, time_step: SupportsInt | None = None) → None#

Zero out the pixels of every group’s backing image.

Parameters:: time_step – If given, only that time step is cleared across all groups. Otherwise all time steps are cleared.

clone(self: mitk.MultiLabelSegmentation) → mitk.MultiLabelSegmentation#: Return a deep copy of the segmentation.

create_filtered_group_image(self: mitk.MultiLabelSegmentation, group: SupportsInt, labels: collections.abc.Iterable) → mitk.Image#

Return a copy of a group’s image filtered to the given labels.

Pixels not belonging to any of labels are set to the unlabeled value.

Parameters:

group – Group index.
labels – Iterable of label values or Label objects.

Returns:

A new Image containing only the requested labels.

create_label_class_map(self: mitk.MultiLabelSegmentation, group: SupportsInt, labels: collections.abc.Iterable | None = None) → tuple#

Build a class-name map for one group.

Returns a tuple (image, id_to_class_name) where image is a remapped image whose pixel values are dense IDs (1, 2, 3, ...), and id_to_class_name is a dict keyed by those new IDs mapping to the corresponding label class name. Pixel value 0 is reserved for unlabeled (background) voxels and is not present in the returned map.

Parameters:

group – Group index.
labels – Optional iterable of labels to restrict the map to. If omitted, all labels in the group are included.

Returns:

A 2-tuple (image, class_name_map) where image is an Image and class_name_map is a dict[int, str] mapping the remapped dense ID to its class name (background ID 0 is omitted).

create_label_mask(self: mitk.MultiLabelSegmentation, label: SupportsInt, binary: bool = True) → mitk.Image#

Extract a mask image for a single label.

Parameters:

label – Label pixel value to extract.
binary – If True (default), produce a 0/1 mask. If False, the mask pixels carry the label’s original pixel value.

Returns:

A new Image masking the requested label.

property direction#: Direction cosine matrix at time step 0 as a 3x3 NumPy array.

property direction_cosines#: Direction cosines at time step 0 as a flat 9-element tuple.

erase_label(self: mitk.MultiLabelSegmentation, value: object) → None#

Clear the pixels of a label without removing its metadata.

The Label stays in the segmentation; only the pixels of its backing image are reset. Use remove_label() to delete the label entirely.

Parameters:: value – Label pixel value or Label object.

erase_labels(self: mitk.MultiLabelSegmentation, values: collections.abc.Iterable) → None#

Clear the pixels of multiple labels at once.

Parameters:: values – Iterable of label values or Label objects.

static from_labeled_image(image: mitk.Image) → mitk.MultiLabelSegmentation#

Construct a segmentation from a pre-labeled image.

Each unique non-zero pixel value in image becomes one Label in a single group of the resulting segmentation.

Parameters:: image – An Image containing integer label values.
Returns:: A new MultiLabelSegmentation.

get_direction(self: mitk.MultiLabelSegmentation, time_step: SupportsInt = 0) → numpy.typing.NDArray[numpy.float64]#

Return the direction cosine matrix at the given time step.

Parameters:: time_step – Time-step index (default 0).
Returns:: A 3x3 NumPy array of doubles.

get_direction_cosines(self: mitk.MultiLabelSegmentation, time_step: SupportsInt = 0) → Annotated[list[float], 'FixedSize(9)']#

Return the direction cosines as a flat 9-element tuple.

Parameters:: time_step – Time-step index (default 0).
Returns:: A 9-element sequence in row-major order.

get_geometry(self: mitk.MultiLabelSegmentation, time_step: SupportsInt = 0) → mitk.BaseGeometry#

Return the full BaseGeometry for the given time step.

Parameters:: time_step – Time-step index (default 0).
Returns:: The spatial geometry at the requested time step.

get_group(self: mitk.MultiLabelSegmentation, index: SupportsInt) → mitk.LabelGroup#

Return the LabelGroup snapshot at index.

Parameters:: index – Zero-based group index.
Raises:: ValueError – If the index does not exist.

get_group_by_name(self: mitk.MultiLabelSegmentation, name: str) → mitk.LabelGroup | None#

Find a group by its display name.

Parameters:: name – Group display name to look up.
Returns:: The matching LabelGroup snapshot, or None if no group has that name.

get_group_class_names(self: mitk.MultiLabelSegmentation, index: SupportsInt) → list[str]#: Return the list of class-name strings for the group at index.

get_group_image(self: mitk.MultiLabelSegmentation, index: SupportsInt) → mitk.Image#: Return the backing Image of the group at index.

get_group_label_values(self: mitk.MultiLabelSegmentation, index: SupportsInt) → list[int]#: Return the integer label values for the group at index.

get_group_labels(self: mitk.MultiLabelSegmentation, index: SupportsInt) → mitk.LabelVector#: Return the LabelVector for the group at index.

get_group_name(self: mitk.MultiLabelSegmentation, index: SupportsInt) → str#: Return the display name of the group at index.

get_group_of_label(self: mitk.MultiLabelSegmentation, value: SupportsInt) → int#

Return the group index that owns the label with pixel value value.

Parameters:: value – Integer label pixel value.
Returns:: The owning group’s index.

get_label(self: mitk.MultiLabelSegmentation, value: SupportsInt) → mitk.Label#

Return the Label with the given pixel value.

Parameters:: value – Integer label pixel value.
Returns:: The matching Label.
Raises:: ValueError – If no label with that value exists.

get_label_values_at(self: mitk.MultiLabelSegmentation, coordinates: Annotated[collections.abc.Sequence[SupportsFloat], 'FixedSize(3)'], time_step: SupportsInt = 0, group: SupportsInt | None = None) → list[int]#

Return the label values present at the given world-space coordinates.

For overlapping multi-group segmentations a single point can belong to several label values across groups.

Parameters:

coordinates – 3-element sequence (x, y, z) in world coordinates.
time_step – Time-step index. Defaults to 0.
group – Optional group index to restrict the lookup to. If omitted, all groups are queried.

Returns:

A list of integer label values at the given point.

get_label_values_by_name(self: mitk.MultiLabelSegmentation, name: str, group: SupportsInt | None = None) → list[int]#

Return the label values whose name matches name.

Parameters:

name – Label name to look up.
group – Optional group index to restrict the search to. If omitted, labels across all groups are considered.

Returns:

A list of integer label values. Empty if no label matches.

get_labels(self: mitk.MultiLabelSegmentation, values: collections.abc.Iterable) → mitk.LabelVector#

Return the labels for a sequence of label values.

Parameters:: values – Iterable of integer label values or Label objects.
Returns:: A LabelVector (missing values are silently skipped).

get_origin(self: mitk.MultiLabelSegmentation, time_step: SupportsInt = 0) → tuple[float, float, float]#

Return the origin at the given time step.

Parameters:: time_step – Time-step index (default 0).
Returns:: A 3-tuple (ox, oy, oz) in world coordinates.

get_property(self: mitk.MultiLabelSegmentation, key: str, raw: bool = False) → object#

Return the property value for key, or None if not set.

By default returns a coerced Python-native value: bool, int, float, str, or an (r, g, b) tuple for ColorProperty. For types without a known Python equivalent the raw mitk.BaseProperty object is returned.

Parameters:

key – Property name.
raw – If True, always return the underlying mitk.BaseProperty object (useful to access metadata or to pass to a C++ function that expects one). Defaults to False.

Returns:

The property value, or None if the property is not set.

get_spacing(self: mitk.MultiLabelSegmentation, time_step: SupportsInt = 0) → tuple[float, float, float]#

Return the voxel spacing at the given time step.

Parameters:: time_step – Time-step index (default 0).
Returns:: A 3-tuple (sx, sy, sz) in world units.

property groups#: List of LabelGroup snapshots for every group.

initialize(*args, **kwargs)#

Overloaded function.

initialize(self: mitk.MultiLabelSegmentation, reference_image: mitk.Image, reset_labels: bool = True) -> None

Re-initialize the segmentation from a reference image.

Parameters:

reference_image – Image whose geometry to adopt.
reset_labels – If True (default), discard all existing labels and groups. If False, keep them.

initialize(self: mitk.MultiLabelSegmentation, time_geometry: mitk.TimeGeometry, reset_labels: bool = True) -> None

Re-initialize the segmentation with an explicit time geometry.

Parameters:

time_geometry – The new geometry.
reset_labels – If True (default), discard all existing labels and groups.

property label_class_names#: Sorted list of unique class names assigned to labels in this segmentation.

property label_values#: Sorted list of all label pixel values across all groups.

property labels#: All labels across all groups, as a LabelVector.

static load(path: str) → mitk.MultiLabelSegmentation#

Load a segmentation from disk (explicit factory).

Equivalent to MultiLabelSegmentation(path).

Parameters:: path – Path to the segmentation file.
Returns:: The loaded segmentation.

merge_labels(self: mitk.MultiLabelSegmentation, target: object, sources: collections.abc.Iterable, overwrite_style: object = <OverwriteStyle.REGARD_LOCKS: 0>) → None#

Merge multiple source labels into a single target label.

Pixels belonging to any of the source labels are reassigned to the target. The source labels are removed.

Parameters:

target – Destination label (pixel value or Label).
sources – Iterable of label values or Label objects.
overwrite_style – How to treat locked target pixels (see OverwriteStyle). Defaults to REGARD_LOCKS.

property ndim#: Number of dimensions of the object.

property num_groups#: Number of label groups in this segmentation.

property origin#: Origin at time step 0 as a 3-tuple (ox, oy, oz).

property_is_owned(self: mitk.MultiLabelSegmentation, key: str) → bool#

Return True if the property key is owned (writable) by this object.

Returns False if the property does not exist or is provided read-only (for example, routed from an internal component like a Label inside a MultiLabelSegmentation).

Parameters:: key – Property name.

property property_keys#: List of all property keys currently set on this object.

relabel_to(self: mitk.MultiLabelSegmentation, label_mapping: collections.abc.Iterable, dest_seg: object = None, keep_untouched_labels: bool = False, merge_style: object = <MergeStyle.REPLACE: 0>, overwrite_style: object = <OverwriteStyle.IGNORE_LOCKS: 1>) → object#

Apply a label-value mapping to produce a new (or updated) segmentation.

Parameters:

label_mapping – Iterable of (source, destination) pairs. Each side is a label pixel value or a Label object.
dest_seg – Target MultiLabelSegmentation. If None (default), self is cloned and used as the target (see keep_untouched_labels for how the clone is prepared). When an explicit target is supplied, every destination value referenced in label_mapping must already exist in dest_seg.
keep_untouched_labels –
Only valid when dest_seg is None.
- False (default): the clone’s group images are cleared before the transfer. Only pixels of mapped labels appear in the result.
- True: the clone retains its original pixel content. Mapped labels are remapped in-place; every other label is left untouched. Combining this with an explicit dest_seg is rejected because the caller already controls the state of that object.
merge_style – MergeStyle (or lowercase string alias "replace" / "merge"). Defaults to REPLACE.
overwrite_style – OverwriteStyle (or lowercase string alias "regard_locks" / "ignore_locks"). Defaults to IGNORE_LOCKS.

Returns:

The populated dest_seg (or the auto-created clone when dest_seg was None).

Raises:

ValueError – If keep_untouched_labels=True is combined with an explicit dest_seg.

remove_group(self: mitk.MultiLabelSegmentation, index: SupportsInt) → None#

Remove the group at index.

Parameters:: index – Zero-based group index.

remove_label(self: mitk.MultiLabelSegmentation, value: object) → None#

Remove a label entirely (metadata and pixels).

Parameters:: value – Label pixel value or Label object.

remove_labels(self: mitk.MultiLabelSegmentation, values: collections.abc.Iterable) → None#

Remove multiple labels at once.

Parameters:: values – Iterable of label values or Label objects.

remove_property(self: mitk.MultiLabelSegmentation, key: str) → None#

Remove the property key if it exists.

Parameters:: key – Property name.
Raises:: PropertyNotOwnedError – If the property is provided read-only and cannot be removed.

rename_label(self: mitk.MultiLabelSegmentation, value: object, name: str, color: tuple[SupportsFloat, SupportsFloat, SupportsFloat]) → None#

Change a label’s display name and color.

Parameters:

value – Label pixel value or Label object.
name – New display name.
color – (r, g, b) tuple of floats in [0, 1].

save(self: mitk.MultiLabelSegmentation, path: str) → None#

Save the segmentation to a file.

The output format is inferred from the file extension. MITK ships with writers for the segmentation file format (.nrrd with auxiliary metadata) and for DICOM SEG (.dcm).

Parameters:: path – Output file path.

set_direction(self: mitk.MultiLabelSegmentation, direction: Annotated[numpy.typing.ArrayLike, numpy.float64], time_step: SupportsInt = 0) → None#

Set the direction cosine matrix at the given time step.

Parameters:

direction – 3x3 array-like (NumPy array, nested list, etc.).
time_step – Time-step index (default 0).

set_group_image(self: mitk.MultiLabelSegmentation, index: SupportsInt, image: mitk.Image) → None#

Replace the backing image of the group at index.

Parameters:

index – Zero-based group index.
image – New Image. Must match the segmentation’s geometry.

set_group_name(self: mitk.MultiLabelSegmentation, index: SupportsInt, name: str) → None#

Set the display name of the group at index.

Parameters:

index – Group index.
name – New display name.

set_origin(self: mitk.MultiLabelSegmentation, origin: Annotated[collections.abc.Sequence[SupportsFloat], 'FixedSize(3)'], time_step: SupportsInt = 0) → None#

Set the origin at the given time step.

Parameters:

origin – 3-element sequence (ox, oy, oz) in world coordinates.
time_step – Time-step index (default 0).

set_property(self: mitk.MultiLabelSegmentation, key: str, value: object) → None#

Set the property key to value.

The value is auto-wrapped into the appropriate BaseProperty subtype based on its Python type: bool -> BoolProperty, int -> IntProperty, float -> DoubleProperty, str -> StringProperty, 3-tuple -> ColorProperty, or an existing mitk.BaseProperty instance is used as-is.

Parameters:

key – Property name.
value – Property value (auto-wrapped to a BaseProperty subtype).

Raises:

PropertyNotOwnedError – If the property is provided read-only (not owned) by this object.

set_spacing(self: mitk.MultiLabelSegmentation, spacing: Annotated[collections.abc.Sequence[SupportsFloat], 'FixedSize(3)'], time_step: SupportsInt = 0) → None#

Set the voxel spacing at the given time step.

Parameters:

spacing – 3-element sequence (sx, sy, sz) in world units.
time_step – Time-step index (default 0).

property spacing#: Voxel spacing at time step 0 as a 3-tuple (sx, sy, sz).

split_labels_by_class_name(self: mitk.MultiLabelSegmentation, group: SupportsInt, labels: collections.abc.Iterable | None = None) → dict[str, list[int]]#

Partition a group’s labels by class name.

Parameters:

group – Group index.
labels – Optional iterable of label values to restrict the partition to. If omitted, all labels in the group are partitioned.

Returns:

A mapping from class-name string to the subset of labels with that class name.

split_labels_by_group(self: mitk.MultiLabelSegmentation, labels: collections.abc.Iterable) → dict[int, list[int]]#

Partition a list of label values by their owning group.

Parameters:: labels – Iterable of label values or Label objects.
Returns:: A mapping from group index to the subset of labels in that group.

property time_geometry#: The full TimeGeometry of this object.

property time_steps#: Number of time steps.

update_group_image(self: mitk.MultiLabelSegmentation, index: SupportsInt, source: mitk.Image, time_step: SupportsInt, source_time_step: SupportsInt = 0) → None#

Copy a single time step into one group’s backing image.

Parameters:

index – Group index.
source – Source Image.
time_step – Destination time step in the segmentation.
source_time_step – Time step to read from source (default 0).

mitk.MultiLabelSegmentation

Contents

mitk.MultiLabelSegmentation#