@carto/api-client 0.4.3 → 0.5.0-alpha.0

package/src/sources/quadbin-tileset-source.ts

@@ -2,6 +2,11 @@
 // SPDX-License-Identifier: MIT
 // Copyright (c) vis.gl contributors
 
+import {getTileFormat} from '../utils/getTileFormat';
+import {
+  WidgetTilesetSource,
+  WidgetTilesetSourceResult,
+} from '../widget-sources';
 import {baseSource} from './base-source';
 import type {
   SourceOptions,
@@ -12,17 +17,24 @@ import type {
 export type QuadbinTilesetSourceOptions = SourceOptions & TilesetSourceOptions;
 type UrlParameters = {name: string};
 
-export type QuadbinTilesetSourceResponse = TilejsonResult;
+export type QuadbinTilesetSourceResponse = TilejsonResult &
+  WidgetTilesetSourceResult;
 
 export const quadbinTilesetSource = async function (
   options: QuadbinTilesetSourceOptions
 ): Promise<QuadbinTilesetSourceResponse> {
-  const {tableName} = options;
+  const {tableName, spatialDataColumn = 'quadbin'} = options;
   const urlParameters: UrlParameters = {name: tableName};
 
-  return baseSource<UrlParameters>(
-    'tileset',
-    options,
-    urlParameters
+  return baseSource<UrlParameters>('tileset', options, urlParameters).then(
+    (result) => ({
+      ...(result as TilejsonResult),
+      widgetSource: new WidgetTilesetSource({
+        ...options,
+        tileFormat: getTileFormat(result as TilejsonResult),
+        spatialDataColumn,
+        spatialDataType: 'quadbin',
+      }),
+    })
   ) as Promise<QuadbinTilesetSourceResponse>;
 };

package/src/sources/raster-source.ts

@@ -28,6 +28,7 @@ export const rasterSource = async function (
   if (filters) {
     urlParameters.filters = filters;
   }
+
   return baseSource<UrlParameters>(
     'raster',
     options,

package/src/sources/types.ts

@@ -48,6 +48,33 @@ export type SourceOptionalOptions = {
    */
   maxLengthURL?: number;
 
+  /**
+   * The column name and the type of geospatial support.
+   *
+   * If not present, defaults to `'geom'` for generic queries, `'quadbin'` for Quadbin sources and `'h3'` for H3 sources.
+   */
+  spatialDataColumn?: string;
+
+  /**
+   * The type of geospatial support. Defaults to `'geo'`.
+   */
+  spatialDataType?: SpatialDataType;
+
+  /**
+   * Relative resolution of a tile. Higher values increase density and data size. At `tileResolution = 1`, tile geometry is
+   * quantized to a 1024x1024 grid. Increasing or decreasing the resolution will increase or decrease the dimensions of
+   * the quantization grid proportionately.
+   *
+   * Supported `tileResolution` values, with corresponding grid sizes:
+   *
+   * - 0.25: 256x256
+   * - 0.5: 512x512
+   * - 1: 1024x1024
+   * - 2: 2048x2048
+   * - 4: 4096x4096
+   */
+  tileResolution?: TileResolution;
+
   /**
    * By default, local in-memory caching is enabled.
    */
@@ -89,6 +116,11 @@ export type AggregationOptions = {
    * @default 6 for quadbin and 4 for h3 sources
    */
   aggregationResLevel?: number;
+
+  /**
+   * Original resolution of the spatial index data as stored in the DW
+   */
+  dataResolution?: number;
 };
 
 export type FilterOptions = {
@@ -99,31 +131,9 @@ export type FilterOptions = {
 };
 
 export type QuerySourceOptions = {
-  /**
-   * The column name and the type of geospatial support.
-   *
-   * If not present, defaults to `'geom'` for generic queries, `'quadbin'` for Quadbin sources and `'h3'` for H3 sources.
-   */
-  spatialDataColumn?: string;
-
-  /** SQL query. */
+  /** Full SQL query with query paremeter placeholders (if any). */
   sqlQuery: string;
 
-  /**
-   * Relative resolution of a tile. Higher values increase density and data size. At `tileResolution = 1`, tile geometry is
-   * quantized to a 1024x1024 grid. Increasing or decreasing the resolution will increase or decrease the dimensions of
-   * the quantization grid proportionately.
-   *
-   * Supported `tileResolution` values, with corresponding grid sizes:
-   *
-   * - 0.25: 256x256
-   * - 0.5: 512x512
-   * - 1: 1024x1024
-   * - 2: 2048x2048
-   * - 4: 4096x4096
-   */
-  tileResolution?: TileResolution;
-
   /**
    * Values for named or positional paramteres in the query.
    *
@@ -166,28 +176,6 @@ export type TableSourceOptions = {
    */
   tableName: string;
 
-  /**
-   * The column name and the type of geospatial support.
-   *
-   * If not present, defaults to `'geom'` for generic tables, `'quadbin'` for Quadbin sources and `'h3'` for H3 sources.
-   */
-  spatialDataColumn?: string;
-
-  /**
-   * Relative resolution of a tile. Higher values increase density and data size. At `tileResolution = 1`, tile geometry is
-   * quantized to a 1024x1024 grid. Increasing or decreasing the resolution will increase or decrease the dimensions of
-   * the quantization grid proportionately.
-   *
-   * Supported `tileResolution` values, with corresponding grid sizes:
-   *
-   * - 0.25: 256x256
-   * - 0.5: 512x512
-   * - 1: 1024x1024
-   * - 2: 2048x2048
-   * - 4: 4096x4096
-   */
-  tileResolution?: TileResolution;
-
   /**
    * Comma-separated aggregation expressions. If assigned on a vector source, source is grouped by geometry and then aggregated.
    *
@@ -216,6 +204,14 @@ export type ColumnsOption = {
 
 export type SpatialDataType = 'geo' | 'h3' | 'quadbin';
 
+/**
+ * Strategy used for covering spatial filter geometry with spatial indexes.
+ * See https://docs.carto.com/data-and-analysis/analytics-toolbox-for-bigquery/sql-reference/quadbin#quadbin_polyfill_mode
+ * or https://docs.carto.com/data-and-analysis/analytics-toolbox-for-bigquery/sql-reference/h3#h3_polyfill_mode for more information.
+ * @internalRemarks Source: cloud-native maps-api
+ * */
+export type SpatialFilterPolyfillMode = 'center' | 'intersects' | 'contains';
+
 export type TilejsonMapInstantiation = MapInstantiation & {
   tilejson: {url: string[]};
 };

package/src/sources/vector-query-source.ts

@@ -3,7 +3,10 @@
 // Copyright (c) vis.gl contributors
 
 /* eslint-disable camelcase */
-import {DEFAULT_TILE_RESOLUTION} from '../constants-internal.js';
+import {
+  DEFAULT_GEO_COLUMN,
+  DEFAULT_TILE_RESOLUTION,
+} from '../constants-internal.js';
 import {
   WidgetQuerySource,
   WidgetQuerySourceResult,
@@ -43,7 +46,7 @@ export const vectorQuerySource = async function (
   const {
     columns,
     filters,
-    spatialDataColumn = 'geom',
+    spatialDataColumn = DEFAULT_GEO_COLUMN,
     sqlQuery,
     tileResolution = DEFAULT_TILE_RESOLUTION,
     queryParameters,
@@ -72,7 +75,11 @@ export const vectorQuerySource = async function (
   return baseSource<UrlParameters>('query', options, urlParameters).then(
     (result) => ({
       ...(result as TilejsonResult),
-      widgetSource: new WidgetQuerySource(options),
+      widgetSource: new WidgetQuerySource({
+        ...options,
+        spatialDataColumn,
+        spatialDataType: 'geo',
+      }),
     })
   );
 };

package/src/sources/vector-table-source.ts

@@ -3,7 +3,10 @@
 // Copyright (c) vis.gl contributors
 
 /* eslint-disable camelcase */
-import {DEFAULT_TILE_RESOLUTION} from '../constants-internal.js';
+import {
+  DEFAULT_GEO_COLUMN,
+  DEFAULT_TILE_RESOLUTION,
+} from '../constants-internal.js';
 import {
   WidgetTableSource,
   WidgetTableSourceResult,
@@ -42,7 +45,7 @@ export const vectorTableSource = async function (
   const {
     columns,
     filters,
-    spatialDataColumn = 'geom',
+    spatialDataColumn = DEFAULT_GEO_COLUMN,
     tableName,
     tileResolution = DEFAULT_TILE_RESOLUTION,
     aggregationExp,
@@ -67,7 +70,11 @@ export const vectorTableSource = async function (
   return baseSource<UrlParameters>('table', options, urlParameters).then(
     (result) => ({
       ...(result as TilejsonResult),
-      widgetSource: new WidgetTableSource(options),
+      widgetSource: new WidgetTableSource({
+        ...options,
+        spatialDataColumn,
+        spatialDataType: 'geo',
+      }),
     })
   );
 };

package/src/sources/vector-tileset-source.ts

@@ -2,6 +2,12 @@
 // SPDX-License-Identifier: MIT
 // Copyright (c) vis.gl contributors
 
+import {DEFAULT_GEO_COLUMN} from '../constants-internal';
+import {getTileFormat} from '../utils/getTileFormat';
+import {
+  WidgetTilesetSource,
+  WidgetTilesetSourceResult,
+} from '../widget-sources';
 import {baseSource} from './base-source';
 import type {
   SourceOptions,
@@ -12,17 +18,24 @@ import type {
 export type VectorTilesetSourceOptions = SourceOptions & TilesetSourceOptions;
 type UrlParameters = {name: string};
 
-export type VectorTilesetSourceResponse = TilejsonResult;
+export type VectorTilesetSourceResponse = TilejsonResult &
+  WidgetTilesetSourceResult;
 
 export const vectorTilesetSource = async function (
   options: VectorTilesetSourceOptions
 ): Promise<VectorTilesetSourceResponse> {
-  const {tableName} = options;
+  const {tableName, spatialDataColumn = DEFAULT_GEO_COLUMN} = options;
   const urlParameters: UrlParameters = {name: tableName};
 
-  return baseSource<UrlParameters>(
-    'tileset',
-    options,
-    urlParameters
+  return baseSource<UrlParameters>('tileset', options, urlParameters).then(
+    (result) => ({
+      ...(result as TilejsonResult),
+      widgetSource: new WidgetTilesetSource({
+        ...options,
+        tileFormat: getTileFormat(result as TilejsonResult),
+        spatialDataColumn,
+        spatialDataType: 'geo',
+      }),
+    })
   ) as Promise<VectorTilesetSourceResponse>;
 };

package/src/spatial-index.ts

@@ -0,0 +1,111 @@
+import {
+  DEFAULT_AGGREGATION_RES_LEVEL_H3,
+  DEFAULT_AGGREGATION_RES_LEVEL_QUADBIN,
+} from './constants-internal';
+import type {ModelSource} from './models/model';
+import type {AggregationOptions} from './sources/types';
+import {assert} from './utils';
+import type {ViewState} from './widget-sources';
+
+const DEFAULT_TILE_SIZE = 512;
+const QUADBIN_ZOOM_MAX_OFFSET = 4;
+
+export function getSpatialFiltersResolution(
+  source: Partial<ModelSource & AggregationOptions>,
+  viewState: ViewState
+): number | undefined {
+  const dataResolution = source.dataResolution ?? Number.MAX_VALUE;
+
+  const aggregationResLevel =
+    source.aggregationResLevel ??
+    (source.spatialDataType === 'h3'
+      ? DEFAULT_AGGREGATION_RES_LEVEL_H3
+      : DEFAULT_AGGREGATION_RES_LEVEL_QUADBIN);
+
+  const aggregationResLevelOffset = Math.max(
+    0,
+    Math.floor(aggregationResLevel)
+  );
+
+  const currentZoomInt = Math.ceil(viewState.zoom);
+  if (source.spatialDataType === 'h3') {
+    const tileSize = DEFAULT_TILE_SIZE;
+    const maxResolutionForZoom =
+      maxH3SpatialFiltersResolutions.find(
+        ([zoom]) => zoom === currentZoomInt
+      )?.[1] ?? Math.max(0, currentZoomInt - 3);
+
+    const maxSpatialFiltersResolution = maxResolutionForZoom
+      ? Math.min(dataResolution, maxResolutionForZoom)
+      : dataResolution;
+
+    const hexagonResolution =
+      getHexagonResolution(viewState, tileSize) + aggregationResLevelOffset;
+
+    return Math.min(hexagonResolution, maxSpatialFiltersResolution);
+  }
+
+  if (source.spatialDataType === 'quadbin') {
+    const maxResolutionForZoom = currentZoomInt + QUADBIN_ZOOM_MAX_OFFSET;
+    const maxSpatialFiltersResolution = Math.min(
+      dataResolution,
+      maxResolutionForZoom
+    );
+
+    const quadsResolution =
+      Math.floor(viewState.zoom) + aggregationResLevelOffset;
+    return Math.min(quadsResolution, maxSpatialFiltersResolution);
+  }
+
+  return undefined;
+}
+
+const maxH3SpatialFiltersResolutions = [
+  [20, 14],
+  [19, 13],
+  [18, 12],
+  [17, 11],
+  [16, 10],
+  [15, 9],
+  [14, 8],
+  [13, 7],
+  [12, 7],
+  [11, 7],
+  [10, 6],
+  [9, 6],
+  [8, 5],
+  [7, 4],
+  [6, 4],
+  [5, 3],
+  [4, 2],
+  [3, 1],
+  [2, 1],
+  [1, 0],
+];
+
+// stolen from https://github.com/visgl/deck.gl/blob/master/modules/carto/src/layers/h3-tileset-2d.ts
+
+// Relative scale factor (0 = no biasing, 2 = a few hexagons cover view)
+const BIAS = 2;
+
+// Resolution conversion function. Takes a WebMercatorViewport and returns
+// a H3 resolution such that the screen space size of the hexagons is
+// similar
+export function getHexagonResolution(
+  viewport: {zoom: number; latitude: number},
+  tileSize: number
+): number {
+  // Difference in given tile size compared to deck's internal 512px tile size,
+  // expressed as an offset to the viewport zoom.
+  const zoomOffset = Math.log2(tileSize / DEFAULT_TILE_SIZE);
+  const hexagonScaleFactor = (2 / 3) * (viewport.zoom - zoomOffset);
+  const latitudeScaleFactor = Math.log(
+    1 / Math.cos((Math.PI * viewport.latitude) / 180)
+  );
+
+  // Clip and bias
+  return Math.max(
+    0,
+    Math.floor(hexagonScaleFactor + latitudeScaleFactor - BIAS)
+  );
+}

package/src/types-internal.ts

@@ -60,3 +60,9 @@ type MapInstantiationFormats = Record<
     error?: any;
   }
 >;
+
+/******************************************************************************
+ * LOCAL CALCULATIONS
+ */
+
+export type FeatureData = Record<string, unknown>;

package/src/types.ts

@@ -1,5 +1,6 @@
 import type {FilterType} from './constants.js';
-import type {Polygon, MultiPolygon} from 'geojson';
+import type {Polygon, MultiPolygon, Feature} from 'geojson';
+import type {BinaryFeature, BinaryFeatureCollection} from '@loaders.gl/schema';
 
 /******************************************************************************
  * MAPS AND TILES
@@ -11,6 +12,43 @@ export type Format = 'json' | 'geojson' | 'tilejson';
 /** @internalRemarks Source: @carto/constants, @deck.gl/carto */
 export type MapType = 'boundary' | 'query' | 'table' | 'tileset' | 'raster';
 
+/**
+ * Alias for GeoJSON 'BBox' type, semantically representing a viewport.
+ * Order of values is "west", "south", "east", "north".
+ */
+export type Viewport = [number, number, number, number];
+
+/**
+ * Subset of deck.gl's Tile2DHeader type, containing only the properties
+ * required for local widget calculations. Deeper dependencies on deck.gl
+ * APIs should be minimized within this library: @deck.gl/carto depends
+ * on the API client, not the other way around.
+ * @internalRemarks Source: @deck.gl/geo-layers
+ */
+export type Tile = {
+  index: {x: number; y: number; z: number};
+  id: string;
+  content: unknown;
+  zoom: number;
+  bbox: {west: number; east: number; north: number; south: number};
+  isVisible: boolean;
+  data?: BinaryFeatureCollection;
+};
+
+/** Subset of deck.gl's Tile2DHeader type, for spatial indexes. */
+export type SpatialIndexTile = Tile & {
+  data?: (Feature & {id: bigint})[];
+};
+
+/** @internalRemarks Source: @deck.gl/carto */
+export type Raster = {
+  blockSize: number;
+  cells: {
+    numericProps: BinaryFeature['numericProps'];
+    properties: BinaryFeature['properties'];
+  };
+};
+
 /******************************************************************************
  * AGGREGATION
  */
@@ -49,12 +87,32 @@ export interface Filter {
   /** [a, b) a is included, b is not. */
   [FilterType.CLOSED_OPEN]?: {owner?: string; values: number[][]};
   [FilterType.TIME]?: {owner?: string; values: number[][]};
-  [FilterType.STRING_SEARCH]?: {owner?: string; values: string[]};
+  [FilterType.STRING_SEARCH]?: {
+    owner?: string;
+    values: string[];
+    params?: StringSearchOptions;
+  };
 }
 
 /** @internalRemarks Source: @carto/react-core */
 export type FilterLogicalOperator = 'and' | 'or';
 
+/**
+ * Type for minimum or maximum value of an interval. Values 'null' and
+ * 'undefined' are intentionally allowed, and represent an unbounded value.
+ */
+export type FilterIntervalExtremum = number | null | undefined;
+export type FilterInterval = [FilterIntervalExtremum, FilterIntervalExtremum];
+export type FilterIntervalComplete = [number, number];
+
+export type StringSearchOptions = {
+  useRegExp?: boolean;
+  mustStart?: boolean;
+  mustEnd?: boolean;
+  caseSensitive?: boolean;
+  keepSpecialCharacters?: boolean;
+};
+
 /******************************************************************************
  * GROUPING
  */

package/src/utils/dateUtils.ts

@@ -0,0 +1,28 @@
+/**
+ * Returns midnight (local time) on the Monday preceeding a given date, in
+ * milliseconds since the UNIX epoch.
+ */
+export function getMonday(date: number | Date): number {
+  const dateCp = new Date(date);
+  const day = dateCp.getDay();
+  const diff = dateCp.getDate() - day + (day ? 1 : -6); // adjust when day is sunday
+  dateCp.setDate(diff);
+  dateCp.setHours(0, 0, 0, 0);
+  return dateCp.getTime();
+}
+
+/**
+ * Returns midnight (UTC) on the Monday preceeding a given date, in
+ * milliseconds since the UNIX epoch.
+ */
+export function getUTCMonday(date: number | Date): number {
+  const dateCp = new Date(date);
+  const day = dateCp.getUTCDay();
+  const diff = dateCp.getUTCDate() - day + (day ? 1 : -6); // adjust when day is sunday
+  dateCp.setUTCDate(diff);
+  return Date.UTC(
+    dateCp.getUTCFullYear(),
+    dateCp.getUTCMonth(),
+    dateCp.getUTCDate()
+  );
+}

package/src/utils/getTileFormat.ts

@@ -0,0 +1,9 @@
+import {TileFormat} from '../constants.js';
+import {Tilejson} from '../sources/types.js';
+
+export function getTileFormat(tilejson: Tilejson): TileFormat {
+  const tileParams = new URL(tilejson.tiles[0]).searchParams;
+  return tileParams.get('formatTiles') === 'mvt'
+    ? TileFormat.MVT
+    : TileFormat.BINARY;
+}

package/src/utils/makeIntervalComplete.ts

@@ -0,0 +1,17 @@
+import {FilterInterval, FilterIntervalComplete} from '../types';
+
+export function makeIntervalComplete(
+  intervals: FilterInterval[]
+): FilterIntervalComplete[] {
+  return intervals.map((val) => {
+    if (val[0] === undefined || val[0] === null) {
+      return [Number.MIN_SAFE_INTEGER, val[1]];
+    }
+
+    if (val[1] === undefined || val[1] === null) {
+      return [val[0], Number.MAX_SAFE_INTEGER];
+    }
+
+    return val;
+  }) as FilterIntervalComplete[];
+}

package/src/utils/transformTileCoordsToWGS84.ts

@@ -0,0 +1,77 @@
+import {lerp} from '@math.gl/core';
+import {lngLatToWorld, worldToLngLat} from '@math.gl/web-mercator';
+import {BBox, GeoJsonGeometryTypes, Geometry, Position} from 'geojson';
+
+type TransformFn = (coordinates: any[], bbox: Position[]) => any[];
+
+const TRANSFORM_FN: Record<
+  Exclude<GeoJsonGeometryTypes, 'GeometryCollection'>,
+  TransformFn
+> = {
+  Point: transformPoint,
+  MultiPoint: transformMultiPoint,
+  LineString: transformLineString,
+  MultiLineString: transformMultiLineString,
+  Polygon: transformPolygon,
+  MultiPolygon: transformMultiPolygon,
+};
+
+/**
+ * Transform tile coords to WGS84 coordinates.
+ *
+ * @param geometry - any valid geojson geometry
+ * @param bbox - geojson bbox
+ */
+export function transformTileCoordsToWGS84<T extends Geometry>(
+  geometry: T,
+  bbox: BBox
+): T {
+  const [west, south, east, north] = bbox;
+  const nw = lngLatToWorld([west, north]);
+  const se = lngLatToWorld([east, south]);
+  const projectedBbox = [nw, se];
+
+  if (geometry.type === 'GeometryCollection') {
+    throw new Error('Unsupported geometry type GeometryCollection');
+  }
+
+  const transformFn = TRANSFORM_FN[geometry.type];
+  const coordinates = transformFn(geometry.coordinates, projectedBbox);
+  return {...geometry, coordinates};
+}
+
+function transformPoint([pointX, pointY]: Position, [nw, se]: Position[]) {
+  const x = lerp(nw[0], se[0], pointX);
+  const y = lerp(nw[1], se[1], pointY);
+
+  return worldToLngLat([x, y]);
+}
+
+function getPoints(geometry: Position[], bbox: Position[]) {
+  return geometry.map((g) => transformPoint(g, bbox));
+}
+
+function transformMultiPoint(multiPoint: Position[], bbox: Position[]) {
+  return getPoints(multiPoint, bbox);
+}
+
+function transformLineString(line: Position[], bbox: Position[]) {
+  return getPoints(line, bbox);
+}
+
+function transformMultiLineString(
+  multiLineString: Position[][],
+  bbox: Position[]
+) {
+  return multiLineString.map((lineString) =>
+    transformLineString(lineString, bbox)
+  );
+}
+
+function transformPolygon(polygon: Position[][], bbox: Position[]) {
+  return polygon.map((polygonRing) => getPoints(polygonRing, bbox));
+}
+
+function transformMultiPolygon(multiPolygon: Position[][][], bbox: Position[]) {
+  return multiPolygon.map((polygon) => transformPolygon(polygon, bbox));
+}