Skip to content

Commit

Permalink
Merge pull request #14 from FZJ-INM1-BDA/develop
Browse files Browse the repository at this point in the history
Merge develop into main
  • Loading branch information
JThoennissen authored Jul 14, 2023
2 parents b3e7d0f + 2770b91 commit 753ad26
Show file tree
Hide file tree
Showing 49 changed files with 2,916 additions and 783 deletions.
25 changes: 25 additions & 0 deletions .zenodo.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,25 @@
{
"creators": [
{
"affiliation": "Institute of Neuroscience and Medicine (INM-1), Forschungszentrum Jülich, Germany",
"name": "Thönnißen, Julia",
"orcid": "0000-0002-5467-871X"
},
{
"affiliation": "Institute of Neuroscience and Medicine (INM-1), Forschungszentrum Jülich, Germany",
"name": "Dickscheid, Timo",
"orcid": "0000-0002-9051-3701"
}
],
"license": "Apache-2.0",
"title": "voluba-mriwarp: Integration of whole-brain MRI scans into multilevel brain atlases",
"description": "voluba-mriwarp is a desktop application that integrates whole-brain T1-weighted MRI scans into the anatomical context of the EBRAINS Human Brain Atlas. It incorporates all required components like skull stripping, registration to MNI ICBM 152 2009c Nonlinear Asymmetric space, and detailed analysis with the siibra toolsuite. The corresponding functionalities are provided via open-source tools like HD-BET, ANTs and siibra-python. voluba-mriwarp is primarily designed for Windows 10 but can also be executed on Linux.\nWarping brain data to a standardized space like MNI152 enables anchoring of whole-brain MRI scans to atlas volumes and therefore facilitates analysis in a detailed anatomical context. However, reasonable registration requires various steps that need optimization effort. _voluba-mriwarp_ aims to simplify this workflow. With this application, you avoid installing multiple tools and tweaking parameters for a proper registration result. Instead, _voluba-mriwarp_ is an easy-to-install and easy-to-use tool combining all necessary steps into one pipeline.\napplies a set of predefined parameters to remove the skull and warp the input brain scan to MNI152 space. You can utilize the warping results in _voluba-mriwarp_ to interactively analyze points by making a probabilistic assignment of coordinates in the input space to brain regions of the EBRAINS Human Brain Atlas. To get an overview of more information about a brain region, you can access siibra-explorer through the application. For further analysis, _voluba-mriwarp_ offers to export the anatomical assignments together with linked multimodal data features like receptor densities, cell distributions or brain connectivity.",
"keywords": [
"neuroimaging",
"skull stripping",
"image registration",
"brain atlases",
"mri scans"
],
"upload_type": "software"
}
26 changes: 8 additions & 18 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,24 +1,16 @@
> **A new release of voluba-mriwarp is planned until 14.07.2023 including the following features:**
- specify your own warping parameters
- choose between different parcellations
- specify a point uncertainty
- select and save multiple points
- export assignments together with linked features into a PDF report


# voluba-mriwarp

> **Note: _voluba-mriwarp_ is still in development. You may still encounter bugs when using it.**
VoluBA (**Volu**metric **B**rain **A**nchoring) offers tools to connect volumetric imaging data to multilevel atlases and in this way makes it accessible for analysis with the siibra toolsuite.

