This document describes how to embed rgl scenes in HTML documents and use embedded Javascript to control a WebGL display in an HTML document. For more general information about rgl, see rgl Overview.
We assume that the HTML document is produced from R markdown source using knitr or 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.
The older method is described in the Legacy WebGL Methods document. It is likely to be supported for some time, but is not recommended for new projects, as the widget method is easier for me to maintain.
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 http://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 elementId. This allows later Javascript code to refer to the image. We also save the object ids from the plot, so that they can be manipulated later.
library(rgl)
plotids <- with(iris, plot3d(Sepal.Length, Sepal.Width, Petal.Length,
type="s", col=as.numeric(Species)))
rglwidget(elementId = "plot3drgl")Next we insert a button to toggle the display of the data.
The sceneId is the same as the elementId we used in rglwidget(), the 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 names() or unclass():
## [1] "data" "axes" "xlab" "ylab" "zlab"## data axes xlab ylab zlab
## 7 8 9 10 11magrittr pipesIt can be error-prone to set the elementId in the rglwidget() to match the sceneId in the toggleWidget() (or 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. For example,
You can swap the order of button and scene; use the magrittr dot to pass the toggleWidget to rglwidget in the controllers argument:
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
setosa <- with(subset(iris, Species == "setosa"),
spheres3d(Sepal.Length, Sepal.Width, Petal.Length,
col=as.numeric(Species),
radius = 0.211))
versicolor <- with(subset(iris, Species == "versicolor"),
spheres3d(Sepal.Length, Sepal.Width, Petal.Length,
col=as.numeric(Species),
radius = 0.211))
virginica <- with(subset(iris, Species == "virginica"),
spheres3d(Sepal.Length, Sepal.Width, Petal.Length,
col=as.numeric(Species),
radius = 0.211))
aspect3d(1,1,1)
axesid <- decorate3d()
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 ids. The asRow function is discussed below.
toggleWidget() is actually a convenient wrapper for two functions: playwidget and subsetControl. 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.
subsetControlFor 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)
)))There are several other “control” functions.
par3dinterpControlpar3dinterpControl approximates the result of par3dinterp.
For example, the following code (similar to the play3d example) rotates the scene in a complex way.
M <- r3dDefaults$userMatrix
fn <- par3dinterp(time = (0:2)*0.75, userMatrix = list(M,
rotate3d(M, pi/2, 1, 0, 0),
rotate3d(M, pi/2, 0, 1, 0)) )
rglwidget() %>%
playwidget(par3dinterpControl(fn, 0, 3, steps=15),
step = 0.01, loop = TRUE, rate = 0.5)Some things to note: The generated Javascript slider has 300 increments, so that motion appears smooth. However, storing 300 userMatrix values would take up a lot of space, so we use interpolation in the Javascript code. However, the Javascript code can only do linear interpolation, not the more complex spline-based SO(3) interpolation done by par3dinterp. Because of this, we need to output 15 steps from par3dinterpControl so that the distortions of linear interpolation are not visible.
propertyControlpropertyControl is a more general function to set the value of properties of the scene. Currently most properties are supported, but use does require knowledge of the internal implementation.
clipplaneControlclipplaneControl allows the user to control the location of a clipping plane by moving a slider.
vertexControlLess general than propertyControl is vertexControl. This function sets attributes of individual vertices in a scene. For example, to set the x-coordinate of the closest point in the setosa group, and modify its colour from black to white,
setosavals <- subset(iris, Species == "setosa")
which <- which.min(setosavals$Sepal.Width)
init <- setosavals$Sepal.Length[which]
rglwidget() %>%
playwidget(
vertexControl(values = matrix(c(init, 0, 0, 0,
8, 1, 1, 1),
nrow = 2, byrow = TRUE),
attributes = c("x", "red", "green", "blue"),
vertices = which, objid = setosa),
step = 0.01)ageControlA related function is ageControl, though it uses a very different specification of the attributes. It is used when the slider controls the “age” of the scene, and attributes of vertices change with their age.
To illustrate we will show a point moving along a curve. We give two ageControl calls in a list; the first one controls the colour of the trail, the second controls the position of the point:
time <- 0:500
xyz <- cbind(cos(time/20), sin(time/10), time)
lineid <- plot3d(xyz, type="l", col = "black")["data"]
sphereid <- spheres3d(xyz[1, , drop=FALSE], radius = 8, col = "red")
rglwidget() %>%
playwidget(list(
ageControl(births = time, ages = c(0, 0, 50),
colors = c("gray", "red", "gray"), objids = lineid),
ageControl(births = 0, ages = time,
vertices = xyz, objids = sphereid)),
start = 0, stop = max(time) + 20, rate = 50,
components = c("Reverse", "Play", "Slower", "Faster",
"Reset", "Slider", "Label"),
loop = TRUE)rglMouseWhile not exactly a control in the sense of the other functions in this section, the rglMouse function is used to add an HTML control to a display to allow the user to select the mouse mode.
For example, the display below initially allows selection of particular points, but the mouse mode may be changed to let the user rotate the display for a another view of the scene.