Skip to content

Latest commit

 

History

History
411 lines (288 loc) · 12.2 KB

cpu-grid-layer.md

File metadata and controls

411 lines (288 loc) · 12.2 KB
Raw

@deck.gl/aggregation-layers lighting

CPUGridLayer

The CPUGridLayer renders a grid heatmap based on an array of points. It takes the constant cell size, aggregates input points into cells. Aggregation is performed on CPU. The color and height of the cell is scaled by number of points it contains.

CPUGridLayer is one of the sublayers for GridLayer, and is provided to customize CPU Aggregation for advanced use cases. For any regular use case, GridLayer is recommended.

CPUGridLayer is a CompositeLayer.

import DeckGL from '@deck.gl/react';
import {CPUGridLayer} from '@deck.gl/aggregation-layers';

const App = ({data, viewport}) => {

  /**
   * Data format:
   * [
   *   {COORDINATES: [-122.42177834, 37.78346622]},
   *   ...
   * ]
   */
  const layer = new CPUGridLayer({
    id: 'grid-layer',
    data,
    pickable: true,
    extruded: true,
    cellSize: 200,
    elevationScale: 4,
    getPosition: d => d.COORDINATES,
    onHover: ({object, x, y}) => {
      const tooltip = `${object.position.join(', ')}\nCount: ${object.count}`;
      /* Update tooltip
         http://deck.gl/#/documentation/developer-guide/adding-interactivity?section=example-display-a-tooltip-for-hovered-object
      */
    }
  });

  return (<DeckGL {...viewport} layers={[layer]} />);
};

Note: The CPUGridLayer at the moment only works with COORDINATE_SYSTEM.LNGLAT.

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 {CPUGridLayer} from '@deck.gl/aggregation-layers';
new CPUGridLayer({});

To use pre-bundled scripts:

<script src="https://unpkg.com/deck.gl@~7.0.0/dist.min.js"></script>
<!-- or -->
<script src="https://unpkg.com/@deck.gl/core@~7.0.0/dist.min.js"></script>
<script src="https://unpkg.com/@deck.gl/layers@~7.0.0/dist.min.js"></script>
<script src="https://unpkg.com/@deck.gl/aggregation-layers@~7.0.0/dist.min.js"></script>
new deck.CPUGridLayer({});

Properties

Inherits from all Base Layer and CompositeLayer properties.

Render Options

cellSize (Number, optional)
  • Default: 1000

Size of each cell in meters

colorDomain (Array, optional)
  • Default: [min(count), max(count)]

Color scale domain, default is set to the range of point counts in each cell.

colorRange (Array, optional)
  • Default:

Specified as an array of 6 colors [color1, color2, ... color6]. Each color is an array of 3 or 4 values [R, G, B] or [R, G, B, A], representing intensities of Red, Green, Blue and Alpha channels. Each intensity is a value between 0 and 255. When Alpha not provided a value of 255 is used. By default colorRange is set to colorbrewer 6-class YlOrRd.

coverage (Number, optional)
  • Default: 1

Cell size multiplier, clamped between 0 - 1. The final size of cell is calculated by coverage * cellSize. Note: coverage does not affect how points are binned. Coverage are linear based.

elevationDomain (Array, optional)
  • Default: [0, max(count)]

Elevation scale input domain, default is set to the extent of point counts in each cell.

elevationRange (Array, optional)
  • Default: [0, 1000]

Elevation scale output range

elevationScale (Number, optional)
  • Default: 1

Cell elevation multiplier. The elevation of cell is calculated by elevationScale * getElevation(d). elevationScale is a handy property to scale all cells without updating the data.

extruded (Boolean, optional)
  • Default: true

Whether to enable cell elevation. Cell elevation scale by count of points in each cell. If set to false, all cell will be flat.

upperPercentile (Number, optional)
  • Default: 100

Filter cells and re-calculate color by upperPercentile. Cells with value larger than the upperPercentile will be hidden.

lowerPercentile (Number, optional)
  • Default: 0

Filter cells and re-calculate color by lowerPercentile. Cells with value smaller than the lowerPercentile will be hidden.

elevationUpperPercentile (Number, optional)
  • Default: 100

Filter cells and re-calculate elevation by elevationUpperPercentile. Cells with elevation value larger than the elevationUpperPercentile will be hidden.

elevationLowerPercentile (Number, optional)
  • Default: 100

Filter cells and re-calculate elevation by elevationLowerPercentile. Cells with elevation value smaller than the elevationLowerPercentile will be hidden.

material (Object, optional)
  • Default: new PhongMaterial()

This is an object that contains material props for lighting effect applied on extruded polygons. Check PhongMaterial for more details.

Data Accessors

getPosition (Function, optional)
  • Default: object => object.position

Method called to retrieve the position of each point.

getColorValue (Function, optional) transition-enabled
  • Default: points => points.length

getColorValue is the accessor function to get the value that cell color is based on. It takes an array of points inside each cell as arguments, returns a number. For example, You can pass in getColorValue to color the cells by avg/mean/max of a specific attributes of each point. By default getColorValue returns the length of the points array.

