All Projects → korbinian90 → ROMEO

korbinian90 / ROMEO

Licence: other
Executables for ROMEO unwrapping for Linux, Windows and Mac OSX

Projects that are alternatives of or similar to ROMEO

qsm-tools
List of open-source quantitative susceptibility mapping (QSM) MRI software packages and data
Stars: ✭ 39 (+44.44%)
Mutual labels:  qsm
Brain-MRI-Segmentation
Smart India Hackathon 2019 project given by the Department of Atomic Energy
Stars: ✭ 29 (+7.41%)
Mutual labels:  mri-images
neurdicom
RESTful PACS server with plugins
Stars: ✭ 97 (+259.26%)
Mutual labels:  mri-images
mrnet
Building an ACL tear detector to spot knee injuries from MRIs with PyTorch (MRNet)
Stars: ✭ 98 (+262.96%)
Mutual labels:  mri-images
3d-prostate-segmentation
Segmentation of prostate from MRI scans
Stars: ✭ 36 (+33.33%)
Mutual labels:  mri-images
3d-nii-visualizer
A NIfTI (nii.gz) 3D Visualizer using VTK and Qt5
Stars: ✭ 86 (+218.52%)
Mutual labels:  mri-images
dl-cs
Compressed Sensing: From Research to Clinical Practice with Data-Driven Learning
Stars: ✭ 36 (+33.33%)
Mutual labels:  mri-reconstruction
MRI intensity normalization
Intensity normalization of multi-channel MRI images using the method proposed by Nyul et al. 2000
Stars: ✭ 49 (+81.48%)
Mutual labels:  mri-images
2D-and-3D-Deep-Autoencoder
Convolutional AutoEncoder application on MRI images
Stars: ✭ 57 (+111.11%)
Mutual labels:  mri-images
AD Prediction
Alzheimer's Disease Prediction by using ResNet, AlexNet
Stars: ✭ 118 (+337.04%)
Mutual labels:  mri-images
prostateMR 3D-CAD-csPCa
Hierarchical probabilistic 3D U-Net, with attention mechanisms (—𝘈𝘵𝘵𝘦𝘯𝘵𝘪𝘰𝘯 𝘜-𝘕𝘦𝘵, 𝘚𝘌𝘙𝘦𝘴𝘕𝘦𝘵) and a nested decoder structure with deep supervision (—𝘜𝘕𝘦𝘵++). Built in TensorFlow 2.5. Configured for voxel-level clinically significant prostate cancer detection in multi-channel 3D bpMRI scans.
Stars: ✭ 32 (+18.52%)
Mutual labels:  mri-images
Magic-VNet
VNet for 3d volume segmentation
Stars: ✭ 45 (+66.67%)
Mutual labels:  mri-images
radnet
U-Net for biomedical image segmentation
Stars: ✭ 11 (-59.26%)
Mutual labels:  mri-images
lune
🌑 Lune.js — Calculate the phases of the moon
Stars: ✭ 104 (+285.19%)
Mutual labels:  phase
kt-Dynamic-MRI-Reconstruction
[MRM'21] Complementary Time-Frequency Domain Network for Dynamic Parallel MR Image Reconstruction. [MICCAI'19] k-t NEXT: Dynamic MR Image Reconstruction Exploiting Spatio-Temporal Correlations
Stars: ✭ 30 (+11.11%)
Mutual labels:  mri-reconstruction
sigmanet
Sigmanet: Systematic Evaluation of Iterative Deep Neural Networks for Fast Parallel MR Image Reconstruction,
Stars: ✭ 45 (+66.67%)
Mutual labels:  mri-reconstruction
Improved-Wasserstein-GAN-application-on-MRI-images
Improved Wasserstein GAN (WGAN-GP) application on medical (MRI) images
Stars: ✭ 23 (-14.81%)
Mutual labels:  mri-images
microDL
3D virtual staining with 2D and 2.5D U-Nets
Stars: ✭ 23 (-14.81%)
Mutual labels:  phase
ArteryNetwork
A pipeline to extract vessels from MR images and perform analysis.
Stars: ✭ 21 (-22.22%)
Mutual labels:  mri-images
visualqc
VisualQC : assistive tool to ease the quality control workflow of neuroimaging data.
Stars: ✭ 56 (+107.41%)
Mutual labels:  mri-images

