R6 Class - Abstract Class of Geometries

Description

R6 Class - Abstract Class of Geometries

Author(s)

Zhengjia Wang

A geometry that renders nothing

Description

This is mainly used when you want to upload group data only

R6 Class - Generate Data Cube Geometry

Description

R6 Class - Generate Data Cube Geometry

Author(s)

Zhengjia Wang

R6 Class - Generate Data Cube Geometry via 3D Volume Texture

Description

R6 Class - Generate Data Cube Geometry via 3D Volume Texture

Author(s)

Zhengjia Wang

R6 Class - Generate Geometry from Vertices and Face Indices

Description

R6 Class - Generate Geometry from Vertices and Face Indices

R6 Class - Generate Group of Geometries

Description

R6 Class - Generate Group of Geometries

Author(s)

Zhengjia Wang

R6 Class - Generate Line Segments

Description

R6 Class - Generate Line Segments

Author(s)

Zhengjia Wang

R6 Class - Generate Sphere Geometry

Description

R6 Class - Generate Sphere Geometry

Author(s)

Zhengjia Wang

R6 Class - Generate Sphere Geometry

Description

R6 Class - Generate Sphere Geometry

Author(s)

Zhengjia Wang

R6 Class - Generate Tube Geometry

Description

R6 Class - Generate Tube Geometry

Author(s)

Zhengjia Wang

Shiny Proxy for Viewer

Description

Shiny Proxy for Viewer

Usage

brain_proxy(outputId, session = shiny::getDefaultReactiveDomain())

Arguments

Value

R6 class ViewerProxy

Setup Package, Install Environment

Description

Setup Package, Install Environment

Usage

brain_setup(continued = FALSE, show_example = TRUE, ...)

Arguments

Author(s)

Zhengjia Wang

Calculate rotation matrix from non-zero vectors

Description

Calculate rotation matrix from non-zero vectors

Usage

calculate_rotation(vec_from, vec_to)

Arguments

Value

A four-by-four transform matrix

Function to check whether 'FreeSurfer' folder has everything we need

Description

Function to check whether 'FreeSurfer' folder has everything we need

Usage

check_freesurfer_path(
  fs_subject_folder,
  autoinstall_template = FALSE,
  return_path = FALSE,
  check_volume = FALSE,
  check_surface = FALSE
)

Arguments

Value

logical whether the directory is valid or, if return_path is true, return 'FreeSurfer' path

Conform imaging data in 'FreeSurfer' way

Description

Reproduces conform algorithm used by 'FreeSurfer' to conform 'NIfTI' and 'MGH' images.

Usage

conform_volume(x, save_to, dim = c(256, 256, 256))

Arguments

Value

Nothing; the result will be save to save_to

Create a geometry group containing multiple geometries

Description

Create a geometry group containing multiple geometries

Usage

create_group(name, position = c(0, 0, 0), layer = 1)

Arguments

Details

A geometry group is a container of multiple geometries. The geometries within the same group share the same shift and rotations (see example 1). In ECoG/iEEG world, you might have 'MRI', 'CT', 'FreeSurfer' that have different orientations. For example, if you want to align MRI to FreeSurfer, Instead of calculating the position of each geometries, you can just put all MRI components into a group, and then set transform of this group, making the group aligned to FreeSurfer.

GeomGroup also can be used to store large data. To generate 3D viewer, 'threeBrain' needs to dynamically serialize data into JSON format, which can be read by browsers. However, a FreeSurfer brain might be ~30 MB. This is a very large size and might take ~5 seconds to serialize. To solve this problem, GeomGroup supports cache in its 'set_group_data' method. This method supports caching static serialized data into a JSON file, and allows the files to be loaded as static data objects. By "static", I mean the data is not supposed to be dynamic, and it should be "read-only". In JavaScript code, I also optimized such that you don't need to load these large datasets repeatedly. And this allows you to load multiple subjects' brain in a short time.

Value

a GeomGroup instance

Author(s)

Zhengjia Wang

Examples

# Example 1: relative position

# create group
g = create_group('Group A')

# create two spheres at 10,0,0, but s2 is relative to group A
s1 = geom_sphere('Sphere 1', radius = 2, position = c(10,0,0))
s2 = geom_sphere('Sphere 2', radius = 2, position = c(10,0,0), group = g)

