@loaders.gl/gis 4.3.4 → 4.4.0-alpha.10

package/src/lib/geometry-converters/wkb/convert-wkt-to-geometry.ts

@@ -0,0 +1,294 @@
+// loaders.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+// Fork of https://github.com/mapbox/wellknown under ISC license (MIT/BSD-2-clause equivalent)
+
+import type {Geometry} from '@loaders.gl/schema';
+
+/* eslint-disable */
+// @ts-nocheck
+
+const numberRegexp = /[-+]?([0-9]*\.[0-9]+|[0-9]+)([eE][-+]?[0-9]+)?/;
+// Matches sequences like '100 100' or '100 100 100'.
+const tuples = new RegExp('^' + numberRegexp.source + '(\\s' + numberRegexp.source + '){1,}');
+
+export type ParseWKTOptions = {
+  wkt?: {
+    /** Whether to add any CRS, if found, as undocumented CRS property on the return geometry */
+    crs?: boolean;
+  };
+};
+
+/** State of parser, passed around between parser functions */
+type ParseWKTState = {
+  parts: string[];
+  _: string | undefined;
+  i: number;
+};
+
+/**
+ * Parse WKT and return GeoJSON.
+ * @param input A WKT geometry string
+ * @return A GeoJSON geometry object
+ *
+ * @note We only support the "geojson" subset of the OGC simple features standard
+ **/
+export function convertWKTToGeometry(input: string, options?: ParseWKTOptions): Geometry | null {
+  const parts = input.split(';');
+  let _ = parts.pop();
+  const srid = (parts.shift() || '').split('=').pop();
+
+  const state: ParseWKTState = {parts, _, i: 0};
+
+  const geometry = parseGeometry(state);
+
+  return options?.wkt?.crs ? addCRS(geometry, srid) : geometry;
+}
+
+function parseGeometry(state: ParseWKTState): Geometry | null {
+  return (
+    parsePoint(state) ||
+    parseLineString(state) ||
+    parsePolygon(state) ||
+    parseMultiPoint(state) ||
+    parseMultiLineString(state) ||
+    parseMultiPolygon(state) ||
+    parseGeometryCollection(state)
+  );
+}
+
+/** Adds a coordinate reference system as an undocumented  */
+function addCRS(obj: Geometry | null, srid?: string): Geometry | null {
+  if (obj && srid?.match(/\d+/)) {
+    const crs = {
+      type: 'name',
+      properties: {
+        name: 'urn:ogc:def:crs:EPSG::' + srid
+      }
+    };
+    // @ts-expect-error we assign an undocumented property on the geometry
+    obj.crs = crs;
+  }
+
+  return obj;
+}
+
+// GEOMETRIES
+
+function parsePoint(state: ParseWKTState): Geometry | null {
+  if (!$(/^(POINT(\sz)?)/i, state)) {
+    return null;
+  }
+  white(state);
+  if (!$(/^(\()/, state)) {
+    return null;
+  }
+  const c = coords(state);
+  if (!c) {
+    return null;
+  }
+  white(state);
+  if (!$(/^(\))/, state)) {
+    return null;
+  }
+  return {
+    type: 'Point',
+    coordinates: c[0]
+  };
+}
+
+function parseMultiPoint(state: ParseWKTState): Geometry | null {
+  if (!$(/^(MULTIPOINT)/i, state)) {
+    return null;
+  }
+  white(state);
+  const newCoordsFormat = state._?.substring(state._?.indexOf('(') + 1, state._.length - 1)
+    .replace(/\(/g, '')
+    .replace(/\)/g, '');
+  state._ = 'MULTIPOINT (' + newCoordsFormat + ')';
+  const c = multicoords(state);
+  if (!c) {
+    return null;
+  }
+  white(state);
+  return {
+    type: 'MultiPoint',
+    coordinates: c
+  };
+}
+
+function parseLineString(state: ParseWKTState): Geometry | null {
+  if (!$(/^(LINESTRING(\sz)?)/i, state)) {
+    return null;
+  }
+  white(state);
+  if (!$(/^(\()/, state)) {
+    return null;
+  }
+  const c = coords(state);
+  if (!c) {
+    return null;
+  }
+  if (!$(/^(\))/, state)) {
+    return null;
+  }
+  return {
+    type: 'LineString',
+    coordinates: c
+  };
+}
+
+function parseMultiLineString(state: ParseWKTState): Geometry | null {
+  if (!$(/^(MULTILINESTRING)/i, state)) return null;
+  white(state);
+  const c = multicoords(state);
+  if (!c) {
+    return null;
+  }
+  white(state);
+  return {
+    // @ts-ignore
+    type: 'MultiLineString',
+    // @ts-expect-error
+    coordinates: c
+  };
+}
+
+function parsePolygon(state: ParseWKTState): Geometry | null {
+  if (!$(/^(POLYGON(\sz)?)/i, state)) {
+    return null;
+  }
+  white(state);
+  const c = multicoords(state);
+  if (!c) {
+    return null;
+  }
+  return {
+    // @ts-ignore
+    type: 'Polygon',
+    // @ts-expect-error
+    coordinates: c
+  };
+}
+
+function parseMultiPolygon(state: ParseWKTState): Geometry | null {
+  if (!$(/^(MULTIPOLYGON)/i, state)) {
+    return null;
+  }
+  white(state);
+  const c = multicoords(state);
+  if (!c) {
+    return null;
+  }
+  return {
+    type: 'MultiPolygon',
+    // @ts-expect-error
+    coordinates: c
+  };
+}
+
+function parseGeometryCollection(state: ParseWKTState): Geometry | null {
+  const geometries: Geometry[] = [];
+  let geometry: Geometry | null;
+
+  if (!$(/^(GEOMETRYCOLLECTION)/i, state)) {
+    return null;
+  }
+  white(state);
+
+  if (!$(/^(\()/, state)) {
+    return null;
+  }
+  while ((geometry = parseGeometry(state))) {
+    geometries.push(geometry);
+    white(state);
+    $(/^(,)/, state);
+    white(state);
+  }
+  if (!$(/^(\))/, state)) {
+    return null;
+  }
+
+  return {
+    type: 'GeometryCollection',
+    geometries: geometries
+  };
+}
+
+// COORDINATES
+
+function multicoords(state: ParseWKTState): number[][] | null {
+  white(state);
+  let depth = 0;
+  const rings: number[][] = [];
+  const stack = [rings];
+  let pointer: any = rings;
+  let elem;
+
+  while ((elem = $(/^(\()/, state) || $(/^(\))/, state) || $(/^(,)/, state) || $(tuples, state))) {
+    if (elem === '(') {
+      stack.push(pointer);
+      pointer = [];
+      stack[stack.length - 1].push(pointer);
+      depth++;
+    } else if (elem === ')') {
+      // For the case: Polygon(), ...
+      if (pointer.length === 0) return null;
+
+      // @ts-ignore
+      pointer = stack.pop();
+      // the stack was empty, input was malformed
+      if (!pointer) return null;
+      depth--;
+      if (depth === 0) break;
+    } else if (elem === ',') {
+      pointer = [];
+      stack[stack.length - 1].push(pointer);
+    } else if (!elem.split(/\s/g).some(isNaN)) {
+      Array.prototype.push.apply(pointer, elem.split(/\s/g).map(parseFloat));
+    } else {
+      return null;
+    }
+    white(state);
+  }
+
+  if (depth !== 0) return null;
+
+  return rings;
+}
+
+function coords(state: ParseWKTState): number[][] | null {
+  const list: number[][] = [];
+  let item: any;
+  let pt;
+  while ((pt = $(tuples, state) || $(/^(,)/, state))) {
+    if (pt === ',') {
+      list.push(item);
+      item = [];
+    } else if (!pt.split(/\s/g).some(isNaN)) {
+      if (!item) item = [];
+      Array.prototype.push.apply(item, pt.split(/\s/g).map(parseFloat));
+    }
+    white(state);
+  }
+
+  if (item) list.push(item);
+  else return null;
+
+  return list.length ? list : null;
+}
+
+// HELPERS
+
+function $(regexp: RegExp, state: ParseWKTState) {
+  const match = state._?.substring(state.i).match(regexp);
+  if (!match) return null;
+  else {
+    state.i += match[0].length;
+    return match[0];
+  }
+}
+
+function white(state: ParseWKTState) {
+  $(/^\s*/, state);
+}