_voluba-mriwarp_ is a desktop application that integrates whole brain T1-weighted MRI scans into the anatomical context of the [Julich Brain Atlas](https://julich-brain-atlas.de/). It incorporates all required components like skull stripping, registration to [ICBM MNI152 2009c nonlinear asymmetric space](https://www.bic.mni.mcgill.ca/ServicesAtlases/ICBM152NLin2009), and detailed analysis with the siibra toolsuite. The corresponding functionalities are provided via open-source tools like [HD-BET](https://github.com/MIC-DKFZ/HD-BET)[^1], [ANTs](http://stnava.github.io/ANTs/) and [siibra-python](https://github.com/FZJ-INM1-BDA/siibra-python). _voluba-mriwarp_ is primarily designed for Windows 10 but can also be executed on Linux.
voluba (**Volu**metric **B**rain **A**nchoring) offers tools to connect volumetric imaging data to multilevel atlases and in this way makes it accessible for analysis with the siibra toolsuite.

Warping brain data to a standardized space like MNI152 enables anchoring of whole brain MRI scans to atlas volumes like [BigBrain](https://julich-brain-atlas.de/atlas/bigbrain). However, reasonable registration requires various steps that need optimization effort. _voluba-mriwarp_ aims to simplify this workflow. With this application, you avoid installing multiple tools and tweaking parameters for a proper registration result. Instead, _voluba-mriwarp_ is an easy-to-install and easy-to-use tool combining all necessary steps into one pipeline.
_voluba-mriwarp_ is a desktop application that integrates whole-brain T1-weighted MRI scans into the anatomical context of the [EBRAINS Human Brain Atlas](https://www.ebrains.eu/tools/human-brain-atlas). It incorporates all required components like skull stripping, registration to [MNI ICBM 152 2009c Nonlinear Asymmetric space](https://www.bic.mni.mcgill.ca/ServicesAtlases/ICBM152NLin2009), and detailed analysis with the siibra toolsuite. The corresponding functionalities are provided via open-source tools like [HD-BET](https://github.com/MIC-DKFZ/HD-BET)[^1], [ANTs](http://stnava.github.io/ANTs/) and [siibra-python](https://github.com/FZJ-INM1-BDA/siibra-python). _voluba-mriwarp_ is primarily designed for Windows 10 but can also be executed on Linux.

> We designed _voluba-mriwarp_ as a desktop application. Therefore, **the input MRI dataset will not be uploaded to any online services**. It remains only on your local computer.
_voluba-mriwarp_ applies a set of predefined parameters to remove the skull and warp the input brain scan to MNI152 space. You can utilize the warping results in _voluba-mriwarp_ to interactively assign brain regions to a point in the input space. Select a location in the displayed brain of a subject to perform a probabilistic assignment using Julich-Brain Cytoarchitectonic Maps 2.9. Hence, you can estimate the probability of a brain region occurring at the selected point. To explore even more information about a cytoarchitectonic area, you can access [siibra-explorer](https://atlases.ebrains.eu/viewer/human) through the application.
Warping brain data to a standardized space like MNI152 enables anchoring of whole-brain MRI scans to atlas volumes and therefore facilitates analysis in a detailed anatomical context. However, reasonable registration requires various steps that need optimization effort. _voluba-mriwarp_ aims to simplify this workflow. With this application, you avoid installing multiple tools and tweaking parameters for a proper registration result. Instead, _voluba-mriwarp_ is an easy-to-install and easy-to-use tool combining all necessary steps into one pipeline.

_voluba-mriwarp_ applies a set of predefined parameters to remove the skull and warp the input brain scan to MNI152 space. You can utilize the warping results in _voluba-mriwarp_ to interactively analyze points by making a probabilistic assignment of coordinates in the input space to brain regions of the [EBRAINS Human Brain Atlas](https://www.ebrains.eu/tools/human-brain-atlas). To get an overview of more information about a brain region, you can access [siibra-explorer](https://atlases.ebrains.eu/viewer/human) through the application. For further analysis, _voluba-mriwarp_ offers to export the anatomical assignments together with linked multimodal data features like receptor densities, cell distributions or brain connectivity.

![image](docs/images/teaser.png)

Expand All @@ -30,7 +22,7 @@ _voluba-mriwarp_ is designed as a Windows application but can also be executed o

#### Install voluba-mriwarp

1. Download the installer [here](https://fz-juelich.sciebo.de/s/GPbDWgkmvsQNq5G/download).
1. Download the installer [here](https://github.com/FZJ-INM1-BDA/voluba-mriwarp/releases/download/v0.2.0/installer.exe).
2. Run the installer.
3. Run _voluba-mriwarp_ directly from the installer. Depending on the installation settings you have chosen, you can also run _voluba-mriwarp_ from the installation directory, the start menu or the desktop shortcut.

Expand All @@ -45,7 +37,7 @@ Hint: The default installation directory is `C:\Users\your_username\AppData\Loca
#### Requirements

* Python 3.8 or higher
* [ANTs](https://github.com/ANTsX/ANTs/wiki/Compiling-ANTs-on-Linux-and-Mac-OS)
* [ANTs Eotapinoma](https://github.com/ANTsX/ANTs/releases/tag/v2.4.4)

#### Install voluba-mriwarp

Expand Down Expand Up @@ -86,12 +78,10 @@ This project is licensed under the Apache License 2.0 - see the LICENSE file for

* [HD-BET](https://github.com/MIC-DKFZ/HD-BET)[^1] (skull removal)
* [ANTs](http://stnava.github.io/ANTs/) (warping)
* [siibra-python](https://github.com/FZJ-INM1-BDA/siibra-python) (region assignment)
* [siibra-python](https://github.com/FZJ-INM1-BDA/siibra-python) (analysis in atlas context)

[^1]: Isensee F, Schell M, Tursunova I, Brugnara G, Bonekamp D, Neuberger U, Wick A, Schlemmer HP, Heiland S, Wick W, Bendszus M, Maier-Hein KH, Kickingereder P. Automated brain extraction of multi-sequence MRI using artificial neural networks. Hum Brain Mapp. 2019; 1–13. [https://doi.org/10.1002/hbm.24750](https://doi.org/10.1002/hbm.24750)

## Acknowledgments

This software code is funded from the European Union’s Horizon 2020 Framework Programme for Research and Innovation under the Specific Grant Agreement No. 945539 (Human Brain Project SGA3).

![image](./data/hbp_ebrains_color_dark.png)
Binary file removed data/hbp_ebrains_color.png
Binary file not shown.
37 changes: 37 additions & 0 deletions data/parameters/default.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,37 @@
{
"command": {
"verbose": "1",
"dimensionality": "3",
"use-histogram-matching": "0",
"winsorize-image-intensities": "[0.005,0.995]",
"masks": "[NULL,MASK]",
"float": "1",
"interpolation": "Linear",
"output": "[TRANSFORM,VOLUME]",
"write-composite-transform": "1",
"collapse-output-transforms": "1",
"stages": [
{
"transform": "Rigid[0.1]",
"metric": "MI[FIXED,MOVING,1,32,Regular,0.25]",
"convergence": "[1000x500x250x0,1e-6,10]",
"smoothing-sigmas": "4x3x2x1vox",
"shrink-factors": "12x8x4x2"
},
{
"transform": "Affine[0.1]",
"metric": "MI[FIXED,MOVING,1,32,Regular,0.25]",
"convergence": "[1000x500x250x0,1e-6,10]",
"smoothing-sigmas": "4x3x2x1vox",
"shrink-factors": "12x8x4x2"
},
{
"transform": "Syn[0.1,3,0]",
"metric": "MI[FIXED,MOVING,1,32]",
"convergence": "[100x100x70x50x0,1e-6,10]",
"smoothing-sigmas": "5x3x2x1x0vox",
"shrink-factors": "10x6x4x2x1"
}
]
}
}
55 changes: 55 additions & 0 deletions data/parameters/optimised.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,55 @@
{
"linear": {
"verbose": "1",
"dimensionality": "3",
"use-histogram-matching": "0",
"winsorize-image-intensities": "[0.005,0.995]",
"interpolation": "Linear",
"output": "[OUTPATH/linear_NAME_transformation,OUTPATH/linear_NAME_registered.nii.gz]",
"stages": [
{
"transform": "Rigid[0.1]",
"metric": "GC[FIXED,MOVING,1,,Regular,0.25]",
"convergence": "[1000x500x250x100,1e-6,10]",
"shrink-factors": "8x4x2x1",
"smoothing-sigmas": "3x2x1x0vox",
"masks": "[NULL,MASK]"
},
{
"transform": "Affine[0.1]",
"metric": "GC[FIXED,MOVING,1,,Regular,0.25]",
"convergence": "[1000x500x250x100,1e-6,10]",
"shrink-factors": "8x4x2x1",
"smoothing-sigmas": "3x2x1x0vox",
"masks": "[NULL,MASK]"
},
{
"transform": "Affine[0.1]",
"metric": "GC[FIXED,MOVING,1,,Regular,0.25]",
"convergence": "[1000x500x250x100,1e-6,10]",
"shrink-factors": "8x4x2x1",
"smoothing-sigmas": "3x2x1x0vox",
"masks": "[NULL,MASK]"
}
]
},
"nonlinear": {
"verbose": "1",
"dimensionality": "3",
"use-histogram-matching": "1",
"winsorize-image-intensities": "[0.005,0.995]",
"interpolation": "Linear",
"output": "[OUTPATH/nonlinear_NAME_transformation,OUTPATH/nonlinear_NAME_registered.nii.gz]",
"stages": [
{
"transform": "SyN[0.2]",
"metric": "CC[FIXED,MOVING,1,4,None,1]",
"convergence": "[100x100x100x50,1e-6,10]",
"shrink-factors": "4x2x1x1",
"smoothing-sigmas": "2x1x1x0vox",
"masks": "[NULL,MASK]",
"initial-moving-transform": "OUTPATH/linear_NAME_transformation0GenericAffine.mat"
}
]
}
}
6 changes: 0 additions & 6 deletions docs/acknowledgement.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,12 +5,6 @@ It has been designed for the [EBRAINS](https://ebrains.eu) infrastructure for br

_voluba-mriwarp_ has received funding from the European Union’s Horizon 2020 Framework Programme for Research and Innovation under the Specific Grant Agreement No. 945539 (Human Brain Project SGA3).

[![logo_centered](images/FZJ_logo.png)](https://www.fz-juelich.de/en)

[![logo](images/EBRAINS_logo.png)](https://ebrains.eu)
[![logo](images/HBP_logo.png)](https://humanbrainproject.eu/en/)
![logo](images/EU_logo.jpg)

<h1>References</h1>

* [HD-BET](https://github.com/MIC-DKFZ/HD-BET)[^1] (skull removal)
Expand Down
Loading

0 comments on commit 753ad26

Please sign in to comment.