CARTO: Support h3 in HeatmapTileLayer (#9753)

Author: felixpalmer

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

@@ -6,12 +6,14 @@
 
 import type {ShaderModule} from '@luma.gl/shadertools';
 import {getResolution} from 'quadbin';
+import {getResolution as getH3Resolution, getNumCells} from 'h3-js';
 
 import {
   Accessor,
   Color,
   CompositeLayer,
   CompositeLayerProps,
+  _deepEqual as deepEqual,
   DefaultProps,
   Layer,
   UpdateParameters
@@ -21,6 +23,7 @@ import {SolidPolygonLayer} from '@deck.gl/layers';
 import {HeatmapProps, heatmap} from './heatmap';
 import {RTTModifier, PostProcessModifier} from './post-process-utils';
 import QuadbinTileLayer, {QuadbinTileLayerProps} from './quadbin-tile-layer';
+import H3TileLayer, {H3TileLayerProps} from './h3-tile-layer';
 import {TilejsonPropType} from './utils';
 import {TilejsonResult} from '@carto/api-client';
 import {_Tile2DHeader as Tile2DHeader} from '@deck.gl/geo-layers';
@@ -48,13 +51,23 @@ const TEXTURE_PROPS: TextureProps = {
   }
 };
 /**
- * Computes the unit density (inverse of cell area)
+ * Computes the unit density for Quadbin cells.
+ * The unit density is the number of cells needed to cover the Earth's surface at a given resolution. It is inversely proportional to the cell area.
  */
-function unitDensityForCell(cell: bigint) {
+function unitDensityForQuadbinCell(cell: bigint) {
   const cellResolution = Number(getResolution(cell));
   return Math.pow(4.0, cellResolution);
 }
 
+/**
+ * Computes the unit density for H3 cells.
+ * The unit density is the number of cells needed to cover the Earth's surface at a given resolution. It is inversely proportional to the cell area.
+ */
+function unitDensityForH3Cell(cellId: string) {
+  const cellResolution = Number(getH3Resolution(cellId));
+  return getNumCells(cellResolution);
+}
+
 /**
  * Converts a colorRange array to a flat array with 4 components per color
  */
@@ -120,12 +133,15 @@ class RTTSolidPolygonLayer extends RTTModifier(SolidPolygonLayer) {
 
   draw(this, opts: any) {
     const cell = this.props!.data[0];
-    const maxDensity = this.props.elevationScale;
-    const densityProps: DensityProps = {
-      factor: unitDensityForCell(cell.id) / maxDensity
-    };
-    for (const model of this.state.models) {
-      model.shaderInputs.setProps({density: densityProps});
+    if (cell) {
+      const maxDensity = this.props.elevationScale;
+      const {scheme} = this.parent.parent.parent.parent.parent.state;
+      const unitDensity =
+        scheme === 'h3' ? unitDensityForH3Cell(cell.id) : unitDensityForQuadbinCell(cell.id);
+      const densityProps: DensityProps = {factor: unitDensity / maxDensity};
+      for (const model of this.state.models) {
+        model.shaderInputs.setProps({density: densityProps});
+      }
     }
 
     super.draw(opts);
@@ -135,6 +151,9 @@ class RTTSolidPolygonLayer extends RTTModifier(SolidPolygonLayer) {
 // Modify QuadbinTileLayer to apply heatmap post process effect
 const PostProcessQuadbinTileLayer = PostProcessModifier(QuadbinTileLayer, heatmap);
 
+// Modify H3TileLayer to apply heatmap post process effect
+const PostProcessH3TileLayer = PostProcessModifier(H3TileLayer, heatmap);
+
 const defaultProps: DefaultProps<HeatmapTileLayerProps> = {
   data: TilejsonPropType,
   getWeight: {type: 'accessor', value: 1},
@@ -152,7 +171,7 @@ export type HeatmapTileLayerProps<DataT = unknown> = _HeatmapTileLayerProps<Data
   };
 
 /** Properties added by HeatmapTileLayer. */
-type _HeatmapTileLayerProps<DataT> = QuadbinTileLayerProps<DataT> &
+type _HeatmapTileLayerProps<DataT> = (QuadbinTileLayerProps<DataT> | H3TileLayerProps<DataT>) &
   HeatmapProps & {
     /**
      * Specified as an array of colors [color1, color2, ...].
@@ -181,12 +200,14 @@ class HeatmapTileLayer<DataT = any, ExtraProps extends {} = {}> extends Composit
   state!: {
     colorTexture?: Texture;
     isLoaded: boolean;
+    scheme: string | null;
     tiles: Set<Tile2DHeader>;
     viewportChanged?: boolean;
   };
   initializeState() {
     this.state = {
       isLoaded: false,
+      scheme: null,
       tiles: new Set(),
       viewportChanged: false
     };
@@ -201,9 +222,15 @@ class HeatmapTileLayer<DataT = any, ExtraProps extends {} = {}> extends Composit
   updateState(opts: UpdateParameters<this>) {
     const {props, oldProps} = opts;
     super.updateState(opts);
-    if (props.colorRange !== oldProps.colorRange) {
+    if (!deepEqual(props.colorRange, oldProps.colorRange, 2)) {
       this._updateColorTexture(opts);
     }
+
+    const scheme = props.data && 'scheme' in props.data ? props.data.scheme : null;
+    if (this.state.scheme !== scheme) {
+      this.setState({scheme});
+      this.state.tiles.clear();
+    }
   }
 
   renderLayers(): Layer {
@@ -222,15 +249,18 @@ class HeatmapTileLayer<DataT = any, ExtraProps extends {} = {}> extends Composit
       ...tileLayerProps
     } = this.props;
 
+    const isH3 = this.state.scheme === 'h3';
+
+    const cellLayerName = isH3 ? 'hexagon-cell-hifi' : 'cell';
     // Inject modified polygon layer as sublayer into TileLayer
     const subLayerProps = {
       ..._subLayerProps,
-      cell: {
-        ..._subLayerProps?.cell,
+      [cellLayerName]: {
+        ..._subLayerProps?.[cellLayerName],
         _subLayerProps: {
-          ..._subLayerProps?.cell?._subLayerProps,
+          ..._subLayerProps?.[cellLayerName]?._subLayerProps,
           fill: {
-            ..._subLayerProps?.cell?._subLayerProps?.fill,
+            ..._subLayerProps?.[cellLayerName]?._subLayerProps?.fill,
             type: RTTSolidPolygonLayer
           }
         }
@@ -248,21 +278,37 @@ class HeatmapTileLayer<DataT = any, ExtraProps extends {} = {}> extends Composit
 
     for (const tile of tiles) {
       const cell = tile.content[0];
-      const unitDensity = unitDensityForCell(cell.id);
+      const unitDensity = isH3 ? unitDensityForH3Cell(cell.id) : unitDensityForQuadbinCell(cell.id);
       maxDensity = Math.max(tile.userData!.maxWeight * unitDensity, maxDensity);
       tileZ = Math.max(tile.zoom, tileZ);
     }
 
-    // Between zoom levels the max density will change, but it isn't possible to know by what factor. Uniform data distributions lead to a factor of 4, while very localized data gives 1. As a heurstic estimate with a value inbetween (2) to make the transitions less obvious.
-    const overzoom = this.context.viewport.zoom - tileZ;
-    const estimatedMaxDensity = maxDensity * Math.pow(2, overzoom);
+    // Between zoom levels the max density will change, but it isn't possible to know by what factor.
+    // As a heuristic, an estimatedGrowthFactor makes the transitions less obvious.
+    // For quadbin, uniform data distributions lead to an estimatedGrowthFactor of 4, while very localized data gives 1.
+    // For H3 the same logic applies but the aperture is 7, rather than 4, so a slightly higher estimatedGrowthFactor is used.
+    let overzoom: number;
+    let estimatedGrowthFactor: number;
+    if (isH3) {
+      // For H3, we need to account for the viewport zoom to H3 resolution mapping (see getHexagonResolution())
+      overzoom = (2 / 3) * this.context.viewport.zoom - tileZ - 2.25;
+      estimatedGrowthFactor = 2.2;
+    } else {
+      overzoom = this.context.viewport.zoom - tileZ;
+      estimatedGrowthFactor = 2;
+    }
 
-    maxDensity = estimatedMaxDensity;
+    maxDensity = maxDensity * Math.pow(estimatedGrowthFactor, overzoom);
     if (typeof onMaxDensityChange === 'function') {
       onMaxDensityChange(maxDensity);
     }
-    return new PostProcessQuadbinTileLayer(
-      tileLayerProps as Omit<QuadbinTileLayerProps, 'data'>,
+    const PostProcessTileLayer = isH3 ? PostProcessH3TileLayer : PostProcessQuadbinTileLayer;
+    const layerProps = isH3
+      ? (tileLayerProps as Omit<H3TileLayerProps, 'data'>)
+      : (tileLayerProps as Omit<QuadbinTileLayerProps, 'data'>);
+
+    return new PostProcessTileLayer(
+      layerProps,
       this.getSubLayerProps({
         id: 'heatmap',
         data,
@@ -330,18 +376,14 @@ class HeatmapTileLayer<DataT = any, ExtraProps extends {} = {}> extends Composit
     let {colorTexture} = this.state;
     const colors = colorRangeToFlatArray(colorRange);
 
-    if (colorTexture && colorTexture?.width === colorRange.length) {
-      // TODO(v9): Unclear whether `setSubImageData` is a public API, or what to use if not.
-      (colorTexture as any).setTexture2DData({data: colors});
-    } else {
-      colorTexture?.destroy();
-      colorTexture = this.context.device.createTexture({
-        ...TEXTURE_PROPS,
-        data: colors,
-        width: colorRange.length,
-        height: 1
-      });
-    }
+    colorTexture?.destroy();
+    colorTexture = this.context.device.createTexture({
+      ...TEXTURE_PROPS,
+      data: colors,
+      width: colorRange.length,
+      height: 1
+    });
+
     this.setState({colorTexture});
   }
 }

modules/carto/src/layers/heatmap.ts

@@ -89,6 +89,9 @@ vec4 heatmap_sampleColor(sampler2D source, vec2 texSize, vec2 texCoord) {
   color.a = pow(color.a, 1.0 / 2.2);
   color.a *= heatmap.opacity;
 
+  // Use premultiplied alpha for compatibility with blending in ScreenPass
+  color.rgb *= color.a;
+
   return color;
 }
 `;

test/apps/carto-dynamic-tile/app.tsx

@@ -8,7 +8,13 @@ import React, {useState} from 'react';
 import {createRoot} from 'react-dom/client';
 import {Map} from 'react-map-gl/maplibre';
 import DeckGL from '@deck.gl/react';
-import {H3TileLayer, RasterTileLayer, QuadbinTileLayer, VectorTileLayer} from '@deck.gl/carto';
+import {
+  H3TileLayer,
+  HeatmapTileLayer,
+  RasterTileLayer,
+  QuadbinTileLayer,
+  VectorTileLayer
+} from '@deck.gl/carto';
 
 import {query} from '@carto/api-client';
 import datasets from './datasets';
@@ -31,6 +37,8 @@ function Root() {
 
   if (dataset.includes('boundary')) {
     layers = [useBoundaryLayer(datasource)];
+  } else if (dataset.includes('heatmap')) {
+    layers = [useHeatmapLayer(datasource)];
   } else if (dataset.includes('h3')) {
     layers = [useH3Layer(datasource)];
   } else if (dataset.includes('raster')) {
@@ -89,6 +97,35 @@ function useBoundaryLayer(datasource) {
   });
 }
 
+function useHeatmapLayer(datasource) {
+  const {getWeight, source, aggregationExp, columns, spatialDataColumn, sqlQuery, tableName} =
+    datasource;
+  const tilejson = source({
+    ...globalOptions,
+    aggregationExp,
+    columns,
+    spatialDataColumn,
+    sqlQuery,
+    tableName
+  });
+
+  return new HeatmapTileLayer({
+    id: 'carto-heatmap',
+    data: tilejson,
+    getWeight,
+    radiusPixels: 30,
+    intensity: 2,
+    colorRange: [
+      [255, 255, 178],
+      [254, 217, 118],
+      [254, 178, 76],
+      [253, 141, 60],
+      [240, 59, 32],
+      [189, 0, 38]
+    ]
+  });
+}
+
 function useH3Layer(datasource) {
   const {getFillColor, source, aggregationExp, columns, spatialDataColumn, sqlQuery, tableName} =
     datasource;

test/apps/carto-dynamic-tile/datasets.ts

@@ -14,11 +14,36 @@ import {
   quadbinQuerySource,
   vectorTableSource,
   vectorTilesetSource,
-  vectorQuerySource,
-  colorBins
-} from '@deck.gl/carto';
+  vectorQuerySource
+} from '@carto/api-client';
+
+import {colorBins} from '@deck.gl/carto';
 
 export default {
+  'heatmap-h3-table': {
+    source: h3TableSource,
+    tableName: 'carto-demo-data.demo_tables.derived_spatialfeatures_usa_h3res8_v1_yearly_v2',
+    aggregationExp: 'sum(population) as population_sum',
+    getWeight: d => d.properties.population_sum || 1
+  },
+  'heatmap-h3-tileset': {
+    source: h3TilesetSource,
+    tableName:
+      'carto-demo-data.demo_tilesets.derived_spatialfeatures_usa_h3res8_v1_yearly_v2_tileset',
+    getWeight: d => d.properties.retail || 1
+  },
+  'heatmap-quadbin-table': {
+    source: quadbinTableSource,
+    tableName: 'carto-demo-data.demo_tables.derived_spatialfeatures_usa_quadbin15_v1_yearly_v2',
+    aggregationExp: 'sum(population) as population_sum',
+    getWeight: d => d.properties.population_sum || 1
+  },
+  'heatmap-quadbin-tileset': {
+    source: quadbinTilesetSource,
+    tableName:
+      'carto-demo-data.demo_tilesets.derived_spatialfeatures_usa_quadbin15_v1_yearly_v2_tileset',
+    getWeight: d => d.properties.avg_retail || 1
+  },
   'boundary-query': {
     source: boundaryQuerySource,
     tilesetTableName: 'carto-boundaries.us.usa_zip_code_v1',

test/apps/carto-dynamic-tile/package.json

@@ -4,7 +4,8 @@
     "start-local": "vite --config ../vite.config.local.mjs"
   },
   "dependencies": {
-    "deck.gl": "^8.0.0",
+    "@carto/api-client": "^0.5.14",
+    "deck.gl": "^9.2.0-alpha",
     "maplibre-gl": "^4.3.2",
     "react": "^18.0.0",
     "react-dom": "^18.0.0",