A practical, code-first guide to DICOM-RT (Radiotherapy) objects — RT Plan, Structure Set, Dose, Image — for developers and medical physicists entering the field.
Status: 🚧 Active development · contributions welcome.
DICOM-RT is the file format that holds the actual content of cancer radiotherapy: where the radiation goes, how much, in which beams, against which contoured organs. Every Treatment Planning System (Eclipse, RayStation, Monaco, Pinnacle) emits these files, and every Oncology Information System (ARIA, MOSAIQ) consumes them.
The official DICOM standard is technically complete but practically inaccessible — thousands of pages of specifications, organized for parsers rather than for humans. The few introductory texts that exist either assume deep medical physics background or stop at trivial examples.
This repository fills that gap. It explains DICOM-RT from the perspective of someone who wants to read, write, validate, and reason about these files in code — without first reading 1,500 pages of specifications.
It is written by a clinical medical physicist who builds software with this data daily.
- Software engineers entering the radiation oncology domain (medical device companies, healthtech startups)
- Medical physicists learning Python / pydicom for clinical automation
- Researchers in AI for radiation oncology needing to handle these files
- Auditors / regulators seeking a plain-language reference for what's actually inside these files
If you already know DICOM-RT cold, this is not for you. If you've ever opened a DICOM file in pydicom, seen 400 tags, and not known where to start — this is for you.
| Object | Purpose | Status |
|---|---|---|
| RT Plan | The treatment prescription: beams, MUs, isocenter, geometry | ✅ |
| RT Structure Set | The contours: targets, organs at risk | ✅ |
| RT Dose | The calculated 3D dose distribution | 🚧 |
| RT Image | Treatment-time imaging (DRR, portal images) | 🚧 |
| RT Treatment Record | What was actually delivered, per fraction | 📋 planned |
| RT Ion Plan | Proton and heavy ion variants | 📋 planned |
Plus:
- DICOM-RT Overview — the framework before any single object
- Glossary — every acronym in radiation oncology, in plain language
examples/— runnable Python scripts for common extraction taskssamples/— tiny anonymized DICOM files for testing
Read the chapters in order if you're new to DICOM-RT. Each chapter is self-contained and includes:
- What this object is and why it exists (clinical motivation, plain language)
- The key tags (organized by what they answer, not by their hex codes)
- Code examples in Python using
pydicom - Common pitfalls when reading or writing the object
- Cross-references to related objects
Use the examples directly if you have a specific task. Each script in examples/ solves one real problem (extract prescription, list structures, compute coverage, etc.).
Use the samples for testing in your own projects. The samples/ directory contains tiny anonymized DICOMs in each transfer syntax variant.
The repository will be bilingual (English / Brazilian Portuguese). Quase nenhum recurso de qualidade sobre DICOM-RT existe em português hoje, e isso é um problema concreto pra desenvolvedores e físicos médicos brasileiros entrando na área.
Portuguese translations will live under docs/pt-br/. The English version is canonical for now; PT-BR will follow.
git clone https://github.com/lucasbritocFis/dicom-rt-explained.git
cd dicom-rt-explained
pip install -r requirements.txt # pydicom, numpy
python examples/01_extract_prescription.py samples/rt_plan_breast.dcmIssues and PRs welcome. Especially valuable:
- Corrections (this is written from clinical experience but DICOM is vast — I will get things wrong)
- Portuguese translations
- New examples for tasks I haven't covered
- Sample DICOMs for transfer syntaxes / scanner variants I don't have access to
Please anonymize all clinical data before contributing samples. See samples/ANONYMIZATION.md for guidelines.
MIT — see LICENSE.
Lucas Brito, PhD — Clinical Medical Physicist and Software Developer. Currently at Oncobarra (Rio de Janeiro). PhD in Physics from CBPF, research at CERN/CMS.
I build software at the intersection of clinical radiotherapy and engineering.