{"id":28727443,"url":"https://github.com/rylern/interpolateheatmaplayer","last_synced_at":"2026-03-12T19:35:11.179Z","repository":{"id":44918586,"uuid":"413418439","full_name":"Rylern/InterpolateHeatmapLayer","owner":"Rylern","description":"Minimalist JavaScript library for rendering temperature maps (or interpolate heatmaps) with Mapbox GJ JS","archived":false,"fork":false,"pushed_at":"2024-11-07T22:34:23.000Z","size":447,"stargazers_count":26,"open_issues_count":0,"forks_count":7,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-06-15T14:42:15.481Z","etag":null,"topics":["average-heatmap","heatmap","interpolation-heatmap","layer","mapbox-gl-js"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Rylern.png","metadata":{"files":{"readme":".github/README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-10-04T12:47:41.000Z","updated_at":"2024-11-08T01:57:53.000Z","dependencies_parsed_at":"2024-06-16T19:48:24.795Z","dependency_job_id":"766781d2-ad1f-4098-bcc6-c1e80defa53a","html_url":"https://github.com/Rylern/InterpolateHeatmapLayer","commit_stats":null,"previous_names":[],"tags_count":8,"template":false,"template_full_name":null,"purl":"pkg:github/Rylern/InterpolateHeatmapLayer","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Rylern%2FInterpolateHeatmapLayer","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Rylern%2FInterpolateHeatmapLayer/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Rylern%2FInterpolateHeatmapLayer/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Rylern%2FInterpolateHeatmapLayer/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Rylern","download_url":"https://codeload.github.com/Rylern/InterpolateHeatmapLayer/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Rylern%2FInterpolateHeatmapLayer/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30440002,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-12T14:34:45.044Z","status":"ssl_error","status_checked_at":"2026-03-12T14:09:33.793Z","response_time":114,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["average-heatmap","heatmap","interpolation-heatmap","layer","mapbox-gl-js"],"created_at":"2025-06-15T14:40:55.585Z","updated_at":"2026-03-12T19:35:11.150Z","avatar_url":"https://github.com/Rylern.png","language":"JavaScript","readme":"# InterpolateHeatmapLayer\n\nInterpolateHeatmapLayer is a JavaScript library for rendering temperature maps (or interpolate heatmaps) with [Mapbox GJ JS](https://docs.mapbox.com/mapbox-gl-js/guides/). This library was inspired by the [temperature-map-gl](https://github.com/ham-systems/temperature-map-gl) library and depends on [Earcut](https://github.com/mapbox/earcut).\n\nCurrently, Mapbox provides a heatmap layer that represent the **density** of points in an area, like on this picture:\n\n![Density heatmap](images/densityHeatmap.png)\n\nThis 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:\n\n![Average heatmap](images/averageHeatmap.png)\n\nExcept a JavaScript pre-processing step, all computation is made with WebGL shaders.\n\n## Examples\n\nA live demo showing the global temperature is available [here](https://rylern.github.io/TemperatureMap/), described [here](https://github.com/Rylern/TemperatureMap).\n\n## Install\n\nNote that this layer only works if the [Mercator](https://docs.mapbox.com/mapbox-gl-js/guides/projections/#what-projections-are-available) projection is used on the Mapbox map.\n\n* Browser:\n\n  * Copy the [interpolateHeatmapLayer.js](https://github.com/Rylern/InterpolateHeatmapLayer/blob/main/dist/interpolateHeatmapLayer.js) file to your project.\n\n  * Import the library before the script using it:\n\n    ```html\n    \u003cbody\u003e\n        \u003cdiv id=\"map\"\u003e\u003c/div\u003e\n        \u003cscript src=\"interpolateHeatmapLayer.js\"\u003e\u003c/script\u003e\n        \u003cscript src=\"map.js\"\u003e\u003c/script\u003e\n    \u003c/body\u003e\n    ```\n\n  * Create the Mapbox map and add the layer created by `interpolateHeatmapLayer.create()`:\n\n  ```javascript\n  // map.js\n  \n  const map = (window.map = new mapboxgl.Map({\n      container: 'map',\n      style: 'mapbox://styles/mapbox/light-v10'\n  }));\n      \n  map.on('load', () =\u003e {\n      const layer = interpolateHeatmapLayer.create({\n          // parameters here\n      });\n      map.addLayer(layer);\n  });\n  ```\n\n\n* NPM:\n\n  ```bash\n  npm install interpolateheatmaplayer\n  ```\n\n  ```javascript\n  const interpolateHeatmapLayer = require('interpolateheatmaplayer');\n  // or: import { create as InterpolateHeatmapLayer } from 'interpolateheatmaplayer';\n  \n  const map = (window.map = new mapboxgl.Map({\n      container: 'map',\n      style: 'mapbox://styles/mapbox/light-v10'\n  }));\n      \n  map.on('load', () =\u003e {\n      const layer = interpolateHeatmapLayer.create({\n          // parameters here\n      });\n      // or: const layer = InterpolateHeatmapLayer({});\n\n      map.addLayer(layer);\n  });\n  ```\n\n## Usage\n\nThe `interpolateHeatmapLayer.create()` function has one object parameter containing the following properties:\n\n* `points`: An list of points, each point being an object containing a latitude `lat`, a longitude `lon`, and a value `val`. Example:\n\n  ```javascript\n  points = [{\n    lat: 62.470663,\n    lon: 6.176846,\n    val: 16\n  },\n  {\n    lat: 48.094903,\n    lon: -1.371596,\n    val: 20\n  }];\n  ```\n\n  Since Mapbox uses the Web Mercator projection that projects the poles at infinity, remember to define the latitude within -85° and 85°. Default value: `[]`.\n\n* `layerId`: string defining the unique [Mapbox layer](https://docs.mapbox.com/mapbox-gl-js/style-spec/layers/#id) name. Default value: `''`.\n\n* `opacity`: number between 0 and 1 describing the transparency of the layer. Default value: `0.5`.\n\n* `minValue`: number defining 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`.\n\n* `maxValue` same, but for the red color. Default value: `-Infinity`.\n\n* `p`: number affecting the computation of the color. A high value makes the color uniform around each point. Take a look at the form of the IDW in the technical explanation part if you want to know more. Default value: `3`.\n\n* `pointRadius`: number defining a radius (in meters). The color will only appear within circles of radius `pointRadius` centered at the points defined in `points`. If `pointsRadius \u003c= 0`, this parameter is not taken into account. Default value: `0`.\n\n* `fasterPointRadius`: boolean indicating if a faster algorithm should be used when defining a `pointRadius \u003e 0`. Due to precision issues, this parameter creates bad visualizations if `pointRadius \u003c 500`. Default value: `false`.\n\n* `roi`: list of coordinates with the same format as `points` (without the `val` attribute). It defines the region of interest, meaning the layer will only be displayed inside that area. If the list is empty, the entire map is the region of interest. If `pointRadius \u003e 0` and a ROI is defined, then the heatmap will only appear on locations that are within the circles AND within the ROI. Default value: `[]`.\n\n* `averageThreshold`: number defining a threshold. For each point of the map, if the distance between the point's value and the average value of all points is below this threshold, the associated color will be transparent. The values and the average are scaled between 0 and 1 when computing their distance, so `averageThreshold` is a value between 0 and 1. For example, if you have `points` with values [0, 5, 10], and you create the layer with these parameters:\n\n  ```javascript\n  const layer = interpolateHeatmapLayer.create({\n      points: points\n      averageThreshold: 0.1\n  });\n  ```\n\n  Then all points with values between 4 and 6 will be transparent.\n\n* `framebufferFactor`: number between 0 and 1. In short, if the framebuffer factor is around 0, the computation of the Inverse Distance Weighting algorithm will be faster but with a lower resolution. Take a look at the technical explanation part if you want to know exactly what this parameter is. Default value: `0.3`.\n\n* `valueToColor`: [GLSL](https://www.khronos.org/opengl/wiki/OpenGL_Shading_Language) function (passed as a string) that maps a value to the layer 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:\n\n  ```glsl\n  vec3 valueToColor(float value) {\n    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));\n  }\n  ```\n\n* `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:\n\n  ```glsl\n  vec4 valueToColor4(float value, float defaultOpacity) {\n      return vec4(valueToColor(value), defaultOpacity);\n  }\n  ```\n\n* `layerBlendingFactor`: a GLEnum that describes a coefficient to apply to the heatmap layer when blending with the map. Depending on where the heatmap layer is created, it is likely that it will appear on top of the map. In that case, pixels of the heatmap layer are blended with pixels of the map. The resulting color of a pixel is given by:\n\n  ```\n  color = (layerColor * layerBlendingFactor) + (mapColor * mapBlendingFactor)\n  ```\n\n  where `layerBlendingFactor` and `mapBlendingFactor` are parameters specifiable here.\n\n  A list of possible values of these parameters can be found [here](https://developer.mozilla.org/en-US/docs/Web/API/WebGLRenderingContext/blendFunc#constants):\n  * You have to replace `gl` by `WebGLRenderingContext`, for example `WebGLRenderingContext.ZERO`.\n  * The source color refers to the heatmap color, and the destination color refers to the map color.\n  \n  Default value: `WebGLRenderingContext.SRC_ALPHA`.\n\n* `mapBlendingFactor`: same as `layerBlendingFactor`, but for the map. Default value: `WebGLRenderingContext.ONE_MINUS_SRC_ALPHA`.\n\nThe `layer` returned by the `interpolateHeatmapLayer.create()` function has also one function: `layer.updatePoints(points)`, in which `points` is an array of points as described above (objects with `lat`, `lon`, and `val` attributes). This function allows you to change the points without creating a new layer. Usage example:\n\n```javascript\nconst layer = interpolateHeatmapLayer.create({\n  points: somePoints\n});\n// some code\nlayer.updatePoints(newPoints);\n```\n\n## Technical explanation\n\nThe color is computed using the [Inverse Distance Weighting](https://en.wikipedia.org/wiki/Inverse_distance_weighting) (IDW) algorithm:\n\nLet:\n\n![equation](https://latex.codecogs.com/gif.latex?%5B%28x_1%2C%20u1%29%2C%20...%2C%20%28x_N%2C%20u_N%29%5D)\n\nbe *N* known data points. We want to find a continuous and once differentiable function:\n\n![equation](https://latex.codecogs.com/gif.latex?u%28x%29%3A%20x%20%5Crightarrow%20R)\n\nsuch as:\n\n![equation](https://latex.codecogs.com/gif.latex?%5Cforall%20i%20%5Cin%20%5B1%2C%20N%5D%2C%20u%28x_i%29%20%3D%20u_i)\n\nThe basic form of the IDW is:\n\n![equation](https://latex.codecogs.com/gif.latex?u%28x%29%20%3D%20%5Cleft%5C%7B%20%5Cbegin%7Barray%7D%7Bll%7D%20%5Cfrac%7B%5Csum_%7Bi%3D1%7D%5E%7BN%7D%20%5Comega_i%20u_i%7D%7B%5Csum_%7Bi%3D1%7D%5E%7BN%7D%20%5Comega_i%7D%20%26%20%5Cmbox%7Bif%20%7D%20%5Cforall%20i%20%5Cin%20%5B1%2C%20N%5D%2C%20d%28x%2C%20x_i%29%20%5Cneq%200%20%5C%5C%20u_i%20%26%20%5Cmbox%7Belse.%7D%20%5Cend%7Barray%7D%20%5Cright.)\n\nwhere\n\n![equation](https://latex.codecogs.com/gif.latex?%5Comega_i%28x%29%20%3D%20%5Cfrac%7B1%7D%7Bd%28x%2C%20x_i%29%5Ep%7D)\n\nIn WebGL, the computation is done in three steps:\n\n* First, we determine where to display the heatmap. This can change depending on the `pointRadius` or `roi` parameters for example. For that, we create a texture where pixel values indicate if the heatmap should be displayed or not. Think of it as a **mask** in Computer Graphics.\n\n* Then, we compute the values given by the **IDW** equation. For that, we render *N* textures, one for each known data point *ui*. Each pixel of each texture contains *wi\\*ui* in its red channel and *wi* in its green channel. These textures are added together to create a single resulting texture containing the sum of the *N* textures. We can get u(x) for each pixel by dividing the red channel by the green channel, since they contain respectively *sum(wi\\*ui)* and *sum(ui)*.\n\n* Finally, the first (mask) and last (IDW) textures are combined to create the heatmap layer. For each pixel, if the mask pixel indicates that the heatmap should appear here, the IDW pixel is used to compute u(x), and this value is converted to a color using the `valueToColor` parameter.\n\nAs you can see, N+3 textures are created, with N+1 textures for the IDW step. This step is therefore the most expensive one. To make it a bit faster, we can reduce the sizes of those N+1 textures (a smaller texture means fewer pixels to compute). This is what the `framebufferFactor` is for. The width/height of the IDW textures are the width/height of the drawing texture divided by the `framebufferFactor`. For example, if the Mapbox map has a size of 800x600 pixels and the `framebufferFactor` is 0.5, then the IDW textures will have a size of 400x300 pixels. This will alter the visual aspect of the heatmap but will make the computer faster, so there is a compromise to find.\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frylern%2Finterpolateheatmaplayer","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frylern%2Finterpolateheatmaplayer","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frylern%2Finterpolateheatmaplayer/lists"}