@deck.gl/carto 9.0.21 → 9.0.24

package/package.json

@@ -3,7 +3,7 @@
   "description": "CARTO official integration with Deck.gl. Build geospatial applications using CARTO and Deck.gl.",
   "license": "MIT",
   "type": "module",
-  "version": "9.0.21",
+  "version": "9.0.24",
   "publishConfig": {
     "access": "public"
   },
@@ -72,5 +72,5 @@
     "@deck.gl/layers": "^9.0.0",
     "@loaders.gl/core": "^4.2.0"
   },
-  "gitHead": "bb9a6c4887b58e210223d4c6f5472811bd096521"
+  "gitHead": "0949b9e539222d84d35b1b315e55710106409553"
 }

package/src/api/layer-map.ts

@@ -18,11 +18,11 @@ import {CPUGridLayer, HeatmapLayer, HexagonLayer} from '@deck.gl/aggregation-lay
 import {GeoJsonLayer} from '@deck.gl/layers';
 import {H3HexagonLayer} from '@deck.gl/geo-layers';
 
+import ClusterTileLayer from '../layers/cluster-tile-layer';
 import H3TileLayer from '../layers/h3-tile-layer';
 import QuadbinTileLayer from '../layers/quadbin-tile-layer';
 import RasterTileLayer from '../layers/raster-tile-layer';
 import VectorTileLayer from '../layers/vector-tile-layer';
