rgl (version 0.100.54)

playwidget: Add a widget to play animations.

Description

This is a widget that can be put in a web page to allow animations with or without Shiny.

Usage

playwidget(sceneId, controls,
            start = 0, stop = Inf, interval = 0.05, rate = 1,
            components = c("Reverse", "Play", "Slower", "Faster",
                           "Reset", "Slider", "Label"),
            loop = TRUE,
            step = 1, labels = NULL,
            precision = 3,
            elementId = NULL, respondTo = NULL,
            reinit = NULL,
            buttonLabels = components, pause = "Pause",
            height = 40,
            ...)

Arguments

sceneId

The HTML id of the rgl scene being controlled, or an object. See the Details below.

controls

A single "rglControl" object, e.g. propertyControl, or a list of several.

start, stop

The starting and stopping values of the animation. If labels is supplied stop will default to step through the labels.

interval

The requested interval (in seconds) between updates. Updates may occur at longer intervals.

rate

The number of units of “nominal” time per real world second.

components

Which components should be displayed? See Details below.

loop

When the player reaches the end of the interval, should it loop back to the beginning?

step

Step size in the slider.

labels

Optional labels to use, corresponding to slider steps. Set to NULL for auto-generated labels.

precision

If labels=NULL, the precision to use when displaying timer values.

elementId

The HTML id of the generated widget, containing buttons, slider, etc.

respondTo

The HTML ID of a Shiny input control (e.g. a sliderInput control) to respond to.

reinit

A vector of ids that will need re-initialization before being drawn again.

buttonLabels, pause

These are the labels that will be shown on the buttons if they are displayed. pause will be shown on the "Play" button while playing.

height

The height of the widget in pixels. In a pipe, this is a relative height.

...

Additional arguments to pass to to htmlwidgets::createWidget.

Value

A widget suitable for use in an Rmarkdown-generated web page, or elsewhere.

Appearance

The appearance of the controls is set by the stylesheet in system.file("htmlwidgets/lib/rglClass/rgl.css").

The overall widget is of class rglPlayer, with id set according to elementId.

The buttons are of HTML class rgl-button, the slider is of class rgl-slider, and the label is of class rgl-label. Each element has an id prefixed by the widget id, e.g. elementId-button-Reverse, elementId-slider, etc. (where elementId should be replaced by the actual id).

The reinit parameter handles the case where an object needs re-initialization after each change. For example, plane objects may need this if their intersection with the bounding box changes shape. Note that re-initialization is generally incompatible with the vertexControl as it modifies values which are set during initialization.

Details

The components are buttons to control the animation, a slider for manual control, and a label to show the current value. They will be displayed in the order given in components. Not all need be included.

The buttons have the following behaviour:

Reverse

Reverse the direction.

Play

Play the animation.

Slower

Decrease the playing speed.

Faster

Increase the playing speed.

Reset

Stop the animation and reset to the start value.

If respondTo is used, no components are shown, as it is assumed Shiny (or whatever control is being referenced) will provide the UI components.

The sceneId component can be another playwidget, a rglwidget result, or a result of htmltools::tags or htmltools::tagList. This allows you to use a magrittr-style “pipe” command to join an rglwidget with one or more playwidgets. If a playwidget comes first, sceneId should be set to NA. If the rglwidget does not come first, previous values should be piped into its controllers argument. Other HTML code (including other widgets) can be used in the chain if wrapped in htmltools::tagList.

See Also

subsetControl, propertyControl, ageControl and vertexControl are possible controls to use.

toggleWidget is a wrapper for playwidget and subsetControl to insert a single button to toggle some elements in a display.

Examples

# NOT RUN {
saveopts <- options(rgl.useNULL = TRUE)

objid <- plot3d(1:10, 1:10, rnorm(10), col=c("red", "red"), type = "s")["data"]

control <- ageControl(value=0,
             births=1:10,
             ages = c(-5,0,5),
             colors = c("green", "yellow", "red"),
             objids = objid)

# }
# NOT RUN {
# This example uses explicit names
rglwidget(elementId = "theplot", controllers = "theplayer",
          height = 300, width = 300)
playwidget("theplot", control, start = -5, stop = 5,
           rate = 3, elementId = "theplayer",
           components = c("Play", "Slider"))
# }
# NOT RUN {
# This example uses pipes, and can skip the names

widget <- rglwidget(height = 300, width = 300) %>%
playwidget(control, start = -5, stop = 5,
           rate = 3, components = c("Play", "Slider"))
if (interactive())
  widget

options(saveopts)
# }