rglwidget: An htmlwidget to hold an rgl scene.

Description

The htmlwidgets package provides a framework for embedding graphical displays in HTML documents of various types. This function provides the necessities to embed an rgl scene in one.

Usage

rglwidget(x = scene3d(), width = NULL, height = NULL,
          controllers = NULL, snapshot = FALSE,
          elementId = NULL, reuse = !interactive(), ...)

Arguments

An rgl scene produced by the scene3d function.

width, height

The width and height of the display in pixels.

controllers

Names of rglcontroller objects associated with this scene. See Details below.

snapshot

Control of snapshot of scene. See writeWebGL for details.

elementId

The id to use on the HTML div component that will hold the scene.

reuse

A logical variable indicating whether rgl objects from earlier scenes should be referenced. See the Details below.

...

Additional arguments to pass to htmlwidgets::createWidget.

Value

An object of class htmlwidget that will intelligently print itself into HTML in a variety of contexts including the R console, within R Markdown documents, and within Shiny output bindings.
It should also display in the RStudio viewer.
If reuse = TRUE, a record will be kept of objects in the scene and they need not be included in the HTML generated for later scenes. This is normally useful only in knitr documents which can have many rgl scenes; if the widget is displayed in RStudio, only one scene will be shown.

Details

This produces a WebGL version of an rgl scene using the htmlwidgets framework. This allows display of the scene in an rmarkdown document or in a shiny app.

In a shiny app, there will often be one or more rglcontroller objects in the app, taking input from the user. In order to be sure that the initial value of the user control is reflected in the scene, you should list all controllers in the controllers argument. See the sample application in system.file("shinyDemo", package = "rglwidget") for an example.

If the reuse argument is FALSE (the default in interactive use), earlier information will be cleared before drawing the new scene. If TRUE, earlier data will be re-used in the current scene, so it may be smaller and faster to load. In both cases information from the current scene (added to earlier information if reuse=TRUE) will be saved for possible use in a future scene. If reuse=NA, the saved information will neither be used nor updated.

If elementId is NULL and we are not in a Shiny app, elementId is set to a random value to facilitate re-use of information.

Examples

Run this code

save <- getOption("rgl.useNULL")
options(rgl.useNULL=TRUE)
example("plot3d", "rgl")
rglwidget()