Well-known text
Well-known text (WKT) is a text markup language for representing vector geometry objects on a map, spatial reference systems of spatial objects and transformations between spatial reference systems. A binary equivalent, known as well-known binary (WKB), is used to transfer and store the same information on databases, such as PostGIS, Microsoft SQL Server and DB2. The formats were originally defined by the Open Geospatial Consortium (OGC) and described in their Simple Feature Access and Coordinate Transformation Service specifications. The current standard definition is in the ISO/IEC 13249-3:2011 standard, "Information technology -- Database languages -- SQL multimedia and application packages -- Part 3: Spatial" (SQL/MM).
Geometric objects
WKT can represent 18 distinct geometric objects:
- Geometry
- Point, MultiPoint
- LineString, MultiLineString
- Polygon, MultiPolygon, Triangle
- CircularString
- Curve, MultiCurve, CompoundCurve
- CurvePolygon
- Surface, MultiSurface, PolyhedralSurface
- TIN
- GeometryCollection
Coordinates for geometries may be 2D (x, y), 3D (x, y, z), 4D (x, y, z, m) with an m value that is part of a linear referencing system or 2D with an m value (x, y, m). Three-dimensional geometries are designated by a "Z" after the geometry type and geometries with a linear referencing system have an "M" after the geometry type. Empty geometries which contain no coordinates can be specified by using the symbol EMPTY
after the type name.
WKT geometries are used throughout OGC specifications and are present in applications that implement these specifications. For example, PostGIS contains functions that can convert geometries to and from a WKT representation, making them human readable.
It's useful to note that the OGC standard definition requires a polygon to be topologically closed. It also states that if the exterior linear ring of a polygon is defined in a counter clockwise direction it will be seen from the "top". Any interior linear rings should be defined in opposite fashion compared to the exterior ring, in this case, clockwise.[1]
Type | Examples | |
---|---|---|
Point | POINT (30 10) | |
LineString | LINESTRING (30 10, 10 30, 40 40) | |
Polygon | POLYGON ((30 10, 40 40, 20 40, 10 20, 30 10)) | |
POLYGON ((35 10, 45 45, 15 40, 10 20, 35 10), |
Type | Examples | |
---|---|---|
MultiPoint | MULTIPOINT ((10 40), (40 30), (20 20), (30 10)) | |
MULTIPOINT (10 40, 40 30, 20 20, 30 10) | ||
MultiLineString | MULTILINESTRING ((10 10, 20 20, 10 40), | |
MultiPolygon | MULTIPOLYGON (((30 20, 45 40, 10 40, 30 20)), | |
MULTIPOLYGON (((40 40, 20 45, 45 30, 40 40)), |
The following are some other examples of geometric WKT strings: (Note: Each item below is an individual geometry.)
GEOMETRYCOLLECTION(POINT(4 6),LINESTRING(4 6,7 10)) POINT ZM (1 1 5 60) POINT M (1 1 80) POINT EMPTY MULTIPOLYGON EMPTY CIRCULARSTRING(1 5, 6 2, 7 3) COMPOUNDCURVE(CIRCULARSTRING(0 0,1 1,1 0),(1 0,0 1)) CURVEPOLYGON(CIRCULARSTRING(-2 0,-1 -1,0 0,1 -1,2 0,0 2,-2 0),(-1 0,0 0.5,1 0,0 1,-1 0)) MULTICURVE((5 5,3 5,3 3,0 3),CIRCULARSTRING(0 0,2 1,2 2)) TRIANGLE((0 0 0,0 1 0,1 1 0,0 0 0)) TIN (((0 0 0, 0 0 1, 0 1 0, 0 0 0)), ((0 0 0, 0 1 0, 1 1 0, 0 0 0))) POLYHEDRALSURFACE Z ( ((0 0 0, 0 1 0, 1 1 0, 1 0 0, 0 0 0)), ((0 0 0, 0 1 0, 0 1 1, 0 0 1, 0 0 0)), ((0 0 0, 1 0 0, 1 0 1, 0 0 1, 0 0 0)), ((1 1 1, 1 0 1, 0 0 1, 0 1 1, 1 1 1)), ((1 1 1, 1 0 1, 1 0 0, 1 1 0, 1 1 1)), ((1 1 1, 1 1 0, 0 1 0, 0 1 1, 1 1 1)) )
Well-known binary
Well-known binary (WKB) representations are typically shown in hexadecimal strings.
The first byte indicates the byte order for the data:
-
00
: big endian -
01
: little endian
The second part is an integer for the geometry type, as described below:
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 |
Each data type has a unique data structure, such as the number of points or linear rings, followed by coordinates in double-precision floating-point format (double).
For example, the geometry POINT(2.0 4.0)
is represented as: 000000000140000000000000004010000000000000
, where:
- 1-byte integer
00
or 0: big endian - 4-byte integer
00000001
or 1: POINT (2D) - 8-byte float
4000000000000000
or 2.0: x-coordinate - 8-byte float
4010000000000000
or 4.0: y-coordinate
Transformations
A WKT format is defined to describe the transformation methods and parameters used to convert coordinates between two different spatial reference systems.
Below are two examples of WKT transformation descriptions.
-
PARAM_MT["Mercator_2SP",
-
PARAMETER["semi_major",6370997.0],
-
PARAMETER["semi_minor",6370997.0],
-
PARAMETER["central_meridian",180.0],
-
PARAMETER["false_easting",-500000.0],
-
PARAMETER["false_northing",-1000000.0],
-
PARAMETER["standard parallel 1",60.0]]
-
PARAM_MT["Affine",
-
PARAMETER["num_row",3],
-
PARAMETER["num_col",3],
-
PARAMETER["elt_0_1",1],
-
PARAMETER["elt_0_2",2],
-
PARAMETER["elt 1 2",3]]
RDBMS Engines that provide support
- Apache Solr enterprise search server since 4.0[2] through JTS
- PostgreSQL with PostGIS Module 2.0
- Oracle Spatial 9i, 10g, 11g
- MarkLogic Server since 4.2[3]
- MySQL since 4.1[4]
- MariaDB, all versions
- IBM DB2 LUW 9, 10 with Spatial Extender
- IBM DB2 for z/OS 9, 10 with Spatial Support
- IBM Netezza with Netezza Spatial
- IBM Informix 9,10,11 with Spatial datablade module
- Microsoft SQL Server 2008, 2008 R2, 2012, 2014
- SpatiaLite
- Teradata 6.1, 6.2, 12, 13 (native in 13 through add-in in previous versions)
- Ingres GeoSpatial
- Altibase 5.x
- SQL Anywhere 12
- SAP HANA SP07,SP08
- H2 since 1.3.173 (2013-07-28)[5]
APIs that provide support
- JTS Topology Suite (Java)
- NetTopologySuite (.NET)
- OpenLayers (JavaScript)
- OpenScales (ActionScript)
- GDAL (C/C++ with bindings to Java, Python, and others)
- Shapely (Python): See Shapely Documentation and Shapely in PyPI
- GeoPHP (PHP)
- Boost C++ libraries (C++): See Geometry io/wkt headers
- pygeoif (Python) parses wkt with regular expressions
- parsewkt (Python) is a peg parser from WKT to python dictionaries
- GEOS (C/C++)
- WkbDecoder (C# .Net) WKB Parser
Protocols that provide support
Atlas/Mapping software that provides support
- Nunaliit participatory atlas creation and data management framework
Variations
- EWKT and EWKB – Extended Well-Known Text/Binary – A PostGIS-specific format that includes the spatial reference system identifier (SRID) and up to 4 ordinate values.[6][7] For example:
SRID=4326;POINT(-44.3 60.1)
to locate a longitude/latitude coordinate using the WGS 84 reference coordinate system. - AGF Text – Autodesk Geometry Format – An extension to OGC's Standard (at the time), to include curved elements; most notably used in MapGuide.[8]
See also
References
- ↑ See the OGC Implementation Specification for geographic information - Simple Feature Access, section 6.1.11.1. http://www.opengeospatial.org/standards/sfa
- ↑ Solr GEO support
- ↑ https://docs.marklogic.com/guide/search-dev/geospatial
- ↑ Well-Known Text (WKT) Format, MySQL documentation
- ↑ H2 create spatial index documentation
- ↑ https://github.com/postgis/postgis/blob/2.1.0/doc/ZMSgeoms.txt
- ↑ http://postgis.org/docs/ST_GeomFromEWKT.html
- ↑ http://www.osgeo.org/files/mapguide/docs/2.0/da/dc0/group___agf_text.htm