TotalSegmentator

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

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_mask = 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)

segmentation_method(preprocessed_image)[source]

Run TotalSegmentator on the preprocessed image and return result.

This implementation runs both the ‘total’ and ‘body’ tasks from TotalSegmentator to ensure comprehensive segmentation. The ‘total’ task segments major organs and structures, while the ‘body’ task provides body outline segmentation to fill gaps.

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.: Background regions from the ‘total’ task are filled with soft tissue labels from the ‘body’ task

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)

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.