GEOS / Geometry Formats / Well-Known Text (WKT) Edit this page

Well-Known Text (WKT)

“Well-known text” is a scheme for writing a simple features geometry into a standard text string.

Examples

  • POINT(0 0)
  • POINT EMPTY
  • LINESTRING(0 0, 0 1, 1 2)
  • LINESTRING EMPTY
  • POLYGON((0 0, 1 0, 1 1, 0 1, 0 0))
  • POLYGON((0 0, 4 0, 4 4, 0 4, 0 0), (1 1, 1 2, 2 2, 2 1, 1 1))
  • POLYGON EMPTY
  • MULTIPOINT(0 0, 1 1)
  • GEOMETRYCOLLECTION(MULTIPOINT(0 0, 1 1), POINT(3 4), LINESTRING(2 3, 3 4))

WKT BNF

<x> ::= <number>
<y> ::= <number>
<z> ::= <number>
<m> ::= <number>
<empty set> ::= EMPTY
<zm> ::= ZM | Z | M
<comma> ::= ,
<left paren> ::= (
<right paren> ::= )

<point> ::= <x> <y> [ <z> ] [ <m> ]

<point text> ::=
    <empty set> |
    <left paren> <point> <right paren>

<linestring text> ::=
    <empty set> |
    <left paren> <point> {<comma> <point>} ... <right paren>

<polygon text> ::=
    <empty set> |
    <left paren> <linestring text> {<comma> <linestring text>} ... <right paren>

<multipoint text> ::=
    <empty set> |
    <left paren> <point> {<comma> <point>} ... <right paren>

<multilinestring text> ::=
    <empty set> |
    <left paren> <linestring text> {<comma> <linestring text>} ... <right paren>

<multipolygon text> ::=
    <empty set> |
    <left paren> <polygon text> {<comma> <polygon text>} ... <right paren>

<geometrycollection text> ::=
    <empty set> |
    <left paren> <wkt representation> {<comma> <wkt representation>} ... <right paren>

<point text representation> ::=
    POINT [ <zm> ] <point text>

<linestring text representation> ::=
    LINESTRING [ <zm> ] <linestring text body>

<polygon text representation> ::=
    POLYGON [ <zm> ] <polygon text body>

<multipoint text representation> ::=
    MULTIPOINT [ <zm> ] <multipoint text>

<multilinestring text representation> ::=
    MULTILINESTRING [ <zm> ] <multilinestring text>

<multipolygon text representation> ::=
    MULTIPOLYGON [ <zm> ] <multipolygon text>

<geometrycollection text representation> ::=
    GEOMETRYCOLLECTION [ <zm> ] <geometrycollection text>

<wkt representation> ::=
    <point text representation> |
    <linestring text representation> |
    <polygon text representation> |
    <collection text representation> |
    <multipoint text representation> |
    <multilinestring text representation> |
    <multipolygon text representation> |
    <geometrycollection text representation>

Writing WKT

Because WKT is a decimal text output, it will never be able to exactly represent the underlying machine representation of the coordinates. In general, WKT is used for display to humans, or for transport when exact coordinate representation is not required (some web applications).

Accordingly, the GEOS well-known text writer allows you to customize the coordinate precision and rounding behaviour, as well as the dimensionality of outputs.

/* Read a linestring */
const char* linestring = "LINESTRING(0 0 1, 1 1 1, 2 1 2)";
GEOSWKTReader* reader = GEOSWKTReader_create();
GEOSGeom* geom = GEOSWKTReader_read(reader, linestring);

/* Get a WKT  writer*/
GEOSWKTWriter* writer = GEOSWKTWriter_create();

/* Preserve the Z dimension. */
GEOSWKTWriter_setOutputDimension(writer, 3);

/* Sets the number places after the decimal to output in WKT. Default 16. */
GEOSWKTWriter_setRoundingPrecision(writer, 4);

/*
 * Sets the number trimming option on a \ref GEOSWKTWriter.
 * With trim set to 1, the writer will strip trailing 0's from
 * the output coordinates. With 0, all coordinates will be
 * padded with 0's out to the rounding precision.
 */
GEOSWKTWriter_setTrim(writer, 1);

/* Generate the WKT , and store the output length */
unsigned char* wkt = GEOSWKTWriter_write(writer, geom);

/* do something ... */

/* Free the WKB */
GEOSFree(wkt);
GEOSGeom_destroy(geom);
GEOSWKTWriter_destroy(writer);
GEOSWKTReader_destroy(reader);