Skip to contents

Sooner or later you want something on the brain that is not a parcellation: electrode positions, a stimulation target, the peak of a cluster. add_points() draws those, and add_atlas() puts a second atlas in the same scene.

The drawing is the easy part. The part worth reading about is which coordinates to give them, because a plausible-looking number in the wrong space produces a plausible-looking picture that is wrong.

Points need a surface that means something

Every ggseg3d cortical surface is fsaverage5, but they are not interchangeable. "white" and "pial" keep the brain’s own shape. "inflated" — what ggseg3d() draws by default — has had every vertex moved outward to smooth the folds away.

Here is the same set of coordinates on both. They were taken straight off the pial surface, so they sit exactly on it:

pial <- resolve_brain_mesh("rh", "pial")$vertices
set.seed(7)
pts <- pial[sample(nrow(pial), 14), ]

ggseg3d(atlas = dk(), hemisphere = "right", surface = "pial") |>
  add_points(pts, x = x, y = y, z = z, colour = "#111111", size = 4) |>
  pan_camera("right lateral")
Right hemisphere pial surface in DK atlas colours, with fourteen black markers spread across the lateral surface, each sitting on the cortex.
Right hemisphere pial surface in DK atlas colours, with fourteen black markers spread across the lateral surface, each sitting on the cortex.

Change nothing but the surface and most of them disappear inside the brain:

ggseg3d(atlas = dk(), hemisphere = "right", surface = "inflated") |>
  add_points(pts, x = x, y = y, z = z, colour = "#111111", size = 4) |>
  pan_camera("right lateral")
The same right hemisphere inflated smooth, with only four of the fourteen markers still visible near the top edge; the rest are hidden inside the larger surface.
The same right hemisphere inflated smooth, with only four of the fourteen markers still visible near the top edge; the rest are hidden inside the larger surface.

Nothing went wrong in either plot. The inflated surface is simply a different shape, so a position on the real brain is not a position on it. Plot measured coordinates on "pial" or "white".

Getting coordinates from a standard space

If your positions come from somewhere else — a montage file, a coordinate table, a paper — they are probably in MNI. mni_to_mesh() converts them:

mni_to_mesh(-42, -20, 55, hemisphere = "lh")
##           x   y  z
## 1 -43.22156 -20 55

The shift is small because the surfaces nearly are MNI already. fsaverage is an MNI305 average, so its coordinates are MNI305; the only difference is that each hemisphere is nudged sideways so the two meet at x = 0 and can be drawn together. mesh_to_mni() undoes that.

Pass space = "mni152" if your coordinates are MNI152 rather than MNI305. Across the brain that is worth two to three millimetres:

rbind(
  mni305 = mni_to_mesh(-42, -20, 55, hemisphere = "lh"),
  mni152 = mni_to_mesh(-42, -20, 55, hemisphere = "lh", space = "mni152")
)
##                x         y        z
## mni305 -43.22156 -20.00000 55.00000
## mni152 -44.37479 -20.77315 53.21614

Asking for an inflated surface is an error rather than a number, because there is no honest answer:

mesh_to_mni(-42, -20, 55, hemisphere = "lh", surface = "inflated")
## Error in `mesh_to_mni()`:
## ! "inflated" has no anatomical coordinates to convert.
## ✖ Inflation and spherical registration move every vertex, so a position on this
##   surface does not correspond to a place in the brain.
## ℹ Use one of "white", "pial", "midthickness", "smoothwm", and "orig".

A worked example

Three motor-cortex coordinates:

targets <- data.frame(
  label = c("M1 hand", "M1 face", "SMA"),
  x = c(-38, -52, -4),
  y = c(-22, -8, -4),
  z = c(56, 34, 58)
)

placed <- mni_to_mesh(targets$x, targets$y, targets$z, hemisphere = "lh")
placed$label <- targets$label
placed
##            x   y  z   label
## 1 -39.221563 -22 56 M1 hand
## 2 -53.221563  -8 34 M1 face
## 3  -5.221563  -4 58     SMA

Draw those directly and you will see nothing at all, which is worth understanding rather than working around. A coordinate reported as a peak is a point in grey matter, a millimetre or two beneath the surface — so the marker is there, with the cortex in front of it. That is the opposite of the earlier failure: these are in exactly the right place, and still invisible.

Either make the marker big enough to break the surface, or put it on the surface. Projecting to the nearest vertex is a few lines and keeps the position honest:

pial <- resolve_brain_mesh("lh", "pial")$vertices

on_surface <- do.call(rbind, lapply(seq_len(nrow(placed)), function(i) {
  d2 <- (pial$x - placed$x[i])^2 +
    (pial$y - placed$y[i])^2 +
    (pial$z - placed$z[i])^2
  pial[which.min(d2), ]
}))
on_surface$label <- placed$label

This one is live: drag to rotate, and hover a marker for its name.

ggseg3d(atlas = dk(), hemisphere = "left", surface = "pial") |>
  add_points(on_surface, x = x, y = y, z = z, text = label,
             colour = "#D7191C", size = 4) |>
  pan_camera("left lateral")

colour and size take one value or one per row, so a column of values can drive either.

Two atlases at once

add_atlas() draws another atlas into the same scene — subcortical structures inside a cortical surface, say:

ggseg3d(atlas = dk(), hemisphere = "left") |>
  add_atlas(aseg()) |>
  pan_camera("right lateral")
Medial view of the left hemisphere with aseg structures inside it: thalamus, hippocampus, caudate and putamen, the ventricles, brain stem and cerebellum, each in its own colour.
Medial view of the left hemisphere with aseg structures inside it: thalamus, hippocampus, caudate and putamen, the ventricles, brain stem and cerebellum, each in its own colour.

Or the other way round, with the cortex as a translucent shell:

ggseg3d(atlas = aseg()) |>
  add_glassbrain(opacity = 0.12) |>
  pan_camera("right lateral")
The same subcortical structures seen through a faint translucent cortical shell, with the cerebellum extending past the shell at the lower left.
The same subcortical structures seen through a faint translucent cortical shell, with the cerebellum extending past the shell at the lower left.

Two things to know.

The atlases are not registered against each other. They line up because the ggsegverse atlases share an anatomical frame, not because add_atlas() reconciles them. If you bring your own atlas from elsewhere, check that it agrees before trusting the overlap.

And the legend describes the atlas the plot was built from, not the one added. If the second atlas needs a readable legend, build the plot from that one and add the other.

Why the cerebellum sticks out

In the picture above the cerebellum extends past the glass brain. That is anatomically right — the cerebellum is not inside the cerebral cortex — but the default glass brain is the inflated surface, which is larger and rounder than any real brain. For judging whether something sits inside the cortex, use an anatomical shell:

ggseg3d(atlas = aseg()) |>
  add_glassbrain(surface = "white", opacity = 0.15)

In short

  • Measured coordinates belong on "pial" or "white", never "inflated".
  • mni_to_mesh() gets you there from MNI305 or MNI152.
  • A peak coordinate sits inside the cortex; project it to the surface, or enlarge the marker, if you expect to see it.
  • add_atlas() composes atlases that already share a frame; it does not create one.