RAPID

RAPID is research code for analyzing 2D radiograph- and topogram-style images with Ultralytics YOLOv8: object detection for coarse body regions and organ-style landmarks, plus image classification, with DICOM-oriented helpers, evaluation scripts, and paper-style figures.

Contents

• End-to-end quick path
• Why RAPID? Why object detection and YOLO?
• Repository layout
• Pipeline overview
• Prerequisites
• Install
• Data layout
• Preparing your own dataset with BOA
• Trained RAPID model weights
• Step-by-step: preprocessing
• Step-by-step: training
• Step-by-step: evaluation and running models
• Postprocessing and figures
• Citation
• Authors and license

End-to-end quick path

1. Clone and install — Install: poetry install and poetry shell from the repo root.
2. Prepare data — Lay out detection or classification folders (or run classification preprocessing scripts from the root). For CT-centric cohorts, consider BOA as optional tooling when building labels or QC.
3. Train — cd src/train and run train_regions.py, train_landmarks.py, and/or train_classification.py (see training).
4. Point scripts at weights — Edit best.pt paths to match your runs/ folder (see paths).
5. Evaluate — cd src/inference for bundled val / CSV flows, or use evaluation scripts.
6. Optional — Postprocessing and figures for overlays and publication plots.

Why RAPID? Why object detection and YOLO?

Scout and topogram images are widely used to plan later acquisitions. Automating structured localization (where relevant anatomy appears) supports routing, quality control, and linking 2D scouts to 3D volumes.

• Object detection returns interpretable spatial outputs (bounding boxes and class names), not only a single global label. That matters when multiple structures appear in one field of view or when you need regions for downstream steps.
• YOLO (via Ultralytics) gives a standard, reproducible training and validation API, solid baselines at fixed input resolution, and common export and metric tooling—aligned with how the train scripts in this repository call YOLO(...).train() and model.val().

The repo is aimed at reviewers who want to reproduce the pipeline and at users who adapt it to their own data and approvals. Official RAPID checkpoints are described under Trained RAPID model weights (release timeline depends on privacy and legal review); this README will be updated when downloads go live.

Repository layout

RAPID/
├── preprocessing/     # splits, classification dataset layout, leakage checks, DICOM→PNG helper
├── src/
│   ├── train/           # YOLO train entrypoints (classification + detection)
│   ├── inference/       # run val / batch predict-style flows (see notes below)
│   └── evaluation/      # metrics, bootstrap CIs, detection PR-style analysis, inter-rater helpers
├── postprocessing/      # e.g. overlay CT onto topogram
├── labels/              # YOLO data YAMLs (paths, class names)
├── plots/               # figures for publication / supplements
├── images/              # banner and static assets
├── pyproject.toml       # Poetry dependencies and Python version
├── LICENSE              # MIT
└── README.md

After training, Ultralytics writes weights under runs/ relative to the shell’s current working directory when you start training (not necessarily the repo root). Download base checkpoints (for example yolov8x.pt, yolov8x-cls.pt) and place them under models/yolo-models/ as referenced by the train scripts, or edit those paths.

Prerequisites

• Python 3.10+ (see pyproject.toml)
• Poetry for dependency install
• NVIDIA GPU strongly recommended — train scripts use device=0; CPU-only runs are not the target configuration
• CUDA compatible with the pinned PyTorch 2.3.1 in Poetry
• Your own datasets and approvals; update every hard-coded path in scripts to match your machine

Declared dependencies not used by the Python scripts in this tree: pyproject.toml also lists Streamlit and fhir-pyrate. No .py file in the repository imports them yet; treat them as reserved for future tooling or remove them locally if you want a minimal environment.

Install

From the repository root:

# Clone (HTTPS — works without SSH keys)
git clone https://github.com/UMEssen/RAPID.git
cd RAPID

# Or SSH
# git clone git@github.com:UMEssen/RAPID.git && cd RAPID

poetry install
poetry shell

Data layout

Detection (YOLO detect)

YAML configs live in labels/. Dataset roots are path in each YAML (default layout relative to repo: ../data/region_dataset and ../data/landmark_dataset). Under each dataset:

<dataset_root>/
  train/images/    train/labels/
  val/images/      val/labels/
  test/images/     test/labels/

• Body regions — labels/body_regions.yaml: 4 classes (head, abdominal_region, thoracic_region, pericardium).
• Landmarks — labels/body_landmarks.yaml: 11 classes (e.g. lung, heart, spine, …).

If your data live elsewhere, edit the path: (and split subfolders if needed) in those YAML files.

Classification (YOLO classify)

Ultralytics expects class folders under the split root, for example:

