animate {animate}

A web-based graphics device for animated visualisations

Description

Extends the 'base' graphics functions to support frame-by-frame animation and keyframes animation.

Public fields

connection

A handle for the WebSocket connection.

ready_state

The ready state of the connection.

shiny

TRUE or FALSE; whether the device is used with in a 'Shiny' app.

session

A 'Shiny' session.

virtual_meta

A list of device metadata.

virtual_session

A virtual session simulated with 'V8'.

event_handlers

A named list of user-defined functions for handling events.

Methods

Public methods

• animate$new()

• animate$off()

• animate$send()

• animate$set_max_stacksize()

• animate$svg()

• animate$bars()

• animate$objects()

• animate$plot()

• animate$points()

• animate$lines()

• animate$abline()

• animate$axis()

• animate$text()

• animate$image()

• animate$event()

• animate$chain()

• animate$simple_event()

• animate$set()

• animate$par()

• animate$remove()

• animate$clear()

• animate$delete()

• animate$import()

• animate$export()

• animate$record()

• animate$observeAnimateEvent()

• animate$clone()

Method new()

Constructor of the device

Usage

animate$new(width, height, id = "SVG_1", launch.browser, ...)

Arguments

width

An integer; the width in pixels.

height

An integer; the height in pixels.

id

A character string; the id assigned to the device.

launch.browser

A function to launch a viewer; two options are rstudioapi::viewer and utils::browseURL. It defaults to the first option if the user is using RStudio and to the second option otherwise. The default applies to interactive session only.

...

Additional arguments. Use virtual = TRUE to use the virtual device, shiny = TRUE for shiny application; everything else will be passed to the SVG element that hosts the visualisation.

Examples

\donttest{
library(animate)
device <- animate$new(400, 400)  # Launch a WebSocket server
attach(device)
x <- 1:10
y <- 1:10
id <- new_id(x)   # Give each point an ID: c("ID-1", "ID-2", ..., "ID-10")
plot(x, y, id = id)

new_y <- 10:1
plot(x, new_y, id = id, transition = TRUE)  # Use transition
off()
detach(device)
}

Method off()

Switch off the device; this function closes the WebSocket connection.

Usage

animate$off()

Method send()

Send commands to device

Usage

animate$send(message)

Arguments

message

The message to send to the device.

Method set_max_stacksize()

Set the maximum size of the stack

Usage

animate$set_max_stacksize(n)

Arguments

n

The number of commands the plot stack can hold. Use -1 for unlimited number of commands.

Method svg()

Initialise a SVG element

Usage

animate$svg(width = 800, height = 600, ...)

Arguments

width

Width of the canvas in pixels.

height

Height of the canvas in pixels.

...

Additional parameters. Some commonly used parameters are id and root. id assigns an id to the SVG element for future reference; root specifies the DOM element to insert the SVG element into.

Method bars()

Add bars to a plot

Usage

animate$bars(x, y, w, h, ...)

Arguments

x

The x coordinates of the bars.

y

The y coordinates of the bars.

w

The width of the bars.

h

The height of the bars.

...

Additional graphical parameters.

Method objects()

Add HTML objects to a plot

Usage

animate$objects(x, y, w, h, content, ...)

Arguments

x

The x coordinates of the objects.

y

The y coordinates of the objects.

w

The width of the objects.

h

The height of the objects.

content

The content of the objects; the HTML string.

...

Additional graphical parameters.

Method plot()

Generic X-Y plotting

Usage

animate$plot(x, y, type = "p", ...)

Arguments

x

The x coordinates of the data.

y

The y coordinates of the data.

type

Type of the plot; one of 'p' and 'l'.

...

Additional graphical parameters.

Method points()

Add points to a plot

Usage

animate$points(x, y, ...)

Arguments

x

The x coordinates of the points.

y

The y coordinates of the points.

...

Additional graphical parameters.

Details

Options for the "pch" parameter: "circle", "plus", "diamond", "square", "star", "triangle", "wye", "triangle_down", "triangle_left", "triangle_right", "diamond_alt", "diamond_square", "pentagon", "hexagon", "hexagon_alt", "octagon", "octagon_alt", "cross".

The unit of the "cex" parameter is squared pixels, corresponding to how much pixel space the symbol would cover. The convention comes from the 'D3' library, and the choice is (believed) to make plots visually consistent across the different symbols.

Method lines()

Add line segments / paths to a plot

Usage

animate$lines(x, y, ...)

Arguments

x

The x coordinates of the line.

y

The y coordinates of the line.

...

Additional graphical parameters.

Method abline()

Add straight lines to a plot

Usage

animate$abline(a, b, h, v, ...)

Arguments

a

The intercept.

b

The slope.

h

The y-value(s) for horizontal line(s).

v

The x-value(s) for vertical line(s).

...

Additional graphical parameters.

Method axis()

Add an axis to a plot

Usage

animate$axis(x, ...)

Arguments

x

The x coordinates of the text.

...

Additional graphical parameters.

y

The y coordinates of the text.

labels

The text.

Method text()

Add text to a plot

Usage

animate$text(x, y, labels, ...)

Arguments

x

The x coordinates of the text.

y

The y coordinates of the text.

labels

The text.

...

Additional graphical parameters.

Method image()

Add background image to a plot

Usage

animate$image(href, width, height, ...)

Arguments

