Timeline

Every map controller instance is initialized with a corresponding timeline which is responsible for managing the times used when requesting weather data and animating that weather data across a time series. While the MapsGL SDK will automatically manage date and time information as needed for each weather-related layerand data source added to a map controller, you can use the following public interface for controlling the timeline and animation playback.

Configuration

The following configuration options are supported when instantiating Timeline instances:

Option	Description	Default
`start`	Type: `Date` ()Start date of the timeline's time range.	`new Date()`
`end`	Type: `Date` ()End date of the timeline's time range.	`new Date()`
`duration`	Type: `number` ()Duration the animation should take to complete, in seconds.	`1`
`delay`	Type: `number` ()Duration to wait before starting the animation, in seconds.	`0`
`endDelay`	Type: `number` ()Duration to hold the end of the animation before repeating, in seconds.	`0`
`autoplay`	Type: `boolean` ()Whether the animation should begin playing immediately.	`false`
`repeat`	Type: `boolean` ()Whether the animation should restart after completing playback.	`true`
`enabled`	Type: `boolean` ()Whether the animation is enabled.	`true`

Since a timeline is initialized by MapController instances, you don't need to create your own Timeline instance. Instead, provide your configuration options when instantiating your MapController instance:

const controller = new aerisweather.mapsgl.MapboxMapController(map, {
    account: account,
    
    // timeline configuration options are included in the `animation` object
    animation: {
        duration: 2,
        endDelay: 1,
        repeat: true
    }
});

Properties

The following properties are available on Timeline instances:

Option	Description	Default
`state`	Type: `AnimationState` (readonly)An enumerated value indicating the current state of the animation: - `initial`: Animation has been initialized but is not ready for playback. - `loading`: Animation is currently loading data required for playback. - `ready`: Animation is ready for playback. - `playing`: Animation is currently playing. - `paused`: Animation is currently paused. - `stopped`: Animation is currently stopped. - `completed`: Animation has finished playback. This state will not be reached if `repeat` is enabled.
`enabled`	Type: `boolean` (readonly)Whether the animation is currently enabled. If `false`, then the animation will not begin playback or trigger playback-related events.
`duration`	Type: `number` ()Total duration of the animation in seconds.
`delay`	Type: `number` ()Delay before playing the animation, in seconds.
`endDelay`	Type: `number` ()Delay to hold the animation at the end before repeating from the beginning, in seconds.
`timeScale`	Type: `number` ()Factor used to scale the time of the animation where a value of `1` is normal speed, `0.5` is half speed, and `2` is double speed, etc. Only positive values are allowed.	`1`
`totalDuration`	Type: `number` (readonly)Total duration of the animation, which includes the `delay`, `duration` and `endDelay` values.
`elapsedTime`	Type: `number` (readonly)Total time that has elapsed since the animation began playing, in seconds.
`position`	Type: `number` (readonly)Current position of the playhead from `0` to `1` where `0` is the start of the animation and `1` is the end.
`isAnimating`	Type: `boolean` (readonly)Returns whether the animation is currently animating. Note that this value will be `false` when the animation is paused. If you want to test if the animation is currently active instead, use `isActive`.
`isPaused`	Type: `boolean` (readonly)Returns whether the animation is currently paused.
`isActive`	Type: `boolean` (readonly)Returns whether the animation is currently active, meaning its state is either playing or paused.
`startDate`	Type: `Date` ()Start date of the animation. This value must be equal to or earlier than `endDate`.
`endDate`	Type: `Date` ()End date of the animation. This value must be equal to or later than `startDate`.
`currentDate`	Type: `Date` (readonly)Date calculated from the playhead's current position.
`deltaTime`	Type: `number` (readonly)Total milliseconds between the end and start dates.
`containsPast`	Type: `boolean` (readonly)Returns whether the timeline contains time in the past.
`containsFuture`	Type: `boolean` (readonly)Returns whether the timeline contains time in the future.
`isPast`	Type: `boolean` (readonly)Returns `true` if the timeline only contains time in the past.
`isFuture`	Type: `boolean` (readonly)Returns `true` if the timeline only contains time in the future.

Methods

The following methods are available on Timeline instances:

Controlling Playback

play()

playFromDate(date: Date)

pause()

resume()

stop()

restart()

reset()

toggle()

goTo(position: number)

goToDate(date: Date)

Managing the Time Range

setStartDateUsingOffset(offset: number, relativeTo: Date)

setStartDateUsingRelativeTime(relativeDate: string, relativeTo: Date)

setEndDateUsingOffset(offset: number, relativeTo: Date)

setEndDateUsingRelativeTime(relativeDate: string, relativeTo: Date)

clampDateRange(min: Date, max: Date)

Events

The following events are triggered by Timeline instances.

play

pause

resume

stop

restart

reset

advance

range:change

Styles Legends