Package 'animate'

Description

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

Public fields

Methods

Public methods

• animate$new()

• animate$off()

• animate$send()

• animate$set_max_stacksize()

• animate$svg()

• animate$bars()

• animate$objects()

• animate$katex()

• animate$plot()

• animate$points()

• animate$lines()

• animate$arrows()

• 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$screenshot()

• animate$observeAnimateEvent()

• animate$clone()

Method new()

Constructor of the device

Usage

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

Arguments

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

Method set_max_stacksize()

Set the maximum size of the stack

Usage

animate$set_max_stacksize(n)

Arguments

Method svg()

Initialise a SVG element

Usage

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

Arguments

Method bars()

Add bars to a plot

Usage

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

Arguments

Method objects()

Add HTML objects to a plot

Usage

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

Arguments

Examples

# Add a HTML DIV element
device <- animate::animate$new(500, 500)
attach(device)
par(xlim = c(0, 10), ylim = c(0, 10))
# Add a grid to aid positioning
abline(h = 0, v = 0)
abline(h = 0:10, v = 0:10, col = "#22222222")
# Add the DIV element
objects(x=1, y=1, w=2, h=1, id = "obj-1", content = "<div>PlaceHolder</div>")
off()
detach(device)

Method katex()

Add TeX symbols to a plot

Usage

animate$katex(x, y, w, h, tex, ...)

Arguments

Details

See https://katex.org/docs/supported for all the supported TeX functions. Currently, the function loads the JavaScript library and the CSS stylesheet from CDN links, so you must be online to use this function. The reason for this is that KaTeX comes with many fonts. If they are all included in the bundle, then the bundle size becomes too large.

Examples

# Add a KaTeX equation (see KaTeX.js )
device <- animate::animate$new(500, 500)
attach(device)
par(xlim = c(0, 10), ylim = c(0, 10))
# Add a grid to aid positioning
abline(h = 0, v = 0)
abline(h = 0:10, v = 0:10, col = "#22222222")
# Add the KaTeX equation
katex(x=1, y=3, w=3, h=1, id = 'tex-1', tex = 'a^2 + b^2 = c^2')
off()
detach(device)

Method plot()

Generic X-Y plotting

Usage

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

Arguments

Method points()

Add points to a plot

Usage

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

Arguments

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

Method arrows()

Add arrows to a plot

Usage

animate$arrows(x0, y0, x1, y1, length, angle = pi/6, code = 2, ...)

Arguments

Details

Currently, the 'arrows' function is not supported as a primitive; instead, it calls the 'lines' function.

Examples

\donttest{
library(animate)
device <- animate$new(500, 500)
attach(device)
par(xlim = c(0, 10), ylim = c(0, 10))  # Use static axes
plot(1:10, 1:10, id = paste0("point-", 1:10))
lines(c(3, 6), c(6, 3), id = "line-1")
arrows(4, 8, 8, 4, id='arrow-1')
arrows(1, 2, 3, 6, id='arrow-1', transition = TRUE)
off()
detach(device)
}

Method abline()

Add straight lines to a plot

Usage

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

Arguments

Method axis()

Add an axis to a plot

Usage

animate$axis(x, ...)

Arguments

Method text()

Add text to a plot

Usage

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

Arguments

Details

Useful tips: use style = list("text-anchor" = "middle", "dominant-baseline" = "middle") or style = list("text-anchor" = "middle", "dominant-baseline" = "central") to center the text.

Method image()

Add background image to a plot

Usage

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

Arguments

Method event()

Attach an interactive event to an element

Usage

animate$event(selector, event_type, callback)

Arguments

Method chain()

Chain a transition after another.

Usage

animate$chain(callback)

Arguments

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

Details

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

Method set()

Set the active device to a SVG element

Usage

animate$set(device_id)

Arguments

Method par()

Set the graphical parameters

Usage

animate$par(...)

Arguments

Method remove()

Remove elements from the active SVG element

Usage

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

Arguments

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

Method import()

Import an animated plot

Usage

animate$import(setting)

Arguments

Method export()

Export an animated plot

Usage

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

Arguments

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 screenshot()

Take screenshot for GIF generation

