Read `FreeSurfer` surface and volume files

  additional_surfaces = NULL,
  aligned_ct = NULL,
  use_cache = TRUE,
  use_141 = getOption("threeBrain.use141", TRUE)

  volume_types = "t1",
  surface_types = "pial",
  curvature = "sulc",
  atlas_types = "aparc+aseg",
  ct_path = NULL,
  use_cache = TRUE,
  use_141 = getOption("threeBrain.use141", TRUE),



character, `FreeSurfer` subject folder, or `RAVE` subject folder


character, subject code to display with only letters and digits


character array, additional surface types to load, such as `white`, `smoothwm`


character, path to `ct_aligned_mri.nii.gz`, used for electrode localization


logical, whether to use cached `json` files or from raw `FreeSurfer` files


logical, whether to use standard 141 brain for surface file, default is getOption('threeBrain.use141', TRUE)


volume types, right now only support T1 image


surface types to load


curvature data. Only support "sulc" for current version


atlas types to be loaded, choices are 'aparc+aseg', 'aparc.a2009s+aseg', 'aparc.DKTatlas+aseg', 'aseg'


an aligned CT file in 'Nifti' format




This function is under FreeSurfer license. 1. Volumes: 3D viewer uses `mri/T1.mgz` from `FreeSurfer` to show the volume information. `T1.mgz` results from step 1 to 5 in `FreeSurfer` command `recon-all -autorecon1`, which aligns the original `DICOM` image to `RAS` coordinate system, resamples to volume with 256x256x256 voxels (tri-linear by default, check for more information).

2. Surface: There are two options for surface files. The first choice is using `std.141` brain generated by `AFNI/SUMA`. This surface file re-calculates vertices from standard 141 space, which averages the "surface" of 141 subjects. If you want to map surface electrodes across different subjects, you might want to consider this case as it's especially designed for surface mapping. However, you'll need `AFNI/SUMA` installed to generate the surface file. The details can be found via, and the `AFNI/SUMA` command related is `SurfToSurf`. Please generate the files to `[FREESURFER SUBJECT DIR]/SUMA/`. The file name follows the convention of `std.141.[lr]h.[SURFACE TYPE].[POSTFIX]`, where `lh` means left hemisphere and `rh` means right hemisphere; `SURFACE TYPE` can be `pial`, `white`, `smoothwm`, and `POSTFIX` can be `asc`, `gii`. If multiple files for the same surface type exists, the search order will be `asc > gii`. The other option is to use mesh files directly from `FreeSurfer` output located at `[FREESURFER SUBJECT DIR]/surf`. If you want to use these surface, make sure they are converted to `asc` or `gii` format.

3. Electrode registration and transforms This package provides two ways to map electrodes to standard space. For surface electrodes, if standard 141 brain is provided, then the first option is to snap electrodes to the nearest vertices in subject space. The key is the vertex number matches across different subjects, hence the location of corresponding vertices at template brain are the mapped electrode coordinates. If standard 141 brain is missing, or the electrode type is `stereo EEG`, then the second option is volume mapping. The idea is to map electrodes to `MNI305` brain. The details can be found at To perform volume mapping, we need `FreeSurfer` folder `mri/transforms`. Currently, only linear `Talairach` transform matrix is supported (located at `talairach.xfm`).

4. Coordinates The 3D viewer in this package uses the center of volume as the origin (0, 0, 0).


Zhengjia Wang


if (FALSE) {
# Please run `download_N27()` if `N27` is not at `default_template_directory()`

# Import from `FreeSurfer` subject folder
brain = threeBrain::freesurfer_brain(
  fs_subject_folder = file.path(default_template_directory(), 'N27'),
  subject_name = 'N27',
  additional_surfaces = c('white', 'smoothwm')

# Visualize. Alternatively, you can use brain$plot(...)
plot( brain )