rglwidget {rgl} | R Documentation

## 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 = figWidth(), height = figHeight(),
              controllers = NULL, snapshot = FALSE,
              elementId = NULL, reuse = !interactive(),
              webGLoptions = list(preserveDrawingBuffer = TRUE),
              shared = NULL, ...)

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

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

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

[Package rgl version 0.99.16 Index]