@deck.gl/carto 8.8.0-alpha.2 → 8.8.0-alpha.5

package/package.json

@@ -2,7 +2,7 @@
   "name": "@deck.gl/carto",
   "description": "CARTO official integration with Deck.gl. Build geospatial applications using CARTO and Deck.gl.",
   "license": "MIT",
-  "version": "8.8.0-alpha.2",
+  "version": "8.8.0-alpha.5",
   "publishConfig": {
     "access": "public"
   },
@@ -23,6 +23,7 @@
   "files": [
     "dist",
     "src",
+    "typed",
     "dist.min.js"
   ],
   "sideEffects": false,
@@ -35,7 +36,7 @@
     "@loaders.gl/loader-utils": "^3.2.0-alpha.4",
     "@loaders.gl/mvt": "^3.2.0-alpha.4",
     "@loaders.gl/tiles": "^3.2.0-alpha.4",
-    "@luma.gl/constants": "^8.5.10",
+    "@luma.gl/constants": "^8.5.13",
     "@math.gl/web-mercator": "3.6.0-alpha.5",
     "cartocolor": "^4.0.2",
     "d3-array": "^2.8.0",
@@ -46,6 +47,7 @@
     "pbf": "^3.2.1"
   },
   "devDependencies": {
+    "@loaders.gl/schema": "^3.2.0-alpha.4",
     "@types/d3-array": "^3.0.2",
     "@types/d3-color": "^1.4.2",
     "@types/d3-scale": "^3.0.0"
@@ -58,5 +60,5 @@
     "@deck.gl/layers": "^8.0.0",
     "@loaders.gl/core": "^3.0.0"
   },
-  "gitHead": "a52215449dff06fb683f5afd6399526353d11f35"
+  "gitHead": "a5e210f62321ab78b7cacbcd0614e0ffcdf6bca7"
 }

package/src/api/layer-map.ts

@@ -42,6 +42,12 @@ export const AGGREGATION = {
   sum: 'SUM'
 };
 
