@loaders.gl/wkt 4.0.0-alpha.9 → 4.0.0-beta.2

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@loaders.gl/wkt",
   "description": "Loader and Writer for the WKT (Well Known Text) Format",
-  "version": "4.0.0-alpha.9",
+  "version": "4.0.0-beta.2",
   "license": "MIT",
   "publishConfig": {
     "access": "public"
@@ -35,8 +35,8 @@
     "fuzzer": "^0.2.1"
   },
   "dependencies": {
-    "@loaders.gl/loader-utils": "4.0.0-alpha.9",
-    "@loaders.gl/schema": "4.0.0-alpha.9"
+    "@loaders.gl/loader-utils": "4.0.0-beta.2",
+    "@loaders.gl/schema": "4.0.0-beta.2"
   },
-  "gitHead": "03ff81ab468f20f3bddeec787aa88d477a7e1c72"
+  "gitHead": "79c2033f755e88e11bc30a04428e3666b177b8fc"
 }

package/src/hex-wkb-loader.ts

@@ -0,0 +1,61 @@
+// loaders.gl, MIT license
+
+import type {LoaderWithParser} from '@loaders.gl/loader-utils';
+import {BinaryGeometry} from '@loaders.gl/schema';
+
+import type {WKBLoaderOptions} from './wkb-loader';
+import {WKBLoader} from './wkb-loader';
+import {VERSION} from './lib/utils/version';
+import {decodeHex} from './lib/utils/hex-transcoder';
+
+export type HexWKBLoaderOptions = WKBLoaderOptions;
+
+/**
+ * Worker loader for Hex-encoded WKB (Well-Known Binary)
+ */
+export const HexWKBLoader: LoaderWithParser<BinaryGeometry, never, HexWKBLoaderOptions> = {
+  name: 'Hexadecimal WKB',
+  id: 'wkb',
+  module: 'wkt',
+  version: VERSION,
+  worker: true,
+  category: 'geometry',
+  extensions: ['wkb'],
+  mimeTypes: [],
+  options: WKBLoader.options,
+  text: true,
+  testText: isHexWKB,
+  // TODO - encoding here seems wasteful - extend hex transcoder?
+  parse: async (arrayBuffer: ArrayBuffer) => parseHexWKB(new TextDecoder().decode(arrayBuffer)),
+  parseTextSync: parseHexWKB
+};
+
+function parseHexWKB(text: string, options?: HexWKBLoaderOptions): BinaryGeometry {
+  const uint8Array = decodeHex(text);
+  const binaryGeometry = WKBLoader.parseSync?.(uint8Array.buffer, options);
+  // @ts-expect-error
+  return binaryGeometry;
+}
+
+/**
+ * Check if string is a valid Well-known binary (WKB) in HEX format
+ * https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry
+ *
+ * @param str input string
+ * @returns true if string is a valid WKB in HEX format
+ */
+export function isHexWKB(string: string | null): boolean {
+  if (!string) {
+    return false;
+  }
+  // check if the length of the string is even and is at least 10 characters long
+  if (string.length < 10 || string.length % 2 !== 0) {
+    return false;
+  }
+  // check if first two characters are 00 or 01
+  if (!string.startsWith('00') && !string.startsWith('01')) {
+    return false;
+  }
+  // check if the rest of the string is a valid hex
+  return /^[0-9a-fA-F]+$/.test(string.slice(2));
+}

package/src/index.ts

@@ -1,4 +1,25 @@
-export {WKBLoader, WKBWorkerLoader} from './wkb-loader';
+// loaders.gl, MIT license
+
+export {WKTCRSLoader} from './wkt-crs-loader';
+export {WKTCRSWriter} from './wkt-crs-writer';
+
 export {WKTLoader, WKTWorkerLoader} from './wkt-loader';
 export {WKTWriter} from './wkt-writer';
+
+export {WKBLoader, WKBWorkerLoader} from './wkb-loader';
 export {WKBWriter} from './wkb-writer';
+
+export {HexWKBLoader} from './hex-wkb-loader';
+
+export {TWKBLoader} from './twkb-loader';
+export {TWKBWriter} from './twkb-writer';
+
+// EXPERIMENTAL APIs
+export {isWKT} from './lib/parse-wkt';
+
+export {isWKB, parseWKBHeader} from './lib/parse-wkb-header';
+export type {WKBHeader} from './lib/parse-wkb-header';
+
+export {isTWKB} from './lib/parse-twkb';
+
+export {encodeHex, decodeHex} from './lib/utils/hex-transcoder';

