"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"),
width = NULL,
height = NULL,
zoom = NULL,
bg = NULL,
title = NULL,
cex.title = NULL,
text_color = "black",
save = FALSE,
close_after_save = TRUE,
fname = "surf",
alpha = 1,
edge_color = NULL,
vertex_color = NULL,
vertex_size = 0,
mode = 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.
The dimensions of the RGL window, in pixels. If both are
NULL (default), the dimensions will be set to
1000 (width) x 700 (height) for 1x1 and 2x2 subplots,
1500 x 525 for 2x1 subplots, and
500 x 700 for 1x2 subplots. These defaults are chosen to fit comfortably
within a 1600 x 900 screen. Specyfing only one will set the other to maintain
the same aspect ratio. Both can be specified to set the dimensions exactly.
The dimensions of the RGL window, in pixels. If both are
NULL (default), the dimensions will be set to
1000 (width) x 700 (height) for 1x1 and 2x2 subplots,
1500 x 525 for 2x1 subplots, and
500 x 700 for 1x2 subplots. These defaults are chosen to fit comfortably
within a 1600 x 900 screen. Specyfing only one will set the other to maintain
the same aspect ratio. Both can be specified to set the dimensions exactly.
Adjustment to size of brain meshes. Default: 3/5
(100% + 3/5*100% = 160% the original size).
Background color. NULL will not color the background (white).
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 use the time index (".dtseries") or name
(.dscalar or .dlabel) of the data column being plotted.
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 an empty string "" to omit the title.
If the title is non-empty but does not appear, cex.title may need to
be lowered.
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".
Save the plot to a .png file named by fname? Default:
FALSE.
If save==TRUE, close the interactive Open GL
window at the end of this function call? Default: TRUE.
An identifier to use for naming the saved images
("[fname].png") or video frames ("[fname]_1.png", "[fname]_2.png", ...).
Default: "xifti" for xifti_view_surface and "surf" for
view_surf.
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).
Deprecated: has no effect and will be removed. See save
and close_after_save.
This function opens an interactive Open GL window rendered by rgl.
If save==TRUE and close_after_save==TRUE, the window will be
closed after the function call. Otherwise, it is kept open and the following
information applies:
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. Execute snapshot to save the
current window as a .png file. Execute rgl.close to close
the window. rgl.viewpoint can be used for programmatic
navigation.
The Open GL window can be embedded as an htmlwidget in an R Markdown document
using one of two methods. The first is executing rglwidget
in the chunk where the plot is made. This first method should work within
both the RStudio IDE and a knitted .html file. The second method is
executing setupKnitr at the start of the document and
then using the chunk option webgl=TRUE in the chunk where the plot is
made. The second method is specifically for knitted .html files. Although
the first method is the newest approach and is recommended by others, we
used the second method in the ciftiTools vignette because the first
is not compatible with htmlpreview. For both methods, the window still
needs to be open to render the widget. Also for both methods, 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.
For view_xifti_surface, if length(idx) > 1, this function will
automaticaly return an htmlwidget using the first method, but with a
playwidget wrapper to add a slider to control which
column index is being displayed. All the meshes will be rendered on top of
one another in the Open GL window, so only the widget will be useful for
viewing the data interactively. Since it uses the first method, it will not
be visible with htmlpreview. No additional call to
rglwidget is necessary, but rgl.close
must be called in a following chunk to close the Open GL window.
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".