package/src/lib/geometry-converters/wkb/helpers/parse-wkb-header.ts

@@ -0,0 +1,213 @@
+// loaders.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import type {WKBGeometryType, WKBHeader} from './wkb-types';
+import {
+  EWKB_FLAG_Z,
+  EWKB_FLAG_M,
+  EWKB_FLAG_SRID,
+  MAX_SRID,
+  WKT_MAGIC_STRINGS,
+  WKT_MAGIC_BYTES
+} from './wkb-types';
+
+/** 
+ * Check if a string is WKT.
+ * @param input A potential WKT geometry string
+ * @return `true` if input appears to be a WKT geometry string, `false` otherwise
+
+ * @note We only support the "geojson" subset of the OGC simple features standard
+ * @todo Does not handle leading spaces which appear to be permitted per the spec:
+ * "A WKT string contains no white space outside of double quotes. 
+ * However padding with white space to improve human readability is permitted; 
+ * the examples of WKT that are included in this document have 
+ * spaces and line feeds inserted to improve clarity. Any padding is stripped out or ignored by parsers."
+ */
+export function isWKT(input: string | ArrayBufferLike): boolean {
+  return getWKTGeometryType(input) !== null;
+}
+
+/** 
+ * Get the geometry type of a WKT string.
+ * @param input A potential WKT geometry string
+ * @return `true` if input appears to be a WKT geometry string, `false` otherwise
+
+ * @note We only support the "geojson" subset of the OGC simple features standard
+ * @todo Does not handle leading spaces which appear to be permitted per the spec:
+ * "A WKT string contains no white space outside of double quotes. 
+ * However padding with white space to improve human readability is permitted; 
+ * the examples of WKT that are included in this document have 
+ * spaces and line feeds inserted to improve clarity. Any padding is stripped out or ignored by parsers."
+ */
+export function getWKTGeometryType(input: string | ArrayBufferLike): WKBGeometryType | null {
+  if (typeof input === 'string') {
+    const index = WKT_MAGIC_STRINGS.findIndex((magicString) => input.startsWith(magicString));
+    return index >= 0 ? ((index + 1) as WKBGeometryType) : null;
+  }
+  const inputArray = new Uint8Array(input);
+  const index = WKT_MAGIC_BYTES.findIndex((magicBytes) =>
+    magicBytes.every((value, index) => value === inputArray[index])
+  );
+  return index >= 0 ? ((index + 1) as WKBGeometryType) : null;
+}
+
+/**
+ * Check if an array buffer might be a TWKB array buffer
+ * @param arrayBuffer The array buffer to check
+ * @returns false if this is definitely not a TWKB array buffer, true if it might be a TWKB array buffer
+ */
+export function isTWKB(arrayBuffer: ArrayBufferLike): boolean {
+  const dataView = new DataView(arrayBuffer);
+  const byteOffset = 0;
+
+  const type = dataView.getUint8(byteOffset);
+  const geometryType = type & 0x0f;
+
+  // Only geometry types 1 to 7 (point to geometry collection are currently defined)
+  if (geometryType < 1 || geometryType > 7) {
+    return false;
+  }
+
+  return true;
+}
+
+/** Sanity checks that first to 5-9 bytes could represent a supported WKB dialect header */
+export function isWKB(arrayBuffer: ArrayBufferLike): boolean {
+  const dataView = new DataView(arrayBuffer);
+  let byteOffset = 0;
+
+  const endianness = dataView.getUint8(byteOffset);
+  byteOffset += 1;
+
+  // Check valid endianness (only 0 or 1 are allowed)
+  if (endianness > 1) {
+    return false;
+  }
+
+  const littleEndian = endianness === 1;
+
+  const geometry = dataView.getUint32(byteOffset, littleEndian);
+  byteOffset += 4;
+
+  // check valid geometry type (we don't support extension geometries)
+  const geometryType = geometry & 0x07;
+  if (geometryType === 0 || geometryType > 7) {
+    return false;
+  }
+
+  const geometryFlags = geometry - geometryType;
+
+  // Accept iso-wkb flags
+  if (
+    geometryFlags === 0 ||
+    geometryFlags === 1000 ||
+    geometryFlags === 2000 ||
+    geometryFlags === 3000
+  ) {
+    return true;
+  }
+
+  // Accept ewkb flags but reject otherwise
+  if ((geometryFlags & ~(EWKB_FLAG_Z | EWKB_FLAG_M | EWKB_FLAG_SRID)) !== 0) {
+    return false;
+  }
+
+  if (geometryFlags & EWKB_FLAG_SRID) {
+    const srid = dataView.getUint32(byteOffset, littleEndian);
+    byteOffset += 4;
+
+    if (srid > MAX_SRID) {
+      return false;
+    }
+  }
+
+  return true;
+}
+
+/**
+ * Parses header and provides a byteOffset to start of geometry data
+ * @param dataView
+ * @param target optionally supply a WKBHeader object to avoid creating a new object for every call
+ * @returns a header object describing the WKB data
+ */
+// eslint-disable-next-line max-statements, complexity
+export function parseWKBHeader(dataView: DataView, target?: WKBHeader): WKBHeader {
+  const wkbHeader: WKBHeader = Object.assign(target || {}, {
+    type: 'wkb',
+    variant: 'wkb',
+    geometryType: 1,
+    dimensions: 2,
+    coordinates: 'xy',
+    littleEndian: true,
+    byteOffset: 0
+  } as WKBHeader);
+
+  if (isWKT(dataView.buffer)) {
+    // TODO - WKB header could include WKT type
+    throw new Error('WKB: Cannot parse WKT data');
+  }
+
+  // Check endianness of data
+  wkbHeader.littleEndian = dataView.getUint8(wkbHeader.byteOffset) === 1;
+  wkbHeader.byteOffset++;
+
+  // 4-digit code representing dimension and type of geometry
+  const geometryCode = dataView.getUint32(wkbHeader.byteOffset, wkbHeader.littleEndian);
+  wkbHeader.byteOffset += 4;
+
+  wkbHeader.geometryType = (geometryCode & 0x7) as 1 | 2 | 3 | 4 | 5 | 6 | 7;
+
+  // Check if iso-wkb variant: iso-wkb adds 1000, 2000 or 3000 to the geometry code
+  const isoType = (geometryCode - wkbHeader.geometryType) / 1000;
+  switch (isoType) {
+    case 0:
+      break;
+    case 1:
+      wkbHeader.variant = 'iso-wkb';
+      wkbHeader.dimensions = 3;
+      wkbHeader.coordinates = 'xyz';
+      break;
+    case 2:
+      wkbHeader.variant = 'iso-wkb';
+      wkbHeader.dimensions = 3;
+      wkbHeader.coordinates = 'xym';
+      break;
+    case 3:
+      wkbHeader.variant = 'iso-wkb';
+      wkbHeader.dimensions = 4;
+      wkbHeader.coordinates = 'xyzm';
+      break;
+    default:
+      throw new Error(`WKB: Unsupported iso-wkb type: ${isoType}`);
+  }
+
+  // Check if EWKB variant. Uses bitmasks for Z&M dimensions as well as optional SRID field
+  const ewkbZ = geometryCode & EWKB_FLAG_Z;
+  const ewkbM = geometryCode & EWKB_FLAG_M;
+  const ewkbSRID = geometryCode & EWKB_FLAG_SRID;
+
+  if (ewkbZ && ewkbM) {
+    wkbHeader.variant = 'ewkb';
+    wkbHeader.dimensions = 4;
+    wkbHeader.coordinates = 'xyzm';
+  } else if (ewkbZ) {
+    wkbHeader.variant = 'ewkb';
+    wkbHeader.dimensions = 3;
+    wkbHeader.coordinates = 'xyz';
+  } else if (ewkbM) {
+    wkbHeader.variant = 'ewkb';
+    wkbHeader.dimensions = 3;
+    wkbHeader.coordinates = 'xym';
+  }
+
+  // If SRID present read four more bytes
+  if (ewkbSRID) {
+    wkbHeader.variant = 'ewkb';
+    // 4-digit code representing dimension and type of geometry
+    wkbHeader.srid = dataView.getUint32(wkbHeader.byteOffset, wkbHeader.littleEndian);
+    wkbHeader.byteOffset += 4;
+  }
+
+  return wkbHeader;
+}