+export const OPACITY_MAP = {
+  getFillColor: 'opacity',
+  getLineColor: 'strokeOpacity',
+  getTextColor: 'opacity'
+};
+
 const AGGREGATION_FUNC = {
   'count unique': (values, accessor) => groupSort(values, v => v.length, accessor).length,
   median,
@@ -71,7 +77,6 @@ const sharedPropMap = {
     enable3d: 'extruded',
     elevationScale: 'elevationScale',
     filled: 'filled',
-    opacity: 'opacity',
     strokeColor: 'getLineColor',
     stroked: 'stroked',
     thickness: 'getLineWidth',
@@ -225,6 +230,10 @@ function normalizeAccessor(accessor, data) {
   return accessor;
 }
 
+export function opacityToAlpha(opacity) {
+  return opacity !== undefined ? Math.round(255 * Math.pow(opacity, 1 / 2.2)) : 255;
+}
+
 export function getColorValueAccessor({name}, colorAggregation, data: any) {
   const aggregator = AGGREGATION_FUNC[colorAggregation];
   const accessor = values => aggregator(values, p => p[name]);
@@ -259,11 +268,12 @@ export function getColorAccessor(
   scale.domain(domain);
   scale.range(scaleColor);
   scale.unknown(UNKNOWN_COLOR);
-  const alpha = opacity !== undefined ? Math.round(255 * Math.pow(opacity, 1 / 2.2)) : 255;
+  const alpha = opacityToAlpha(opacity);
 
   const accessor = properties => {
-    const {r, g, b} = rgb(scale(properties[name]));
-    return [r, g, b, alpha];
+    const propertyValue = properties[name];
+    const {r, g, b} = rgb(scale(propertyValue));
+    return [r, g, b, propertyValue === null ? 0 : alpha];
   };
   return normalizeAccessor(accessor, data);
 }

package/src/api/maps-api-common.ts

@@ -35,6 +35,7 @@ export type Format = ValuesOf<typeof FORMATS>;
 // AVAILABLE FORMATS FOR TILES
 export const TILE_FORMATS = {
   MVT: 'mvt',
+  JSON: 'json',
   GEOJSON: 'geojson',
   BINARY: 'binary'
 } as const;

package/src/api/parseMap.ts

@@ -6,7 +6,9 @@ import {
   getColorValueAccessor,
   getSizeAccessor,
   getTextAccessor,
-  getTextPixelOffsetAccessor
+  getTextPixelOffsetAccessor,
+  OPACITY_MAP,
+  opacityToAlpha
 } from './layer-map';
 import {_flatten as flatten, log} from '@deck.gl/core';
 import {assert} from '../utils';
@@ -131,10 +133,21 @@ function createStyleProps(config, mapping) {
   mapProps(config, result, mapping);
 
   // Kepler format sometimes omits strokeColor. TODO: remove once we can rely on
-  // `strokeColor` always being sert when `stroke: true`.
+  // `strokeColor` always being set when `stroke: true`.
   if (result.stroked && !result.getLineColor) {
     result.getLineColor = result.getFillColor;
   }
+
+  for (const colorAccessor in OPACITY_MAP) {
+    if (Array.isArray(result[colorAccessor])) {
+      const color = [...result[colorAccessor]];
+      const opacityKey = OPACITY_MAP[colorAccessor];
+      const opacity = config.visConfig[opacityKey];
+      color[3] = opacityToAlpha(opacity);
+      result[colorAccessor] = color;
+    }
+  }
+
   result.highlightColor = config.visConfig.enable3d ? [255, 255, 255, 60] : [252, 242, 26, 255];
   return result;
 }
@@ -159,7 +172,7 @@ function createChannelProps(visualChannels, type, config, data) {
       if (!AGGREGATION[colorAggregation]) {
         result.getColorValue = getColorValueAccessor(colorField, colorAggregation, data);
       } else {
-        result.getColorWeight = d => [colorField.name];
+        result.getColorWeight = d => d[colorField.name];
       }
     }
   } else if (colorField) {
@@ -167,13 +180,15 @@ function createChannelProps(visualChannels, type, config, data) {
       colorField,
       colorScale,
       visConfig.colorRange,
-      1, // Rely on layer opacity
+      visConfig.opacity,
       data
     );
   }
 
   if (strokeColorField) {
-    const opacity = visConfig.strokeOpacity !== undefined ? visConfig.strokeOpacity : 1;
+    const fallbackOpacity = type === 'point' ? visConfig.opacity : 1;
+    const opacity =
+      visConfig.strokeOpacity !== undefined ? visConfig.strokeOpacity : fallbackOpacity;
     result.getLineColor = getColorAccessor(
       strokeColorField,
       strokeColorScale,

package/src/index.ts

@@ -1,6 +1,8 @@
 export {getDefaultCredentials, setDefaultCredentials} from './config';
 export {default as CartoLayer} from './layers/carto-layer';
 export {default as _CartoTileLayer} from './layers/carto-tile-layer';
+export {default as _H3TileLayer} from './layers/h3-tile-layer';
+export {default as _QuadkeyTileLayer} from './layers/quadkey-tile-layer';
 export {default as BASEMAP} from './basemap';
 export {default as colorBins} from './style/color-bins-style';
 export {default as colorCategories} from './style/color-categories-style';

package/src/layers/carto-layer.ts

@@ -1,5 +1,7 @@
 import {CompositeLayer, Layer, log} from '@deck.gl/core';
 import CartoTileLayer from './carto-tile-layer';
+import H3TileLayer from './h3-tile-layer';
+import QuadkeyTileLayer from './quadkey-tile-layer';
 import {MVTLayer} from '@deck.gl/geo-layers';
 import {GeoJsonLayer} from '@deck.gl/layers';
 import {fetchLayerData, getDataV2, API_VERSIONS} from '../api';
@@ -55,7 +57,13 @@ const defaultProps = {
   geoColumn: null,
 
   // (Array<String>, optional): names of columns to fetch. By default, all columns are fetched.
-  columns: {type: 'array', value: null}
+  columns: {type: 'array', value: null},
+
+  // (String, optional): aggregration SQL expression. Only used for spatial index datasets
+  aggregationExp: null,
+
+  // (Number, optional): aggregration resolution level. Only used for spatial index datasets, defaults to 6 for quadkeys, 4 for h3
+  aggregationResLevel: null
 };
 
 export interface CartoLayerProps<DataT = any> extends CompositeLayerProps<DataT> {
@@ -240,7 +248,7 @@ export default class CartoLayer<DataT = any> extends CompositeLayer<CartoLayerPr
           source,
           clientId,
           credentials: credentials as CloudNativeCredentials,
-          connection: connection as string,
+          connection,
           ...rest
         });
       }
@@ -283,6 +291,12 @@ export default class CartoLayer<DataT = any> extends CompositeLayer<CartoLayerPr
         (tileUrl.searchParams.get('formatTiles') as TileFormat) ||
         TILE_FORMATS.MVT;
 
+      if (data.scheme === 'h3') {
+        return [H3TileLayer, props];
+      }
+      if (data.scheme === 'quadkey') {
+        return [QuadkeyTileLayer, props];
+      }
       return props.formatTiles === TILE_FORMATS.MVT ? [MVTLayer, props] : [CartoTileLayer, props];
     }
 

package/src/layers/{carto-tile-layer.js → carto-tile-layer.ts}

@@ -1,29 +1,39 @@
 /* global TextDecoder */
 import Protobuf from 'pbf';
-import {log} from '@deck.gl/core';
+import {Layer, LayersList, log} from '@deck.gl/core';
 import {ClipExtension} from '@deck.gl/extensions';
-import {MVTLayer, _getURLFromTemplate} from '@deck.gl/geo-layers';
+import {
+  MVTLayer,
+  MVTLayerProps,
+  TileLayer,
+  _getURLFromTemplate,
+  _Tile2DHeader,
+  _TileLoadProps as TileLoadProps
+} from '@deck.gl/geo-layers';
 import {GeoJsonLayer} from '@deck.gl/layers';
 import {geojsonToBinary} from '@loaders.gl/gis';
-import {Tile} from './schema/carto-tile';
-import {TILE_FORMATS} from '../api/maps-api-common';
+import {Properties, Tile, TileReader} from './schema/carto-tile';
+import {TileFormat, TILE_FORMATS} from '../api/maps-api-common';
+import {LoaderOptions, LoaderWithParser} from '@loaders.gl/loader-utils';
+import type {BinaryFeatures} from '@loaders.gl/schema';
+import type {Feature} from 'geojson';
 
-function parseJSON(arrayBuffer) {
+function parseJSON(arrayBuffer: ArrayBuffer): any {
   return JSON.parse(new TextDecoder().decode(arrayBuffer));
 }
 
-function parsePbf(buffer) {
+function parsePbf(buffer: ArrayBuffer): Tile {
   const pbf = new Protobuf(buffer);
-  const tile = Tile.read(pbf);
+  const tile = TileReader.read(pbf);
   return tile;
 }
 
-function unpackProperties(properties) {
+function unpackProperties(properties: Properties[]) {
   if (!properties || !properties.length) {
     return [];
   }
   return properties.map(item => {
-    const currentRecord = {};
+    const currentRecord: Record<string, unknown> = {};
     item.data.forEach(({key, value}) => {
       currentRecord[key] = value;
     });
@@ -31,7 +41,7 @@ function unpackProperties(properties) {
   });
 }
 
-function parseCartoTile(arrayBuffer, options) {
+function parseCartoTile(arrayBuffer: ArrayBuffer, options?: LoaderOptions): BinaryFeatures | null {
   if (!arrayBuffer) return null;
   const formatTiles = options && options.cartoTile && options.cartoTile.formatTiles;
   if (formatTiles === TILE_FORMATS.GEOJSON) return geojsonToBinary(parseJSON(arrayBuffer).features);
@@ -45,13 +55,15 @@ function parseCartoTile(arrayBuffer, options) {
     polygons: {...polygons, properties: unpackProperties(polygons.properties)}
   };
 
-  return data;
+  // Note: there is slight, difference in `numericProps` type, however geojson/mvtlayer can cope with this
+  return data as unknown as BinaryFeatures;
 }
 
 const defaultTileFormat = TILE_FORMATS.BINARY;
 
-const CartoTileLoader = {
+const CartoTileLoader: LoaderWithParser = {
   name: 'CARTO Tile',
+  version: '1',
   id: 'cartoTile',
   module: 'carto',
   extensions: ['pbf'],
@@ -73,8 +85,29 @@ const defaultProps = {
   loaders: [CartoTileLoader]
 };
 
-export default class CartoTileLayer extends MVTLayer {
-  getTileData(tile) {
+/** All properties supported by CartoTileLayer. */
+export type CartoTileLayerProps<DataT extends Feature = Feature> = _CartoTileLayerProps &
+  MVTLayerProps<DataT>;
+
+/** Properties added by CartoTileLayer. */
+type _CartoTileLayerProps = {
+  /** Use to override the default tile data format.
+   *
+   * Possible values are: `TILE_FORMATS.BINARY`, `TILE_FORMATS.GEOJSON` and `TILE_FORMATS.MVT`.
+   *
+   * Only supported when `apiVersion` is `API_VERSIONS.V3` and `format` is `FORMATS.TILEJSON`.
+   * */
+  formatTiles?: TileFormat;
+};
+
+export default class CartoTileLayer<
+  DataT extends Feature = Feature,
+  ExtraProps = {}
+> extends MVTLayer<DataT, Required<_CartoTileLayerProps> & ExtraProps> {
+  static layerName = 'CartoTileLayer';
+  static defaultProps = defaultProps;
+
+  getTileData(tile: TileLoadProps) {
     const url = _getURLFromTemplate(this.state.data, tile);
     if (!url) {
       return Promise.reject('Invalid URL');
@@ -100,25 +133,29 @@ export default class CartoTileLayer extends MVTLayer {
     return fetch(url, {propName: 'data', layer: this, loadOptions, signal});
   }
 
-  renderSubLayers(props) {
+  renderSubLayers(
+    props: TileLayer['props'] & {
+      id: string;
+      data: any;
+      _offset: number;
+      tile: _Tile2DHeader;
+    }
+  ): GeoJsonLayer | null {
     if (props.data === null) {
       return null;
     }
 
-    props.autoHighlight = false;
+    const tileBbox = props.tile.bbox as any;
+    const {west, south, east, north} = tileBbox;
 
-    const {
-      bbox: {west, south, east, north}
-    } = props.tile;
-    props.extensions = [new ClipExtension(), ...(props.extensions || [])];
-    props.clipBounds = [west, south, east, north];
+    const subLayerProps = {
+      ...props,
+      autoHighlight: false,
+      extensions: [new ClipExtension(), ...(props.extensions || [])],
+      clipBounds: [west, south, east, north]
+    };
 
-    const subLayer = new GeoJsonLayer({
-      ...props
-    });
+    const subLayer = new GeoJsonLayer(subLayerProps);
     return subLayer;
   }
 }
-
-CartoTileLayer.layerName = 'CartoTileLayer';
-CartoTileLayer.defaultProps = defaultProps;

package/src/layers/h3-tile-layer.js

@@ -0,0 +1,52 @@
+import {CompositeLayer} from '@deck.gl/core';
+import {H3HexagonLayer} from '@deck.gl/geo-layers';
+import H3Tileset2D from './h3-tileset-2d';
+import SpatialIndexTileLayer from './spatial-index-tile-layer';
+
+const renderSubLayers = props => {
+  const {data} = props;
+  const {index} = props.tile;
+  if (!data || !data.length) return null;
+
+  return new H3HexagonLayer(props, {
+    centerHexagon: index,
+    highPrecision: true
+  });
+};
+
+const defaultProps = {
+  aggregationResLevel: 4
+};
+
+export default class H3TileLayer extends CompositeLayer {
+  initializeState() {
+    this.setState({data: null, tileJSON: null});
+  }
+
+  updateState({props, oldProps, context, changeFlags}) {
+    if (changeFlags.dataChanged) {
+      let {data} = this.props;
+      const tileJSON = data;
+      data = tileJSON.tiles;
+      this.setState({data, tileJSON});
+    }
+  }
+
+  renderLayers() {
+    const {data, tileJSON} = this.state;
+    const maxZoom = parseInt(tileJSON.maxresolution);
+    return [
+      new SpatialIndexTileLayer(this.props, {
+        id: `h3-tile-layer-${this.props.id}`,
+        data,
+        getHexagon: d => d.id,
+        TilesetClass: H3Tileset2D,
+        renderSubLayers,
+        maxZoom
+      })
+    ];
+  }
+}
+
+H3TileLayer.layerName = 'H3TileLayer';
+H3TileLayer.defaultProps = defaultProps;

package/src/layers/h3-tileset-2d.js

@@ -0,0 +1,108 @@
+import {_Tileset2D as Tileset2D} from '@deck.gl/geo-layers';
+import {
+  polyfill,
+  getRes0Indexes,
+  geoToH3,
+  h3GetResolution,
+  h3ToGeoBoundary,
+  h3ToParent,
+  kRing
+} from 'h3-js';
+
+function getHexagonsInBoundingBox({west, north, east, south}, resolution) {
+  if (resolution === 0) {
+    return getRes0Indexes();
+  }
+  if (east - west > 180) {
+    // This is a known issue in h3-js: polyfill does not work correctly
+    // when longitude span is larger than 180 degrees.
+    return getHexagonsInBoundingBox({west, north, east: 0, south}, resolution).concat(
+      getHexagonsInBoundingBox({west: 0, north, east, south}, resolution)
+    );
+  }
+
+  // `polyfill()` fills based on hexagon center, which means tiles vanish
+  // prematurely. Get more accurate coverage by oversampling
+  const oversample = 2;
+  const h3Indices = polyfill(
+    [
+      [
+        [west, north],
+        [west, south],
+        [east, south],
+        [east, north],
+        [west, north]
+      ]
+    ],
+    resolution + oversample,
+    true
+  );
+
+  return oversample ? [...new Set(h3Indices.map(i => h3ToParent(i, resolution)))] : h3Indices;
+}
+
+function tileToBoundingBox(index) {
+  const coordinates = h3ToGeoBoundary(index);
+  const latitudes = coordinates.map(c => c[0]);
+  const longitudes = coordinates.map(c => c[1]);
+  const west = Math.min(...longitudes);
+  const south = Math.min(...latitudes);
+  const east = Math.max(...longitudes);
+  const north = Math.max(...latitudes);
+  return {west, south, east, north};
+}
+
+// Resolution conversion function. Takes a WebMercatorViewport and returns
+// a H3 resolution such that the screen space size of the hexagons is
+// similar
+// Relative scale factor (0 = no biasing, 2 = a few hexagons cover view)
+const BIAS = 2;
+function getHexagonResolution(viewport) {
+  const hexagonScaleFactor = (2 / 3) * viewport.zoom;
+  const latitudeScaleFactor = Math.log(1 / Math.cos((Math.PI * viewport.latitude) / 180));
+
+  // Clip and bias
+  return Math.max(0, Math.floor(hexagonScaleFactor + latitudeScaleFactor - BIAS));
+}
+
+export default class H3Tileset2D extends Tileset2D {
+  getTileIndices({viewport, minZoom, maxZoom}) {
+    const [east, south, west, north] = viewport.getBounds();
+
+    let z = getHexagonResolution(viewport);
+    let indices = [];
+    if (typeof minZoom === 'number' && Number.isFinite(minZoom) && z < minZoom) {
+      z = minZoom;
+    }
+    if (typeof maxZoom === 'number' && Number.isFinite(maxZoom) && z > maxZoom) {
+      z = maxZoom;
+
+      // Once we are at max zoom, getHexagonsInBoundingBox doesn't work, simply
+      // get a ring centered on the hexagon in the viewport center
+      const center = geoToH3(viewport.latitude, viewport.longitude, maxZoom);
+      indices = kRing(center, 1);
+    } else {
+      indices = getHexagonsInBoundingBox({west, north, east, south}, z);
+    }
+
+    return indices.map(i => ({i}));
+  }
+
+  getTileId({i}) {
+    return i;
+  }
+
+  getTileMetadata({i}) {
+    return {bbox: tileToBoundingBox(i)};
+  }
+
+  getTileZoom({i}) {
+    return h3GetResolution(i);
+  }
+
+  getParentIndex(index) {
+    const resolution = h3GetResolution(index.i);
+    const i = h3ToParent(index.i, resolution - 1);
+    return {i};
+  }
+}

package/src/layers/quadkey-tile-layer.js

@@ -0,0 +1,47 @@
+import {CompositeLayer} from '@deck.gl/core';
+import {QuadkeyLayer} from '@deck.gl/geo-layers';
+import QuadkeyTileset2D from './quadkey-tileset-2d';
+import SpatialIndexTileLayer from './spatial-index-tile-layer';
+
+const renderSubLayers = props => {
+  const {data} = props;
+  if (!data || !data.length) return null;
+  return new QuadkeyLayer(props);
+};
+
+const defaultProps = {
+  aggregationResLevel: 6
+};
+
+export default class QuadkeyTileLayer extends CompositeLayer {
+  initializeState() {
+    this.setState({data: null, tileJSON: null});
+  }
+
+  updateState({props, oldProps, context, changeFlags}) {
+    if (changeFlags.dataChanged) {
+      let {data} = this.props;
+      const tileJSON = data;
+      data = tileJSON.tiles;
+      this.setState({data, tileJSON});
+    }
+  }
+
+  renderLayers() {
+    const {data, tileJSON} = this.state;
+    const maxZoom = parseInt(tileJSON.maxresolution);
+    return [
+      new SpatialIndexTileLayer(this.props, {
+        id: `quadkey-tile-layer-${this.props.id}`,
+        data,
+        getQuadkey: d => d.id,
+        TilesetClass: QuadkeyTileset2D,
+        renderSubLayers,
+        maxZoom
+      })
+    ];
+  }
+}
+
+QuadkeyTileLayer.layerName = 'QuadkeyTileLayer';
+QuadkeyTileLayer.defaultProps = defaultProps;

package/src/layers/quadkey-tileset-2d.js

@@ -0,0 +1,36 @@
+import {_Tileset2D as Tileset2D} from '@deck.gl/geo-layers';
+
+function tileToQuadkey(tile) {
+  let index = '';
+  for (let z = tile.z; z > 0; z--) {
+    let b = 0;
+    const mask = 1 << (z - 1);
+    if ((tile.x & mask) !== 0) b++;
+    if ((tile.y & mask) !== 0) b += 2;
+    index += b.toString();
+  }
+  return {i: index};
+}
+
+export default class QuadkeyTileset2D extends Tileset2D {
+  getTileIndices(opts) {
+    return super.getTileIndices(opts).map(tileToQuadkey);
+  }
+
+  getTileId({i}) {
+    return i;
+  }
+
+  getTileMetadata() {
+    return {};
+  }
+
+  getTileZoom({i}) {
+    return i.length;
+  }
+
+  getParentIndex(index) {
+    const i = index.i.slice(0, -1);
+    return {i};
+  }
+}