Usage

animate$screenshot(action, selector = NULL, options = list())

Arguments

Details

The function uses html2canvas.js to capture the screenshot and gif.js to string them into a GIF file.

Some known limitations: Simultaneously playing (SVG) animation and rendering them to raster image on the fly can be resource heavy; there is no guarantee that the specified frame rate will be met. Also, since html2canvas is used to take the screenshot, its restrictions also apply here. For cases where screenshot is insufficient, use the record function instead. See more detail here.

For "new" action, the options are as given by the GIF.js library:

Available dithering methods are: FloydSteinberg, FalseFloydSteinberg, Stucki, Atkinson. You can add -serpentine to use serpentine scanning, e.g. Stucki-serpentine.

For the "capture" action, the options are:

Examples

\donttest{
# Frame-by-frame animation example
device <- animate::animate$new(500, 500)
attach(device)

# Initialise the generator
screenshot("new", "body", list(width = 1000, height = 1000, quality = 10))

# Plotting the sine curve
x <- seq(1, 40, 0.1)
y <- sin(x * pi / 6)
plot(x, y, type="l", id="line-1")
screenshot("capture")  # capture the frame

# Update the plot with the same id
for (n in 41:200) {
  new_x <- seq(1, n, 0.1)
  new_y <- sin(new_x * pi / 6)
  plot(new_x, new_y, type="l", id="line-1")
  screenshot("capture", options = list(delay = 100))  # capture the frame with options
  Sys.sleep(0.2)  # allow ample time for the screen capture to process
}

# Render and save the GIF file (this can take some time to complete)
screenshot("save")
off()
det


# Key-frame animation example
device <- animate::animate$new(500, 500)
attach(device)

# Initialise the generator
screenshot("new", "body", list(width = 1000, height = 900, quality = 10))

# Plot 10 points at random locations
x <- 1:10
y <- 10 * runif(10)
id <- new_id(y, prefix="points")
plot(x, y, bg="orange", id=id)

# Capture screenshot every 100ms and output to GIF frame with 200ms gap in-between
screenshot("start", options = list(delayCapture = 100, delay = 200))

# Update the plot with default transition animation
new_y <- 10 * runif(10)
points(x, new_y, bg="blue", id=id, transition=TRUE)

# Update the plot with specific transition animation
new_y <- 10 * runif(10)
points(x, new_y, bg="green", cex=(1:10)*30, id=id, transition=list(duration = 2000))

# End the screen capturing and generate the GIF file
screenshot("end")

# Clean up
off()
detach(device)
}

Method observeAnimateEvent()

Event handler

Usage

animate$observeAnimateEvent(input)

Arguments

Method clone()

The objects of this class are cloneable with this method.

Usage

animate$clone(deep = FALSE)

