Animating weather map layers with Mapbox GL

Xweather Maps boasts a versatile range of capabilities, allowing users to generate static maps, interactive tiles, and animations. Along with various display methods, Xweather Maps can be utilized as a third-party source in most mapping libraries. In this tutorial, we'll discuss the process of animating Xweather Maps layers in an existing Mapbox GL application.

Step 1: Choose your implementation method

You have several options to build weather animations using Mapbox GL and Xweather Maps: 

1. Use the Xweather JS SDK to add interactive animations by combining the existing and animated interactive map demos

2. Build custom animation code to avoid adding and maintaining additional dependencies

Our focus moving forward will demonstrate the latter.

Step 2: Get started with Mapbox

There are countless variations of existing Mapbox applications. This post will be using the Quickstart section from the Mapbox documents as a starting point; however, these concepts will also apply to other applications. Here's our starting point: 

Step 3: Integrate your map tiles

Have the following handy:

• An active Xweather Flex subscription (get started with a free trial here!) 

• Your client_id and client_secret (you can find these in your Account Dashboard) 

Next, you'll decide which Map layer(s) to add. This example will use the radar 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 map tiles:

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

Step 4: Showing & hiding radar layers

Now that we've established how to get Xweather 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 addSource() and addLayer() methods, which will be included in the addRasterLayer() function:

Notice this function takes a single argument, i. This will be used to identify each frame as we loop over the animation frames. To get the show/hide effect we want, we'll need to control the opacity of our raster layer with the setPaintProperty() method. When this method is called upon we paint the raster-opacity. The raster-opacity 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):

Step 5: 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 frameCount. Keep in mind that more frames mean more resources that need to be loaded, which could potentially slow down your load time. We've set intervalStep, which determines the number of minutes between each valid time, or frame. This will be used in conjunction with the previously-mentioned offset parameter to calculate each step. The currentImageOffset will initially be set to 0 because our animation will end with the most current frame available. Our lastImageOffset is also currently set to currentImageOffset so we have a reference for the last loaded frame.

To kick off our animation, we'll wrap everything in the map.on() method, which will take a load event and a callback function:

Once the Mapbox GL map has completed loading, we can begin loading the Xweather Maps tiles. The first addRasterLayer() and showRasterLayer() calls are loading the very first frame, which is the most recent radar valid time we have (0). Then our for loop grabs every tile for every frame and loads them into the browser so they're ready to use. Finally, the setInterval() function will show and hide each frame sequentially every second.

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 (and for the full example and inspiration, visit our Maps docs!):

• Wrap setInterval() in a new function to trigger the animation based on a different event (user input, adding stop/play buttons, etc.)

• Try a new Maps 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

Tip: Try the Xweather Maps wizard to build your tile URL for your next animation project.