MRI Phase Unwrapping with ROMEO

Author: Steffen Bollmann, Michèle Masson-Trottier

The University of Queensland

Date: 16/03/2026

License:

Purpose¶

MRI phase data are inherently wrapped — phase values outside the range $[-\pi, \pi]$ “wrap around”, creating artificial discontinuities. Phase unwrapping recovers the true, continuous phase signal, which is essential for downstream analyses such as quantitative susceptibility mapping (QSM) and field mapping.

This tutorial demonstrates how to:

1. Download a demo dataset with magnitude and phase images

2. Prepare the data for unwrapping

3. Run ROMEO (Robust phase unwrapping) to recover continuous phase

Citation and Resources¶

Tools used in this workflow¶

ROMEO

Dymerska, B., Eckstein, K., et al. (2021). Phase unwrapping with a rapid opensource minimum spanning tree algorithm (ROMEO). Magnetic Resonance in Medicine, 85(4), 2294–2308. Dymerska et al. (2020)

Educational resources¶

• ROMEO on GitHub

• Neurodesk documentation

Prerequisites¶

• A running Neurodesk environment

• Familiarity with basic terminal commands

• No additional installation required — ROMEO is pre-installed in Neurodesk

Load software tools and download demo data¶

We use the same demo dataset as the SWI tutorial. Open a terminal in Neurodesktop and run the following commands to download the data, then copy and prepare the magnitude and phase files for ROMEO.

The terminal in Neurodesktop.

pip install osfclient
cd ~/neurodesktop-storage/
osf -p ru43c fetch -f 01_bids.zip ~/neurodesktop-storage/swi-demo/01_bids.zip

unzip -o ~/neurodesktop-storage/swi-demo/01_bids.zip -d ~/neurodesktop-storage/swi-demo/

Now copy the magnitude and phase files into a dedicated working directory:

mkdir -p ~/neurodesktop-storage/romeo-demo/

cp ~/neurodesktop-storage/swi-demo/01_bids/sub-170705134431std1312211075243167001/ses-1/anat/sub-170705134431std1312211075243167001_ses-1_run-1_part-phase_T2starw.nii \
   ~/neurodesktop-storage/romeo-demo/phase.nii

cp ~/neurodesktop-storage/swi-demo/01_bids/sub-170705134431std1312211075243167001/ses-1/anat/sub-170705134431std1312211075243167001_ses-1_run-1_part-mag_T2starw.nii \
   ~/neurodesktop-storage/romeo-demo/mag.nii

Terminal output after downloading and preparing the data.

Run ROMEO for phase unwrapping¶

Open the ROMEO tool from the Neurodesk application menu, then run the following command in the ROMEO container terminal:

romeo \
  -p ~/neurodesktop-storage/romeo-demo/phase.nii \
  -m ~/neurodesktop-storage/romeo-demo/mag.nii \
  -k nomask \
  -o ~/neurodesktop-storage/romeo-demo/

Terminal output after running ROMEO.

Inspect the results¶

The unwrapped phase image is saved in the output directory. You can verify it was created in the LXTerminal:

ls ~/neurodesktop-storage/romeo-demo/

Open ITK-SNAP from the Neurodesk Visualisation menu and load the original wrapped phase (phase.nii) alongside the unwrapped output to compare.

Comparison of wrapped (left) and unwrapped (right) phase in ITK-SNAP.

Summary¶

In this tutorial you:

1. Downloaded and prepared magnitude and phase MRI data

2. Used ROMEO to perform robust phase unwrapping

3. Compared the wrapped and unwrapped phase images