@math.gl/geospatial 5.0.0-alpha.9 → 5.0.0-beta.1

package/src/web-mercator.ts

@@ -0,0 +1,5 @@
+// math.gl
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
+
+export * from '@math.gl/web-mercator';

package/src/wkb/index.ts

@@ -0,0 +1,38 @@
+// math.gl
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
+
+export type {WellKnownDimension, WellKnownGeometry} from './types';
+export {
+  getWellKnownDimensionSize,
+  inferWellKnownGeometryDimension
+} from './types';
+
+export type {WKBParseOptions, WKBParseResult} from './wkb';
+export {parseWKB, writeWKB} from './wkb';
+
+export type {
+  WKBBounds,
+  WKBDialect,
+  WKBGeometryCounts,
+  WKBGeometryType,
+  WKBHeader,
+  WKBScanResult,
+  WKBTraversalOptions,
+  WKBVisitor
+} from './wkb-reader';
+export {inspectWKBHeader, scanWKB, visitWKB} from './wkb-reader';
+
+export type {
+  WKBBuilderBaseOptions,
+  WKBBuilderMeasureOptions,
+  WKBBuilderOptions,
+  WKBBuilderWriteOptions,
+  WKBCoordinateTransform,
+  WKBGeometryArray,
+  WKBGeometryWriter
+} from './wkb-builder';
+export {WKBBuilder} from './wkb-builder';
+
+export type {WKTParseOptions, WKTParseResult} from './wkt';
+export {formatWKT, parseWKT, parseWKTWithMetadata} from './wkt';

package/src/wkb/types.ts

@@ -0,0 +1,54 @@
+// math.gl
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
+
+/** Semantic coordinate dimensions used by WKB and WKT. M is distinct from Z. */
+export type WellKnownDimension = 'xy' | 'xyz' | 'xym' | 'xyzm';
+
+/** Immutable, format-neutral geometry value shared by the WKB and WKT codecs. */
+export type WellKnownGeometry =
+  | Readonly<{type: 'Point'; coordinates: readonly number[]}>
+  | Readonly<{type: 'LineString'; coordinates: readonly (readonly number[])[]}>
+  | Readonly<{type: 'Polygon'; coordinates: readonly (readonly (readonly number[])[])[]}>
+  | Readonly<{type: 'MultiPoint'; coordinates: readonly (readonly number[])[]}>
+  | Readonly<{
+      type: 'MultiLineString';
+      coordinates: readonly (readonly (readonly number[])[])[];
+    }>
+  | Readonly<{
+      type: 'MultiPolygon';
+      coordinates: readonly (readonly (readonly (readonly number[])[])[])[];
+    }>
+  | Readonly<{type: 'GeometryCollection'; geometries: readonly WellKnownGeometry[]}>;
+
+/** Returns the number of coordinate components in a semantic dimension. */
+export function getWellKnownDimensionSize(dimension: WellKnownDimension): 2 | 3 | 4 {
+  switch (dimension) {
+    case 'xy':
+      return 2;
+    case 'xyz':
+    case 'xym':
+      return 3;
+    case 'xyzm':
+      return 4;
+  }
+}
+
+/** Infers tuple width from the deepest non-empty geometry coordinate. Three values mean XYZ. */
+export function inferWellKnownGeometryDimension(geometry: WellKnownGeometry): WellKnownDimension {
+  const size = getGeometryDimensionSize(geometry);
+  return size >= 4 ? 'xyzm' : size === 3 ? 'xyz' : 'xy';
+}
+
+function getGeometryDimensionSize(geometry: WellKnownGeometry): number {
+  if (geometry.type === 'GeometryCollection') {
+    return Math.max(2, ...geometry.geometries.map(getGeometryDimensionSize));
+  }
+  return getCoordinateDimension(geometry.coordinates);
+}
+
+function getCoordinateDimension(value: readonly unknown[]): number {
+  if (value.length === 0) return 2;
+  if (typeof value[0] === 'number') return value.length;
+  return Math.max(2, ...value.map(child => getCoordinateDimension(child as readonly unknown[])));
+}

