"surf" object(s)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.
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,
width = NULL,
height = NULL,
zoom = NULL
)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.
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.
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()).
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.
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). Set fname to a
length 1 character vector to name files by this suffix followed by the
fname_suffix: either the data column names ("names") or the
index value ("idx"). Set this to a character vector with the same
length as idx to name the files exactly.
If a separate color legend exists and !isFALSE(fname), it will be
saved to "[first_surf_fname]_legend.png".
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.
Color for text in title and colorbar legend. Default: "black".
Background color. NULL will not color the background (white).
Transparency value for mesh coloring, between 0 and 1. Default:
1.0 (no transparency).
Outline each edge in this color. Default: NULL (do
not outline the edges).
Draw each vertex in this color. Default:
"black". Vertices are only drawn if vertex_size > 0
Draw each vertex with this size. Default: 0
(do not draw the vertices).
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. (These arguments do not affect the size of the
legend, which cannot be controlled.)
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. (These arguments do not affect the size of the
legend, which cannot be controlled.)
Adjust the sizes of the brain meshes. Default: NULL (will
be set to 0.6 or 160\
widget.)
Here are instructions for using the interactive Open GL window and html widget:
To navigate the plot, left click and drag the cursor to rotate. 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,
rgl.close to close the window, and
rgl.viewpoint to programmatically control the
perspective.
See the vignette for examples on embedding snapshots of the Open GL window or interactive html widgets in an R Markdown document.
If save==TRUE, the plot(s) is written to a .png file. (For
view_xifti_surface, if length(idx) > 1, each idx will
be written to a separate image file.) You can use
include_graphics to embed an image file in an R
Markdown document. If close_after_save==TRUE, the return value of this
function call is the name(s) of the image file(s) that were written, so it
can be used directly to display the image.
There's an additional way to embed an image of this plot without writing a
.png file: use save==FALSE and set the chunk options
rgl=TRUE, format="png". You will probably need to tweak the image
dimensions e.g. fig.width=8, fig.height=5 in the chunk options,
because it uses the defaults from RMarkdown/Knitr instead of what makes
sense based on the dimensions of the Open GL window.
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".