Customize 3D Viewer Color Palette

Create basic 3D viewer and render with colors

3D Viewer
Interactive Module
Author
Affiliation

Zhengjia Wang

Dept. of Neurosurgery, University of Pennsylvania

Published

September 16, 2024

Prerequisites

This post assumes that you have already imported subject’s imaging data to RAVE and finished the electrode localization.

1. Simple 3D viewer

Library ravecore provides simple high-level function rave_brain to load 3D brain object.

brain <- ravecore::rave_brain("demo/DemoSubject")

# See the output to the right for what's inside of the brain object
brain
Subject - DemoSubject 
Transforms:

- FreeSurfer TalXFM [from scanner to MNI305]:
          [,1]      [,2]     [,3]       [,4]
[1,]  1.071608 -0.069364 0.003839  -5.186203
[2,] -0.033422  1.293478 0.133732 -26.001312
[3,]  0.039658 -0.231380 1.268464 -21.980759
[4,]  0.000000  0.000000 0.000000   1.000000

- Torig [Voxel IJK/CRS to FreeSurfer space tkrRAS, 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 IJK/CRS to Scanner space, vox2ras]
     [,1] [,2] [,3]      [,4]
[1,]   -1    0    0  131.6145
[2,]    0    0    1 -127.5000
[3,]    0   -1    0  127.5000
[4,]    0    0    0    1.0000

- Scanner origin in FreeSurfer tkrRAS coordinate
[1] -3.614471 -0.500000  0.500000

- FreeSurfer RAS to MNI305, vox2vox-MNI305
          [,1]      [,2]     [,3]       [,4]
[1,]  1.071608 -0.069364 0.003839  -1.349508
[2,] -0.033422  1.293478 0.133732 -25.542242
[3,]  0.039658 -0.231380 1.268464 -22.587338
[4,]  0.000000  0.000000 0.000000   1.000000
Surface information (total count 1)
  pial [ fs ]  
Volume information (total count 1)
  T1

Use brain$plot(<your arguments...>) to show the viewer:

brain$plot()

Preview of the result. See below if you want to play with the 3D viewer interactively

2. Render electrodes with values

brain$set_electrode_values(table_or_path) allows users to load a data table and render electrodes with colors. Users can create a csv table using Excel or their favorite programming languages, as long as the table follows the following format (See example data table):

Subject Electrode varname*
DemoSubject 1 0.25
DemoSubject 14 -0.4
… … …

Here is the explanation of the columns (case-sensitive):

  • Subject is the subject code
  • Electrode is the electrode channel number (integer)
  • varname* can be almost anything (give it a meaningful name, for e.g., Power, Cluster, …) that you would like to show, and the values can be either numeric or categorical
    • The variable name is recommended to only contain letters and digits. For example, BetaBandPower seems to be a good idea, while names like 75-150 Hz should be avoided
    • The variable values must not be numerical if the intent is categorical. For example cluster values such as 1, 2, 3, … should be avoided and users should use Cluster 1, Cluster 2, Cluster 3, …, or A, B, C, … instead
data_table <- data.frame(
    Subject = "DemoSubject",
    Electrode = c(13,14,15,16,24),
    ContinuousValue = runif(5),
    Categorical = letters[c(1,2,3,2,3)]
)

brain$set_electrode_values(data_table)

brain$plot()

Left: continuous values with symmetric value range. The color palette transition from blue to white to red (default); Right: Categorical data with default color palette

3. Render options

brain$plot allows users to provide render options to change the following components:

  • Color palette
  • Default value ranges (for continuous data)
  • Control panels

Here’s a full example:

# Load brain
brain <- ravecore::rave_brain("demo/DemoSubject")

# Set values with 2 variables: `ContinuousVal` and `CategoricalVal`
brain$set_electrode_values(
  data.frame(
    Subject = "DemoSubject",
    Electrode = c(13:16, 24, 73:80), 
    ContinuousVal = rnorm(13),
    CategoricalVal = sample(letters[1:4], size = 13, replace = TRUE),
    PValue = c(0.15, 0.5, 0.9, 0.01, 0.05, 0.45, 0.8,
               0.68, 0.6, 0.33, 0.001, 0.36, 0.83)
  )
)

# Plot brain with options
brain$plot(
  side_display = FALSE, control_display = FALSE,
  
  # change color palettes: each variable requires a palette (if not default)
  palettes = list(
    
    # discrete values require each category to be filled with a 
    # color. The order is alphabetic
    CategoricalVal = c("red", "blue", "green"),
    
    # continuous values requires at least 2 key colors
    ContinuousVal = c("white", "purple"),
    
    # p-value is not linearly scaled, R provides `colorRampPalette`
    # to generate non-linear color palette from at least 
    # 3 key colors. 
    # This example used 5 key colors with bias = 2 so the
    PValue = colorRampPalette(
      c("red", "yellow", "cyan", "gray", "gray"), bias = 2
    )(100)
    
  ),
  
  # Change value range: sets the value range for variables that have
  # bounded ranges, such as p-values
  value_ranges = list(
    
    # p-value should range from 0-1 
    PValue = c(0, 1),
    
    # We also want to trim the `ContinuousVal` to 95% CI
    ContinuousVal = c(-2, 2)
    
  ),
  
  # Set initial controller status
  controllers = list(
    
    # Display p-value 
    "Display Data" = "PValue",
    
    
    # Overlay atlases from side canvas
    "Voxel Type" = "aparc_aseg",
    "Voxel Display" = "side camera",
    
    # Overlay axial slices with surfaces
    "Overlay Axial" = TRUE,
    
    # Set surface opacity
    "Left Opacity" = 0.4,
    "Left Mesh Clipping" = 0.3,
    "Right Opacity" = 0.4,
    "Right Mesh Clipping" = 0.3,
    
    # Electrode outline
    "Outlines" = "on",
    "Translucent" = "contact+outline",
    
    # Background color and camera position
    "Background Color" = "#000000",
    "Camera Position" = "superior"
    
  )
  
)

Key Documentations

Function ravecore::rave_brain

.help_text("rave_brain", package = "ravecore")