view_surf: View '"surf"' object(s)

In ciftiTools: Tools for Reading, Writing, Viewing and Manipulating CIFTI Files

View "surf" object(s)

Description

Visualize one or two "surf" objects(s), or the "surf" component(s) in a "xifti" using an interactive Open GL window made with rgl. The rgl package is required.

Usage

view_surf(
  ...,
  view = c("both", "lateral", "medial"),
  widget = NULL,
  title = NULL,
  fname = FALSE,
  cex.title = NULL,
  text_color = "black",
  bg = NULL,
  alpha = 1,
  edge_color = NULL,
  vertex_color = NULL,
  vertex_size = 0,
  material = NULL,
  width = NULL,
  height = NULL,
  zoom = NULL
)

Arguments

...	One of: A "surf" object; two "surf" objects; or, a "xifti" object. If a "surf" object has an empty "hemisphere" metadata entry, it will be set to the opposite side of the other's if known; otherwise, it will be set to the left side. If both are unknown, the first will be taken as the left and the second as the right.
view	Which view to display: "lateral", "medial", or "both". If NULL (default), both views will be shown. Each view will be plotted in a separate panel row.
widget	Display the plot in an htmlwidget? Should be logical or NULL (default), in which case a widget will be used only if needed (length(idx)>1 & isFALSE(fname), fname is a file path to an .html file, or if rgl.useNULL()).
title	Optional title(s) for the plot(s). It will be printed at the top in a separate subplot with 1/4 the height of the brain cortex subplots. Default: NULL will not use any title if length(idx)==1. Otherwise, it will use the time index (".dtseries") or name (.dscalar or .dlabel) of each data column. To use a custom title(s), use a length 1 character vector (same title for each plot) or length length(idx) character vector (different title for each plot). Set to NULL or an empty character to omit the title. If the title is non-empty but does not appear, try lowering cex.title.
fname	Save the plot(s) (and color legend if applicable)? If isFALSE(fname) (default), no files will be written. If fname is a length-1 character vector ending in ".html", an html with an interactive widget will be written. If neither of the cases above apply, a png image will be written for each idx. If isTRUE(fname) the files will be named by the data column names (underscores will replace spaces). Or, set fname to a length 1 character vector to name files by this suffix followed by the fname_suffix. Or, set fname to a character vector with the same length as idx to name the files exactly.
cex.title	Font size multiplier for the title. NULL (default) will use 2 for titles less than 20 characters long, and smaller sizes for increasingly longer titles.
text_color	Color for text in title and colorbar legend. Default: "black".
bg	Background color. NULL will use "white". Does not affect the color legend or color bar if printed separately: those will always have white backgrounds.
alpha	Transparency value for mesh coloring, between 0 and 1. Default: 1.0 (no transparency).
edge_color	Outline each edge in this color. Default: NULL (do not outline the edges).
vertex_color	Draw each vertex in this color. Default: "black". Vertices are only drawn if vertex_size > 0
vertex_size	Draw each vertex with this size. Default: 0 (do not draw the vertices).
material	A list of materials from material3d to use. For example, list(lit=FALSE, smooth=FALSE) will use exact colors from the color scale, rather than adding geometric shading and interpolating vertex colors. If NULL, use defaults.
width, height	The dimensions of the RGL window, in pixels. If both are NULL (default), these dimensions depend on type of output (Open GL window or widget) and subplots (hemisphere, view, title, and slider_title) and are chosen to be the largest plot within a 1500 x 700 area (Open GL window) or 600 x 700 area (widget) that maintains a brain hemisphere subplot dimensions ratio of 10 x 7. Specifying only one will set the other to maintain this aspect ratio. Both can be specified to set the dimensions exactly, but note that the dimensions cannot be larger than the screen resolution. (These arguments do not affect the size of the legend, which cannot be controlled.) The plot will be taller than height to accommodate a title or color bar. If multiple idx are being composited with together, these arguments refer to a single idx within the composited plot, and not the composited plot itself.
zoom	Adjust the sizes of the brain meshes. Default: NULL (will be set to 0.6 or 160\ widget.)

Details

This function works as a wrapper to view_xifti_surface, but some arguments are not applicable (e.g. color scheme and legend). Also, instead of using the hemisphere argument, name the surface arguments surfL or surfR (see description for parameter ...). Finally, the default value for param is "surf", not "xifti".

Navigating and Embedding the Interactive Plots

To navigate the interactive Open GL window and html widget, left click and drag the cursor to rotate the meshes. Use the scroll wheel or right click and drag to zoom. Press the scroll wheel and drag to change the field-of-view. For Open GL windows, execute snapshot to save the current window as a .png file, close3d to close the window, and view3d to programmatically control the perspective.

To embed an interactive plot in an R Markdown document, first execute rgl::setupKnitr() to prepare the document for embedding the widget. Then execute the plot command as you normally would to create a widget (i.e. without specifying fname, and by requesting more than one idx or by setting widget to TRUE). When the R Markdown document is knitted, the interactive widget should be displayed below the chunk in which the plot command was executed. See the vignette for an example.

Embedding the Static Plots

To embed a static plot in an R Markdown document, first execute rgl::setupKnitr() to prepare the document for embedding the snapshot of the Open GL window. Then execute the plot command as you normally would to create an Open GL window (i.e. without specifying fname, and by requesting only one idx). In the options for the chunk in which the plot command is executed, set rgl=TRUE, format="png". You can also control the image dimensions here e.g. fig.height=3.8, fig.width=5. When the R Markdown document is knitted, the static plots should be displayed below the chunk in which the plot command was executed. See the vignette for an example.

See Also

Other visualizing: view_comp(), view_xifti(), view_xifti_surface(), view_xifti_volume()

Other surface-related: add_surf(), boundary_mask_surf(), edit_mask_surf(), even_vert_samp(), is.surf(), load_surf(), mask_surf(), read_surf(), resample_surf(), rotate_surf(), surf_area(), write_surf_gifti()

ciftiTools documentation built on Oct. 4, 2024, 1:12 a.m.