volvis.lb.with.surface: Visualize volume slices with surface mesh contours overlaid...

In fsbrain: Managing and Visualizing Brain Surface Data

Visualize volume slices with surface mesh contours overlaid in lightbox view.

Description

Creates a lightbox view of 2D MRI slices with the cortical surface boundary contours drawn on top. This is the fsbrain equivalent of what FreeSurfer's freeview or tkmedit show — useful for quality assessment of surface reconstruction against the underlying MRI volume. The surface mesh is loaded from the subject's FreeSurfer directory and its intersection with each displayed slice plane is computed and drawn as colored contour lines.

Usage

volvis.lb.with.surface(
  subjects_dir,
  subject_id,
  volume = "brain",
  surface = "white",
  hemi = "both",
  surface_color = "#FF0000",
  surface_lwd = 1,
  slices = -5,
  axis = 1L,
  per_row = 5L,
  per_col = NULL,
  border_geometry = "5x5",
  background_color = "#000000",
  silent = TRUE
)

Arguments

subjects_dir	character string, the FreeSurfer SUBJECTS_DIR.
subject_id	character string, the subject identifier.
volume	numeric 3D array or character string. Either a 3D brain volume (e.g., from T1.mgz or brain.mgz), or the name of a volume file to load from the subject's ⁠mri/⁠ directory. Defaults to "brain".
surface	character string or vector of strings, the surface(s) to use for contour extraction. One or more of "white", "pial", or "inflated". If a vector, contours for all surfaces are drawn. Defaults to "white".
hemi	character string, one of 'lh', 'rh', or 'both'. Which hemisphere surface(s) to overlay. Defaults to "both".
surface_color	character string or character vector, the color(s) for the surface contour lines. If a single color, all surfaces and hemispheres use it. If a vector of length length(surface), each surface gets its own color (both hemispheres use it). If a vector of length 2 * length(surface), colors are assigned as (lh_surf1, rh_surf1, lh_surf2, rh_surf2, ...). Defaults to "#FF0000" (red).
surface_lwd	numeric, line width for the contour lines (passed as lwd to segments). Defaults to 1.
slices	passed to volvis.lightbox. A negative integer N means "use every Nth slice". A numeric vector gives explicit slice indices (1-based). Defaults to -5 (every 5th slice).
axis	integer, the slice axis. 1 = sagittal, 2 = coronal, 3 = axial (in volume CRS convention). Defaults to 1L.
per_row	integer, number of slice images per row in the lightbox grid. Defaults to 5L.
per_col	integer, number of rows. If NULL, computed from per_row. Defaults to NULL.
border_geometry	character string, geometry for borders between tiles, passed to image_border. Defaults to "5x5".
background_color	character string, background color for borders and empty tiles. Defaults to "#000000".
silent	logical, whether to suppress messages. Defaults to TRUE.

Value

a magick image instance containing the lightbox with surface contours overlaid. Can be saved with image_write or displayed interactively.

See Also

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

Examples

## Not run: 
   fsbrain::download_optional_data();
   subjects_dir <- fsbrain::get_optional_data_filepath("subjects_dir");

   # Axial slices with white surface contours in red:
   img <- volvis.lb.with.surface(subjects_dir, "subject1",
      volume="brain", surface="white", axis=3L,
      surface_color="#FF0000");
   magick::image_write(img, "~/fsbrain_qa_axial.png");

   # Coronal slices in green:
   img <- volvis.lb.with.surface(subjects_dir, "subject1",
      volume="brain", surface="white", axis=2L,
      surface_color="#00FF00");

   # Sagittal slices: left hemisphere red, right hemisphere blue:
   img <- volvis.lb.with.surface(subjects_dir, "subject1",
      volume="brain", surface="white", axis=1L,
      surface_color=c("#FF0000", "#0000FF"));

   # Single hemisphere, pial surface, every 5th slice:
   img <- volvis.lb.with.surface(subjects_dir, "subject1",
      volume="brain", surface="pial", hemi="lh",
      axis=3L, slices=-5, surface_color="#FF8800");

   # Both white and pial surfaces overlaid: white in red, pial in yellow:
   img <- volvis.lb.with.surface(subjects_dir, "subject1",
      volume="brain", surface=c("white", "pial"), axis=3L,
      surface_color=c("#FF0000", "#FFFF00"));

   # White (lh red, rh blue) + pial (lh green, rh orange):
   img <- volvis.lb.with.surface(subjects_dir, "subject1",
      volume="brain", surface=c("white", "pial"), axis=3L,
      surface_color=c("#FF0000", "#0000FF", "#00FF00", "#FF8800"));

## End(Not run)

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