MapsGL Android - Animating Data and Timelines

Animating data across a time series helps tell part of the story when visualizing data. This is especially important for visualizing weather data, where observing short and long-term trends over time contributes to a better understanding of what’s happening and what to expect.

A map controller supports displaying and animating weather data by using a time-based timeline, meaning a timeline with a specific start and end date. This means that you can configure your map to display data for a specific period in time in the past, future or both.

All active data sources visible on the map will be animated as long as those sources support it. Encoded, raster, particle, and vector weather layers (fill, line, circle, heatmap, symbol, and tropical tracks) animate with the timeline. For weather layers, you can refer to the weather layers listing to review which layers currently support animations.

By default a timeline animation will repeat indefinitely with a longer delay at the end of the timeline before restarting from the beginning. Since each data source and map layer may have differing update intervals and periods, each data source will animate independent of each other. Thus, the total number of data intervals may vary between the different data sources within a single animation.

Defining a Time Range

When you instantiate your map controller, it is created with a default timeline. You then set the start and end dates, duration, and related options on controller.timeline.

The default timeline starts twenty-four (24) hours before the current time and ends at the current time:

val controller = MapboxMapController(mapView, xweatherAccount)
controller.timeline.start = Date(System.currentTimeMillis() - (24 * 3600 * 1000))
controller.timeline.end = Date()

The start and end dates or time intervals can either be in the past or future. However, there are some requirements:

• The starting date/time offset must always be earlier than the ending date/time offset.
• The ending date/time offset must always be later than the starting date/time offset.

You can also update the timeline after the map has already been initialized. Just update start and end on the timeline instance and provide them with the desired Date objects:

// create a map controller using a Mapbox map instance
val controller = MapboxMapController(
    mapView,
    xweatherAccount
)
 
val calendarStart = Calendar.getInstance()
calendarStart.set(2025, Calendar.MAY, 11, 10, 30, 0)
val calendarEnd = Calendar.getInstance()
calendarEnd.set(2025, Calendar.MAY, 12, 10, 30, 0)
 
controller.timeline.start = calendarStart.time
controller.timeline.end = calendarEnd.time

Alternatively, you can use the setStartDateUsingOffset and setEndDateUsingOffset methods on a timeline instance to set the time range using time offsets, in milliseconds. You can also provide a second argument to these methods, which should be a Date instance from which you want to calculate the offset from. If you don’t provide a relative date, then the current date and time will be used by default:

// create a map controller using a Mapbox map instance
val controller = MapboxMapController(mapView, xweatherAccount)
 
// set the start time to 24 hours ago
controller.timeline.setStartDateUsingOffset(-24 * 3600 * 1000)
 
// set the end time to 4 hours later than the new start time
controller.timeline.setEndDateUsingOffset(4 * 3600 * 1000, controller.timeline.start)

Using Relative Time Offsets

In addition to providing a timeline’s hour offset ranges as numerical values, you can also provide a relative period string instead. This method supports specifying years, months, weeks, days, hours, minutes and/or seconds for your timeline range.

Relative time strings are calculated relative to the current date and time by default. Pass a Date as the second argument to calculate the offset from a specific instant.

For example, you may want your timeline to start from a week ago and end at the current day and time:

val controller = MapboxMapController(mapView, xweatherAccount)
controller.timeline.setStartDateUsingRelativeTime("-1 week")
controller.timeline.setEndDateUsingRelativeTime("now")

You can also use floats as well, such as starting the timeline half a day ago:

val controller = MapboxMapController(mapView, xweatherAccount)
controller.timeline.setStartDateUsingRelativeTime("-0.5 day")
controller.timeline.setEndDateUsingRelativeTime("now")

You can also update your timeline range once instantiated using the setStartDateUsingRelativeTime and setEndDateUsingRelativeTime methods on your timeline instance:

// create a map controller using a Mapbox map instance
val controller = MapboxMapController(mapView, xweatherAccount)
 
// set the start time to 3 days ago
controller.timeline.setStartDateUsingRelativeTime("-3 days")
 
// set the end time to 12 hours later than the new start time
controller.timeline.setEndDateUsingRelativeTime("12 hours", controller.timeline.start)

Refer to the timeline reference for more information about the supported formats when using relative time string offsets.

Controlling Animation Speed

You can speed up or slow down an animation from the default of two (2) seconds by configuring the duration timeline option. This value should be set to the number of seconds you want it to take to complete a single iteration of an animation loop. Use a higher number to slow down the animation, and use a lower number to speed an animation up.

Additionally, an animation also includes a delay at the end of each iteration before restarting the animation from the beginning using the endDelay configuration option. By default this value is set to one (1) second. Adjust this option on your timeline configuration to increase or decrease the amount of time the last animation frame is held before restarting.

For example, the following timeline configuration would set the animation duration to five (5) seconds and hold the last frame to three (3) seconds:

val controller = MapboxMapController(mapView, xweatherAccount)
controller.timeline.duration = 5.0
controller.timeline.endDelay = 3.0

You can also update these properties any time after your map controller and timeline have been instantiated:

controller.timeline.duration = 2.0
controller.timeline.endDelay = 0.0

Showing a Specific Time

A map’s timeline also supports going to a specific time within its range, allowing you to display data for a specific point in time. You can use the goToOffset method on the map timeline and provide a number corresponding to the time offset from start, in milliseconds:

// move the timeline position to 1 hour after the start time
controller.timeline.goToOffset(3600 * 1000)

Or, you can use goToDate and set the timeline’s playhead position to a specific Date within the start and end date range:

// move the timeline position a specific time within the range (30 minutes after the start)
val date = Date(controller.timeline.start.time + 30 * 60 * 1000)
controller.timeline.goToDate(date)

Implementing a loading icon

You can choose to display a loading icon while data is downloading:

//observe MapboxMapcontrollers "onLoadStart" member:
controller.onLoadStart.observe(this) {
    // set the visibility of a ProgressBar in your layout to true:
    binding.loadingBar.isVisible = true
}
 
//observe MapboxMapcontrollers "onLoadComplete" member:
controller.onLoadComplete.observe(this) {
    // set the visibility to a ProgressBar in your layout to false:
    binding.loadingBar.isVisible = false
}

Refer to the timeline reference for detailed information about the properties and methods supported on Timeline instances.