CARTO: Support h3 in ClusterTileLayer (#9755)

* First attempt at cluster h3

* try to fix dynamic tile app

* heatmap test app

* test app clusters

* Correctly read in stats

* determine scheme in update state

* Better scheme change detection

* h3 zoom level to res mapping

* Better palette handling

* Palette utils

* _getAggregationLevels

* Merge branch 'master' into felix/h3-cluster-tile-layer

* remove datasetss

* cellToLatLng

* Revert test app changes

* Lint

* lint again

* token

* lint

Author: felixpalmer

modules/carto/src/layers/cluster-tile-layer.ts

@@ -24,7 +24,8 @@ import {
   GetPickingInfoParams,
   Layer,
   LayersList,
-  PickingInfo
+  PickingInfo,
+  WebMercatorViewport
 } from '@deck.gl/core';
 
 import {
@@ -34,38 +35,59 @@ import {
   computeAggregationStats,
   extractAggregationProperties,
   ParsedQuadbinCell,
-  ParsedQuadbinTile
+  ParsedQuadbinTile,
+  ParsedH3Cell,
+  ParsedH3Tile
 } from './cluster-utils';
 import {DEFAULT_TILE_SIZE} from '../constants';
 import QuadbinTileset2D from './quadbin-tileset-2d';
+import H3Tileset2D, {getHexagonResolution} from './h3-tileset-2d';
 import {getQuadbinPolygon} from './quadbin-utils';
+import {getResolution, cellToLatLng} from 'h3-js';
 import CartoSpatialTileLoader from './schema/carto-spatial-tile-loader';
 import {TilejsonPropType, mergeLoadOptions} from './utils';
 import type {TilejsonResult} from '@carto/api-client';
 
 registerLoaders([CartoSpatialTileLoader]);
 
+function getScheme(tilesetClass: typeof H3Tileset2D | typeof QuadbinTileset2D): 'h3' | 'quadbin' {
+  if (tilesetClass === H3Tileset2D) return 'h3';
+  if (tilesetClass === QuadbinTileset2D) return 'quadbin';
+  throw new Error('Invalid tileset class');
+}
+
 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]
+    value: ({id}) => {
+      // Determine scheme based on ID type: H3 uses string IDs, Quadbin uses bigint IDs
+      if (typeof id === 'string') {
+        const [lat, lng] = cellToLatLng(id);
+        return [lng, lat];
+      }
+      // eslint-disable-next-line @typescript-eslint/no-unnecessary-type-assertion
+      return getQuadbinPolygon(id as bigint, 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>,
+  ParsedQuadbinTile<FeaturePropertiesT> | ParsedH3Tile<FeaturePropertiesT>,
   PickingInfo<Feature<Geometry, FeaturePropertiesT>>
 >;
 
 /** All properties supported by ClusterTileLayer. */
 export type ClusterTileLayerProps<FeaturePropertiesT = unknown> =
   _ClusterTileLayerProps<FeaturePropertiesT> &
-    Omit<TileLayerProps<ParsedQuadbinTile<FeaturePropertiesT>>, 'data'>;
+    Omit<
+      TileLayerProps<ParsedQuadbinTile<FeaturePropertiesT> | ParsedH3Tile<FeaturePropertiesT>>,
+      'data'
+    >;
 
 /** Properties added by ClusterTileLayer. */
 type _ClusterTileLayerProps<FeaturePropertiesT> = Omit<
@@ -84,63 +106,84 @@ type _ClusterTileLayerProps<FeaturePropertiesT> = Omit<
 
   /**
    * The (average) position of points in a cell used for clustering.
-   * If not supplied the center of the quadbin cell is used.
+   * If not supplied the center of the quadbin cell or H3 cell is used.
    *
    * @default cell center
    */
-  getPosition?: Accessor<ParsedQuadbinCell<FeaturePropertiesT>, [number, number]>;
+  getPosition?: Accessor<
+    ParsedQuadbinCell<FeaturePropertiesT> | ParsedH3Cell<FeaturePropertiesT>,
+    [number, number]
+  >;
 
   /**
    * The weight of each cell used for clustering.
    *
    * @default 1
    */
-  getWeight?: Accessor<ParsedQuadbinCell<FeaturePropertiesT>, number>;
+  getWeight?: Accessor<
+    ParsedQuadbinCell<FeaturePropertiesT> | ParsedH3Cell<FeaturePropertiesT>,
+    number
+  >;
 };
 
 class ClusterGeoJsonLayer<
   FeaturePropertiesT extends {} = {},
   ExtraProps extends {} = {}
 > extends TileLayer<
-  ParsedQuadbinTile<FeaturePropertiesT>,
+  ParsedQuadbinTile<FeaturePropertiesT> | ParsedH3Tile<FeaturePropertiesT>,
   ExtraProps & Required<_ClusterTileLayerProps<FeaturePropertiesT>>
 > {
   static layerName = 'ClusterGeoJsonLayer';
   static defaultProps = defaultProps;
   state!: TileLayer<FeaturePropertiesT>['state'] & {
     data: BinaryFeatureCollection;
-    clusterIds: bigint[];
-    hoveredFeatureId: bigint | number | null;
+    clusterIds: (bigint | string)[];
+    hoveredFeatureId: bigint | string | number | null;
     highlightColor: number[];
     aggregationCache: WeakMap<any, Map<number, ClusteredFeaturePropertiesT<FeaturePropertiesT>[]>>;
+    scheme: string | null;
   };
 
   initializeState() {
     super.initializeState();
     this.state.aggregationCache = new WeakMap();
+    this.state.scheme = getScheme(this.props.TilesetClass as any);
+  }
+
+  updateState(opts) {
+    const {props} = opts;
+    const scheme = getScheme(props.TilesetClass);
+    if (this.state.scheme !== scheme) {
+      // Clear caches when scheme changes
+      this.setState({scheme, tileset: null});
+      this.state.aggregationCache = new WeakMap();
+    }
+
+    super.updateState(opts);
   }
 
   // eslint-disable-next-line max-statements
   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) {
+    }) as Tile2DHeader<ParsedQuadbinTile<FeaturePropertiesT> | ParsedH3Tile<FeaturePropertiesT>>[];
+    if (!visibleTiles?.length || !this.state.tileset) {
       return null;
     }
     visibleTiles.sort((a, b) => b.zoom - a.zoom);
+    const {getPosition, getWeight} = this.props;
+    const {aggregationCache, scheme} = this.state;
 
-    const {zoom} = this.context.viewport;
-    const {clusterLevel, getPosition, getWeight} = this.props;
-    const {aggregationCache} = this.state;
+    const isH3 = scheme === 'h3';
 
     const properties = extractAggregationProperties(visibleTiles[0]);
     const data = [] as ClusteredFeaturePropertiesT<FeaturePropertiesT>[];
     let needsUpdate = false;
+
+    const aggregationLevels = this._getAggregationLevels(visibleTiles);
+
     for (const tile of visibleTiles) {
       // Calculate aggregation based on viewport zoom
-      const overZoom = Math.round(zoom - tile.zoom);
-      const aggregationLevels = Math.round(clusterLevel) - overZoom;
       let tileAggregationCache = aggregationCache.get(tile.content);
       if (!tileAggregationCache) {
         tileAggregationCache = new Map();
@@ -152,7 +195,8 @@ class ClusterGeoJsonLayer<
         aggregationLevels,
         properties,
         getPosition,
-        getWeight
+        getWeight,
+        isH3 ? 'h3' : 'quadbin'
       );
       needsUpdate ||= didAggregate;
       data.push(...tileAggregationCache.get(aggregationLevels)!);
@@ -186,7 +230,9 @@ class ClusterGeoJsonLayer<
   }
 
   getPickingInfo(params: GetPickingInfoParams): ClusterTileLayerPickingInfo<FeaturePropertiesT> {
-    const info = params.info as TileLayerPickingInfo<ParsedQuadbinTile<FeaturePropertiesT>>;
+    const info = params.info as TileLayerPickingInfo<
+      ParsedQuadbinTile<FeaturePropertiesT> | ParsedH3Tile<FeaturePropertiesT>
+    >;
 
     if (info.index !== -1) {
       const {data} = params.sourceLayer!.props;
@@ -207,6 +253,31 @@ class ClusterGeoJsonLayer<
   filterSubLayer() {
     return true;
   }
+
+  private _getAggregationLevels(visibleTiles: Tile2DHeader[]): number {
+    const isH3 = this.state.scheme === 'h3';
+    const firstTile = visibleTiles[0];
+
+    // Resolution of data present in tiles
+    let tileResolution;
+
+    // Resolution of tiles that should be (eventually) visible in the viewport
+    let viewportResolution;
+    if (isH3) {
+      tileResolution = getResolution(firstTile.id);
+      viewportResolution = getHexagonResolution(
+        this.context.viewport as WebMercatorViewport,
+        (this.state.tileset as any).opts.tileSize
+      );
+    } else {
+      tileResolution = firstTile.zoom;
+      viewportResolution = this.context.viewport.zoom;
+    }
+
+    const resolutionDiff = Math.round(viewportResolution - tileResolution);
+    const aggregationLevels = Math.round(this.props.clusterLevel) - resolutionDiff;
+    return aggregationLevels;
+  }
 }
 
 // Adapter layer around ClusterLayer that converts tileJSON into TileLayer API
@@ -219,9 +290,10 @@ export default class ClusterTileLayer<
 
   getLoadOptions(): any {
     const tileJSON = this.props.data as TilejsonResult;
+    const scheme = tileJSON && 'scheme' in tileJSON ? tileJSON.scheme : 'quadbin';
     return mergeLoadOptions(super.getLoadOptions(), {
       fetch: {headers: {Authorization: `Bearer ${tileJSON.accessToken}`}},
-      cartoSpatialTile: {scheme: 'quadbin'}
+      cartoSpatialTile: {scheme}
     });
   }
 
@@ -230,13 +302,16 @@ export default class ClusterTileLayer<
     if (!tileJSON) return null;
 
     const {tiles: data, maxresolution: maxZoom} = tileJSON;
+    const isH3 = tileJSON && 'scheme' in tileJSON && tileJSON.scheme === 'h3';
+    const TilesetClass = isH3 ? H3Tileset2D : QuadbinTileset2D;
+
     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,
+        TilesetClass: TilesetClass as any,
         maxZoom,
         loadOptions: this.getLoadOptions()
       })

