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,
elementId = NULL,
reuse = FALSE,
webGLoptions = list(preserveDrawingBuffer = TRUE),
shared = NULL, minimal = TRUE,
webgl, snapshot,
shinyBrush = NULL,
altText = "3D plot",
...,
oldConvertBBox = 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 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.
An RGL scene produced by the scene3d function.
The width and height of the display in pixels.
Names of playwidget objects
associated with this scene, or objects (typically piped in). See Details below.
Control of mode of display of scene. See Details below.
The id to use on the HTML div
component that will hold the scene.
Ignored. See Details below.
A list of options to pass to WebGL when the drawing context is created. See the Details below.
An object produced by rglShared, or a list of such objects.
Should attributes be skipped if they currently have
no effect? See scene3d.
The name of a Shiny input element
to receive information about mouse selections.
Text to include for screen-readers or browsers that don't handle WebGL. See Details below.
See Details below.
Additional arguments
to pass to htmlwidgets::createWidget.
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.
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:
The ID of the subscene where the mouse is selecting.
Either "changing" or "inactive".
The coordinates of the corners of the selected region in the window,
in order c(x1, y1, x2, y2).
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
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.
hook_webgl for an earlier approach to this problem. rglwidgetOutput for Shiny details.
save <- options(rgl.useNULL=TRUE)
example("plot3d", "rgl")
widget <- rglwidget()
if (interactive() || in_pkgdown_example())
widget
# \donttest{
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)
Run the code above in your browser using DataLab