setupKnitr.RdThese 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.
setupKnitr(autoprint = FALSE,
rgl.newwindow = autoprint,
rgl.closewindows = autoprint)
hook_rgl(before, options, envir)
hook_webgl(before, options, envir)
hook_rglchunk(before, options, envir)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.
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.)
A string to be embedded into the output, or NULL if called
when no output is available.