Category filtering in DataFilterExtension

docs/api-reference/extensions/data-filter-extension.md

@@ -71,6 +71,7 @@ new DataFilterExtension({filterSize, fp64});
 ```
 
 * `filterSize` (Number) - the size of the filter (number of columns to filter by). The data filter can show/hide data based on 1-4 numeric properties of each object. Default `1`.
+* `categorySize` (Number) - the size of the category filter (number of columns to filter by). The category filter can show/hide data based on 1-4 properties of each object. Default `1`.
 * `fp64` (Boolean) - if `true`, use 64-bit precision instead of 32-bit. Default `false`. See the "remarks" section below for use cases and limitations.
 * `countItems` (Boolean) - if `true`, reports the number of filtered objects with the `onFilteredItemsChange` callback. Default `false`.
 
@@ -153,6 +154,63 @@ Format:
 * If `filterSize` is `1`: `[softMin, softMax]`
 * If `filterSize` is `2` to `4`: `[[softMin0, softMax0], [softMin1, softMax1], ...]` for each filtered property, respectively.
 
+##### `getFilterCategory` ([Function](../../developer-guide/using-layers.md#accessors), optional) {#getfiltercategory}
+
+* Default: `0`
+
+Called to retrieve the category for each object that it will be filtered by. Returns either a category as a number or string (if `categorySize: 1`) or an array.
+
+For example, consider data in the following format:
+
+```json
+[
+  {"industry": "retail", "coordinates": [-122.45, 37.78], "size": 10},
+  ...
+]
+```
+
+To filter by industry:
+
+```js
+new ScatterplotLayer({
+  data,
+  getPosition: d => d.coordinates,
+  getFilterCategory: d => d.industry,
+  filterCategories: ['retail', 'health'],
+  extensions: [new DataFilterExtension({categorySize: 1})]
+})
+```
+
+To filter by both industry and size:
+
+```js
+new ScatterplotLayer({
+  data,
+  getPosition: d => d.coordinates,
+  getFilterCategory: d => [d.industry, d.size],
+  filterCategories: [['retail', 'health'], [10, 20, 50]],
+  extensions: [new DataFilterExtension({categorySize: 2})]
+})
+```
+
+##### `filterCategories` (Array, optional) {#filtercategories}
+
+* Default: `[0]`
+
+The list of categories that should be rendered. If an object's filtered category is in the list, the object will be rendered; otherwise it will be hidden. This prop can be updated on user input or animation with very little cost.
+
+Format:
+
+* If `categorySize` is `1`: `['category1', 'category2']`
+* If `categorySize` is `2` to `4`: `[['category1', 'category2', ...], ['category3', ...], ...]` for each filtered property, respectively.
+
+The maximum number of supported is determined by the `categorySize`:
+
+- If `categorySize` is `1`: 128 categories
+- If `categorySize` is `2`: 64 categories per dimension
+- If `categorySize` is `3` or `4`: 32 categories per dimension
+
+If this value is exceeded any categories beyond the limit will be ignored.
 
 ##### `filterTransformSize` (Boolean, optional) {#filtertransformsize}
 

modules/extensions/src/data-filter/data-filter-extension.ts

@@ -22,27 +22,36 @@ import {GL} from '@luma.gl/constants';
 import type {Framebuffer} from '@luma.gl/core';
 import type {Model} from '@luma.gl/engine';
 import type {Layer, LayerContext, Accessor, UpdateParameters} from '@deck.gl/core';
-import {LayerExtension} from '@deck.gl/core';
+import {_deepEqual as deepEqual, LayerExtension, log} from '@deck.gl/core';
 import {shaderModule, shaderModule64} from './shader-module';
 import * as aggregator from './aggregator';
 
 const defaultProps = {
   getFilterValue: {type: 'accessor', value: 0},
+  getFilterCategory: {type: 'accessor', value: 0},
   onFilteredItemsChange: {type: 'function', value: null, optional: true},
 
   filterEnabled: true,
   filterRange: [-1, 1],
   filterSoftRange: null,
+  filterCategories: [0],
   filterTransformSize: true,
   filterTransformColor: true
 };
 
+type FilterCategory = number | string;
+
 export type DataFilterExtensionProps<DataT = any> = {
   /**
    * Accessor to retrieve the value for each object that it will be filtered by.
    * Returns either a number (if `filterSize: 1`) or an array of numbers.
    */
   getFilterValue?: Accessor<DataT, number | number[]>;
+  /**
+   * Accessor to retrieve the category (`number | string`) for each object that it will be filtered by.
+   * Returns either a single category (if `filterSize: 1`) or an array of categories.
+   */
+  getFilterCategory?: Accessor<DataT, FilterCategory | FilterCategory[]>;
   /**
    * Enable/disable the data filter. If the data filter is disabled, all objects are rendered.
    * @default true
@@ -70,6 +79,11 @@ export type DataFilterExtensionProps<DataT = any> = {
    * @default true
    */
   filterTransformColor?: boolean;
+  /**
+   * The categories which define whether an object should be rendered.
+   * @default []
+   */
+  filterCategories: FilterCategory[] | FilterCategory[][];
   /**
    * Only called if the `countItems` option is enabled.
    */
@@ -82,21 +96,26 @@ export type DataFilterExtensionProps<DataT = any> = {
 };
 
 type DataFilterExtensionOptions = {
+  /**
+   * The size of the category filter (number of columns to filter by). The category filter can show/hide data based on 1-4 properties of each object.
+   * @default 1
+   */
+  categorySize?: 1 | 2 | 3 | 4;
   /**
    * The size of the filter (number of columns to filter by). The data filter can show/hide data based on 1-4 numeric properties of each object.
    * @default 1
    */
-  filterSize: number;
+  filterSize?: 1 | 2 | 3 | 4;
   /**
    * Use 64-bit precision instead of 32-bit.
    * @default false
    */
-  fp64: boolean;
+  fp64?: boolean;
   /**
    * If `true`, reports the number of filtered objects with the `onFilteredItemsChange` callback.
    * @default `false`.
    */
-  countItems: boolean;
+  countItems?: boolean;
 };
 
 const DATA_TYPE_FROM_SIZE = {
@@ -111,37 +130,29 @@ export default class DataFilterExtension extends LayerExtension<DataFilterExtens
   static defaultProps = defaultProps;
   static extensionName = 'DataFilterExtension';
 
-  constructor({
-    filterSize = 1,
-    fp64 = false,
-    countItems = false
-  }: Partial<DataFilterExtensionOptions> = {}) {
-    if (!DATA_TYPE_FROM_SIZE[filterSize]) {
-      throw new Error('filterSize out of range');
-    }
-
-    super({filterSize, fp64, countItems});
-  }
-
   getShaders(this: Layer<DataFilterExtensionProps>, extension: this): any {
-    const {filterSize, fp64} = extension.opts;
+    const {categorySize, filterSize, fp64} = extension.opts;
 
     return {
       modules: [fp64 ? shaderModule64 : shaderModule],
       defines: {
-        DATAFILTER_TYPE: DATA_TYPE_FROM_SIZE[filterSize],
+        DATACATEGORY_TYPE: DATA_TYPE_FROM_SIZE[categorySize || 1],
+        DATACATEGORY_CHANNELS: categorySize,
+        DATAFILTER_TYPE: DATA_TYPE_FROM_SIZE[filterSize || 1],
         DATAFILTER_DOUBLE: Boolean(fp64)
       }
     };
   }
 
   initializeState(this: Layer<DataFilterExtensionProps>, context: LayerContext, extension: this) {
     const attributeManager = this.getAttributeManager();
+    const {categorySize, filterSize, fp64} = extension.opts;
+
     if (attributeManager) {
       attributeManager.add({
         filterValues: {
-          size: extension.opts.filterSize,
-          type: extension.opts.fp64 ? GL.DOUBLE : GL.FLOAT,
+          size: filterSize,
+          type: fp64 ? GL.DOUBLE : GL.FLOAT,
           accessor: 'getFilterValue',
           shaderAttributes: {
             filterValues: {
@@ -151,6 +162,23 @@ export default class DataFilterExtension extends LayerExtension<DataFilterExtens
               divisor: 1
             }
           }
+        },
+        filterCategoryValues: {
+          size: categorySize,
+          type: GL.FLOAT,
+          accessor: 'getFilterCategory',
+          transform:
+            categorySize === 1
+              ? d => extension._getCategoryKey.call(this, d, 0)
+              : d => d.map((x, i) => extension._getCategoryKey.call(this, x, i)),
+          shaderAttributes: {
+            filterCategoryValues: {
+              divisor: 0
+            },
+            instanceFilterCategoryValues: {
+              divisor: 1
+            }
+          }
         }
       });
     }
@@ -194,31 +222,60 @@ export default class DataFilterExtension extends LayerExtension<DataFilterExtens
 
   updateState(
     this: Layer<DataFilterExtensionProps>,
-    {props, oldProps}: UpdateParameters<Layer<DataFilterExtensionProps>>
+    {props, oldProps, changeFlags}: UpdateParameters<Layer<DataFilterExtensionProps>>,
+    extension: this
   ) {
+    const attributeManager = this.getAttributeManager();
+    const {categorySize} = extension.opts;
     if (this.state.filterModel) {
-      const attributeManager = this.getAttributeManager();
       const filterNeedsUpdate =
         // attributeManager must be defined for filterModel to be set
         attributeManager!.attributes.filterValues.needsUpdate() ||
+        attributeManager!.attributes.filterCategoryValues?.needsUpdate() ||
         props.filterEnabled !== oldProps.filterEnabled ||
         props.filterRange !== oldProps.filterRange ||
-        props.filterSoftRange !== oldProps.filterSoftRange;
+        props.filterSoftRange !== oldProps.filterSoftRange ||
+        props.filterCategories !== oldProps.filterCategories;
       if (filterNeedsUpdate) {
         this.setState({filterNeedsUpdate});
       }
     }
+    if (attributeManager?.attributes.filterCategoryValues) {
+      // Update bitmask if accessor or selected categories has changed
+      const categoryBitMaskNeedsUpdate =
+        attributeManager.attributes.filterCategoryValues.needsUpdate() ||
+        !deepEqual(props.filterCategories, oldProps.filterCategories, 2);
+      if (categoryBitMaskNeedsUpdate) {
+        this.setState({categoryBitMaskNeedsUpdate});
+      }
+
+      // Need to recreate category map if categorySize has changed
+      const resetCategories = changeFlags.dataChanged;
+      if (resetCategories) {
+        this.setState({
+          categoryMap: Array(categorySize)
+            .fill(0)
+            .map(() => ({}))
+        });
+        attributeManager.attributes.filterCategoryValues.setNeedsUpdate('categoryMap');
+      }
+    }
   }
 
   draw(this: Layer<DataFilterExtensionProps>, params: any, extension: this) {
     const filterFBO = this.state.filterFBO as Framebuffer;
     const filterModel = this.state.filterModel as Model;
     const filterNeedsUpdate = this.state.filterNeedsUpdate as boolean;
+    const categoryBitMaskNeedsUpdate = this.state.categoryBitMaskNeedsUpdate as boolean;
 
     const {onFilteredItemsChange} = this.props;
+
+    if (categoryBitMaskNeedsUpdate) {
+      extension._updateCategoryBitMask.call(this, params, extension);
+    }
     if (filterNeedsUpdate && onFilteredItemsChange && filterModel) {
       const {
-        attributes: {filterValues, filterIndices}
+        attributes: {filterValues, filterCategoryValues, filterIndices}
       } = this.getAttributeManager()!;
       filterModel.setVertexCount(this.getNumInstances());
 
@@ -228,8 +285,10 @@ export default class DataFilterExtension extends LayerExtension<DataFilterExtens
       // @ts-expect-error filterValue and filterIndices should always have buffer value
       filterModel.setAttributes({
         ...filterValues.getValue(),
+        ...filterCategoryValues?.getValue(),
         ...filterIndices?.getValue()
       });
+      filterModel.setUniforms(params.uniforms);
       filterModel.device.withParametersWebGL(
         {
           framebuffer: filterFBO,
@@ -260,4 +319,54 @@ export default class DataFilterExtension extends LayerExtension<DataFilterExtens
     filterFBO?.destroy();
     filterModel?.destroy();
   }
+
+  /**
+   * Updates the bitmask used on the GPU to perform the filter based on the
+   * `filterCategories` prop. The mapping between categories and bit in the bitmask
+   * is performed by `_getCategoryKey()`
+   */
+  _updateCategoryBitMask(
+    this: Layer<DataFilterExtensionProps>,
+    params: any,
+    extension: this
+  ): void {
+    const {categorySize} = extension.opts;
+    const {filterCategories} = this.props;
+    const categoryBitMask = new Uint32Array([0, 0, 0, 0]);
+    const categoryFilters = (
+      categorySize === 1 ? [filterCategories] : filterCategories
+    ) as FilterCategory[][];
+    const maxCategories = categorySize === 1 ? 128 : categorySize === 2 ? 64 : 32;
+    for (let c = 0; c < categoryFilters.length; c++) {
+      const categoryFilter = categoryFilters[c];
+      for (const category of categoryFilter) {
+        const key = extension._getCategoryKey.call(this, category, c);
+        if (key < maxCategories) {
+          const channel = c * (maxCategories / 32) + Math.floor(key / 32);
+          categoryBitMask[channel] += Math.pow(2, key % 32); // 1 << key fails for key > 30
+        } else {
+          log.warn(`Exceeded maximum number of categories (${maxCategories})`)();
+        }
+      }
+    }
+    /* eslint-disable-next-line camelcase */
+    params.uniforms.filter_categoryBitMask = categoryBitMask;
+    this.state.categoryBitMaskNeedsUpdate = false;
+  }
+
+  /**
+   * Returns an index of bit in the bitmask for a given category. If the category has
+   * not yet been assigned a bit, a new one is assigned.
+   */
+  _getCategoryKey(
+    this: Layer<DataFilterExtensionProps>,
+    category: FilterCategory,
+    channel: number
+  ) {
+    const categoryMap = (this.state.categoryMap as Record<FilterCategory, number>[])[channel];
+    if (!(category in categoryMap)) {
+      categoryMap[category] = Object.keys(categoryMap).length;
+    }
+    return categoryMap[category];
+  }
 }