rglwidget: An htmlwidget to hold an RGL scene

In rgl: 3D Visualization Using OpenGL

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,
          fastTransparency = getOption("rgl.fastTransparency", TRUE))

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, fastTransparency	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/ 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.

In version 1.3.4, the handling of transparent objects was changed to match the rgl device more closely. The new method of rendering is quite a bit faster, though sometimes less accurate. To get the older drawing method set fastTransparency = FALSE.

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)

rgl documentation built on Oct. 28, 2024, 5:07 p.m.