TotalSegmentator

SegmentChestTotalSegmentator groups a TotalSegmentator labelmap into the anatomy masks used by PhysioTwin4D workflows.

SegmentChestTotalSegmentatorWithContrast is the contrast-enhanced variant: same interface, thresholds and grouping tuned for contrast CT. Pick it when your scan has vascular contrast, and the plain class otherwise.

Class Reference

class physiotwin4d.SegmentChestTotalSegmentator(log_level=20)[source]

Bases: SegmentAnatomyBase

Chest CT segmentation using TotalSegmentator deep learning model.

This class implements chest CT segmentation using the TotalSegmentator neural network, which provides detailed anatomical structure segmentation including organs, bones, and vessels. It maps TotalSegmentator’s output labels to physiological groups for motion analysis.

TotalSegmentator provides segmentation for 117 anatomical structures including detailed organ, bone, and vessel segmentation. This implementation combines the ‘total’ task (main organs and structures) with the ‘body’ task (body outline) to ensure complete coverage.

Anatomy groups (heart, lung, bone, major_vessels, soft_tissue) are populated into SegmentAnatomyBase.taxonomy so downstream consumers (ConvertVTKToUSD, USDAnatomyTools) see a single, consistent group→organ mapping.

For contrast-enhanced studies (CT with contrast-enhanced blood in the heart/vessels), use SegmentChestTotalSegmentatorWithContrast instead, which subclasses this class and adds a connected-component pass to label contrast-enhanced blood under a "contrast" taxonomy group.

target_spacing

Target spacing set to 1.5mm for TotalSegmentator.

Type:

float

Example

>>> segmenter = SegmentChestTotalSegmentator()
>>> result = segmenter.segment(ct_image)
>>> labelmap = result['labelmap']
>>> heart_labelmap = result['heart']
__init__(log_level=20)[source]

Initialize the TotalSegmentator-based chest segmentation.

Populates SegmentAnatomyBase.taxonomy with the TotalSegmentator class index space, then calls SegmentAnatomyBase._finalize_other_group() so unclaimed ids end up in the other group.

Parameters:

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

set_has_academic_license(has_academic_license)[source]

Set whether the academic license is available.

Parameters:

has_academic_license (bool) – Whether the academic license is available

Return type:

None

segmentation_method(preprocessed_image)[source]

Run TotalSegmentator on the preprocessed image and return result.

This implementation always runs the ‘total’ task (major organs and structures). Outside fast mode it also runs the ‘lung_vessels’ overlay and the ‘body’ task; when has_academic_license is set it additionally runs the ‘heartchambers_highres’ and ‘tissue_4_types’ tasks. The ‘body’ task contributes only its skin outline (the skin label) into remaining background regions; it does not fill gaps with soft tissue.

The method uses temporary files for coordinate system conversion between ITK (LPS) and nibabel (RAS) formats, which is required for proper integration with TotalSegmentator.

Parameters:

preprocessed_image (itk.image) – The preprocessed CT image with isotropic spacing and appropriate intensity scaling

Returns:

The segmentation labelmap with TotalSegmentator labels.

The ‘body’ task’s skin label is written into the remaining background regions as the skin outline.

Return type:

itk.image

Note

Requires GPU acceleration (device=”gpu:0”) for reasonable performance. The method automatically handles coordinate system conversions between ITK and nibabel formats.

Example

>>> labelmap = segmenter.segmentation_method(preprocessed_ct)
class physiotwin4d.SegmentChestTotalSegmentatorWithContrast(log_level=20)[source]

Bases: SegmentChestTotalSegmentator

Chest CT segmentation using TotalSegmentator, with contrast-enhanced blood detection.

Extends SegmentChestTotalSegmentator with an additional connected-component pass that identifies contrast-enhanced blood vessels and cardiac chambers, labeling them under a "contrast" taxonomy group (label id 155). Use this class instead of SegmentChestTotalSegmentator for contrast-enhanced studies.

contrast_threshold

Lower intensity threshold used to detect contrast-enhanced blood.

Type:

int

Example

>>> segmenter = SegmentChestTotalSegmentatorWithContrast()
>>> result = segmenter.segment(ct_image)
>>> labelmap = result['labelmap']
>>> contrast_labelmap = result['contrast']
__init__(log_level=20)[source]

Initialize the contrast-enhanced TotalSegmentator-based segmentation.