package/src/lib/encode-twkb.ts

@@ -0,0 +1,304 @@
+// loaders.gl, MIT license
+// Forked from https://github.com/cschwarz/wkx under MIT license, Copyright (c) 2013 Christian Schwarz
+
+import type {Point, MultiPoint, LineString} from '@loaders.gl/schema';
+import type {
+  MultiLineString,
+  Polygon,
+  MultiPolygon,
+  GeometryCollection,
+  Geometry
+} from '@loaders.gl/schema';
+
+import {BinaryWriter} from './utils/binary-writer';
+import {WKBGeometryType} from './parse-wkb-header';
+
+type TWKBPrecision = {
+  xy: number;
+  z: number;
+  m: number;
+  xyFactor: number;
+  zFactor: number;
+  mFactor: number;
+};
+
+type TWKBEncoderContext = TWKBPrecision & {
+  hasZ?: boolean;
+  hasM?: boolean;
+};
+
+export function encodeTWKB(
+  geometry: Geometry,
+  options?: {hasZ?: boolean; hasM?: boolean}
+): ArrayBuffer {
+  const writer = new BinaryWriter(0, true);
+
+  const context: TWKBEncoderContext = {
+    ...getTwkbPrecision(5, 0, 0),
+    hasZ: options?.hasZ,
+    hasM: options?.hasM
+  };
+
+  encodeGeometry(writer, geometry, context);
+
+  // TODO - we need to slice it?
+  return writer.arrayBuffer;
+}
+
+function encodeGeometry(writer: BinaryWriter, geometry: Geometry, context: TWKBEncoderContext) {
+  switch (geometry.type) {
+    case 'Point':
+      return encodePoint(writer, context, geometry);
+    case 'LineString':
+      return encodeLineString(writer, context, geometry);
+    case 'Polygon':
+      return encodePolygon(writer, context, geometry);
+    case 'MultiPoint':
+      return encodeMultiPoint(writer, context, geometry);
+    case 'MultiLineString':
+      return encodeMultiLineString(writer, context, geometry);
+    case 'MultiPolygon':
+      return encodeMultiPolygon(writer, context, geometry);
+    case 'GeometryCollection':
+      return encodeGeometryCollection(writer, context, geometry);
+    default:
+      throw new Error('unsupported geometry type');
+  }
+}
+
+function encodePoint(writer: BinaryWriter, context: TWKBEncoderContext, point: Point): void {
+  const isEmpty =
+    point.coordinates.length === 0 || point[0] === 'undefined' || point[1] === 'undefined';
+
+  writeTwkbHeader(writer, context, WKBGeometryType.Point, isEmpty);
+
+  if (!isEmpty) {
+    const previousPoint = [0, 0, 0, 0];
+    writeTwkbPoint(writer, context, point.coordinates, previousPoint);
+  }
+}
+
+function encodeLineString(
+  writer: BinaryWriter,
+  context: TWKBEncoderContext,
+  lineString: LineString
+): ArrayBuffer {
+  const points = lineString.coordinates;
+  const isEmpty = points.length === 0;
+
+  writeTwkbHeader(writer, context, WKBGeometryType.LineString, isEmpty);
+
+  if (!isEmpty) {
+    writer.writeVarInt(points.length);
+    const previousPoint = [0, 0, 0, 0];
+    for (const point of points) {
+      writeTwkbPoint(writer, context, point, previousPoint);
+    }
+  }
+
+  return writer.arrayBuffer;
+}
+
+function encodePolygon(
+  writer: BinaryWriter,
+  context: TWKBEncoderContext,
+  polygon: Polygon
+): ArrayBuffer {
+  const polygonRings = polygon.coordinates;
+
+  const isEmpty = polygonRings.length === 0;
+
+  writeTwkbHeader(writer, context, WKBGeometryType.Polygon, isEmpty);
+
+  if (!isEmpty) {
+    writer.writeVarInt(polygonRings.length);
+
+    const previousPoint = [0, 0, 0, 0];
+    for (const ring of polygonRings) {
+      writer.writeVarInt(ring.length);
+      for (const point of ring) {
+        writeTwkbPoint(writer, context, previousPoint, point);
+      }
+    }
+  }
+
+  return writer.arrayBuffer;
+}
+
+function encodeMultiPoint(
+  writer: BinaryWriter,
+  context: TWKBEncoderContext,
+  multiPoint: MultiPoint
+): void {
+  const points = multiPoint.coordinates;
+  const isEmpty = points.length === 0;
+
+  writeTwkbHeader(writer, context, WKBGeometryType.MultiPoint, isEmpty);
+
+  if (!isEmpty) {
+    writer.writeVarInt(points.length);
+
+    const previousPoint = [0, 0, 0, 0];
+    for (let i = 0; i < points.length; i++) {
+      writeTwkbPoint(writer, context, previousPoint, points[i]);
+    }
+  }
+}
+
+function encodeMultiLineString(
+  writer: BinaryWriter,
+  context: TWKBEncoderContext,
+  multiLineStrings: MultiLineString
+): ArrayBuffer {
+  const lineStrings = multiLineStrings.coordinates;
+  const isEmpty = lineStrings.length === 0;
+
+  writeTwkbHeader(writer, context, WKBGeometryType.MultiLineString, isEmpty);
+
+  if (!isEmpty) {
+    writer.writeVarInt(lineStrings.length);
+
+    const previousPoint = [0, 0, 0, 0];
+    for (const lineString of lineStrings) {
+      writer.writeVarInt(lineString.length);
+
+      for (const point of lineString) {
+        writeTwkbPoint(writer, context, previousPoint, point);
+      }
+    }
+  }
+
+  return writer.arrayBuffer;
+}
+
+function encodeMultiPolygon(
+  writer: BinaryWriter,
+  context: TWKBEncoderContext,
+  multiPolygon: MultiPolygon
+): void {
+  const {coordinates} = multiPolygon;
+  const isEmpty = coordinates.length === 0;
+
+  writeTwkbHeader(writer, context, WKBGeometryType.MultiPolygon, isEmpty);
+
+  if (!isEmpty) {
+    const polygons = coordinates;
+    writer.writeVarInt(polygons.length);
+
+    const previousPoint = [0, 0, 0, 0];
+
+    for (const polygonRings of polygons) {
+      writer.writeVarInt(polygonRings.length);
+      for (const ring of polygonRings) {
+        writer.writeVarInt(ring.length);
+        for (const point of ring) {
+          writeTwkbPoint(writer, context, previousPoint, point);
+        }
+      }
+    }
+  }
+}
+
+function encodeGeometryCollection(
+  writer: BinaryWriter,
+  context: TWKBEncoderContext,
+  geometryCollection: GeometryCollection
+): void {
+  const {geometries} = geometryCollection;
+  const isEmpty = geometries.length === 0;
+
+  writeTwkbHeader(writer, context, WKBGeometryType.GeometryCollection, isEmpty);
+
+  if (geometries.length > 0) {
+    writer.writeVarInt(geometries.length);
+    for (const geometry of geometries) {
+      encodeGeometry(writer, geometry, context);
+    }
+  }
+}
+
+/**
+ *
+ * @param writer
+ * @param context
+ * @param geometryType
+ * @param isEmpty
+ */
+function writeTwkbHeader(
+  writer: BinaryWriter,
+  context: TWKBEncoderContext,
+  geometryType: WKBGeometryType,
+  isEmpty: boolean
+) {
+  const type = (zigZagEncode(context.xy) << 4) + geometryType;
+  let metadataHeader = context.hasZ || context.hasM ? 1 << 3 : 0;
+  metadataHeader += isEmpty ? 1 << 4 : 0;
+
+  writer.writeUInt8(type);
+  writer.writeUInt8(metadataHeader);
+
+  if (context.hasZ || context.hasM) {
+    let extendedPrecision = 0;
+    if (context.hasZ) {
+      extendedPrecision |= 0x1;
+    }
+    if (context.hasM) {
+      extendedPrecision |= 0x2;
+    }
+    writer.writeUInt8(extendedPrecision);
+  }
+}
+
+/**
+ * Write one point to array buffer. ZigZagEncoding the delta fdrom the previous point. Mutates previousPoint.
+ * @param writer
+ * @param context
+ * @param previousPoint - Mutated by this function
+ * @param point
+ */
+function writeTwkbPoint(
+  writer: BinaryWriter,
+  context: TWKBEncoderContext,
+  point: number[],
+  previousPoint: number[]
+): void {
+  const x = point[0] * context.xyFactor;
+  const y = point[1] * context.xyFactor;
+  const z = point[2] * context.zFactor;
+  const m = point[3] * context.mFactor;
+
+  writer.writeVarInt(zigZagEncode(x - previousPoint[0]));
+  writer.writeVarInt(zigZagEncode(y - previousPoint[1]));
+  if (context.hasZ) {
+    writer.writeVarInt(zigZagEncode(z - previousPoint[2]));
+  }
+  if (context.hasM) {
+    writer.writeVarInt(zigZagEncode(m - previousPoint[3]));
+  }
+
+  previousPoint[0] = x;
+  previousPoint[1] = y;
+  previousPoint[2] = z;
+  previousPoint[3] = m;
+}
+
+// HELPERS
+
+function zigZagEncode(value: number): number {
+  return (value << 1) ^ (value >> 31);
+}
+
+function getTwkbPrecision(
+  xyPrecision: number,
+  zPrecision: number,
+  mPrecision: number
+): TWKBPrecision {
+  return {
+    xy: xyPrecision,
+    z: zPrecision,
+    m: mPrecision,
+    xyFactor: Math.pow(10, xyPrecision),
+    zFactor: Math.pow(10, zPrecision),
+    mFactor: Math.pow(10, mPrecision)
+  };
+}

