Map Timeline

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

You can determine which data layers are Maps-specific layers by using the static [AWFWeatherLayer isAmp:(AWFMapLayer)layerType] method.

Defining a Time Range

When you instantiate your weather map, it's setup using the default weather map configuration or a custom configuration you specify. This configuration object also provides information about the map's timeline, such as the timeline's start and end dates and the maximum number of intervals allowed for an animation.

You set the timeline start and end dates using in your configuration using time intervals relative to the current date and time when the map is initialized or updated. 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

Since these are defined using time interval offsets, the actual date and time will not be known until the map has been initialized or updated.

Alternatively, you can set the start and end dates for your timeline specifically on your weather map using the timeline.startDate and timeline.endDate properties:

let now = NSDate()
// 4 days ago
weatherMap.timeline.startDate = now.awf_date(byAddingDays: -4, ignoringTime: false)
// 4 days from now
weatherMap.timeline.endDate = now.awf_date(byAddingDays: 4, ignoringTime: false)

This differs from using the weather map configuration method in that it requires the start and end dates to be NSDate instances instead of time intervals.

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.

Updating the start and/or end dates on your weather map instance 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.

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 your AWFWeatherMap instance and provide the date you want to advance the timeline to:

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

// start animating from 1 hour ago
weatherMap.startAnimating(fromTime: now.awf_date(byAddingDays: -1, ignoringTime: false))

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

Setting the Maximum Intervals

The maximum number of intervals allowed for an animated data source controls both the speed and the amount of detail for the animation. Additionally, for image/raster data sources, this value defines the maximum number of image requests that will be made when loading the data required for playback.

This value is defined using the maximumIntervalsForAnimation property on a weather map's configuration object and must be an integer greater than 0. The actual time intervals that are requested will be equalized across the timeline's range, meaning the time between each interval will is equivalent to the timeline's total time duration divided by the number of intervals requested.

For instance, if a timeline range totals 6 hours (360 minutes) and the total intervals requested is 10, then the total time between each interval will be 40 minutes (360 / (10 - 1)). The total time is divided by one less than the total number of intervals because we always want to load data for the very beginning and ending of the range.

Animating Multiple Layers

Animating multiple data layers and sources on a weather map is easy because the weather map handles everything for you. But one thing to be aware of is that the update intervals vary across all data layers and sources. Thus, not all layers will animated at the same intervals.

For example, radar imagery for the US updates about every 6 minutes, whereas infrared satellite updates every 15 minutes. So animating these two layers together may contain more intervals from radar than satellite depending on your timeline's range and number of intervals requested.

Point data sources will load all available data from the Xweather Weather API for the timeline's range and animate points based on the event's timestamp for the model associated with the point. So these points will be displayed at their exact time of occurrence during an animation's playback.

Refer to the Xweather Raster Maps layers reference (opens in a new tab) for more information about the different update intervals for data layers.