@carto/api-client 0.5.0-alpha.9 → 0.5.0

package/src/fetch-map/types.ts

@@ -0,0 +1,268 @@
+import {LayerType, SCALE_TYPE} from './layer-map.js';
+import {Format, MapType, ProviderType, QueryParameters} from '../types.js';
+import {TilejsonResult, GeojsonResult, JsonResult} from '../sources/types.js';
+
+export type VisualChannelField = {
+  name: string;
+  type: string;
+  colorColumn?: string;
+};
+
+export type VisualChannels = {
+  colorField?: VisualChannelField;
+  colorScale?: SCALE_TYPE;
+
+  customMarkersField?: VisualChannelField;
+  customMarkersScale?: SCALE_TYPE;
+
+  radiusField?: VisualChannelField;
+  radiusScale?: SCALE_TYPE;
+
+  rotationScale?: SCALE_TYPE;
+  rotationField?: VisualChannelField;
+
+  sizeField?: VisualChannelField;
+  sizeScale?: SCALE_TYPE;
+
+  strokeColorField?: VisualChannelField;
+  strokeColorScale?: SCALE_TYPE;
+
+  heightField?: VisualChannelField;
+  heightScale?: SCALE_TYPE;
+
+  weightField?: VisualChannelField;
+};
+
+export type ColorRange = {
+  category: string;
+  colors: string[];
+  colorMap: string[][] | undefined;
+  name: string;
+  type: string;
+};
+
+export type CustomMarkersRange = {
+  markerMap: {
+    value: string;
+    markerUrl?: string;
+  }[];
+  othersMarker?: string;
+};
+
+export type VisConfig = {
+  filled?: boolean;
+  opacity?: number;
+  enable3d?: boolean;
+
+  colorAggregation?: any;
+  colorRange: ColorRange;
+
+  customMarkers?: boolean;
+  customMarkersRange?: CustomMarkersRange | null;
+  customMarkersUrl?: string | null;
+
+  radius: number;
+  radiusRange?: number[];
+
+  sizeAggregation?: any;
+  sizeRange?: any;
+
+  strokeColorAggregation?: any;
+  strokeOpacity?: number;
+  strokeColorRange?: ColorRange;
+
+  heightRange?: any;
+  heightAggregation?: any;
+
+  weightAggregation?: any;
+};
+
+export type TextLabel = {
+  field: VisualChannelField | null | undefined;
+  alignment?: 'center' | 'bottom' | 'top';
+  anchor?: 'middle' | 'start' | 'end';
+  size: number;
+  color?: number[];
+  offset?: [number, number];
+  outlineColor?: number[];
+};
+
+export type MapLayerConfig = {
+  columns?: Record<string, any>;
+  color?: number[];
+  label?: string;
+  dataId: string;
+  textLabel: TextLabel[];
+  visConfig: VisConfig;
+};
+
+export type MapConfigLayer = {
+  type: LayerType;
+  id: string;
+  config: MapLayerConfig;
+  visualChannels: VisualChannels;
+};
+
+export interface CustomStyle {
+  url?: string;
+  style?: any;
+  customAttribution?: string;
+}
+
+// TODO replace with more complete type from Builder
+export type KeplerMapConfig = {
+  filters: any;
+  mapState: any;
+  mapStyle: {
+    styleType: string;
+    visibleLayerGroups: Record<string, boolean>;
+  };
+  popupSettings: any;
+  visState: {
+    layers: MapConfigLayer[];
+    layerBlending: any;
+    interactionConfig: any;
+  };
+  customBaseMaps?: {
+    customStyle?: CustomStyle;
+  };
+};
+
+export type BasemapType = 'maplibre' | 'google-maps';
+
+export type Basemap = MapLibreBasemap | GoogleBasemap;
+
+export type BasemapCommon = {
+  /**
+   * Type of basemap.
+   */
+  type: BasemapType;
+
+  /**
+   * Custom attribution for style data if not provided by style definition.
+   */
+  attribution?: string;
+
+  /**
+   * Properties of the basemap. These properties are specific to the basemap type.
+   */
+  props: Record<string, any>;
+};
+
+export type MapLibreBasemap = BasemapCommon & {
+  type: 'maplibre';
+
+  /**
+   * MapLibre map properties.
+   *
+   * Meant to be passed to directly to `maplibregl.Map` object.
+   */
+  props: MapLibreBasemapProps;
+
+  /**
+   * Layer groups to be displayed in the basemap.
+   */
+  visibleLayerGroups?: Record<string, boolean>;
+
+  /**
+   * If `style` has been filtered by `visibleLayerGroups` then this property contains original style object, so user
+   * can use `applyLayerGroupFilters` again with new settings.
+   */
+  rawStyle?: string | Record<string, any>;
+};
+
+// Cherry-pick of maplibregl Map API props that are supported/provided by fetchMap interface
+export type MapLibreBasemapProps = {
+  style: string | Record<string, any>;
+  center: [number, number];
+  zoom: number;
+  pitch?: number;
+  bearing?: number;
+};
+
+export type GoogleBasemap = BasemapCommon & {
+  type: 'google-maps';
+
+  /**
+   * Google map properties.
+   *
+   * Meant to be passed to directly to `google.maps.Map` object.
+   */
+  props: GoogleBasemapProps;
+};
+
+// Cherry-pick of Google Map API props that are supported/provided by fetchMap interface
+export type GoogleBasemapProps = {
+  mapTypeId: string;
+  mapId?: string;
+  center?: {lat: number; lng: number};
+  zoom?: number;
+  tilt?: number;
+  heading?: number;
+};
+
+export type Dataset = {
+  id: string;
+  type: MapType;
+  source: string;
+  cache?: number;
+  connectionName: string;
+  geoColumn: string;
+  data: TilejsonResult | GeojsonResult | JsonResult;
+  columns: string[];
+  format: Format;
+  aggregationExp: string;
+  aggregationResLevel: number;
+  queryParameters: QueryParameters;
+  connectionId?: string;
+  providerId: ProviderType;
+  createdAt?: string;
+  updatedAt?: string;
+  label?: string;
+  color?: string;
+  uniqueIdProperty?: string;
+  queryTemplate?: string | null;
+  name?: string | null;
+  spatialIndex?: string | null;
+  exportToBucketAvailable?: boolean;
+};
+
+export type AttributeType = 'String' | 'Number' | 'Timestamp' | 'Boolean';
+
+export type AttributeStatsBase = {
+  attribute: string;
+  type: AttributeType;
+};
+
+export type AttributeStatsNumber = AttributeStatsBase & {
+  type: 'Number';
+  min: number;
+  avg: number;
+  max: number;
+  sum: number;
+  quantiles: number[][];
+};
+
+export type AttributeStatsTimestamp = AttributeStatsBase & {
+  type: 'Timestamp';
+  min: string;
+  max: string;
+};
+
+export interface AttributeStatsStringCategory {
+  category: string;
+  frequency: number;
+}
+
+export type AttributeStatsString = AttributeStatsBase & {
+  type: 'String' | 'Boolean';
+  categories: AttributeStatsStringCategory[];
+};
+
+/**
+ * Result of getAttributeStats request to backend.
+ */
+export type AttributeStats =
+  | AttributeStatsString
+  | AttributeStatsNumber
+  | AttributeStatsTimestamp;

