This document describes how to embed
rgl, see rgl Overview.
We assume that the HTML document is produced from R markdown source using
rmarkdown. This format mixes text with Markdown markup with chunks of R code. There is a limited amount of discussion of other methods.
There are two ways to embed an
rgl scene in the document. The recommended one is to call
rglwidget to produce a “widget” which can be embedded into your document by printing it.
Older methods (e.g.
writeWebGL) used before
rgl version 0.102.0 are no longer supported.
I have conducted experiments on a third method. This is intended to be similar to the way standard 2D graphics are included by
knitr, i.e. it will detect the fact that you’ve drawn something, and just include it automatically. At present it is not recommended, but that may change in the future.
Most browsers now support WebGL, but in some browsers it may be disabled by default. See https://get.webgl.org for help on a number of different browsers.
We start with a simple plot of the iris data. We insert a code chunk and call the
rglwidget function with optional argument
library(rgl) <- with(iris, plot3d(Sepal.Length, Sepal.Width, Petal.Length, plotids type="s", col=as.numeric(Species))) rglwidget(elementId = "plot3drgl")
Next we insert a button to toggle the display of the data.
toggleWidget(sceneId = "plot3drgl", ids = plotids["data"], label = "Data")
sceneId is the same as the
elementId we used in
ids are the object ids of the objects that we’d like to toggle, and the
label is the label shown on the button. To find the names in the
plotids variable, apply
##  "data" "axes" "xlab" "ylab" "zlab"
## data axes xlab ylab zlab ## 13 14 15 16 17
magrittror base pipes
It can be error-prone to set the
elementId in the
rglwidget() to match the
sceneId in the
playwidget(), described below). In the usual case where both are intended to appear together,
magrittr-style pipes can be used quite flexibly: the first argument of the control widget accepts the result of
rglwidget() (or other control widgets), and the
controllers argument of
rglwidget() accepts control widgets. In R 4.1.0, the new base pipe operator
|> should be usable in the same way.
rglwidget() %>% toggleWidget(ids = plotids["data"], label = "Data")
If you have R 4.1.0 or greater, this should do the same:
rglwidget() |> toggleWidget(ids = plotids["data"], label = "Data")
You can swap the order of button and scene; use the
magrittr dot (or the
=> syntax in base pipes) to pass the
rglwidget in the
toggleWidget(NA, ids = plotids["data"], label = "Data") %>% rglwidget(controllers = .)
or using R 4.1.0 or later,
toggleWidget(NA, ids = plotids["data"], label = "Data") |> => rglwidget(controllers = w) w
We have seen how to change the contents of the plot using
toggleWidget. We can do more elaborate displays. For example, we can redo the previous plot, but with the three species as separate “spheres” objects and buttons to toggle them:
clear3d() # Remove the earlier display <- with(subset(iris, Species == "setosa"), setosa spheres3d(Sepal.Length, Sepal.Width, Petal.Length, col=as.numeric(Species), radius = 0.211)) <- with(subset(iris, Species == "versicolor"), versicolor spheres3d(Sepal.Length, Sepal.Width, Petal.Length, col=as.numeric(Species), radius = 0.211)) <- with(subset(iris, Species == "virginica"), virginica spheres3d(Sepal.Length, Sepal.Width, Petal.Length, col=as.numeric(Species), radius = 0.211)) aspect3d(1,1,1) <- decorate3d() axesid rglwidget() %>% toggleWidget(ids = setosa) %>% toggleWidget(ids = versicolor) %>% toggleWidget(ids = virginica) %>% toggleWidget(ids = axesid) %>% asRow(last = 4)
Since we skipped the
label argument, the buttons are labelled with the name of the variable passed as
asRow function is discussed below.
toggleWidget() is actually a convenient wrapper for two functions:
playwidget() adds the button to the web page (and can also add sliders, do animations, etc.), while
subsetControl() chooses a subset of objects to display.
For a more general example, we could use a slider to select several subsets of the data in the iris display. For example,
rglwidget() %>% playwidget(start = 0, stop = 3, interval = 1, subsetControl(1, subsets = list( Setosa = setosa, Versicolor = versicolor, Virginica = virginica, All = c(setosa, versicolor, virginica) )))