modules/carto/src/layers/cluster-utils.ts

@@ -3,6 +3,7 @@
 // Copyright (c) vis.gl contributors
 
 import {cellToParent} from 'quadbin';
+import {cellToParent as h3CellToParent, getResolution as getH3Resolution} from 'h3-js';
 import {_Tile2DHeader as Tile2DHeader} from '@deck.gl/geo-layers';
 import {Accessor, log} from '@deck.gl/core';
 import {BinaryFeatureCollection} from '@loaders.gl/schema';
@@ -14,25 +15,34 @@ export type AggregationProperties<FeaturePropertiesT> = {
   name: keyof FeaturePropertiesT;
 }[];
 export type ClusteredFeaturePropertiesT<FeaturePropertiesT> = FeaturePropertiesT & {
-  id: bigint;
+  id: bigint | string;
   count: number;
   position: [number, number];
 };
 export type ParsedQuadbinCell<FeaturePropertiesT> = {id: bigint; properties: FeaturePropertiesT};
 export type ParsedQuadbinTile<FeaturePropertiesT> = ParsedQuadbinCell<FeaturePropertiesT>[];
+export type ParsedH3Cell<FeaturePropertiesT> = {id: string; properties: FeaturePropertiesT};
+export type ParsedH3Tile<FeaturePropertiesT> = ParsedH3Cell<FeaturePropertiesT>[];
 
 /**
  * Aggregates tile by specified properties, caching result in tile.userData
  *
  * @returns true if data was aggregated, false if cache used
  */
 export function aggregateTile<FeaturePropertiesT>(
-  tile: Tile2DHeader<ParsedQuadbinTile<FeaturePropertiesT>>,
+  tile: Tile2DHeader<ParsedQuadbinTile<FeaturePropertiesT> | ParsedH3Tile<FeaturePropertiesT>>,
   tileAggregationCache: Map<number, ClusteredFeaturePropertiesT<FeaturePropertiesT>[]>,
   aggregationLevels: number,
   properties: AggregationProperties<FeaturePropertiesT> = [],
-  getPosition: Accessor<ParsedQuadbinCell<FeaturePropertiesT>, [number, number]>,
-  getWeight: Accessor<ParsedQuadbinCell<FeaturePropertiesT>, number>
+  getPosition: Accessor<
+    ParsedQuadbinCell<FeaturePropertiesT> | ParsedH3Cell<FeaturePropertiesT>,
+    [number, number]
+  >,
+  getWeight: Accessor<
+    ParsedQuadbinCell<FeaturePropertiesT> | ParsedH3Cell<FeaturePropertiesT>,
+    number
+  >,
+  scheme: 'quadbin' | 'h3' = 'quadbin'
 ): boolean {
   if (!tile.content) return false;
 
@@ -50,19 +60,24 @@ export function aggregateTile<FeaturePropertiesT>(
     tileAggregationCache.clear();
   }
 
-  const out: Record<number, any> = {};
+  const out: Record<string, any> = {};
   for (const cell of tile.content) {
     let id = cell.id;
     const position = typeof getPosition === 'function' ? getPosition(cell, {} as any) : getPosition;
 
     // Aggregate by parent rid
     for (let i = 0; i < aggregationLevels - 1; i++) {
-      id = cellToParent(id);
+      if (scheme === 'h3') {
+        const currentResolution = getH3Resolution(id as string);
+        id = h3CellToParent(id as string, Math.max(0, currentResolution - 1));
+      } else {
+        id = cellToParent(id as bigint);
+      }
     }
 
-    // Unfortunately TS doesn't support Record<bigint, any>
+    // Use string key for both H3 and Quadbin to avoid TypeScript Record<bigint, any> issues
     // https://github.com/microsoft/TypeScript/issues/46395
-    const parentId = Number(id);
+    const parentId = String(id);
     if (!(parentId in out)) {
       out[parentId] = {id, count: 0, position: [0, 0]};
       for (const {name, aggregation} of properties) {
@@ -104,7 +119,7 @@ export function aggregateTile<FeaturePropertiesT>(
 }
 
 export function extractAggregationProperties<FeaturePropertiesT extends {}>(
-  tile: Tile2DHeader<ParsedQuadbinTile<FeaturePropertiesT>>
+  tile: Tile2DHeader<ParsedQuadbinTile<FeaturePropertiesT> | ParsedH3Tile<FeaturePropertiesT>>
 ): AggregationProperties<FeaturePropertiesT> {
   const properties: AggregationProperties<FeaturePropertiesT> = [];
   const validAggregations: Aggregation[] = ['any', 'average', 'count', 'min', 'max', 'sum'];