@loaders.gl/wkt 4.0.0-alpha.24 → 4.0.0-alpha.26

package/src/lib/parse-twkb.ts

@@ -0,0 +1,356 @@
+// loaders.gl, MIT license
+// Forked from https://github.com/cschwarz/wkx under MIT license, Copyright (c) 2013 Christian Schwarz
+
+import type {Geometry, GeometryCollection} from '@loaders.gl/schema';
+import type {Point, LineString, Polygon} from '@loaders.gl/schema';
+import type {MultiPoint, MultiLineString, MultiPolygon} from '@loaders.gl/schema';
+import {BinaryReader} from './utils/binary-reader';
+import {WKBGeometryType} from './parse-wkb-header';
+
+/**
+ * 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: ArrayBuffer): boolean {
+  const binaryReader = new BinaryReader(arrayBuffer);
+
+  const type = binaryReader.readUInt8();
+  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;
+}
+
+/** Passed around between parsing functions, extracted from the header */
+type TWKBHeader = {
+  geometryType: WKBGeometryType;
+
+  hasBoundingBox: boolean;
+  hasSizeAttribute: boolean;
+  hasIdList: boolean;
+  hasExtendedPrecision: boolean;
+  isEmpty: boolean;
+
+  precision: number;
+  precisionFactor: number;
+
+  hasZ: boolean;
+  zPrecision: number;
+  zPrecisionFactor: number;
+
+  hasM: boolean;
+  mPrecision: number;
+  mPrecisionFactor: number;
+};
+
+export function parseTWKBGeometry(arrayBuffer: ArrayBuffer): Geometry {
+  const binaryReader = new BinaryReader(arrayBuffer);
+
+  const context = parseTWKBHeader(binaryReader);
+
+  if (context.hasSizeAttribute) {
+    binaryReader.readVarInt();
+  }
+
+  if (context.hasBoundingBox) {
+    let dimensions = 2;
+
+    if (context.hasZ) {
+      dimensions++;
+    }
+    if (context.hasM) {
+      dimensions++;
+    }
+
+    // TODO why are we throwing away these datums?
+    for (let i = 0; i < dimensions; i++) {
+      binaryReader.readVarInt();
+      binaryReader.readVarInt();
+    }
+  }
+
+  return parseGeometry(binaryReader, context, context.geometryType);
+}
+
+function parseTWKBHeader(binaryReader: BinaryReader): TWKBHeader {
+  const type = binaryReader.readUInt8();
+  const metadataHeader = binaryReader.readUInt8();
+
+  const geometryType = type & 0x0f;
+
+  const precision = zigZagDecode(type >> 4);
+
+  const hasExtendedPrecision = Boolean((metadataHeader >> 3) & 1);
+  let hasZ = false;
+  let hasM = false;
+  let zPrecision = 0;
+  let zPrecisionFactor = 1;
+  let mPrecision = 0;
+  let mPrecisionFactor = 1;
+
+  if (hasExtendedPrecision) {
+    const extendedPrecision = binaryReader.readUInt8();
+    hasZ = (extendedPrecision & 0x01) === 0x01;
+    hasM = (extendedPrecision & 0x02) === 0x02;
+
+    zPrecision = zigZagDecode((extendedPrecision & 0x1c) >> 2);
+    zPrecisionFactor = Math.pow(10, zPrecision);
+
+    mPrecision = zigZagDecode((extendedPrecision & 0xe0) >> 5);
+    mPrecisionFactor = Math.pow(10, mPrecision);
+  }
+
+  return {
+    geometryType,
+
+    precision,
+    precisionFactor: Math.pow(10, precision),
+
+    hasBoundingBox: Boolean((metadataHeader >> 0) & 1),
+    hasSizeAttribute: Boolean((metadataHeader >> 1) & 1),
+    hasIdList: Boolean((metadataHeader >> 2) & 1),
+    hasExtendedPrecision,
+    isEmpty: Boolean((metadataHeader >> 4) & 1),
+
+    hasZ,
+    hasM,
+    zPrecision,
+    zPrecisionFactor,
+    mPrecision,
+    mPrecisionFactor
+  };
+}
+
+function parseGeometry(
+  binaryReader: BinaryReader,
+  context: TWKBHeader,
+  geometryType: WKBGeometryType
+): Geometry {
+  switch (geometryType) {
+    case WKBGeometryType.Point:
+      return parsePoint(binaryReader, context);
+    case WKBGeometryType.LineString:
+      return parseLineString(binaryReader, context);
+    case WKBGeometryType.Polygon:
+      return parsePolygon(binaryReader, context);
+    case WKBGeometryType.MultiPoint:
+      return parseMultiPoint(binaryReader, context);
+    case WKBGeometryType.MultiLineString:
+      return parseMultiLineString(binaryReader, context);
+    case WKBGeometryType.MultiPolygon:
+      return parseMultiPolygon(binaryReader, context);
+    case WKBGeometryType.GeometryCollection:
+      return parseGeometryCollection(binaryReader, context);
+    default:
+      throw new Error(`GeometryType ${geometryType} not supported`);
+  }
+}
+
+// GEOMETRIES
+
+function parsePoint(reader: BinaryReader, context: TWKBHeader): Point {
+  if (context.isEmpty) {
+    return {type: 'Point', coordinates: []};
+  }
+
+  return {type: 'Point', coordinates: readFirstPoint(reader, context)};
+}
+
+function parseLineString(reader: BinaryReader, context: TWKBHeader): LineString {
+  if (context.isEmpty) {
+    return {type: 'LineString', coordinates: []};
+  }
+
+  const pointCount = reader.readVarInt();
+
+  const previousPoint = makePreviousPoint(context);
+
+  const points: number[][] = [];
+  for (let i = 0; i < pointCount; i++) {
+    points.push(parseNextPoint(reader, context, previousPoint));
+  }
+
+  return {type: 'LineString', coordinates: points};
+}
+
+function parsePolygon(reader: BinaryReader, context: TWKBHeader): Polygon {
+  if (context.isEmpty) {
+    return {type: 'Polygon', coordinates: []};
+  }
+
+  const ringCount = reader.readVarInt();
+
+  const previousPoint = makePreviousPoint(context);
+
+  const exteriorRingLength = reader.readVarInt();
+  const exteriorRing: number[][] = [];
+
+  for (let i = 0; i < exteriorRingLength; i++) {
+    exteriorRing.push(parseNextPoint(reader, context, previousPoint));
+  }
+
+  const polygon: number[][][] = [exteriorRing];
+  for (let i = 1; i < ringCount; i++) {
+    const interiorRingCount = reader.readVarInt();
+
+    const interiorRing: number[][] = [];
+    for (let j = 0; j < interiorRingCount; j++) {
+      interiorRing.push(parseNextPoint(reader, context, previousPoint));
+    }
+
+    polygon.push(interiorRing);
+  }
+
+  return {type: 'Polygon', coordinates: polygon};
+}
+
+function parseMultiPoint(reader: BinaryReader, context: TWKBHeader): MultiPoint {
+  if (context.isEmpty) {
+    return {type: 'MultiPoint', coordinates: []};
+  }
+
+  const previousPoint = makePreviousPoint(context);
+  const pointCount = reader.readVarInt();
+
+  const coordinates: number[][] = [];
+  for (let i = 0; i < pointCount; i++) {
+    coordinates.push(parseNextPoint(reader, context, previousPoint));
+  }
+
+  return {type: 'MultiPoint', coordinates};
+}
+
+function parseMultiLineString(reader: BinaryReader, context: TWKBHeader): MultiLineString {
+  if (context.isEmpty) {
+    return {type: 'MultiLineString', coordinates: []};
+  }
+
+  const previousPoint = makePreviousPoint(context);
+  const lineStringCount = reader.readVarInt();
+
+  const coordinates: number[][][] = [];
+  for (let i = 0; i < lineStringCount; i++) {
+    const pointCount = reader.readVarInt();
+
+    const lineString: number[][] = [];
+    for (let j = 0; j < pointCount; j++) {
+      lineString.push(parseNextPoint(reader, context, previousPoint));
+    }
+
+    coordinates.push(lineString);
+  }
+
+  return {type: 'MultiLineString', coordinates};
+}
+
+function parseMultiPolygon(reader: BinaryReader, context: TWKBHeader): MultiPolygon {
+  if (context.isEmpty) {
+    return {type: 'MultiPolygon', coordinates: []};
+  }
+
+  const previousPoint = makePreviousPoint(context);
+  const polygonCount = reader.readVarInt();
+
+  const polygons: number[][][][] = [];
+  for (let i = 0; i < polygonCount; i++) {
+    const ringCount = reader.readVarInt();
+
+    const exteriorPointCount = reader.readVarInt();
+
+    const exteriorRing: number[][] = [];
+    for (let j = 0; j < exteriorPointCount; j++) {
+      exteriorRing.push(parseNextPoint(reader, context, previousPoint));
+    }
+
+    const polygon: number[][][] = exteriorRing ? [exteriorRing] : [];
+
+    for (let j = 1; j < ringCount; j++) {
+      const interiorRing: number[][] = [];
+
+      const interiorRingLength = reader.readVarInt();
+
+      for (let k = 0; k < interiorRingLength; k++) {
+        interiorRing.push(parseNextPoint(reader, context, previousPoint));
+      }
+
+      polygon.push(interiorRing);
+    }
+
+    polygons.push(polygon);
+  }
+
+  return {type: 'MultiPolygon', coordinates: polygons};
+}
+
+/** Geometry collection not yet supported */
+function parseGeometryCollection(reader: BinaryReader, context: TWKBHeader): GeometryCollection {
+  return {type: 'GeometryCollection', geometries: []};
+  /**
+  if (context.isEmpty) {
+    return {type: 'GeometryCollection', geometries: []};
+  }
+
+  const geometryCount = reader.readVarInt();
+
+  const geometries: Geometry[] = new Array(geometryCount);
+  for (let i = 0; i < geometryCount; i++) {
+    const geometry = parseGeometry(reader, context, geometryType);
+    geometries.push(geometry);
+  }
+
+  return {type: 'GeometryCollection', geometries: []};
+  */
+}
+
+// HELPERS
+
+/** 
+ * Maps negative values to positive values while going back and
+  forth (0 = 0, -1 = 1, 1 = 2, -2 = 3, 2 = 4, -3 = 5, 3 = 6 ...)
+ */
+function zigZagDecode(value: number): number {
+  return (value >> 1) ^ -(value & 1);
+}
+
+function makePointCoordinates(x: number, y: number, z?: number, m?: number): number[] {
+  return (z !== undefined ? (m !== undefined ? [x, y, z, m] : [x, y, z]) : [x, y]) as number[];
+}
+
+function makePreviousPoint(context: TWKBHeader): number[] {
+  return makePointCoordinates(0, 0, context.hasZ ? 0 : undefined, context.hasM ? 0 : undefined);
+}
+
+function readFirstPoint(reader: BinaryReader, context: TWKBHeader): number[] {
+  const x = zigZagDecode(reader.readVarInt()) / context.precisionFactor;
+  const y = zigZagDecode(reader.readVarInt()) / context.precisionFactor;
+  const z = context.hasZ ? zigZagDecode(reader.readVarInt()) / context.zPrecisionFactor : undefined;
+  const m = context.hasM ? zigZagDecode(reader.readVarInt()) / context.mPrecisionFactor : undefined;
+  return makePointCoordinates(x, y, z, m);
+}
+
+/**
+ * Modifies previousPoint
+ */
+function parseNextPoint(
+  reader: BinaryReader,
+  context: TWKBHeader,
+  previousPoint: number[]
+): number[] {
+  previousPoint[0] += zigZagDecode(reader.readVarInt()) / context.precisionFactor;
+  previousPoint[1] += zigZagDecode(reader.readVarInt()) / context.precisionFactor;
+
+  if (context.hasZ) {
+    previousPoint[2] += zigZagDecode(reader.readVarInt()) / context.zPrecisionFactor;
+  }
+  if (context.hasM) {
+    previousPoint[3] += zigZagDecode(reader.readVarInt()) / context.mPrecisionFactor;
+  }
+
+  // Copy the point
+  return previousPoint.slice();
+}

