@math.gl/geoarrow 5.0.0-alpha.2

package/src/tessellate.ts

@@ -0,0 +1,133 @@
+// math.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import {earcut} from '@math.gl/polygon';
+import type {GeoArrowColumn, GeoArrowGeometryValue} from './types';
+import {getGeoArrowDimensionSize} from './types';
+import {materializeGeoArrowRows} from './layout';
+import {assertGeoArrowResourceLimits, type GeoArrowResourceLimitOptions} from './kernels';
+
+/** Options for polygon tessellation. */
+export type TessellateGeoArrowPolygonsOptions = Readonly<{
+  /** Number of values emitted for each output vertex. Defaults to the input dimension. */
+  positionSize?: 2 | 3 | 4;
+  /** Value added to every source row index. */
+  sourceRowOffset?: number;
+  limits?: GeoArrowResourceLimitOptions;
+}>;
+
+/** Flat, renderer-ready output for polygon and multipolygon rows. */
+export type GeoArrowTessellation = Readonly<{
+  positions: Float32Array;
+  /** Source column row for every emitted vertex. */
+  sourceRowIndices: Uint32Array;
+  indices: Uint16Array | Uint32Array;
+  sourceDimension: 2 | 3 | 4;
+  positionSize: 2 | 3 | 4;
+  rowCount: number;
+  polygonCount: number;
+  vertexCount: number;
+  triangleCount: number;
+}>;
+
+/**
+ * Tessellates Polygon and MultiPolygon values with stable source-row attribution.
+ *
+ * Non-polygon members of mixed columns and geometry collections are skipped. Closing coordinates
+ * are removed before triangulation and all input descriptors remain borrowed and untouched.
+ */
+export function tessellateGeoArrowPolygons(
+  column: GeoArrowColumn,
+  options: TessellateGeoArrowPolygonsOptions = {}
+): GeoArrowTessellation {
+  assertGeoArrowResourceLimits(column, options.limits);
+  const rows = materializeGeoArrowRows(column);
+  const sourceDimension = getGeoArrowDimensionSize(column.dimension);
+  const positionSize = options.positionSize || sourceDimension;
+  const sourceRowOffset = options.sourceRowOffset || 0;
+  const positions: number[] = [];
+  const sourceRowIndices: number[] = [];
+  const indices: number[] = [];
+  let polygonCount = 0;
+
+  for (let rowIndex = 0; rowIndex < rows.length; rowIndex++) {
+    const row = rows[rowIndex];
+    if (row) {
+      visitPolygons(row, polygon => {
+        const vertexOffset = positions.length / positionSize;
+        const flatCoordinates: number[] = [];
+        const holeIndices: number[] = [];
+        let localVertexCount = 0;
+
+        for (let ringIndex = 0; ringIndex < polygon.length; ringIndex++) {
+          const ring = removeClosingCoordinate(polygon[ringIndex]);
+          if (ring.length < 3) continue;
+          if (localVertexCount > 0) holeIndices.push(localVertexCount);
+          for (const coordinate of ring) {
+            for (let component = 0; component < sourceDimension; component++) {
+              flatCoordinates.push(coordinate[component] ?? 0);
+            }
+            for (let component = 0; component < positionSize; component++) {
+              positions.push(coordinate[component] ?? 0);
+            }
+            sourceRowIndices.push(sourceRowOffset + rowIndex);
+            localVertexCount++;
+          }
+        }
+
+        if (localVertexCount >= 3) {
+          const localIndices = earcut(flatCoordinates, holeIndices, sourceDimension);
+          for (const index of localIndices) indices.push(vertexOffset + index);
+          polygonCount++;
+        }
+      });
+    }
+  }
+
+  const vertexCount = positions.length / positionSize;
+  const IndexArray = vertexCount <= 65535 ? Uint16Array : Uint32Array;
+  return {
+    positions: Float32Array.from(positions),
+    sourceRowIndices: Uint32Array.from(sourceRowIndices),
+    indices: IndexArray.from(indices),
+    sourceDimension,
+    positionSize,
+    rowCount: rows.length,
+    polygonCount,
+    vertexCount,
+    triangleCount: indices.length / 3
+  };
+}
+
+function visitPolygons(
+  geometry: GeoArrowGeometryValue,
+  visitor: (polygon: readonly (readonly (readonly number[])[])[]) => void
+): void {
+  switch (geometry.type) {
+    case 'Polygon':
+      visitor(geometry.coordinates);
+      break;
+    case 'MultiPolygon':
+      for (const polygon of geometry.coordinates) visitor(polygon);
+      break;
+    case 'GeometryCollection':
+      for (const child of geometry.geometries) visitPolygons(child, visitor);
+      break;
+    default:
+      break;
+  }
+}
+
+function removeClosingCoordinate(
+  ring: readonly (readonly number[])[]
+): readonly (readonly number[])[] {
+  if (ring.length < 2) return ring;
+  const first = ring[0];
+  const last = ring[ring.length - 1];
+  if (first.length !== last.length) return ring;
+  for (let index = 0; index < first.length; index++) {
+    if (first[index] !== last[index]) return ring;
+  }
+  return ring.slice(0, -1);
+}

