rglwidget: An htmlwidget to hold an rgl scene.
In rgl: 3D Visualization Using OpenGL

Description Usage Arguments Details Value Shiny specifics Appearance Author(s) See Also Examples

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.

rglwidget(x = scene3d(minimal), width = figWidth(), height = figHeight(),
          controllers = NULL, snapshot = !webgl,
          elementId = NULL, reuse = !interactive(),
          webGLoptions = list(preserveDrawingBuffer = TRUE), 
          shared = NULL, minimal = TRUE, 
          webgl = !latex, latex, 
          shinyBrush = NULL, ...)

`x`	An rgl scene produced by the `scene3d` function.
`width, height`	The width and height of the display in pixels.
`controllers`	Names of `playwidget` objects associated with this scene, or objects (typically piped in). See Details below.
`snapshot,webgl,latex`	Control of mode of display of scene. See Details below.
`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.
`webGLoptions`	A list of options to pass to WebGL when the drawing context is created. See the Details below.
`shared`	An object produced by `rglShared`, or a list of such objects.
`minimal`	Should attributes be skipped if they currently have no effect? See `scene3d`.
`shinyBrush`	The name of a Shiny `input` element to receive information about mouse selections.
`...`	Additional arguments to pass to `htmlwidgets::createWidget`.

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

options(rgl.printRglwidget = TRUE) will cause rglwidget() to be called and displayed when the result of an rgl call that changes the scene is printed.

In RMarkdown or in standalone code, you can use a magrittr-style “pipe” command to join an rglwidget with a playwidget or toggleWidget. If the control widget comes first, it should be piped into the controllers argument. If the rglwidget comes first, it can be piped into the first argument of playwidget or toggleWidget.

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.

To save the display to a file, use htmlwidgets::saveWidget. This requires pandoc to be installed.

The webGLoptions argument is a list which will be passed when the WebGL context is created. See the WebGL 1.0 specification on https://www.khronos.org/registry/webgl/specs/ for possible settings. The default in rglwidget differs from the WebGL default by setting preserveDrawingBuffer = TRUE in order to allow other tools to read the image, but please note that some implementations of WebGL contain bugs with this setting. We have attempted to work around them, but may change our default in the future if this proves unsatisfactory.

The default for the latex argument is TRUE if we detect that we are producing LaTeX/PDF output in knitr, FALSE otherwise.

The webgl argument controls whether a dynamic plot is displayed in HTML. In LaTeX dynamic plots can't be displayed, so if the latex argument is TRUE, webgl defaults to FALSE.

The snapshot argument controls whether a snapshot is displayed: it can be a logical value or a character value. If logical and FALSE, no snapshot will be included. If TRUE, a snapshot will be taken of the scene x using snapshot3d. If snapshot is a character string starting "data:", it will be assumed to be the result of the image_uri function. Otherwise it will be assumed to be a filename, and image_uri will be used to embed it in the output page.

For HTML output, if both webgl = TRUE and a snapshot are specified, both will be included in the output, and the snapshot will be shown when WebGL is unavailable. If webgl = FALSE, only the snapshot will be included. It's an error to have both webgl = FALSE and snapshot = FALSE.

An object of class "htmlwidget" (or "shiny.tag.list" if pipes are used) 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.

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 rmarkdown documents which can have many rgl scenes; if the widget is displayed in RStudio, only one scene will be shown.

If objects are passed in the shared argument, then the widget will respond to selection and filtering applied to those as shared datasets. See rglShared for more details and an example.

This widget is designed to work with Shiny for interactive displays linked to a server running R.

In a Shiny app, there will often be one or more playwidget 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 players in the controllers argument. See the sample application in system.file("shinyDemo", package = "rglwidget") for an example.

In Shiny, it is possible to find out information about mouse selections by specifying the name of an input item in the shinyBrush argument. For example, with shinyBrush = "brush3d", each change to the mouse selection will send data to input$brush3d in an object of class "rglMouseSelection" with the following components:

subscene: The ID of the subscene where the mouse is selecting.
state: Either "changing" or "inactive".
region: The coordinates of the corners of the selected region in the window, in order c(x1, y1, x2, y2).
model, proj, view: The model matrix, projection matrix and viewport in effect at that location.

This object can be used as the first argument to selectionFunction3d to produce a test function for whether a particular location is in the selected region. If the brush becomes inactive, an object containing only the state field will be sent, with value "inactive".

The appearance of the display is set by the stylesheet in system.file("htmlwidgets/lib/rglClass/rgl.css").

The widget is of class rglWebGL, with id set according to elementId. (As of this writing, no special settings are given for class rglWebGL, but you can add your own.)

Duncan Murdoch

hook_webgl for an earlier approach to this problem. rglwidgetOutput for Shiny details.

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

# Save it to a file.  This requires pandoc
filename <- tempfile(fileext = ".html")
htmlwidgets::saveWidget(rglwidget(), filename)
browseURL(filename)