feat(wkt): Add TWKB parser

visgl · Sep 18, 2023 · 73bf97f · 73bf97f
1 parent c7797f9
commit 73bf97f
Show file tree

Hide file tree

Showing 20 changed files with 1,174 additions and 650 deletions.
diff --git a/docs/modules/shapefile/formats/shapefile.md b/docs/modules/shapefile/formats/shapefile.md
@@ -1,7 +1,7 @@
 
 # Shapefile
 
-- *[`@loaders.gl/shapefile`](/docs/modules/shapefile/formats/shapefile)*
+- *[`@loaders.gl/shapefile`](/docs/modules/shapefile)*
 - *https://www.clicketyclick.dk/databases/xbase/format/data_types.html*
 - *http://www.dbase.com/Knowledgebase/INT/db7_file_fmt.htm*
 - *http://webhelp.esri.com/arcgisdesktop/9.3/index.cfm?TopicName=Geoprocessing_considerations_for_shapefile_output*

diff --git a/docs/modules/wkt/formats/twkb.md b/docs/modules/wkt/formats/twkb.md
@@ -0,0 +1,21 @@
+# TWKB
+
+- *[`@loaders.gl/wkt`](/docs/modules/wkt)*
+- *[TWKB specification](https://github.com/TWKB/Specification/blob/master/twkb.md)*
+
+TWKB is a format for serializing vector geometry data into a binary byte buffer, similar to [WKB](./wkb) but with an emphasis on minimizing size of the buffer.
+
+## Memory Layout
+
+WKB uses IEEE doubles as the coordinate storage format, so for data with lots of spatially adjacent coordinates (typical for GIS data) it wastes precision, i.e. space on redundant coordinate information:
+
+- TWKB only stores the absolute position once, and stores all other positions as delta values relative to the preceding position.
+- TWKB Only use as much address space as is necessary for any given value. Practically this means that "variable length integers" or "varints" are used throughout the specification for storing values in any situation where numbers greater than 128 might be encountered.
+
+## Ecosystem Support
+
+- PostGIS offers a function to return geometries in TWKB format: [ST_AsTWKB](https://postgis.net/docs/ST_AsTWKB.html).
+
+## Versions / History
+
+Unknown.
diff --git a/docs/modules/wkt/formats/wkb.md b/docs/modules/wkt/formats/wkb.md
@@ -2,7 +2,9 @@
 
 ![ogc-logo](../../../images/logos/ogc-logo-60.png)
 
-Well-known binary
+- *[`@loaders.gl/wkt`](/docs/modules/wkt)*
+
+Well-Known Binary (WKB) is a binary version of Well-known Text
 
 ## Overview
 
@@ -20,14 +22,22 @@ Well-known binary (WKB) representations are typically shown in hexadecimal strin
 - GML Geometry 
 
 
-| Format | Support | Description                                        |
-| ------ | ------- | -------------------------------------------------- |
-| EWKT   | ❌       | WKT that starts with a spatial reference id (SRID) |
-| TWKB   | ❌       | WKB variant reduces binary size ~2x.               |
+| Format | Support | Description                          |
+| ------ | ------- | ------------------------------------ |
+| WKB    | ❌       |                                      |
+| TWKB   | ❌       | WKB variant reduces binary size ~2x. |
 
 TWKB uses varints, precision truncation and zigzag point encoding to reduce binary size ~2x (however compressed size reduction is less)
 
-## Encoding
+## Version History
+
+TBA.
+
+## Ecosystem Support
+
+- PostGIS offers a function to return geometries in TWKB format: [ST_AsTWKB](https://postgis.net/docs/ST_AsTWKB.html).
+
+## Format Details
 
 The first byte indicates the byte order for the data:
 
@@ -36,36 +46,38 @@ The first byte indicates the byte order for the data:
 
 The next 4 bytes are a 32-bit unsigned integer for the geometry type, as described below:
 
-*Note that some implementations, including loaders.gl, only handle the core GeoJSON geometry equivalents (points, line strings, polygons and to a varying degrees geometry collections of the same).*
-
-| Type               | 2D   | Z    | M    | ZM   |
-| ------------------ | ---- | ---- | ---- | ---- |
-| Geometry           | 0000 | 1000 | 2000 | 3000 |
-| Point              | 0001 | 1001 | 2001 | 3001 |
-| LineString         | 0002 | 1002 | 2002 | 3002 |
-| Polygon            | 0003 | 1003 | 2003 | 3003 |
-| MultiPoint         | 0004 | 1004 | 2004 | 3004 |
-| MultiLineString    | 0005 | 1005 | 2005 | 3005 |
-| MultiPolygon       | 0006 | 1006 | 2006 | 3006 |
-| GeometryCollection | 0007 | 1007 | 2007 | 3007 |
-|                    |
-| CircularString     | 0008 | 1008 | 2008 | 3008 |
-| CompoundCurve      | 0009 | 1009 | 2009 | 3009 |
-| CurvePolygon       | 0010 | 1010 | 2010 | 3010 |
-| MultiCurve         | 0011 | 1011 | 2011 | 3011 |
-| MultiSurface       | 0012 | 1012 | 2012 | 3012 |
-| Curve              | 0013 | 1013 | 2013 | 3013 |
-| Surface            | 0014 | 1014 | 2014 | 3014 |
-| PolyhedralSurface  | 0015 | 1015 | 2015 | 3015 |
-| TIN                | 0016 | 1016 | 2016 | 3016 |
-| Triangle           | 0017 | 1017 | 2017 | 3017 |
-| Circle             | 0018 | 1018 | 2018 | 3018 |
-| GeodesicString     | 0019 | 1019 | 2019 | 3019 |
-| EllipticalCurve    | 0020 | 1020 | 2020 | 3020 |
-| NurbsCurve         | 0021 | 1021 | 2021 | 3021 |
-| Clothoid           | 0022 | 1022 | 2022 | 3022 |
-| SpiralCurve        | 0023 | 1023 | 2023 | 3023 |
-| CompoundSurface    | 0024 | 1024 | 2024 | 3024 |
-| BrepSolid          |      | 1025 |      | |
-| AffinePlacement    | 102  | 1102 |      | |
+| Type                 | Supported | 2D   | Z    | M    | ZM   |
+| -------------------- | --------- | ---- | ---- | ---- |
+| `Geometry`           | ✅         | 0000 | 1000 | 2000 | 3000 |
+| `Point`              | ✅         | 0001 | 1001 | 2001 | 3001 |
+| `LineString`         | ✅         | 0002 | 1002 | 2002 | 3002 |
+| `Polygon`            | ✅         | 0003 | 1003 | 2003 | 3003 |
+| `MultiPoint`         | ✅         | 0004 | 1004 | 2004 | 3004 |
+| `MultiLineString`    | ✅         | 0005 | 1005 | 2005 | 3005 |
+| `MultiPolygon`       | ✅         | 0006 | 1006 | 2006 | 3006 |
+| `GeometryCollection` | ✅ \*      | 0007 | 1007 | 2007 | 3007 |
+|                      |           |      |      |      |      |
+| `CircularString`     | ❌         | 0008 | 1008 | 2008 | 3008 |
+| `CompoundCurve`      | ❌         | 0009 | 1009 | 2009 | 3009 |
+| `CurvePolygon`       | ❌         | 0010 | 1010 | 2010 | 3010 |
+| `MultiCurve`         | ❌         | 0011 | 1011 | 2011 | 3011 |
+| `MultiSurface`       | ❌         | 0012 | 1012 | 2012 | 3012 |
+| `Curve`              | ❌         | 0013 | 1013 | 2013 | 3013 |
+| `Surface`            | ❌         | 0014 | 1014 | 2014 | 3014 |
+| `PolyhedralSurface`  | ❌         | 0015 | 1015 | 2015 | 3015 |
+| `TIN`                | ❌         | 0016 | 1016 | 2016 | 3016 |
+| `Triangle`           | ❌         | 0017 | 1017 | 2017 | 3017 |
+| `Circle`             | ❌         | 0018 | 1018 | 2018 | 3018 |
+| `GeodesicString`     | ❌         | 0019 | 1019 | 2019 | 3019 |
+| `EllipticalCurve`    | ❌         | 0020 | 1020 | 2020 | 3020 |
+| `NurbsCurve`         | ❌         | 0021 | 1021 | 2021 | 3021 |
+| `Clothoid`           | ❌         | 0022 | 1022 | 2022 | 3022 |
+| `SpiralCurve`        | ❌         | 0023 | 1023 | 2023 | 3023 |
+| `CompoundSurface`    | ❌         | 0024 | 1024 | 2024 | 3024 |
+| `BrepSolid`          | ❌         |      | 1025 |      |      |
+| `AffinePlacement`    | ❌         | 102  | 1102 |      |      |
+
+Remarks:
+- *Many implementations, including loaders.gl, only handle the core GeoJSON geometry equivalents (points, line strings, polygons and to a varying degrees geometry collections of the same).*
+- *`GeometryCollection`* can be difficult for some clients to handle.
 
diff --git a/docs/modules/wkt/formats/wkt-crs.md b/docs/modules/wkt/formats/wkt-crs.md
@@ -2,16 +2,20 @@
 
 ![ogc-logo](../../../images/logos/ogc-logo-60.png)
 
-- OGC Standard: https://www.ogc.org/standards/wkt-crs
-- Wikipedia Page: https://en.wikipedia.org/wiki/Well-known_text_representation_of_coordinate_reference_systems
+- *[`@loaders.gl/wkt`](/docs/modules/wkt)*
+- *[OGC Standard](https://www.ogc.org/standards/wkt-crs)*
+- *[Wikipedia Page](https://en.wikipedia.org/wiki/Well-known_text_representation_of_coordinate_reference_systems)*
 
 Well-known text representation of coordinate reference systems (WKT or WKT-CRS) is a text markup language for representing spatial reference systems and transformations between spatial reference systems. The formats were originally defined by the Open Geospatial Consortium (OGC) and described in their Simple Feature Access and Well-known text representation of coordinate reference systems specifications. The current standard definition is ISO 19162:2019.
 
-# Version History
+## Version History
+
+| Name                  | Year   | Description                                                  | ISO              |
+| --------------------- | ------ | ------------------------------------------------------------ | ---------------- |
+| WKT                   | (1999  | As initially defined by the Open Geospatial Consortium (OGC) |
+| "WKT 1"               | (2001  | WKT was extended in 2001. Sometimes known as "WKT 1".        | ISO 19125-1:2004 |
+| "WKT 2" / "WKT-CRS 1" | (2015) | Addresses new requirements and inconsistencies in WKT 1.     | ISO 19162:2015   |
+| "WKT-CRS 2"           | (2018) | A newer revision.                                            | ISO 19162:2019   |
+
+## Ecosystem Support
 
-- WKT (1999) - As initially defined by the Open Geospatial Consortium (OGC) 
-- "WKT 1" (2001) - WKT was extended in 2001, to ISO 19125-1:2004, sometimes known as "WKT 1".
-- "WKT 2" / "WKT-CRS 1" (2015) - The updated "Well-known text representation of coordinate reference systems" standard, adopted by Open Geospatial Consortium / ISO 19162:2015. 
-  - Addresses new requirements and inconsistencies in implementation of WKT 1 format.
-  - Confusingly, this standard has a version number 1 for the new, stricter WKT-CRS specification. 
-- "WKT-CRS 2" (2018) - A newer revision called was published in 2018: ISO 19162:2019.
diff --git a/docs/modules/wkt/formats/wkt.md b/docs/modules/wkt/formats/wkt.md
@@ -40,20 +40,24 @@ Well-known text (WKT) for geometry is a text markup language for representing ve
 | GeoJSON Geometry | JSON based, human-readable, slightly more verbose, easier to parse  |
 | GML Geometry     | XML based, human-readable, even more verbose, more complex to parse |
 
+## Ecosystem Support
+
+- PostGIS and some other databases offer functions to return geometries in WKT format: [WKT](https://postgis.net/docs/ST_AsText.html), [ST_AsEWKT](https://postgis.net/docs/ST_AsEWKT.html).
+
 ## Geometries
 
 WKT can represent a range of distinct geometric objects.
 
 *Note that some implementations, including loaders.gl, only handle the core GeoJSON geometry equivalents (points, line strings, polygons and to a varying degrees geometry collections of the same).*
 
-| Geometry                             |
-| ------------------------------------ |
-| Point, MultiPoint                    |
-| LineString, MultiLineString          |
-| Polygon, MultiPolygon                |
-| GeometryCollection                   |
-|                                      |
-| Triangle                             |
-| PolyhedralSurface                    |
-| TIN (Triangulated irregular network) |
+| Geometry                               |
+| -------------------------------------- |
+| `Point`, `MultiPoint`                  |
+| `LineString`, `MultiLineString`        |
+| `Polygon`, `MultiPolygon`              |
+| `GeometryCollection`                   |
+|                                        |
+| `Triangle`                             |
+| `PolyhedralSurface`                    |
+| `TIN` (Triangulated irregular network) |
 
diff --git a/modules/wkt/src/index.ts b/modules/wkt/src/index.ts
@@ -3,6 +3,9 @@
 export {WKBLoader, WKBWorkerLoader} from './wkb-loader';
 export {WKBWriter} from './wkb-writer';
 
+export {TWKBLoader} from './twkb-loader';
+export {TWKBWriter} from './twkb-writer';
+
 export {HexWKBLoader} from './hex-wkb-loader';
 
 export {WKTLoader, WKTWorkerLoader} from './wkt-loader';