Skip to contents

Draws markers at coordinates of your own – electrode or sensor positions, stimulation sites, anything with an x, y and z. Up to ggseg3d 1.6.5 this was done with plotly's add_trace(); plotly is no longer the renderer, and this replaces it.

Usage

add_points(
  p,
  data,
  x = x,
  y = y,
  z = z,
  colour = "#FF0000",
  size = 3,
  text = NULL,
  opacity = 1
)

Arguments

p

A ggseg3d widget or ggsegray rgl object.

data

A data.frame of marker positions.

x, y, z

Columns of data holding the coordinates.

colour

Marker colour (hex or named), either one value or one per row of data.

size

Marker radius, in the same units as the coordinates. One value or one per row.

text

Column of data to show on hover, or NULL for none.

opacity

Numeric. Marker transparency (0-1).

Value

The input object, for piping. A ggsegray is returned unchanged: rgl draws to the open device rather than into the object.

Details

Coordinates are taken in the space of the surface already drawn, with x left-right, y posterior-anterior and z inferior-superior. Which surface that is decides whether measured positions land where they should:

  • "pial" and "white" are the anatomical surfaces. Pial spans about x -70 to 70, y -105 to 69 and z -48 to 79; white sits a few millimetres inside that. These are fsaverage surface coordinates, so positions recorded in a standard space land roughly where they belong without a transform.

  • "inflated", which ggseg3d() draws by default, is not anatomical. Inflation moves every vertex outward, leaving a rounder surface spanning about x -83 to 82 and z -73 to 73. Measured positions do not correspond to it, so plot them on surface = "pial" instead.

A coordinate taken from a standard space is usually a point inside the grey matter rather than on its surface, so a marker drawn at one can be hidden by the cortex around it. Raise size, or draw the surface with add_glassbrain() over a subcortical atlas, if a marker does not appear.

Markers are drawn as small spheres, so they shade and occlude like the rest of the scene rather than floating in front of it.

Examples

sensors <- data.frame(
  x = c(50, 45, 40),
  y = c(22, -10, -40),
  z = c(16, 40, 30),
  name = c("C4", "P4", "O2")
)

# \donttest{
# on an anatomical surface, so the coordinates mean something
ggseg3d(atlas = dk(), hemisphere = "right", surface = "pial") |>
  add_points(sensors, x = x, y = y, z = z, text = name)
# }