Map View Timeline

Map views 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 map view to display data for a specific period in time in the past, future or both. All active data layers visible on the map will be animated.

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 and the timeline's date range. Since each map layer has differing update intervals and periods, each layer will appear to animate independent of each other. Thus, the total number of changes during an animation may vary between the different layers within a single animation.

Defining a Time Range

When you instantiate your map view, 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):

animation: {
    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:

const map = new views.Map('#mapview', {
    animation: {
        from: -2 * 3600,
        to: 0
    }
});
 
// 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:

const map = new views.Map('#mapview', {
    animation: {
        from: -2 * 3600,
        to: 0
    }
});
 
// 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 layers currently active on the weather map as needed to account for the time range change.

Showing a Specific Time

A 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:

const map = new views.Map('#mapview', {
    animation: {
        from: -2 * 3600,
        to: 0
    }
});
 
// 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);

Always Showing 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:

const map = new views.Map('#mapview', {
    animation: {
        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.

Managing a Map View Map Controls