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 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's setup using the default map controller configurationor with custom configuration options you provide. This configuration object also configures the initial state of the map's timeline, such as the start and end dates or times and the number of intervals to show while animating along the timeline.

You specify the start and end dates or times for your map's timeline in your configuration by providing a Date instances 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):

{
    start: new Date(Date.now() - 2 * 3600 * 1000),
    end: 0
}

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 startDate and endDate properties on the timeline instance and provide them with the desired Date objects:

// create a map controller using a Mapbox map instance
const controller = new aerisweather.mapsgl.MapboxMapController(map, { account });
 
controller.on('load', () => {
 
    // update the timeline start and end using exact dates    
    controller.timeline.startDate = new Date(2022, 10, 20, 17);
    controller.timeline.endDate = new Date(2022, 10, 23, 17);
 
});

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
const controller = new aerisweather.mapsgl.MapboxMapController(map, { account });
 
controller.on('load', () => {
 
    // 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.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 setStartDateUsingRelativeTime and setEndDateUsingRelativeTime 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'd just need to set the timeline's to option to -1 week:

{
    start: '-1 week',
    end: 'now'
}

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

{
    start: '-1 week',
    end: '1 week'
}

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

{
    start: '-0.5 day',
    end: 'now'
}

You can also update your timeline range once instantiated using the setStartDateUsingRelativeTime and setEndDateUsingRelativeTime methods on your timeline instance. These methods also support providing a relative Date as a second argument from which the relative time string offset will be calculated from:

// create a map controller using a Mapbox map instance
const controller = new aerisweather.mapsgl.MapboxMapController(map, { account });
 
controller.on('load', () => {
 
    // 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.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.

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

{
    duration: 0.75,
    endDelay: 3
}

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

controller.timeline.duration = 2;
controller.timeline.endDelay = 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 the startDate, 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)
const date = new Date(controller.timeline.startDate.getTime() + 30 * 60 * 1000);
controller.timeline.goToDate(date);

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

Weather Data Using Legends