package/src/fetch-map/utils.ts

@@ -0,0 +1,69 @@
+import type {BinaryFeature} from '@loaders.gl/schema';
+import type {Dataset} from './types.js';
+type Properties = BinaryFeature['properties'];
+type NumericProps = BinaryFeature['numericProps'];
+
+// Returns a Proxy object that allows accessing binary data
+// as if it were JSON properties
+export function createBinaryProxy(
+  data: {numericProps: NumericProps; properties: Properties[]},
+  index: number
+) {
+  const {properties, numericProps} = data;
+  return new Proxy(properties[index] || {}, {
+    get(target, property) {
+      if (property in numericProps) {
+        return numericProps[property as string].value[index];
+      }
+      return target[property as any];
+    },
+
+    has(target, property) {
+      return property in numericProps || property in target;
+    },
+
+    ownKeys(target) {
+      return [...Object.keys(numericProps), ...Reflect.ownKeys(target)];
+    },
+
+    getOwnPropertyDescriptor() {
+      return {enumerable: true, configurable: true};
+    },
+  });
+}
+
+export function scaleIdentity() {
+  let unknown: any;
+
+  function scale(x: any) {
+    return x === null ? unknown : x;
+  }
+
+  scale.invert = scale;
+
+  scale.domain = scale.range = (d: any) => d;
+
+  scale.unknown = (u: any) => {
+    if (u) {
+      unknown = u;
+    }
+
+    return unknown;
+  };
+
+  scale.copy = () => {
+    const scaleCopy = scaleIdentity();
+    scaleCopy.unknown(unknown);
+    return scaleCopy;
+  };
+
+  return scale;
+}
+
+export function isRemoteCalculationSupported(dataset: Dataset) {
+  if (dataset?.type === 'tileset' || dataset.providerId === 'databricks') {
+    return false;
+  }
+
+  return true;
+}

