@deck.gl/aggregation-layers 8.8.0-alpha.6 → 8.8.0-beta.3

package/src/cpu-grid-layer/cpu-grid-layer.ts

@@ -0,0 +1,324 @@
+// Copyright (c) 2015 - 2017 Uber Technologies, Inc.
+//
+// Permission is hereby granted, free of charge, to any person obtaining a copy
+// of this software and associated documentation files (the "Software"), to deal
+// in the Software without restriction, including without limitation the rights
+// to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+// copies of the Software, and to permit persons to whom the Software is
+// furnished to do so, subject to the following conditions:
+//
+// The above copyright notice and this permission notice shall be included in
+// all copies or substantial portions of the Software.
+//
+// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+// OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+// THE SOFTWARE.
+
+import GL from '@luma.gl/constants';
+import {GridCellLayer} from '@deck.gl/layers';
+import {Accessor, AccessorFunction, Color, Position, Material, DefaultProps} from '@deck.gl/core';
+
+import {defaultColorRange} from '../utils/color-utils';
+import {pointToDensityGridDataCPU} from './grid-aggregator';
+import CPUAggregator from '../utils/cpu-aggregator';
+import AggregationLayer, {AggregationLayerProps} from '../aggregation-layer';
+
+import Layer, {UpdateParameters} from 'modules/core/src/lib/layer';
+import {GetPickingInfoParams, PickingInfo} from 'modules/core/src/lib/picking/pick-info';
+import {AggregateAccessor} from '../types';
+
+// eslint-disable-next-line @typescript-eslint/no-empty-function
+function nop() {}
+
+const defaultProps: DefaultProps<CPUGridLayerProps> = {
+  // color
+  colorDomain: null,
+  colorRange: defaultColorRange,
+  getColorValue: {type: 'accessor', value: null}, // default value is calculated from `getColorWeight` and `colorAggregation`
+  getColorWeight: {type: 'accessor', value: 1},
+  colorAggregation: 'SUM',
+  lowerPercentile: {type: 'number', min: 0, max: 100, value: 0},
+  upperPercentile: {type: 'number', min: 0, max: 100, value: 100},
+  colorScaleType: 'quantize',
+  onSetColorDomain: nop,
+
+  // elevation
+  elevationDomain: null,
+  elevationRange: [0, 1000],
+  getElevationValue: {type: 'accessor', value: null}, // default value is calculated from `getElevationWeight` and `elevationAggregation`
+  getElevationWeight: {type: 'accessor', value: 1},
+  elevationAggregation: 'SUM',
+  elevationLowerPercentile: {type: 'number', min: 0, max: 100, value: 0},
+  elevationUpperPercentile: {type: 'number', min: 0, max: 100, value: 100},
+  elevationScale: {type: 'number', min: 0, value: 1},
+  elevationScaleType: 'linear',
+  onSetElevationDomain: nop,
+
+  gridAggregator: pointToDensityGridDataCPU,
+
+  // grid
+  cellSize: {type: 'number', min: 0, max: 1000, value: 1000},
+  coverage: {type: 'number', min: 0, max: 1, value: 1},
+  getPosition: {type: 'accessor', value: x => x.position},
+  extruded: false,
+
+  // Optional material for 'lighting' shader module
+  material: true,
+
+  // data filter
+  _filterData: {type: 'function', value: null, optional: true}
+};
+
+/** All properties supported by CPUGridLayer. */
+export type CPUGridLayerProps<DataT = any> = _CPUGridLayerProps<DataT> &
+  AggregationLayerProps<DataT>;
+
+/** Properties added by CPUGridLayer. */
+export type _CPUGridLayerProps<DataT> = {
+  /**
+   * Size of each cell in meters.
+   * @default 1000
+   */
+  cellSize?: number;
+
+  /**
+   * Color scale domain, default is set to the extent of aggregated weights in each cell.
+   * @default [min(colorWeight), max(colorWeight)]
+   */
+  colorDomain?: [number, number] | null;
+
+  /**
+   * Default: [colorbrewer](http://colorbrewer2.org/#type=sequential&scheme=YlOrRd&n=6) `6-class YlOrRd`
+   */
+  colorRange?: Color[];
+
+  /**
+   * Cell size multiplier, clamped between 0 - 1.
+   * @default 1
+   */
+  coverage?: number;
+
+  /**
+   * Elevation scale input domain, default is set to between 0 and the max of aggregated weights in each cell.
+   * @default [0, max(elevationWeight)]
+   */
+  elevationDomain?: [number, number] | null;
+
+  /**
+   * Elevation scale output range.
+   * @default [0, 1000]
+   */
+  elevationRange?: [number, number];
+
+  /**
+   * Cell elevation multiplier.
+   * @default 1
+   */
+  elevationScale?: number;
+
+  /**
+   * Whether to enable cell elevation. If set to false, all cell will be flat.
+   * @default true
+   */
+  extruded?: boolean;
+
+  /**
+   * Filter cells and re-calculate color by `upperPercentile`.
+   * Cells with value arger than the upperPercentile will be hidden.
+   * @default 100
+   */
+  upperPercentile?: number;
+
+  /**
+   * Filter cells and re-calculate color by `lowerPercentile`.
+   * Cells with value smaller than the lowerPercentile will be hidden.
+   * @default 0
+   */
+  lowerPercentile?: number;
+
+  /**
+   * Filter cells and re-calculate elevation by `elevationUpperPercentile`.
+   * Cells with elevation value larger than the `elevationUpperPercentile` will be hidden.
+   * @default 100
+   */
+  elevationUpperPercentile?: number;
+
+  /**
+   * Filter cells and re-calculate elevation by `elevationLowerPercentile`.
+   * Cells with elevation value larger than the `elevationLowerPercentile` will be hidden.
+   * @default 0
+   */
+  elevationLowerPercentile?: number;
+
+  /**
+   * Scaling function used to determine the color of the grid cell, default value is 'quantize'.
+   * Supported Values are 'quantize', 'linear', 'quantile' and 'ordinal'.
+   * @default 'quantize'
+   */
+  colorScaleType?: 'quantize' | 'linear' | 'quantile' | 'ordinal';
+
+  /**
+   * Scaling function used to determine the elevation of the grid cell, only supports 'linear'.
+   */
+  elevationScaleType?: 'linear';
+
+  // TODO - document
+  gridAggregator?: (props: any, params: any) => any;
+
+  /**
+   * Material settings for lighting effect. Applies if `extruded: true`.
+   *
+   * @default true
+   * @see https://deck.gl/docs/developer-guide/using-lighting
+   */
+  material?: Material;
+
+  /**
+   * Defines the operation used to aggregate all data object weights to calculate a cell's color value.
+   * @default 'SUM'
+   */
+  colorAggregation?: 'SUM' | 'MEAN' | 'MIN' | 'MAX';
+
+  /**
+   * Defines the operation used to aggregate all data object weights to calculate a cell's elevation value.
+   * @default 'SUM'
+   */
+  elevationAggregation?: 'SUM' | 'MEAN' | 'MIN' | 'MAX';
+
+  /**
+   * Method called to retrieve the position of each object.
+   * @default object => object.position
+   */
+  getPosition?: AccessorFunction<DataT, Position>;
+
+  /**
+   * The weight of a data object used to calculate the color value for a cell.
+   * @default 1
+   */
+  getColorWeight?: Accessor<DataT, number>;
+
+  /**
+   * After data objects are aggregated into cells, this accessor is called on each cell to get the value that its color is based on.
+   * @default null
+   */
+  getColorValue?: AggregateAccessor<DataT> | null;
+
+  /**
+   * The weight of a data object used to calculate the elevation value for a cell.
+   * @default 1
+   */
+  getElevationWeight?: Accessor<DataT, number>;
+
+  /**
+   * After data objects are aggregated into cells, this accessor is called on each cell to get the value that its elevation is based on.
+   * @default null
+   */
+  getElevationValue?: AggregateAccessor<DataT> | null;
+
+  /**
+   * This callback will be called when bin color domain has been calculated.
+   * @default () => {}
+   */
+  onSetColorDomain?: (minMax: [number, number]) => void;
+
+  /**
+   * This callback will be called when bin elevation domain has been calculated.
+   * @default () => {}
+   */
+  onSetElevationDomain?: (minMax: [number, number]) => void;
+
+  /**
+   * (Experimental) Filter data objects
+   */
+  _filterData: null | ((d: DataT) => boolean);
+};
+
+export default class CPUGridLayer<DataT = any, ExtraPropsT = {}> extends AggregationLayer<
+  ExtraPropsT & Required<_CPUGridLayerProps<DataT>>
+> {
+  static layerName = 'CPUGridLayer';
+  static defaultProps = defaultProps;
+
+  initializeState(): void {
+    const cpuAggregator = new CPUAggregator({
+      getAggregator: props => props.gridAggregator,
+      getCellSize: props => props.cellSize
+    });
+
+    this.state = {
+      cpuAggregator,
+      aggregatorState: cpuAggregator.state
+    };
+    const attributeManager = this.getAttributeManager()!;
+    attributeManager.add({
+      positions: {size: 3, type: GL.DOUBLE, accessor: 'getPosition'}
+    });
+    // color and elevation attributes can't be added as attributes
+    // they are calcualted using 'getValue' accessor that takes an array of pints.
+  }
+
+  updateState(opts: UpdateParameters<this>) {
+    super.updateState(opts);
+    this.setState({
+      // make a copy of the internal state of cpuAggregator for testing
+      aggregatorState: this.state.cpuAggregator.updateState(opts, {
+        viewport: this.context.viewport,
+        attributes: this.getAttributes(),
+        numInstances: this.getNumInstances()
+      })
+    });
+  }
+
+  getPickingInfo({info}: GetPickingInfoParams): PickingInfo {
+    return this.state.cpuAggregator.getPickingInfo({info});
+  }
+
+  // create a method for testing
+  _onGetSublayerColor(cell) {
+    return this.state.cpuAggregator.getAccessor('fillColor')(cell);
+  }
+
+  // create a method for testing
+  _onGetSublayerElevation(cell) {
+    return this.state.cpuAggregator.getAccessor('elevation')(cell);
+  }
+
+  _getSublayerUpdateTriggers() {
+    return this.state.cpuAggregator.getUpdateTriggers(this.props);
+  }
+
+  renderLayers(): Layer {
+    const {elevationScale, extruded, cellSize, coverage, material, transitions} = this.props;
+    const {cpuAggregator} = this.state;
+    const SubLayerClass = this.getSubLayerClass('grid-cell', GridCellLayer);
+    const updateTriggers = this._getSublayerUpdateTriggers();
+
+    return new SubLayerClass(
+      {
+        cellSize,
+        coverage,
+        material,
+        elevationScale,
+        extruded,
+
+        getFillColor: this._onGetSublayerColor.bind(this),
+        getElevation: this._onGetSublayerElevation.bind(this),
+        transitions: transitions && {
+          getFillColor: transitions.getColorValue || transitions.getColorWeight,
+          getElevation: transitions.getElevationValue || transitions.getElevationWeight
+        }
+      },
+      this.getSubLayerProps({
+        id: 'grid-cell',
+        updateTriggers
+      }),
+      {
+        data: cpuAggregator.state.layerData.data
+      }
+    );
+  }
+}

