Skip to contents

Getting Started

Source: vignettes/A-getting-started.Rmd
A-getting-started.Rmd

threeBrain is an R package that renders FreeSurfer or AFNI/SUMA files in the modern web browsers. The goal is to provide 3D viewers that are powerful, interactive, easy-to-share.

Directory Setup

The basic setup of a typical subject folder should look like this:

Project Directory
  └─Subject code 
    ├─mri   - Atlas, T1 and/or CT image files (*.mgz, transforms, ...)
    ├─surf  - FreeSurfer surface files (pial, sulc, ...)
    ├─SUMA  - (Optional) SUMA standard 141 surfaces (std.141.*)
    └─...   - Other files

If you are using FreeSurfer to generate MRI reconstruction, then you are all set! For AFNI/SUMA users, please place your SUMA folder under subject folder.

If you don’t have any FreeSurfer folders, you can download a sample archive from here, choose N27-complete.zip, and extract to your download directory. Once extracted, you will have a N27 subject folder in the ~/Downloads/ directory. The directory tree looks exactly the same as described above.

In the following context, I will use ~/Downloads/N27 as an example

Generate Viewer Object 

library(threeBrain)
subject_code <- "N27"
subject_path <- "~/Downloads/N27"
brain <- threeBrain(subject_path, subject_code)
print(brain)
#> Subject - N27 
#> Transforms:
#> 
#> - FreeSurfer TalXFM [from scanner to MNI305]:
#>        [,1]    [,2]    [,3]    [,4]
#> [1,] 0.9692 -0.0029 -0.0134 -0.1638
#> [2,] 0.0062  0.9685  0.0492 -2.0717
#> [3,] 0.0145  0.0276  0.9541  0.1361
#> [4,] 0.0000  0.0000  0.0000  1.0000
#> 
#> - Torig [Voxel CRS to FreeSurfer origin, vox2ras-tkr]
#>      [,1] [,2] [,3] [,4]
#> [1,]   -1    0    0  128
#> [2,]    0    0    1 -128
#> [3,]    0   -1    0  128
#> [4,]    0    0    0    1
#> 
#> - Norig [Voxel CRS to Scanner center, vox2ras]
#>      [,1] [,2] [,3]   [,4]
#> [1,]   -1    0    0  128.5
#> [2,]    0    0    1 -145.5
#> [3,]    0   -1    0  146.5
#> [4,]    0    0    0    1.0
#> 
#> - Scanner center relative to FreeSurfer origin
#> [1]  -0.5  17.5 -18.5
#> 
#> - FreeSurfer RAS to MNI305, vox2vox-MNI305
#>        [,1]    [,2]    [,3]      [,4]
#> [1,] 0.9692 -0.0029 -0.0134   0.12365
#> [2,] 0.0062  0.9685  0.0492 -18.10715
#> [3,] 0.0145  0.0276  0.9541  17.31120
#> [4,] 0.0000  0.0000  0.0000   1.00000
#> Surface information (total count 1)
#> Loading required namespace: rstudioapi
#>   pial [ std.141 ]  
#> Volume information (total count 1)
#>   T1

If this is the first time, it might take a while to import and generate cache files.

Visualization

Visualizing the viewer is simply just one line.

brain$plot()

Surface, Volume, Atlas

By default, the viewers only load the following information. Only the pial surfaces are mandatory, other files are optional.

  • T1 (MR images) and transforms (optional)
    • mri/brain.finalsurfs.mgz
    • mri/transforms/talairach.xfm
  • pial (mandatory) and sulc (optional)
    • surf/*h.pial or SUMA/std.141.*h.pial[.asc|gii]
    • surf/*h.sulc or SUMA/std.141.*h.sulc.1D
  • aparc+aseg (optional)
    • mri/aparc+aseg.mgz

The T1 image is automatically detected if brain.finalsurfs.mgz is missing. The following alternatives are brainmask.mgz, brainmask.auto.mgz, T1.mgz.

To load more than one surfaces, please specify the surface types when loading the viewer. The available surface types are:

  • pial - (default)
  • smoothwm, white - (smoothed) white matter
  • inflated, sphere - inflated surfaces
  • pial-outer-smoothed - (‘FreeSurfer’-only) smoothed surface tightly wrapping the pial surface
  • inf_200 - (‘SUMA’-only) inflated pial surface

The atlas type can be selected from aparc+aseg, aparc.a2009s+aseg, aparc.DKTatlas+aseg, or aseg. To load a specific atlas, please make sure the corresponding file exists in mri/. For example, mri/aseg.mgz.

The following example loads pial and smoothwm, with aseg as atlas. The viewer shows ‘Coronal’ plane, smoothed white matter, ‘Ventricle’, and ‘Cerebellum’ all together in one scene.

brain <- threeBrain(
  subject_path, subject_code, 
  surface_types = c('pial', 'smoothwm'), 
  atlas_types = 'aseg')

brain$plot(
  controllers = list(
    "Voxel Type" = "aseg",
    "Voxel Label" = "4,5,6,7",
    "Surface Type" = "smoothwm",
    "Left Opacity" = 0.4,
    "Overlay Coronal" = TRUE
  ), 
  control_display = FALSE,
  camera_pos = c(0, -500, 0)
)