Skip to main content

HeatmapTileLayer (Experimental)

HeatmapTileLayer is a layer for visualizing point data aggregated using the Quadbin Spatial Index using a heatmap.

Usage​

import DeckGL from '@deck.gl/react';
import {HeatmapTileLayer, quadbinTableSource} from '@deck.gl/carto';

function App({viewState}) {
  const data = quadbinTableSource({
    accessToken: 'XXX',
    connectionName: 'carto_dw',
    tableName: 'carto-demo-data.demo_tables.quadbin'
  });

  const layer = new HeatmapTileLayer({
    data,
    getWeight: d => d.properties.count
  })

  return <DeckGL viewState={viewState} layers={[layer]} />;
}

Installation​

To install the dependencies from NPM:

npm install deck.gl
# or
npm install @deck.gl/core @deck.gl/layers @deck.gl/carto
import {HeatmapTileLayer} from '@deck.gl/carto';
new HeatmapTileLayer({});

To use pre-bundled scripts:

<script src="https://unpkg.com/deck.gl@^9.0.0/dist.min.js"></script>
<script src="https://unpkg.com/@deck.gl/carto@^9.0.0/dist.min.js"></script>

<!-- or -->
<script src="https://unpkg.com/@deck.gl/core@^9.0.0/dist.min.js"></script>
<script src="https://unpkg.com/@deck.gl/layers@^9.0.0/dist.min.js"></script>
<script src="https://unpkg.com/@deck.gl/geo-layers@^9.0.0/dist.min.js"></script>
<script src="https://unpkg.com/@deck.gl/carto@^9.0.0/dist.min.js"></script>
new deck.carto.HeatmapTileLayer({});

Properties​

Inherits from all Base Layer and CompositeLayer properties.

data (TilejsonResult)​

Required. A valid TilejsonResult object.

Use one of the following Data Sources to fetch this from the CARTO API:

Render Options​

radiusPixels (number, optional) transition-enabled​

  • Default: 20

Radius of the heatmap blur in pixels, to which the weight of a cell is distributed.

colorDomain (number[2], optional) transition-enabled​

  • Default: [0, 1]

Controls how weight values are mapped to the colorRange, as an array of two numbers [minValue, maxValue]. The values are normalized, with a value of 1 corresponding to the maximum density present in the viewport.

When colorDomain is specified, a pixel with minValue is assigned the first color in colorRange, a pixel with maxValue is assigned the last color in colorRange, and any value in between is interpolated. Pixels in the bottom 10% of the range defined by colorDomain are gradually faded out by reducing alpha, until 100% transparency at minValue. Pixels with weight more than maxValue are capped to the last color in colorRange.

colorRange (Color[], optional)​

The color palette used in the heatmap, as an array of colors [color1, color2, ...]. Each color is in the format of [r, g, b]. Each channel is a number between 0-255.

intensity (number, optional) transition-enabled​

  • Default: 1

Value that is multiplied with the total weight at a pixel to obtain the final weight. A value larger than 1 biases the output color towards the higher end of the spectrum, and a value less than 1 biases the output color towards the lower end of the spectrum.

Data Accessors​

getWeight (Accessor<number>, optional)​

  • Default: 1

Method called to retrieve weight of each quadbin cell. By default each cell will use a weight of 1.

Callbacks​

onMaxDensityChange (Function, optional)​

Function that is called when the maximum density of the displayed data changes. The units correspond to a density, such that a value of 1 is a weight of 1 across the entire world, in Mercator projection space. To obtain the density the layer invokes the getWeight accessor on all visible quadbin cells, normalizing by the cell area (0.25 ** cellZ). The value is then heurstically adjusted based on the viewport zoom to give smooth transitions when the data changes.

  • Default: null
Example​

A quadbin cell at zoom level 2 with a weight of 1000 gives a density of 16000 (1000 / (0.25 ** 2)). Upon zooming in, there are different ways the data can be distributed, with the extremes are given here:

  • At zoom level 3 the cell splits equally into four cells with weight 250. The density stays at 16000 (250 / (0.25 ** 3)).
  • The cell splits into three empty cells and one with weight 1000. The density increases to 64000 (1000 / (0.25 ** 3)).