"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,
material = NULL,
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). Or, 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"). Or, set fname to a character vector with the same
length as idx to name the files exactly.
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 use "white". Does not affect
the color legend or color bar if printed separately: those will always have
white backgrounds.
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).
A list of materials from rgl.material
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.
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.
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.
Adjust the sizes of the brain meshes. Default: NULL (will
be set to 0.6 or 160\
widget.)
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,
rgl.close to close the window, and
rgl.viewpoint 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.
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.
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".
Other functions for working with GIFTI surface geometry data:
is.surf(),
read_surf(),
resample_surf(),
rotate_surf(),
write_surf_gifti()