@deck.gl/carto 8.9.3 → 8.9.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.9.3",
+  "version": "8.9.5",
   "publishConfig": {
     "access": "public"
   },
@@ -62,5 +62,5 @@
     "@deck.gl/layers": "^8.0.0",
     "@loaders.gl/core": "^3.0.0"
   },
-  "gitHead": "6f194255993e10898d6bd01ea38935385d222dd4"
+  "gitHead": "001fc31bd3dfa02eb4a0caba299584952f2236f6"
 }

package/src/api/layer-map.ts

@@ -27,7 +27,6 @@ import {
   CustomMarkersRange,
   MapDataset,
   MapTextSubLayerConfig,
-  TextLabel,
   VisConfig,
   VisualChannelField,
   VisualChannels
@@ -140,7 +139,7 @@ export function getLayer(
 ): {Layer: ConstructorOf<Layer>; propMap: any; defaultProps: any} {
   let basePropMap: any = sharedPropMap;
 
-  if (config.visConfig?.customMarkers && !config.textLabel) {
+  if (config.visConfig?.customMarkers) {
     basePropMap = mergePropMaps(sharedPropMap, customMarkersPropsMap);
   }
   if (type === 'mvt' || type === 'tileset' || type === 'h3' || type === 'quadbin') {
@@ -296,8 +295,26 @@ function calculateDomain(data, name, scaleType, scaleLength?) {
 
 function normalizeAccessor(accessor, data) {
   if (data.features || data.tilestats) {
-    return ({properties}) => {
-      return accessor(properties);
+    return (object, info) => {
+      if (object) {
+        return accessor(object.properties || object.__source.object.properties);
+      }
+
+      const {data, index} = info;
+      const {properties, numericProps} = data;
+      const proxy = new Proxy(properties[index] || {}, {
+        get(target, property, receiver) {
+          if (property in numericProps) {
+            return numericProps[property as string].value[index];
+          }
+          return target[property as string];
+        },
+
+        has(target, property) {
+          return property in numericProps || property in target;
+        }
+      });
+      return accessor(proxy);
     };
   }
   return accessor;
@@ -468,25 +485,4 @@ export function getTextAccessor({name, type}: VisualChannelField, data) {
   return normalizeAccessor(accessor, data);
 }
 
-export function getTextPixelOffsetAccessor(
-  {alignment, anchor, size}: TextLabel,
-  radius
-): Accessor<unknown, [number, number]> {
-  const padding = 20;
-  const signX = anchor === 'middle' ? 0 : anchor === 'start' ? 1 : -1;
-  const signY = alignment === 'center' ? 0 : alignment === 'bottom' ? 1 : -1;
-  const sizeOffset = alignment === 'center' ? 0 : size;
-
-  const calculateOffset = (r: number): [number, number] => [
-    signX * (r + padding),
-    signY * (r + padding + sizeOffset)
-  ];
-
-  return typeof radius === 'function'
-    ? d => {
-        return calculateOffset(radius(d));
-      }
-    : calculateOffset(radius);
-}
-
 export {domainFromValues as _domainFromValues};

package/src/api/maps-v3-client.ts

@@ -534,6 +534,7 @@ async function fillInTileStats(
   return await Promise.all(promises);
 }
 
+/* eslint-disable max-statements */
 export async function fetchMap({
   cartoMapId,
   clientId,
@@ -613,8 +614,22 @@ export async function fetchMap({
 
   // Mutates attributes in visualChannels to contain tile stats
   await fillInTileStats(map, localCreds);
-  return {
-    ...parseMap(map),
-    ...{stopAutoRefresh}
-  };
+  const out = {...parseMap(map), ...{stopAutoRefresh}};
+
+  const textLayers = out.layers.filter(layer => {
+    const pointType = layer.props.pointType || '';
+    return pointType.includes('text');
+  });
+
+  /* global FontFace, window, document */
+  if (textLayers.length && window.FontFace && !document.fonts.check('12px Inter')) {
+    // Fetch font needed for labels
+    const font = new FontFace(
+      'Inter',
+      'url(https://fonts.gstatic.com/s/inter/v12/UcC73FwrK3iLTeHuS_fvQtMwCp50KnMa1ZL7W0Q5nw.woff2)'
+    );
+    await font.load().then(f => document.fonts.add(f));
+  }
+
+  return out;
 }

package/src/api/parseMap.ts

@@ -6,16 +6,19 @@ import {
   getColorValueAccessor,
   getSizeAccessor,
   getTextAccessor,
-  getTextPixelOffsetAccessor,
   OPACITY_MAP,
   opacityToAlpha,
   getIconUrlAccessor,
   negateAccessor,
   getMaxMarkerSize
 } from './layer-map';
-import {_flatten as flatten, log} from '@deck.gl/core';
+import PointLabelLayer from '../layers/point-label-layer';
+import {log} from '@deck.gl/core';
+import {CollisionFilterExtension} from '@deck.gl/extensions';
 import {assert} from '../utils';
-import {MapDataset, MapTextSubLayerConfig, VisualChannels} from './types';
+import {MapDataset, MapLayerConfig, VisualChannels} from './types';
+
+const collisionFilterExtension = new CollisionFilterExtension();
 
 export function parseMap(json) {
   const {keplerMapConfig, datasets, token} = json;
@@ -32,7 +35,7 @@ export function parseMap(json) {
     initialViewState: mapState,
     mapStyle,
     token,
-    layers: extractTextLayers(layers.reverse()).map(({id, type, config, visualChannels}) => {
+    layers: layers.reverse().map(({id, type, config, visualChannels}) => {
       try {
         const {dataId} = config;
         const dataset: MapDataset | null = datasets.find(d => d.id === dataId);
@@ -45,9 +48,9 @@ export function parseMap(json) {
           id,
           data,
           ...defaultProps,
-          ...(!config.textLabel && createInteractionProps(interactionConfig)),
+          ...createInteractionProps(interactionConfig),
           ...styleProps,
-          ...createChannelProps(visualChannels, type, config, data), // Must come after style
+          ...createChannelProps(id, type, config, visualChannels, data), // Must come after style
           ...createParametersProp(layerBlending, styleProps.parameters || {}), // Must come after style
           ...createLoadOptions(token)
         });
@@ -59,34 +62,6 @@ export function parseMap(json) {
   };
 }
 
-function extractTextLayers(layers) {
-  return flatten(
-    layers.map(({id, config, ...rest}) => {
-      const {textLabel, ...configRest} = config;
-      return [
-        // Original layer without textLabel
-        {id, config: configRest, ...rest},
-
-        // One layer per valid text label, with full opacity
-        ...textLabel
-          .filter(t => t.field)
-          .map(t => {
-            return {
-              id: `${id}-label-${t.field.name}`,
-              config: {
-                textLabel: t,
-                ...configRest,
-                label: `${config.label}-label-${t.field.name}`,
-                visConfig: {...configRest.visConfig, opacity: 1}
-              },
-              ...rest
-            };
-          })
-      ];
-    })
-  );
-}
-
 function createParametersProp(layerBlending, parameters: Record<string, any>) {
   if (layerBlending === 'additive') {
     parameters.blendFunc = [GL.SRC_ALPHA, GL.DST_ALPHA];
@@ -127,7 +102,7 @@ function mapProps(source, target, mapping) {
   }
 }
 
-function createStyleProps(config: MapTextSubLayerConfig, mapping) {
+function createStyleProps(config: MapLayerConfig, mapping) {
   const result: Record<string, any> = {};
   mapProps(config, result, mapping);
 
@@ -153,9 +128,10 @@ function createStyleProps(config: MapTextSubLayerConfig, mapping) {
 
 /* eslint-disable complexity, max-statements */
 function createChannelProps(
-  visualChannels: VisualChannels,
+  id: string,
   type: string,
-  config: MapTextSubLayerConfig,
+  config: MapLayerConfig,
+  visualChannels: VisualChannels,
   data
 ) {
   const {
@@ -175,7 +151,6 @@ function createChannelProps(
   }
   const {textLabel, visConfig} = config;
   const result: Record<string, any> = {};
-  const textLabelField = textLabel && textLabel.field;
 
   if (type === 'grid' || type === 'hexagon') {
     result.colorScaleType = colorScale;
@@ -253,12 +228,7 @@ function createChannelProps(
     );
   }
 
-  if (textLabelField) {
-    result.getText = getTextAccessor(textLabelField, data);
-    result.pointType = 'text';
-    const radius = result.getPointRadius || visConfig.radius;
-    result.getTextPixelOffset = getTextPixelOffsetAccessor(textLabel, radius);
-  } else if (visConfig.customMarkers) {
+  if (visConfig.customMarkers) {
     const maxIconSize = getMaxMarkerSize(visConfig, visualChannels);
     const {getPointRadius, getFillColor} = result;
     const {customMarkersUrl, customMarkersRange, filled: useMaskedIcons} = visConfig;
@@ -298,6 +268,59 @@ function createChannelProps(
         getSizeAccessor(visualChannels.rotationField, undefined, null, undefined, data)
       );
     }
+  } else if (type === 'point' || type === 'tileset') {
+    result.pointType = 'circle';
+  }
+
+  if (textLabel && textLabel.length && textLabel[0].field) {
+    const [mainLabel, secondaryLabel] = textLabel;
+    const collisionGroup = id;
+
+    ({
+      alignment: result.getTextAlignmentBaseline,
+      anchor: result.getTextAnchor,
+      color: result.getTextColor,
+      outlineColor: result.textOutlineColor,
+      size: result.textSizeScale
+    } = mainLabel);
+    const {
+      color: getSecondaryColor,
+      field: secondaryField,
+      outlineColor: secondaryOutlineColor,
+      size: secondarySizeScale
+    } = secondaryLabel || {};
+
+    result.getText = mainLabel.field && getTextAccessor(mainLabel.field, data);
+    const getSecondaryText = secondaryField && getTextAccessor(secondaryField, data);
+
+    result.pointType = `${result.pointType}+text`;
+    result.textCharacterSet = 'auto';
+    result.textFontFamily = 'Inter, sans';
+    result.textFontSettings = {sdf: true};
+    result.textFontWeight = 600;
+    result.textOutlineWidth = 3;
+
+    result._subLayerProps = {
+      ...result._subLayerProps,
+      'points-text': {
+        type: PointLabelLayer,
+        extensions: [collisionFilterExtension],
+        collisionEnabled: true,
+        collisionGroup,
+
+        // getPointRadius already has radiusScale baked in, so only pass one or the other
+        ...(result.getPointRadius
+          ? {getRadius: result.getPointRadius}
+          : {radiusScale: visConfig.radius}),
+
+        ...(secondaryField && {
+          getSecondaryText,
+          getSecondaryColor,
+          secondarySizeScale,
+          secondaryOutlineColor
+        })
+      }
+    };
   }
 
   return result;

package/src/api/types.ts

@@ -77,6 +77,7 @@ export type TextLabel = {
   size: number;
   color?: number[];
   offset?: [number, number];
+  outlineColor?: number[];
 };
 
 export type MapLayerConfig = {

package/src/index.ts

@@ -2,6 +2,7 @@ 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 _PointLabelLayer} from './layers/point-label-layer';
 export {default as _QuadbinTileLayer} from './layers/quadbin-tile-layer';
 export {default as BASEMAP} from './basemap';
 export {default as colorBins} from './style/color-bins-style';

package/src/layers/point-label-layer.ts

@@ -0,0 +1,266 @@
+import {
+  Accessor,
+  Color,
+  CompositeLayer,
+  CompositeLayerProps,
+  DefaultProps,
+  Layer,
+  LayersList
+} from '@deck.gl/core';
+import {
+  TextLayer,
+  TextLayerProps,
+  _TextBackgroundLayer as TextBackgroundLayer
+} from '@deck.gl/layers';
+
+const [LEFT, TOP, RIGHT, BOTTOM] = [0, 1, 2, 3];
+
+class EnhancedTextBackgroundLayer extends TextBackgroundLayer {
+  static layerName = 'EnhancedTextBackgroundLayer';
+
+  getShaders() {
+    const shaders = super.getShaders();
+    let vs = shaders.vs;
+
+    // Modify shader so that the padding is offset by the pixel offset to ensure the padding
+    // always captures the anchor point. As padding is uniform we cannot pass it a per-label value
+    vs = vs.replaceAll('padding.', '_padding.');
+    vs = vs.replace(
+      'void main(void) {',
+      'void main(void) {\n  vec4 _padding = padding + instancePixelOffsets.xyxy * vec4(1.0, 1.0, -1.0, -1.0);'
+    );
+
+    return {...shaders, vs};
+  }
+}
+
+// TextLayer which includes modified text-background-layer-vertex shader and only renders the
+// primary background layer in the collision pass
+class EnhancedTextLayer extends TextLayer {
+  static layerName = 'EnhancedTextLayer';
+
+  filterSubLayer({layer, renderPass}) {
+    const background = layer.id.includes('primary-background');
+    if (renderPass === 'collision') {
+      return background; // Only draw primary background layer in collision pass
+    }
+
+    return !background; // Do not draw background layer in other passes
+  }
+}
+
+const defaultProps: DefaultProps<PointLabelLayerProps> = {
+  ...TextLayer.defaultProps,
+  getRadius: {type: 'accessor', value: 1},
+  radiusScale: {type: 'number', min: 0, value: 1}
+};
+
+/** All properties supported by PointLabelLayer. */
+export type PointLabelLayerProps<DataT = any> = _PointLabelLayerProps<DataT> &
+  TextLayerProps &
+  CompositeLayerProps;
+
+/** Properties added by PointLabelLayer. */
+type _PointLabelLayerProps<DataT> = TextLayerProps<DataT> & {
+  /**
+   * Radius multiplier.
+   * @default 1
+   */
+  radiusScale?: number;
+  /**
+   * Radius accessor.
+   * @default 1
+   */
+  getRadius?: Accessor<DataT, number>;
+  /**
+   * Secondary label text accessor
+   */
+  getSecondaryText?: Accessor<DataT, string>;
+  /**
+   * Secondary label color accessor
+   * @default [0, 0, 0, 255]
+   */
+  getSecondaryColor?: Accessor<DataT, Color>;
+  /**
+   * Secondary label color of outline around the text, in `[r, g, b, [a]]`. Each channel is a number between 0-255 and `a` is 255 if not supplied.
+   * @default [0, 0, 0, 255]
+   */
+  secondaryOutlineColor?: Color;
+  /**
+   * Secondary label text size multiplier.
+   * @default 1
+   */
+  secondarySizeScale?: number;
+};
+
+export default class PointLabelLayer<
+  DataT = any,
+  ExtraProps extends {} = {}
+> extends CompositeLayer<ExtraProps & Required<_PointLabelLayerProps<DataT>>> {
+  static layerName = 'PointLabelLayer';
+  static defaultProps = defaultProps;
+
+  calculatePixelOffset(secondary) {
+    const {
+      getTextAnchor: anchor,
+      getAlignmentBaseline: alignment,
+      getRadius,
+      getSecondaryText,
+      radiusScale,
+      secondarySizeScale,
+      sizeScale
+    } = this.props;
+    const xMult = anchor === 'middle' ? 0 : anchor === 'start' ? 1 : -1;
+    const yMult = alignment === 'center' ? 0 : alignment === 'bottom' ? 1 : -1;
+
+    // Padding based on font size (font size / 4)
+    const xPadding = sizeScale / 4;
+    const yPadding = sizeScale * (1 + 1 / 4);
+
+    // Place secondary label under main label (secondary label always 'top' baseline aligned)
+    const secondaryOffset = 0.6 * (1 - yMult) * sizeScale;
+    let yOffset = secondary ? secondaryOffset : 0;
+
+    // Special case, position relative to secondary label
+    if (anchor === 'middle' && alignment === 'top' && getSecondaryText) {
+      yOffset -= secondaryOffset;
+      yOffset -= secondarySizeScale;
+      yOffset += sizeScale;
+    }
+
+    // Padding based on point radius (radius/ 4)
+    const radiusPadding = 1 + 1 / 4;
+
+    return typeof getRadius === 'function'
+      ? (d, info) => {
+          const r = (info ? getRadius(d, info) : 1) * radiusScale * radiusPadding;
+          return [xMult * (r + xPadding), yMult * (r + yPadding) + yOffset];
+        }
+      : [
+          xMult * (getRadius * radiusScale * radiusPadding + xPadding),
+          yMult * (getRadius * radiusScale * radiusPadding + yPadding) + yOffset
+        ];
+  }
+
+  calculateBackgroundPadding() {
+    const {getTextAnchor: anchor, getAlignmentBaseline: alignment, sizeScale} = this.props;
+
+    // Heuristics to avoid label overlap
+    const paddingX = 12 * sizeScale;
+    const paddingY = 3 * sizeScale;
+    const backgroundPadding = [0, 0, 0, 0];
+    if (alignment === 'top') {
+      backgroundPadding[TOP] = paddingY;
+    } else if (alignment === 'bottom') {
+      backgroundPadding[BOTTOM] = paddingY;
+    } else {
+      backgroundPadding[TOP] = 0.5 * paddingY;
+      backgroundPadding[BOTTOM] = 0.5 * paddingY;
+    }
+    if (anchor === 'start') {
+      backgroundPadding[LEFT] = paddingX;
+    } else if (anchor === 'end') {
+      backgroundPadding[RIGHT] = paddingX;
+    } else {
+      backgroundPadding[LEFT] = 0.5 * paddingX;
+      backgroundPadding[RIGHT] = 0.5 * paddingX;
+    }
+
+    return backgroundPadding;
+  }
+
+  renderTextLayer(id, {updateTriggers: updateTriggersOverride = {}, ...props}): EnhancedTextLayer {
+    const {
+      data,
+
+      characterSet,
+      fontFamily,
+      fontSettings,
+      fontWeight,
+      outlineColor,
+      outlineWidth,
+      sizeScale,
+      radiusScale,
+
+      getAlignmentBaseline,
+      getColor,
+      getPosition,
+      getTextAnchor,
+
+      updateTriggers
+    } = this.props;
+
+    return new EnhancedTextLayer(
+      this.getSubLayerProps({
+        id,
+        data,
+
+        characterSet,
+        fontFamily,
+        fontSettings,
+        fontWeight,
+        outlineColor,
+        outlineWidth,
+        sizeScale,
+
+        getAlignmentBaseline,
+        getColor,
+        getPosition,
+        getTextAnchor,
+
+        updateTriggers: {
+          ...updateTriggers,
+          ...updateTriggersOverride,
+          getPixelOffset: [
+            updateTriggers.getRadius,
+            updateTriggers.getTextAnchor,
+            updateTriggers.getAlignmentBaseline,
+            radiusScale,
+            sizeScale
+          ]
+        }
+      }),
+      {
+        getSize: 1,
+        _subLayerProps: {background: {type: EnhancedTextBackgroundLayer}}
+      },
+      props
+    );
+  }
+
+  renderLayers(): Layer | null | LayersList {
+    const {
+      getText,
+      getSecondaryColor,
+      getSecondaryText,
+      secondaryOutlineColor,
+      secondarySizeScale,
+      updateTriggers
+    } = this.props;
+    const getPixelOffset = this.calculatePixelOffset(false);
+    const backgroundPadding = this.calculateBackgroundPadding();
+    const out = [
+      // Text doesn't update via updateTrigger for some reason
+      this.renderTextLayer(`${updateTriggers.getText}-primary`, {
+        backgroundPadding,
+        getText,
+        getPixelOffset,
+        background: true // Only use background for primary label for faster collisions
+      }),
+      Boolean(getSecondaryText) &&
+        this.renderTextLayer(`${updateTriggers.getSecondaryText}-secondary`, {
+          getText: getSecondaryText,
+          getPixelOffset: this.calculatePixelOffset(true),
+          getAlignmentBaseline: 'top',
+          // updateTriggers: {getText: updateTriggers.getSecondaryText},
+
+          // Optional overrides
+          ...(getSecondaryColor && {getColor: getSecondaryColor}),
+          ...(secondarySizeScale && {sizeScale: secondarySizeScale}),
+          ...(secondaryOutlineColor && {outlineColor: secondaryOutlineColor})
+        })
+    ];
+
+    return out;
+  }
+}

package/src/layers/schema/carto-spatial-tile-loader.ts

@@ -1,7 +1,7 @@
 import {LoaderOptions, LoaderWithParser} from '@loaders.gl/loader-utils';
 
 import {Tile, TileReader} from './carto-spatial-tile';
-import {parsePbf, unpackProperties} from './tile-loader-utils';
+import {parsePbf} from './tile-loader-utils';
 import {IndexScheme, binaryToSpatialjson, SpatialJson} from './spatialjson-utils';
 
 const CartoSpatialTileLoader: LoaderWithParser = {
@@ -31,10 +31,7 @@ function parseCartoSpatialTile(
 
   const {cells} = tile;
   const scheme = options?.cartoSpatialTile?.scheme;
-  const data = {
-    cells: {...cells, properties: unpackProperties(cells.properties)},
-    scheme
-  };
+  const data = {cells, scheme};
 
   return binaryToSpatialjson(data);
 }

package/src/layers/schema/carto-spatial-tile.ts

@@ -1,20 +1,15 @@
+import {readPackedFixed64} from './fast-pbf';
 import {Indices, IndexScheme} from './spatialjson-utils';
-import {
-  KeyValueProperties,
-  NumericProp,
-  NumericPropKeyValueReader,
-  PropertiesReader
-} from './carto-tile';
+import {NumericProp, NumericPropKeyValueReader, PropertiesReader} from './carto-tile';
 
 // Indices =====================================
 
 export class IndicesReader {
   static read(pbf, end?: number): Indices {
-    const {value} = pbf.readFields(IndicesReader._readField, {value: []}, end);
-    return {value: new BigUint64Array(value)};
+    return pbf.readFields(IndicesReader._readField, {value: []}, end);
   }
   static _readField(this: void, tag: number, obj, pbf) {
-    if (tag === 1) readPackedFixed64(pbf, obj.value);
+    if (tag === 1) readPackedFixed64(pbf, obj);
   }
 }
 
@@ -22,7 +17,7 @@ export class IndicesReader {
 
 interface Cells {
   indices: Indices;
-  properties: KeyValueProperties[];
+  properties: Record<string, string>[];
   numericProps: Record<string, NumericProp>;
 }
 
@@ -61,23 +56,3 @@ export class TileReader {
     else if (tag === 2) obj.cells = CellsReader.read(pbf, pbf.readVarint() + pbf.pos);
   }
 }
-
-// pbf doesn't support BigInt natively, implement support for packed fixed64 type
-const SHIFT_LEFT_32 = BigInt((1 << 16) * (1 << 16));
-
-function readPackedEnd(pbf) {
-  return pbf.type === 2 ? pbf.readVarint() + pbf.pos : pbf.pos + 1;
-}
-function readFixed64(pbf) {
-  const a = BigInt(pbf.readFixed32());
-  const b = BigInt(pbf.readFixed32());
-  return a + b * SHIFT_LEFT_32;
-}
-
-function readPackedFixed64(pbf, arr) {
-  if (pbf.type !== 2) return arr.push(readFixed64(pbf));
-  const end = readPackedEnd(pbf);
-  arr = arr || [];
-  while (pbf.pos < end) arr.push(readFixed64(pbf));
-  return arr;
-}