twkb-parser

This library is used to convert TWKB geometry into GeoJSON geometry

TWKB is a compressed binary format for geographic data. The specification is available on Github.

Installation

This library is available on npmjs:

npm install twkb-parser

Import the library in JavaScript:

import { TWKB } from 'twkb-parser'

CommonJS and IIFE builds are also available. You can download the files from this repository, or import them with a CDN:

• https://cdn.jsdelivr.net/npm/[email protected]/build/twkb-parser.iife.js
• https:/unpkg.com/[email protected]/build/twkb-parser.iife.js

Import the library in HTML:

<script src="https://cdn.jsdelivr.net/npm/[email protected]/build/twkb-parser.iife.js">

Usage

Encoding

To convert a GeoJSON geometry to TWKB bytes:

const geometry = { type: "Polygon", coordinates: [...] };
const bytes = TWKB.fromGeoJSON(geometry).toByteArray();
console.log(bytes); // Uint8Array<[...]>

TWKB encoding requires two input: a geometry and a coordinates precision.

The precision is the number of significant digits on the fractionnal parts of the coordinates. For example, a precision of 4 will convert 9.12345678 to 9.1234. It is used to reduce the size of the output, and it must be chosen based on the precision of the geometry and the projection system of the coordinates.

By default, precision = 6.

To convert a GeoJSON geometry in WGS84 with coordinates precision up to 1 meter, a precision of 5 is adequate:

const geometry = { type: "LineString", coordinates: [...] };
const precision = 5;
const string = TWKB.fromGeoJSON(geometry, precision).toBase64();
console.log(string); // aGVsbG8gdGhlcmU...

There are other optionnal parameters that can be specified when compressing a geometry: the precision for Z coordinates, the inclusion of a bouding box, etc. See section API for more details

Decoding

To convert a TWKB byte array into a GeoJSON geometry:

const bytes = new Uint8Array(...);
const geometry = TWKB.fromArray(bytes).toGeoJSON();
console.log(geometry); // { type: "MultiPoint", coordinates: [...] }

TWKB decoding only require a single input: the TWKB data. All encoding parameters are already included in the TWKB format.

API

A single TWKB interface is exposed in this library. All methods use the same structure: TWKB.fromInput(...).toOutput().

TWKB.fromGeoJSON(geojson: object, precision?: number, parameters?: object)

This method allows the conversion of a GeoJSON geometry.

Arguments

• geojson: a geometry object in GeoJSON format. Only Geometry, MultiGeometry and GeometryCollection are supported, not Feature objects.
• precision (optionnal): a number used to reduce the coordinates precision. Must be in range [-7, 7].
• parameters (optionnal): an object containing additionnal encoding parameters.

The parameters attribute has the following interface:

parameters = {
    precisionZ?: number,
    precisionM?: number,
    includeBbox?: boolean,
    includeSize?: boolean,
    ids?: IdList
  }

• precisionZ: a number used to reduce the Z coordinates precision. Must be in range [0, 7].
• precisionM: a number used to reduce the M coordinates precision. Must be in range [0, 7].
• includeBbox: a boolean to toggle the encoding of the GeoJSON bouding box. The bbox attribute must be defined on the geometry.
• includeSize: a boolean to toggle the encoding of the size of the data. See TWKB specs for details.
• ids: an array of number representing individual geometry ID. Only valid on MultiGeometry / GeometryCollection. See TWKB specs for details.

TWKB.fromGeoJSON(...).toArray(): number[]

Convert the GeoJSON geometry to a TWKB geometry

TWKB.fromGeoJSON(...).toByteArray(): Uint8Array

Convert the GeoJSON geometry to a TWKB geometry

TWKB.fromGeoJSON(...).toBase64(): string

Convert the GeoJSON geometry to a TWKB geometry, encoded as a Base64 string.

TWKB.fromArray(twkb: number[] | Uint8Array)

This method allows the conversion of a TWKB geometry.

Arguments

• twkb: an array of byte (0-255) values representing a TWKB geometry.

TWKB.fromArray(...).toGeoJSON(): GeoJSON

Convert the TWKB geometry to a GeoJSON geometry.

TWKB.fromArray(...).toBase64(): string

Convert the TWKB geometry to the same geometry, encoded as a Base64 string. This is basically just Base64 encoding.

TWKB.fromBase64(twkb: string)

This method allows the conversion of a TWKB geometry.

Arguments

• twkb: a Base64 string representing a TWKB geometry.

TWKB.fromBase64(...).toGeoJSON(): string

Convert the TWKB geometry to a GeoJSON geometry.

TWKB.fromBase64(...).toArray(): number[]

Convert the TWKB geometry to the same geometry. This is basically just Base64 decoding.

TWKB.fromBase64(...).toByteArray(): Uint8Array

Convert the TWKB geometry to the same geometry. This is basically just Base64 decoding.

Alternatives

The wkx library can also be used to convert TWKB geometry, and support more geometry format (WKT, WKB, etc).

There are some downsides to the wkx library:

• The coordinates precision for TWKB compression is fixed at 5.
• The coordinates are truncated and not rounded, which may result in a loss of data after decompression.
• The compression / decompression is 30x to 1000x slower, and it increases exponentially based on the geometry size (see Benchmark section).

The geobuf library implements a format with simlar properties and compression performance. It is based on Google's protocol buffer, and can encode entire Feature object.

Benchmark

System: Pop_OS 22.04 CPU: Intel i7-8665U @1.90Hz RAM: 16 Go Node v20.18.2

conversion of a GeoJSON LineString with 5,000 points
--------------------
JSON               | size: 130.7 KB

TWKB (twkb-parser) | size: 11.2 KB  | compression: 91.4%  | time: 6.9 ms

TWKB (wkx)         | size: 11.2 KB  | compression: 91.4%  | time: 257.7 ms

Geobuf             | size: 17.8 KB  | compression: 86.4%  | time: 9.8 ms

WKB (wkx)          | size: 78.1 KB  | compression: 40.2%  | time: 6.1 ms

WKT (wkx)          | size: 121.0 KB | compression: 7.5%   | time: 5.0 ms


conversion of a GeoJSON LineString with 500,000 points
--------------------
JSON               | size: 12.8 MB

TWKB (twkb-parser) | size: 1.1 MB   | compression: 91.5%  | time: 182.7 ms

TWKB (wkx)         | size: 1.1 MB   | compression: 91.5%  | time: 124970.5 ms (!!)

Geobuf             | size: 1.7 MB   | compression: 86.4%  | time: 115.3 ms

WKB (wkx)          | size: 7.6 MB   | compression: 40.2%  | time: 161.1 ms

WKT (wkx)          | size: 11.8 MB  | compression: 7.5%   | time: 606.8 ms