package/src/filters/tileFeatures.ts

@@ -1,10 +1,12 @@
-import {SpatialFilter, SpatialIndexTile, Tile} from '../types.js';
+import {RasterTile, SpatialFilter, SpatialIndexTile, Tile} from '../types.js';
 import {tileFeaturesGeometries} from './tileFeaturesGeometries.js';
 import {tileFeaturesSpatialIndex} from './tileFeaturesSpatialIndex.js';
 import {TileFormat} from '../constants.js';
 import {DEFAULT_GEO_COLUMN} from '../constants-internal.js';
 import {FeatureData} from '../types-internal.js';
-import {SpatialDataType} from '../sources/types.js';
+import {RasterMetadata, SpatialDataType} from '../sources/types.js';
+import {isRasterTile, tileFeaturesRaster} from './tileFeaturesRaster.js';
+import {assert} from '../utils.js';
 
 /** @privateRemarks Source: @carto/react-core */
 export type TileFeatures = {
@@ -14,12 +16,14 @@ export type TileFeatures = {
   spatialDataColumn?: string;
   spatialFilter: SpatialFilter;
   uniqueIdProperty?: string;
+  rasterMetadata?: RasterMetadata;
   options?: TileFeatureExtractOptions;
 };
 
 /** @privateRemarks Source: @carto/react-core */
 export type TileFeatureExtractOptions = {
   storeGeometry?: boolean;
+  uniqueIdProperty?: string;
 };
 
 /** @privateRemarks Source: @carto/react-core */
@@ -30,21 +34,34 @@ export function tileFeatures({
   tileFormat,
   spatialDataColumn = DEFAULT_GEO_COLUMN,
   spatialDataType,
+  rasterMetadata,
   options = {},
 }: TileFeatures): FeatureData[] {
-  if (spatialDataType !== 'geo') {
-    return tileFeaturesSpatialIndex({
-      tiles: tiles as SpatialIndexTile[],
+  if (spatialDataType === 'geo') {
+    return tileFeaturesGeometries({
+      tiles,
+      tileFormat,
+      spatialFilter,
+      uniqueIdProperty,
+      options,
+    });
+  }
+
+  if (tiles.some(isRasterTile)) {
+    assert(rasterMetadata, 'Missing raster metadata');
+    return tileFeaturesRaster({
+      tiles: tiles as RasterTile[],
       spatialFilter,
       spatialDataColumn,
       spatialDataType,
+      rasterMetadata,
     });
   }
-  return tileFeaturesGeometries({
-    tiles,
-    tileFormat,
+
+  return tileFeaturesSpatialIndex({
+    tiles: tiles as SpatialIndexTile[],
     spatialFilter,
-    uniqueIdProperty,
-    options,
+    spatialDataColumn,
+    spatialDataType,
   });
 }

package/src/filters/tileFeaturesRaster.ts

@@ -0,0 +1,122 @@
+import {
+  cellToChildren as _cellToChildren,
+  cellToTile,
+  geometryToCells,
+  getResolution,
+} from 'quadbin';
+import {RasterTile, SpatialFilter, Tile} from '../types.js';
+import {FeatureData} from '../types-internal.js';
+import {
+  RasterMetadata,
+  RasterMetadataBand,
+  SpatialDataType,
+} from '../sources/types.js';
+
+export type TileFeaturesRasterOptions = {
+  tiles: RasterTile[];
+  spatialFilter: SpatialFilter;
+  spatialDataColumn: string;
+  spatialDataType: SpatialDataType;
+  rasterMetadata: RasterMetadata;
+};
+
+export function tileFeaturesRaster({
+  tiles,
+  ...options
+}: TileFeaturesRasterOptions): FeatureData[] {
+  // Cache band metadata for faster lookup while iterating over pixels.
+  const metadataByBand: Record<string, RasterMetadataBand & {nodata: number}> =
+    {};
+  for (const band of options.rasterMetadata.bands) {
+    // TODO(cleanup): Remove copy and cast after API is updated to return 'nodata' as a number.
+    metadataByBand[band.name] = {...band, nodata: Number(band.nodata)};
+  }
+
+  // Omit empty and invisible tiles for simpler processing and types.
+  tiles = tiles.filter(isRasterTileVisible);
+  if (tiles.length === 0) return [];
+
+  // Raster tiles, and all pixels, are quadbin cells. Resolution of a pixel is
+  // the resolution of the tile, plus the number of subdivisions. Block size
+  // must be square, N x N, where N is a power of two.
+  const tileResolution = getResolution(tiles[0].index.q);
+  const tileBlockSize = tiles[0].data!.blockSize;
+  const cellResolution = tileResolution + BigInt(Math.log2(tileBlockSize));
+
+  // Compute covering cells for the spatial filter, at same resolution as the
+  // raster pixels, to be used as a mask.
+  const spatialFilterCells = new Set(
+    geometryToCells(options.spatialFilter, cellResolution)
+  );
+
+  const data = new Map<bigint, FeatureData>();
+
+  for (const tile of tiles as Required<RasterTile>[]) {
+    const parent = tile.index.q;
+
+    const children = cellToChildrenSorted(parent, cellResolution);
+
+    // For each pixel/cell within the spatial filter, create a FeatureData.
+    // Order is row-major, starting from NW and ending at SE.
+    for (let i = 0; i < children.length; i++) {
+      if (!spatialFilterCells.has(children[i])) continue;
+
+      const cellData: FeatureData = {};
+      let cellDataExists = false;
+
+      for (const band in tile.data.cells.numericProps) {
+        const value = tile.data.cells.numericProps[band].value[i];
+        const bandMetadata = metadataByBand[band];
+
+        if (isValidBandValue(value, bandMetadata.nodata)) {
+          cellData[band] = tile.data.cells.numericProps[band].value[i];
+          cellDataExists = true;
+        }
+      }
+
+      if (cellDataExists) {
+        data.set(children[i], cellData);
+      }
+    }
+  }
+
+  return Array.from(data.values());
+}
+
+/**
+ * Detects whether a given {@link Tile} is a {@link RasterTile}.
+ * @privateRemarks Method of detection is arbitrary, and may be changed.
+ */
+export function isRasterTile(tile: Tile): tile is RasterTile {
+  return !!(tile.data as Record<string, unknown>)?.cells;
+}
+
+function isRasterTileVisible(tile: RasterTile): tile is Required<RasterTile> {
+  return !!(tile.isVisible && tile.data?.cells?.numericProps);
+}
+
+/**
+ * For the raster format, children are sorted in row-major order, starting from
+ * NW and ending at SE. Order returned by quadbin's cellToChildren() is not
+ * defined (and not related to the raster format), so sort explicitly here.
+ */
+function cellToChildrenSorted(parent: bigint, resolution: bigint): bigint[] {
+  return _cellToChildren(parent, resolution).sort(
+    (cellA: bigint, cellB: bigint) => {
+      const tileA = cellToTile(cellA);
+      const tileB = cellToTile(cellB);
+      if (tileA.y !== tileB.y) {
+        return tileA.y > tileB.y ? 1 : -1;
+      }
+      return tileA.x > tileB.x ? 1 : -1;
+    }
+  );
+}
+
+/**
+ * Returns true if the given value is valid (not NaN, not 'nodata')
+ * for the given raster band.
+ */
+function isValidBandValue(value: unknown, nodata: number): value is number {
+  return Number.isNaN(value) ? false : nodata !== value;
+}

package/src/index.ts

@@ -1,6 +1,7 @@
 export * from './client.js';
 export * from './constants.js';
 export * from './deck/index.js';
+export * from './fetch-map/index.js';
 export * from './filters.js';
 export * from './geo.js';
 export * from './sources/index.js';

package/src/models/model.ts

@@ -39,10 +39,7 @@ export interface ModelSource {
   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;
@@ -86,7 +83,6 @@ export function executeModel(props: {
     filtersLogicalOperator = 'and',
     spatialDataType = 'geo',
     spatialFiltersMode = 'intersects',
-    spatialFiltersResolution = 0,
   } = source;
 
   const queryParams: Record<string, unknown> = {
@@ -118,9 +114,6 @@ export function executeModel(props: {
   }
 
   if (spatialDataType !== 'geo') {
-    if (spatialFiltersResolution > 0) {
-      queryParams.spatialFiltersResolution = spatialFiltersResolution;
-    }
     queryParams.spatialFiltersMode = spatialFiltersMode;
   }
 

package/src/sources/base-source.ts

@@ -18,9 +18,8 @@ import {MapType} from '../types.js';
 import {APIErrorContext} from '../api/index.js';
 import {getClient} from '../client.js';
 
-export const SOURCE_DEFAULTS: SourceOptionalOptions = {
+export const SOURCE_DEFAULTS: Omit<SourceOptionalOptions, 'clientId'> = {
   apiBaseUrl: DEFAULT_API_BASE_URL,
-  clientId: getClient(),
   format: 'tilejson',
   headers: {},
   maxLengthURL: DEFAULT_MAX_LENGTH_URL,
@@ -34,6 +33,7 @@ export async function baseSource<UrlParameters extends Record<string, unknown>>(
   const {accessToken, connectionName, cache, ...optionalOptions} = options;
   const mergedOptions = {
     ...SOURCE_DEFAULTS,
+    clientId: getClient(),
     accessToken,
     connectionName,
     endpoint,
@@ -80,6 +80,7 @@ export async function baseSource<UrlParameters extends Record<string, unknown>>(
   if (format === 'tilejson') {
     const json = await requestWithParameters<TilejsonResult>({
       baseUrl: dataUrl,
+      parameters: {client: clientId},
       headers,
       errorContext,
       maxLengthURL,
@@ -93,6 +94,7 @@ export async function baseSource<UrlParameters extends Record<string, unknown>>(
 
   return await requestWithParameters<GeojsonResult | JsonResult>({
     baseUrl: dataUrl,
+    parameters: {client: clientId},
     headers,
     errorContext,
     maxLengthURL,

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

@@ -2,12 +2,12 @@
 // SPDX-License-Identifier: MIT
 // Copyright (c) vis.gl contributors
 
+import {baseSource} from './base-source.js';
 import {getTileFormat} from '../utils/getTileFormat.js';
 import {
   WidgetTilesetSource,
   WidgetTilesetSourceResult,
 } from '../widget-sources/index.js';
-import {baseSource} from './base-source.js';
 import type {
   SourceOptions,
   TilejsonResult,

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

@@ -2,12 +2,12 @@
 // SPDX-License-Identifier: MIT
 // Copyright (c) vis.gl contributors
 
+import {baseSource} from './base-source.js';
 import {getTileFormat} from '../utils/getTileFormat.js';
 import {
   WidgetTilesetSource,
   WidgetTilesetSourceResult,
 } from '../widget-sources/index.js';
-import {baseSource} from './base-source.js';
 import type {
   SourceOptions,
   TilejsonResult,

package/src/sources/raster-source.ts

@@ -3,6 +3,12 @@
 // Copyright (c) vis.gl contributors
 
 import {baseSource} from './base-source.js';
+import {getTileFormat} from '../utils/getTileFormat.js';
+import {
+  WidgetRasterSource,
+  WidgetRasterSourceResult,
+} from '../widget-sources/index.js';
+
 import type {
   FilterOptions,
   SourceOptions,
@@ -18,7 +24,7 @@ type UrlParameters = {
   filters?: Record<string, unknown>;
 };
 
-export type RasterSourceResponse = TilejsonResult;
+export type RasterSourceResponse = TilejsonResult & WidgetRasterSourceResult;
 
 export const rasterSource = async function (
   options: RasterSourceOptions
@@ -29,9 +35,16 @@ export const rasterSource = async function (
     urlParameters.filters = filters;
   }
 
-  return baseSource<UrlParameters>(
-    'raster',
-    options,
-    urlParameters
+  return baseSource<UrlParameters>('raster', options, urlParameters).then(
+    (result) => ({
+      ...(result as TilejsonResult),
+      widgetSource: new WidgetRasterSource({
+        ...options,
+        tileFormat: getTileFormat(result as TilejsonResult),
+        spatialDataColumn: 'quadbin',
+        spatialDataType: 'quadbin',
+        rasterMetadata: (result as TilejsonResult).raster_metadata!,
+      }),
+    })
   ) as Promise<RasterSourceResponse>;
 };