Thymus Segmentator

Automatic 3D segmentation of the anterior mediastinal fat (thymus) from CT scans.

This repository contains code, configs and a trained model for a UNet-based segmentation of the anterior mediastinal fat (structure containing the thymus). The project includes scripts, MONAI-based transforms, configuration files for training and inference, and a Dockerfile for easy deployment.

Highlights

• Task: Segmentation of anterior mediastinal fat (thymus region)
• Model: UNet-style segmentation model
• Trained model snapshot included in models/ (e.g. model_v2.pt)

Repository layout

• app/ — main package and configuration files
  • configs/ — YAML configs for train, inference, and evaluate
  • docs/ — documentation snippets
  • models/ — place for model checkpoint(s)
• scripts/ — useful helpers and MONAI transforms (e.g. meta.py, transforms.py, utils.py)
• Dockerfile — containerize the project

Model & Data

Inspect app/configs/metadata.json for the model metadata (format, authorship and versions). Key points:

• Input: single-channel CT patches (shape: 96×96×96, normalized to [-1, 1])
• Output: segmentation map with 2 channels (background + anterior_mediastinal_fat)
• Framework versions used while developing: MONAI 1.1.0, PyTorch 1.12.0, NumPy 1.22.3

For full metadata, see app/configs/metadata.json.

Requirements

This project was developed against the versions listed in app/configs/metadata.json. At minimum you'll need:

• Python 3.8+ (recommended)
• PyTorch (tested with 1.12.0)
• MONAI (tested with 1.1.0)
• NumPy

Optional (used by some scripts): fire, pytorch-ignite, nibabel.

Instalation - Quickstart

Option 1: Using the MONAI bundle on a virtual environment

1. Clone the repository:

   git clone https://github.com/vprudente/open_thymus_segmentator.git
   cd open_thymus_segmentator

2. Create a virtual environment with UV(recommended):

   uv venv
   source .venv/bin/activate  # On Windows: .venv\Scripts\activate

3. Install dependencies:

   uv sync

   If you do not want to use uv, you could just as easily do a pip install -e . in the repo directory

Option 2: Using the Docker image (Only available for inference)

Build the Docker image locally:

docker build -t open-thymus-seg .

Run a container and mount your data directory to /data inside the container. The project expects configuration-driven runs (see app/configs/inference.yaml and app/configs/train.yaml).

Running inference

The trained model is not stored in this repo. Download weights before inference from: Zenodo

1. Place your input CTs (NIfTI, NRRD or supported formats) in a folder accessible to the container or environment. The project expects pre-processing and patch-based inputs — check app/scripts/transforms.py and app/scripts/meta.py for available transforms.

2. Update app/configs/inference.yaml to point to your model checkpoint and data paths.

3. Run the inference script or entrypoint that loads the config and executes the pipeline.

   Option 1: Run directly using MONAI's CLI

   python -m monai.bundle run \
       --meta_file "./configs/metadata.json" \
       --config_file "./configs/inference.yaml" \
       --dataset_dir "<your-path-to-nrrd-img>" \
       --output_dir "<your-output-path-directory>"

   Note: If running in a GPU-enabled system the flag --gpu can be used to specify the device , e.g. --gpu "cuda:0". For additional details read the bundle instructions in app/docs/README.md or dive deeper into MONAI's documentation.

   Option 2: Run it using Docker

   # TODO

   Warning: Exact commands vary depending on your local setup or dockerized environment. The repository uses configuration-driven pipelines — adapt the YAML files in app/configs/ for paths and runtime options.

Training

Training is controlled by app/configs/train.yaml. Typical steps:

1. Prepare your dataset (the network is patch-based, see network_data_format in app/configs/metadata.json for patch shape and channel expectations).
2. Edit train.yaml to point to training and validation data folders and adjust hyperparameters.
3. Run the training entrypoint (the project uses MONAI-style transforms and training loops).

Useful scripts and utilities

• scripts/meta.py — collection of MONAI-based metadata transforms (update/copy/pop metadata fields on MetaTensor objects).
• scripts/transforms.py — project-specific transforms used in preprocessing and data loading.
• scripts/utils.py — helper utilities used across scripts.
• scripts/separate_model_optim.py — helper for optimizer/model separation (see file header for usage).

Examine these scripts to adapt the pipeline to your dataset and runtime environment.

License

Copyright © 2023 Vasco Prudente & Keno Bressem

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.