view_surface: Display a Brain Surface with RGL

In bbuchsbaum/neurosurf: Data structures and IO for surface-based neuroimaging data

Display a Brain Surface with RGL

Description

This function visualizes a 3D brain surface using the rgl package. It allows for the rendering of a surface with optional vertex colors, transparency, and lighting effects. Additionally, the function supports the display of spheres at specified coordinates on the surface, making it versatile for highlighting specific regions or points of interest.

Usage

view_surface(
  surfgeom,
  vals = NA,
  cmap = rainbow(256, alpha = 1),
  vert_clrs = NULL,
  bgcol = "lightgray",
  alpha = 1,
  add_normals = TRUE,
  thresh = NULL,
  irange = range(vals, na.rm = TRUE),
  specular = "white",
  viewpoint = c("lateral", "medial", "ventral", "posterior"),
  new_window = TRUE,
  offset = c(0, 0, 0),
  zoom = 1,
  spheres = NULL,
  ...
)

Arguments

surfgeom	A SurfaceGeometry object representing the 3D brain surface geometry to be displayed.
vals	A numeric vector of values corresponding to each surface node. These values will be mapped to colors using the provided color map (cmap).
cmap	A color map consisting of a vector of colors in hex format. Default is rainbow(256, alpha = 1). This color map is used to color the surface based on the vals vector.
vert_clrs	Optional vertex colors in hex format. If provided, these colors will override the colors generated from vals and cmap.
bgcol	A color or vector of colors in hex format used to shade the surface background. Default is "lightgray".
alpha	A numeric value indicating the transparency level of the surface. The default is 1 (fully opaque). Values should be between 0 (fully transparent) and 1 (fully opaque).
add_normals	Logical, indicating whether to add normals to the surface mesh. This is useful for improving the lighting effects. Default is TRUE.
thresh	A numeric vector of length 2 indicating the lower and upper transparency thresholds. Nodes with values outside this range will be made transparent.
irange	A numeric vector of length 2 indicating the lower and upper bounds of the intensity range for the color scale. Default is the range of vals.
specular	A color in hex format or a numeric value indicating the specular reflection color used for lighting. Default is "white".
viewpoint	A character string specifying the initial viewpoint of the surface. Options are "lateral", "medial", "ventral", or "posterior".
new_window	Logical, indicating whether to open a new RGL window for the surface display. Default is TRUE. If FALSE, the current RGL window will be cleared and reused.
offset	A numeric vector of length 3 specifying the translation offset of the surface in the x, y, and z directions. Default is c(0, 0, 0).
zoom	A numeric value specifying the zoom factor. Default is 1 (no zoom).
spheres	Optional. A data frame containing the coordinates (x, y, z), radii (radius), and optional colors (color) for spheres to be displayed on the surface. Each row represents a sphere.
...	Additional arguments passed to rgl::shade3d.

Value

An object returned by rgl::shade3d representing the rendered surface. This can be used for further manipulation of the rendered object.

See Also

shade3d, spheres3d, view3d

Examples

## Not run: 
  # Example surface geometry object (assuming `white_surf` is preloaded)
  sphere_data <- data.frame(
    x = c(10, 20, 30),
    y = c(10, 20, 30),
    z = c(10, 20, 30),
    radius = c(2, 3, 4),
    color = c("#FF0000", "#00FF00", "#0000FF")
  )

  # Display the surface with spheres
  view_surface(white_surf, viewpoint = "lateral", spheres = sphere_data)

## End(Not run)

bbuchsbaum/neurosurf documentation built on Aug. 29, 2024, 10:53 a.m.