threeBrain

KO | EN

gitlite — search

#javascript #python #hacktoberfest #react #ai #typescript #llm #go #golang #android #machine-learning #rust #deep-learning #linux

★ 50 Open GitHub ↗

3D Visualization of Brain MRI

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# [threeBrain - HTML, WebGL based 3D Viewer](https://dipterix.org/threeBrain/index.html)

[![CRAN_Status_Badge](https://www.r-pkg.org/badges/version/threeBrain)](https://cran.r-project.org/package=threeBrain)
[![R-CMD-check](https://github.com/dipterix/threeBrain/actions/workflows/R-CMD-check.yaml/badge.svg)](https://github.com/dipterix/threeBrain/actions/workflows/R-CMD-check.yaml)
[![Project Status: Active – The project has reached a stable, usable state and is being actively developed.](https://www.repostatus.org/badges/latest/active.svg)](https://www.repostatus.org/#active)
[![DOI-RAVE](https://raw.githubusercontent.com/dipterix/threeBrain/master/inst/doi.svg)](https://doi.org/10.1016/j.neuroimage.2020.117341)
[![DOI-YAEL](https://img.shields.io/badge/DOI-10.1523%2FENEURO.0328--23.2023-blue?link=https%3A%2F%2Fdoi.org%2F10.1523%2FENEURO.0328-23.2023)](https://doi.org/10.1523/ENEURO.0328-23.2023)

[<img src="https://github.com/dipterix/threeBrain/blob/master/adhoc/demo.gif?raw=true" width="100%" />](https://youtu.be/dSxJqBiw3sk)

<!-- demo dynamic: start

**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://rave.wiki). Please check our website https://rave.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.

threeBrain

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README