Arguments

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$objects`
## ------------------------------------------------

# Add a HTML DIV element
device <- animate::animate$new(500, 500)
attach(device)
par(xlim = c(0, 10), ylim = c(0, 10))
# Add a grid to aid positioning
abline(h = 0, v = 0)
abline(h = 0:10, v = 0:10, col = "#22222222")
# Add the DIV element
objects(x=1, y=1, w=2, h=1, id = "obj-1", content = "<div>PlaceHolder</div>")
off()
detach(device)

## ------------------------------------------------
## Method `animate$katex`
## ------------------------------------------------

# Add a KaTeX equation (see KaTeX.js )
device <- animate::animate$new(500, 500)
attach(device)
par(xlim = c(0, 10), ylim = c(0, 10))
# Add a grid to aid positioning
abline(h = 0, v = 0)
abline(h = 0:10, v = 0:10, col = "#22222222")
# Add the KaTeX equation
katex(x=1, y=3, w=3, h=1, id = 'tex-1', tex = 'a^2 + b^2 = c^2')
off()
detach(device)

## ------------------------------------------------
## Method `animate$arrows`
## ------------------------------------------------


library(animate)
device <- animate$new(500, 500)
attach(device)
par(xlim = c(0, 10), ylim = c(0, 10))  # Use static axes
plot(1:10, 1:10, id = paste0("point-", 1:10))
lines(c(3, 6), c(6, 3), id = "line-1")
arrows(4, 8, 8, 4, id='arrow-1')
arrows(1, 2, 3, 6, id='arrow-1', transition = TRUE)
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)


## ------------------------------------------------
## Method `animate$screenshot`
## ------------------------------------------------


# Frame-by-frame animation example
device <- animate::animate$new(500, 500)
attach(device)

# Initialise the generator
screenshot("new", "body", list(width = 1000, height = 1000, quality = 10))

# Plotting the sine curve
x <- seq(1, 40, 0.1)
y <- sin(x * pi / 6)
plot(x, y, type="l", id="line-1")
screenshot("capture")  # capture the frame

# Update the plot with the same id
for (n in 41:200) {
  new_x <- seq(1, n, 0.1)
  new_y <- sin(new_x * pi / 6)
  plot(new_x, new_y, type="l", id="line-1")
  screenshot("capture", options = list(delay = 100))  # capture the frame with options
  Sys.sleep(0.2)  # allow ample time for the screen capture to process
}

# Render and save the GIF file (this can take some time to complete)
screenshot("save")
off()
det


# Key-frame animation example
device <- animate::animate$new(500, 500)
attach(device)

# Initialise the generator
screenshot("new", "body", list(width = 1000, height = 900, quality = 10))

# Plot 10 points at random locations
x <- 1:10
y <- 10 * runif(10)
id <- new_id(y, prefix="points")
plot(x, y, bg="orange", id=id)

# Capture screenshot every 100ms and output to GIF frame with 200ms gap in-between
screenshot("start", options = list(delayCapture = 100, delay = 200))

# Update the plot with default transition animation
new_y <- 10 * runif(10)
points(x, new_y, bg="blue", id=id, transition=TRUE)

# Update the plot with specific transition animation
new_y <- 10 * runif(10)
points(x, new_y, bg="green", cex=(1:10)*30, id=id, transition=list(duration = 2000))

# End the screen capturing and generate the GIF file
screenshot("end")

# Clean up
off()
detach(device)

Description

The HTML dependency of an 'animate' plot

Usage

animateDependencies()

Description

Create an animate output (container) element

Usage

animateOutput(
  outputId = "animateOutput",
  width = "100%",
  height = "400px",
  ...
)

Arguments

Note

(Advanced usage) A "stack_limit" parameter can be included in the optional parameters to control how many directives the device should keep track of.

Examples

# Using 'animate' in a 'Shiny' app
library(shiny)

ui <- fluidPage(
  actionButton("buttonPlot", "Plot"),
  actionButton("buttonPoints", "Points"),
  actionButton("buttonLines", "Lines"),
  animateOutput()
)

server <- function(input, output, session) {
  device <- animate$new(600, 400, session = session)
  id <- new_id(1:10)

  observeEvent(input$buttonPlot, {     # Example 1
    device$plot(1:10, 1:10, id = id)
  })

  observeEvent(input$buttonPoints, {   # Example 2
    device$points(1:10, runif(10, 1, 10), id = id, transition = TRUE)
  })

  observeEvent(input$buttonLines, {    # Example 3
    x <- seq(1, 10, 0.1)
    y <- sin(x)
    id <- "line_1"
    device$lines(x, y, id = id)
    for (n in 11:100) {
      x <- seq(1, n, 0.1)
      y <- sin(x)
      device$lines(x, y, id = id)
      Sys.sleep(0.05)
    }
  })
}

# shinyApp(ui = ui, server = server)  # Launch the 'Shiny' app

Description

Playback option for the functions rmd_animate and insert_animate.

Usage

click_to_loop(selector = "#SVG_1", start = 2, wait = 20)

Arguments

Examples

input <- tempfile(fileext = ".Rmd")
output <- tempfile(fileext = ".html")
writeLines('
```{r, echo = FALSE, message = FALSE}
# Run / include the following in a code chunk of an R Markdown document
library(animate)
insert_animate(system.file("tests/Lorenz_system.json.gz", package = "animate"),
               options = click_to_loop())
