| rgl.Sweave {rgl} | R Documentation |
rgl with Sweave
As of R 2.13.0, it is possible to include rgl graphics into
a Sweave document. These functions support that
integration.
Sweave.snapshot() rgl.Sweave(name, width, height, options, ...) rgl.Sweave.off()
name, width, height, options, ... |
These arguments are passed by |
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>>=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:
(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.
(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.
(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.
These functions are called for their side effects.
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.
It is possible to use this driver in R version 2.13.0, but there are problems
because there is no automatic call to rgl.Sweave.off() at the
end of a chunk, because the chunk is always run at least twice in that
version of R, and because custom string options are not supported.
An explicit call to rgl.Sweave.off() as the last
line of the code chunk is recommended, though efforts are made to do the right thing
if this is omitted. Some other notes that apply to R version 2.13.0:
Calling rgl.close() within the chunk should work.
If neither rgl.Sweave.off() nor rgl.close() is called and
a new chunk with grdevice=rgl.Sweave is opened, a call to
rgl.Sweave.off() will be inserted. However, the last chunk with
grdevice=rgl.Sweave will not be automatically closed.
Running Sweave() within R is likely to leave a number of
open rgl device windows.
It is not possible to specify the output type using the outputtype
chunk option. Snapshots will always be saved in ‘.png’ format.
Most of these problems are fixed in later versions of R, including 2.13.0-patched.
Within the R 2.13.x series, it is recommended to use the
figs.only=TRUE, pdf=FALSE options (and leave the other
graphics drivers at their default FALSE settings), which cause
the code in the chunk to be run only once.
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.
Duncan Murdoch
RweaveLatex for a description of alternate graphics drivers
in Sweave, and standard options that can be used in code chunks.