package/src/wkb/wkb-builder.ts

@@ -0,0 +1,395 @@
+// math.gl
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
+
+import type {WellKnownDimension} from './types';
+import type {WKBGeometryType} from './wkb-reader';
+
+/** Function that writes one WKB geometry into a builder. */
+export type WKBGeometryWriter = (builder: WKBBuilder) => void;
+
+/** Transforms one complete coordinate before it is written. */
+export type WKBCoordinateTransform = (
+  coordinate: readonly number[],
+  dimension: WellKnownDimension
+) => readonly number[];
+
+/** Options shared by WKB measuring and writing modes. */
+export type WKBBuilderBaseOptions = Readonly<{
+  /** Coordinate dimension written by every geometry header. Defaults to `xy`. */
+  dimension?: WellKnownDimension;
+  /** Optional per-row dimension resolver used by geometry-array helpers. */
+  dimensionResolver?: (geometryIndex: number) => WellKnownDimension;
+  /** Byte order written by every geometry header. Defaults to little endian. */
+  byteOrder?: 'little-endian' | 'big-endian';
+  /** Optional EWKB spatial reference identifier. */
+  srid?: number;
+  /** Optional coordinate transform applied during writing and measurement. */
+  transform?: WKBCoordinateTransform;
+}>;
+
+/** Options for a builder that only measures byte length. */
+export type WKBBuilderMeasureOptions = WKBBuilderBaseOptions & Readonly<{mode: 'measure'}>;
+
+/** Options for a builder that writes into caller-owned storage. */
+export type WKBBuilderWriteOptions = WKBBuilderBaseOptions &
+  Readonly<{
+    mode: 'write';
+    target: ArrayBufferLike | ArrayBufferView;
+    /** Starting byte offset within `target`. Defaults to zero. */
+    byteOffset?: number;
+  }>;
+
+/** Constructor options for {@link WKBBuilder}. */
+export type WKBBuilderOptions = WKBBuilderMeasureOptions | WKBBuilderWriteOptions;
+
+/** Plain offset, value, and validity buffers suitable for Arrow Binary adapters. */
+export type WKBGeometryArray = Readonly<{
+  valueOffsets: Int32Array;
+  values: Uint8Array;
+  nullBitmap?: Uint8Array;
+  nullCount: number;
+}>;
+
+const GEOMETRY_TYPE_CODES: Readonly<Record<WKBGeometryType, number>> = {
+  Point: 1,
+  LineString: 2,
+  Polygon: 3,
+  MultiPoint: 4,
+  MultiLineString: 5,
+  MultiPolygon: 6,
+  GeometryCollection: 7
+};
+
+/**
+ * Incremental WKB writer with matching measure and caller-buffer write modes.
+ *
+ * Callers run the same event sequence once in `measure` mode and once in `write`
+ * mode. No Arrow or GeoJSON objects are created by the builder.
+ */
+export class WKBBuilder {
+  readonly mode: 'measure' | 'write';
+  dimension: WellKnownDimension;
+  readonly littleEndian: boolean;
+  readonly srid?: number;
+  readonly transform?: WKBCoordinateTransform;
+
+  private readonly dataView: DataView | null;
+  private readonly startByteOffset: number;
+  private readonly endByteOffset: number;
+  private byteOffset: number;
+
+  constructor(options: WKBBuilderOptions) {
+    this.mode = options.mode;
+    this.dimension = options.dimension ?? 'xy';
+    this.littleEndian = options.byteOrder !== 'big-endian';
+    this.srid = options.srid;
+    this.transform = options.transform;
+    validateSrid(this.srid);
+
+    if (options.mode === 'write') {
+      const dataView = getTargetDataView(options.target);
+      const byteOffset = options.byteOffset ?? 0;
+      if (!Number.isSafeInteger(byteOffset) || byteOffset < 0 || byteOffset > dataView.byteLength) {
+        throw new Error('WKBBuilder byteOffset is outside the target');
+      }
+      this.dataView = dataView;
+      this.startByteOffset = byteOffset;
+      this.endByteOffset = dataView.byteLength;
+      this.byteOffset = byteOffset;
+    } else {
+      this.dataView = null;
+      this.startByteOffset = 0;
+      this.endByteOffset = Number.POSITIVE_INFINITY;
+      this.byteOffset = 0;
+    }
+  }
+
+  /** Begins a geometry and writes its count field when required. */
+  beginGeometry(type: WKBGeometryType, count?: number): void {
+    switch (type) {
+      case 'Point':
+        this.beginPoint();
+        break;
+      case 'LineString':
+        this.beginLineString(count ?? 0);
+        break;
+      case 'Polygon':
+        this.beginPolygon(count ?? 0);
+        break;
+      case 'MultiPoint':
+        this.beginMultiPoint(count ?? 0);
+        break;
+      case 'MultiLineString':
+        this.beginMultiLineString(count ?? 0);
+        break;
+      case 'MultiPolygon':
+        this.beginMultiPolygon(count ?? 0);
+        break;
+      case 'GeometryCollection':
+        this.writeHeader('GeometryCollection');
+        this.writeUint32(count ?? 0);
+        break;
+    }
+  }
+
+  /** Begins one point geometry. */
+  beginPoint(): void {
+    this.writeHeader('Point');
+  }
+
+  /** Begins one linestring geometry. */
+  beginLineString(pointCount: number): void {
+    this.writeHeader('LineString');
+    this.writeUint32(pointCount);
+  }
+
+  /** Begins one polygon geometry. */
+  beginPolygon(ringCount: number): void {
+    this.writeHeader('Polygon');
+    this.writeUint32(ringCount);
+  }
+
+  /** Begins one linear ring inside a polygon. */
+  beginLinearRing(pointCount: number): void {
+    this.writeUint32(pointCount);
+  }
+
+  /** Begins one multipoint geometry. */
+  beginMultiPoint(pointCount: number): void {
+    this.writeHeader('MultiPoint');
+    this.writeUint32(pointCount);
+  }
+
+  /** Begins one multilinestring geometry. */
+  beginMultiLineString(lineCount: number): void {
+    this.writeHeader('MultiLineString');
+    this.writeUint32(lineCount);
+  }
+
+  /** Begins one multipolygon geometry. */
+  beginMultiPolygon(polygonCount: number): void {
+    this.writeHeader('MultiPolygon');
+    this.writeUint32(polygonCount);
+  }
+
+  /** Writes one coordinate using the builder's semantic dimension. */
+  writeCoordinate(x: number, y: number, z?: number, m?: number): void {
+    let coordinate = makeCoordinate(this.dimension, x, y, z, m);
+    if (this.transform) coordinate = this.transform(coordinate, this.dimension);
+    const coordinateSize = getDimensionSize(this.dimension);
+    for (let index = 0; index < coordinateSize; index++) {
+      this.writeFloat64(coordinate[index] ?? Number.NaN);
+    }
+  }
+
+  /** Temporarily changes the semantic dimension for a nested geometry. */
+  withDimension<T>(dimension: WellKnownDimension, callback: () => T): T {
+    const previous = this.dimension;
+    this.dimension = dimension;
+    try {
+      return callback();
+    } finally {
+      this.dimension = previous;
+    }
+  }
+
+  /** Returns the number of bytes measured or written. */
+  finishGeometry(): number {
+    return this.byteOffset - this.startByteOffset;
+  }
+
+  /** Measures geometry callbacks and returns contiguous Binary offsets. */
+  static measureGeometryArray(
+    geometryWriters: readonly (WKBGeometryWriter | null | undefined)[],
+    options: WKBBuilderBaseOptions = {}
+  ): Int32Array {
+    const valueOffsets = new Int32Array(geometryWriters.length + 1);
+    for (let geometryIndex = 0; geometryIndex < geometryWriters.length; geometryIndex++) {
+      const geometryWriter = geometryWriters[geometryIndex];
+      const byteLength = geometryWriter
+        ? measureGeometry(geometryWriter, {
+            ...options,
+            dimension: options.dimensionResolver?.(geometryIndex) ?? options.dimension
+          })
+        : 0;
+      const nextOffset = valueOffsets[geometryIndex] + byteLength;
+      if (nextOffset > 0x7fffffff) throw new Error('WKB geometry array exceeds Int32 offsets');
+      valueOffsets[geometryIndex + 1] = nextOffset;
+    }
+    return valueOffsets;
+  }
+
+  /** Writes geometry callbacks into an existing contiguous values buffer. */
+  static writeGeometryArray(
+    geometryWriters: readonly (WKBGeometryWriter | null | undefined)[],
+    valueOffsets: Int32Array,
+    values: Uint8Array,
+    options: WKBBuilderBaseOptions = {}
+  ): Uint8Array {
+    if (valueOffsets.length !== geometryWriters.length + 1) {
+      throw new Error('WKB valueOffsets length must equal geometry count plus one');
+    }
+    for (let i = 0; i < valueOffsets.length; i++) {
+      if (
+        !Number.isInteger(valueOffsets[i]) ||
+        valueOffsets[i] < 0 ||
+        (i > 0 && valueOffsets[i] < valueOffsets[i - 1])
+      ) {
+        throw new Error('WKB valueOffsets must be nonnegative and nondecreasing');
+      }
+    }
+    if (valueOffsets[valueOffsets.length - 1] > values.byteLength) {
+      throw new Error('WKB values buffer is smaller than its final offset');
+    }
+    for (let geometryIndex = 0; geometryIndex < geometryWriters.length; geometryIndex++) {
+      const geometryWriter = geometryWriters[geometryIndex];
+      if (!geometryWriter) continue;
+      const builder = new WKBBuilder({
+        ...options,
+        mode: 'write',
+        target: values,
+        byteOffset: valueOffsets[geometryIndex],
+        dimension: options.dimensionResolver?.(geometryIndex) ?? options.dimension
+      });
+      geometryWriter(builder);
+      const byteLength = builder.finishGeometry();
+      if (valueOffsets[geometryIndex] + byteLength !== valueOffsets[geometryIndex + 1]) {
+        throw new Error('WKB measure and write passes produced different byte lengths');
+      }
+    }
+    return values;
+  }
+
+  /** Builds plain offsets, values, and validity buffers in two passes. */
+  static buildGeometryArray(
+    geometryWriters: readonly (WKBGeometryWriter | null | undefined)[],
+    options: WKBBuilderBaseOptions = {}
+  ): WKBGeometryArray {
+    const valueOffsets = WKBBuilder.measureGeometryArray(geometryWriters, options);
+    const values = new Uint8Array(valueOffsets[valueOffsets.length - 1]);
+    WKBBuilder.writeGeometryArray(geometryWriters, valueOffsets, values, options);
+    const {nullBitmap, nullCount} = makeNullBitmap(geometryWriters);
+    return {
+      valueOffsets,
+      values,
+      ...(nullCount > 0 ? {nullBitmap} : {}),
+      nullCount
+    };
+  }
+
+  private writeHeader(geometryType: WKBGeometryType): void {
+    this.writeUint8(this.littleEndian ? 1 : 0);
+    this.writeUint32(getWKBTypeCode(geometryType, this.dimension, this.srid !== undefined));
+    if (this.srid !== undefined) this.writeUint32(this.srid);
+  }
+
+  private writeUint8(value: number): void {
+    this.ensureSize(1);
+    this.dataView?.setUint8(this.byteOffset, value);
+    this.byteOffset++;
+  }
+
+  private writeUint32(value: number): void {
+    if (!Number.isSafeInteger(value) || value < 0 || value > 0xffffffff) {
+      throw new Error('WKB count must be an unsigned 32-bit integer');
+    }
+    this.ensureSize(4);
+    this.dataView?.setUint32(this.byteOffset, value, this.littleEndian);
+    this.byteOffset += 4;
+  }
+
+  private writeFloat64(value: number): void {
+    this.ensureSize(8);
+    this.dataView?.setFloat64(this.byteOffset, value, this.littleEndian);
+    this.byteOffset += 8;
+  }
+
+  private ensureSize(byteLength: number): void {
+    if (this.byteOffset + byteLength > this.endByteOffset) {
+      throw new Error('WKBBuilder target buffer overflow');
+    }
+  }
+}
+
+function measureGeometry(
+  geometryWriter: WKBGeometryWriter,
+  options: WKBBuilderBaseOptions
+): number {
+  const builder = new WKBBuilder({...options, mode: 'measure'});
+  geometryWriter(builder);
+  return builder.finishGeometry();
+}
+
+function getTargetDataView(target: ArrayBufferLike | ArrayBufferView): DataView {
+  return ArrayBuffer.isView(target)
+    ? new DataView(target.buffer, target.byteOffset, target.byteLength)
+    : new DataView(target);
+}
+
+function getWKBTypeCode(
+  geometryType: WKBGeometryType,
+  dimension: WellKnownDimension,
+  hasSrid: boolean
+): number {
+  const geometryCode = GEOMETRY_TYPE_CODES[geometryType];
+  if (hasSrid) {
+    const dimensionFlags =
+      dimension === 'xyz'
+        ? 0x80000000
+        : dimension === 'xym'
+          ? 0x40000000
+          : dimension === 'xyzm'
+            ? 0xc0000000
+            : 0;
+    return (geometryCode | dimensionFlags | 0x20000000) >>> 0;
+  }
+  const dimensionOffset =
+    dimension === 'xyz' ? 1000 : dimension === 'xym' ? 2000 : dimension === 'xyzm' ? 3000 : 0;
+  return geometryCode + dimensionOffset;
+}
+
+function makeCoordinate(
+  dimension: WellKnownDimension,
+  x: number,
+  y: number,
+  z?: number,
+  m?: number
+): readonly number[] {
+  switch (dimension) {
+    case 'xy':
+      return [x, y];
+    case 'xyz':
+      return [x, y, z ?? Number.NaN];
+    case 'xym':
+      return [x, y, m ?? Number.NaN];
+    case 'xyzm':
+      return [x, y, z ?? Number.NaN, m ?? Number.NaN];
+  }
+}
+
+function getDimensionSize(dimension: WellKnownDimension): 2 | 3 | 4 {
+  return dimension === 'xy' ? 2 : dimension === 'xyzm' ? 4 : 3;
+}
+
+function validateSrid(srid: number | undefined): void {
+  if (srid !== undefined && (!Number.isSafeInteger(srid) || srid < 0 || srid > 0xffffffff)) {
+    throw new Error('WKBBuilder srid must be an unsigned 32-bit integer');
+  }
+}
+
+function makeNullBitmap(geometryWriters: readonly (WKBGeometryWriter | null | undefined)[]): {
+  nullBitmap: Uint8Array;
+  nullCount: number;
+} {
+  const nullBitmap = new Uint8Array(Math.ceil(geometryWriters.length / 8));
+  let nullCount = 0;
+  for (let geometryIndex = 0; geometryIndex < geometryWriters.length; geometryIndex++) {
+    if (geometryWriters[geometryIndex]) {
+      nullBitmap[geometryIndex >> 3] |= 1 << (geometryIndex & 7);
+    } else {
+      nullCount++;
+    }
+  }
+  return {nullBitmap, nullCount};
+}