package/src/lib/encode-wkb.ts

@@ -14,13 +14,13 @@ import type {
   GeometryCollection
 } from '@loaders.gl/schema';
 
-import BinaryWriter from './utils/binary-writer';
+import {BinaryWriter} from './utils/binary-writer';
 
 /**
  * Integer code for geometry type
  * Reference: https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry#Well-known_binary
  */
-enum WKB {
+export enum WKB {
   Point = 1,
   LineString = 2,
   Polygon = 3,
@@ -33,7 +33,7 @@ enum WKB {
 /**
  * Options for encodeWKB
  */
-interface WKBOptions {
+type WKBOptions = {
   /** Does the GeoJSON input have Z values? */
   hasZ?: boolean;
 
@@ -42,14 +42,14 @@ interface WKBOptions {
 
   /** Spatial reference for input GeoJSON */
   srid?: any;
-}
+};
 
 /**
  * Encodes a GeoJSON object into WKB
  * @param geojson A GeoJSON Feature or Geometry
  * @returns string
  */
-export default function encodeWKB(
+export function encodeWKB(
   geometry: Geometry | Feature,
   options: WKBOptions | {wkb: WKBOptions} = {}
 ): ArrayBuffer {

package/src/lib/encode-wkt-crs.ts

@@ -0,0 +1,39 @@
+// loaders.gl, MIT license
+// parse-wkt-crs was forked from https://github.com/DanielJDufour/wkt-crs under Creative Commons CC0 1.0 license.
+
+import type {WKTCRS} from './parse-wkt-crs';
+
+export type EncodeWKTCRSOptions = {
+  debug?: boolean;
+};
+
+/**
+ * convert JSON representation of Well-Known Text
+ * back to standard Well-Known Text
+ */
+export function encodeWKTCRS(wkt: WKTCRS, options?: EncodeWKTCRSOptions): string {
+  if (Array.isArray(wkt) && wkt.length === 1 && Array.isArray(wkt[0])) {
+    wkt = wkt[0]; // ignore first extra wrapper array
+  }
+
+  const [kw, ...attrs] = wkt;
+  const str = `${kw}[${attrs
+    .map((attr) => {
+      if (Array.isArray(attr)) {
+        return encodeWKTCRS(attr, options);
+      } else if (typeof attr === 'number') {
+        return attr.toString();
+      } else if (typeof attr === 'string') {
+        // can't automatically convert all caps to varibale
+        // because EPSG is string in AUTHORITY["EPSG", ...]
+        if (attr.startsWith('raw:')) {
+          // convert "raw:NORTH" to NORTH
+          return attr.replace('raw:', '');
+        }
+        return `"${attr}"`;
+      }
+      throw new Error(`[wktcrs] unexpected attribute "${attr}"`);
+    })
+    .join(',')}]`;
+  return str;
+}

package/src/lib/encode-wkt.ts

@@ -1,5 +1,6 @@
+// loaders.gl, MIT license
 // Fork of https://github.com/mapbox/wellknown under ISC license (MIT/BSD-2-clause equivalent)
-// eslint-disable-next-line import/no-unresolved
+
 import type {Feature, Geometry} from '@loaders.gl/schema';
 
 /**
@@ -7,7 +8,7 @@ import type {Feature, Geometry} from '@loaders.gl/schema';
  * @param geojson
  * @returns string
  */
-export default function encodeWKT(geometry: Geometry | Feature): string {
+export function encodeWKT(geometry: Geometry | Feature): string {
   if (geometry.type === 'Feature') {
     geometry = geometry.geometry;
   }