@carto/api-client 0.5.0-alpha.2 → 0.5.0-alpha.3

package/build/filters/tileFeatures.d.ts

@@ -1,7 +1,7 @@
 import { SpatialFilter, Tile } from '../types';
 import { TileFormat } from '../constants';
 import { FeatureData } from '../types-internal';
-import { SpatialDataType } from '../sources/types';
+import { RasterMetadata, SpatialDataType } from '../sources/types';
 /** @internalRemarks Source: @carto/react-core */
 export type TileFeatures = {
     tiles: Tile[];
@@ -10,6 +10,7 @@ export type TileFeatures = {
     spatialDataColumn?: string;
     spatialFilter?: SpatialFilter;
     uniqueIdProperty?: string;
+    rasterMetadata?: RasterMetadata;
     options?: TileFeatureExtractOptions;
 };
 /** @internalRemarks Source: @carto/react-core */
@@ -17,4 +18,4 @@ export type TileFeatureExtractOptions = {
     storeGeometry?: boolean;
 };
 /** @internalRemarks Source: @carto/react-core */
-export declare function tileFeatures({ tiles, spatialFilter, uniqueIdProperty, tileFormat, spatialDataColumn, spatialDataType, options, }: TileFeatures): FeatureData[];
+export declare function tileFeatures({ tiles, spatialFilter, uniqueIdProperty, tileFormat, spatialDataColumn, spatialDataType, rasterMetadata, options, }: TileFeatures): FeatureData[];

package/build/filters/tileFeaturesRaster.d.ts

@@ -0,0 +1,16 @@
+import { RasterTile, SpatialFilter, Tile } from '../types';
+import { FeatureData } from '../types-internal';
+import { RasterMetadata, SpatialDataType } from '../sources/types';
+export type TileFeaturesRasterOptions = {
+    tiles: RasterTile[];
+    spatialFilter: SpatialFilter;
+    spatialDataColumn: string;
+    spatialDataType: SpatialDataType;
+    rasterMetadata: RasterMetadata;
+};
+export declare function tileFeaturesRaster({ tiles, ...options }: TileFeaturesRasterOptions): FeatureData[];
+/**
+ * Detects whether a given {@link Tile} is a {@link RasterTile}.
+ * @privateRemarks Method of detection is arbitrary, and may be changed.
+ */
+export declare function isRasterTile(tile: Tile): tile is RasterTile;

package/build/index.d.ts

@@ -8,6 +8,7 @@ export * from './types.js';
 export { APIErrorContext, APIRequestType, CartoAPIError, QueryOptions, buildPublicMapUrl, // Internal, but required for fetchMap().
 buildStatsUrl, // Internal, but required for fetchMap().
 query, requestWithParameters, } from './api/index.js';
+export { _getHexagonResolution } from './spatial-index.js';
 export * from './filters/index.js';
 export * from './operations/index.js';
 export * from './utils/makeIntervalComplete.js';

package/build/sources/raster-source.d.ts

@@ -1,4 +1,5 @@
+import { WidgetRasterSourceResult } from '../widget-sources';
 import type { FilterOptions, SourceOptions, TilejsonResult, TilesetSourceOptions } from './types';
 export type RasterSourceOptions = SourceOptions & TilesetSourceOptions & FilterOptions;
-export type RasterSourceResponse = TilejsonResult;
+export type RasterSourceResponse = TilejsonResult & WidgetRasterSourceResult;
 export declare const rasterSource: (options: RasterSourceOptions) => Promise<RasterSourceResponse>;

package/build/sources/types.d.ts

@@ -319,7 +319,7 @@ export type RasterMetadataBand = {
     /**
      * Default color mapping for unique values (or if coloprinterp is `palette`)
      */
-    colortable?: Record<string, number[]>;
+    colortable?: Record<string, [number, number, number, number]>;
     /**
      * No value representation.
      * Observed values:

package/build/spatial-index.d.ts

@@ -2,7 +2,13 @@ import type { ModelSource } from './models/model';
 import type { AggregationOptions } from './sources/types';
 import type { ViewState } from './widget-sources';
 export declare function getSpatialFiltersResolution(source: Partial<ModelSource & AggregationOptions>, viewState: ViewState): number | undefined;
-export declare function getHexagonResolution(viewport: {
+/**
+ * Resolution conversion function. Takes a WebMercatorViewport and returns
+ * a H3 resolution such that the screen space size of the hexagons is
+ * "similar" to the given tileSize on screen. Intended for use with deck.gl.
+ * @internal
+ */
+export declare function _getHexagonResolution(viewport: {
     zoom: number;
     latitude: number;
 }, tileSize: number): number;

package/build/types.d.ts

@@ -44,6 +44,14 @@ export type SpatialIndexTile = Tile & {
         id: bigint;
     })[];
 };
