R: Integrating 'rgl' with 'Sweave'

rgl.Sweave {rgl} | R Documentation

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

[Package rgl version 0.99.9 Index]