README

Mapbox :: Interpolated Heatmap(s)

InterpolateHeatmapLayer is a minimalist JavaScript library for rendering temperature maps (or interpolate heatmaps) with Mapbox GL JS. This library was greatly inspired by the temperature-map-gl library, and depends on Earcut.

Currently, Mapbox provides a heatmap layer that represent the density of points in an area, like on this picture:

Density heatmap

This library aims at providing a heatmap that can define a color to any location by making an average of the values of the surroundings points, like on this picture:

Average heatmap

Except a JavaScript pre-processing step, all computation is made with WebGL shaders.

Examples

A live demo showing the global temperature is available here, described here.

Install

Browser:

Import the library before the script using it:

<body>
  <div id="map"></div>
  <script src="mapbox-gl-interpolate-heatmap.cjs.js"></script>
  <script src="map.js"></script>
</body>

Create the Mapbox map and add the layer created by interpolateHeatmapLayer.create():

// map.js

const map = new mapboxgl.Map({
  container: 'map',
  style: 'mapbox://styles/mapbox/light-v10',
});

map.on('load', () => {
  const layer = new MapboxInterpolateHeatmapLayer({
    // parameters here
  });
  map.addLayer(layer);
});

NPM:

npm install mapbox-gl-interpolate-heatmap

import { MapboxInterpolateHeatmapLayer } from 'mapbox-gl-interpolate-heatmap';

const map = new mapboxgl.Map({
  container: 'map',
  style: 'mapbox://styles/mapbox/light-v10',
});

map.on('load', () => {
  const layer = new MapboxInterpolateHeatmapLayer({
    // parameters here
  });
  map.addLayer(layer);
});

Usage

The new MapboxInterpolateHeatmapLayer() function has the following parameters:

data: An array of points, each point being an object containing a latitude lat, a longitude lon, and a value val. Example:
```
data = [
  {
    lat: 62.470663,
    lon: 6.176846,
    val: 16,
  },
  {
    lat: 48.094903,
    lon: -1.371596,
    val: 20,
  },
];
```
Since Mapbox uses the Web Mercator projection that projects the poles at infinity, remember to define the latitude within -85° and 85°. Default value: [].
id: unique Mapbox layer name. Default value: ''.
opacity: a number between 0 and 1 describing the transparency of the color. Default value: 0.5.
minValue: define the value corresponding to the blue color. When it's not defined, the lowest value of points is represented by the blue color. If some value of points is lower than minValue, minValue takes this value. Default value: Infinity.
maxValue same, but for the red color. Default value: -Infinity.
framebufferFactor: number between 0 and 1. In short, if the framebuffer factor is around 0, the computation will be faster but less accurate. Take a look at the technical explanation part if you want to know what exactly this parameter is. Default value: 0.3.
p: a factor affecting the computation of the color. A high value makes the color uniform around each point. Once again, take a look at the technical explanation part if you want to know more. Default value: 3.
aoi: area of interest, the layer will only be displayed inside that area. It's a list of coordinates with the same format as points (without the val attribute). If the list is empty, the entire map is the region of interest. Default value: [].
valueToColor: GLSL function (passed as a string) that map a value to the heatmap color. By default, a low value is colored blue, a medium green and a high red. This parameter allows you to change this behavior. The function must be named valueToColor with a float parameter (which will take values between 0 and 1), and must return a vec3 (with each component between 0 and 1). Default value:
```
vec3 valueToColor(float value) {
  return vec3(max((value-0.5)*2.0, 0.0), 1.0 - 2.0*abs(value - 0.5), max((0.5-value)*2.0, 0.0));
}
```
valueToColor4: Same as valueToColor, but with alpha channel support. The function name and signature must be defined as:

vec4 valueToColor4(float value, float defaultOpacity)

Default value:
```
vec4 valueToColor4(float value, float defaultOpacity) {
    return vec4(valueToColor(value), defaultOpacity);
}
```

Technical explanation

The color is computed using the Inverse Distance Weighting (IDW) algorithm:

Let:

$[(x_1, u1), ..., (x_N, u_N)]$

be N known data points. We want to find a continuous and once differentiable function:

$u(x): x \rightarrow R$

such as:

$\forall i \in [1, N], u(x_i) = u_i$

The basic form of the IDW is:

$u(x) = \left\{ \begin{array}{ll} \frac{\sum_{i=1}^{N} \omega_i u_i}{\sum_{i=1}^{N} \omega_i} & \mbox{if } \forall i \in [1, N], d(x, x_i) \neq 0 \\ u_i & \mbox{else.} \end{array} \right.$

where

$\omega_i(x) = \frac{1}{d(x, x_i)^p}$

In WebGL:

First, we render N textures. Each fragment of each texture contains wi*ui in its red channel, and wi in its green channel.
Then, we use blending with accumulator configuration on these N textures. It creates one texture, containing the sum of the N textures. Therefore, we can get u(x) for each fragment by dividing the red channel by the green channel.
We pass this texture to the shader rendering the heatmap, convert u(x) to a color, and finally display this color.

The size of the computation textures is the size of the rendering texture multiplied by the framebufferFactor. This factor can be below 0.5 without any real visual consequences. If the user has defined a region of interest and uses a framebufferFactor < 1, visual artifacts appear at the edge of the heatmap. To prevent this, the rendering texture takes the whole screen size if framebufferFactor < 1.

Contributing

Create your feature branch from dev (git checkout -b feat/new-feature)
Commit your changes (git commit -Sam 'feat: add feature')
Push to the branch (git push origin feat/new-feature)
Create a new Pull Request

Note:

Please contribute using Github Flow
Commits & PRs will be allowed only if the commit messages & PR titles follow the conventional commit standard, read more about it here
PS. Ensure your commits are signed. Read why

Please contribute using Github Flow. Create a new branch from the default branch, add commits, and open a pull request

mapbox-gl-interpolate-heatmap

Usage no npm install needed!