Skip to main content

ContourLayer

Edit on Codepen

The ContourLayer aggregates data into iso-lines or iso-bands for a given threshold and cell size. Isoline represents collection of line segments that separate the area above and below a given threshold. Isoband represents a collection of polygons (filled) that fill the area containing values in a given threshold range. To generate an Isoline single threshold value is needed, to generate an Isoband an array with two values needed. Data is first aggregated using given cell size and resulting scalar field is used to run Marching Squares algorithm that generates a set of vertices to form Isolines or Isobands. In below documentation Isoline and Isoband is referred as contour.

import {Deck} from '@deck.gl/core';
import {ContourLayer} from '@deck.gl/aggregation-layers';

const layer = new ContourLayer({
  id: 'ContourLayer',
  data: 'https://raw.githubusercontent.com/visgl/deck.gl-data/master/website/sf-bike-parking.json',

  cellSize: 200,
  contours: [
    {threshold: 1, color: [255, 0, 0], strokeWidth: 2, zIndex: 1},
    {threshold: [3, 10], color: [55, 0, 55], zIndex: 0},
    {threshold: 5, color: [0, 255, 0], strokeWidth: 6, zIndex: 2},
    {threshold: 15, color: [0, 0, 255], strokeWidth: 4, zIndex: 3}
  ],
  getPosition: d => d.COORDINATES,
  getWeight: d => d.SPACES,
  pickable: true
});

new Deck({
  initialViewState: {
    longitude: -122.4,
    latitude: 37.74,
    zoom: 11
  },
  controller: true,
  getTooltip: ({object}) => object && `threshold: ${object.contour.threshold}`,
  layers: [layer]
});

Installation​

To install the dependencies from NPM:

npm install deck.gl
# or
npm install @deck.gl/core @deck.gl/layers @deck.gl/aggregation-layers
import {ContourLayer} from '@deck.gl/aggregation-layers';
import type {ContourLayerProps} from '@deck.gl/aggregation-layers';

new ContourLayer<DataT>(...props: ContourLayerProps<DataT>[]);

To use pre-bundled scripts:

<script src="https://unpkg.com/deck.gl@^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/aggregation-layers@^9.0.0/dist.min.js"></script>
new deck.ContourLayer({});

Properties​

Inherits from all Base Layer properties.

Render Options​

cellSize (number, optional) transition-enabled​

  • Default: 1000

Size of each cell in meters

gpuAggregation (boolean, optional)​

  • Default: true

When set to true and browser supports GPU aggregation, aggregation is performed on GPU. GPU aggregation can be 2 to 3 times faster depending upon number of points and number of cells.

aggregation (string, optional)​

  • Default: 'SUM'

Defines the type of aggregation operation, valid values are 'SUM', 'MEAN', 'MIN' and 'MAX'. When no value or an invalid value is set, 'SUM' is used as aggregation.

  • SUM : Grid cell contains sum of all weights that fall into it.
  • MEAN : Grid cell contains mean of all weights that fall into it.
  • MIN : Grid cell contains minimum of all weights that fall into it.
  • MAX : Grid cell contains maximum of all weights that fall into it.

contours (object[], optional)​

  • Default: [{threshold: 1}]

Array of objects with following keys

  • threshold (number | number[2]) :

    • Isolines: threshold value must be a single number, Isolines are generated based on this threshold value.
    • Isobands: threshold value must be an array of two numbers. Isobands are generated using [threshold[0], threshold[1]) as threshold range, i.e area that has values >= threshold[0] and < threshold[1] are rendered with corresponding color. NOTE: threshold[0] is inclusive and threshold[1] is not inclusive.

  • color (Color, optional) : RGBA color array to be used to render the contour, if not specified a default value of [255, 255, 255, 255] is used. When a three component RGB array specified, a default value of 255 is used for Alpha.

  • strokeWidth (number, optional) : Applicable for Isolines only, width of the Isoline in pixels, if not specified a default value of 1 is used.

  • zIndex (number, optional) : Defines z order of the contour. Contour with higher zIndex value is rendered above contours with lower zIndex values. When visualizing overlapping contours, zIndex along with zOffset (defined below) can be used to precisely layout contours. This also avoids z-fighting rendering issues. If not specified a unique value from 0 to n (number of contours) is assigned.

NOTE: Like any other layer prop, a shallow comparison is performed on contours prop to determine if it is changed. This prop should be set to an array object, that changes only when contours need to be changed.

zOffset (number, optional)​

  • Default: 0.005

A very small z offset that is added for each vertex of a contour (Isoline or Isoband). This is needed to control the layout of contours, especially when rendering overlapping contours. Imagine a case where an Isoline is specified which is overlapped with an Isoband. To make sure the Isoline is visible we need to render this above the Isoband.

Data Accessors​

getPosition (Accessor<Position>, optional)​

  • Default: object => object.position

Method called to retrieve the position of each object.

getWeight (Accessor<number>, optional)​

  • Default: 1

The weight of each object.

  • If a number is provided, it is used as the weight for all objects.
  • If a function is provided, it is called on each object to retrieve its weight.

Sub Layers​

The ContourLayer renders the following sublayers:

Source​

modules/aggregation-layers/src/contour-layer