vis.volume.on.surface: Visualize a brain volume overlaid on a cortical surface in...

In fsbrain: Managing and Visualizing Brain Surface Data

Visualize a brain volume overlaid on a cortical surface in 3D.

Description

Render a brain volume (as an isosurface or as voxels) together with a cortical surface mesh colored by morphometry data in the same interactive 3D scene. The volume coordinates are transformed to surface RAS space using the FreeSurfer vox2ras_tkr matrix, ensuring proper spatial alignment of volume and surface.

Usage

vis.volume.on.surface(
  subjects_dir,
  subject_id,
  volume = "brain",
  volume_mode = "contour",
  volume_level = 80,
  volume_color = "#666666",
  volume_alpha = 0.3,
  measure = "thickness",
  surface = "white",
  hemi = "both",
  views = c("t4"),
  surface_style = "semitransparent",
  rgloptions = rglo(),
  makecmap_options = mkco.seq(),
  cortex_only = FALSE,
  render_every = 20L,
  ...
)

Arguments

subjects_dir	character string, the FreeSurfer SUBJECTS_DIR, i.e., a directory containing the data for all your subjects, each in a subdir named after the subject identifier.
subject_id	character string, the subject identifier.
volume	numeric 3D array or character string. Either a 3D volume array with voxel intensities, or the name of a volume file to load from the subject's ⁠mri/⁠ directory (e.g., "brain", "aseg", "aparc+aseg"). Background voxels should have value NA or 0.
volume_mode	character string, one of "contour" or "voxels". The rendering mode for the volume: "contour" creates a smooth isosurface using the misc3d package (requires the optional dependency misc3d), "voxels" renders individual foreground voxels as small cubes. Defaults to "contour".
volume_level	numeric scalar, the intensity threshold for contour mode. Only voxels with intensity values >= this threshold contribute to the isosurface. Ignored in voxel mode. Defaults to 80 (suitable for a raw brain.mgz with values in range 0-255).
volume_color	character string, the color for the volume rendering. Defaults to "#666666" (medium gray).
volume_alpha	numeric in range 0..1, the transparency (alpha) of the volume overlay. Lower values make the volume more transparent, revealing the surface beneath. Defaults to 0.3.
measure	character string or NULL, the morphometry data to use for coloring the surface. E.g., "thickness", "sulc", "area", or "curv". Pass NULL to render the surface in a single plain color without morphometry overlay. Defaults to "thickness".
surface	character string, the display surface. E.g., "white", "pial", or "inflated". Defaults to "white".
hemi	character string, one of 'lh', 'rh', or 'both'. The hemisphere to display. Defaults to "both".
views	list of strings, the view configuration. For single interactive view use c("si"). For 4-angle tiled view use c("t4"). For 9-angle tiled view use c("t9"). Defaults to c("t4").
surface_style	character string, a rendering style for the cortical surface, e.g., 'default', 'shiny' or 'semitransparent'. Use 'semitransparent' to make the surface partially see-through, which works well for volume overlays. Defaults to "semitransparent".
rgloptions	named list, parameters passed to par3d. Example: rgloptions = list("windowRect"=c(50,50,800,800)). Defaults to the result of rglo.
makecmap_options	named list of parameters to pass to makecmap. Should include at least a colormap function as name 'colFn'. Defaults to the result of mkco.seq.
cortex_only	logical, whether to mask the medial wall (i.e., only render cortical vertices). Defaults to FALSE.
render_every	integer, for voxel mode only: render every Nth foreground voxel. Higher values improve performance but reduce density. Set to 1 to render all voxels (may be slow). Defaults to 20.
...	extra parameters passed to the volume rendering backend (e.g., lit=FALSE for unlit voxels).

Value

invisible named list with entries: "surface" (the coloredmeshes from the surface rendering, a hemilist of coloredmesh instances) and "volume" (the volume rendering result: a Triangles3D object for contour mode, or a list of coloredvoxels for voxel mode).

See Also

Other visualization functions: highlight.vertices.on.subject(), highlight.vertices.on.subject.spheres(), vis.color.on.subject(), vis.data.on.fsaverage(), vis.data.on.subject(), vis.labeldata.on.subject(), vis.mask.on.subject(), vis.region.values.on.subject(), vis.rglwidget(), vis.subject.annot(), vis.subject.label(), vis.subject.morph.native(), vis.subject.morph.standard(), vis.subject.pre(), vis.symmetric.data.on.subject(), vislayout.from.coloredmeshes()

Other volume visualization: volvis.lb(), volvis.lb.with.surface(), volvis.lightbox(), volvis.slices.with.surface()

Examples

## Not run: 
   fsbrain::download_optional_data();
   subjects_dir = fsbrain::get_optional_data_filepath("subjects_dir");
   # Contour overlay of brain volume on thickness-colored surface:
   vis.volume.on.surface(subjects_dir, 'subject1', 'brain',
      volume_mode='contour', volume_level=60, measure='thickness',
      views=c('si'), surface_style='semitransparent');
   # Voxel overlay of aseg segmentation ventricles:
   aseg = subject.volume(subjects_dir, 'subject1', 'aseg');
   ventricle_mask = vol.mask.from.segmentation(aseg, c(4,14,15,43));
   vis.volume.on.surface(subjects_dir, 'subject1', ventricle_mask,
      volume_mode='voxels', measure=NULL, views=c('si'),
      volume_color='red');

## End(Not run)

fsbrain documentation built on Aug. 23, 2026, 5:06 p.m.