Animations

toro provides the ability to animate certain aspects of the map, allowing you to visualise data in both space and time.

Setup

For the following examples we’ll use a line representing a route around Aotearoa, which could represent the path of a vessel taking samples around the country. We’ll animate a point along this route to visualise the path of the vessel over time.

library(sf)
#> Linking to GEOS 3.14.1, GDAL 3.12.1, PROJ 9.7.1; sf_use_s2() is TRUE
library(toro)

nz_line <- sf::st_sf(
  id = 1,
  geometry = sf::st_sfc(
    sf::st_linestring(
      cbind(
        c(
          172.2041,
          182.2494,
          168.1286,
          163.9383,
          171.7449
        ),
        c(
          -32.56960,
          -38.85522,
          -48.49620,
          -46.43999,
          -34.62533
        )
      )
    ),
    crs = 4326
  )
)

Basic example

For the most basic example, add a route (line) and then use add_animation_controls() to add controls to the map for animating along the route.

map() |>
  add_route(route_id = "nz_route", points = nz_line) |>
  add_animation_controls(route_id = "nz_route")

Advanced examples

Speed control

You can add a customisable speed control. By default, there are 3 speed options: 0.5x, 1x, and 2x. You can change the speed options by passing custom values and labels to the add_animation_controls() function.

map() |>
  add_route(route_id = "nz_route", points = nz_line) |>
  add_animation_controls(
    route_id = "nz_route",
    include_speed_control = TRUE,
    speed_values = c(0.3, 0.5, 1, 2, 4),
    speed_labels = c("Slower", "Slow", "Default", "Fast", "Faster")
  )

Animating icon

You can also supply an icon to be animated along the route. By default, toro has a built in image with the ID “toro-pin” that you can use for this purpose, or you can add your own custom image. To use a custom image, use add_image() to add the image and then pass the settings.animatingIcon parameter to add_route() to specify the icon you want to animate along the route.

map() |>
  add_route(
    route_id = "nz_route",
    points = nz_line,
    settings = list(
      animatingIcon = get_layout_options(
        "symbol",
        list(icon_image = "toro-pin", icon_size = 0.5)
      )
    )
  ) |>
  add_animation_controls(route_id = "nz_route")

Other customisations

You can set dropVisited to TRUE in the animation settings to leave a marker on the map at each point that has been visited during the animation.

You can also change the styles of the different parts of the route using the animatedRouteStyle, unanimatedRouteStyle, and visitedRouteStyle settings.

map() |>
  add_route(
    route_id = "nz_route",
    points = nz_line,
    settings = list(
      dropVisited = TRUE,
      routeLine = list(
        "line-color" = "#11a366",
        "line-width" = 2,
        "line-dasharray" = c(2, 4)
      ),
      visitedPoints = list(
        "circle-color" = "#20de60",
        "circle-radius" = 4
      ),
      animatingPoint = list(
        "circle-color" = "#dbe811",
        "circle-radius" = 8
      )
    )
  ) |>
  add_animation_controls(route_id = "nz_route")

Timeline controls

Animated routes can be shown from a timeline perspective, where the animation is controlled by a timeline slider. This is useful for visualising data that has a temporal component, such as the movement of a vessel over time. A dataframe with multiple points and a date column is required for this type of animation. Each point is plotted in the route and the animation is controlled by the timeline slider, which allows the user to select a date range to view the points that fall within that range. The timeline slider can be added to the map using the add_timeline_control() function.

# A trip across a few New Zealand cities, one point per date.
# The `date` column is what the timeline reads for its start/end range.
trip <- sf::st_sf(
  city = c("Auckland", "Taupo", "Wellington", "Christchurch", "Queenstown"),
  date = as.Date(c(
    "2024-01-01",
    "2024-01-08",
    "2024-01-15",
    "2024-01-22",
    "2024-01-29"
  )),
  geometry = sf::st_sfc(
    sf::st_point(c(174.7633, -36.8485)), # Auckland
    sf::st_point(c(176.0702, -38.6857)), # Taupo
    sf::st_point(c(174.7762, -41.2865)), # Wellington
    sf::st_point(c(172.6362, -43.5321)), # Christchurch
    sf::st_point(c(168.6626, -45.0312)), # Queenstown
    crs = 4326
  )
)

map() |>
  add_route(
    route_id = "nz_trip",
    points = trip,
    # This flag is what actually turns the timeline on:
    settings = list(showTimelineControls = TRUE)
  ) |>
  add_timeline_control(
    position = "bottom-left",
    start_date = min(trip$date),
    end_date = max(trip$date)
  )