Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/dipterix/threebrain
3D Visualization of Brain MRI
https://github.com/dipterix/threebrain
brain ecog electroencephalography ieeg localization mri-brain neuroimaging r template-brains
Last synced: about 1 month ago
JSON representation
3D Visualization of Brain MRI
- Host: GitHub
- URL: https://github.com/dipterix/threebrain
- Owner: dipterix
- License: other
- Created: 2019-03-05T16:59:20.000Z (almost 6 years ago)
- Default Branch: master
- Last Pushed: 2024-03-15T16:43:06.000Z (11 months ago)
- Last Synced: 2024-03-17T14:11:11.370Z (11 months ago)
- Topics: brain, ecog, electroencephalography, ieeg, localization, mri-brain, neuroimaging, r, template-brains
- Language: R
- Homepage: https://dipterix.org/threeBrain/
- Size: 114 MB
- Stars: 37
- Watchers: 1
- Forks: 9
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# [threeBrain - HTML, WebGL based 3D Viewer](https://dipterix.org/threeBrain/index.html)
[](https://cran.r-project.org/package=threeBrain)
[](https://github.com/dipterix/threeBrain/actions/workflows/R-CMD-check.yaml)
[](https://www.repostatus.org/#active)
[](https://doi.org/10.1016/j.neuroimage.2020.117341)
[](https://doi.org/10.1523/ENEURO.0328-23.2023)
[
](https://youtu.be/dSxJqBiw3sk)
**Key Features**:
* Uses modern browsers, easy to **embed** and **share**
* Displays MRI, surfaces, and electrodes in the same canvas
* **Maps multiple subjects** on template brains using `AFNI/SUMA` (standard 141) or `MNI-305` locations
* **Electrode localization**
* Volume rendering and surface/electrode **animation**
* Integration with interactive `R-shiny` framework
[News](https://dipterix.org/threeBrain/news/index.html) | [reference page](https://dipterix.org/threeBrain/reference/index.html) | [keyboard shortcuts](https://dipterix.org/threeBrain/shortcuts.html)
#### System Requirement
* **Web Browsers**: the viewer uses `WegGL2` to render in browsers. Please check [this list](https://caniuse.com/webgl2) to see compatible browsers. As of 2023, **Chrome**, **Firefox**, **Safari**, and **Edge** (not IE) have full supports.
## A. Installation
1. [`R`](https://cran.r-project.org/) and [`RStudio Desktop (Free Version)`](https://posit.co/download/rstudio-desktop/)
2. Open `RStudio`, enter from its console:
```r
install.packages("threeBrain", repos = "https://rave-ieeg.r-universe.dev")
```
If you want to install `dev` version from *Github*, then use:
```r
install.packages("remotes")
remotes::install_github("dipterix/threeBrain")
```
3. (Optional) Setups: after installation, in `RStudio` console, type the following command
```r
threeBrain::brain_setup()
```
and follow the instructions.
## B. Basic Brain Viewer
Once finishing setting up of `threeBrain`, there will be a template subject `N27` (Collin's 27) created locally. The location is platform-related. You can find it by running the following command:
```r
library(threeBrain)
default_template_directory()
#> [1] "/Users/dipterix/Library/Application Support/
#> org.R-project.R/R/threeBrain/templates"
```
**N27** template folder resides inside of this directory.
Let's view this subject using the `threeBrain` function.
1. Import subject
```r
library(threeBrain)
n27_path <- file.path(default_template_directory(), "N27")
x <- threeBrain( path = n27_path,
subject_code = 'N27', surface_types = 'pial')
```
2. Visualize
```r
plot(x) # alternatively, you can use x$plot()`
```
## C. Subject Setup
The sample subject (`N27`) is a sample generated by `FreeSurfer` ([download](https://surfer.nmr.mgh.harvard.edu/fswiki/DownloadAndInstall)). If you have any subjects processed by `FreeSurfer`, use function `threeBrain` to visualize.
## D. Add/Render Electrodes
If you have electrode file, you can import it before calling `plot` function. Please make sure it's in `csv` format.
```r
x$set_electrodes(electrodes = "[PATH to ELECTRODE FILE]")
```
Here is an example of electrode csv file. Only the first five columns (**case-sensitive**) are mandatory: `Electrode (integer)`, `Coord_x`, `Coord_y`, `Coord_z`, and `Label (character)`. `Coord_*` is `tkRAS` location from `FreeSurfer` coordinates.
```
| Electrode| Coord_x| Coord_y| Coord_z|Label | MNI305_x| MNI305_y| MNI305_z|SurfaceElectrode |SurfaceType | Radius| VertexNumber|Hemisphere |
|---------:|-------:|-------:|-------:|:------|--------:|---------:|---------:|:----------------|:-----------|------:|------------:|:----------|
| 1| 29.0| -7.8| -34.6|RMHCH1 | 30.46817| -17.98119| -23.40022|FALSE |pial | 2| -1|left |
| 2| 33.8| -8.0| -34.2|RMHCH2 | 35.57109| -17.76624| -22.80131|FALSE |pial | 2| -1|left |
| 3| 38.0| -7.5| -33.5|RMHCH3 | 39.97102| -16.81249| -22.17986|FALSE |white | 2| -1|right |
| 4| 42.6| -6.8| -33.0|RMHCH4 | 44.79092| -15.73442| -21.82591|FALSE |smoothwm | 2| -1|right |
| 5| 47.0| -6.8| -32.6|RMHCH5 | 49.45370| -15.35431| -21.31272|FALSE |pial | 2| -1|right |
| ...
```
To assign values to electrodes, run
```r
x$set_electrode_values(electrodes = "[PATH to ELECTRODE VALUE FILE]")
```
The electrode value file is also a csv like:
```
| Electrode| Subject| Project| Time| ValueName| ValueName2| ...|
|---------:|-------:|-------:|-------:|:---------|----------:|-----|
| 1| N27| Demo| 0|A | 30.46817| ...|
| 2| N27| Demo| 0|B | 35.57109| ...|
| 3| N27| Demo| 0|C | 39.97102| ...|
| 4| N27| Demo| 0|D | 44.79092| ...|
| 5| N27| Demo| 0|A | 49.45370| ...|
| ...
```
`Project` and `Time` are optional. However, if you are also using [`rave`](https://github.com/beauchamplab/rave), please make sure `Project` exists. If you want to show animation, `Time` is necessary and must be numeric. `ValueName?` can be any characters containing letters (`A-Z`, `a-z`), letters (`0-9`) and underscore (`_`).
## E. Merge Subjects and Template mapping
If you have your own subjects with `FreeSurfer` output, for example, I have two subjects `YAB` and `YCQ`. To merge these two subjects and show them on `N27` template,
```r
library(threeBrain)
# yab = ... (see section B for import a single subject)
# ycq = ...
template_n27 = merge_brain(yab, ycq, template_subject = 'N27')
plot( template_n27 )
```
The viewer will be in `N27` template, and electrodes of these two subjects can be mapped via `MNI305` (for surface and stereo EEG) or `std.141` (for surface-only).
## F. Electrode Localization (`YAEL`)
[YAEL ("Your Advanced Electrode Localizer)](https://doi.org/10.1523/ENEURO.0328-23.2023) has been integrated into [RAVE (R Analysis and Visualization of iEEG)](https://openwetware.org/wiki/RAVE). Please check our website https://yael.wiki
[Here is a `sfN` poster](https://www.dropbox.com/s/st0cw1aro4kmo2e/2022-poster-sfN-Zhengjia-RAVE_poster-07Nov22.pdf?dl=0)
## Citation
To cite `threeBrain` in publications use:
* Wang, Z., Magnotti, J. F., Zhang, X., & Beauchamp, M. S. (2023). YAEL: Your Advanced Electrode Localizer. Eneuro, 10(10).
* Magnotti, J. F., Wang, Z., & Beauchamp, M. S. (2020). RAVE: Comprehensive open-source software for reproducible analysis and visualization of intracranial EEG data. NeuroImage, 223, 117341.
A BibTeX entry for LaTeX users:
```
@Article{,
title = {{YAEL}: Your Advanced Electrode Localizer},
author = {Zhengjia Wang and John F. Magnotti and Xiang Zhang and Michael S. Beauchamp},
journal = {Eneuro},
year = {2023},
volume = {10},
number = {10},
publisher = {Society for Neuroscience},
doi = {10.1523/ENEURO.0328-23.2023},
}
@Article{,
title = {{RAVE}: Comprehensive open-source software for reproducible analysis and visualization of intracranial EEG data},
author = {John F. Magnotti and Zhengjia Wang and Michael S. Beauchamp},
journal = {NeuroImage},
year = {2020},
volume = {223},
doi = {10.1016/j.neuroimage.2020.117341},
pages = {117341},
}
```
## License
The front-end viewer (JavaScript) is licensed under MPL-2.0 free open-source license. Using the generated viewers or incorporating the existing viewers as a whole into your own work "as-is" is permissive.