MapLibre GL Interpolate Heatmap

A MapLibre GL JS custom layer for rendering interpolated heatmaps (extracting average values) with WebGL shaders. Works with MapLibre GL JS v5+ (WebGL2).

This library was greatly inspired by temperature-map-gl and depends on Earcut.

Density vs Interpolated Heatmaps

MapLibre provides a built-in heatmap layer that represents the density of points:

This library provides an interpolated heatmap that calculates colors based on the weighted average of surrounding point values:

Installation

# npm
npm install maplibre-gl-interpolate-heatmap maplibre-gl

# bun
bun add maplibre-gl-interpolate-heatmap maplibre-gl

# JSR
bunx jsr add @geoql/maplibre-gl-interpolate-heatmap

Usage

import maplibregl from 'maplibre-gl';
import { MaplibreInterpolateHeatmapLayer } from 'maplibre-gl-interpolate-heatmap';
import 'maplibre-gl/dist/maplibre-gl.css';

const map = new maplibregl.Map({
  container: 'map',
  style: 'https://demotiles.maplibre.org/style.json',
  center: [0, 20],
  zoom: 2,
});

map.on('load', () => {
  const layer = new MaplibreInterpolateHeatmapLayer({
    id: 'temperature',
    data: [
      { lat: 62.47, lon: 6.18, val: 16 },
      { lat: 48.09, lon: -1.37, val: 20 },
      { lat: 35.68, lon: 139.69, val: 28 },
    ],
    opacity: 0.5,
    minValue: 10,
    maxValue: 35,
  });

  map.addLayer(layer);
});

Options

| Option | Type | Default | Description | | ------------------- | ------------------------ | ----------- | ---------------------------------------------------------------- | | id | string | '' | Unique layer ID | | data | Array<{lat, lon, val}> | [] | Data points (latitude must be within -85° to 85°) | | opacity | number | 0.5 | Layer opacity (0-1) | | minValue | number | Infinity | Value mapped to blue color | | maxValue | number | -Infinity | Value mapped to red color | | p | number | 3 | IDW power parameter (higher = more uniform colors around points) | | framebufferFactor | number | 0.3 | Computation resolution (0-1, lower = faster but less accurate) | | aoi | Array<{lat, lon}> | [] | Area of interest polygon (empty = entire map) | | valueToColor | string | See below | GLSL function mapping value (0-1) to vec3 color | | valueToColor4 | string | See below | GLSL function mapping value to vec4 with alpha |

Custom Color Functions

Default valueToColor (blue → green → red gradient):

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)
  );
}

Default valueToColor4:

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

How It Works

Colors are computed using Inverse Distance Weighting (IDW):

1. Render N textures, each containing wi * ui (red) and wi (green) per fragment
2. Blend textures with accumulator to sum all contributions
3. Divide red by green channel to get interpolated value u(x)
4. Map value to color using the GLSL color function

Where wi(x) = 1 / d(x, xi)^p is the weight based on distance.

Requirements

• Node.js >= 24.0.0
• MapLibre GL JS >= 3.0.0 (v5+ recommended for WebGL2)

Contributing

1. Fork and create a feature branch from main
2. Make changes following conventional commits
3. Ensure commits are signed (why?)
4. Submit a PR

bun install
bun run build
bun run lint
bun run format

License

MIT © Vinayak Kulkarni