@math.gl/geoarrow 5.0.0-alpha.2 → 5.0.0-alpha.3

package/src/codecs.ts

@@ -2,7 +2,9 @@
 // SPDX-License-Identifier: MIT
 // Copyright (c) vis.gl contributors
 
-import {formatWKT, parseWKB, parseWKT, writeWKB} from '@math.gl/wkb';
+import {formatWKT, parseWKB, parseWKT} from '@math.gl/wkb';
+import type {WKBGeometryWriter} from '@math.gl/wkb';
+import {WKBBuilder} from '@math.gl/wkb';
 import type {
   GeoArrowColumn,
   GeoArrowDimension,
@@ -11,7 +13,7 @@ import type {
 } from './types';
 import {getGeoArrowDimensionSize} from './types';
 import {makeGeoArrowColumnFromGeometryRows} from './builder';
-import {getGeoArrowOffset, isGeoArrowValueValid, materializeGeoArrowRows} from './layout';
+import {getGeoArrowOffset, isGeoArrowValueValid, materializeGeometryRow} from './layout';
 
 const textEncoder = new TextEncoder();
 const textDecoder = new TextDecoder();
@@ -32,9 +34,42 @@ export function decodeGeoArrowWKB(column: GeoArrowColumn): GeoArrowColumn {
 /** Encodes a native GeoArrow column as variable-width WKB bytes. */
 export function encodeGeoArrowWKB(column: GeoArrowColumn): GeoArrowColumn {
   if (column.encoding === 'geoarrow.wkb') return column;
-  const rows = materializeGeoArrowRows(column);
-  const values = rows.map(row => (row ? writeWKB(row, column.dimension) : null));
-  return copyMetadata(column, makeSerializedColumn(values, 'geoarrow.wkb', column.dimension));
+  const writers: Array<WKBGeometryWriter | null> = [];
+  const dimensions: GeoArrowDimension[] = [];
+  for (const chunk of column.chunks) {
+    for (let rowIndex = 0; rowIndex < chunk.length; rowIndex++) {
+      if (!isGeoArrowValueValid(chunk.validity, rowIndex)) {
+        writers.push(null);
+        dimensions.push(column.dimension);
+        continue;
+      }
+      dimensions.push(
+        getPhysicalGeometryDimension(chunk, rowIndex, column.encoding, column.dimension)
+      );
+      writers.push(builder =>
+        writePhysicalGeometry(builder, chunk, rowIndex, column.encoding, column.dimension)
+      );
+    }
+  }
+  const built = WKBBuilder.buildGeometryArray(writers, {
+    dimension: column.dimension,
+    dimensionResolver: index => dimensions[index] || column.dimension
+  });
+  return copyMetadata(column, {
+    encoding: 'geoarrow.wkb',
+    dimension: column.dimension,
+    coordinateLayout: null,
+    chunks: [
+      {
+        kind: 'serialized',
+        encoding: 'binary',
+        length: writers.length,
+        offsets: built.valueOffsets,
+        values: built.values,
+        ...(built.nullBitmap ? {validity: {values: built.nullBitmap}} : {})
+      }
+    ]
+  });
 }
 
 /** Decodes a GeoArrow WKT column into native physical geometry buffers. */
@@ -53,13 +88,206 @@ export function decodeGeoArrowWKT(column: GeoArrowColumn): GeoArrowColumn {
 /** Encodes a native GeoArrow column as variable-width UTF-8 WKT. */
 export function encodeGeoArrowWKT(column: GeoArrowColumn): GeoArrowColumn {
   if (column.encoding === 'geoarrow.wkt') return column;
-  const rows = materializeGeoArrowRows(column);
-  const values = rows.map(row =>
-    row ? textEncoder.encode(formatWKT(row, column.dimension)) : null
-  );
+  const values: Array<Uint8Array | null> = [];
+  for (const chunk of column.chunks) {
+    for (let rowIndex = 0; rowIndex < chunk.length; rowIndex++) {
+      const row = isGeoArrowValueValid(chunk.validity, rowIndex)
+        ? materializeGeometryRow(chunk, rowIndex, column.encoding)
+        : null;
+      values.push(row ? textEncoder.encode(formatWKT(row, column.dimension)) : null);
+    }
+  }
   return copyMetadata(column, makeSerializedColumn(values, 'geoarrow.wkt', column.dimension));
 }
 
+function writePhysicalGeometry(
+  builder: WKBBuilder,
+  array: import('./types').GeoArrowArray,
+  rowIndex: number,
+  encoding: import('./types').GeoArrowEncoding,
+  dimension: GeoArrowDimension
+): void {
+  const depth = getEncodingDepth(encoding);
+  if (encoding === 'geoarrow.geometry' && array.kind === 'dense-union') {
+    const physical = (array.offset || 0) + rowIndex;
+    const typeId = array.typeIds[physical];
+    const child = array.children.find(candidate => candidate.typeId === typeId);
+    if (!child) throw new Error('Dense-union row references an unknown child');
+    const childDimension = child.dimension || dimension;
+    builder.withDimension(childDimension, () =>
+      writePhysicalGeometry(
+        builder,
+        child.data,
+        array.valueOffsets[physical],
+        child.encoding || encodingFromName(child.name),
+        childDimension
+      )
+    );
+    return;
+  }
+  if (encoding === 'geoarrow.geometrycollection' && array.kind === 'list') {
+    const [first, last] = getListRange(array, rowIndex);
+    builder.beginGeometry('GeometryCollection', last - first);
+    if (array.child.kind !== 'dense-union')
+      throw new Error('GeometryCollection requires dense union child');
+    const union = array.child;
+    for (let index = first; index < last; index++) {
+      const physical = (union.offset || 0) + index;
+      const child = union.children.find(candidate => candidate.typeId === union.typeIds[physical]);
+      if (child) {
+        const childDimension = child.dimension || dimension;
+        builder.withDimension(childDimension, () =>
+          writePhysicalGeometry(
+            builder,
+            child.data,
+            union.valueOffsets[physical],
+            child.encoding || encodingFromName(child.name),
+            childDimension
+          )
+        );
+      }
+    }
+    return;
+  }
+  if (array.kind !== 'list' && depth > 0) throw new Error(`Invalid ${encoding} storage`);
+  const writeCoordinate = (leaf: import('./types').GeoArrowArray, index: number): void => {
+    const coordinate = readPhysicalCoordinate(leaf, index);
+    if (!coordinate) throw new Error('Invalid GeoArrow coordinate storage');
+    if (dimension === 'xym')
+      builder.writeCoordinate(coordinate[0], coordinate[1], undefined, coordinate[2]);
+    else if (dimension === 'xyzm')
+      builder.writeCoordinate(coordinate[0], coordinate[1], coordinate[2], coordinate[3]);
+    else builder.writeCoordinate(coordinate[0], coordinate[1], coordinate[2]);
+  };
+  const writeSequence = (
+    leaf: import('./types').GeoArrowArray,
+    first: number,
+    last: number
+  ): void => {
+    for (let index = first; index < last; index++) writeCoordinate(leaf, index);
+  };
+  if (encoding === 'geoarrow.point') {
+    builder.beginPoint();
+    writeCoordinate(array, rowIndex);
+  } else if (encoding === 'geoarrow.linestring' || encoding === 'geoarrow.multipoint') {
+    const [first, last] = getListRange(array as import('./types').GeoArrowList, rowIndex);
+    if (encoding === 'geoarrow.linestring') {
+      builder.beginLineString(last - first);
+      writeSequence((array as import('./types').GeoArrowList).child, first, last);
+    } else {
+      builder.beginMultiPoint(last - first);
+      const leaf = (array as import('./types').GeoArrowList).child;
+      for (let index = first; index < last; index++) {
+        builder.beginPoint();
+        writeCoordinate(leaf, index);
+      }
+    }
+  } else if (encoding === 'geoarrow.polygon' || encoding === 'geoarrow.multilinestring') {
+    const [first, last] = getListRange(array as import('./types').GeoArrowList, rowIndex);
+    const parts = (array as import('./types').GeoArrowList).child;
+    if (encoding === 'geoarrow.polygon') builder.beginPolygon(last - first);
+    else builder.beginMultiLineString(last - first);
+    for (let partIndex = first; partIndex < last; partIndex++) {
+      const [ringFirst, ringLast] = getListRange(
+        parts as import('./types').GeoArrowList,
+        partIndex
+      );
+      const leaf = (parts as import('./types').GeoArrowList).child;
+      if (encoding === 'geoarrow.polygon') builder.beginLinearRing(ringLast - ringFirst);
+      else builder.beginLineString(ringLast - ringFirst);
+      writeSequence(leaf, ringFirst, ringLast);
+    }
+  } else if (encoding === 'geoarrow.multipolygon') {
+    const [first, last] = getListRange(array as import('./types').GeoArrowList, rowIndex);
+    const polygons = (array as import('./types').GeoArrowList).child;
+    builder.beginMultiPolygon(last - first);
+    for (let polygonIndex = first; polygonIndex < last; polygonIndex++) {
+      const [partFirst, partLast] = getListRange(
+        polygons as import('./types').GeoArrowList,
+        polygonIndex
+      );
+      const parts = (polygons as import('./types').GeoArrowList).child;
+      builder.beginPolygon(partLast - partFirst);
+      for (let partIndex = partFirst; partIndex < partLast; partIndex++) {
+        const [ringFirst, ringLast] = getListRange(
+          parts as import('./types').GeoArrowList,
+          partIndex
+        );
+        builder.beginLinearRing(ringLast - ringFirst);
+        writeSequence((parts as import('./types').GeoArrowList).child, ringFirst, ringLast);
+      }
+    }
+  }
+}
+
+function getPhysicalGeometryDimension(
+  array: import('./types').GeoArrowArray,
+  rowIndex: number,
+  encoding: import('./types').GeoArrowEncoding,
+  dimension: GeoArrowDimension
+): GeoArrowDimension {
+  if (encoding !== 'geoarrow.geometry' || array.kind !== 'dense-union') return dimension;
+  const physical = (array.offset || 0) + rowIndex;
+  const child = array.children.find(candidate => candidate.typeId === array.typeIds[physical]);
+  return child?.dimension || dimension;
+}
+
+function readPhysicalCoordinate(
+  array: import('./types').GeoArrowArray,
+  index: number
+): number[] | null {
+  if (array.kind === 'fixed-size-list' && array.child.kind === 'primitive') {
+    const logical = (array.offset || 0) + index;
+    const values: number[] = [];
+    for (let component = 0; component < array.size; component++)
+      values.push(
+        Number(
+          array.child.values[
+            (array.child.offset || 0) +
+              (logical * array.size + component) * (array.child.stride || 1)
+          ]
+        )
+      );
+    return values;
+  }
+  if (array.kind === 'struct') {
+    const logical = (array.offset || 0) + index;
+    return ['x', 'y', 'z', 'm'].flatMap(name => {
+      const child = array.children[name];
+      return child?.kind === 'primitive'
+        ? [Number(child.values[(child.offset || 0) + logical * (child.stride || 1)])]
+        : [];
+    });
+  }
+  return null;
+}
+
+function getListRange(list: import('./types').GeoArrowList, index: number): [number, number] {
+  const offset = (list.offset || 0) + index;
+  const base =
+    typeof (list.offsetBase ?? 0) === 'bigint'
+      ? Number(list.offsetBase)
+      : Number(list.offsetBase ?? 0);
+  return [
+    getGeoArrowOffset(list.offsets, offset) - base,
+    getGeoArrowOffset(list.offsets, offset + 1) - base
+  ];
+}
+
+function getEncodingDepth(encoding: import('./types').GeoArrowEncoding): number {
+  return encoding === 'geoarrow.point'
+    ? 0
+    : encoding === 'geoarrow.linestring' || encoding === 'geoarrow.multipoint'
+      ? 1
+      : encoding === 'geoarrow.polygon' || encoding === 'geoarrow.multilinestring'
+        ? 2
+        : 3;
+}
+
+function encodingFromName(name: string): import('./types').GeoArrowEncoding {
+  return `geoarrow.${name.toLowerCase()}` as import('./types').GeoArrowEncoding;
+}
+
 function normalizeRowsToDimension(
   rows: readonly (GeoArrowGeometryValue | null)[],
   dimension: GeoArrowDimension
@@ -106,6 +334,20 @@ function decodeSerializedRows(
 }
 
 function getSerializedBytes(array: GeoArrowSerialized, rowIndex: number): Uint8Array {
+  if (array.views) {
+    const viewIndex = ((array.offset || 0) + rowIndex) * 4;
+    const length = array.views[viewIndex];
+    // Arrow BinaryView stores short values inline in the 16-byte view record.
+    if (length <= 12) {
+      const byteOffset = array.views.byteOffset + viewIndex * 4 + 4;
+      return new Uint8Array(array.views.buffer, byteOffset, length);
+    }
+    const bufferIndex = array.views[viewIndex + 2];
+    const byteOffset = array.views[viewIndex + 3];
+    const data = array.dataBuffers?.[bufferIndex];
+    if (!data) throw new Error(`Serialized view references missing data buffer ${bufferIndex}`);
+    return data.subarray(byteOffset, byteOffset + length);
+  }
   const offsetIndex = (array.offset || 0) + rowIndex;
   const baseValue = array.offsetBase ?? 0;
   const base = typeof baseValue === 'bigint' ? Number(baseValue) : baseValue;

package/src/index.ts

@@ -72,6 +72,7 @@ export {
   assertGeoArrowResourceLimits,
   convertGeoArrowColumn,
   getGeoArrowBounds,
+  getGeoArrowRowBounds,
   interleaveGeoArrowCoordinates,
   mapGeoArrowCoordinates,
   mapGeoArrowCoordinatesInto,