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.

The following timeline and animation topics are covered below:

• Defining a Time Range
• Controlling the Animation Speed
• Configuring Animation Data Loading Behavior
• Showing a Specific Time
• Start Animating When the Map is Ready
• Always Show Past and/or Future Data

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
}

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 (opens in a new tab) 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:

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.

// 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.

// 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.

// 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.

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.