package/src/gpu-grid-layer/{gpu-grid-cell-layer.js → gpu-grid-cell-layer.ts}

@@ -18,19 +18,28 @@
 // OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
 // THE SOFTWARE.
 
-import {Layer, fp64LowPart, project32, gouraudLighting, picking} from '@deck.gl/core';
+import {
+  Layer,
+  fp64LowPart,
+  project32,
+  gouraudLighting,
+  picking,
+  LayerContext,
+  LayerProps,
+  DefaultProps
+} from '@deck.gl/core';
 import GL from '@luma.gl/constants';
-import {Model, CubeGeometry} from '@luma.gl/core';
+import {Model, CubeGeometry, Buffer} from '@luma.gl/core';
 import {fp64arithmetic} from '@luma.gl/shadertools';
 import {defaultColorRange, colorRangeToFlatArray} from '../utils/color-utils';
-
+import type {_GPUGridLayerProps} from './gpu-grid-layer';
 import vs from './gpu-grid-cell-layer-vertex.glsl';
 import fs from './gpu-grid-cell-layer-fragment.glsl';
 
 const COLOR_DATA_UBO_INDEX = 0;
 const ELEVATION_DATA_UBO_INDEX = 1;
 
-const defaultProps = {
+const defaultProps: DefaultProps<_GPUGridCellLayerProps & LayerProps> = {
   // color
   colorDomain: null,
   colorRange: defaultColorRange,
@@ -41,19 +50,31 @@ const defaultProps = {
   elevationScale: {type: 'number', min: 0, value: 1},
 
   // grid
-  gridSize: {type: 'array', min: 0, value: [1, 1]},
-  gridOrigin: {type: 'array', min: 0, value: [0, 0]},
-  gridOffset: {type: 'array', min: 0, value: [0, 0]},
+  gridSize: {type: 'array', value: [1, 1]},
+  gridOrigin: {type: 'array', value: [0, 0]},
+  gridOffset: {type: 'array', value: [0, 0]},
 
   cellSize: {type: 'number', min: 0, max: 1000, value: 1000},
-  offset: {type: 'array', min: 0, value: [1, 1]},
+  offset: {type: 'array', value: [1, 1]},
   coverage: {type: 'number', min: 0, max: 1, value: 1},
   extruded: true,
 
   material: true // Use lighting module defaults
 };
 
-export default class GPUGridCellLayer extends Layer {
+type _GPUGridCellLayerProps = _GPUGridLayerProps<any> & {
+  offset: number[];
+  gridSize: number[];
+  gridOrigin: number[];
+  gridOffset: number[];
+  colorMaxMinBuffer: Buffer;
+  elevationMaxMinBuffer: Buffer;
+};
+
+export default class GPUGridCellLayer extends Layer<_GPUGridCellLayerProps> {
+  static layerName = 'GPUGridCellLayer';
+  static defaultProps = defaultProps;
+
   getShaders() {
     return super.getShaders({
       vs,
@@ -62,9 +83,8 @@ export default class GPUGridCellLayer extends Layer {
     });
   }
 
-  initializeState() {
-    const {gl} = this.context;
-    const attributeManager = this.getAttributeManager();
+  initializeState({gl}: LayerContext) {
+    const attributeManager = this.getAttributeManager()!;
     attributeManager.addInstanced({
       colors: {
         size: 4,
@@ -80,7 +100,7 @@ export default class GPUGridCellLayer extends Layer {
     this.setState({model});
   }
 
-  _getModel(gl) {
+  _getModel(gl: WebGLRenderingContext): Model {
     return new Model(gl, {
       ...this.getShaders(),
       id: this.props.id,
@@ -142,7 +162,7 @@ export default class GPUGridCellLayer extends Layer {
 
   getDomainUniforms() {
     const {colorDomain, elevationDomain} = this.props;
-    const domainUniforms = {};
+    const domainUniforms: Record<string, any> = {};
     if (colorDomain !== null) {
       domainUniforms.colorDomainValid = true;
       domainUniforms.colorDomain = colorDomain;
@@ -158,8 +178,8 @@ export default class GPUGridCellLayer extends Layer {
     return domainUniforms;
   }
 
-  _setupUniformBuffer(model) {
-    const gl = this.context.gl;
+  private _setupUniformBuffer(model: Model): void {
+    const gl = this.context.gl as WebGL2RenderingContext;
     const programHandle = model.program.handle;
 
     const colorIndex = gl.getUniformBlockIndex(programHandle, 'ColorData');
@@ -168,6 +188,3 @@ export default class GPUGridCellLayer extends Layer {
     gl.uniformBlockBinding(programHandle, elevationIndex, ELEVATION_DATA_UBO_INDEX);
   }
 }
-
-GPUGridCellLayer.layerName = 'GPUGridCellLayer';
-GPUGridCellLayer.defaultProps = defaultProps;

package/src/gpu-grid-layer/{gpu-grid-layer.js → gpu-grid-layer.ts}

@@ -20,17 +20,28 @@
 
 import {Buffer} from '@luma.gl/core';
 import GL from '@luma.gl/constants';
-import {log} from '@deck.gl/core';
+import {
+  Accessor,
+  AccessorFunction,
+  Color,
+  Material,
+  GetPickingInfoParams,
+  LayerContext,
+  log,
+  PickingInfo,
+  Position,
+  DefaultProps
+} from '@deck.gl/core';
 
 import GPUGridAggregator from '../utils/gpu-grid-aggregation/gpu-grid-aggregator';
 import {AGGREGATION_OPERATION} from '../utils/aggregation-operation-utils';
 import {defaultColorRange, colorRangeToFlatArray} from '../utils/color-utils';
 import GPUGridCellLayer from './gpu-grid-cell-layer';
 import {pointToDensityGridDataCPU} from './../cpu-grid-layer/grid-aggregator';
-import GridAggregationLayer from '../grid-aggregation-layer';
+import GridAggregationLayer, {GridAggregationLayerProps} from '../grid-aggregation-layer';
 import {getBoundingBox, getGridParams} from '../utils/grid-aggregation-utils';
 
-const defaultProps = {
+const defaultProps: DefaultProps<GPUGridLayerProps> = {
   // color
   colorDomain: null,
   colorRange: defaultColorRange,
@@ -65,14 +76,113 @@ const DIMENSIONS = {
 };
 const POSITION_ATTRIBUTE_NAME = 'positions';
 
-export default class GPUGridLayer extends GridAggregationLayer {
-  initializeState() {
-    const {gl} = this.context;
+/** All properties supported by GPUGridLayer. */
+export type GPUGridLayerProps<DataT = any> = _GPUGridLayerProps<DataT> &
+  GridAggregationLayerProps<DataT>;
+
+/** Properties added by GPUGridLayer. */
+export type _GPUGridLayerProps<DataT> = {
+  /**
+   * Size of each cell in meters.
+   * @default 1000
+   */
+  cellSize?: number;
+
+  /**
+   * Color scale domain, default is set to the extent of aggregated weights in each cell.
+   * @default [min(colorWeight), max(colorWeight)]
+   */
+  colorDomain?: [number, number] | null;
+
+  /**
+   * Default: [colorbrewer](http://colorbrewer2.org/#type=sequential&scheme=YlOrRd&n=6) `6-class YlOrRd`
+   */
+  colorRange?: Color[];
+
+  /**
+   * Cell size multiplier, clamped between 0 - 1.
+   * @default 1
+   */
+  coverage?: number;
+
+  /**
+   * Elevation scale input domain, default is set to between 0 and the max of aggregated weights in each cell.
+   * @default [0, max(elevationWeight)]
+   */
+  elevationDomain?: [number, number] | null;
+
+  /**
+   * Elevation scale output range.
+   * @default [0, 1000]
+   */
+  elevationRange?: [number, number];
+
+  /**
+   * Cell elevation multiplier.
+   * @default 1
+   */
+  elevationScale?: number;
+
+  /**
+   * Whether to enable cell elevation. If set to false, all cell will be flat.
+   * @default true
+   */
+  extruded?: boolean;
+
+  /**
+   * Material settings for lighting effect. Applies if `extruded: true`.
+   *
+   * @default true
+   * @see https://deck.gl/docs/developer-guide/using-lighting
+   */
+  material?: Material;
+
+  /**
+   * Defines the operation used to aggregate all data object weights to calculate a cell's color value.
+   * @default 'SUM'
+   */
+  colorAggregation?: 'SUM' | 'MEAN' | 'MIN' | 'MAX';
+
+  /**
+   * Defines the operation used to aggregate all data object weights to calculate a cell's elevation value.
+   * @default 'SUM'
+   */
+  elevationAggregation?: 'SUM' | 'MEAN' | 'MIN' | 'MAX';
+
+  /**
+   * Method called to retrieve the position of each object.
+   * @default object => object.position
+   */
+  getPosition?: AccessorFunction<DataT, Position>;
+
+  /**
+   * The weight of a data object used to calculate the color value for a cell.
+   * @default 1
+   */
+  getColorWeight?: Accessor<DataT, number>;
+
+  /**
+   * The weight of a data object used to calculate the elevation value for a cell.
+   * @default 1
+   */
+  getElevationWeight?: Accessor<DataT, number>;
+};
+
+/**
+ * The `GPUGridLayer` renders a grid heatmap based on an array of inputs.
+ */
+export default class GPUGridLayer<DataT = any, ExtraPropsT = {}> extends GridAggregationLayer<
+  ExtraPropsT & Required<_GPUGridLayerProps<DataT>>
+> {
+  static layerName = 'GPUGridLayer';
+  static defaultProps = defaultProps;
+
+  initializeState({gl}: LayerContext): void {
     const isSupported = GPUGridAggregator.isSupported(gl);
     if (!isSupported) {
       log.error('GPUGridLayer is not supported on this browser, use GridLayer instead')();
     }
-    super.initializeState({
+    super.initializeAggregationLayer({
       dimensions: DIMENSIONS
     });
     this.setState({
@@ -101,7 +211,7 @@ export default class GPUGridLayer extends GridAggregationLayer {
       },
       positionAttributeName: 'positions'
     });
-    const attributeManager = this.getAttributeManager();
+    const attributeManager = this.getAttributeManager()!;
     attributeManager.add({
       [POSITION_ATTRIBUTE_NAME]: {
         size: 3,
@@ -129,7 +239,7 @@ export default class GPUGridLayer extends GridAggregationLayer {
     }
   }
 
-  getHashKeyForIndex(index) {
+  getHashKeyForIndex(index: number): string {
     const {numRow, numCol, boundingBox, gridOffset} = this.state;
     const gridSize = [numCol, numRow];
     const gridOrigin = [boundingBox.xMin, boundingBox.yMin];
@@ -147,7 +257,7 @@ export default class GPUGridLayer extends GridAggregationLayer {
     return `${latIdx}-${lonIdx}`;
   }
 
-  getPositionForIndex(index) {
+  getPositionForIndex(index: number): Position {
     const {numRow, numCol, boundingBox, gridOffset} = this.state;
     const gridSize = [numCol, numRow];
     const gridOrigin = [boundingBox.xMin, boundingBox.yMin];
@@ -160,9 +270,9 @@ export default class GPUGridLayer extends GridAggregationLayer {
     return [xPos, yPos];
   }
 
-  getPickingInfo({info, mode}) {
+  getPickingInfo({info, mode}: GetPickingInfoParams): PickingInfo {
     const {index} = info;
-    let object = null;
+    let object: any = null;
     if (index >= 0) {
       const {gpuGridAggregator} = this.state;
       const position = this.getPositionForIndex(index);
@@ -190,7 +300,7 @@ export default class GPUGridLayer extends GridAggregationLayer {
           const {gridOffset, translation, boundingBox} = this.state;
           const {viewport} = this.context;
           const attributes = this.getAttributes();
-          const cpuAggregation = pointToDensityGridDataCPU(props, {
+          const cpuAggregation = pointToDensityGridDataCPU(props as any, {
             gridOffset,
             attributes,
             viewport,
@@ -267,14 +377,14 @@ export default class GPUGridLayer extends GridAggregationLayer {
     );
   }
 
-  finalizeState() {
+  finalizeState(context: LayerContext) {
     const {color, elevation} = this.state.weights;
     [color, elevation].forEach(weight => {
       const {aggregationBuffer, maxMinBuffer} = weight;
       maxMinBuffer.delete();
       aggregationBuffer?.delete();
     });
-    super.finalizeState();
+    super.finalizeState(context);
   }
 
   // Aggregation Overrides
@@ -338,6 +448,3 @@ export default class GPUGridLayer extends GridAggregationLayer {
     elevation.operation = AGGREGATION_OPERATION[elevationAggregation];
   }
 }
-
-GPUGridLayer.layerName = 'GPUGridLayer';
-GPUGridLayer.defaultProps = defaultProps;