@maptiler/weather
v3.1.1TypeScript
Weather layers for MapTiler Cloud and MapTiler SDK
1.0K/weekUpdated 2 weeks agoUnpacked: 1.0 MB
Published by MapTiler Team
npm install @maptiler/weather
Interactive weather layers to customize for MapTiler Cloud and MapTiler SDK JS
Live weather data in your map!
The Weather module for MapTiler SDK contains a set of weather-specific tiled layers to put into your map, just like any layer!
Here are some features:
- 4-day forecast 📅
- global coverage 🌐
- hourly precision ⏱
- fresh data every few hours (generaly ~6h) 📦
- animated 🏁
- highly customizable ✨
- plenty of built-in color ramps 🎨
- easy to setup with nice default settings 🙌
- pick weather values for any lon/lat (and mouse move) 📌
- included in your FREE MapTiler Cloud plan! 😎
A dedicated layer for each of the following variables:
- temperatures 🌡️
- winds ༄
- presure 🌀
- precipitations 🌧️
- radar 📡
Install
``
shell
npm install --save @maptiler/weather
`Every layer requires to use MapTiler SDK (which is built on top MapLibre Gl JS), if you don't have it already as part of your project, you can install the two together:
shell
npm install --save @maptiler/sdk @maptiler/weather
`Getting Started
Since all the layers are going to be added to a , let's instanciate a map first:`ts
import { Map, config, MapStyle } from "@maptiler/sdk";// Make sure you set your MapTiler Cloud API key:
config.apiKey = "YOUR_API_KEY";
// Let's assume you have a div container to place your map in
const map = new maptilersdk.Map({
container: someComtainer,
style: MapStyle.DATAVIZ.DARK,
});
`Then, regardless of the type of weather layer you want to add to your map, keep in mind that it behaves just like a regular SDK/MapLibre layer, so you probably want to place it under some labels and border. What we advice is to place it underneath the
layer that we make partially transparent:`ts
map.on('load', function () {
// Make the water layer a bit transparent:
map.setPaintProperty("Water", 'fill-color', "rgba(0, 0, 0, 0.5)"); // Add the weather layer underneath the
water layer:
map.addLayer(layer, 'Water');
});
`Layers
Each type of layer comes with a dedicated constructor to which can be provided the same minimal set of options:
- of type string. Default: depends on the type of layer.
- opacity of type number. Default: 1.
- colorramp of type ColorRamp. Default: depends on the type of layer
- smooth of type boolean. Default: true (colors are nicely interpolated)
Temperature Layer
Create a temperature layer:
`ts
import { TemperatureLayer } from "@maptiler/weather";// After creating a Map instance like in the
Getting Startedconst layer = new TemperatureLayer(); // using default settings
// or
const layer = new TemperatureLayer({ / options / }); // overwriting default
// Add the layer like in the
- Forecast for temperatures at 2m above ground
- The default layer ID is
- The unit is degree Celcius (°C)
- The default color ramp is , which spans from -70.15°C to 46.85°C
- Maximum range possible spans from to 128°CPressure Layer
Create a pressure layer:
ts
import { PressureLayer } from "@maptiler/weather";// After creating a Map instance like in the
Getting Startedconst layer = new PressureLayer(); // using default settings
// or
const layer = new PressureLayer({ / options / }); // overwriting default
// Add the layer like in the
- Forecast for air pressure at mean sea level
- The default layer ID is
- The unit is hecto Pascal (hPa) or millibar (mbar)
- The default color ramp is , which spans from 900hPa to 1080hPa
- Maximum range possible spans from to 1080hPaPrecipitation Layer
Create a precipitation layer:
ts
import { PrecipitationLayer } from "@maptiler/weather";// After creating a Map instance like in the
Getting Startedconst layer = new PrecipitationLayer(); // using default settings
// or
const layer = new PrecipitationLayer({ / options / }); // overwriting default
// Add the layer like in the
- Forecast for precipitation of all sorts (rain, snow, hail, sleet) in amount per hour
- The default layer ID is
- The unit is millimeter per hour (mm/h)
- The default color ramp is , which spans from 0mm/h to 50mm/h
- Maximum range possible spans from to 50mm/hRadar Layer
Create a radar reflectivity layer:
ts
import { RadarLayer } from "@maptiler/weather";// After creating a Map instance like in the
Getting Startedconst layer = new RadarLayer(); // using default settings
// or
const layer = new RadarLayer({ / options / }); // overwriting default
// Add the layer like in the
- Forecast for maximum composite radar reflectivity value
- The default layer ID is
- The unit is radar reflectivity factor (dBZ)
- The default color ramp is , which spans from 0dBZ to 75dBZ
- Maximum range possible spans from to 80dBZNote: the built-in color ramp
was specificaly designed by our team to represent cloud coverage, and may be more intuitive for generalistic weather forecast usecases. Give it a try!
ℹ️ Know more about radar reflectivity 📡
Radar reflectivity measure the amount and size of particles that are in the sky, but not only precipitation.
- dust and insects: from
-10dBZ to 5dBz
- light mist / drizzle / flurries: ~10dBZ
- mist / drizzle / flurries:
- very light rain or snow:
- light rain or snow:
- light to moderate rain or snow:
- moderate rain or snow, possible sleet: to 40dBZ
- moderate to heavy rain or snow, possible sleet:
- heavy rain or snow, possible sleet:
- very heavy rain or snow, with small hail possible:
- extreme rain or snow, with moderate hail possible:
- extreme rain or snow, with large hail possible: Read more about radar reflectivity
Wind Layer
Create a wind layer:
ts
import { WindLayer } from "@maptiler/weather";// After creating a Map instance like in the
Getting Startedconst layer = new WindLayer(); // using default settings
// or
const layer = new WindLayer({ / options / }); // overwriting default
// Add the layer like in the
- Forecast for speed and direction at an altitude of 10m above ground
- The default layer ID is
- The unit is meter per second (m/s)
- The default color ramp is , which spans from 0m/s to 40m/s
- Maximum range possible spans from to 75m/sThe wind layer contains both a background to which is applied a color ramp and a set of moving particles, for this reason, the constructor
has more options that then other weather layers. Please refer to our official documentation to have the complete list.Layer Methods
- .getAnimationStartDate(): Get the start date of the animated sequence, as a Date object
- .getAnimationStart(): Get the start date of the animated sequence, as a UNIX timestamp in seconds (number)
- .getAnimationEndDate(): Get the end date of the animated sequence, as a Date object
- .getAnimationEnd(): Get the end date of the animated sequence, as a UNIX timestamp in seconds (number)
- .setOpacity(opacity: number): Set the layer opacity, from 0 (fully transparent) to 1 (fully opaque)
- .getAnimationTimeDate(): Get the current time of the animation, as a Date object
- .getAnimationTime(): Get the current time of the animation, as a UNIX timestamp in seconds (number)
- .setAnimationTime(time: number): Set the animation time, as a UNIX timestamp in seconds (number)
- Emits event animationTimeSet
- : Plays the animation at a given speed factor. Pauses if factor is 0
- Emits event if factor is greater than 0
- Emits event if factor is 0
- : Get the animation speed factor
- .isPlaying(): Get if the animation is currently playing
- .pickAt(lng: number, lat: number): Get the value(s) as an object. Depending on the type of layer, the values returned can be in different units. Please refer to the official documetation
- async .onSourceReadyAsync(): Async function corresponding to the "sourceReady" event. Resolves directly if source is already ready, or awaits the event "sourceReady" if not.Layer Events
To add a calback function to a layer event, do the following:
`ts
layer.on("eventName", (e) => {
// Do something
})
`Here are the possible events:
-
- ⚡ Called only once after the layer has been added to the map, when all the necessary weather data source are loaded and ready to be used.
- 🍱 The event callback parameter is as such
-
- ⚡ Called when the animation is starting to play or plays after having been on pause after calling
- 🍱 The event callback parameter is as such with time being the timestamp in seconds
- pauseAnimation
- ⚡ Called when the animation is being paused after calling
- 🍱 The event callback parameter is as such with time being the timestamp in seconds
- tick
- ⚡ Called for each animation update, possibly many times per seconds
- 🍱 The event callback parameter is as such with time being the timestamp in seconds
- animationTimeSet
- ⚡ Called when the progress time of the animation is manually set with
- 🍱 The event callback parameter is as such with time being the timestamp in secondsNote that most layer methods can only called after the event
sourceReady has been emmited.Color Ramp
There are many builtin color ramps that are ready to be used. since most of them are defined in the interval [0, 1], they need to be scaled acording to their intended usage. Let's see how to do this:`ts
import { ColorRamp } from "@maptiler/weather";// Let's use the Viridis color ramp,
// but we want to use it for air pressure, so on a range [900, 1080] hPa
const viridisPressure = ColorRamp.builtin.VIRIDIS.scale(900, 1080);
`Note that the
method first clones the color ramp on which it is called so that the original one is not modified.A color ramp can also be flipped with
.reverse() or generate a canvas of itself with .getCanvasStrip() to create UI elements.To create a new color ramp manually that can be used with any of the weather layers, you must provide a color stop definition as follow:
`ts
import { ColorRamp, TemperatureLayer } from "@maptiler/weather";const myTemperatureColoramp = new ColorRamp({
stops: [
{ value: -65, color: [3, 78, 77, 255] },
{ value: -55, color: [4, 98, 96, 255] },
{ value: -40, color: [5, 122, 120, 255] },
{ value: -25, color: [6, 152, 149, 255] },
{ value: -20, color: [8, 201, 198, 255] },
{ value: -12, color: [20, 245, 241, 255] },
{ value: -8, color: [108, 237, 249, 255] },
{ value: -4, color: [133, 205, 250, 255] },
{ value: 0, color: [186, 227, 252, 255] },
{ value: 4, color: [238, 221, 145, 255] },
{ value: 8, color: [232, 183, 105, 255] },
{ value: 12, color: [232, 137, 69, 255] },
{ value: 20, color: [231, 107, 24, 255] },
{ value: 25, color: [236, 84, 19, 255] },
{ value: 30, color: [236, 44, 19, 255] },
{ value: 40, color: [123, 23, 10, 255] },
{ value: 55, color: [91, 11, 0, 255] },
],
})
const layer = new TemperatureLayer({
colorramp: myTemperatureColoramp,
});
`Note that all the color stop's
are in the actual unit of the layer (above: °C) and the colors are in [R, G, B, A].Again, find more details on what's possible with color ramps on our official documentation;
Color blindness
> Color blindness is the decreased ability to see colors or differences in colors.
> The most common form is caused by a genetic disorder called congenital red–green color blindness. source: Wikipedia
Because some forms of color blindness can affect up to 8% of the population, we thought it was fair that our library includes some perceptually uniform color ramps that are more color blind friendly.
The description from TypeScript auto completion will let you know about this information, otherwise, look for the ramps based on one of the following:
-
Mako
-
-
-
🎨 See all the builtin color ramps
License
MapTiler Weather JS Module
Copyright © 2023 MapTiler AG. All rights reserved.
The software and files (collectively “Software”) in this repository are licensed for use only with MapTiler service(s).
For the license terms, please reference MapTiler General Terms and Conditions which incorporate MapTiler Weather JS Module Product Terms (collectively “Terms”) and Privacy Policy at Privacy policy.
This license allows users with an active MapTiler account to modify and integrate authorized portions of the Software for use with the relevant MapTiler service(s) in accordance with the MapTiler Terms. This license terminates automatically if a user no longer maintains a MapTiler account or their usage breaches MapTiler Terms.