data/classification_dataset/
  train/
    <class_a>/*.png
    <class_b>/*.png
  val/...
  test/...

The helper preprocessing/build_classification_dataset.py copies PNGs from a flat layout into that structure using CSVs (--raw_dir, --output_dir, --train_csv, --val_csv, --test_csv). Column names default to study_name and class_label (see script).

Preparing your own dataset with BOA

If you work with CT volumes and want rich anatomical reference while assembling your own study material (QC, cohort filtering, weak supervision ideas, or aligning 3D findings with 2D scouts), you can use BOA (Body and Organ Analysis) from the same organization.

BOA is a CT segmentation and analysis stack (SHIP-AI / IKIM) that combines TotalSegmentator-style structure extraction with body composition and related tasks—including body region detection and organ- and tissue-level outputs—so you get consistent labels across large cohorts. It is not a dependency of this repository; RAPID’s train scripts do not call BOA. Treat it as an optional companion pipeline: run BOA on your CTs under your own ethics and data policy, then map or fuse whatever BOA exports into whatever labeling workflow you use for RAPID (for example exporting 2D topogram PNGs and writing YOLO *.txt boxes by hand, semi-automatic tooling, or custom scripts).

• Repository: https://github.com/UMEssen/Body-and-Organ-Analysis
• Follow the BOA README for environment setup, Docker, and CLI or PACS-style usage.
• Cite BOA and upstream tools (TotalSegmentator, nnU-Net, etc.) per their README when you publish work that used BOA.

Trained RAPID model weights

We intend to publish trained RAPID weights (body regions, landmarks, and classification checkpoints used in our studies) so others can run inference without retraining. Release is gated on data privacy, consent, and legal review at our institution; timelines can shift as those reviews complete.

What to expect

• Check this README, repository Releases, and commit messages for updates—we will keep them aligned when a download is approved.
• Until a release appears, continue to train from Ultralytics base weights (see Step-by-step: training) or use your own best.pt from a compliant cohort.

If you need weights for a collaboration or reproducibility window before public release, use institutional channels (contact in pyproject.toml) rather than assuming artifacts are redistributable.

Step-by-step: preprocessing

Run from repository root unless a script assumes otherwise.

Classification pipeline (example order):

python preprocessing/classification_splitter.py
python preprocessing/build_classification_dataset.py --raw_dir raw --output_dir dataset \
  --train_csv classification_train.csv --val_csv classification_val.csv --test_csv classification_test.csv
python preprocessing/check_data_leakage.py

DICOM → single PNG (template): edit the path in preprocessing/dicom2png.py, then run:

python preprocessing/dicom2png.py

Detection dataset builder: preprocessing/build_detection_dataset.py imports utils.workers, which is not included in this repository. Treat that script as internal / incomplete in the public tree, or supply your own module. You can still build the folder layout above with any tooling that writes YOLO-format label .txt files next to images.

Step-by-step: training

Download YOLOv8 base weights and place them under models/yolo-models/ (or change the paths in the scripts). When official RAPID checkpoints become available, you can point the same train or inference scripts at those files instead; see Trained RAPID model weights.

Recommended: run train scripts from src/train/ so relative paths match the files.

cd src/train

# Detection — body regions (YAML: labels/body_regions.yaml)
python train_regions.py

# Detection — landmarks (YAML: labels/body_landmarks.yaml)
python train_landmarks.py

# Classification (folder dataset: ../../data/classification_dataset/train)
python train_classification.py

Script	Task	Config / weights
train_regions.py	Detect 4 body regions	../../labels/body_regions.yaml, yolov8x.pt
train_landmarks.py	Detect 11 landmark classes	../../labels/body_landmarks.yaml, yolov8x.pt
train_classification.py	Image classification	../../data/classification_dataset/train, yolov8x-cls.pt

Hyperparameters (epochs, batch size, learning rate, device, run name, etc.) are set in each file; adjust for your hardware and study.

Step-by-step: evaluation and running models

Detection

src/inference/inference_detection.py runs model.val(...) on the test split defined in the YAML (split="test"), prints metrics, and can save prediction txt files (save_txt=True, save_conf=True). It is not a generic model.predict() loop over arbitrary folders; for that, use the Ultralytics API in a small script or the CLI, pointing to your best.pt.

Before running: set each YOLO('.../best.pt') path to the weights produced by your training run. The file may still contain example names such as regions-train; your run directory will match the name= you used in train().

cd src/inference
python inference_detection.py

For PR-style / bootstrap analysis from saved label files, configure GT_DIR, PRED_DIR, and LABEL_MAP in src/evaluation/evaluation_detection.py, then run it from a working directory where those relative paths resolve (or use absolute paths).

Classification

src/inference/inference_classification.py loads best.pt, walks the test image tree, writes ../../results/classification/test-512.csv, and copies misclassified cases to ../../failure_analysis/failed_classification_cases. Adjust model path, input folder, and output paths inside the script.

cd src/inference
python inference_classification.py

src/evaluation/evaluation_classification.py expects a CSV (default filename classification.csv in the working directory) with columns such as predicted and actual; point it at the CSV you produced or adapt the path in the script.

Inter-rater agreement

src/evaluation/inter_rater_agreement.py reads fixed Excel paths under Radiologists-Results/ and uses irrCAC (Gwet’s AC). It is not wired into Poetry dependencies here; install irrCAC separately and align file names with your study, or treat the script as a template for radiologist-score analysis.

Postprocessing and figures

CT on topogram overlay — from repo root (or adjust paths inside the file):

python postprocessing/ct2topo.py

Plots (paths inside each script may need editing). plots/confusion_matrices.py is suitable for supplement-style confusion matrices; other scripts support curves and clinical summaries:

python plots/confusion_matrices.py
python plots/pr_curve.py
python plots/train_val_loss_curves.py
python plots/clinical_analysis.py

Citation

If you use this repository in academic work, please cite the associated publication when available.

If you used BOA for dataset preparation, cite BOA and its upstream components as instructed in the BOA repository (including TotalSegmentator and nnU-Net references there).

Authors and license

Maintainer contact in pyproject.toml. Code is released under the MIT License — see LICENSE (Copyright University Medicine Essen).