User Interaction in WebGL

Introduction

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.

Browser support

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.

Examples

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.

toggleWidget(sceneId = "plot3drgl", ids = plotids["data"], label = "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():

names(plotids)

## [1] "data" "axes" "xlab" "ylab" "zlab"

unclass(plotids)

## data axes xlab ylab zlab 
##    7    8    9   10   11

Using magrittr pipes

It 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,

rglwidget() %>%
toggleWidget(ids = plotids["data"], label = "Data")

Normally the sizing of the rglwidget() matches the chunk’s fig.width and fig.height settings. Sometimes the controls take up too much space, and you’ll want to reduce the size of the display. You can use the figWidth and figHeight in the width and height arguments to rglwidget() to compute alternate heights. For example, the chunk below requests a regular size figure in the chunk header, but shrinks the rglwidget() using the height argument. It also swaps the order of button and scene to illustrate how to put the control ahead of the scene:

toggleWidget(NA, ids = plotids["data"], label = "Data") %>%
rglwidget(controllers = ., height = 0.8*figHeight()) 

Controls

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)

Since we skipped the label argument, the buttons are labelled with the name of the variable passed as ids.

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.

rglwidget() %>%
playwidget(start = 0, stop = 3, interval = 1,
       subsetControl(1, subsets = list(
                 Setosa = setosa,
                 Versicolor = versicolor,
                 Virginica = virginica,
                 All = c(setosa, versicolor, virginica)
                 )))

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)

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)

time <- 0:500
xyz <- cbind(cos(time/20), sin(time/10), time)
lineid <- plot3d(xyz, type="l", col = c("black", "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)

Low level controls

We repeat the initial plot from this document:

plotids <- with(iris, plot3d(Sepal.Length, Sepal.Width, Petal.Length, 
                  type="s", col=as.numeric(Species)))
subid <- currentSubscene3d()
rglwidget(elementId="plot3drgl2")

We might like a button on the web page to cause a change to the display, e.g. a rotation of the plot. First we add buttons, with the “onclick” event set to a function described below:

<button type="button" onclick="rotate(10)">Forward</button>
<button type="button" onclick="rotate(-10)">Backward</button>

We stored the subscene number that is currently active in subid in the code chunk above, and use it as `r subid` in the script below. knitr substitutes the value 1 when it processes the document.

The rotate() function uses the Javascript function document.getElementById to retrieve the <div> component of the web page containing the scene. It will have a component named rglinstance which contains information about the scene that we can modify:

<script type="text/javascript">
var rotate = function(angle) {
  var rgl = document.getElementById("plot3drgl2").rglinstance;
  rgl.getObj(`r subid`).par3d.userMatrix.rotate(angle, 0,1,0);
  rgl.drawScene();
};
</script>

If we had used webGL=TRUE in the chunk header, the knitr WebGL support would create a global object with a name of the form <chunkname>rgl. For example, if the code chunk was named plot3d2, the object would be called plot3d2rgl, and this code would work:

<script type="text/javascript">
var rotate = function(angle) {
  plot3d2rgl.getObj(`r subid`).par3d.userMatrix.rotate(angle, 0,1,0);
  plot3d2rgl.drawScene();
};
</script>

Index

The following functions are described in this document: