function accessors (#100)

* Support for function accessors

* updated point example

* updated Readme

Author: kylebarron

README.md

@@ -21,6 +21,53 @@ Standalone examples exist in the [`examples/`](examples/) directory. Create an i
 
 More hosted examples on Observable are planned.
 
+## Providing accessors
+
+All deck.gl layers have two types of properties: ["Render Options"](https://deck.gl/docs/api-reference/layers/scatterplot-layer#render-options) — constant properties across a layer — and "Data Accessors" — properties that can vary across rows. An accessor is any property prefixed with `get`, like `GeoArrowScatterplotLayer`'s `getFillColor`.
+
+With `@geoarrow/deck.gl-layers` specifically, there are two ways to pass these data accessors, either as pre-computed columns or with function callbacks on Arrow data.
+
+### Pre-computed Arrow columns
+
+If you have an Arrow column ([`Vector`](https://arrow.apache.org/docs/js/classes/Arrow_dom.Vector.html) in Arrow JS terminology), you can pass that directly into a layer:
+
+```ts
+import { Table } from "apache-arrow";
+import { GeoArrowScatterplotLayer } from "@geoarrow/deck.gl-layers";
+
+const table = new Table(...);
+const deckLayer = new GeoArrowScatterplotLayer({
+  id: "scatterplot",
+  data: table,
+  /// Geometry column
+  getPosition: table.getChild("geometry")!,
+  /// Column of type FixedSizeList[3] or FixedSizeList[4], with child type Uint8
+  getFillColor: table.getChild("colors")!,
+});
+```
+
+For example, [lonboard](https://github.com/developmentseed/lonboard) computes Arrow columns on the Python side for all attributes so that end users have available the full capabilities Python. Then those columns are serialized to Python and the resulting `arrow.Vector` is passed into the relevant layer.
+
+### Function accessors
+
+GeoArrow layers accept a callback that takes an object with `index` and `data`. `data` is an `arrow.RecordBatch` object (a vertical section of the input `Table`), and `index` is the positional index of the current row of that batch. In TypeScript, you should see accurate type checking.
+
+```ts
+const deckLayer = new GeoArrowPathLayer({
+  id: "geoarrow-path",
+  data: table,
+  getColor: ({ index, data, target }) => {
+    const recordBatch = data.data;
+    const row = recordBatch.get(index)!;
+    return COLORS_LOOKUP[row["scalerank"]];
+  },
+}),
+```
+
+The full example is in [`examples/multilinestring/app.tsx`](examples/multilinestring/app.tsx).
+
+You can also use assign to the `target` prop to reduce garbage collector overhead, as described in the [deck.gl performance guide](https://deck.gl/docs/developer-guide/performance#supply-binary-blobs-to-the-data-prop).
+
 ## Data Loading
 
 To create deck.gl layers using this library, you need to first get GeoArrow-formatted data into the browser, discussed below.
@@ -38,6 +85,7 @@ import { GeoArrowScatterplotLayer } from "@geoarrow/deck.gl-layers";
 const resp = await fetch("url/to/file.arrow");
 const jsTable = await tableFromIPC(resp);
 const deckLayer = new GeoArrowScatterplotLayer({
+  id: "scatterplot",
   data: jsTable,
   /// Replace with the correct geometry column name
   getPosition: jsTable.getChild("geometry")!,
@@ -60,6 +108,7 @@ const arrayBuffer = await resp.arrayBuffer();
 const wasmTable = readParquet(new Uint8Array(arrayBuffer));
 const jsTable = tableFromIPC(wasmTable.intoIPCStream());
 const deckLayer = new GeoArrowScatterplotLayer({
+  id: "scatterplot",
   data: jsTable,
   /// Replace with the correct geometry column name
   getPosition: jsTable.getChild("geometry")!,
@@ -82,6 +131,7 @@ const arrayBuffer = await resp.arrayBuffer();
 const wasmTable = readGeoParquet(new Uint8Array(arrayBuffer));
 const jsTable = tableFromIPC(wasmTable.intoTable().intoIPCStream());
 const deckLayer = new GeoArrowScatterplotLayer({
+  id: "scatterplot",
   data: jsTable,
   /// Replace with the correct geometry column name
   getPosition: jsTable.getChild("geometry")!,
@@ -104,6 +154,7 @@ const arrayBuffer = await resp.arrayBuffer();
 const wasmTable = readFlatGeobuf(new Uint8Array(arrayBuffer));
 const jsTable = tableFromIPC(wasmTable.intoTable().intoIPCStream());
 const deckLayer = new GeoArrowScatterplotLayer({
+  id: "scatterplot",
   data: jsTable,
   /// Replace with the correct geometry column name
   getPosition: jsTable.getChild("geometry")!,

examples/multilinestring/app.tsx

@@ -9,9 +9,9 @@ const GEOARROW_MULTILINESTRING_DATA =
   "http://localhost:8080/ne_10m_roads_north_america.feather";
 
 const INITIAL_VIEW_STATE = {
-  latitude: 20,
-  longitude: 0,
-  zoom: 2,
+  latitude: 40,
+  longitude: -90,
+  zoom: 4,
   bearing: 0,
   pitch: 0,
 };
@@ -24,16 +24,20 @@ const NAV_CONTROL_STYLE = {
   left: 10,
 };
 
-function Root() {
-  const onClick = (info) => {
-    if (info.object) {
-      // eslint-disable-next-line
-      alert(
-        `${info.object.properties.name} (${info.object.properties.abbrev})`
-      );
-    }
-  };
+// https://colorbrewer2.org/#type=sequential&scheme=PuBuGn&n=9
+const COLORS_LOOKUP = {
+  "3": [255, 247, 251],
+  "4": [236, 226, 240],
+  "5": [208, 209, 230],
+  "6": [166, 189, 219],
+  "7": [103, 169, 207],
+  "8": [54, 144, 192],
+  "9": [2, 129, 138],
+  "10": [1, 108, 89],
+  "11": [1, 70, 54],
+};
 
+function Root() {
   const [table, setTable] = useState<arrow.Table | null>(null);
 
   useEffect(() => {
@@ -58,17 +62,14 @@ function Root() {
       new GeoArrowPathLayer({
         id: "geoarrow-path",
         data: table,
-        // getPath: table.getC
-        // getPosition: table.getChild("geometry")!,
-        getColor:[255, 0, 0],
-        widthMinPixels: 0.2,
-        // getFillColor: [255, 0, 0],
-        // getFillColor: table.getChild("colors")!,
-        // getLineColor: table.getChild("colors")!,
-        radiusMinPixels: 4,
-        getPointRadius: 10,
-        pointRadiusMinPixels: 0.8,
-      })
+        getColor: ({ index, data }) => {
+          const recordBatch = data.data;
+          const row = recordBatch.get(index)!;
+          return COLORS_LOOKUP[row["scalerank"]];
+        },
+        widthMinPixels: 0.8,
+        pickable: true,
+      }),
     );
 
   return (

examples/point/app.tsx

@@ -54,12 +54,17 @@ function Root() {
       new GeoArrowScatterplotLayer({
         id: "geoarrow-points",
         data: table,
+        // Pre-computed colors in the original table
         getFillColor: table.getChild("colors")!,
-        radiusMinPixels: 1.5,
-        getPointRadius: 10,
-        pointRadiusMinPixels: 0.8,
+        opacity: 0.01,
+        getRadius: ({ index, data }) => {
+          const recordBatch = data.data;
+          const row = recordBatch.get(index)!;
+          return row["avg_d_kbps"] / 10;
+        },
+        radiusMinPixels: 0.1,
         pickable: true,
-      })
+      }),
     );
 
   return (

src/arc-layer.ts

@@ -164,12 +164,14 @@ export class GeoArrowArcLayer<
         ...ourDefaultProps,
         ...otherProps,
 
-        // @ts-expect-error used for picking purposes
+        // used for picking purposes
         recordBatchIdx,
         tableOffsets,
 
         id: `${this.props.id}-geoarrow-arc-${recordBatchIdx}`,
         data: {
+          // @ts-expect-error passed through to enable use by function accessors
+          data: table.batches[recordBatchIdx],
           length: sourceData.length,
           attributes: {
             getSourcePosition: {

src/column-layer.ts

@@ -168,12 +168,14 @@ export class GeoArrowColumnLayer<
         ...ourDefaultProps,
         ...otherProps,
 
-        // @ts-expect-error used for picking purposes
+        // used for picking purposes
         recordBatchIdx,
         tableOffsets,
 
         id: `${this.props.id}-geoarrow-column-${recordBatchIdx}`,
         data: {
+          // @ts-expect-error passed through to enable use by function accessors
+          data: table.batches[recordBatchIdx],
           length: geometryData.length,
           attributes: {
             getPosition: {

src/h3-hexagon-layer.ts

@@ -105,13 +105,15 @@ export class GeoArrowH3HexagonLayer<
         ...ourDefaultProps,
         ...otherProps,
 
-        // @ts-expect-error used for picking purposes
+        // used for picking purposes
         recordBatchIdx,
         tableOffsets,
 
         id: `${this.props.id}-geoarrow-arc-${recordBatchIdx}`,
 
         data: {
+          // @ts-expect-error passed through to enable use by function accessors
+          data: table.batches[recordBatchIdx],
           length: hexData.length,
           attributes: {
             getHexagon: {

src/heatmap-layer.ts

@@ -128,12 +128,14 @@ export class GeoArrowHeatmapLayer<
         ...ourDefaultProps,
         ...otherProps,
 
-        // @ts-expect-error used for picking purposes
+        // used for picking purposes
         recordBatchIdx,
         tableOffsets,
 
         id: `${this.props.id}-geoarrow-heatmap-${recordBatchIdx}`,
         data: {
+          // @ts-expect-error passed through to enable use by function accessors
+          data: table.batches[recordBatchIdx],
           length: geometryData.length,
           attributes: {
             getPosition: {

src/path-layer.ts

@@ -182,8 +182,9 @@ export class GeoArrowPathLayer<
 
         id: `${this.props.id}-geoarrow-path-${recordBatchIdx}`,
         data: {
+          // @ts-expect-error passed through to enable use by function accessors
+          data: table.batches[recordBatchIdx],
           length: lineStringData.length,
-          // @ts-expect-error
           startIndices: geomOffsets,
           attributes: {
             getPath: { value: flatCoordinateArray, size: nDim },
@@ -255,10 +256,14 @@ export class GeoArrowPathLayer<
         // used for picking purposes
         recordBatchIdx,
         tableOffsets,
-        invertedGeomOffsets: invertOffsets(geomOffsets),
 
         id: `${this.props.id}-geoarrow-path-${recordBatchIdx}`,
         data: {
+          // @ts-expect-error passed through to enable use by function accessors
+          data: table.batches[recordBatchIdx],
+          // Map from expanded multi-geometry index to original index
+          // Used both in picking and for function callbacks
+          invertedGeomOffsets: invertOffsets(geomOffsets),
           // Note: this needs to be the length one level down.
           length: lineStringData.length,
           // Offsets into coordinateArray where each single-line string starts

src/picking.ts

@@ -5,7 +5,9 @@ import { GeoArrowPickingInfo } from "./types";
 export interface GeoArrowExtraPickingProps {
   recordBatchIdx: number;
   tableOffsets: Uint32Array;
-  invertedGeomOffsets?: Uint8Array | Uint16Array | Uint32Array;
+  data: {
+    invertedGeomOffsets?: Uint8Array | Uint16Array | Uint32Array;
+  };
 }
 
 export function getPickingInfo(
@@ -22,8 +24,8 @@ export function getPickingInfo(
 
   // if a Multi- geometry dataset, map from the rendered index back to the
   // feature index
-  if (sourceLayer.props.invertedGeomOffsets) {
-    index = sourceLayer.props.invertedGeomOffsets[index];
+  if (sourceLayer.props.data.invertedGeomOffsets) {
+    index = sourceLayer.props.data.invertedGeomOffsets[index];
   }
 
   const recordBatchIdx = sourceLayer.props.recordBatchIdx;

src/scatterplot-layer.ts

@@ -169,12 +169,14 @@ export class GeoArrowScatterplotLayer<
         ...ourDefaultProps,
         ...otherProps,
 
-        // @ts-expect-error used for picking purposes
+        // used for picking purposes
         recordBatchIdx,
         tableOffsets,
 
         id: `${this.props.id}-geoarrow-scatterplot-${recordBatchIdx}`,
         data: {
+          // @ts-expect-error passed through to enable use by function accessors
+          data: table.batches[recordBatchIdx],
           length: geometryData.length,
           attributes: {
             getPosition: {
@@ -237,13 +239,17 @@ export class GeoArrowScatterplotLayer<
         ...ourDefaultProps,
         ...otherProps,
 
-        // @ts-expect-error used for picking purposes
+        // used for picking purposes
         recordBatchIdx,
         tableOffsets,
-        invertedGeomOffsets: invertOffsets(geomOffsets),
 
         id: `${this.props.id}-geoarrow-scatterplot-${recordBatchIdx}`,
         data: {
+          // @ts-expect-error passed through to enable use by function accessors
+          data: table.batches[recordBatchIdx],
+          // Map from expanded multi-geometry index to original index
+          // Used both in picking and for function callbacks
+          invertedGeomOffsets: invertOffsets(geomOffsets),
           // Note: this needs to be the length one level down.
           length: pointData.length,
           attributes: {