+export type RasterTile = Tile & {
+    id: string;
+    index: {
+        q: bigint;
+        i: string;
+    };
+    data?: Raster;
+};
 /** @internalRemarks Source: @deck.gl/carto */
 export type Raster = {
     blockSize: number;

package/build/widget-sources/index.d.ts

@@ -1,5 +1,6 @@
 export * from './widget-source.js';
 export * from './widget-query-source.js';
+export * from './widget-raster-source.js';
 export * from './widget-remote-source.js';
 export * from './widget-table-source.js';
 export * from './widget-tileset-source.js';

package/build/widget-sources/widget-raster-source.d.ts

@@ -0,0 +1,11 @@
+import { RasterMetadata } from '../sources/index.js';
+import { WidgetTilesetSource, WidgetTilesetSourceProps } from './widget-tileset-source.js';
+export type WidgetRasterSourceProps = WidgetTilesetSourceProps & {
+    rasterMetadata: RasterMetadata;
+    spatialDataType: 'quadbin';
+};
+export type WidgetRasterSourceResult = {
+    widgetSource: WidgetRasterSource;
+};
+export declare class WidgetRasterSource extends WidgetTilesetSource<WidgetRasterSourceProps> {
+}

package/build/widget-sources/widget-tileset-source.d.ts

@@ -2,8 +2,9 @@ import { TilesetSourceOptions } from '../sources/index.js';
 import type { ModelSource } from '../models/index.js';
 import { CategoryRequestOptions, CategoryResponse, FeaturesRequestOptions, FeaturesResponse, FormulaRequestOptions, FormulaResponse, HistogramRequestOptions, HistogramResponse, RangeRequestOptions, RangeResponse, ScatterRequestOptions, ScatterResponse, TableRequestOptions, TableResponse, TimeSeriesRequestOptions, TimeSeriesResponse } from './types.js';
 import { TileFormat } from '../constants.js';
-import { SpatialFilter } from '../types.js';
+import { SpatialFilter, Tile } from '../types.js';
 import { TileFeatureExtractOptions } from '../filters/index.js';
+import { FeatureData } from '../types-internal.js';
 import { FeatureCollection } from 'geojson';
 import { SpatialDataType } from '../sources/types.js';
 import { WidgetSource, WidgetSourceProps } from './widget-source.js';
@@ -36,9 +37,9 @@ export type WidgetTilesetSourceResult = {
  * const { widgetSource } = await data;
  * ```
  */
-export declare class WidgetTilesetSource extends WidgetSource<WidgetTilesetSourceProps> {
-    private _tiles;
-    private _features;
+export declare class WidgetTilesetSource<Props extends WidgetTilesetSourceProps = WidgetTilesetSourceProps> extends WidgetSource<Props> {
+    protected _tiles: Tile[];
+    protected _features: FeatureData[];
     protected getModelSource(owner: string): ModelSource;
     /**
      * Loads features as a list of tiles (typically provided by deck.gl).

package/package.json

@@ -1,10 +1,14 @@
 {
   "name": "@carto/api-client",
   "description": "Client library for CARTO APIs and framework-agnostic CARTO + deck.gl applications",
-  "repository": "github:CartoDB/carto-api-client",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/CartoDB/carto-api-client.git"
+  },
+  "homepage": "https://github.com/CartoDB/carto-api-client#readme",
   "author": "Don McCurdy <donmccurdy@carto.com>",
   "packageManager": "yarn@4.3.1",
-  "version": "0.5.0-alpha.2",
+  "version": "0.5.0-alpha.3",
   "license": "MIT",
   "publishConfig": {
     "access": "public",
@@ -62,7 +66,8 @@
     "@turf/invariant": "^7.1.0",
     "@turf/union": "^7.1.0",
     "@types/geojson": "^7946.0.15",
-    "h3-js": "4.1.0"
+    "h3-js": "4.1.0",
+    "quadbin": "^0.4.0-alpha.2"
   },
   "devDependencies": {
     "@deck.gl/aggregation-layers": "^9.0.38",
@@ -75,12 +80,13 @@
     "@lit/react": "^1.0.6",
     "@lit/task": "^1.0.1",
     "@loaders.gl/core": "^4.3.3",
-    "@luma.gl/core": "9.0.27",
-    "@luma.gl/engine": "9.0.27",
+    "@luma.gl/core": "~9.0.27",
+    "@luma.gl/engine": "~9.0.27",
+    "@turf/buffer": "^7.2.0",
     "@types/json-schema": "^7.0.15",
     "@types/react": "^18.3.18",
     "@types/semver": "^7.5.8",
-    "@vitest/coverage-istanbul": "^2.1.8",
+    "@vitest/coverage-istanbul": "^3.0.2",
     "@webcomponents/webcomponentsjs": "^2.8.0",
     "concurrently": "^9.1.2",
     "echarts": "^5.6.0",

package/src/filters/tileFeatures.ts

@@ -1,10 +1,12 @@
-import {SpatialFilter, SpatialIndexTile, Tile} from '../types';
+import {RasterTile, SpatialFilter, SpatialIndexTile, Tile} from '../types';
 import {tileFeaturesGeometries} from './tileFeaturesGeometries';
 import {tileFeaturesSpatialIndex} from './tileFeaturesSpatialIndex';
-import {SpatialIndex, TileFormat} from '../constants';
+import {TileFormat} from '../constants';
 import {DEFAULT_GEO_COLUMN} from '../constants-internal';
 import {FeatureData} from '../types-internal';
-import {SpatialDataType} from '../sources/types';
+import {RasterMetadata, SpatialDataType} from '../sources/types';
+import {isRasterTile, tileFeaturesRaster} from './tileFeaturesRaster';
+import {assert} from '../utils';
 
 /** @internalRemarks Source: @carto/react-core */
 export type TileFeatures = {
@@ -14,6 +16,7 @@ export type TileFeatures = {
   spatialDataColumn?: string;
   spatialFilter?: SpatialFilter;
   uniqueIdProperty?: string;
+  rasterMetadata?: RasterMetadata;
   options?: TileFeatureExtractOptions;
 };
 
@@ -30,6 +33,7 @@ export function tileFeatures({
   tileFormat,
   spatialDataColumn = DEFAULT_GEO_COLUMN,
   spatialDataType,
+  rasterMetadata,
   options = {},
 }: TileFeatures): FeatureData[] {
   // TODO(cleanup): Is an empty response the expected result when spatialFilter
@@ -38,19 +42,31 @@ export function tileFeatures({
     return [];
   }
 
-  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,111 @@
+import {
+  cellToChildren as _cellToChildren,
+  cellToTile,
+  geometryToCells,
+  getResolution,
+} from 'quadbin';
+import {RasterTile, SpatialFilter, Tile} from '../types';
+import {FeatureData} from '../types-internal';
+import {
+  RasterMetadata,
+  RasterMetadataBand,
+  SpatialDataType,
+} from '../sources/types';
+
+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 bandMetadataByName: Record<string, RasterMetadataBand> = {};
+  for (const band of options.rasterMetadata.bands) {
+    bandMetadataByName[band.name] = band;
+  }
+
+  // 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 as bigint);
+  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 as bigint;
+
+    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];
+        // TODO(cleanup): nodata should be a number, not a string.
+        if (Number(bandMetadataByName[band].nodata) !== value) {
+          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 ? tile.data.hasOwnProperty('cells') : false;
+}
+
+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;
+    }
+  );
+}

package/src/index.ts

@@ -17,6 +17,8 @@ export {
   requestWithParameters,
 } from './api/index.js';
 
+export {_getHexagonResolution} from './spatial-index.js';
+
 // For unit testing only.
 export * from './filters/index.js';
 export * from './operations/index.js';

package/src/sources/raster-source.ts

@@ -2,6 +2,8 @@
 // SPDX-License-Identifier: MIT
 // Copyright (c) vis.gl contributors
 
+import {getTileFormat} from '../utils/getTileFormat';
+import {WidgetRasterSource, WidgetRasterSourceResult} from '../widget-sources';
 import {baseSource} from './base-source';
 import type {
   FilterOptions,
@@ -18,7 +20,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 +31,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>;
 };

package/src/sources/types.ts

@@ -373,7 +373,7 @@ export type RasterMetadataBand = {
   /**
    * Default color mapping for unique values (or if coloprinterp is `palette`)
    */
-  colortable?: Record<string, number[]>;
+  colortable?: Record<string, [number, number, number, number]>;
 
   /**
    * No value representation.

package/src/spatial-index.ts

@@ -4,7 +4,6 @@ import {
 } 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;
@@ -40,7 +39,7 @@ export function getSpatialFiltersResolution(
       : dataResolution;
 
     const hexagonResolution =
-      getHexagonResolution(viewState, tileSize) + aggregationResLevelOffset;
+      _getHexagonResolution(viewState, tileSize) + aggregationResLevelOffset;
 
     return Math.min(hexagonResolution, maxSpatialFiltersResolution);
   }
@@ -88,10 +87,13 @@ const maxH3SpatialFiltersResolutions = [
 // 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(
+/**
+ * Resolution conversion function. Takes a WebMercatorViewport and returns
+ * a H3 resolution such that the screen space size of the hexagons is
+ * "similar" to the given tileSize on screen. Intended for use with deck.gl.
+ * @internal
+ */
+export function _getHexagonResolution(
   viewport: {zoom: number; latitude: number},
   tileSize: number
 ): number {

package/src/types.ts

@@ -40,6 +40,12 @@ export type SpatialIndexTile = Tile & {
   data?: (Feature & {id: bigint})[];
 };
 
+export type RasterTile = Tile & {
+  id: string;
+  index: {q: bigint; i: string};
+  data?: Raster;
+};
+
 /** @internalRemarks Source: @deck.gl/carto */
 export type Raster = {
   blockSize: number;

package/src/widget-sources/index.ts

@@ -1,5 +1,6 @@
 export * from './widget-source.js';
 export * from './widget-query-source.js';
+export * from './widget-raster-source.js';
 export * from './widget-remote-source.js';
 export * from './widget-table-source.js';
 export * from './widget-tileset-source.js';

package/src/widget-sources/widget-raster-source.ts

@@ -0,0 +1,14 @@
+import {RasterMetadata} from '../sources/index.js';
+import {
+  WidgetTilesetSource,
+  WidgetTilesetSourceProps,
+} from './widget-tileset-source.js';
+
+export type WidgetRasterSourceProps = WidgetTilesetSourceProps & {
+  rasterMetadata: RasterMetadata;
+  spatialDataType: 'quadbin';
+};
+
+export type WidgetRasterSourceResult = {widgetSource: WidgetRasterSource};
+
+export class WidgetRasterSource extends WidgetTilesetSource<WidgetRasterSourceProps> {}

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

@@ -75,9 +75,11 @@ export type WidgetTilesetSourceResult = {widgetSource: WidgetTilesetSource};
  * const { widgetSource } = await data;
  * ```
  */
-export class WidgetTilesetSource extends WidgetSource<WidgetTilesetSourceProps> {
-  private _tiles: Tile[] = [];
-  private _features: FeatureData[] = [];
+export class WidgetTilesetSource<
+  Props extends WidgetTilesetSourceProps = WidgetTilesetSourceProps,
+> extends WidgetSource<Props> {
+  protected _tiles: Tile[] = [];
+  protected _features: FeatureData[] = [];
 
   protected override getModelSource(owner: string): ModelSource {
     return {
@@ -106,9 +108,6 @@ export class WidgetTilesetSource extends WidgetSource<WidgetTilesetSourceProps>
     options,
   }: {
     spatialFilter: SpatialFilter;
-    // TODO(cleanup): As an optional property, 'uniqueIdProperty' will be easy to forget.
-    // Would it be better to configure it on the source function, rather than separately
-    // on the layer and in 'loadTiles()'?
     uniqueIdProperty?: string;
     options?: TileFeatureExtractOptions;
   }) {
@@ -117,9 +116,7 @@ export class WidgetTilesetSource extends WidgetSource<WidgetTilesetSourceProps>
       options,
       spatialFilter,
       uniqueIdProperty,
-      tileFormat: this.props.tileFormat,
-      spatialDataColumn: this.props.spatialDataColumn,
-      spatialDataType: this.props.spatialDataType,
+      ...this.props,
     });
   }