threeBrain - HTML, WebGL based 3D Viewer

A live demo is live NOW! (Recommended: view it with Chrome)

• Click here for the news
• For function usage, check Reference page
• Check keyboard shortcuts here

A. Installation

1. R and RStudio Desktop (Free Version)
2. Open RStudio, enter from its console:

install.packages("threeBrain")

If you want to install dev version from Github, then use:

install.packages("devtools")
devtools::install_github("dipterix/threeBrain")

3. (Optional) Setups: after installation, in RStudio console, type the following command

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 at

~/rave_data/others/three_brain/N27

~ is your home directory. For example on my laptop, it's /Users/dipterix/. On Windows, it's C:\Users\dipterix\.

Let's view this subject. The following commands all go to RStudio console.

1. Import subject

# freesurfer_brain is deprecated, use freesurfer_brain2 instead
n27 = freesurfer_brain2(
    fs_subject_folder = '~/rave_data/others/three_brain/N27',
    subject_name = 'N27',
    surface_types = 'pial'
)

2. Visualize

plot(x)       # alternatively, you can use `x$plot()`

C. Directory Setup

~/rave_data/others/three_brain/N27 is a sample generated by FreeSurfer (download). If you have any subjects processed by FreeSurfer, direct fs_subject_folder to your subject folder.

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.

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 RAS 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

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, 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,

# yab = ... (see section B for import a single subject)
# ycq = ...
template_n27 = threeBrain::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).