href

The link to the image.

width

The width of the image.

height

Th height of the image.

...

Additional graphical parameters.

Method event()

Attach an interactive event to an element

Usage

animate$event(selector, event_type, callback)

Arguments

selector

A character string; a CSS selector.

event_type

A character string; the event type. For example, "click", "mouseover", "mouseout". See more options at https://www.w3schools.com/jsref/dom_obj_event.asp.

callback

A function, to be called when the event is triggered. The function should take an argument to receive the data from the browser end.

Method chain()

Chain a transition after another.

Usage

animate$chain(callback)

Arguments

callback

A function, to be called when the event is triggered. The function should take an argument to receive the data from the browser end.

Examples

\donttest{
library(animate)
device <- animate$new(600, 600)  # Launch a WebSocket server
attach(device)
par(xlim = c(0, 10), ylim = c(0, 10))
plot(1:10, 1:10, id = 1:10)
points(1:10, sample(10, 10), id = 1:10,
  transition = list(
    duration = 1000,
    on = chain(function(message) {
      print(message)
      points(1:10, sample(10, 10), id = 1:10, bg = "green",
             transition = list(duration = 2000))
      })
  ))
par(xlim = NULL, ylim = NULL)  # Reset `xlim` and `ylim` in `par`
off()
detach(device)
}

Method simple_event()

Attach a captured event to an element

Usage

animate$simple_event(selector, event_type, method, param)

Arguments

selector

A character string; a CSS selector.

event_type

A character string; the event type. For example, "click", "mouseover", "mouseout". See more options at https://www.w3schools.com/jsref/dom_obj_event.asp.

method

A character string; the name of a device function (e.g. "points").

param

A named list of arguments to be called with.

Method set()

Set the active device to a SVG element

Usage

animate$set(device_id)

Arguments

device_id

A character vector; ID of the device.

Method par()

Set the graphical parameters

Usage

animate$par(...)

Arguments

...

The graphical parameters

Method remove()

Remove elements from the active SVG element

Usage

animate$remove(id = NULL, selector = "*")

Arguments

id

A character vector; the ID of the elements.

selector

A character vector; a CSS selector.

Method clear()

Remove all elements from the active SVG element

Usage

animate$clear()

Method delete()

Remove a SVG element

Usage

animate$delete(id = NULL)

Arguments

id

A character string; the ID of the SVG. If not provided, remove the active SVG element. #' @description #' Perform a group of graphical operations to a plot #' @param ... Any number of graphical operations. group = function(...) self$send(Message("fn_group", c(...))) ,

Method import()

Import an animated plot

Usage

animate$import(setting)

Arguments

setting

A JSON file exported from previous runs.

Method export()

Export an animated plot

Usage

animate$export(path = "./animate.json", handler = "browser")

Arguments

path

A character string; the file path to export to.

handler

'r' or 'browser'; the program to handle the export operation.

Method record()

Record an animated plot as a MP4 video

Usage

animate$record()

Details

This function will prompt you to select a screen / window / tab to record. Once started, the recording can be stopped by using the stop button at the notification box, or clicking anywhere on the page near the device. Always confirm that the screen recording notification box is gone. The captured video will be downloaded right after the recording stops.

This uses web browsers' Media Streams API to record the screen and return the captured frames as a video. The entire process runs locally. The source file that provides this functionality can be found at system.file("addons/screen_record.js", package = "animate").

This function is disabled for 'Shiny' app and R Markdown document.

This function does not work in the RStudio viewer. Please use the "show in new window" button to launch the page with a web browser.

See browser compatibility at: https://developer.mozilla.org/en-US/docs/Web/API/MediaStream_Recording_API#browser_compatibility

See Media Streams API reference at: https://developer.mozilla.org/en-US/docs/Web/API/Media_Streams_API

Method observeAnimateEvent()

Event handler

Usage

animate$observeAnimateEvent(input)

Arguments

input

The input object in the server function of a 'Shiny' app.

Method clone()

The objects of this class are cloneable with this method.

Usage

animate$clone(deep = FALSE)

Arguments

deep

Whether to make a deep clone.

Note

This function differs from the event function in that events registered through simple_event do not require R at deployment to work.

Examples

## ------------------------------------------------
## Method `animate$new`
## ------------------------------------------------


library(animate)
device <- animate$new(400, 400)  # Launch a WebSocket server
attach(device)
x <- 1:10
y <- 1:10
id <- new_id(x)   # Give each point an ID: c("ID-1", "ID-2", ..., "ID-10")
plot(x, y, id = id)

new_y <- 10:1
plot(x, new_y, id = id, transition = TRUE)  # Use transition
off()
detach(device)


## ------------------------------------------------
## Method `animate$chain`
## ------------------------------------------------


library(animate)
device <- animate$new(600, 600)  # Launch a WebSocket server
attach(device)
par(xlim = c(0, 10), ylim = c(0, 10))
plot(1:10, 1:10, id = 1:10)
points(1:10, sample(10, 10), id = 1:10,
  transition = list(
    duration = 1000,
    on = chain(function(message) {
      print(message)
      points(1:10, sample(10, 10), id = 1:10, bg = "green",
             transition = list(duration = 2000))
      })
  ))
par(xlim = NULL, ylim = NULL)  # Reset `xlim` and `ylim` in `par`
off()
detach(device)