rgl.Sweave {rgl}

Integrating RGL with Sweave

Description

As of R 2.13.0, it is possible to include RGL graphics into a Sweave document. These functions support that integration.

Usage

Sweave.snapshot()
rgl.Sweave(name, width, height, options, ...)
rgl.Sweave.off()

Arguments

name, width, height, options, ...

These arguments are passed by Sweave to rgl.Sweave when it opens the device.

Details

The rgl.Sweave function is not normally called by the user. The user specifies it as the graphics driver when opening the code chunk, e.g. by using

<<fig = TRUE, pdf = FALSE, grdevice = rgl.Sweave, resolution = 100>>=

When the RGL device is closed at the end of the code chunk, rgl.Sweave.off() will be called automatically. It will save a snapshot of the last image (by default in ‘.png’ format) for inclusion in the Sweave document and (by default) close the device. Alternatively, the Sweave.snapshot() function can be called to save the image before the end of the chunk. Only one snapshot will be taken per chunk.

Several chunk options are used by the rgl.Sweave device:

stayopen

(default FALSE). If TRUE then the RGL device will not be closed at the end of the chunk, instead a call to Sweave.snapshot() will be used if it has not been called explicitly. Subsequent chunks can add to the scene.

outputtype

(default png). The output may be specified as outputtype = pdf or outputtype = eps instead, in which case the rgl.postscript function will be used to write output in the specified format. Note that rgl.postscript has limitations and does not always render scenes correctly.

delay

(default 0.1). After creating the display window, Sys.sleep will be called to delay this many seconds, to allow the display system to initialize. This is needed in X11 systems which open the display asynchronously. If the default time is too short, rgl.Sweave may falsely report that the window is too large to open.

Value

These functions are called for their side effects.

Note

We recommend turning off all other graphics drivers in a chunk that uses grdevice = rgl.Sweave. The RGL functions do not write to a standard graphics device.

Note

The rgl package relies on your graphics hardware to render OpenGL scenes, and the default ‘.png’ output copies a bitmap from the hardware device. All such devices have limitations on the size of the bitmap, but they do not always signal these limitations in a way that RGL will detect. If you find that images are not being produced properly, try reducing the size using the resolution, width or height chunk options.

Author(s)

Duncan Murdoch

See Also

RweaveLatex for a description of alternate graphics drivers in Sweave, and standard options that can be used in code chunks.

hook_rgl and hook_webgl allow fixed or interactive RGL scenes to be embedded in knitr documents.