July 14

Animating Map Layers with Mapbox GL

AerisWeather Maps boasts a versatile range of capabilities. Maps allows users to generate static maps, interactive tiles, and animations. Along with various methods to display you maps, Maps can be utilized as a 3rd party source in most mapping libraries. Let’s take a minute to discuss how easy it is to add an animation to an existing Mapbox GL application. For the tl;dr version, check out our live example.

Choose Your Implementation Method

We have a couple options you may want to explore. Using the AerisWeather JS SDK, adding an interactive animation is simple by combining the existing map and animate interactive map demos. Another option involves building custom animation code. This allows users to avoid adding and maintaining additional dependencies. Our focus moving forward will demonstrate the latter.

Starting With Mapbox

There are countless variations of existing Mapbox applications, but this post will be using the Quickstart section from the Mapbox documents as a starting point. However, the concepts will be the same for other applications. Here’s our starting point:

Integrating AMP Tiles

First order of business make sure you have your and  and an active Maps subscription. Then we can decide which Map layer(s) we want to add, this example will use the layer. Let’s set these variables like so:

Next we’ll take a look at two functions that will help build the resource path for adding the AMP tiles:


function getTilePaths(offset) {
return [
getPath(1, offset),
getPath(2, offset),
getPath(3, offset),
getPath(4, offset),

The first function, will generate a single tile URL with all the necessary components for Mapbox to add a 3rd party tile source (AMP). This function will take two arguments, and . The  variable will be used to calculate the valid time for each animation frame while will be defined in . Our function will return four tile paths, one for each server that users can access for Maps. Using four server tiles instead of one will help improve load times and overall customer experience.

Showing & Hiding Radar Layers

Now that we’ve established how to get Maps resources loaded, we need to include logic to add these tiles to the map instance. We also need to consider how we are going to animate. The animation will consist of several frames that will be shown and hidden synchronously to get the animation effect. First, we will need to use Mapbox’s and methods, which will be included in the function:

Notice this function takes a single argument, . This will be used to identify each frame as we loop over the animation frames. In order to get the show / hide effect we want we’ll need to control the opacity of our raster layer with the   method. When this method is called upon we paint the . The can also be used as a transition per the spec which will allow for a smoother change between layers. We’ll add this to a single function like so:

However, this function will be called from two separate functions, one to set opacity to zero (hide) and another to set opacity to one (show):

Putting It All Together

The blueprint for our animation is complete, but we still need to kick it all off. We’ll start by setting a few global variables that will be used for our animation:

The number of frames in your animation is defined by . Keep in mind more frames means more resources need to be loaded which could potentially slow down your overall load time. We’ve set  which determines the number of minutes between each valid time, or frame. This will be used in conjunction with the previously mentioned parameter to calculate each step. The will initially be set to 0 because our animation will end with the most current frame available. Additionally, our is currently set to so we have a reference for the last loaded frame. To kick off our animation we’ll wrap everything in the
method which will take a event and a callback function:

Once the Mapbox map has completed loading we being loading Map tiles. The first and calls are loading the very first frame which is the most recent radar valid time we have (o). Then our for loop grabs every tile for every frame and loads them into the browser so they’re ready to use. Finally, the function will show and hide each frame sequentially every second. Congratulations, you have successfully created animations with the AMP tiles!

Advanced Challenges

This tutorial focuses on a basic approach to creating an animation. Here are a few ideas to take your animation one step further:

  • Wrap  in a new function to trigger the animation based on a different event (i.e. user input, adding stop / play buttons, etc.).
  • Try a new Map layer to animate. Note, you will need to pay attention to the Updates interval in the docs to ensure you’re giving enough time between steps.
  • Animate into the future with a forecast layer and some tweaking of the animation logic.

To view the full example, please visit our Map docs. Hopefully this tutorial helped outline a few basic principles for integrating AMP animations into existing 3rd party libraries. Use the Map Wizard to build your tile URL for your next animation project!

Share this post:

Leave a Reply

Your email address will not be published.

This site uses Akismet to reduce spam. Learn how your comment data is processed.