Visualize "xifti" cortical data using an interactive Open GL window
made with rgl. The rgl and fields packages are required.
view_xifti_surface(
xifti,
idx = NULL,
hemisphere = NULL,
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 = "xifti",
colors = NULL,
color_mode = NULL,
zlim = NULL,
surfL = NULL,
surfR = NULL,
qualitative_colorlegend = TRUE,
colorlegend_ncol = NULL,
colorbar_embedded = TRUE,
colorbar_digits = NULL,
alpha = 1,
edge_color = NULL,
vertex_color = NULL,
vertex_size = 0,
border_color = NULL,
widget_idx_warn = NULL,
render_rgl = TRUE,
mode = NULL
)view_cifti_surface(
xifti,
idx = NULL,
hemisphere = NULL,
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 = "xifti",
colors = NULL,
color_mode = NULL,
zlim = NULL,
surfL = NULL,
surfR = NULL,
colorbar_embedded = TRUE,
colorbar_digits = NULL,
alpha = 1,
edge_color = NULL,
vertex_color = NULL,
vertex_size = 0,
widget_idx_warn = NULL,
render_rgl = TRUE,
mode = NULL
)
viewCIfTI_surface(
xifti,
idx = NULL,
hemisphere = NULL,
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 = "xifti",
colors = NULL,
color_mode = NULL,
zlim = NULL,
surfL = NULL,
surfR = NULL,
colorbar_embedded = TRUE,
colorbar_digits = NULL,
alpha = 1,
edge_color = NULL,
vertex_color = NULL,
vertex_size = 0,
widget_idx_warn = NULL,
render_rgl = TRUE,
mode = NULL
)
viewcii_surface(
xifti,
idx = NULL,
hemisphere = NULL,
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 = "xifti",
colors = NULL,
color_mode = NULL,
zlim = NULL,
surfL = NULL,
surfR = NULL,
colorbar_embedded = TRUE,
colorbar_digits = NULL,
alpha = 1,
edge_color = NULL,
vertex_color = NULL,
vertex_size = 0,
widget_idx_warn = NULL,
render_rgl = TRUE,
mode = NULL
)
Object of class "xifti".
See is.xifti and make_xifti.
The time/column index of the data to display. If its length is
greater than one and save==FALSE, use the widget instead of the
OpenGL window to view the plot interactively, because the widget's slider
will control what time/column is being displayed in the widget whereas all
meshes will be rendered on top of one another in the Open GL window.
Which brain cortex to display: "both", "left", or "right". Each will be plotted in a separate panel column.
If a brain cortex is requested but no surface is available, a default inflated surface will be used.
This argument can also be NULL (default). In this case, the default
inflated surface included with ciftiTools will be used for each
cortex with data (i.e. if xifti$data$cortex_left and/or
xifti$data$cortex_right exist).
Surfaces without data will be colored white.
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.
(Optional) "ROY_BIG_BL", vector of colors to use,
OR the name of a ColorBrewer palette (see RColorBrewer::brewer.pal.info
and colorbrewer2.org). Defaults are "ROY_BIG_BL" (sequential),
"Set2" (qualitative), and "ROY_BIG_BL" (diverging). An exception
to these defaults is if the "xifti" object represents a .dlabel CIFTI (intent 3007),
then the qualitative colors in the label table will be used.
See the ciftiTools::make_color_pal() description for more details.
(Optional) "sequential", "qualitative",
or "diverging". NULL will use the qualitative color mode if
the "xifti" object represents a .dlabel CIFTI (intent 3007), and the sequential
color mode otherwise. See the ciftiTools::make_color_pal()
description for more details.
(Optional) Controls the mapping of values to each
color in colors. If the length is longer than
one, using -Inf will set the value to DATA_MIN, and Inf will set
the value to DATA_MAX. See the
ciftiTools::make_color_pal() description for more details.
(Optional if xifti$surf$cortex_left and
xifti$surf$cortex_right are not empty) The brain surface model to use.
Each can be a file path for a GIFTI, a file read by gifti::readgii,
or a list with components "vertices" and "faces". If provided, they will override
xifti$surf$cortex_left and xifti$surf$cortex_right if they exist.
Otherwise, leave these arguments as NULL (default) to use
xifti$surf$cortex_left and xifti$surf$cortex_right.
If color_mode=="qualitative", should
the colorbar be replaced with a color legend? It will be printed separately
from the RGL window. Default: TRUE.
Number of columns in color legend. If
NULL (default), use 10 entries per row. Only applies if the color
legend is drawn (qualitative_colorlegend is TRUE and the
qualitative color mode is used).
Should the colorbar be embedded in the plot?
It will be positioned in the bottom-left corner, in a separate subplot
with 1/4 the height of the brain cortex subplots. Default: TRUE.
If FALSE, print it separately instead.
The number of digits for the colorbar legend ticks.
If NULL (default), let format decide.
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).
Only applicable if color_mode is
"qualitative". Border vertices will be identified (those that share a
faces with at least one vertex of a different value) and drawn in this color
instead, overriding the color indicated by their value. If NULL, do
not draw borders.
If save==FALSE or close_after_save==FALSE,
each mesh must be rendered in the same window. This is problematic if
idx and the mesh size are large. So, this option can be used to print
a warning when length(idx) exceeds widget_idx_warn and the
meshes are being drawn in the same window. Use Inf to never print a
warning. The default, NULL, will print a warning if idx times
the number of vertices exceeds 200k (approximately three 32k meshes for both
the left and right hemisphere.)
Default: TRUE. If FALSE, do not render the
Open GL window, widget, or image(s). Instead, return the rgl mesh
objects and coloring information. This should be used by developers only.
Deprecated: has no effect and will be removed. See save
and close_after_save.
If save and close_after_save, the name(s) of the image
file(s) that were written.
Otherwise, if the length of idx is equal to one, a list of the rgl
object IDs which can be used to further manipulate the Open GL window; if
the length of idx is greater than one, the htmlwidget with slider
to interactively control which timepoint is being displayed.
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.