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)).