Labelmap Tools

Convert segmentation labelmaps into binary registration masks, with optional label exclusion and physically isotropic dilation.

Module Reference

Labelmap Tools for PhysioMotion4D

This module provides the LabelmapTools class with the definitive utility for turning a multi-label (or binary) segmentation labelmap into a binary registration mask, optionally excluding specific labels and dilating the result by a physical radius in millimeters.

class physiomotion4d.labelmap_tools.LabelmapTools(log_level=20)[source]

Utilities for converting segmentation labelmaps into registration masks.

A labelmap is an itk.Image of integer labels where 0 is background and each positive value identifies an anatomical structure. A registration mask is a binary itk.Image where every foreground voxel is 1. This class centralizes the labelmap-to-mask conversion so that thresholding, label exclusion, and physically isotropic dilation are performed identically everywhere in the platform.

Example

>>> tools = LabelmapTools()
>>> # Binary mask of every labeled voxel, dilated 5 mm
>>> mask = tools.convert_labelmap_to_mask(labelmap, dilation_in_mm=5.0)
>>> # Exclude the table/background labels 8 and 9 before masking
>>> mask = tools.convert_labelmap_to_mask(
...     labelmap, dilation_in_mm=5.0, exclude_labels=[8, 9]
... )
__init__(log_level=20)[source]

Initialize LabelmapTools.

Parameters:

log_level (int | str) – Logging level (default: logging.INFO)

convert_labelmap_to_mask(labelmap, dilation_in_mm=0.0, exclude_labels=None)[source]

Convert a labelmap into a binary registration mask.

Any voxel whose label is in exclude_labels is set to background first; every remaining non-zero voxel becomes foreground (1). The binary mask is then dilated by dilation_in_mm millimeters of physical radius. The radius is converted into per-axis voxel counts from the labelmap’s spacing so the dilation is physically isotropic even on anisotropic grids; each per-axis count is clamped to at least 1 voxel when dilation_in_mm > 0.

Parameters:

  • labelmap (Image) – Multi-label or binary itk.Image. Any non-zero voxel that is not excluded is treated as foreground.

  • dilation_in_mm (float) – Physical radius of the binary dilation in millimeters. Pass 0 (or negative) to skip dilation and return the raw thresholded mask. Default 0.0.

  • exclude_labels (Optional[list[int]]) – Optional list of integer label values to force to background before thresholding. When None (the default) no labels are excluded.

Return type:

Image

Returns:

itk.Image[itk.UC, 3] binary mask in the same physical space as labelmap (origin, spacing, direction copied from the input).

create_distance_map(labelmap, max_distance_mm=20.0, distance_scale=5.0, preserve_labels=True, fill_background_only=False, exclude_labels=None)[source]

Encode a labelmap as a continuous label-plus-boundary-distance image.

Each output voxel holds its original integer label plus a small fractional offset that encodes how far the voxel lies from the nearest boundary between two differently-labeled regions:

value = label + min(distance_to_nearest_boundary_mm,

max_distance_mm) / distance_scale

The boundary set is every voxel that 6-neighbors a voxel with a different label (background label 0 participates, so the outer surface of each structure is a boundary). The unsigned physical distance from each voxel to that set is computed with SignedMaurerDistanceMapImageFilter (taking the magnitude), clipped to max_distance_mm, divided by distance_scale, and added to the voxel’s original label.

With the defaults (20 mm clip, 5 scale) the fractional offset stays in [0.0, 4.0], potentially passing adjacent integer labels but emphasizing in medial alignment as well as boundary.

The motivation is registration metrics such as Greedy’s NCC: a raw integer labelmap is piecewise-constant, so the local variance inside each region is zero and NCC produces NaN gradients. Replacing it with this continuous encoding gives every region a smoothly varying signal while preserving label identity.

Parameters:

  • labelmap (Image) – Multi-label (or binary) itk.Image of integer labels.

  • max_distance_mm (float) – Distance clip, in millimeters. Default 20.0.

  • distance_scale (float) – Divisor applied to the clipped distance before it is added to the label. Default 5.0. With the default clip this bounds the fractional offset to [0, 4.0].

Return type:

Image

Returns:

itk.Image[itk.F, 3] in the same physical space as labelmap (origin, spacing, direction copied from the input).

Navigation

Utility Modules | Image Tools | Transform Tools