Map Timeline and Animations

Weather maps support 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 weather 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. However, nearly all raster/image and point data sources are animatable.

By default a weather map animation will repeat indefinitely with a longer delay at the end of the timeline before restarting from the beginning. An animation’s speed is controlled by both the maximum number of intervals allowed, specifically for raster/image data sources, and the timeline’s date range. Since each data source and map layer has differing update intervals and periods, each data source will animate independent of each other. Thus, the total number of intervals may vary between the different data sources within a single animation.

Note that by default a map will only display past/current data for past/current timeline intervals and future data for future timeline intervals. However, you can change this behavior. See the Always Show Past and/or Future Data section below for more information.

The following timeline and animation topics are covered below:

Defining a Time Range

When you instantiate your weather map, it’s setup using the default weather map configuration or 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 using time offsets relative to the current date and time when the map is initialized, in seconds. 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):

timeline: {
    from: -2 * 3600,
    to: 0
}

Note that these offset values must be provided in seconds.

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. Use the setStartOffset() and setEndOffset() methods, providing the offsets in seconds relative to now:

aeris.views().then(views => {
    const map = new views.InteractiveMap('#map', {
        timeline: {
            from: -2 * 3600,
            to: 0
        }
    });
    map.on('ready', () => {

        // update the timeline to start 6 hours ago
        map.timeline.setStartOffset(-6 * 3600);

        // update the timeline to end 2 hours from now
        map.timeline.setEndOffset(2 * 3600);

    });
});

Alternatively, instead of offset time values you can also set the timeline range using dates using setStartDate() and setEndDate(), whose values can be Date objects or a number corresponding to the Epoch time in milliseconds:

aeris.views().then(views => {
    const map = new views.InteractiveMap('#map', {
        timeline: {
            from: -2 * 3600,
            to: 0
        }
    });
    map.on('ready', () => {

        // update the timeline start and end using dates
        const start = new Date(2018, 10, 20, 17);
        const end = new Date(2018, 10, 23, 17);
        
        map.timeline.setStartDate(start);
        map.timeline.setEndDate(end);

    });
});

Updating the start and/or end dates on your map’s timeline will stop any active animation and update the data sources currently active on the weather map as needed to account for the time range change.

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 supports specifying years, months, weeks, days, hours, minutes and/or seconds for your timeline range.

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:

aeris.views().then(views => {
    const map = new views.InteractiveMap('#map', {
        timeline: {
            from: '-1 week',
            to: 0
        }
    });
});

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

aeris.views().then(views => {
    const map = new views.InteractiveMap('#map', {
        timeline: {
            from: '-2 weeks',
            to: '1 week'
        }
    });
});

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

aeris.views().then(views => {
    const map = new views.InteractiveMap('#map', {
        timeline: {
            from: '-0.5 day',
            to: 0
        }
    });
});

The following time period formats are supported:

Time Period Supported Formats Examples
year year, yr, y 0.25 year, 0.25yr, 0.25y
month month, mn 1 month, 1mn
week week, wk, w 2 weeks, 2wk, 2w
day day, d 4 days, 4d
hour hour, hr, h 12 hours, 12hr, 12h
minute minute, min, m 30 minutes, 30min, 30m
second second, sec, s 120 seconds, 120sec, 120s

Controlling the 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:

aeris.views().then(views => {
    const map = new views.InteractiveMap('#map', {
        timeline: {
            duration: 5,
            endDelay: 3
        }
    });
});

Configuring Animation Data Loading Behavior

Most of the time, additional data will need to be loaded in order for animations to begin playback, such as data for the timeline’s full date range or raster/vector data for specific intervals across the date range. Some layers, specifically raster/tile layers, require a large amount of data and imagery for the entire animation and can take a longer amount of time to load, especially on slower network connections. The following configuration options are available to help you tune your weather map timeline to fit your desired result when it comes to animation data loading and playback.

Starting with version 1.3.2 of the SDK, you can now control how you prefer to handle the loading of animation data on your interactive map instances. A comparison of the supported loading options along with their pros and cons are outlined below.

Immediately Begin Playback While Loading Concurrently

Using this timeline configuration will immediately start playing the map animation and allow data to load during playback. All animation intervals will appear whether they’ve fully loaded or not and the value for showLoadingIntervals will be ignored.

Pros Cons
Eliminates any delay before playback begins which can make animation data loading appear to be faster, especially on fast network connections. Often results in empty raster data frames during the initial animation playback until data is loaded, especially on slower network connections and larger map sizes. Animating more layers will result in a longer duration in which empty or partial frames will appear during the animation.
// immediately begin animation playback
// loading intervals will be included during playback, which can result in empty frames 
// until those intervals have partially or fully loaded
aeris.views().then(views => {
    const map = new views.InteractiveMap('#map', {
        timeline: {
            bufferIntervals: 0
        }
    });
});

