animate {animate} | R Documentation |
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
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
andutils::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
androot
.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)