package/src/lib/geometry-converters/wkb/helpers/wkb-types.ts

@@ -0,0 +1,82 @@
+// loaders.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+/**
+ * Integer codes for geometry types in WKB and related formats
+ * @see: https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry#Well-known_binary
+ */
+export enum WKBGeometryType {
+  Point = 1,
+  LineString = 2,
+  Polygon = 3,
+  MultiPoint = 4,
+  MultiLineString = 5,
+  MultiPolygon = 6,
+  GeometryCollection = 7
+}
+
+/** Parsed WKB header */
+export type WKBHeader = {
+  /** WKB or TWKB */
+  type: 'wkb' | 'twkb';
+  /** WKB variant */
+  variant: 'wkb' | 'ewkb' | 'iso-wkb' | 'twkb';
+  /** geometry type encoded in this WKB: point, line, polygon etc */
+  geometryType: 1 | 2 | 3 | 4 | 5 | 6 | 7;
+  /** Number of dimensions for coordinate data */
+  dimensions: 2 | 3 | 4;
+  /** Coordinate names, Z and M are controlled by flags */
+  coordinates: 'xy' | 'xyz' | 'xym' | 'xyzm';
+  /** WKB Geometry has a spatial coordinate reference system id */
+  srid?: number;
+  /** true if binary data is stored as little endian */
+  littleEndian: boolean;
+  /** Offset to start of geometry */
+  byteOffset: number;
+};
+
+/**
+ * Options for writing WKB
+ */
+export type WKBOptions = {
+  /** Does the GeoJSON input have Z values? */
+  hasZ?: boolean;
+  /** Does the GeoJSON input have M values? */
+  hasM?: boolean;
+  /** Spatial reference for input GeoJSON */
+  srid?: any;
+};
+
+/** WKB Geometry has a z coordinate */
+export const EWKB_FLAG_Z = 0x80000000;
+/** WKB Geometry has an m coordinate */
+export const EWKB_FLAG_M = 0x40000000;
+/** WKB Geometry has a spatial coordinate reference system id */
+export const EWKB_FLAG_SRID = 0x20000000;
+/** @todo: Assume no more than 10K SRIDs are defined */
+export const MAX_SRID = 10000;
+
+/**
+ * @see: https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry#Well-known_binary
+ * @note Order matches WKBGeometryType enum (need to add 1)
+ * @note: We only support this "geojson" subset of the OGC simple features standard
+ */
+export const WKT_MAGIC_STRINGS = [
+  'POINT(',
+  'LINESTRING(',
+  'POLYGON(',
+  'MULTIPOINT(',
+  'MULTILINESTRING(',
+  'MULTIPOLYGON(',
+  'GEOMETRYCOLLECTION('
+];
+
+const textEncoder = new TextEncoder();
+
+/**
+ * @see: https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry#Well-known_binary
+ * @note Order matches WKBGeometryType enum (need to add 1)
+ * @note: We only support this "geojson" subset of the OGC simple features standard
+ */
+export const WKT_MAGIC_BYTES = WKT_MAGIC_STRINGS.map((string) => textEncoder.encode(string));