```
', input)
knitr::knit(input, output)
# browseURL(output)

Description

Playback option for the functions rmd_animate and insert_animate.

Usage

click_to_play(selector = "#SVG_1", start = 2)

Arguments

Examples

input <- tempfile(fileext = ".Rmd")
output <- tempfile(fileext = ".html")
writeLines('
```{r, echo = FALSE, message = FALSE}
# Run / include the following in a code chunk of an R Markdown document
library(animate)
insert_animate(system.file("tests/basic_points.json", package = "animate"),
               options = click_to_play())
```
', input)
knitr::knit(input, output)
# browseURL(output)

Description

Launch the 'FFmpeg'-based video editor ('Shiny' app)

Usage

ffmpeg()

Note

This requires ffmpeg to work. The 'ffmpeg' binary can be downloaded from https://ffmpeg.org/download.html.

Description

Insert an animated plot into an R Markdown document

Usage

insert_animate(file, options = click_to_play(), style, use_cdn = TRUE)

Arguments

Examples

input <- tempfile(fileext = ".Rmd")
output <- tempfile(fileext = ".html")
writeLines('
```{r, echo = FALSE, message = FALSE}
# Run / include the following in a code chunk of an R Markdown document
library(animate)
insert_animate(system.file("tests/Lorenz_system.json.gz", package = "animate"),
               options = click_to_loop())
```
', input)
knitr::knit(input, output)
# browseURL(output)

Description

Playback option for the functions rmd_animate and insert_animate.

Usage

loop(times = 1, wait = 20)

Arguments

Examples

input <- tempfile(fileext = ".Rmd")
output <- tempfile(fileext = ".html")
writeLines('
```{r, echo = FALSE, message = FALSE}
# Run / include the following in a code chunk of an R Markdown document
library(animate)
insert_animate(system.file("tests/Lorenz_system.json.gz", package = "animate"),
               options = loop(times = 2, wait = 15))
```
', input)
knitr::knit(input, output)
# browseURL(output)

Description

A utility function for generating IDs

Usage

new_id(x, prefix = "ID", sep = "-")

Arguments

Examples

new_id(x = runif(10), prefix = "points")

Description

In-line rendering of an animated plot in an R Markdown document

Usage

rmd_animate(device, ...)

Arguments

Note

This function should only be used in a code chunk of an R Markdown document.

Examples

input <- tempfile(fileext = ".Rmd")
output <- tempfile(fileext = ".html")
writeLines('
```{r, echo = FALSE, message = FALSE}
# Run / include the following in a code chunk of an R Markdown document
library(animate)
device <- animate$new(500, 500, virtual = TRUE)  # set `virtual = TRUE` for R Markdown document
attach(device)

# Data
id <- new_id(1:10)
s <- 1:10 * 2 * pi / 10
s2 <- sample(s)

# Plot
par(xlim = c(-2.5, 2.5), ylim = c(-2.5, 2.5))
plot(2*sin(s), 2*cos(s), id = id)
points(sin(s2), cos(s2), id = id, transition = list(duration = 2000))

# Render in-line in an R Markdown document
rmd_animate(device, click_to_play(start = 3))  # begin the plot at the third frame
```
```{r, echo = FALSE, message = FALSE}
par(xlim = NULL, ylim = NULL)  # Reset `xlim` and `ylim` in `par`
# Do some other plots
off()
detach(device)
```
', input)
knitr::knit(input, output)
# browseURL(output)

Description

A thin wrapper of the httpuv package, modified to serve animated plots.

Public fields

Methods

Public methods

• websocket$startServer()

• websocket$stopServer()

• websocket$listServers()

• websocket$stopAllServers()

• websocket$new()

• websocket$clone()

Method startServer()

Start a WebSocket server

Usage

websocket$startServer()

Method stopServer()

Stop a WebSocket server

Usage

websocket$stopServer()

Method listServers()

List all running WebSocket servers

Usage

websocket$listServers()

Method stopAllServers()

Stop all running WebSocket servers

Usage

websocket$stopAllServers()

Method new()

Initialise a WebSocket connection

Usage

websocket$new(in_handler, port = 9454)

Arguments

Returns

A 'websocket' object.

Method clone()

The objects of this class are cloneable with this method.

Usage

websocket$clone(deep = FALSE)

Arguments