TotalSegmentator

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

Class Reference

class physiomotion4d.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.

target_spacing

Target spacing set to 1.5mm for TotalSegmentator.

Type:: float

Example

>>> segmenter = SegmentChestTotalSegmentator()
>>> result = segmenter.segment(ct_image, contrast_enhanced_study=True)
>>> 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 physiomotion4d import SegmentChestTotalSegmentator

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

masks = segmenter.segment(image, contrast_enhanced_study=True)

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
contrast

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 seven groups plus labelmap are always present; downstream code that targets a different segmenter should check membership.

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 physiomotion4d-convert-ct-to-vtk CLI.