Spatial index widgets

src/index.ts

@@ -4,6 +4,7 @@ export * from './filters.js';
 export * from './geo.js';
 export * from './widget-sources/index.js';
 export * from './types.js';
+export * from './spatial-index.js';
 
 export {
   APIErrorContext,

src/models/model.ts

@@ -10,6 +10,7 @@ import {$TODO} from '../types-internal.js';
 import {assert} from '../utils.js';
 import {ModelRequestOptions, makeCall} from './common.js';
 import {ApiVersion} from '../constants.js';
+import {SpatialDataType, SpatialFilterPolyfillMode} from '../sources/types.js';
 
 /** @internalRemarks Source: @carto/react-api */
 const AVAILABLE_MODELS = [
@@ -38,6 +39,12 @@ export interface ModelSource {
   geoColumn?: string;
   spatialFilter?: SpatialFilter;
   queryParameters?: QueryParameters;
+  spatialDataColumn?: string;
+  spatialDataType?: SpatialDataType;
+  spatialFiltersResolution?: number;
+  spatialFiltersMode?: SpatialFilterPolyfillMode;
+  /** original resolution of the spatial index data as stored in the DW */
+  dataResolution?: number;
 }
 
 const {V3} = ApiVersion;

src/sources/h3-query-source.ts

@@ -18,7 +18,10 @@ import type {
 export type H3QuerySourceOptions = SourceOptions &
   QuerySourceOptions &
   AggregationOptions &
-  FilterOptions;
+  FilterOptions & {
+    spatialDataType: 'h3';
+  };
+
 type UrlParameters = {
   aggregationExp: string;
   aggregationResLevel?: string;
@@ -30,7 +33,7 @@ type UrlParameters = {
 };
 
 export const h3QuerySource = async function (
-  options: H3QuerySourceOptions
+  options: Omit<H3QuerySourceOptions, 'spatialDataType'>
 ): Promise<TilejsonResult & WidgetQuerySourceResult> {
   const {
     aggregationExp,
@@ -59,7 +62,12 @@ export const h3QuerySource = async function (
   return baseSource<UrlParameters>('query', options, urlParameters).then(
     (result) => ({
       ...(result as TilejsonResult),
-      widgetSource: new WidgetQuerySource(options),
+      widgetSource: new WidgetQuerySource({
+        ...options,
+        // NOTE: passing redundant spatialDataColumn here to apply the default value 'h3'
+        spatialDataColumn,
+        spatialDataType: 'h3',
+      }),
     })
   );
 };

src/sources/h3-table-source.ts

@@ -18,7 +18,9 @@ import type {
 export type H3TableSourceOptions = SourceOptions &
   TableSourceOptions &
   AggregationOptions &
-  FilterOptions;
+  FilterOptions & {
+    spatialDataType: 'h3';
+  };
 
 type UrlParameters = {
   aggregationExp: string;
@@ -30,7 +32,7 @@ type UrlParameters = {
 };
 
 export const h3TableSource = async function (
-  options: H3TableSourceOptions
+  options: Omit<H3TableSourceOptions, 'spatialDataType'>
 ): Promise<TilejsonResult & WidgetTableSourceResult> {
   const {
     aggregationExp,
@@ -55,7 +57,12 @@ export const h3TableSource = async function (
   return baseSource<UrlParameters>('table', options, urlParameters).then(
     (result) => ({
       ...(result as TilejsonResult),
-      widgetSource: new WidgetTableSource(options),
+      widgetSource: new WidgetTableSource({
+        ...options,
+        // NOTE: passing redundant spatialDataColumn here to apply the default value 'h3'
+        spatialDataColumn,
+        spatialDataType: 'h3',
+      }),
     })
   );
 };

src/sources/quadbin-query-source.ts

@@ -18,7 +18,9 @@ import type {
 export type QuadbinQuerySourceOptions = SourceOptions &
   QuerySourceOptions &
   AggregationOptions &
-  FilterOptions;
+  FilterOptions & {
+    spatialDataType: 'quadbin';
+  };
 
 type UrlParameters = {
   aggregationExp: string;
@@ -31,7 +33,7 @@ type UrlParameters = {
 };
 
 export const quadbinQuerySource = async function (
-  options: QuadbinQuerySourceOptions
+  options: Omit<QuadbinQuerySourceOptions, 'spatialDataType'>
 ): Promise<TilejsonResult & WidgetQuerySourceResult> {
   const {
     aggregationExp,
@@ -60,7 +62,12 @@ export const quadbinQuerySource = async function (
   return baseSource<UrlParameters>('query', options, urlParameters).then(
     (result) => ({
       ...(result as TilejsonResult),
-      widgetSource: new WidgetQuerySource(options),
+      widgetSource: new WidgetQuerySource({
+        ...options,
+        // NOTE: passing redundant spatialDataColumn here to apply the default value 'quadbin'
+        spatialDataColumn,
+        spatialDataType: 'quadbin',
+      }),
     })
   );
 };

src/sources/quadbin-table-source.ts

@@ -18,7 +18,9 @@ import type {
 export type QuadbinTableSourceOptions = SourceOptions &
   TableSourceOptions &
   AggregationOptions &
-  FilterOptions;
+  FilterOptions & {
+    spatialDataType: 'quadbin';
+  };
 
 type UrlParameters = {
   aggregationExp: string;
@@ -30,7 +32,7 @@ type UrlParameters = {
 };
 
 export const quadbinTableSource = async function (
-  options: QuadbinTableSourceOptions
+  options: Omit<QuadbinTableSourceOptions, 'spatialDataType'>
 ): Promise<TilejsonResult & WidgetTableSourceResult> {
   const {
     aggregationExp,
@@ -56,7 +58,12 @@ export const quadbinTableSource = async function (
   return baseSource<UrlParameters>('table', options, urlParameters).then(
     (result) => ({
       ...(result as TilejsonResult),
-      widgetSource: new WidgetTableSource(options),
+      widgetSource: new WidgetTableSource({
+        ...options,
+        // NOTE: passing redundant spatialDataColumn here to apply the default value 'quadbin'
+        spatialDataColumn,
+        spatialDataType: 'quadbin',
+      }),
     })
   );
 };

src/sources/types.ts

@@ -177,6 +177,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[]};
 };

src/sources/vector-query-source.ts

@@ -21,7 +21,9 @@ import type {
 export type VectorQuerySourceOptions = SourceOptions &
   QuerySourceOptions &
   FilterOptions &
-  ColumnsOption;
+  ColumnsOption & {
+    spatialDataType: 'geo';
+  };
 
 type UrlParameters = {
   columns?: string;
@@ -34,7 +36,7 @@ type UrlParameters = {
 };
 
 export const vectorQuerySource = async function (
-  options: VectorQuerySourceOptions
+  options: Omit<VectorQuerySourceOptions, 'spatialDataType'>
 ): Promise<TilejsonResult & WidgetQuerySourceResult> {
   const {
     columns,
@@ -64,7 +66,10 @@ export const vectorQuerySource = async function (
   return baseSource<UrlParameters>('query', options, urlParameters).then(
     (result) => ({
       ...(result as TilejsonResult),
-      widgetSource: new WidgetQuerySource(options),
+      widgetSource: new WidgetQuerySource({
+        ...options,
+        spatialDataType: 'geo',
+      }),
     })
   );
 };

src/sources/vector-table-source.ts

@@ -21,7 +21,10 @@ import type {
 export type VectorTableSourceOptions = SourceOptions &
   TableSourceOptions &
   FilterOptions &
-  ColumnsOption;
+  ColumnsOption & {
+    spatialDataType: 'geo';
+  };
+
 type UrlParameters = {
   columns?: string;
   filters?: Record<string, unknown>;
@@ -32,7 +35,7 @@ type UrlParameters = {
 };
 
 export const vectorTableSource = async function (
-  options: VectorTableSourceOptions
+  options: Omit<VectorTableSourceOptions, 'spatialDataType'>
 ): Promise<TilejsonResult & WidgetTableSourceResult> {
   const {
     columns,
@@ -58,7 +61,10 @@ export const vectorTableSource = async function (
   return baseSource<UrlParameters>('table', options, urlParameters).then(
     (result) => ({
       ...(result as TilejsonResult),
-      widgetSource: new WidgetTableSource(options),
+      widgetSource: new WidgetTableSource({
+        ...options,
+        spatialDataType: 'geo',
+      }),
     })
   );
 };

src/spatial-index.ts

@@ -0,0 +1,125 @@
+import {
+  DEFAULT_AGGREGATION_RES_LEVEL_H3,
+  DEFAULT_AGGREGATION_RES_LEVEL_QUADBIN,
+} from './constants-internal';
+import {ModelSource} from './models/model';
+import {AggregationOptions} from './sources/types';
+
+const DEFAULT_TILE_SIZE = 512;
+const QUADBIN_ZOOM_MAX_OFFSET = 4;
+
+export function getSpatialFiltersResolution({
+  source,
+  viewState,
+}: {
+  source: ModelSource & AggregationOptions;
+  viewState: {
+    zoom: number;
+    latitude: number;
+    longitude: number;
+  };
+}) {
+  if (source.spatialDataType === 'geo') {
+    return undefined;
+  }
+
+  const currentZoom = viewState.zoom ?? 1;
+
+  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(currentZoom);
+  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(
+        {zoom: currentZoom, latitude: viewState.latitude},
+        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)
+  );
+}

src/widget-sources/types.ts

@@ -1,4 +1,4 @@
-import {TileResolution} from '../sources/types';
+import {SpatialFilterPolyfillMode, TileResolution} from '../sources/types';
 import {
   GroupDateType,
   SortColumnType,
@@ -13,6 +13,8 @@ import {
 /** Common options for {@link WidgetBaseSource} requests. */
 interface BaseRequestOptions {
   spatialFilter?: SpatialFilter;
+  spatialFiltersResolution?: number;
+  spatialFiltersMode?: SpatialFilterPolyfillMode;
   abortController?: AbortController;
   filterOwner?: string;
 }