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.
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;
// 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
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)
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:
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.
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 NSDate *now = [NSDate date]; [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
// start animating from 1 hour ago NSDate *now = [NSDate date]; [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 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.
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 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 AerisWeather 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 AerisWeather Mapping Platform layers reference for more information about the different update intervals for data layers.
Last modified: July 30, 2020