package/src/lib/geometry-converters/wkb/helpers/wkb-utils.ts

@@ -0,0 +1,85 @@
+// loaders.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import type {WKBOptions} from './wkb-types';
+import {WKBGeometryType} from './wkb-types';
+
+const WKBGeometryTypeNames = {
+  Point: WKBGeometryType.Point,
+  LineString: WKBGeometryType.LineString,
+  Polygon: WKBGeometryType.Polygon,
+  MultiPoint: WKBGeometryType.MultiPoint,
+  MultiLineString: WKBGeometryType.MultiLineString,
+  MultiPolygon: WKBGeometryType.MultiPolygon,
+  GeometryCollection: WKBGeometryType.GeometryCollection
+} as const satisfies Record<string, WKBGeometryType>;
+
+/** Convert a WKB geometry type integer to GeoJSON style geometry type string*/
+export function getGeometryTypeFromWKBType(
+  wkbGeometryType: WKBGeometryType
+): keyof typeof WKBGeometryTypeNames {
+  for (const key in WKBGeometryTypeNames) {
+    if (WKBGeometryTypeNames[key] === wkbGeometryType) {
+      return key as keyof typeof WKBGeometryTypeNames;
+    }
+  }
+  throw new Error(String(wkbGeometryType));
+}
+
+/** Convert a GeoJSON style geometry type string to a WKB geometry type integer*/
+export function getWKBTypeFromGeometryType(
+  geometryType: keyof typeof WKBGeometryTypeNames
+): WKBGeometryType {
+  return WKBGeometryTypeNames[geometryType];
+}
+
+/** Sanity: Adjust Z/M dimensions with actual point size */
+export function matchWKBOptionsToPointSize(
+  pointSize: number,
+  options?: WKBOptions
+): Required<WKBOptions> {
+  const wkbOptions: Required<WKBOptions> = {hasZ: false, hasM: false, srid: undefined, ...options};
+
+  // Align options with actual point size
+  switch (pointSize) {
+    case 4:
+      wkbOptions.hasZ = true;
+      wkbOptions.hasM = true;
+      break;
+
+    case 3:
+      // Prefer Z over M
+      if (wkbOptions.hasZ && wkbOptions.hasM) {
+        wkbOptions.hasM = false;
+      }
+      if (!wkbOptions.hasZ && !wkbOptions.hasM) {
+        wkbOptions.hasZ = true;
+      }
+      break;
+
+    case 2:
+      wkbOptions.hasZ = false;
+      wkbOptions.hasM = false;
+      break;
+
+    default:
+    // ignore - broken input data?
+  }
+
+  return wkbOptions;
+}
+
+/** Get coordinate size given Z/M dimensions */
+export function getCoordinateByteSize(options?: WKBOptions): number {
+  let coordinateByteSize = 16;
+
+  if (options?.hasZ) {
+    coordinateByteSize += 8;
+  }
+  if (options?.hasM) {
+    coordinateByteSize += 8;
+  }
+
+  return coordinateByteSize;
+}

package/src/lib/geometry-converters/wkb/helpers/write-wkb-header.ts

@@ -0,0 +1,41 @@
+// loaders.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import {BinaryWriter} from '../../../utils/binary-writer';
+import type {WKBOptions} from './wkb-types';
+
+/**
+ * Construct and write WKB integer code
+ * Reference: https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry#Well-known_binary
+ */
+export function writeWkbHeader(
+  writer: BinaryWriter,
+  geometryType: number,
+  options?: WKBOptions
+): void {
+  // little endian
+  writer.writeInt8(1);
+  const {hasZ, hasM, srid} = options || {};
+
+  let dimensionType = 0;
+
+  if (!srid) {
+    if (hasZ && hasM) {
+      dimensionType += 3000;
+    } else if (hasZ) {
+      dimensionType += 1000;
+    } else if (hasM) {
+      dimensionType += 2000;
+    }
+  } else {
+    if (hasZ) {
+      dimensionType |= 0x80000000;
+    }
+    if (hasM) {
+      dimensionType |= 0x40000000;
+    }
+  }
+
+  writer.writeUInt32LE((dimensionType + geometryType) >>> 0);
+}