This vignette demonstrates how to
display 3D brain surface meshes using the rgl plotting
tools provided by the neurosurf package, primarily through
the plot() method which utilizes the
view_surface() function internally.
For interactive HTML widgets, see
vignette("interactive-surfaces"). For high-level,
multi-view layouts with colourbars and atlas outlines, see
vignette("surface-figures").
First, we set up knitr options to embed rgl
plots directly into the HTML output using WebGL and prevent standalone
rgl windows from popping up during knitting. We then load
example left and right hemisphere white matter surfaces included with
the package and prepare some data (smoothed geometry, curvature, random
values) for the examples.
The simplest way to display a SurfaceGeometry object is
using the plot() method. By default, it renders the surface
with a light gray background. We can specify a
viewpoint.
# Plot the smoothed left hemisphere from a lateral viewpoint
render_surface(white_lh_display, viewpoint = "lateral", lit = TRUE)
Surface curvature helps distinguish gyri (outward folds) from sulci
(inward folds). The curvature() function calculates this,
and curv_cols_smooth() maps the values to a continuous
grayscale gradient (dark in sulci, light on gyri) for natural-looking
shading. For a simpler binary split, see curv_cols().
Either way, pass the resulting colors to the bgcol argument
of plot().
# Calculate curvature colors
curv_colors <- curv_cols_smooth(curv_lh_display)
# Plot with curvature background from a medial viewpoint
render_surface(white_lh_display, bgcol = curv_colors, viewpoint = "medial", specular = "black")
Often, we want to visualize data mapped onto the surface vertices
(e.g., activation values, thickness). We can pass a vector of values to
the vals argument. The cmap argument specifies
the color map, and irange defines the data range to map
onto the colormap. Values outside irange are clamped to the
minimum or maximum color.
# Overlay random data using a rainbow colormap
# Map data range from -2 to 2 onto the colormap
render_surface(white_lh_display, vals = random_vals_display_smooth, cmap = rainbow(256),
irange = c(-2, 2), thresh = NULL, viewpoint = "lateral", specular = "gray")
The thresh argument (a vector of two values,
c(lower, upper)) can be used with vals to make
parts of the surface transparent. Vertices where the corresponding value
in vals is inside this range (between
lower and upper) are rendered transparently;
values outside remain opaque. This is useful for masking out a band of
values.
# Same data overlay as above, but make values between -1 and 1 transparent
render_surface(white_lh_display, vals = random_vals_display_smooth, cmap = rainbow(256),
irange = c(-2, 2), thresh = c(-1, 1), viewpoint = "lateral", lit = TRUE)
Instead of mapping data values to a colormap, you can provide a
vector of specific hex color codes directly to the
vert_clrs argument. This overrides vals and
cmap. The vector length must match the number of
vertices.
# Color vertices based on their x-coordinate (e.g., red for positive x, blue for negative)
x_coords <- coords(white_lh_display)[, 1]
vertex_colors <- ifelse(x_coords > median(x_coords), "#FF0000", "#0000FF") # Red/Blue
render_surface(white_lh_display, vert_clrs = vertex_colors, viewpoint = "ventral", lit = TRUE)
The alpha argument controls the overall transparency of
the surface, ranging from 0 (fully transparent) to 1 (fully opaque).
# Plot the surface with 60% opacity (40% transparent)
render_surface(white_lh_display, vals = random_vals_display_smooth, cmap = heat.colors(256),
irange = c(-2, 2), alpha = 0.6, viewpoint = "posterior")
The appearance of the surface is affected by lighting. The
specular argument controls the color of specular highlights
(shininess). Setting it to "black" creates a matte
appearance.
# Plot with a matte finish (no specular highlights)
render_surface(white_lh_display, vals = random_vals_display_smooth, cmap = topo.colors(256),
irange = c(-2, 2), specular = "black", viewpoint = "lateral", lit = TRUE)
Use snapshot_surface() to render an off-screen PNG and
include it directly:
.render_counter$n <- .render_counter$n + 1
snapshot_file <- knitr::fig_path(paste0("-snapshot-", .render_counter$n, ".png"))
dir.create(dirname(snapshot_file), recursive = TRUE, showWarnings = FALSE)
img_path <- try(snapshot_surface(white_lh_display,
file = snapshot_file,
vals = random_vals_display_smooth,
cmap = viridis::viridis(256),
viewpoint = "lateral",
specular = "black",
width = 1200, height = 900),
silent = TRUE)
if (!inherits(img_path, "try-error") && snapshot_is_usable(img_path)) {
knitr::include_graphics(img_path)
} else {
rgl::open3d()
view_surface(white_lh_display,
vals = random_vals_display_smooth,
cmap = viridis::viridis(256),
viewpoint = "lateral",
specular = "black",
new_window = FALSE)
widget <- rgl::rglwidget()
rgl::close3d()
widget
}
The viewpoint argument can be set to common anatomical
views like "lateral", "medial",
"ventral", or "posterior". The function
automatically selects the correct left/right version based on the
surface’s hemisphere information (surf@hemi).
# Display multiple viewpoints with curvature shading
render_multi_view(white_lh_display,
viewpoints = c("lateral", "medial", "ventral", "posterior"),
bgcol = curv_cols_smooth(curv_lh_display), specular = "black")