{"id":20132129,"url":"https://github.com/korbinian90/romeo","last_synced_at":"2025-07-23T11:04:59.622Z","repository":{"id":105747793,"uuid":"263740768","full_name":"korbinian90/ROMEO","owner":"korbinian90","description":"Executables for ROMEO unwrapping for Linux, Windows and Mac OSX","archived":false,"fork":false,"pushed_at":"2025-05-27T05:37:27.000Z","size":140,"stargazers_count":45,"open_issues_count":12,"forks_count":0,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-05-27T06:32:28.819Z","etag":null,"topics":["mri-images","mri-reconstruction","phase","qsm"],"latest_commit_sha":null,"homepage":"","language":null,"has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/korbinian90.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2020-05-13T20:53:27.000Z","updated_at":"2025-05-27T05:37:30.000Z","dependencies_parsed_at":null,"dependency_job_id":"5daa5b37-d019-489a-a1f3-8a367b9e4bd9","html_url":"https://github.com/korbinian90/ROMEO","commit_stats":null,"previous_names":[],"tags_count":21,"template":false,"template_full_name":null,"purl":"pkg:github/korbinian90/ROMEO","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/korbinian90%2FROMEO","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/korbinian90%2FROMEO/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/korbinian90%2FROMEO/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/korbinian90%2FROMEO/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/korbinian90","download_url":"https://codeload.github.com/korbinian90/ROMEO/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/korbinian90%2FROMEO/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":266665782,"owners_count":23964973,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-07-23T02:00:09.312Z","response_time":66,"last_error":null,"robots_txt_status":null,"robots_txt_updated_at":null,"robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["mri-images","mri-reconstruction","phase","qsm"],"created_at":"2024-11-13T20:52:34.161Z","updated_at":"2025-07-23T11:04:59.603Z","avatar_url":"https://github.com/korbinian90.png","language":null,"funding_links":[],"categories":[],"sub_categories":[],"readme":"# ROMEO Unwrapping\nUnwrapping of 3D and 4D datasets.\nCoil combination of 5D datasets.  \n\n![ROMEO](https://user-images.githubusercontent.com/1307522/144416428-0c51a0e5-cb07-4b7d-8571-9fa2dc33f580.png)\n\n## Get ROMEO\nOrdered from simple to more involved approaches.\n### Option 1: [Download standalone executable within mritools (Linux and Windows)](https://github.com/korbinian90/CompileMRI.jl/releases)\n**Download link for mritools as plain text: https://github.com/korbinian90/CompileMRI.jl/releases**  \n*Note: It might not work on every Linux distribution due to shared library incompatibilities (https://github.com/korbinian90/ROMEO/issues/16)*  \n*If a compiled MacOS version is required, see [Known-issues/MacOS](https://github.com/korbinian90/ROMEO#macos), but the suggested way is Option 2*\n\n### Option 2: [Julia command line usage](https://github.com/korbinian90/ROMEO.jl#usage---command-line) (every OS)\nIdentical usage to the standalone version with better compatibility.  \n1. Install julia\n2. Run [romeo.jl](https://github.com/korbinian90/ROMEO.jl/blob/master/romeo.jl) command line script\n\n### Option 3: Run in [Neurodesk](https://neurodesk.github.io/) (every OS)\nNeurodesk is an analysis environment for reproducible neuroimaging running in a docker container.\nIt comes with a range of useful tools preinstalled, including ROMEO.\n(https://neurodesk.github.io/)\n\n### Option 4: Use the julia package [ROMEO.jl](https://github.com/korbinian90/ROMEO.jl) (every OS) \nAll the flexibility, but requires handling phase offsets and B0 calculation yourself (see [MriResearchTools.jl](https://github.com/korbinian90/MriResearchTools.jl))\n\n### Option 5: Compile ROMEO (every OS)\nFollow the steps in https://github.com/korbinian90/CompileMRI.jl\n\n## Publication\n**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\n\n**MCPC-3D-S Coil Combination**:\nEckstein, 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\n\n## Getting Started\n### Prerequisites\nPhase (and optionally Magnitude) images in NIfTI fileformat.  \nFor multi-echo/multi-timepoint data, 4D-NIfTI files are used with echoes/timepoints in the 4th dimension.   \nIndividual 3D files can be merged into 4D files using [fslmerge](https://fsl.fmrib.ox.ac.uk/fsl/fslwiki/Fslutils).  \nIf 5D-NIfTI datasets with channels in the 5th dimension are given, coil combination is performed as first step. \n\n### Run ROMEO\nROMEO is a command line application. The binary is in the folder `mritools/bin`\n\nExample usage for B0-mapping with a 5-echo scan with TE = [3,6,9,12,15] ms:  \n`$ romeo ph.nii -m mag.ii -B -t 3:3:15 -o outputdir`\n\nExample usage for single-echo data:  \n`$ romeo ph.nii -m mag.ii -k nomask -o outputdir`\n\nExample for multiple time points with identical echo time (fMRI):  \n`$ romeo ph.nii -m mag.ii -k nomask -t epi -o outputdir`\n\nExample usage for a 3-echo scan with TE = [3,6,9] ms:  \n`$ romeo ph.nii -m mag.ii -t [3,6,9] -o outputdir`\n\nNote that echo times are required for unwrapping multi-echo data.\n\n## Different Use Cases\n### Multi-Echo\nIf multi-echo data is available, supplying ROMEO with multi-echo information should improve the unwrapping accuracy. The same is true for magnitude information. To calculate a B0 map in Hz, the echo time needs to be given in ms.\n\n### Coil Combination\nCoil 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 \u003e= 3 echoes).\n\n### Repeated Measurements (EPI)\n4D 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`.\n\n### Setting the Template Echo\nIn 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.  \nWith the optional argument `--template 2`, this can be changed to the second (or any other) echo/time-point.\n\n### Phase Offsets\nIf 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.\n\nFor 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.\n\n### Disconnected Regions\nFor datasets with disconnected regions, the `--max-seeds`, `--correct-regions` and `--merge-regions` options might be of interest.\n\nThe option `--max-seeds` creates multiple regions, which are unwrapped independently. The detected regions are written to the output file `regions.nii`.\n\n### Fat and Water - Multi-Echo\nFor acquisitions, in which fat and water signals mix, the assumption of *linear phase evolution* might be broken. Both temporal unwrapping and MCPC-3D-S phase offset removal depend on linear phase evolution and might produce incorrect results, leading to multi-echo unwrapping problems and remaining phase offsets in the resulting B0 map.\n\nUsing the `--individual-unwrapping` flag might improve the unwrapping performance by disabling temporal unwrapping. Still, a calculated B0 map might contain unwanted phase offsets.\n\n## Common Pitfalls\n### Phase Input\nThe input data is automatically rescaled to [-π;π]. For example, the input data can be given from [0;4095], which is rescaled to the range [-π;π]. In case the data is already in radians, this can be deactivated using the flag `--no-rescale`. This might be necessary for phase difference data, where calculating the phase difference increases the range to [-2π;2π], but no rescaling to [-π;π] should occur.\n\n## Help on arguments:\n```\n$ ./bin/romeo\n\nusage: \u003cPROGRAM\u003e [-p PHASE] [-m MAGNITUDE] [-o OUTPUT]\n                 [-t ECHO-TIMES [ECHO-TIMES...]] [-k MASK [MASK...]]\n                 [-u] [-e UNWRAP-ECHOES [UNWRAP-ECHOES...]]\n                 [-w WEIGHTS] [-B [COMPUTE-B0]]\n                 [--B0-phase-weighting B0-PHASE-WEIGHTING]\n                 [--phase-offset-correction [PHASE-OFFSET-CORRECTION]]\n                 [--phase-offset-smoothing-sigma-mm PHASE-OFFSET-SMOOTHING-SIGMA-MM [PHASE-OFFSET-SMOOTHING-SIGMA-MM...]]\n                 [--write-phase-offsets] [-i] [--template TEMPLATE]\n                 [-N] [--no-phase-rescale] [--fix-ge-phase]\n                 [--threshold THRESHOLD] [-v] [-g] [-q] [-Q]\n                 [-s MAX-SEEDS] [--merge-regions] [--correct-regions]\n                 [--wrap-addition WRAP-ADDITION]\n                 [--temporal-uncertain-unwrapping [TEMPORAL-UNCERTAIN-UNWRAPPING]]\n                 [--version] [-h]\n\noptional arguments:\n  -p, --phase PHASE     The phase image that should be unwrapped\n  -m, --magnitude MAGNITUDE\n                        The magnitude image (better unwrapping if\n                        specified)\n  -o, --output OUTPUT   The output path or filename (default:\n                        \"unwrapped.nii\")\n  -t, --echo-times ECHO-TIMES [ECHO-TIMES...]\n                        The echo times in [ms] required for temporal\n                        unwrapping specified in array or range syntax\n                        (eg. \"[1.5,3.0]\" or \"3.5:3.5:14\"). For\n                        identical echo times, \"-t epi\" can be used\n                        with the possibility to specify the echo time\n                        as e.g. \"-t epi 5.3\" (for B0 calculation).\n  -k, --mask MASK [MASK...]\n                        nomask | qualitymask \u003cthreshold\u003e | robustmask\n                        | \u003cmask_file\u003e. \u003cthreshold\u003e=0.1 for qualitymask\n                        in [0;1] (default: Any[\"robustmask\"])\n  -u, --mask-unwrapped  Apply the mask on the unwrapped result. If\n                        mask is \"nomask\", sets it to \"robustmask\".\n  -e, --unwrap-echoes UNWRAP-ECHOES [UNWRAP-ECHOES...]\n                        Load only the specified echoes from disk\n                        (default: Any[\":\"])\n  -w, --weights WEIGHTS\n                        romeo | romeo2 | romeo3 | romeo4 | romeo6 |\n                        bestpath | \u003c4d-weights-file\u003e | \u003cflags\u003e.\n                        \u003cflags\u003e are up to 6 bits to activate\n                        individual weights (eg. \"1010\"). The weights\n                        are (1)phasecoherence\n                        (2)phasegradientcoherence (3)phaselinearity\n                        (4)magcoherence (5)magweight (6)magweight2\n                        (default: \"romeo\")\n  -B, --compute-B0 [COMPUTE-B0]\n                        Calculate combined B0 map in [Hz]. Supports\n                        the B0 output filename as optional input. This\n                        activates MCPC3Ds phase offset correction\n                        (monopolar) for multi-echo data. (default: \"\",\n                        without arg: \"B0\")\n  --B0-phase-weighting B0-PHASE-WEIGHTING\n                        phase_snr | phase_var | average | TEs | mag |\n                        simulated_mag Set the weighting for the B0\n                        calculation. (default: \"phase_snr\")\n  --phase-offset-correction [PHASE-OFFSET-CORRECTION]\n                        on | off | bipolar. Applies the MCPC3Ds method\n                        to perform phase offset determination and\n                        removal (for multi-echo). \"bipolar\" removes\n                        eddy current artefacts (requires \u003e= 3 echoes).\n                        (default: \"default off\", without arg: \"on\")\n  --phase-offset-smoothing-sigma-mm PHASE-OFFSET-SMOOTHING-SIGMA-MM [PHASE-OFFSET-SMOOTHING-SIGMA-MM...]\n                        default: [7,7,7] Only applied if\n                        phase-offset-correction is activated. The\n                        given sigma size is divided by the voxel size\n                        from the nifti phase file to obtain a\n                        smoothing size in voxels. A value of [0,0,0]\n                        deactivates phase offset smoothing (not\n                        recommended).\n  --write-phase-offsets\n                        Saves the estimated phase offsets to the\n                        output folder\n  -i, --individual-unwrapping\n                        Unwraps the echoes individually (not\n                        temporal). This might be necessary if there is\n                        large movement (timeseries) or\n                        phase-offset-correction is not applicable.\n  --template TEMPLATE   Template echo that is spatially unwrapped and\n                        used for temporal unwrapping (type: Int64,\n                        default: 1)\n  -N, --no-mmap         Deactivate memory mapping. Memory mapping\n                        might cause problems on network storage\n  --no-phase-rescale, --no-rescale\n                        Deactivate rescaling of input images. By\n                        default the input phase is rescaled to the\n                        range [-π;π]. This option allows inputting\n                        already unwrapped phase images without\n                        manually wrapping them first.\n  --fix-ge-phase        GE systems write corrupted phase output (slice\n                        jumps). This option fixes the phase problems.\n  --threshold THRESHOLD\n                        \u003cmaximum number of wraps\u003e. Threshold the\n                        unwrapped phase to the maximum number of wraps\n                        and sets exceeding values to 0 (type: Float64,\n                        default: Inf)\n  -v, --verbose         verbose output messages\n  -g, --correct-global  Phase is corrected to remove global n2π phase\n                        offset. The median of phase values (inside\n                        mask if given) is used to calculate the\n                        correction term. This also corrects multi-echo\n                        phase for individual unwrapping, and might\n                        require MCPC3Ds phase offset correction.\n  -q, --write-quality   Writes out the ROMEO quality map as a 3D image\n                        with one value per voxel\n  -Q, --write-quality-all\n                        Writes out an individual quality map for each\n                        of the ROMEO weights.\n  -s, --max-seeds MAX-SEEDS\n                        EXPERIMENTAL! Sets the maximum number of seeds\n                        for unwrapping. Higher values allow more\n                        seperated regions. (type: Int64, default: 1)\n  --merge-regions       EXPERIMENTAL! Spatially merges neighboring\n                        regions after unwrapping.\n  --correct-regions     EXPERIMENTAL! Performed after merging. Brings\n                        the median of each region closest to 0 (mod\n                        2π).\n  --wrap-addition WRAP-ADDITION\n                        [0;π] EXPERIMENTAL! Usually the true phase\n                        difference of neighboring voxels cannot exceed\n                        π to be able to unwrap them. This setting\n                        increases the limit and uses 'linear\n                        unwrapping' of 3 voxels in a line. Neighbors\n                        can have (π + wrap-addition) phase difference.\n                        (type: Float64, default: 0.0)\n  --temporal-uncertain-unwrapping [TEMPORAL-UNCERTAIN-UNWRAPPING]\n                        EXPERIMENTAL! Uses spatial unwrapping on\n                        voxels that have low quality values after\n                        temporal unwrapping. A higher threshold leads\n                        to more voxels being spatially unwrapped. The\n                        range of the threshold is [0;1] (type:\n                        Float64, default: 0.0, without arg: 0.5)\n  --version             show version information and exit\n  -h, --help            show this help message and exit\n```\n\n## Related Repositories\nThe sourcecode is available under [ROMEO.jl](https://github.com/korbinian90/ROMEO.jl).  \nThe binaries are a standalone compiled version of [RomeoApp.jl](https://github.com/korbinian90/RomeoApp.jl). The compilation scripts and recent releases are in [CompileMRI.jl](https://github.com/korbinian90/CompileMRI.jl).\n\n## Known issues\n### v1.4\n- single echo unwrapping with magnitude and default mask leads to ReadOnlyMemory error. Fixed in v1.4.1\n- binary data type for mask not supported. Fixed in v2.0.1\n### v2.0.1\n- input scaling issue (with INT16). Fixed in v2.0.2\n### v3.1\n- quality map output is corrupted. Fixed in v3.1.1\n### MacOS\nTo 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](https://github.com/korbinian90/CompileMRI.jl/releases) MacOS executable, [v3.2.2](https://github.com/korbinian90/ROMEO/releases/tag/v3.2.2) and [v3.1](https://github.com/korbinian90/ROMEO/releases/tag/v3.1). This problem is still unsolved and no clear way how to improve the compatibility. Please look at the different ways to run it on MacOS above.\n\n### Issues when calling from MATLAB  \n\n- `libstdc++` error (libstdc++.so.6: version `GLIBCXX_3.4.29' not found)  \n- Segmentation fault (error code 139)  \n\nProblem: ROMEO crashes with version conflicts of shared dependencies when called within MATLAB via `unix()` or `system()`.  \nReason: MATLAB runs other programs with a [modified environment variable](https://discourse.julialang.org/t/ann-juliafrommatlab-jl-call-julia-from-matlab/66882/2)  \nSolution: clean LD_LIBRARY_PATH before execution and restore it afterwards  \nExample:  \n```matlab\n% remove matlab specific LD_LIBRARY_PATH\nif isunix; paths = getenv('LD_LIBRARY_PATH'); setenv('LD_LIBRARY_PATH'); end\nsuccess = system(\u003cromeo call\u003e);\n% restore paths\nif isunix; setenv('LD_LIBRARY_PATH', paths); end\n```\n\n## Feedback\nFeature requests and bug reports are welcome!\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkorbinian90%2Fromeo","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkorbinian90%2Fromeo","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkorbinian90%2Fromeo/lists"}