ROMEO Unwrapping

Unwrapping of 3D and 4D datasets. Coil combination of 5D datasets.

ROMEO

Get ROMEO

Ordered from simple to more involved approaches.

Option 1: Download standalone executable within mritools (Linux and Windows)

Download link for mritools as plain text: https://github.com/korbinian90/CompileMRI.jl/releases
If a compiled MacOS version is required, see Known-issues/MacOS, but the suggested way is Option 4

Option 2: Run in Neurodesk (every OS)

Neurodesk is an analysis environment for reproducible neuroimaging running in a docker container. It comes with a range of useful tools preinstalled, including ROMEO. (https://neurodesk.github.io/)

Option 3: Use the julia command line caller (every OS)

Step by step explanation here: https://github.com/korbinian90/RomeoApp.jl

Option 4: Compile ROMEO (every OS)

Follow the steps in https://github.com/korbinian90/CompileMRI.jl

Option 5: Use the julia package ROMEO.jl (every OS)

All the flexibility, but requires handling phase offsets and B0 calculation yourself (see MriResearchTools.jl)

Publication

ROMEO: Dymerska, B., Eckstein, K., Bachrata, B., Siow, B., Trattnig, S., Shmueli, K., Robinson, S.D., 2020. Phase Unwrapping with a Rapid Opensource Minimum Spanning TreE AlgOrithm (ROMEO). Magnetic Resonance in Medicine. https://doi.org/10.1002/mrm.28563

MCPC-3D-S Coil Combination: Eckstein, K., Dymerska, B., Bachrata, B., Bogner, W., Poljanc, K., Trattnig, S., Robinson, S.D., 2018. Computationally Efficient Combination of Multi-channel Phase Data From Multi-echo Acquisitions (ASPIRE). Magnetic Resonance in Medicine 79, 2996–3006. https://doi.org/10.1002/mrm.26963

Getting Started

Prerequisites

Phase (and optionally Magnitude) images in NIfTI fileformat.
For multi-echo/multi-timepoint data, 4D-NIfTI files are used with echoes/timepoints in the 4th dimension.
Individual 3D files can be merged into 4D files using fslmerge.
If 5D-NIfTI datasets with channels in the 5th dimension are given, coil combination is performed as first step.

Run ROMEO

ROMEO is a command line application. The binary is in the folder mritools/bin

Example usage for B0-mapping with a 5-echo scan with TE = [3,6,9,12,15] ms:
$ romeo ph.nii -m mag.ii -B -t 3:3:15 -o outputdir

Example usage for single-echo data:
$ romeo ph.nii -m mag.ii -k nomask -o outputdir

Example for multiple time points with identical echo time (fMRI):
$ romeo ph.nii -m mag.ii -k nomask -t epi -o outputdir

Example usage for a 3-echo scan with TE = [3,6,9] ms:
$ romeo ph.nii -m mag.ii -t [3,6,9] -o outputdir

Note that echo times are required for unwrapping multi-echo data.

Different Use Cases

Multi-Echo

If multi-echo data is available, supplying ROMEO with multi-echo information should improve the unwrapping accuracy. The same is true for magnitude information.

Coil Combination

Coil combination will be automatically performed for 5D datasets using MCPC-3D-S. The echoes have to be in the 4th dimension and the channels in the 5th dimension. For bipolar datasets use --phase-offset-correction bipolar as additional argument (bipolar correction requires >= 3 echoes).

Repeated Measurements (EPI)

4D data with an equal echo time for all volumes should be unwrapped as 4D for best accuracy and temporal stability. The echo times can be set to -t epi.

Setting the Template Echo

In certain cases, the phase of the first echo/time-point looks differently than the rest of the acquisition, which can occur due to flow compensation of only the first echo or not having reached the steady state in fMRI. This might cause template unwrapping to fail, as the first echo is chosen as the template by default.
With the optional argument --template 2, this can be changed to the second (or any other) echo/time-point.

Phase Offsets

If the multi-echo data contains large phase offsets (phase at echo time zero), default template unwrapping might fail. Setting the individual-unwrapping flag is a solution, as it performs spatial unwrapping for each echo instead. The computed B0 map is not corrected for remaining phase offsets.

For proper handling, the phase offsest can be removed using MCPC-3D-S with the option phase-offset-correction. This works for monopolar and bipolar data, already combined or uncombined channels. However, this requires "linear phase evolution". If the phase is already "corrupted" by other coil combination algorithms, it might not be possible to estimate and remove the phase offsets.

Help on arguments:

$ ./bin/romeo

usage: <PROGRAM> [-p PHASE] [-m MAGNITUDE] [-o OUTPUT]
                 [-t ECHO-TIMES [ECHO-TIMES...]] [-k MASK [MASK...]]
                 [-u] [-e UNWRAP-ECHOES [UNWRAP-ECHOES...]]
                 [-w WEIGHTS] [-B]
                 [--phase-offset-correction [PHASE-OFFSET-CORRECTION]]
                                  [--phase-offset-smoothing-sigma-mm PHASE-OFFSET-SMOOTHING-SIGMA-MM [PHASE-OFFSET-SMOOTHING-SIGMA-MM...]]
                 [--write-phase-offsets] [-i] [--template TEMPLATE]
                 [-N] [--no-rescale] [--threshold THRESHOLD] [-v] [-g]
                 [-q] [-Q] [-s MAX-SEEDS] [--merge-regions]
                 [--correct-regions] [--wrap-addition WRAP-ADDITION]
                 [--temporal-uncertain-unwrapping] [--version] [-h]

optional arguments:
  -p, --phase PHASE     The phase image that should be unwrapped
  -m, --magnitude MAGNITUDE
                        The magnitude image (better unwrapping if
                        specified)
  -o, --output OUTPUT   The output path or filename (default:
                        "unwrapped.nii")
  -t, --echo-times ECHO-TIMES [ECHO-TIMES...]
                        The echo times required for temporal
                        unwrapping specified in array or range syntax
                        (eg. "[1.5,3.0]" or "3.5:3.5:14"). For
                        identical echo times, "-t epi" can be used
                        with the possibility to specify the echo time
                        as e.g. "-t epi 5.3" (for B0 calculation).
  -k, --mask MASK [MASK...]
                        nomask | qualitymask <threshold> | robustmask
                        | <mask_file>. <threshold>=0.1 for qualitymask
                        in [0;1] (default: ["robustmask"])
  -u, --mask-unwrapped  Apply the mask on the unwrapped result. If
                        mask is "nomask", sets it to "robustmask".
  -e, --unwrap-echoes UNWRAP-ECHOES [UNWRAP-ECHOES...]
                        Load only the specified echoes from disk
                        (default: [":"])
  -w, --weights WEIGHTS
                        romeo | romeo2 | romeo3 | romeo4 | romeo6 |
                        bestpath | <4d-weights-file> | <flags>.
                        <flags> are up to 6 bits to activate
                        individual weights (eg. "1010"). The weights
                        are (1)phasecoherence
                        (2)phasegradientcoherence (3)phaselinearity
                        (4)magcoherence (5)magweight (6)magweight2
                        (default: "romeo")
  -B, --compute-B0      Calculate combined B0 map in [Hz]. This
                        activates MCPC3Ds phase offset correction
                        (monopolar) for multi-echo data.
  --phase-offset-correction [PHASE-OFFSET-CORRECTION]
                        on | off | bipolar. Applies the MCPC3Ds method
                        to perform phase offset determination and
                        removal (for multi-echo). "bipolar" removes
                        eddy current artefacts (requires >= 3 echoes).
                        (default: "off", without arg: "on")
  --phase-offset-smoothing-sigma-mm PHASE-OFFSET-SMOOTHING-SIGMA-MM [PHASE-OFFSET-SMOOTHING-SIGMA-MM...]
                        default: [7,7,7] Only applied if
                        phase-offset-correction is activated. The
                        given sigma size is divided by the voxel size
                        from the nifti phase file to obtain a
                        smoothing size in voxels. A value of [0,0,0]
                        deactivates phase offset smoothing (not
                        recommended).
  --write-phase-offsets
                        Saves the estimated phase offsets to the
                        output folder
  -i, --individual-unwrapping
                        Unwraps the echoes individually (not
                        temporal). This might be necessary if there is
                        large movement (timeseries) or
                        phase-offset-correction is not applicable.
  --template TEMPLATE   Template echo that is spatially unwrapped and
                        used for temporal unwrapping (type: Int64,
                        default: 1)
  -N, --no-mmap         Deactivate memory mapping. Memory mapping
                        might cause problems on network storage
  --no-rescale          Deactivate rescaling of input images. By
                        default the input phase is rescaled to the
                        range [-π;π]. This option allows inputting
                        already unwrapped phase images without
                        manually wrapping them first.
  --threshold THRESHOLD
                        <maximum number of wraps>. Threshold the
                        unwrapped phase to the maximum number of wraps
                        and sets exceeding values to 0 (type: Float64,
                        default: Inf)
  -v, --verbose         verbose output messages
  -g, --correct-global  Phase is corrected to remove global n2π phase
                        offset. The median of phase values (inside
                        mask if given) is used to calculate the
                        correction term
  -q, --write-quality   Writes out the ROMEO quality map as a 3D image
                        with one value per voxel
  -Q, --write-quality-all
                        Writes out an individual quality map for each
                        of the ROMEO weights.
  -s, --max-seeds MAX-SEEDS
                        EXPERIMENTAL! Sets the maximum number of seeds
                        for unwrapping. Higher values allow more
                        seperated regions. (type: Int64, default: 1)
  --merge-regions       EXPERIMENTAL! Spatially merges neighboring
                        regions after unwrapping.
  --correct-regions     EXPERIMENTAL! Performed after merging. Brings
                        the median of each region closest to 0 (mod
                        2π).
  --wrap-addition WRAP-ADDITION
                        [0;π] EXPERIMENTAL! Usually the true phase
                        difference of neighboring voxels cannot exceed
                        π to be able to unwrap them. This setting
                        increases the limit and uses 'linear
                        unwrapping' of 3 voxels in a line. Neighbors
                        can have (π + wrap-addition) phase difference.
                        (type: Float64, default: 0.0)
  --temporal-uncertain-unwrapping
                        EXPERIMENTAL! Uses spatial unwrapping on
                        voxels that have high uncertainty values after
                        temporal unwrapping.
  --version             show version information and exit
  -h, --help            show this help message and exit

Related Repositories

The sourcecode is available under ROMEO.jl.
The binaries are a standalone compiled version of RomeoApp.jl. The compilation scripts and recent releases are in CompileMRI.jl.

Known issues

v1.4

  • single echo unwrapping with magnitude and default mask leads to ReadOnlyMemory error. Fixed in v1.4.1
  • binary data type for mask not supported. Fixed in v2.0.1

v2.0.1

  • input scaling issue (with INT16). Fixed in v2.0.2

v3.1

  • quality map output is corrupted. Fixed in v3.1.1

MacOS

To run romeo executables on MacOS, multiple files have to be flagged as save to execute. Additionally, the executable might only run on specific OS versions. You can try the newest MacOS executable, v3.2.2 and v3.1. This problem is still unsolved and no clear way how to improve the compatibility

Issues when calling from MATLAB

libstdc++ error (libstdc++.so.6: version `GLIBCXX_3.4.29' not found)

Problem: ROMEO crashes with version conflicts of libstdc++ when called within MATLAB via unix() or system().
Reason: The libstdc++ library is already loaded in MATLAB, which causes a conflict if the version is older than what ROMEO expects.
Solution: Use LD_PRELOAD to specify the newer libstdc++ version before running matlab
Example:

$ export LD_PRELOAD=/<path-to-romeo>/mritools_Linux_3.3.5/lib/julia/libstc++.so
$ matlab

Segmentation fault (error code 139)

Problem: Similar to the above problem, matlab has already loaded an incompatible shared library. Solution:

$ export LD_PRELOAD=/<path-to-romeo>/mritools_Linux_3.3.5/lib/julia/libunwind.so
$ matlab 

or for multiple preload libraries

$ export LD_PRELOAD="/<path-to-romeo>/mritools_Linux_3.3.5/lib/julia/libstc++.so /<path-to-romeo>/mritools_Linux_3.3.5/lib/julia/libunwind.so"

Feedback

Feature requests and bug reports are welcome!

Note that the project description data, including the texts, logos, images, and/or trademarks, for each open source project belongs to its rightful owner. If you wish to add or remove any projects, please contact us at [email protected].