rglwidget {rgl}

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(minimal), width = figWidth(), height = figHeight(),
          controllers = NULL,
          elementId = NULL, 
          reuse = FALSE,
          webGLoptions = list(preserveDrawingBuffer = TRUE), 
          shared = NULL, minimal = TRUE, 
          webgl, snapshot, 
          shinyBrush = NULL, 
          altText = "3D plot",
          ...,
          oldConvertBBox = FALSE)

Arguments

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

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

Ignored. See 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.

altText

Text to include for screen-readers or browsers that don't handle WebGL. See Details below.

oldConvertBBox

See Details below.

...

Additional arguments to pass to htmlwidgets::createWidget.

Details

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.

In earlier versions, the reuse argument let one output scene share data from earlier ones. This is no longer supported.

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. For a snapshot, you can use htmltools::save_html(img(src=rglwidget(snapshot=TRUE)), file = ...).

The webGLoptions argument is a list which will be passed when the WebGL context is created. See the WebGL 1.0 specification on https://registry.khronos.org/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 webgl argument controls whether a dynamic plot is displayed in HTML. In LaTeX and some other formats dynamic plots can't be displayed, so if the snapshot argument is TRUE, webgl must be FALSE. (In previous versions of the rgl package, both webgl and snapshot could be TRUE; that hasn't worked for a while and is no longer allowed as of version 0.105.6.)

The snapshot argument controls whether a snapshot is displayed: it must be !webgl if both are specified.

Prior to rgl 0.106.21, rglwidget converted bounding box decorations into separate objects: a box, text for the labels, segments for the ticks. By default it now generates these in Javascript, allowing axis labels to move as they do in the display in R. If you prefer the old conversion, set oldConvertBBox = TRUE.

Value

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 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.

R Markdown specifics

In an R Markdown document, you would normally call setupKnitr(autoprint = TRUE) and would not make explicit calls to rglwidget(). If you do make such calls, the graphics will be inserted into the document.

In knitr versions greater than 1.42.5, the altText argument will be ignored and the alternate text will be set from chunk option fig.alt or fig.cap as with other graphics.

Shiny specifics

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".

Appearance

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.)

Author(s)

Duncan Murdoch

See Also

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

Examples

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

if (interactive() && !in_pkgdown_example()) {
  # Save it to a file.  This requires pandoc
  filename <- tempfile(fileext = ".html")
  htmlwidgets::saveWidget(rglwidget(), filename)
  browseURL(filename)
}


options(save)