Introduction to ggseg3d
In ggseg3d: Interactive 3D Brain Atlas Visualization

#| label: intro-setup
#| include: false
knitr::opts_chunk$set(
  message = FALSE,
  eval = interactive()
)
library(ggseg3d)
library(dplyr)
dir.create("img", showWarnings = FALSE)

Brain segmentation results are easier to interpret when they look like a brain. ggseg3d takes a data frame with region names and renders it as an interactive 3D mesh — rotate, zoom, hover for labels — right in the browser.

Getting started

#| label: intro-basic
#| eval: false
library(ggseg3d)

ggseg3d(hemisphere = "left") |>
  pan_camera("left lateral")

#| label: intro-snap-basic
#| echo: false
ggseg3d(hemisphere = "left") |>
  pan_camera("left lateral") |>
  snapshot_brain("img/intro-basic.png")

Left hemisphere of the Desikan-Killiany atlas, each cortical region in a distinct colour, viewed from the lateral side.

With no arguments, ggseg3d() plots the Desikan-Killiany atlas. The output is an htmlwidget: click and drag to rotate, scroll to zoom, hover to see region names.

Mapping data

Match your data to the atlas by region name, then point colour_by at the variable you care about:

#| label: intro-plot-data
#| eval: false
library(dplyr)

some_data <- tibble(
  region = c("precentral", "postcentral", "insula", "superior parietal"),
  p = c(0.01, 0.04, 0.2, 0.5)
)

ggseg3d(.data = some_data, atlas = dk(), colour_by = "p", text_by = "p") |>
  pan_camera("right lateral")

#| label: intro-snap-plot-data
#| echo: false
some_data <- tibble(
  region = c("precentral", "postcentral", "insula", "superior parietal"),
  p = c(0.01, 0.04, 0.2, 0.5)
)

ggseg3d(.data = some_data, atlas = dk(), colour_by = "p", text_by = "p") |>
  pan_camera("right lateral") |>
  snapshot_brain("img/intro-plot-data.png")

Right hemisphere with four cortical regions coloured on a blue-to-red scale by p-value; unmatched regions shown in grey.

text_by = "p" adds the p-value to the hover tooltip so you can inspect individual regions without a separate table.

Subcortical atlases

Cortical surfaces are only half the story. The aseg atlas covers subcortical structures, and add_glassbrain() wraps them in a translucent cortex for anatomical context:

#| label: intro-subcortical
#| eval: false
subcort_data <- tibble(
  region = c("Thalamus", "Caudate", "Hippocampus"),
  p = c(0.2, 0.5, 0.8)
)

ggseg3d(.data = subcort_data, atlas = aseg(), colour_by = "p", na_alpha = .5) |>
  add_glassbrain()

#| label: intro-snap-subcortical
#| echo: false
subcort_data <- tibble(
  region = c("Thalamus", "Caudate", "Hippocampus"),
  p = c(0.2, 0.5, 0.8)
)

ggseg3d(.data = subcort_data, atlas = aseg(), colour_by = "p", na_alpha = .5) |>
  add_glassbrain() |>
  snapshot_brain("img/intro-subcortical.png")

Thalamus, caudate, and hippocampus coloured by p-value, visible through a semi-transparent cortical shell.

Camera and background

pan_camera() sets the viewing angle. set_background() changes the canvas colour — handy for dark-themed slides:

#| label: intro-camera
#| eval: false
ggseg3d(hemisphere = "left") |>
  pan_camera("left lateral") |>
  set_background("black")

#| label: intro-snap-camera
#| echo: false
ggseg3d(hemisphere = "left") |>
  pan_camera("left lateral") |>
  set_background("black") |>
  snapshot_brain("img/intro-background.png")

Left hemisphere on a black background, cortical regions visible in their default atlas colours.

Camera presets cover the standard anatomical views: "left lateral", "right medial", "left superior", and so on. For anything else, pass a list with eye coordinates.