# set transform (rotation)
g$set_transform(matrix(c(
  0,1,0,0,
  1,0,0,0,
  0,0,1,0,
  0,0,0,1
), byrow = TRUE, ncol = 4))

# global position for s2 is 0,10,0
if( interactive() ) { threejs_brain(s1, s2) }

# Example 2: cache

## Not run: 

# download N27 brain
# Make sure you have N27 brain downloaded to `default_template_directory()`
# download_N27()

template_dir <- default_template_directory()

dat = freesurferformats::read.fs.surface(
  file.path(template_dir, 'N27/surf/lh.pial')
)
vertex = dat$vertices[,1:3]
face = dat$faces[,1:3]

# 1. dynamically serialize
mesh = geom_freemesh('lh', vertex = vertex, face = face, layer = 1)

# 2. cache
# Create group, all geometries in this group are relatively positioned
tmp_file = tempfile()
mesh = geom_freemesh('Left Hemisphere cached', vertex = vertex,
                     face = face, cache_file = tmp_file)


## End(Not run)

Calculate cross-product of two vectors in '3D'

Description

Calculate cross-product of two vectors in '3D'

Usage

cross_prod(x, y)

Arguments

Value

A '3D' vector that is the cross-product of x and y

Default Directory to Store Template Brain

Description

Default Directory to Store Template Brain

Usage

default_template_directory(check = FALSE)

Arguments

Details

