setupKnitr {rgl}

Displaying RGL scenes in knitr documents

Description

These functions allow RGL graphics to be embedded in knitr documents.

The simplest method is to run setupKnitr(autoprint = TRUE) early in the document. That way RGL commands act a lot like base graphics commands: plots will be automatically inserted where appropriate, according to the fig.keep chunk option. By default (fig.keep = "high"), only high-level plots are kept, after low-level changes have been merged into them. See the knitr documentation https://yihui.org/knitr/options/#plots for more details. To suppress auto-printing, the RGL calls can be wrapped in invisible(). Similarly to grid graphics (used by lattice and ggplot2), automatic inclusion requires the object to be printed: only the last statement in a code block in braces is automatically printed. Unlike those packages, auto-printing is the only way to get this to work: calling print explicitly doesn't work.

Other functions allow embedding either as bitmaps (hook_rgl with format "png"), fixed vector graphics (hook_rgl with format "eps", "pdf" or "postscript"), or interactive WebGL graphics (hook_webgl). hook_rglchunk is not normally invoked by the user; it is the hook that supports automatic creation and deletion of RGL scenes.

Usage

setupKnitr(autoprint = FALSE,
           rgl.newwindow = autoprint,
           rgl.closewindows = autoprint)
hook_rgl(before, options, envir)
hook_webgl(before, options, envir)
hook_rglchunk(before, options, envir)

Arguments

autoprint

If true, RGL commands automatically plot (with low level plots suppressed by the default value of the fig.keep chunk option.)

rgl.newwindow, rgl.closewindows

Default values for the knitr chunk options.

before, options, envir

Standard knitr hook function arguments.

Details

The setupKnitr() function needs to be called once at the start of the document to install the knitr hooks. If it is called twice in the same session the second call will override the first.

The following chunk options are supported:

• rgl.newwindow: Whether to open a new window for the chunk. Default is set by setupKnitr argument.

• rgl.closewindows: Whether to close windows at the end of the chunk. Default is set by setupKnitr argument.

• rgl.margin (default 100): number of pixels by which to indent the WebGL window.

• snapshot: Logical value: when autoprinting in HTML, should a snapshot be used instead of the dynamic WebGL display? Corresponds to rglwidget(snapshot = TRUE, webgl = FALSE). Ignored in LaTeX, where a snapshot will always be produced (unless fig.keep specifies no figure at all).

• dpi, fig.retina, fig.width, fig.height: standard knitr chunk options used to set the size of the output.

• fig.keep, fig.hold, fig.beforecode: standard knitr chunk options used to control the display of plots.

• dev: used by hook_rgl to set the output format. May be "eps", "postscript", "pdf" or "png" (default: "png").

• rgl.keepopen: no longer used. Ignored with a warning.

• fig.alt is partially supported: rgl will always use the first entry if fig.alt is a vector. Other graphics types match the entries in fig.alt to successive plots within the chunk. (This is due to a limitation in knitr, and may change in the future.)

Value

A string to be embedded into the output, or NULL if called when no output is available.

Note

The setupKnitr(autoprint = TRUE) method assumes all printing of RGL objects happens through auto-printing of objects produced by the lowlevel or highlevel functions. All RGL functions that produce graphics do this, but functions in other packages that call them may not return values appropriately.

Mixing explicit calls to rglwidget with auto-printing is likely to lead to failure of some scenes to display. To avoid this, set options(rgl.printRglwidget = FALSE) before using such explicit calls. Similarly, use that option before calling the example function in a code chunk if the example prints RGL objects.

Author(s)

The hook* functions are originally by Yihui Xie in the knitr package; and have been modified by Duncan Murdoch. Some parts of the setupKnitr function duplicate source code from knitr.