Note: grid layer compares whether getColorValue has changed to recalculate the value for each bin that its color based on. You should pass in the function defined outside the render function so it doesn't create a new function on every rendering pass.

 class MyGridLayer {
    getColorValue (points) {
        return points.length;
    }

    renderLayers() {
      return new CPUGridLayer({
        id: 'grid-layer',
        getColorValue: this.getColorValue // instead of getColorValue: (points) => { return points.length; }
        data,
        cellSize: 500
      });
    }
 }
getColorWeight (Function, optional) transition-enabled
  • Default: point => 1

getColorWeight is the accessor function to get the weight of a point used to calculate the color value for a cell.

colorAggregation (String, optional)
  • Default: 'SUM'

colorAggregation defines, operation used to aggregate all data point weights to calculate a cell's color value. Valid values are 'SUM', 'MEAN', 'MIN' and 'MAX'. 'SUM' is used when an invalid value is provided.

Note: getColorWeight and colorAggregation together define how color value of cell is determined, same can be done by setting getColorValue prop. But to enable GPU aggregation, former props must be provided instead of later.

Example1 : Using count of data elements that fall into a cell to encode the its color
  • Using getColorValue
function getCount(points) {
  return points.length;
}
...
const layer = new CPUGridLayer({
  id: 'my-grid-layer',
  ...
  getColorValue: getCount,
  ...
});
  • Using getColorWeight and colorAggregation
function getWeight(point) {
  return 1;
}
...
const layer = new CPUGridLayer({
  id: 'my-grid-layer',
  ...
  getColorWeight: getWeight,
  colorAggregation: 'SUM'
  ...
});
Example2 : Using mean value of 'SPACES' field of data elements to encode the color of the cell
  • Using getColorValue
function getMean(points) {
  return points.reduce((sum, p) => sum += p.SPACES, 0) / points.length;
}
...
const layer = new CPUGridLayer({
  id: 'my-grid-layer',
  ...
  getColorValue: getMean,
  ...
});
  • Using getColorWeight and colorAggregation
function getWeight(point) {
  return point.SPACES;
}
...
const layer = new CPUGridLayer({
  id: 'my-grid-layer',
  ...
  getColorWeight: getWeight,
  colorAggregation: 'SUM'
  ...
});

If your use case requires aggregating using an operation that is not one of 'SUM', 'MEAN', 'MAX' and 'MIN', getColorValue should be used to define such custom aggregation function. In those cases GPU aggregation is not supported.

getElevationValue (Function, optional) transition-enabled
  • Default: points => points.length

Similar to getColorValue, getElevationValue is the accessor function to get the value that cell elevation is based on. It takes an array of points inside each cell as arguments, returns a number. By default getElevationValue returns the length of the points array.

Note: grid layer compares whether getElevationValue has changed to recalculate the value for each cell for its elevation. You should pass in the function defined outside the render function so it doesn't create a new function on every rendering pass.

getElevationWeight (Function, optional) transition-enabled
  • Default: point => 1

getElevationWeight is the accessor function to get the weight of a point used to calcuate the elevation value for a cell.

elevationAggregation (String, optional)
  • Default: 'SUM'

elevationAggregation defines, operation used to aggregate all data point weights to calculate a cell's elevation value. Valid values are 'SUM', 'MEAN', 'MIN' and 'MAX'. 'SUM' is used when an invalid value is provided.

Note: getElevationWeight and elevationAggregation together define how elevation value of cell is determined, same can be done by setting getColorValue prop. But to enable GPU aggregation, former props must be provided instead of later.

Example1 : Using count of data elements that fall into a cell to encode the its elevation
  • Using getElevationValue
function getCount(points) {
  return points.length;
}
...
const layer = new CPUGridLayer({
  id: 'my-grid-layer',
  ...
  getElevationValue: getCount,
  ...
});
  • Using getElevationWeight and elevationAggregation
function getWeight(point) {
  return 1;
}
...
const layer = new CPUGridLayer({
  id: 'my-grid-layer',
  ...
  getElevationWeight: getWeight,
  elevationAggregation: 'SUM'
  ...
});
Example2 : Using maximum value of 'SPACES' field of data elements to encode the elevation of the cell
  • Using getElevationValue
function getMax(points) {
  return points.reduce((max, p) => p.SPACES > max ? p.SPACES : max, -Infinity);
}
...
const layer = new CPUGridLayer({
  id: 'my-grid-layer',
  ...
  getElevationValue: getMax,
  ...
});
  • Using getElevationWeight and elevationAggregation
function getWeight(point) {
  return point.SPACES;
}
...
const layer = new CPUGridLayer({
  id: 'my-grid-layer',
  ...
  getElevationWeight: getWeight,
  elevationAggregation: 'MAX'
  ...
});

If your use case requires aggregating using an operation that is not one of 'SUM', 'MEAN', 'MAX' and 'MIN', getElevationValue should be used to define such custom aggregation function. In those cases GPU aggregation is not supported.

onSetColorDomain (Function, optional)
  • Default: () => {}

This callback will be called when bin color domain has been calculated.

onSetElevationDomain (Function, optional)
  • Default: () => {}

This callback will be called when bin elevation domain has been calculated.

Sub Layers

The CPUGridLayer renders the following sublayers:

Source

modules/aggregation-layers/src/cpu-grid-layer