Parameters:

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

postprocess_after_labelmap(input_image, labelmap_image)[source]

Run contrast-enhanced blood detection on the labelmap.

Overrides SegmentAnatomyBase.postprocess_after_labelmap().

Parameters:

  • input_image (itk.Image) – The original, unpreprocessed input image

  • labelmap_image (itk.Image) – The postprocessed segmentation labelmap

Returns:

The labelmap, with contrast-enhanced regions labeled

Return type:

itk.Image

segment_connected_component(preprocessed_image, labelmap_image, lower_threshold, upper_threshold, labelmap_ids=None, mask_id=0, use_mid_slice=True, hole_fill=2)[source]

Segment connected components based on intensity thresholding.

Identifies connected regions within intensity thresholds and existing anatomical masks, then selects the largest component. This is useful for segmenting structures like contrast-enhanced blood or specific tissue types.

Parameters:

  • preprocessed_image (itk.Image) – The preprocessed input image

  • labelmap_image (itk.Image) – Existing labelmap to constrain search

  • lower_threshold (int) – Lower intensity threshold

  • upper_threshold (int) – Upper intensity threshold

  • labelmap_ids (Optional[list[int]]) – List of label IDs to search within. If None, searches within all existing labels

  • mask_id (int) – ID to assign to the segmented component

  • use_mid_slice (bool) – If True, find largest component in middle slice only; if False, use entire 3D volume

  • hole_fill (int) – Number of pixels to dilate/erode for hole filling

Returns:

Updated labelmap with new component labeled as mask_id

Return type:

itk.Image

Example

>>> # Segment contrast-enhanced blood
>>> updated_labels = segmenter.segment_connected_component(
...     preprocessed_image, labels, 700, 4000, mask_id=155
... )
segment_contrast_agent(preprocessed_image, labelmap_image)[source]

Include contrast-enhanced blood in the labelmap.

Segments high-intensity regions corresponding to contrast-enhanced blood vessels and cardiac chambers. Uses connected component analysis focused on the middle slice where the heart is typically located.

Parameters:

  • preprocessed_image (itk.Image) – The preprocessed CT image

  • labelmap_image (itk.Image) – Existing segmentation labelmap

Returns:

Updated labelmap with contrast-enhanced regions labeled

Return type:

itk.Image

Note

Assumes the mid-z slice of the data contains the heart.

Example

>>> contrast_labels = segmenter.segment_contrast_agent(preprocessed_image, base_labels)

Basic Usage

import itk

from physiotwin4d import SegmentChestTotalSegmentator

image = itk.imread("chest_ct.nrrd")
segmenter = SegmentChestTotalSegmentator()

masks = segmenter.segment(image)

heart = masks["heart"]
lungs = masks["lung"]
vessels = masks["major_vessels"]
labelmap = masks["labelmap"]

itk.imwrite(heart, "heart_mask.nrrd")
itk.imwrite(lungs, "lung_mask.nrrd")
itk.imwrite(vessels, "major_vessels_mask.nrrd")
itk.imwrite(labelmap, "labelmap.nrrd")

Returned Keys

For this segmenter, segment() returns a dictionary with the following keys:

  • labelmap

  • lung

  • heart

  • major_vessels

  • bone

  • soft_tissue

  • other

The dictionary should be accessed by key. Do not unpack it positionally. The exact key set is determined by the segmenter’s AnatomyTaxonomy and may differ from other segmenters (see Segmentation Base Class). For SegmentChestTotalSegmentator specifically, all six groups plus labelmap are always present; downstream code that targets a different segmenter should check membership.

For contrast-enhanced studies, use SegmentChestTotalSegmentatorWithContrast instead of SegmentChestTotalSegmentator. It adds a contrast key to the returned dictionary and exposes a contrast_threshold attribute (default 500) that can be overridden before calling segment():

from physiotwin4d import SegmentChestTotalSegmentatorWithContrast

segmenter = SegmentChestTotalSegmentatorWithContrast()
segmenter.contrast_threshold = 600  # optional override

masks = segmenter.segment(image)
contrast = masks["contrast"]

Operational Notes

TotalSegmentator model inference may download model assets and can be slow on a CPU-only environment. For repeatable workflows, prefer the tutorial scripts or the physiotwin4d-convert-image-to-vtk CLI.

See Also