@deck.gl/aggregation-layers 8.8.0-alpha.4 → 8.8.0-beta.1

package/src/hexagon-layer/{hexagon-layer.js → hexagon-layer.ts}

@@ -18,17 +18,19 @@
 // OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
 // THE SOFTWARE.
 
-import {log} from '@deck.gl/core';
-import {ColumnLayer} from '@deck.gl/layers';
+import {Accessor, AccessorFunction, Color, log, Position, UpdateParameters} from '@deck.gl/core';
+import {ColumnLayer, _MaterialProps as MaterialProps} from '@deck.gl/layers';
 
 import {defaultColorRange} from '../utils/color-utils';
 
 import {pointToHexbin} from './hexagon-aggregator';
 import CPUAggregator from '../utils/cpu-aggregator';
-import AggregationLayer from '../aggregation-layer';
+import AggregationLayer, {AggregationLayerProps} from '../aggregation-layer';
 
 import GL from '@luma.gl/constants';
+import {AggregateAccessor} from '../types';
 
+// eslint-disable-next-line @typescript-eslint/no-empty-function
 function nop() {}
 
 const defaultProps = {
@@ -67,7 +69,173 @@ const defaultProps = {
   _filterData: {type: 'function', value: null, optional: true}
 };
 
-export default class HexagonLayer extends AggregationLayer {
+/** All properties supported by by HexagonLayer. */
+export type HexagonLayerProps<DataT = any> = _HexagonLayerProps<DataT> &
+  AggregationLayerProps<DataT>;
+
+/** Properties added by HexagonLayer. */
+type _HexagonLayerProps<DataT = any> = {
+  /**
+   * Radius of hexagon bin in meters. The hexagons are pointy-topped (rather than flat-topped).
+   * @default 1000
+   */
+  radius?: number;
+
+  /**
+   * Function to aggregate data into hexagonal bins.
+   * @default d3-hexbin
+   */
+  hexagonAggregator?: () => any;
+
+  /**
+   * Color scale input domain.
+   * @default [min(colorWeight), max(colorWeight)]
+   */
+  colorDomain?: number[];
+
+  /**
+   * Specified as an array of colors [color1, color2, ...].
+   * @default `6-class YlOrRd` - [colorbrewer](http://colorbrewer2.org/#type=sequential&scheme=YlOrRd&n=6)
+   */
+  colorRange?: Color[];
+
+  /**
+   * Hexagon radius multiplier, clamped between 0 - 1.
+   * @default 1
+   */
+  coverage?: number;
+
+  /**
+   * Elevation scale input domain. The elevation scale is a linear scale that maps number of counts to elevation.
+   * @default [0, max(elevationWeight)]
+   */
+  elevationDomain?: number[];
+
+  /**
+   * Elevation scale output range.
+   * @default [0, 1000]
+   */
+  elevationRange?: number[];
+
+  /**
+   * Hexagon elevation multiplier.
+   * @default 1
+   */
+  elevationScale?: number;
+
+  /**
+   * Whether to enable cell elevation. If set to false, all cell will be flat.
+   * @default false
+   */
+  extruded?: boolean;
+
+  /**
+   * Filter bins and re-calculate color by `upperPercentile`.
+   * Hexagons with color value larger than the `upperPercentile` will be hidden.
+   * @default 100
+   */
+  upperPercentile?: number;
+
+  /**
+   * Filter bins and re-calculate color by `lowerPercentile`.
+   * Hexagons with color value smaller than the `lowerPercentile` will be hidden.
+   * @default 0
+   */
+  lowerPercentile?: number;
+
+  /**
+   * Filter bins and re-calculate elevation by `elevationUpperPercentile`.
+   * Hexagons with elevation value larger than the `elevationUpperPercentile` will be hidden.
+   * @default 100
+   */
+  elevationUpperPercentile?: number;
+
+  /**
+   * Filter bins and re-calculate elevation by `elevationLowerPercentile`.
+   * Hexagons 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', 'quantile' and 'ordinal'.
+   * @default 'quantize'
+   */
+  colorScaleType?: 'quantize' | 'quantile' | 'ordinal';
+
+  /**
+   * This is an object that contains material props
+   * for [lighting effect](/docs/api-reference/core/lighting-effect.md) applied on extruded polygons.
+   * @default true
+   */
+  material?: MaterialProps | boolean;
+
+  /**
+   * 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 bin.
+   * @default 1
+   */
+  getColorWeight?: Accessor<DataT, number>;
+
+  /**
+   * After data objects are aggregated into bins, 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 bin.
+   * @default 1
+   */
+  getElevationWeight?: Accessor<DataT, number>;
+
+  /**
+   * After data objects are aggregated into bins, 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 cell color domain has been calculated.
+   * @default () => {}
+   */
+  onSetColorDomain?: (minMax: [number, number]) => void;
+
+  /**
+   * This callback will be called when cell elevation domain has been calculated.
+   * @default () => {}
+   */
+  onSetElevationDomain?: (minMax: [number, number]) => void;
+};
+
+export default class HexagonLayer<ExtraPropsT = {}> extends AggregationLayer<
+  ExtraPropsT & Required<_HexagonLayerProps>
+> {
+  static layerName = 'HexagonLayer';
+  static defaultProps = defaultProps;
+
+  state!: AggregationLayer['state'] & {
+    cpuAggregator: CPUAggregator;
+    aggregatorState: any;
+  };
   initializeState() {
     const cpuAggregator = new CPUAggregator({
       getAggregator: props => props.hexagonAggregator,
@@ -79,7 +247,7 @@ export default class HexagonLayer extends AggregationLayer {
       aggregatorState: cpuAggregator.state,
       vertices: null
     };
-    const attributeManager = this.getAttributeManager();
+    const attributeManager = this.getAttributeManager()!;
     attributeManager.add({
       positions: {size: 3, type: GL.DOUBLE, accessor: 'getPosition'}
     });
@@ -87,7 +255,7 @@ export default class HexagonLayer extends AggregationLayer {
     // they are calculated using 'getValue' accessor that takes an array of pints.
   }
 
-  updateState(opts) {
+  updateState(opts: UpdateParameters<this>) {
     super.updateState(opts);
 
     if (opts.changeFlags.propsOrDataChanged) {
@@ -199,6 +367,3 @@ export default class HexagonLayer extends AggregationLayer {
     );
   }
 }
-
-HexagonLayer.layerName = 'HexagonLayer';
-HexagonLayer.defaultProps = defaultProps;

package/src/index.ts

@@ -33,3 +33,12 @@ export {default as _GPUGridAggregator} from './utils/gpu-grid-aggregation/gpu-gr
 export {default as _CPUAggregator} from './utils/cpu-aggregator';
 export {default as _AggregationLayer} from './aggregation-layer';
 export {default as _BinSorter} from './utils/bin-sorter';
+
+// types
+export type {ContourLayerProps} from './contour-layer/contour-layer';
+export type {HeatmapLayerProps} from './heatmap-layer/heatmap-layer';
+export type {HexagonLayerProps} from './hexagon-layer/hexagon-layer';
+export type {CPUGridLayerProps} from './cpu-grid-layer/cpu-grid-layer';
+export type {GridLayerProps} from './grid-layer/grid-layer';
+export type {GPUGridLayerProps} from './gpu-grid-layer/gpu-grid-layer';
+export type {ScreenGridLayerProps} from './screen-grid-layer/screen-grid-layer';

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

@@ -19,15 +19,16 @@
 // THE SOFTWARE.
 
 import GL from '@luma.gl/constants';
-import {Model, Geometry, FEATURES, hasFeatures} from '@luma.gl/core';
-import {Layer, log, picking} from '@deck.gl/core';
+import {Model, Geometry, FEATURES, hasFeatures, Texture2D} from '@luma.gl/core';
+import {Layer, LayerProps, log, picking, UpdateParameters} from '@deck.gl/core';
 import {defaultColorRange, colorRangeToFlatArray} from '../utils/color-utils';
 import vs from './screen-grid-layer-vertex.glsl';
 import fs from './screen-grid-layer-fragment.glsl';
+import type {_ScreenGridLayerProps} from './screen-grid-layer';
 
 const DEFAULT_MINCOLOR = [0, 0, 0, 0];
 const DEFAULT_MAXCOLOR = [0, 255, 0, 255];
-const COLOR_PROPS = [`minColor`, `maxColor`, `colorRange`, `colorDomain`];
+const COLOR_PROPS = ['minColor', 'maxColor', 'colorRange', 'colorDomain'];
 
 const defaultProps = {
   cellSizePixels: {value: 100, min: 1},
@@ -37,19 +38,36 @@ const defaultProps = {
   colorRange: defaultColorRange
 };
 
-export default class ScreenGridCellLayer extends Layer {
+/** All properties supported by ScreenGridCellLayer. */
+export type ScreenGridCellLayerProps<DataT> = _ScreenGridCellLayerProps<DataT> & LayerProps<DataT>;
+
+/** Proprties added by ScreenGridCellLayer. */
+export type _ScreenGridCellLayerProps<DataT> = _ScreenGridLayerProps<DataT> & {
+  maxTexture: Texture2D;
+};
+
+export default class ScreenGridCellLayer<DataT = any, ExtraPropsT = {}> extends Layer<
+  ExtraPropsT & Required<_ScreenGridCellLayerProps<DataT>>
+> {
+  static layerName = 'ScreenGridCellLayer';
+  static defaultProps = defaultProps;
+
   static isSupported(gl) {
     return hasFeatures(gl, [FEATURES.TEXTURE_FLOAT]);
   }
 
+  state!: Layer['state'] & {
+    model: Model;
+  };
   getShaders() {
     return {vs, fs, modules: [picking]};
   }
 
   initializeState() {
     const {gl} = this.context;
-    const attributeManager = this.getAttributeManager();
+    const attributeManager = this.getAttributeManager()!;
     attributeManager.addInstanced({
+      // eslint-disable-next-line @typescript-eslint/unbound-method
       instancePositions: {size: 3, update: this.calculateInstancePositions},
       instanceCounts: {size: 4, noAlloc: true}
     });
@@ -63,10 +81,12 @@ export default class ScreenGridCellLayer extends Layer {
     return changeFlags.somethingChanged;
   }
 
-  updateState({oldProps, props, changeFlags}) {
-    super.updateState({oldProps, props, changeFlags});
+  updateState(params: UpdateParameters<this>) {
+    super.updateState(params);
+
+    const {oldProps, props, changeFlags} = params;
 
-    const attributeManager = this.getAttributeManager();
+    const attributeManager = this.getAttributeManager()!;
     if (props.numInstances !== oldProps.numInstances) {
       attributeManager.invalidateAll();
     } else if (oldProps.cellSizePixels !== props.cellSizePixels) {
@@ -120,7 +140,7 @@ export default class ScreenGridCellLayer extends Layer {
 
   // Private Methods
 
-  _getModel(gl) {
+  _getModel(gl: WebGLRenderingContext): Model {
     return new Model(gl, {
       ...this.getShaders(),
       id: this.props.id,
@@ -134,7 +154,7 @@ export default class ScreenGridCellLayer extends Layer {
     });
   }
 
-  _shouldUseMinMax() {
+  _shouldUseMinMax(): boolean {
     const {minColor, maxColor, colorDomain, colorRange} = this.props;
     if (minColor || maxColor) {
       log.deprecated('ScreenGridLayer props: minColor and maxColor', 'colorRange, colorDomain')();
@@ -149,7 +169,7 @@ export default class ScreenGridCellLayer extends Layer {
     return true;
   }
 
-  _updateUniforms(oldProps, props, changeFlags) {
+  _updateUniforms(oldProps, props, changeFlags): void {
     const {model} = this.state;
     if (COLOR_PROPS.some(key => oldProps[key] !== props[key])) {
       model.setUniforms({shouldUseMinMax: this._shouldUseMinMax()});
@@ -177,6 +197,3 @@ export default class ScreenGridCellLayer extends Layer {
     }
   }
 }
-
-ScreenGridCellLayer.layerName = 'ScreenGridCellLayer';
-ScreenGridCellLayer.defaultProps = defaultProps;

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

@@ -18,12 +18,24 @@
 // OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
 // THE SOFTWARE.
 
-import {log} from '@deck.gl/core';
+import {
+  Accessor,
+  Color,
+  GetPickingInfoParams,
+  Layer,
+  LayerContext,
+  LayersList,
+  log,
+  PickingInfo,
+  Position,
+  UpdateParameters
+} from '@deck.gl/core';
 import GL from '@luma.gl/constants';
+import type {Texture2D} from '@luma.gl/core';
 import GPUGridAggregator from '../utils/gpu-grid-aggregation/gpu-grid-aggregator';
 import {AGGREGATION_OPERATION, getValueFunc} from '../utils/aggregation-operation-utils';
 import ScreenGridCellLayer from './screen-grid-cell-layer';
-import GridAggregationLayer from '../grid-aggregation-layer';
+import GridAggregationLayer, {GridAggregationLayerProps} from '../grid-aggregation-layer';
 import {getFloatTexture} from '../utils/resource-utils.js';
 
 const defaultProps = {
@@ -46,7 +58,99 @@ const DIMENSIONS = {
   }
 };
 
-export default class ScreenGridLayer extends GridAggregationLayer {
+/** All properties supported by ScreenGridLayer. */
+export type ScreenGridLayerProps<DataT> = _ScreenGridLayerProps<DataT> &
+  GridAggregationLayerProps<DataT>;
+
+/** Properties added by ScreenGridLayer. */
+export type _ScreenGridLayerProps<DataT = any> = {
+  /**
+   * Unit width/height of the bins.
+   * @default 100
+   */
+  cellSizePixels?: number;
+
+  /**
+   * Cell margin size in pixels.
+   * @default 2
+   */
+  cellMarginPixels?: number;
+
+  /**
+   * Expressed as an rgba array, minimal color that could be rendered by a tile.
+   * @default [0, 0, 0, 255]
+   * @deprecated Deprecated in version 5.2.0, use `colorRange` and `colorDomain` instead.
+   */
+  minColor?: Color | null;
+
+  /**
+   * Expressed as an rgba array, maximal color that could be rendered by a tile.
+   * @default [0, 255, 0, 255]
+   * @deprecated Deprecated in version 5.2.0, use `colorRange` and `colorDomain` instead.
+   */
+  maxColor?: Color | null;
+
+  /**
+   * Color scale input domain. The color scale maps continues numeric domain into discrete color range.
+   * @default [1, max(weight)]
+   */
+  colorDomain?: [number, number] | null;
+
+  /**
+   * Specified as an array of colors [color1, color2, ...].
+   *
+   * @default `6-class YlOrRd` - [colorbrewer](http://colorbrewer2.org/#type=sequential&scheme=YlOrRd&n=6)
+   */
+  colorRange?: Color[];
+
+  /**
+   * Method called to retrieve the position of each object.
+   *
+   * @default d => d.position
+   */
+  getPosition?: Accessor<DataT, Position>;
+
+  /**
+   * The weight of each object.
+   *
+   * @default 1
+   */
+  getWeight?: Accessor<DataT, number>;
+
+  /**
+   * Perform aggregation is performed on GPU.
+   *
+   * NOTE: GPU Aggregation requires WebGL2 support by the browser.
+   * When `gpuAggregation` is set to true and browser doesn't support WebGL2, aggregation falls back to CPU.
+   *
+   * @default true
+   */
+  gpuAggregation?: boolean;
+
+  /**
+   * Defines the type of aggregation operation
+   *
+   * V valid values are 'SUM', 'MEAN', 'MIN' and 'MAX'.
+   *
+   * @default 'SUM'
+   */
+  aggregation?: 'SUM' | 'MEAN' | 'MIN' | 'MAX';
+};
+
+export default class ScreenGridLayer<DataT = any, ExtraProps = {}> extends GridAggregationLayer<
+  ExtraProps & Required<_ScreenGridLayerProps<DataT>>
+> {
+  static layerName = 'ScreenGridLayer';
+  static defaultProps = defaultProps;
+
+  state!: GridAggregationLayer['state'] & {
+    supported: boolean;
+    gpuGridAggregator?: any;
+    gpuAggregation?: any;
+    weights?: any;
+    maxTexture?: Texture2D;
+  };
+
   initializeState() {
     const {gl} = this.context;
     if (!ScreenGridCellLayer.isSupported(gl)) {
@@ -55,9 +159,10 @@ export default class ScreenGridLayer extends GridAggregationLayer {
       log.error(`ScreenGridLayer: ${this.id} is not supported on this browser`)();
       return;
     }
-    super.initializeState({
+    super.initializeAggregationLayer({
       dimensions: DIMENSIONS,
-      getCellSize: props => props.cellSizePixels
+      // @ts-expect-error
+      getCellSize: props => props.cellSizePixels // TODO
     });
     const weights = {
       count: {
@@ -77,7 +182,7 @@ export default class ScreenGridLayer extends GridAggregationLayer {
       posOffset: [0, 0],
       translation: [1, -1]
     });
-    const attributeManager = this.getAttributeManager();
+    const attributeManager = this.getAttributeManager()!;
     attributeManager.add({
       [POSITION_ATTRIBUTE_NAME]: {
         size: 3,
@@ -90,15 +195,15 @@ export default class ScreenGridLayer extends GridAggregationLayer {
     });
   }
 
-  shouldUpdateState({changeFlags}) {
+  shouldUpdateState({changeFlags}: UpdateParameters<this>) {
     return this.state.supported && changeFlags.somethingChanged;
   }
 
-  updateState(opts) {
+  updateState(opts: UpdateParameters<this>) {
     super.updateState(opts);
   }
 
-  renderLayers() {
+  renderLayers(): LayersList | Layer {
     if (!this.state.supported) {
       return [];
     }
@@ -121,8 +226,8 @@ export default class ScreenGridLayer extends GridAggregationLayer {
     );
   }
 
-  finalizeState() {
-    super.finalizeState();
+  finalizeState(context: LayerContext): void {
+    super.finalizeState(context);
 
     const {aggregationBuffer, maxBuffer, maxTexture} = this.state;
 
@@ -131,7 +236,7 @@ export default class ScreenGridLayer extends GridAggregationLayer {
     maxTexture?.delete();
   }
 
-  getPickingInfo({info, mode}) {
+  getPickingInfo({info}: GetPickingInfoParams): PickingInfo {
     const {index} = info;
     if (index >= 0) {
       const {gpuGridAggregator, gpuAggregation, weights} = this.state;
@@ -244,6 +349,3 @@ export default class ScreenGridLayer extends GridAggregationLayer {
     }
   }
 }
-
-ScreenGridLayer.layerName = 'ScreenGridLayer';
-ScreenGridLayer.defaultProps = defaultProps;

package/src/types.ts

@@ -0,0 +1,10 @@
+export type AggregateAccessor<DataT = any> = {
+  /** a list of objects whose positions fall inside this cell. */
+  objects: DataT[];
+  objectInfo: {
+    /** the indices of `objects` in the original data. */
+    indices: number[];
+    /** the value of the `data` prop */
+    data: any;
+  };
+};

package/src/utils/{bin-sorter.js → bin-sorter.ts}

@@ -43,8 +43,23 @@ const defaultProps = {
   filterData: null
 };
 
+export type AggregatedBin = {
+  i: number;
+  value: any;
+  counts: number;
+};
+
 export default class BinSorter {
-  constructor(bins = [], props = defaultProps) {
+  maxCount!: number;
+  maxValue!: number;
+  minValue!: number;
+  totalCount!: number;
+
+  aggregatedBins: AggregatedBin[];
+  sortedBins!: AggregatedBin[];
+  binMap: Record<number, AggregatedBin>;
+
+  constructor(bins = [], props: Partial<typeof defaultProps> = defaultProps) {
     this.aggregatedBins = this.getAggregatedBins(bins, props);
     this._updateMinMaxValues();
     this.binMap = this.getBinMap();
@@ -57,7 +72,7 @@ export default class BinSorter {
    * @param {Function} getValue
    * @return {Array} array of values and index lookup
    */
-  getAggregatedBins(bins, props) {
+  getAggregatedBins(bins, props): AggregatedBin[] {
     const {
       getValue = defaultGetValue,
       getPoints = defaultGetPoints,
@@ -67,7 +82,7 @@ export default class BinSorter {
 
     const hasFilter = typeof filterData === 'function';
     const binCount = bins.length;
-    const aggregatedBins = [];
+    const aggregatedBins: AggregatedBin[] = [];
     let index = 0;
 
     for (let binIndex = 0; binIndex < binCount; binIndex++) {
@@ -94,7 +109,7 @@ export default class BinSorter {
     return aggregatedBins;
   }
 
-  _percentileToIndex(percentileRange) {
+  _percentileToIndex(percentileRange): [number, number] {
     const len = this.sortedBins.length;
     if (len < 2) {
       return [0, 0];
@@ -113,7 +128,7 @@ export default class BinSorter {
    * This is used to retrieve bin value for color calculation
    * @return {Object} bin index to aggregatedBins
    */
-  getBinMap() {
+  getBinMap(): Record<number, AggregatedBin> {
     const binMap = {};
     for (const bin of this.aggregatedBins) {
       binMap[bin.i] = bin;
@@ -125,9 +140,8 @@ export default class BinSorter {
 
   /**
    * Get ths max count of all bins
-   * @return {Number | Boolean} max count
    */
-  _updateMinMaxValues() {
+  _updateMinMaxValues(): void {
     let maxCount = 0;
     let maxValue = 0;
     let minValue = MAX_32_BIT_FLOAT;
@@ -151,11 +165,12 @@ export default class BinSorter {
    * @param {Number} range[1] - upper bound
    * @return {Array} array of new value range
    */
-  getValueRange(percentileRange) {
+  getValueRange(percentileRange: [number, number]): [number, number] {
     if (!this.sortedBins) {
       this.sortedBins = this.aggregatedBins.sort((a, b) => ascending(a.value, b.value));
     }
     if (!this.sortedBins.length) {
+      // @ts-expect-error
       return [];
     }
     let lowerIdx = 0;
@@ -170,7 +185,7 @@ export default class BinSorter {
     return [this.sortedBins[lowerIdx].value, this.sortedBins[upperIdx].value];
   }
 
-  getValueDomainByScale(scale, [lower = 0, upper = 100] = []) {
+  getValueDomainByScale(scale: string, [lower = 0, upper = 100] = []) {
     if (!this.sortedBins) {
       this.sortedBins = this.aggregatedBins.sort((a, b) => ascending(a.value, b.value));
     }
@@ -182,7 +197,7 @@ export default class BinSorter {
     return this._getScaleDomain(scale, indexEdge);
   }
 
-  _getScaleDomain(scaleType, [lowerIdx, upperIdx]) {
+  _getScaleDomain(scaleType: string, [lowerIdx, upperIdx]: [number, number]): [number, number] {
     const bins = this.sortedBins;
 
     switch (scaleType) {
@@ -194,7 +209,7 @@ export default class BinSorter {
         return getQuantileDomain(bins.slice(lowerIdx, upperIdx + 1), d => d.value);
 
       case 'ordinal':
-        return getOrdinalDomain(bins, d => d.value);
+        return getOrdinalDomain(bins, d => d.value) as [number, number];
 
       default:
         return [bins[lowerIdx].value, bins[upperIdx].value];