view_surf

0th

Percentile

View "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.

Usage
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
)
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.

width

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.

height

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.

zoom

Adjustment to size of brain meshes. Default: 3/5 (100% + 3/5*100% = 160% the original size).

bg

Background color. NULL will not color the background (white).

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 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.

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".

save

Save the plot to a .png file named by fname? Default: FALSE.

close_after_save

If save==TRUE, close the interactive Open GL window at the end of this function call? Default: TRUE.

fname

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.

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).

mode

Deprecated: has no effect and will be removed. See save and close_after_save.

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

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.

Embedding the Static Plots

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.

Aliases
  • view_surf
Documentation reproduced from package ciftiTools, version 0.1.6.0, License: GPL-3

Community examples

Looks like there are no examples yet.