Only Load a Number of Intervals Before Playback

With this configuration, the animation will wait for a certain number of animation intervals to fully load before beginning playback. Then, the remaining intervals will load concurrently while the animation is actively playing. All intervals will still appear during playback including intervals that have not fully loaded.

Pros Cons
Loads a desired number of frames before playing which can reduce the amount of empty frames during playback you often see when immediately starting the animation. Increases the wait time before animation playback can begin, which may result in a perceptually slower data loading process.
// load the first 3 animation intervals before playing 
// loading intervals will be included during playback, which can result in empty frames 
// until those intervals have partially or fully loaded
aeris.views().then(views => {
    const map = new views.InteractiveMap('#map', {
        timeline: {
            bufferIntervals: 3,
            showLoadingIntervals: true
        }
    });
});

Only Show Loaded Intervals During Playback

Similar to the configuration option above, this configuration will begin playback after a certain number of intervals have fully loaded. However, only fully loaded intervals will be shown during animation playback instead of showing partial or loading intervals. Intervals will only be included in the animation once they have fully loaded during playback.

Pros Cons
Reduces the wait time before playback begins (depending on the value for bufferIntervals. Also eliminates empty frames in the animation since only fully-loaded intervals are included. Increases the wait time before animation playback can begin, which may result in a perceptually slower data loading process. Loaded intervals will also appear relative to times along the timeline the data may not necessarily represent.
// load the first 3 animation intervals before playing 
// loading intervals will only be included during playback once they've fully loaded
aeris.views().then(views => {
    const map = new views.InteractiveMap('#map', {
        timeline: {
            bufferIntervals: 3,
            showLoadingIntervals: false
        }
    });
});

Load All Intervals Before Playback

This timeline configuration will wait for all animation intervals to fully load before beginning playback.

Pros Cons
Eliminates all empty frames that may occur when configuring an animation to load during playback. All data intervals are always included during playback. Results in the longest wait time before an animation can begin playback since all intervals must be fully loaded.

The following configuration will show each interval once it’s fully loaded during the loading progress, which was the default behavior in SDK versions prior to 1.3.2:

// wait for all intervals to fully load before playing
aeris.views().then(views => {
    const map = new views.InteractiveMap('#map', {
        timeline: {
            bufferIntervals: -1
        }
    });
});

Alternatively, you can hide the loading progress and only show animation frames once all intervals have loaded by disabling showLoading in your configuration:

// wait for all intervals to fully load before playing
aeris.views().then(views => {
    const map = new views.InteractiveMap('#map', {
        timeline: {
            bufferIntervals: -1,
            showLoading: false
        }
    });
});

Showing a Specific Time

A weather map’s timeline also supports going to a specific time within its range, allowing you to display weather data for a particular point in time. Just use the goToTime() method on the map’s timeline instance and provide the Date or a number corresponding to the Epoch time in milliseconds:

aeris.views().then(views => {
    const map = new views.InteractiveMap('#map', {
        timeline: {
            from: -2 * 3600,
            to: 0
        }
    });
    map.on('ready', () => {

        // get the current time offset for the start position
        const from = map.timeline.from;

        // move the timeline position to 1 hour after the beginning, or 1 hour ago
        map.timeline.goToTime(from + 3600);

    });
});

Start Animating When the Map is Ready

You may want to start playing the map’s animation immediately when the map has been loaded and setup. To do so, just tell the animation to play within an event handler for the map’s ready event:

aeris.views().then(views => {
    const map = new views.InteractiveMap('#map', {
        timeline: {
            from: -2 * 3600,
            to: 0
        }
    });
    map.on('ready', () => {

        // start animating immediately when the map is ready
        map.timeline.play();

    });
});

Always Show Past and/or Future Data

By default, an interactive map will only show past/current data (radar, satellite, alerts, observations, etc) for current timeline intervals and those in the past. As such, a map will only show future data (such as forecasts, outlooks, etc) for future timeline intervals.

You may, however, want to always show past data for future intervals and/or future intervals for past data. This is often useful if you want to display an animation consisting of future data, such as future radar or forecast temperatures, that constains time intervals in the past relative to now.

To accomplish this, you just need to set the necessary alwaysShowPast and/or alwaysShowFuture properties on your map’s timeline configuration object. For instance, the following will always render future layers for timeline intervals in the past:

aeris.views().then(views => {
    const map = new views.InteractiveMap('#map', {
        timeline: {
            from: -12 * 3600,
            to: 6 * 3600,
            alwaysShowFuture: true
        }
    });
});

Note that most layers which represent observations or past data, such as current temperatures or road conditions, aren’t available for future time intervals and will result in invalid requests. Therefore, you’ll most likely only use the alwaysShowFuture option.

Last modified: September 03, 2020