matrad-vmat-example

VMAT treatment planning pipeline for thorax patients (1TH*): DICOM → matRad MAT → VMAT optimization (FMO → Sequencing → DAO).

---

Requirements

• Python 3.8+ (standard library only — no pip packages required)
• MATLAB R2021a
• matRad (see Setup below)

---

Setup

1. Clone with submodule

git clone --recurse-submodules https://github.com/DoseRAD2026/matrad-vmat-example

Or if already cloned:

git submodule update --init

2. Configure MATLAB path

Both scripts hardcode the MATLAB binary path. Edit if yours differs:

# script/01_dicom2mat.py and script/02_vmat_optimization.py
MATLAB_BIN = "/usr/local/MATLAB/link/R2021a/matlab"

3. Place DICOM input data

data/input/<patient_id>/    ← CT + RTSTRUCT .dcm files

---

Structure

matrad-vmat-example/
├── data/
│   ├── input/<patient_id>/       # CT + RTSTRUCT DICOM files
│   └── output/<patient_id>/      # all outputs (generated)
├── matRad-dev_VMAT_merge/        # matRad submodule (pinned commit)
└── script/
    ├── 01_dicom2mat.py
    └── 02_vmat_optimization.py

---

Usage

# Step 1 — DICOM → MAT
python script/01_dicom2mat.py                   # all patients
python script/01_dicom2mat.py 1THB002           # single patient

# Step 2 — VMAT optimization
python script/02_vmat_optimization.py           # all patients
python script/02_vmat_optimization.py 1THB002   # single patient
python script/02_vmat_optimization.py 1THB002 --force-recalc-dij   # skip dij cache
python script/02_vmat_optimization.py 1THB002 -c pln.json          # custom plan params

---

Outputs

Written to data/output/<patient_id>/:

File	Content
<id>.mat	matRad ct + cst structs
<id>_stf_dij_cache.mat	Beam geometry + dose influence matrix (cached)
<id>_dose.mha	Optimized dose cube, per-fraction (single precision)
<id>_dvh_report.txt	DVH metrics + constraint PASS/FAIL
<id>_dvh.png	DVH plot
<id>_optimization.png	FMO + DAO convergence curves

The stf/dij calculation is slow and cached automatically. Re-runs reuse the cache unless parameters change or --force-recalc-dij is passed.

---

Planning Protocol

Prescription: 70 Gy / 35 fx (2 Gy/fx), full 360° VMAT arc.

Parameter	Value
Gantry angle spacing	2° (181 control points)
Bixel size	5 mm
Dose grid	5 mm
Sequencer	Siochi, 7 levels
Optimizer	IPOPT

OAR	Constraint
Spinal cord	Dmax < 50.5 Gy
Lung	V60Gy < 33%, V5Gy < 33%
Oesophagus	Dmax < 73.5 Gy, V60Gy < 15.3%, Dmean < 30.6 Gy
Brachial plexus	Dmax < 66 Gy

A ring structure (PTV+5 mm to PTV+12 mm) is added to control dose fall-off. PTV is selected automatically by priority: PTVOPT > PTV > PTV_UNION > PTV1 > PTV_HAUPTPLAN.