-import {MapType} from './types';
 import {assert, createBinaryProxy, scaleIdentity} from '../utils';
 import {
   CustomMarkersRange,
@@ -32,6 +32,7 @@ import {
   VisualChannelField,
   VisualChannels
 } from './types';
+import HeatmapTileLayer from '../layers/heatmap-tile-layer';
 
 const SCALE_FUNCS = {
   linear: scaleLinear,
@@ -46,6 +47,17 @@ const SCALE_FUNCS = {
 };
 export type SCALE_TYPE = keyof typeof SCALE_FUNCS;
 
+type TileLayerType =
+  | 'clusterTile'
+  | 'h3'
+  | 'heatmapTile'
+  | 'mvt'
+  | 'quadbin'
+  | 'raster'
+  | 'tileset';
+type DocumentLayerType = 'geojson' | 'grid' | 'heatmap' | 'hexagon' | 'hexagonId' | 'point';
+type LayerType = TileLayerType | DocumentLayerType;
+
 function identity<T>(v: T): T {
   return v;
 }
@@ -74,6 +86,16 @@ const AGGREGATION_FUNC = {
   variance
 };
 
+const TILE_LAYER_TYPE_TO_LAYER: Record<TileLayerType, ConstructorOf<Layer>> = {
+  clusterTile: ClusterTileLayer,
+  h3: H3TileLayer,
+  heatmapTile: HeatmapTileLayer,
+  mvt: VectorTileLayer,
+  quadbin: QuadbinTileLayer,
+  raster: RasterTileLayer,
+  tileset: VectorTileLayer
+};
+
 const hexToRGBA = c => {
   const {r, g, b, opacity} = rgb(c);
   return [r, g, b, 255 * opacity];
@@ -135,7 +157,7 @@ function mergePropMaps(a: Record<string, any> = {}, b: Record<string, any> = {})
 }
 
 export function getLayer(
-  type: string,
+  type: LayerType,
   config: MapTextSubLayerConfig,
   dataset: MapDataset
 ): {Layer: ConstructorOf<Layer>; propMap: any; defaultProps: any} {
@@ -144,8 +166,8 @@ export function getLayer(
   if (config.visConfig?.customMarkers) {
     basePropMap = mergePropMaps(sharedPropMap, customMarkersPropsMap);
   }
-  if (type === 'mvt' || type === 'tileset' || type === 'h3' || type === 'quadbin') {
-    return getTileLayer(dataset, basePropMap);
+  if (TILE_LAYER_TYPE_TO_LAYER[type]) {
+    return getTileLayer(dataset, basePropMap, type);
   }
 
   const geoColumn = dataset?.geoColumn;
@@ -154,7 +176,7 @@ export function getLayer(
   const hexagonId = config.columns?.hex_id;
 
   const layerTypeDefs: Record<
-    string,
+    DocumentLayerType,
     {Layer: ConstructorOf<Layer>; propMap?: any; defaultProps?: any}
   > = {
     point: {
@@ -201,32 +223,11 @@ export function getLayer(
   };
 }
 
-export function layerFromTileDataset(
-  scheme: string,
-  type?: MapType
-): typeof VectorTileLayer | typeof H3TileLayer | typeof QuadbinTileLayer {
-  if (type === 'raster') {
-    return RasterTileLayer;
-  }
-  if (scheme === 'h3') {
-    return H3TileLayer;
-  }
-  if (scheme === 'quadbin') {
-    return QuadbinTileLayer;
-  }
-
-  return VectorTileLayer;
-}
-
-function getTileLayer(dataset: MapDataset, basePropMap) {
-  const {
-    aggregationExp,
-    aggregationResLevel,
-    data: {scheme}
-  } = dataset;
+function getTileLayer(dataset: MapDataset, basePropMap, type: LayerType) {
+  const {aggregationExp, aggregationResLevel} = dataset;
 
   return {
-    Layer: layerFromTileDataset(scheme),
+    Layer: TILE_LAYER_TYPE_TO_LAYER[type] || VectorTileLayer,
     propMap: basePropMap,
     defaultProps: {
       ...defaultProps,

package/src/index.ts

@@ -1,3 +1,4 @@
+import {default as ClusterTileLayer} from './layers/cluster-tile-layer';
 import {default as H3TileLayer} from './layers/h3-tile-layer';
 import {default as HeatmapTileLayer} from './layers/heatmap-tile-layer';
 import {default as _PointLabelLayer} from './layers/point-label-layer';
@@ -5,6 +6,7 @@ import {default as QuadbinTileLayer} from './layers/quadbin-tile-layer';
 import {default as RasterTileLayer} from './layers/raster-tile-layer';
 import {default as VectorTileLayer} from './layers/vector-tile-layer';
 const CARTO_LAYERS = {
+  ClusterTileLayer,
   H3TileLayer,
   HeatmapTileLayer,
   _PointLabelLayer,
@@ -14,6 +16,7 @@ const CARTO_LAYERS = {
 };
 export {
   CARTO_LAYERS,
+  ClusterTileLayer,
   H3TileLayer,
   HeatmapTileLayer,
   _PointLabelLayer,

package/src/layers/cluster-tile-layer.ts

@@ -0,0 +1,218 @@
+import {GeoJsonLayer, GeoJsonLayerProps} from '@deck.gl/layers';
+import {
+  TileLayer,
+  _Tile2DHeader as Tile2DHeader,
+  TileLayerProps,
+  TileLayerPickingInfo
+} from '@deck.gl/geo-layers';
+import {registerLoaders} from '@loaders.gl/core';
+import {binaryToGeojson} from '@loaders.gl/gis';
+import {BinaryFeatureCollection} from '@loaders.gl/schema';
+import type {Feature, Geometry} from 'geojson';
+
+import {
+  Accessor,
+  DefaultProps,
+  CompositeLayer,
+  _deepEqual as deepEqual,
+  GetPickingInfoParams,
+  Layer,
+  LayersList,
+  PickingInfo
+} from '@deck.gl/core';
+
+import {
+  aggregateTile,
+  ClusteredFeaturePropertiesT,
+  clustersToBinary,
+  computeAggregationStats,
+  extractAggregationProperties,
+  ParsedQuadbinCell,
+  ParsedQuadbinTile
+} from './cluster-utils';
+import {DEFAULT_TILE_SIZE} from '../constants';
+import QuadbinTileset2D from './quadbin-tileset-2d';
+import {getQuadbinPolygon} from './quadbin-utils';
+import CartoSpatialTileLoader from './schema/carto-spatial-tile-loader';
+import {injectAccessToken, TilejsonPropType} from './utils';
+import type {TilejsonResult} from '../sources/types';
+
+registerLoaders([CartoSpatialTileLoader]);
+
+const defaultProps: DefaultProps<ClusterTileLayerProps> = {
+  data: TilejsonPropType,
+  clusterLevel: {type: 'number', value: 5, min: 1},
+  getPosition: {
+    type: 'accessor',
+    value: ({id}) => getQuadbinPolygon(id, 0.5).slice(2, 4) as [number, number]
+  },
+  getWeight: {type: 'accessor', value: 1},
+  refinementStrategy: 'no-overlap',
+  tileSize: DEFAULT_TILE_SIZE
+};
+
+export type ClusterTileLayerPickingInfo<FeaturePropertiesT = {}> = TileLayerPickingInfo<
+  ParsedQuadbinTile<FeaturePropertiesT>,
+  PickingInfo<Feature<Geometry, FeaturePropertiesT>>
+>;
+
+/** All properties supported by ClusterTileLayer. */
+export type ClusterTileLayerProps<FeaturePropertiesT = unknown> =
+  _ClusterTileLayerProps<FeaturePropertiesT> &
+    Omit<TileLayerProps<ParsedQuadbinTile<FeaturePropertiesT>>, 'data'>;
+
+/** Properties added by ClusterTileLayer. */
+type _ClusterTileLayerProps<FeaturePropertiesT> = Omit<
+  GeoJsonLayerProps<ClusteredFeaturePropertiesT<FeaturePropertiesT>>,
+  'data'
+> & {
+  data: null | TilejsonResult | Promise<TilejsonResult>;
+
+  /**
+   * The number of aggregation levels to cluster cells by. Larger values increase
+   * the clustering radius, with an increment of `clusterLevel` doubling the radius.
+   *
+   * @default 5
+   */
+  clusterLevel?: number;
+
+  /**
+   * The (average) position of points in a cell used for clustering.
+   * If not supplied the center of the quadbin cell is used.
+   *
+   * @default cell center
+   */
+  getPosition?: Accessor<ParsedQuadbinCell<FeaturePropertiesT>, [number, number]>;
+
+  /**
+   * The weight of each cell used for clustering.
+   *
+   * @default 1
+   */
+  getWeight?: Accessor<ParsedQuadbinCell<FeaturePropertiesT>, number>;
+};
+
+class ClusterGeoJsonLayer<
+  FeaturePropertiesT extends {} = {},
+  ExtraProps extends {} = {}
+> extends TileLayer<
+  ParsedQuadbinTile<FeaturePropertiesT>,
+  ExtraProps & Required<_ClusterTileLayerProps<FeaturePropertiesT>>
+> {
+  static layerName = 'ClusterGeoJsonLayer';
+  static defaultProps = defaultProps;
+  state!: TileLayer<FeaturePropertiesT>['state'] & {
+    data: BinaryFeatureCollection;
+    clusterIds: bigint[];
+    hoveredFeatureId: bigint | number | null;
+    highlightColor: number[];
+  };
+
+  renderLayers(): Layer | null | LayersList {
+    const visibleTiles = this.state.tileset?.tiles.filter((tile: Tile2DHeader) => {
+      return tile.isLoaded && tile.content && this.state.tileset!.isTileVisible(tile);
+    }) as Tile2DHeader<ParsedQuadbinTile<FeaturePropertiesT>>[];
+    if (!visibleTiles?.length) {
+      return null;
+    }
+    visibleTiles.sort((a, b) => b.zoom - a.zoom);
+
+    const {zoom} = this.context.viewport;
+    const {clusterLevel, getPosition, getWeight} = this.props;
+
+    const properties = extractAggregationProperties(visibleTiles[0]);
+    const data = [] as ClusteredFeaturePropertiesT<FeaturePropertiesT>[];
+    for (const tile of visibleTiles) {
+      // Calculate aggregation based on viewport zoom
+      const overZoom = Math.round(zoom - tile.zoom);
+      const aggregationLevels = Math.round(clusterLevel) - overZoom;
+      aggregateTile(tile, aggregationLevels, properties, getPosition, getWeight);
+      data.push(...tile.userData![aggregationLevels]);
+    }
+
+    data.sort((a, b) => Number(b.count - a.count));
+
+    const clusterIds = data?.map((tile: any) => tile.id);
+    const needsUpdate = !deepEqual(clusterIds, this.state.clusterIds, 1);
+    this.setState({clusterIds});
+
+    if (needsUpdate) {
+      const stats = computeAggregationStats(data, properties);
+      for (const d of data) {
+        d.stats = stats;
+      }
+      this.setState({data: clustersToBinary(data)});
+    }
+
+    const props = {
+      ...this.props,
+      id: 'clusters',
+      data: this.state.data,
+      dataComparator: (data?: BinaryFeatureCollection, oldData?: BinaryFeatureCollection) => {
+        const newIds = data?.points?.properties?.map((tile: any) => tile.id);
+        const oldIds = oldData?.points?.properties?.map((tile: any) => tile.id);
+        return deepEqual(newIds, oldIds, 1);
+      }
+    } as GeoJsonLayerProps<ClusteredFeaturePropertiesT<FeaturePropertiesT>>;
+
+    return new GeoJsonLayer(this.getSubLayerProps(props));
+  }
+
+  getPickingInfo(params: GetPickingInfoParams): ClusterTileLayerPickingInfo<FeaturePropertiesT> {
+    const info = params.info as TileLayerPickingInfo<ParsedQuadbinTile<FeaturePropertiesT>>;
+
+    if (info.index !== -1) {
+      const {data} = params.sourceLayer!.props;
+      info.object = binaryToGeojson(data as BinaryFeatureCollection, {
+        globalFeatureId: info.index
+      }) as Feature;
+    }
+
+    return info;
+  }
+
+  protected _updateAutoHighlight(info: PickingInfo): void {
+    for (const layer of this.getSubLayers()) {
+      layer.updateAutoHighlight(info);
+    }
+  }
+
+  filterSubLayer() {
+    return true;
+  }
+}
+
+// Adapter layer around ClusterLayer that converts tileJSON into TileLayer API
+export default class ClusterTileLayer<
+  FeaturePropertiesT = any,
+  ExtraProps extends {} = {}
+> extends CompositeLayer<ExtraProps & Required<_ClusterTileLayerProps<FeaturePropertiesT>>> {
+  static layerName = 'ClusterTileLayer';
+  static defaultProps = defaultProps;
+
+  getLoadOptions(): any {
+    const loadOptions = super.getLoadOptions() || {};
+    const tileJSON = this.props.data as TilejsonResult;
+    injectAccessToken(loadOptions, tileJSON.accessToken);
+    loadOptions.cartoSpatialTile = {...loadOptions.cartoSpatialTile, scheme: 'quadbin'};
+    return loadOptions;
+  }
+
+  renderLayers(): Layer | null | LayersList {
+    const tileJSON = this.props.data as TilejsonResult;
+    if (!tileJSON) return null;
+
+    const {tiles: data, maxresolution: maxZoom} = tileJSON;
+    return [
+      // @ts-ignore
+      new ClusterGeoJsonLayer(this.props, {
+        id: `cluster-geojson-layer-${this.props.id}`,
+        data,
+        // TODO: Tileset2D should be generic over TileIndex type
+        TilesetClass: QuadbinTileset2D as any,
+        maxZoom,
+        loadOptions: this.getLoadOptions()
+      })
+    ];
+  }
+}

package/src/layers/cluster-utils.ts

@@ -0,0 +1,160 @@
+import {cellToParent} from 'quadbin';
+import {_Tile2DHeader as Tile2DHeader} from '@deck.gl/geo-layers';
+import {Accessor} from '@deck.gl/core';
+import {BinaryFeatureCollection} from '@loaders.gl/schema';
+
+export type Aggregation = 'any' | 'average' | 'count' | 'min' | 'max' | 'sum';
+export type AggregationProperties<FeaturePropertiesT> = {
+  aggregation: Aggregation;
+  name: keyof FeaturePropertiesT;
+}[];
+export type ClusteredFeaturePropertiesT<FeaturePropertiesT> = FeaturePropertiesT & {
+  id: bigint;
+  count: number;
+  position: [number, number];
+  stats: Record<keyof FeaturePropertiesT, {min: number; max: number}>;
+};
+export type ParsedQuadbinCell<FeaturePropertiesT> = {id: bigint; properties: FeaturePropertiesT};
+export type ParsedQuadbinTile<FeaturePropertiesT> = ParsedQuadbinCell<FeaturePropertiesT>[];
+
+export function aggregateTile<FeaturePropertiesT>(
+  tile: Tile2DHeader<ParsedQuadbinTile<FeaturePropertiesT>>,
+  aggregationLevels: number,
+  properties: AggregationProperties<FeaturePropertiesT> = [],
+  getPosition: Accessor<ParsedQuadbinCell<FeaturePropertiesT>, [number, number]>,
+  getWeight: Accessor<ParsedQuadbinCell<FeaturePropertiesT>, number>
+): void {
+  if (!tile.content) return;
+
+  // Aggregate on demand and cache result
+  if (!tile.userData) tile.userData = {};
+  if (tile.userData[aggregationLevels]) return;
+
+  const out: Record<number, any> = {};
+  for (const cell of tile.content) {
+    let id = cell.id;
+    const position = typeof getPosition === 'function' ? getPosition(cell, {} as any) : getPosition;
+
+    // Aggregate by parent id
+    for (let i = 0; i < aggregationLevels - 1; i++) {
+      id = cellToParent(id);
+    }
+
+    // Unfortunately TS doesn't support Record<bigint, any>
+    // https://github.com/microsoft/TypeScript/issues/46395
+    const parentId = Number(id);
+    if (!(parentId in out)) {
+      out[parentId] = {id, count: 0, position: [0, 0]};
+      for (const {name, aggregation} of properties) {
+        if (aggregation === 'any') {
+          // Just pick first value for ANY
+          out[parentId][name] = cell.properties[name];
+        } else {
+          out[parentId][name] = 0;
+        }
+      }
+    }
+    // Layout props
+    const prevTotalW = out[parentId].count;
+    out[parentId].count += typeof getWeight === 'function' ? getWeight(cell, {} as any) : getWeight;
+
+    const totalW = out[parentId].count;
+    const W = totalW - prevTotalW;
+    out[parentId].position[0] = (prevTotalW * out[parentId].position[0] + W * position[0]) / totalW;
+    out[parentId].position[1] = (prevTotalW * out[parentId].position[1] + W * position[1]) / totalW;
+
+    // Re-aggregate other properties so clusters can be styled
+    for (const {name, aggregation} of properties) {
+      const prevValue = out[parentId][name];
+      const value = cell.properties[name] as number;
+      if (aggregation === 'average') {
+        out[parentId][name] = (prevTotalW * prevValue + W * value) / totalW;
+      } else if (aggregation === 'count' || aggregation === 'sum') {
+        out[parentId][name] = prevValue + value;
+      } else if (aggregation === 'max') {
+        out[parentId][name] = Math.max(prevValue, value);
+      } else if (aggregation === 'min') {
+        out[parentId][name] = Math.min(prevValue, value);
+      }
+    }
+  }
+
+  tile.userData[aggregationLevels] = Object.values(out);
+}
+
+export function extractAggregationProperties<FeaturePropertiesT extends {}>(
+  tile: Tile2DHeader<ParsedQuadbinTile<FeaturePropertiesT>>
+): AggregationProperties<FeaturePropertiesT> {
+  const properties: AggregationProperties<FeaturePropertiesT> = [];
+  const validAggregations: Aggregation[] = ['any', 'average', 'count', 'min', 'max', 'sum'];
+  for (const name of Object.keys(tile.content![0].properties)) {
+    let aggregation = name.split('_').pop()!.toLowerCase() as Aggregation;
+    if (!validAggregations.includes(aggregation)) {
+      aggregation = 'any';
+    }
+    properties.push({name: name as keyof FeaturePropertiesT, aggregation});
+  }
+
+  return properties;
+}
+
+export function computeAggregationStats<FeaturePropertiesT>(
+  data: ClusteredFeaturePropertiesT<FeaturePropertiesT>[],
+  properties: AggregationProperties<FeaturePropertiesT>
+) {
+  const stats = {} as Record<keyof FeaturePropertiesT, {min: number; max: number}>;
+  for (const {name, aggregation} of properties) {
+    stats[name] = {min: Infinity, max: -Infinity};
+    if (aggregation !== 'any') {
+      for (const d of data) {
+        stats[name].min = Math.min(stats[name].min, d[name] as number);
+        stats[name].max = Math.max(stats[name].max, d[name] as number);
+      }
+    }
+  }
+
+  return stats;
+}
+
+const EMPTY_UINT16ARRAY = new Uint16Array();
+const EMPTY_BINARY_PROPS = {
+  positions: {value: new Float32Array(), size: 2},
+  properties: [],
+  numericProps: {},
+  featureIds: {value: EMPTY_UINT16ARRAY, size: 1},
+  globalFeatureIds: {value: EMPTY_UINT16ARRAY, size: 1}
+};
+
+export function clustersToBinary<FeaturePropertiesT>(
+  data: ClusteredFeaturePropertiesT<FeaturePropertiesT>[]
+): BinaryFeatureCollection {
+  const positions = new Float32Array(data.length * 2);
+  const featureIds = new Uint16Array(data.length);
+  for (let i = 0; i < data.length; i++) {
+    positions.set(data[i].position, 2 * i);
+    featureIds[i] = i;
+  }
+
+  return {
+    shape: 'binary-feature-collection',
+    points: {
+      type: 'Point',
+      positions: {value: positions, size: 2},
+      properties: data,
+      numericProps: {},
+      featureIds: {value: featureIds, size: 1},
+      globalFeatureIds: {value: featureIds, size: 1}
+    },
+    lines: {
+      type: 'LineString',
+      pathIndices: {value: EMPTY_UINT16ARRAY, size: 1},
+      ...EMPTY_BINARY_PROPS
+    },
+    polygons: {
+      type: 'Polygon',
+      polygonIndices: {value: EMPTY_UINT16ARRAY, size: 1},
+      primitivePolygonIndices: {value: EMPTY_UINT16ARRAY, size: 1},
+      ...EMPTY_BINARY_PROPS
+    }
+  };
+}

package/src/style/color-bins-style.ts

@@ -1,7 +1,7 @@
 import {scaleThreshold} from 'd3-scale';
-import {AccessorFunction} from '@deck.gl/core';
+import {AccessorFunction, Color} from '@deck.gl/core';
 import {Feature} from 'geojson';
-import getPalette, {Color, DEFAULT_PALETTE, NULL_COLOR} from './palette';
+import getPalette, {DEFAULT_PALETTE, NULL_COLOR} from './palette';
 import {assert} from '../utils';
 import {AttributeSelector, getAttrValue} from './utils';
 

package/src/style/color-categories-style.ts

@@ -1,6 +1,6 @@
-import {AccessorFunction} from '@deck.gl/core';
+import {AccessorFunction, Color} from '@deck.gl/core';
 import {Feature} from 'geojson';
-import getPalette, {Color, DEFAULT_PALETTE, NULL_COLOR, OTHERS_COLOR} from './palette';
+import getPalette, {DEFAULT_PALETTE, NULL_COLOR, OTHERS_COLOR} from './palette';
 import {assert} from '../utils';
 import {AttributeSelector, getAttrValue} from './utils';
 

package/src/style/color-continuous-style.ts

@@ -1,7 +1,7 @@
-import {AccessorFunction} from '@deck.gl/core';
+import {AccessorFunction, Color} from '@deck.gl/core';
 import {scaleLinear} from 'd3-scale';
 import {Feature} from 'geojson';
-import getPalette, {Color, DEFAULT_PALETTE, NULL_COLOR} from './palette';
+import getPalette, {DEFAULT_PALETTE, NULL_COLOR} from './palette';
 import {assert} from '../utils';
 import {AttributeSelector, getAttrValue} from './utils';
 

package/src/style/palette.ts

@@ -1,7 +1,6 @@
 import * as cartoColors from 'cartocolor';
 import {assert} from '../utils';
-
-export type Color = [r: number, b: number, g: number, a?: number];
+import {Color} from '@deck.gl/core';
 
 export const DEFAULT_PALETTE = 'PurpOr';
 export const NULL_COLOR: Color = [204, 204, 204];