package/src/types.ts

@@ -0,0 +1,200 @@
+// math.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import type {SpatialReference} from '@math.gl/crs';
+import type {TypedArray} from '@math.gl/types';
+import type {WellKnownGeometry} from '@math.gl/wkb';
+
+/** GeoArrow concrete, mixed, bounding-box, and serialized encodings. */
+export type GeoArrowEncoding =
+  | 'geoarrow.point'
+  | 'geoarrow.linestring'
+  | 'geoarrow.polygon'
+  | 'geoarrow.multipoint'
+  | 'geoarrow.multilinestring'
+  | 'geoarrow.multipolygon'
+  | 'geoarrow.geometry'
+  | 'geoarrow.geometrycollection'
+  | 'geoarrow.box'
+  | 'geoarrow.wkb'
+  | 'geoarrow.wkt';
+
+/** Semantic coordinate dimensions. M is never interpreted as Z. */
+export type GeoArrowDimension = 'xy' | 'xyz' | 'xym' | 'xyzm';
+
+/** Physical coordinate organization for native geometries. */
+export type GeoArrowCoordinateLayout = 'interleaved' | 'separated';
+
+/** Supported list-offset buffers. */
+export type GeoArrowOffsets = Int32Array | BigInt64Array;
+
+/** Numeric physical storage accepted by GeoArrow descriptors. */
+export type GeoArrowNumericArray = TypedArray | BigInt64Array | BigUint64Array;
+
+/** Borrowed validity bitmap. Set bits are valid rows. */
+export type GeoArrowValidity = Readonly<{
+  values: Uint8Array;
+  /** Bit position corresponding to logical row zero. */
+  bitOffset?: number;
+}>;
+
+/** Properties shared by all physical arrays. */
+export type GeoArrowArrayBase = Readonly<{
+  /** Number of logical values represented by this array. */
+  length: number;
+  /** Optional borrowed validity bitmap for this nesting level. */
+  validity?: GeoArrowValidity;
+}>;
+
+/** Primitive scalar storage, optionally strided within a typed array. */
+export type GeoArrowPrimitive = GeoArrowArrayBase &
+  Readonly<{
+    kind: 'primitive';
+    values: GeoArrowNumericArray;
+    /** Scalar offset of logical value zero. */
+    offset?: number;
+    /** Scalars between consecutive logical values. Defaults to one. */
+    stride?: number;
+  }>;
+
+/** Fixed-size list storage, used for interleaved coordinate tuples. */
+export type GeoArrowFixedSizeList = GeoArrowArrayBase &
+  Readonly<{
+    kind: 'fixed-size-list';
+    size: number;
+    child: GeoArrowArray;
+    /** Logical list offset into the child. */
+    offset?: number;
+  }>;
+
+/** Variable-size list storage. */
+export type GeoArrowList = GeoArrowArrayBase &
+  Readonly<{
+    kind: 'list';
+    offsets: GeoArrowOffsets;
+    /** Index of logical row zero in `offsets`. */
+    offset?: number;
+    /** Value subtracted from offsets before indexing the supplied child view. */
+    offsetBase?: number | bigint;
+    child: GeoArrowArray;
+  }>;
+
+/** Named separated children, used for separated coordinates and boxes. */
+export type GeoArrowStruct = GeoArrowArrayBase &
+  Readonly<{
+    kind: 'struct';
+    children: Readonly<Record<string, GeoArrowArray>>;
+    /** Logical struct offset applied to every child. */
+    offset?: number;
+  }>;
+
+/** Struct storage used by `geoarrow.box` minimum/maximum ordinate columns. */
+export type GeoArrowBox = GeoArrowStruct;
+
+/** One dense-union child and its stable type ID. */
+export type GeoArrowDenseUnionChild = Readonly<{
+  name: string;
+  typeId: number;
+  data: GeoArrowArray;
+}>;
+
+/** Dense-union storage for mixed geometry families. */
+export type GeoArrowDenseUnion = GeoArrowArrayBase &
+  Readonly<{
+    kind: 'dense-union';
+    typeIds: Int8Array | Uint8Array;
+    valueOffsets: Int32Array;
+    children: readonly GeoArrowDenseUnionChild[];
+    /** Logical row offset into typeIds and valueOffsets. */
+    offset?: number;
+  }>;
+
+/** Variable-width binary or UTF-8 storage for WKB and WKT. */
+export type GeoArrowSerialized = GeoArrowArrayBase &
+  Readonly<{
+    kind: 'serialized';
+    encoding: 'binary' | 'utf8';
+    offsets: GeoArrowOffsets;
+    values: Uint8Array;
+    /** Index of logical row zero in `offsets`. */
+    offset?: number;
+    /** Value subtracted from offsets before indexing `values`. */
+    offsetBase?: number | bigint;
+  }>;
+
+/** Arrow-compatible physical array tree without Arrow runtime classes. */
+export type GeoArrowArray =
+  | GeoArrowPrimitive
+  | GeoArrowFixedSizeList
+  | GeoArrowList
+  | GeoArrowStruct
+  | GeoArrowDenseUnion
+  | GeoArrowSerialized;
+
+/** One logical GeoArrow geometry column backed by borrowed chunks. */
+export type GeoArrowColumn = Readonly<{
+  encoding: GeoArrowEncoding;
+  dimension: GeoArrowDimension;
+  coordinateLayout: GeoArrowCoordinateLayout | null;
+  chunks: readonly GeoArrowArray[];
+  spatialReference?: SpatialReference | null;
+  edges?: 'planar' | 'spherical';
+  metadata?: Readonly<Record<string, unknown>>;
+}>;
+
+/** Materialized geometry value used at codec and builder boundaries. */
+export type GeoArrowGeometryValue = WellKnownGeometry;
+
+/** Coordinate callback used by mapping kernels. */
+export type GeoArrowCoordinateMapper = (
+  coordinate: readonly number[],
+  rowIndex: number
+) => readonly number[];
+
+/** Four-value XY bounds. */
+export type GeoArrowBounds = readonly [number, number, number, number];
+
+/** Returns the number of coordinate components for a semantic dimension. */
+export function getGeoArrowDimensionSize(dimension: GeoArrowDimension): 2 | 3 | 4 {
+  switch (dimension) {
+    case 'xy':
+      return 2;
+    case 'xyz':
+    case 'xym':
+      return 3;
+    case 'xyzm':
+      return 4;
+  }
+}
+
+/** Returns the concrete geometry family associated with an encoding. */
+export function getGeoArrowGeometryType(
+  encoding: GeoArrowEncoding
+): Exclude<GeoArrowGeometryValue['type'], 'GeometryCollection'> | 'GeometryCollection' | null {
+  switch (encoding) {
+    case 'geoarrow.point':
+      return 'Point';
+    case 'geoarrow.linestring':
+      return 'LineString';
+    case 'geoarrow.polygon':
+      return 'Polygon';
+    case 'geoarrow.multipoint':
+      return 'MultiPoint';
+    case 'geoarrow.multilinestring':
+      return 'MultiLineString';
+    case 'geoarrow.multipolygon':
+      return 'MultiPolygon';
+    case 'geoarrow.geometrycollection':
+      return 'GeometryCollection';
+    default:
+      return null;
+  }
+}
+
+/** Returns the canonical concrete encoding for a materialized geometry family. */
+export function getGeoArrowEncodingForGeometry(
+  type: GeoArrowGeometryValue['type']
+): GeoArrowEncoding {
+  return `geoarrow.${type.toLowerCase()}` as GeoArrowEncoding;
+}

package/src/worker.ts

@@ -0,0 +1,20 @@
+// math.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import type {GeoArrowColumn} from './types';
+import {getGeoArrowTransferList} from './layout';
+
+export {getGeoArrowTransferList} from './layout';
+export type {GeoArrowColumn} from './types';
+
+/** A column and the unique borrowed buffers that may be transferred with it. */
+export type GeoArrowTransfer = Readonly<{
+  column: GeoArrowColumn;
+  transferList: ArrayBuffer[];
+}>;
+
+/** Prepares an explicit structured-clone transfer payload without detaching any buffers. */
+export function prepareGeoArrowTransfer(column: GeoArrowColumn): GeoArrowTransfer {
+  return {column, transferList: getGeoArrowTransferList(column)};
+}