When threeBrain.template_dir is not set or invalid, the function checks 'RAVE' (R Analysis and Visualization for 'iEEG', https://openwetware.org/wiki/RAVE) folder at home directory. If this folder is missing, then returns results from R_user_dir('threeBrain', 'data'). To override the default behavior, use options(threeBrain.template_dir=...).

Value

A directory path where template brain is stored at; see also download_N27

Examples

default_template_directory()

Read 'FreeSurfer' surface and volume files

Description

Read 'FreeSurfer' surface and volume files

Usage

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

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

Arguments

Details

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 https://surfer.nmr.mgh.harvard.edu/fswiki/recon-all 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 https://openwetware.org/wiki/Beauchamp:CorticalSurfaceHCP, 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 https://surfer.nmr.mgh.harvard.edu/fswiki/CoordinateSystems. 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).

Author(s)

Zhengjia Wang

Examples

## Not run: 
# 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 )

## End(Not run)

Query the 'FreeSurfer' labels

Description

Query the 'FreeSurfer' labels

Usage

freesurfer_lut

Format

An object of class list of length 3.

Details

The 'FreeSurfer' atlases use https://surfer.nmr.mgh.harvard.edu/fswiki/FsTutorial/AnatomicalROI/FreeSurferColorLUT look-up table to query indexes. The 'threeBrain' electrode localization also uses this table to export the 'FSLabel' from electrode. If volume type is set to 'aparc_aseg', then please also use this table to filter.

Examples

freesurfer_lut$from_key(0:10)

freesurfer_lut$get_key("ctx-lh-supramarginal")

Generate smooth envelope around surface

Description

Alternative to 'Matlab' version of 'pial-outer-smoothed', use this function along with fill_surface.

Usage

generate_smooth_envelope(
  surface_path,
  save_as = NULL,
  inflate = 3,
  verbose = TRUE,
  save_format = c("auto", "bin", "asc", "vtk", "ply", "off", "obj", "gii", "mz3", "byu")
)

Arguments

Value

A 3-dimensional mesh that contains vertices and face indices, the result is also saved to save_as is specified.

Examples

if(interactive() &&
   file.exists(file.path(default_template_directory(), "N27"))) {

library(threeBrain)

fs_path <- file.path(default_template_directory(), "N27")

# lh.pial-outer-smoothed
lh_pial <- file.path(fs_path, "surf", "lh.pial")
save_as <- file.path(fs_path, "surf", "lh.pial-outer-smoothed")
generate_smooth_envelope(lh_pial, save_as)

# rh.pial-outer-smoothed
rh_pial <- file.path(fs_path, "surf", "rh.pial")
save_as <- file.path(fs_path, "surf", "rh.pial-outer-smoothed")
generate_smooth_envelope(rh_pial, save_as)

brain <- threeBrain(
  path = fs_path, subject_code = "N27",
  surface_types = 'pial-outer-smoothed'
)
brain$plot(controllers = list(
  "Surface Type" = 'pial-outer-smoothed'
))

}

Approximate 'sub-cortical' surfaces from 'parcellation'

Description

Superseded by volume_to_surf. Please do not use this function.

Usage

generate_subcortical_surface(
  atlas,
  index,
  save_prefix = NULL,
  label = NULL,
  IJK2RAS = NULL,
  grow = 1,
  remesh = TRUE,
  smooth = TRUE,
  smooth_delta = 3,
  ...
)

Arguments

Value

A surface mesh, containing 'atlas' index, label, surface nodes and face indices.

Creates any mesh geometry given vertices and face indices

Description

Creates any mesh geometry given vertices and face indices

Usage

geom_freemesh(
  name,
  vertex = NULL,
  face = NULL,
  position = c(0, 0, 0),
  layer = 1,
  cache_file = NULL,
  group = NULL
)

Arguments

Details

When generating a free mesh internally, a group must be specified, therefore if group is NULL here, then a group will be generated. However, it's always recommended to pass a group to the free mesh.

Author(s)

Zhengjia Wang

Examples

## Not run: 
# Make sure you have N27 brain downloaded to `default_template_directory()`
# threeBrain::download_N27()

n27_dir = file.path(default_template_directory(), "N27")
surf_type = 'pial'

# Locate mesh files
lh = read_fs_asc(file.path(n27_dir, sprintf('surf/lh.%s.asc', surf_type)))
rh = read_fs_asc(file.path(n27_dir, sprintf('surf/rh.%s.asc', surf_type)))

# Create groups
group = create_group(name = sprintf('Surface - %s (N27)', surf_type))

# create mesh
lh_mesh = geom_freemesh(
  name = sprintf('FreeSurfer Left Hemisphere - %s (N27)', surf_type),
  vertex = lh$vertices[,1:3],
  face = lh$faces[,1:3],
  group = group
)
rh_mesh = geom_freemesh(
  name = sprintf('FreeSurfer Right Hemisphere - %s (N27)', surf_type),
  vertex = rh$vertices[,1:3],
  face = rh$faces[,1:3],
  group = group
)


# Render
if( interactive() ) { threejs_brain(lh_mesh, rh_mesh) }




## End(Not run)

Create sphere geometry

Description

Create sphere geometry

Usage

geom_sphere(
  name,
  radius,
  position = c(0, 0, 0),
  layer = 1,
  group = NULL,
  value = NULL,
  time_stamp = NULL
)

Arguments

Author(s)

Zhengjia Wang

Examples

# Create a sphere with animation
g = lapply(1:10, function(ii){
  v = rep(ii, 10)
  v[1:ii] = 1:ii
  geom_sphere(paste0('s', ii), ii, value = v, position = c(11 * ii, 0,0), time_stamp = (1:10)/10)
})
if( interactive() ) { threejs_brain(.list = g) }

Function to read digest header

Description

Function to read digest header

Usage

get_digest_header(file, key, if_error = NULL, .list = NULL)

Arguments

Get 'voxel' to world matrix

Description

Get 'voxel' to world matrix

Usage

get_ijk2ras(x, type = c("scanner", "tkr"))

Arguments

Value

A four by four matrix

Import 'FreeSurfer' or 'SUMA' files into the viewer structure

Description

Import 'T1-MRI', surface files, curvature/'sulcus', atlas, and 'Talairach' transform matrix into 'json' format. These functions are not intended to be called directly, use import_from_freesurfer instead.

Usage

import_fs(
  subject_name,
  fs_path,
  quiet = FALSE,
  dtype = c("T1", "surface", "curv", "atlas_volume", "atlas_surface", "xform"),
  sub_type = NULL,
  hemisphere = c("l", "r"),
  ...
)

import_suma(
  subject_name,
  fs_path,
  quiet = FALSE,
  dtype = c("T1", "surface", "curv", "atlas_volume", "atlas_surface", "xform"),
  sub_type = NULL,
  hemisphere = c("l", "r"),
  ...
)

Arguments

Value

logical, TRUE if the file is or has been cached, or FALSE if the file is missing.

Import from 'FreeSurfer' and create 'JSON' cache for 3D viewer

Description

Import from 'FreeSurfer' and create 'JSON' cache for 3D viewer

Usage

import_from_freesurfer(fs_path, subject_name, quiet = FALSE)

Arguments

Value

None.

List or load all electrode prototypes

Description

List all built-in and user-customized electrode prototypes. User paths will be searched first, if multiple prototype configuration files are found for the same type.

Usage

list_electrode_prototypes()

load_prototype(type)

Arguments

Value

list_electrode_prototypes returns a named list, names are the prototype types and values are the prototype configuration paths; load_prototype returns the prototype instance if type exists, or throw an error.

Examples

availables <- list_electrode_prototypes()
if( "sEEG-16" %in% names(availables) ) {
  proto <- load_prototype( "sEEG-16" )

  print(proto, details = FALSE)
}

Launch a 'shiny' application to localize electrodes

Description

If 'RAVE' has been installed, please use 'RAVE' modules. This function is purely for demonstration purposes.

Usage

localization_module(
  subject_code,
  fs_path,
  ct_path = NULL,
  surfaces = "pial",
  use_141 = TRUE,
  shiny_options = list(launch.browser = TRUE),
  save_path = tempfile(pattern = "electrode", fileext = ".csv"),
  ...,
  control_presets = NULL,
  side_display = FALSE,
  controllers = list()
)

Arguments

Value

A list of 'ui' elements, 'server' function, and a stand-alone 'app'

Examples

# This example require N27 template brain to be installed
# see `?download_N27` for details

# using N27 to localize
fs_path <- file.path(default_template_directory(), "N27")
if(interactive() && dir.exists(fs_path)){
  module <- localization_module("N27", fs_path)

  print(module$app)
}

Create Multi-subject Template

Description

Create Multi-subject Template

Usage

merge_brain(
  ...,
  .list = NULL,
  template_surface_types = NULL,
  template_subject = unname(getOption("threeBrain.template_subject", "N27")),
  template_dir = default_template_directory()
)

Arguments

Author(s)

Zhengjia Wang

Create or load new electrode prototype from existing configurations

Description

Create or load new electrode prototype from existing configurations

Usage

new_electrode_prototype(base_prototype, modifier = NULL)

Arguments

Value

An electrode prototype instance

Examples

available_prototypes <- list_electrode_prototypes()
if("Precision33x31" %in% names(available_prototypes)) {

  # Load by type name
  new_electrode_prototype("Precision33x31")

  # load by path
  path <- available_prototypes[["Precision33x31"]]
  new_electrode_prototype(path)

  # load by json string
  json <- readLines(path)
  new_electrode_prototype(json)

}

Plot slices of volume

Description

Plot slices of volume

Usage

plot_slices(
  volume,
  overlays = NULL,
  transform = NULL,
  positions = NULL,
  zoom = 1,
  pixel_width = 0.5,
  col = c("black", "white"),
  normalize = NULL,
  zclip = NULL,
  overlay_alpha = 0.3,
  zlim = normalize,
  main = "",
  title_position = c("left", "top"),
  fun = NULL,
  nc = NA,
  which = NULL,
  ...
)

Arguments

Value

Nothing

Read 'FreeSurfer' ascii file

Description

Read 'FreeSurfer' ascii file

Usage

read_fs_asc(file)

Arguments

Value

a list of vertices and face indices

Read FreeSurfer Annotations

Description

Read FreeSurfer Annotations

Usage

read_fs_labels(path, vertex_number)

Arguments

Read 'FreeSurfer' m3z file

Description

Read 'FreeSurfer' m3z file

Usage

read_fs_m3z(filename)

Arguments

Details

An 'm3z' file is a 'gzip' binary file containing a dense vector field that describes a 3D registration between two volumes/images. This implementation follows the 'Matlab' implementation from the 'FreeSurfer'. This function is released under the 'FreeSurfer' license: https://surfer.nmr.mgh.harvard.edu/fswiki/FreeSurferSoftwareLicense.

Value

registration data

Read 'FreeSurfer' 'mgz/mgh' file

Description

Read 'FreeSurfer' 'mgz/mgh' file

Usage

read_fs_mgh_mgz(filename)

Arguments

Value

list contains coordinate transforms and volume data

Function to load surface data from 'Gifti' files

Description

The function 'read_gii2' is a dynamic wrapper of Python 'nibabel' loader. If no Python is detected, it will switch to 'gifti::readgii'.

Usage

read_gii2(path)

Arguments

Format

An R function acting as safe wrapper for nibabel.load.

Function to load 'FreeSurfer' 'mgz/mgh' file

Description

The function 'read_mgz' is a dynamic wrapper of Python 'nibabel' loader. If no Python is detected, it will switch to built-in function 'read_fs_mgh_mgz', which has limited features.

Usage

read_mgz(path)

Arguments

Format

An R function acting as safe wrapper for nibabel.load.

Read volume file in 'MGH' or 'Nifti' formats

Description

Read volume file in 'MGH' or 'Nifti' formats

Usage

read_volume(file, format = c("auto", "mgh", "nii"), header_only = FALSE)

Arguments

Value

A list of volume data and transform matrices; if header_only=TRUE, then volume data will be substituted by the header.

Objects exported from other packages

Description

These objects are imported from other packages. Follow the links below to see their documentation.

freesurferformats

read.fs.annot, read.fs.curv, read.fs.label, read.fs.mgh, read.fs.morph, read.fs.surface, read.fs.transform, read.fs.volume, read.fs.weight, read.nifti1.data, read.nifti1.header, read.nifti2.data, read.nifti2.header, write.fs.surface, write.nifti1, write.nifti2

Shiny Renderer for threeBrain Widgets

Description

Shiny Renderer for threeBrain Widgets

Arguments

Author(s)

Zhengjia Wang

Function to reshape data to 'RAS' order

Description

Function to reshape data to 'RAS' order

Usage

reorient_volume(volume, Torig)

Arguments

Value

Reshaped tensor with dimensions corresponding to 'R', 'A', and 'S'

Save threeBrain widgets to local file system

Description

Save threeBrain widgets to local file system

Usage

save_brain(widget, path, title = "3D Viewer", as_zip = FALSE, ...)

Arguments

Author(s)

Zhengjia Wang

Create 'sEEG' shaft geometry prototype

Description

Intended for creating/editing geometry prototype, please see load_prototype to load existing prototype

Usage

seeg_prototype(
  type,
  center_position,
  contact_widths,
  diameter = 1,
  channel_order = seq_along(center_position),
  fix_contact = 1,
  overall_length = 200,
  description = NULL,
  dry_run = FALSE,
  default_interpolation = NULL,
  viewer_options = NULL,
  overwrite = FALSE
)

Arguments

Value

A electrode shaft geometry prototype; the configuration file is saved to 'RAVE' 3rd-party repository.

Examples

probe_head <- 2
n_contacts <- 12
width <- 2.41
contact_spacing <- 5
overall_length <- 400
diameter <- 1.12

contacts <- probe_head + width / 2 + 0:(n_contacts-1) * contact_spacing
proto <- seeg_prototype(
  type = "AdTech-sEEG-SD12R-SP05X-000",
  description = c(
    "AdTech sEEG - 12 contacts",
    "Contact length   : 2.41 mm",
    "Central spacing  : 5    mm",
    "Tip size         : 2    mm",
    "Diameter         : 1.12 mm"
  ),
  center_position = contacts,
  contact_widths = width,
  diameter = diameter,
  overall_length = overall_length,
  dry_run = TRUE
)

print(proto, details = FALSE)

Download and Manage Template Subjects

Description

Download and Manage Template Subjects

Usage

download_template_subject(
  subject_code = "N27",
  url,
  template_dir = default_template_directory()
)

download_N27(make_default = FALSE, ...)

set_default_template(
  subject_code,
  view = TRUE,
  template_dir = default_template_directory()
)

threebrain_finalize_installation(
  upgrade = c("ask", "always", "never", "data-only", "config-only"),
  async = TRUE
)

available_templates()

Arguments

Details

To view electrodes implanted in multiple subjects, it's highly recommended to view them in a template space The detail mapping method is discussed in function freesurfer_brain.

To map to a template space, one idea is to find someone whose brain is normal. In our case, the choice is subject 'N27', also known as 'Colin 27'. function download_N27 provides a simple and easy way to download a partial version from the Internet.

If you have any other ideas about template brain, you can use function set_default_template(subject_code, template_dir) to redirect to your choice. If your template brain is a 'Zip' file on the Internet, we provide function download_template_subject to automatically install it.

Author(s)

Zhengjia Wang

Create a brain object

Description

Create a brain object

Usage

threeBrain(
  path,
  subject_code,
  surface_types = "pial",
  atlas_types,
  ...,
  template_subject = unname(getOption("threeBrain.template_subject", "N27")),
  backward_compatible = getOption("threeBrain.compatible", FALSE)
)

Arguments

Shiny Output for threeBrain Widgets

Description

Shiny Output for threeBrain Widgets

Arguments

Author(s)

Zhengjia Wang

Create a Threejs Brain and View it in Browsers

Description

Create a Threejs Brain and View it in Browsers

Usage

threejs_brain(
  ...,
  .list = list(),
  width = NULL,
  height = NULL,
  background = "#FFFFFF",
  cex = 1,
  timestamp = TRUE,
  title = "",
  side_canvas = FALSE,
  side_zoom = 1,
  side_width = 250,
  side_shift = c(0, 0),
  side_display = TRUE,
  control_panel = TRUE,
  control_presets = NULL,
  control_display = TRUE,
  camera_center = c(0, 0, 0),
  camera_pos = c(500, 0, 0),
  start_zoom = 1,
  symmetric = 0,
  default_colormap = "Value",
  palettes = NULL,
  value_ranges = NULL,
  value_alias = NULL,
  show_inactive_electrodes = TRUE,
  surface_colormap = system.file("palettes", "surface", "ContinuousSample.json", package
    = "threeBrain"),
  voxel_colormap = system.file("palettes", "datacube2", "FreeSurferColorLUT.json",
    package = "threeBrain"),
  videos = list(),
  widget_id = "threebrain_data",
  tmp_dirname = NULL,
  debug = FALSE,
  enable_cache = FALSE,
  token = NULL,
  controllers = list(),
  browser_external = TRUE,
  global_data = list(),
  global_files = list(),
  qrcode = NULL,
  custom_javascript = NULL,
  show_modal = "auto",
  embed = FALSE
)

Arguments

Author(s)

Zhengjia Wang

Examples

if( interactive() ) {
library(threeBrain)

# Please use `download_N27` to download N27 Collins template brain
n27_path <- file.path(default_template_directory(), "N27")
if( dir.exists(n27_path) ) {

  brain <- threeBrain(path = n27_path, subject_code = "N27",
                             surface_types = c('pial', 'smoothwm'))
  print(brain)

  brain$plot(
    background = "#000000",
    controllers = list(
      'Voxel Type' = 'aparc_aseg',
      'Surface Type' = 'smoothwm',
      'Blend Factor' = 1,
      'Right Opacity' = 0.3,
      'Overlay Sagittal' = TRUE
    ),
    show_modal = TRUE
  )

}
}

Add video content to the viewer

Description

Add video content to the viewer

Usage

video_content(
  path,
  duration = Inf,
  time_start = 0,
  asp_ratio = 16/9,
  local = TRUE
)

Arguments

Details

The video path can be either local file path or a 'URL' from websites. When path is from the internet, there are two options: download the video before generating the viewer, or directly use the 'URL'.

If download happens before a viewer is generated (local=TRUE), then the video content is local. The viewer will be self-contained. However, the distribution will contain the video, and the archive size might be large.

If raw 'URL' is used (local=FALSE), then viewer is not self-contained as the video link might break anytime. The 'screenshot' and 'record' function might be limited if the 'URL' has different domain than yours. However, the distribution will not contain the video, hence smaller. This works in the scenarios when it is preferred not to share video files or they are licensed, or simply distribution is limited. Besides, this method is slightly faster than the local alternatives.

Generate surface file from 'nii' or 'mgz' volume files

Description

Generate surface file from 'nii' or 'mgz' volume files

Usage

volume_to_surf(
  volume,
  save_to = NA,
  lambda = 0.2,
  degree = 2,
  threshold_lb = 0.5,
  threshold_ub = NA,
  format = "auto"
)

Arguments

Value

Triangle 'rgl' mesh (vertex positions in native 'RAS'). If save_to is a valid path, then the mesh will be saved to this location.

See Also

read_volume, vcg_isosurface, vcg_smooth_implicit

Examples

library(threeBrain)
N27_path <- file.path(default_template_directory(), "N27")
if(dir.exists(N27_path)) {
  aseg <- file.path(N27_path, "mri", "aparc+aseg.mgz")

  # generate surface for left-hemisphere insula
  mesh <- volume_to_surf(aseg, threshold_lb = 1034,
                         threshold_ub = 1036)

  if(interactive()) {
    ravetools::rgl_view({
      ravetools::rgl_call("shade3d", mesh, color = "yellow")
    })
  }
}

Color maps for volume or surface data

Description

Color maps for volume or surface data

Usage

create_colormap(
  gtype = c("surface", "volume"),
  dtype = c("continuous", "discrete"),
  key,
  color,
  value,
  alpha = FALSE,
  con = NULL,
  auto_rescale = FALSE,
  ...
)

save_colormap(cmap, con)

freeserfer_colormap(con)

load_colormap(con)

Arguments

Details

Internal 'JavaScript' shader implementation uses integer color keys to connect color palettes and corresponding values. The keys must be non-negative.

Zero key is a special color key reserved by system. Please avoid using it for valid values.

Value

A list of color map information

Examples

# Creates a symmetric continuous colormap with 3 keys
# The color range is -10 to 10
# The colors are 'blue','white','red' for these keys

pal <- create_colormap(
  gtype = "volume", dtype = "continuous",
  key = c(1,2,3), value = c(-10,0,10),
  color = c('blue','white','red'))

print( pal )

# ---------------- Get colormap key from a value ------------

# returns key index starting from
pal$get_key( -10 )

# nearest value
pal$get_key( 2 )

# set threshold, key is now 0 (no color)
pal$get_key( 2, max_delta = 1 )


# ---------------- Save and load ----------------
f <- tempfile( fileext = '.json' )
save_colormap( pal, f )
cat(readLines(f), sep = '\n')

load_colormap(f)

Generate volume data from 'MNI' coordinates

Description

Generate volume data from 'MNI' coordinates

Usage

add_voxel_cube(
  brain,
  name,
  cube,
  size = c(256, 256, 256),
  trans_mat = NULL,
  trans_space_from = c("model", "scannerRAS"),
  color_format = c("RGBAFormat", "RedFormat")
)

add_nifti(
  brain,
  name,
  path,
  trans_mat = NULL,
  color_format = c("RGBAFormat", "RedFormat"),
  trans_space_from = c("model", "scannerRAS")
)

create_voxel_cube(
  mni_ras,
  value,
  colormap,
  keys = colormap$get_key(value),
  dimension = c(256, 256, 256)
)

Arguments

Value

create_voxel_cube returns a list of cube data and other informations; add_voxel_cube returns the brain object

Examples

# requires N27 brain to be installed
# use `download_N27()` to download template Collins brain


# sample MNI coords
tbl <- read.csv(system.file(
  'sample_data/example_cube.csv', package = 'threeBrain'
))
head(tbl)

# load colormap
cmap <- load_colormap(system.file(
  'palettes/datacube2/Mixed.json', package = 'threeBrain'
))

x <- create_voxel_cube(
  mni_ras = tbl[, c('x', 'y', 'z')],
  keys = tbl$key,
  dimension = c(128, 128, 128)
)


n27_path <- file.path(default_template_directory(), "N27")
if( interactive() && dir.exists(n27_path) ) {
  brain <- merge_brain()

  # or add_voxel_cube(brain, 'example', x$cube)
  x$add_to_brain(brain, 'example')

  brain$plot(controllers = list(
    "Voxel Type" = 'example',
    'Right Opacity' = 0.3,
    'Left Opacity' = 0.3,
    'Background Color' = '#000000'
  ), voxel_colormap = cmap)
}