R: Add a widget to play animations.

playwidget {rgl} | R Documentation

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

    ## Default S3 method:
    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",
                ...)

    ## S3 method for class 'rglWebGL'
    playwidget(sceneId, controls, elementId = NULL, ...)

    ## S3 method for class 'rglPlayer'
    playwidget(sceneId, controls, ...)

    ## S3 method for class 'shiny.tag.list'
    playwidget(sceneId, controls, elementId = NULL, ...)

### 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.
`...` | The default method passes additional arguments to `htmlwidgets::createWidget`.

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

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

### Author(s)

Duncan Murdoch

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

    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)

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

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

[Package rgl version 0.99.9 Index]