README.md

---
pipeline_tag: image-segmentation
license: cc-by-4.0
tags:
- medical
- ct
- body-composition
- 3d-segmentation
- nnunet
- residual-encoder
---

# BodyCompositionCT-ResEncM

BodyCompositionCT-ResEncM is a 3D nnU-Net v2 model for segmenting native
body-composition compartments and supporting anatomical structures in CT. This
is a single-checkpoint ResEnc M model trained on the complete training set. For
five-fold ResEnc L ensemble inference, see
[BodyCompositionCT-ResEncL](https://huggingface.co/fhofmann/BodyCompositionCT-ResEncL).

## Model overview

| Property | Value |
| --- | --- |
| Task | Mutually exclusive 3D semantic segmentation |
| Input | One CT volume |
| Architecture | nnU-Net v2, `3d_fullres`, ResEnc M |
| Checkpoint | One `fold_all` model trained on all training cases |
| Training set | 1,656 CT scans |
| Native output | Background plus seven foreground labels |
| License | CC BY 4.0 |

## Native output labels

| ID | Label | Description |
| ---: | --- | --- |
| 0 | Background | |
| 1 | Muscle | Muscle compartment |
| 2 | Bone | Bone |
| 3 | Subcutaneous | Subcutaneous compartment |
| 4 | Abdominal | Abdominal compartment, with organs and larger vessels excluded |
| 5 | Thoracic | Thoracic compartment, with organs and larger vessels excluded |
| 6 | Heart | Heart |
| 7 | Lungs | Lungs |

Labels 1, 3, 4, and 5 denote anatomical compartments rather than final
attenuation-defined tissue masks. The muscle compartment can contain inter- and
intramuscular connective tissue, smaller vessels, and larger fat-attenuation
regions. IMAT is not a separate model class; CT-visible IMAT can be derived
downstream within label 1 using HU-thresholding. All downstream tissue
measurements should state their HU range, cleanup rules, and source compartment.

The machine-readable mapping is stored in
[dataset.json](nnUNetTrainer__nnUNetResEncUNetMPlans__3d_fullres/dataset.json).

## Training data and target construction

The training set contains 750 CT scans from
[SAROS](https://doi.org/10.1038/s41597-024-03337-6) and 906 from the
[TotalSegmentator v2 dataset](https://doi.org/10.5281/zenodo.10047292).
Another 332 cases (150 SAROS and 182 TotalSegmentator) were reserved and were
not used for training.

Targets were constructed from dense
[BOA](https://doi.org/10.1097/RLI.0000000000001040) Task542 body-region
predictions, sparse expert-reviewed SAROS labels, and TotalSegmentator-derived
anatomical masks. Reviewed SAROS labels replaced predictions on annotated
slices. TotalSegmentator muscle, bone, lung, tracheal, body-trunk, organ,
vessel, and neural masks supplied corrections and exclusions. HU-guided
candidate selection, morphological cleanup, model-assisted completion, and
manual review produced the final seven foreground labels.

Only the open TotalSegmentator `total` and `body` tasks were used for target
construction; the separately licensed `tissue_types` and `vertebrae_body`
tasks were not used.

Training logs, plans, a configuration snapshot, and the training progress plot
are included with the model.

## Inference

The model uses the standard nnU-Net v2 results layout. The commands below were
tested with nnU-Net v2 2.5.2. Input files must be unwindowed CT NIfTI volumes
containing Hounsfield-unit values and named `<case>_0000.nii.gz`. Do not
normalize or resample them manually; nnU-Net applies the preprocessing stored
in the plans.

For integration with preprocessing and downstream tissue derivation, see the
[BodyComposition pipeline](https://github.com/fohofmann/BodyComposition).

Set the nnU-Net results directory and download the model:

```bash
export nnUNet_results="/path/to/nnUNet_results"

hf download fhofmann/BodyCompositionCT-ResEncM \
  --local-dir "${nnUNet_results}/Dataset611_Tissue"
```

Optionally verify the model artifacts:

```bash
cd "${nnUNet_results}/Dataset611_Tissue"
sha256sum -c MODEL_ARTIFACTS.sha256
```

Run inference:

```bash
nnUNetv2_predict \
  -d Dataset611_Tissue \
  -i INPUT_FOLDER \
  -o OUTPUT_FOLDER \
  -f all \
  -tr nnUNetTrainer \
  -c 3d_fullres \
  -p nnUNetResEncUNetMPlans
```

No independent nnU-Net postprocessing configuration was selected for this
`fold_all` model. HU-based tissue derivation remains a separate downstream
step.

The checkpoint is a serialized PyTorch artifact. Load it only from a trusted
copy of this repository.

## Evaluation status

The `fold_all` checkpoint was trained on all 1,656 training cases and therefore
has no held-out training fold. Values in the training logs are optimization
diagnostics, not independent performance estimates.

## Intended use and limitations

The model is intended to provide compartment masks for research pipelines,
including downstream body-composition measurements derived with CT attenuation thresholds.

- It is not intended for diagnosis, treatment decisions, or stand-alone
  clinical measurement.
- Training targets combine automated segmentations, deterministic corrections,
  and manual review; residual source-model and labeling errors can remain.
- Performance may vary across populations, scanners, acquisition protocols,
  contrast phases, artifacts, implants, and uncommon anatomy.
- The targets focus on the body trunk; extremity use is out of scope.
- External validation is required for each intended population and
  measurement definition.

## License and attribution

The trained weights, model documentation, metadata, and included training
records are released under
[CC BY 4.0](https://creativecommons.org/licenses/by/4.0/). Reuse requires
appropriate credit, a link to the license, and an indication of changes. See
[LICENSE](LICENSE) for the attribution format.

Training source data, source annotations, upstream checkpoints, and
third-party software are not redistributed and retain their original terms:

| Upstream material | Role | Terms |
| --- | --- | --- |
| SAROS labels and split metadata | Sparse reviewed labels | CC BY 4.0 |
| SAROS source CT scans | Training images | Collection-specific TCIA terms, including restricted, CC BY, and CC BY-NC collections |
| BOA Task542 weights | Dense initial body-region predictions | MIT |
| TotalSegmentator v2 dataset | Training CT scans and anatomical labels | CC BY 4.0 |
| TotalSegmentator `total` and `body` tasks | Corrections and exclusions | Apache-2.0 |
| nnU-Net v2 | Training framework and architecture | Apache-2.0 |

See [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md) for source links and the
complete provenance and license summary.

## References

- Hofmann FO et al. *Validation of body composition parameters extracted via
  deep learning-based segmentation from routine computed tomographies.*
  Scientific Reports (2025).
  https://doi.org/10.1038/s41598-025-96238-6
- Haubold J et al. *SAROS: A dataset for whole-body region and organ
  segmentation in CT imaging.* Scientific Data (2024).
  https://doi.org/10.1038/s41597-024-03337-6
- Haubold J et al. *BOA: A CT-Based Body and Organ Analysis for Radiologists at
  the Point of Care.* Investigative Radiology (2023).
  https://doi.org/10.1097/RLI.0000000000001040
- Wasserthal J et al. *TotalSegmentator: Robust Segmentation of 104 Anatomic
  Structures in CT Images.* Radiology: Artificial Intelligence (2023).
  https://doi.org/10.1148/ryai.230024
- Isensee F et al. *nnU-Net: a self-configuring method for deep
  learning-based biomedical image segmentation.* Nature Methods (2021).
  https://doi.org/10.1038/s41592-020-01008-z
- Isensee F et al. *nnU-Net Revisited: A Call for Rigorous Validation in 3D
  Medical Image Segmentation.* arXiv (2024).
  https://doi.org/10.48550/arXiv.2404.09556

Questions and feedback are welcome in the repository's
[Community](https://huggingface.co/fhofmann/BodyCompositionCT-ResEncM/discussions)
section.