Map Timeline

Weather maps support displaying and animating their point data by using a time-based timeline rather than interval-based. 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 layers visible on the map when an animation starts playing will be animated and synced with the map’s primary timeline, meaning all map data is rendered relative to their specific time within the timeline’s range.

By default, a weather map animation will repeat infinitely with a longer pause at the end of the timeline before restarting the animation from the beginning. An animation’s speed is controlled by both the maximum number of intervals allowed within an animation (specifically for tile and image data layers) and the timeline’s date range. Since each data layer animates independent of each other, the total number of intervals may vary between the active layers.

Heads Up! Adding and removing tile/image map layers using the iOS SDK will count against your account's allowed daily map units, and animating these tile/image layers can consume your allowed map units quickly. Refer to the AerisWeather Mapping Platform Accesses documentation for more information regarding how map units are calculated. You can determine which data layers are tile/image layers using the global function AWFIsTileLayerType(AWFDataLayerType layerType) within the AerisMaps.framework of the SDK.

Defining a Time Range

When you initialize your weather map, you’ll want to provide a weather map configuration object that provides all of the required settings for your map. It is this configuration object where you will also want to specify the initial start and end intervals for your timeline’s range (if you have animations enabled in the configuration).

When using a weather map configuration object, you will specify the timeline’s range using time intervals relative to the current time when the map is created. For instance, the default timeline range always starts two (2) hours before now, and ends at the current date and time:

// 2 hours ago
mapConfig.timelineStartOffsetFromNow = -(AWFHourInterval * 2);

// now
mapConfig.timelineEndOffsetFromNow = 0;
// 2 hours ago
mapConfig.timelineStartOffsetFromNow = -(AWFHourInterval * 2)

// now
mapConfig.timelineEndOffsetFromNow = 0

Since these are time intervals, the actual start and end dates are unknown until the map and timeline have been initialized on your AWFWeatherMap instance, which occurs immediately at instantiation.

Alternatively, you can also dynamically change the timeline’s range by setting the available properties on your AWFWeatherMap instance once it has already been created, even at runtime. This differs from the map configuration method in that it requires the start and end dates to be actual NSDate instances, not time intervals:

NSDate *now = [NSDate date];

// 4 days ago
self.weatherMap.timelineStartDate = [now awf_dateByAddingDays:-4];

// 4 days from now
self.weatherMap.timelineStartDate = [now awf_dateByAddingDays:4];
let now = NSDate()

// 4 days ago
weatherMap.timelineStartDate = now.awf_date(byAddingDays: -4, ignoringTime: false)

// 4 days from now
weatherMap.timelineEndDate = now.awf_date(byAddingDays: 4, ignoringTime: false)

The start and end dates and/or time intervals can either be in the past or future. There are some requirements, however:

  • The starting date must always be earlier than the ending date.
  • The ending date must always be later than the starting date.

Changing the start and/or end dates on the timeline will stop any current animation and update the currently active data layers as needed.

Showing a Specific Time

While an animation is not currently playing, you can update the weather map to show weather data for a specific period in time within the timeline’s date range. Simply use the goToTime: method on your AWFWeatherMap instance, providing the date you want to update the map to:

NSDate *now = [NSDate date];

// show data for 1 hour ago
[self.weatherMap goToTime:[now awf_dateByAddingDays:-1]];
// show data for 1 hour ago
weatherMap.go(toTime: now.awf_date(byAddingDays: -1, ignoringTime: false))

You can also start animating from a specific time within the range using startAnimatingFromTime: on your weather map instance:

NSDate *now = [NSDate date];

// start animating from 1 hour ago
[self.weatherMap startAnimatingFromTime:[now awf_dateByAddingDays:-1]];
// start animating from 1 hour ago
weatherMap.startAnimating(fromTime: now.awf_date(byAddingDays: -1, ignoringTime: false))

If you need to obtain the current position along the timeline for which the map’s data layers are displaying data for, use the readonly property timelineCurrentTime on your weather map, which will return an NSDate representing the timeline’s current position.

Maximum Intervals

The maximum number of intervals allowed for an animated data layer controls both the speed of and the amount of detail for the animation. Also, for tile and image data layers, this value defines the maximum number of image requests that will be made when loading the data needed for playback.

This value is set using the maximumIntervalsForAnimation property on a weather map’s configuration object and must be a valid integer value greater than 0. If the total number of intervals available within a time period for a specific data layer is greater than this maximum interval value, then the animation will use the maximum intervals allowed equally distributed across the time range.

For instance, if a radar data layer currently has 40 intervals available, but we have set our maximumIntervalsForAnimation property equal to 20, then the set of intervals used for the animation will every other interval (0, 2, 4, 6,…) versus every interval (0, 1, 2, 3,…). This will have the effect of an animation that is less smooth since the differences (time) between two intervals will be greater than if they were consecutive intervals.

Last modified: July 30, 2020