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. Some data sources, specifically some shape/polygon-based data sources, don't currently support animating their data. For weather layers, you can refer to the weather layers (opens in a new tab) 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

Once you have instantiated your map controller, you can access the controller's timeline instance to update the startDate and endDate properties on the timeline instance. Use the desired Date objects for your desired time range. For instance, the default timeline configuration specifies a start time two (2) hours before the current time and an end time equal to the current time (offset of 0):

controller.timeline.startDate = Date(timeIntervalSinceNow: -3600 * 2)
controller.timeline.endDate = 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.

Alternatively, you can use the setStartDate(usingOffset:) and setEndDate(usingOffset:) 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:

// set the start time to 24 hours ago
controller.timeline.setStartDate(usingOffset: -3600 * 24)
 
// set the end time to 4 hours later than the new start time
controller.timeline.setEndDate(usingOffset: 3600 * 4, relativeTo: controller.timeline.startDate)

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.

Note that relative time strings for both start and end times are calculated relative to the current date and time when provided as part of your map controller's configuration object. If you prefer to calculate string time offsets relative to a specific date or time, then use setStartDate(usingRelativeTime:) and setEndDate(usingRelativeTime:) after instantiating your map controller instead.

For example, you may want your timeline to start from a week ago and end at the current day and time. You would need to use the setStartDate(usingRelativeTime:) and setEndDate(usingRelativeTime:) methods on your timeline instance:

controller.timeline.setStartDate(usingRelativeTime: "-1 week")
controller.timeline.setEndDate(usingRelativeTime: "now")

Or, you may want your timeline to start from 2 weeks ago and extend to a week from now:

controller.timeline.setStartDate(usingRelativeTime: "-2 weeks")
controller.timeline.setEndDate(usingRelativeTime: "1 week")

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

controller.timeline.setStartDate(usingRelativeTime: "-0.5 day")
controller.timeline.setEndDate(usingRelativeTime: "now")

These methods also support providing a relative Date as a second argument from which the relative time string offset will be calculated from:

// set the start time to 3 days ago
controller.timeline.setStartDate(usingRelativeTime: "-3 days")  
 
// set the end time to 12 hours later than the new start time
controller.timeline.setEndDate(usingRelativeTime: "12 hours", relativeTo: controller.timeline.startDate);

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.

You can update these properties any time after your map controller and timeline have been instantiated. For example, the following timeline configuration would set the animation duration to five (5) seconds and hold the last frame to three (3) seconds:

controller.timeline.duration = 0.75;
controller.timeline.endDelay = 3;

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 goTo(offset:) method on the map timeline and provide a number corresponding to the time offset from the startDate, in milliseconds:

// move the timeline position to 1 hour after the start time
controller.timeline.goTo(offset: (3600 * 1000);

Or, you can use goTo(date:) 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)
let date = mapController.timeline.startDate.addingTimeInterval(1800)
controller.timeline.goTo(date: date);

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

Weather Data Map Controller