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 = !interactive(),
webGLoptions = list(preserveDrawingBuffer = TRUE),
shared = NULL, minimal = TRUE,
webgl, snapshot,
shinyBrush = NULL, ...)
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.
A logical variable indicating whether rgl objects from earlier scenes should be referenced. See the 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.
Additional arguments
to pass to htmlwidgets::createWidget
.
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:
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.)
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.
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://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 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 rgl, 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.
hook_webgl
for an earlier approach to this problem. rglwidgetOutput
for Shiny details.
# NOT RUN {
save <- getOption("rgl.useNULL")
options(rgl.useNULL=TRUE)
example("plot3d", "rgl")
widget <- rglwidget()
if (interactive())
widget
# }
# NOT RUN {
# Save it to a file. This requires pandoc
filename <- tempfile(fileext = ".html")
htmlwidgets::saveWidget(rglwidget(), filename)
browseURL(filename)
# }
Run the code above in your browser using DataLab