package/src/lib/parse-wkb-header.ts

@@ -0,0 +1,172 @@
+// loaders.gl, MIT license
+
+const EWKB_FLAG_Z = 0x80000000;
+const EWKB_FLAG_M = 0x40000000;
+const EWKB_FLAG_SRID = 0x20000000;
+
+const MAX_SRID = 10000; // TBD: Assume no more than 10K SRIDs are defined
+
+/**
+ * Integer code for geometry types in WKB and related formats
+ * Reference: 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 variant */
+  type: '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';
+  srid?: number;
+  /** true if binary data is stored as little endian */
+  littleEndian: boolean;
+  /** Offset to start of geometry */
+  byteOffset: number;
+};
+
+/** Sanity checks that first to 5-9 bytes could represent a supported WKB dialect header */
+export function isWKB(arrayBuffer: ArrayBuffer): 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
+export function parseWKBHeader(dataView: DataView, target?: WKBHeader): WKBHeader {
+  const wkbHeader: WKBHeader = Object.assign(target || {}, {
+    type: 'wkb',
+    geometryType: 1,
+    dimensions: 2,
+    coordinates: 'xy',
+    littleEndian: true,
+    byteOffset: 0
+  } as WKBHeader);
+
+  // 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.type = 'iso-wkb';
+      wkbHeader.dimensions = 3;
+      wkbHeader.coordinates = 'xyz';
+      break;
+    case 2:
+      wkbHeader.type = 'iso-wkb';
+      wkbHeader.dimensions = 3;
+      wkbHeader.coordinates = 'xym';
+      break;
+    case 3:
+      wkbHeader.type = '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.type = 'ewkb';
+    wkbHeader.dimensions = 4;
+    wkbHeader.coordinates = 'xyzm';
+  } else if (ewkbZ) {
+    wkbHeader.type = 'ewkb';
+    wkbHeader.dimensions = 3;
+    wkbHeader.coordinates = 'xyz';
+  } else if (ewkbM) {
+    wkbHeader.type = 'ewkb';
+    wkbHeader.dimensions = 3;
+    wkbHeader.coordinates = 'xym';
+  }
+
+  // If SRID present read four more bytes
+  if (ewkbSRID) {
+    wkbHeader.type = 'ewkb';
+    // 4-digit code representing dimension and type of geometry
+    wkbHeader.srid = dataView.getUint32(wkbHeader.byteOffset, wkbHeader.littleEndian);
+    wkbHeader.byteOffset += 4;
+  }
+
+  return wkbHeader;
+}