WKT Geometry Viewer

Copy a shape out of a spatial database and you usually get a line of text that starts with a word in capitals: POLYGON, then a nest of brackets, then pairs of numbers. It looks too plain to need checking. Yet that one line can describe a field, a hole in the field, a shape that crosses itself, or nothing at all, and the text alone will not tell you which.

Well-Known Text, or WKT, is the human-readable half of a pair. Its binary twin, Well-Known Binary, carries the same geometry as a run of bytes. Both come from the Open Geospatial Consortium’s Simple Feature Access standard, which describes the binary form as a portable way to pass geometry between a client and a database. In practice both turn up wherever spatial data changes hands, down to the cells of a spreadsheet someone emails you on a Friday afternoon.

A small grammar for points, lines and polygons

The standard defines WKT with a short grammar. A point is two numbers, x then y. A line string is a list of points in brackets. A polygon is a list of rings, each ring itself a closed list of points, and the first ring is the outside edge. Multi versions wrap several of each, and a geometry collection can mix them. The keywords are case-insensitive, so Point, point and POINT are the same thing, and the grammar even allows square brackets in place of round ones, as long as each pair matches.

Coordinates can carry more than a position on a flat map. A third number may be a height, tagged Z, or a measure along a route, tagged M, and ZM carries both. The word EMPTY stands for a geometry with no coordinates at all; the standard returns one, for instance, when a search along measures finds no match.

Then there is a dialect. PostGIS, the spatial extension for PostgreSQL, writes Extended WKT, which puts the coordinate system in front: SRID=4326; followed by the geometry. Its manual explains why. The original simple feature formats had no place for the spatial reference identifier, and a number like 4326 is what tells a reader that the coordinates are longitude and latitude on WGS 84 rather than metres on some national grid. EWKT also drops the Z tag when a point has three numbers, so POINT (1 2 3) in PostGIS means the same as POINT Z (1 2 3) in the standard.

The binary form is stricter and smaller. Each geometry opens with one byte that says which way round its numbers are stored: 0 for big endian, 1 for little endian. Four bytes give the type as an integer, from 1 for a point to 7 for a collection, and the standard adds 1000, 2000, 3000 to that code for Z, for M and for both.

After that come counts and eight-byte floating point numbers. The point at x 2, y 4 written big endian is 21 bytes: 00, then 00000001, then 4000000000000000 and 4010000000000000. PostGIS took a different route for its extended binary, setting high bits of the type code to flag Z, M and an embedded SRID. A proposal kept in the PostGIS source tree spells out those flags and sets a convention for empty points: every coordinate is written as a quiet NaN.

So one geometry has at least four spellings in common use, and a tool that reads them has to know all four.

Mixing them up is easy. Ignore the first byte and read that big endian point as little endian, and the type code 1 turns into 16,777,216. A reader that skipped the type check would go on to turn the x value 2 into roughly 3.2e-322.

Why the order of a ring matters

A polygon ring is closed by repeating its first point at the end. That is not a convention a parser can quietly assume. The standard calls a ring a line string that is closed and simple, and the GeoJSON specification is blunt: a linear ring has four or more positions, and the first and last must hold identical values. Four, because a triangle needs three corners plus the repeat. Leave the last point off and the ring breaks the rules of both documents, however obvious the intended shape.

Direction matters too. The standard says the outer ring appears counterclockwise when viewed from the top, and holes run the other way. GeoJSON adopts the same right-hand rule but tells parsers not to reject polygons that break it, because its older version never mentioned winding and plenty of data in the wild winds both ways.

Here is a worked example you can reproduce. Paste the standard’s own example, Polygon ((10 10, 10 20, 20 20, 20 15, 10 10)), into the viewer. The area comes out as 75 square units, and the ring is reported as clockwise. Walk it by hand: up the left side from (10, 10) to (10, 20), across the top to (20, 20), down to (20, 15), then back along the slope. That is clockwise. Both polygons in the standard’s MultiPolygon example run the same way. The example table in the document that defines counterclockwise outer rings does not follow its own advice, which tells you how loosely the rule is applied in practice.

Why care, then? Because the standard ties the upward face of a surface to that direction, and because the shoelace sum that gives a polygon its area returns a signed number. Counterclockwise is positive. A tool that trusts the sign without taking its absolute value will report a negative field, or subtract a hole twice.

Valid shapes and the ones that only look valid

The standard lists what makes a polygon valid. Rings may not cross. They may touch each other only at single points. There may be no cut lines, spikes or punctures, and the inside must be one connected piece. For a multipolygon, the members may not overlap, and their edges may meet at finitely many points but not run along each other.

Every one of those rules is broken by data people actually make. The classic is the bow-tie, POLYGON ((0 0, 10 10, 10 0, 0 10, 0 0)), where the ring crosses itself in the middle. Its shoelace area is zero, because the two triangles wind in opposite directions and cancel.

Ask what its real area is and there is no good answer, and the standard simply forbids the shape.

Holes cause the quieter failures. A hole drawn slightly outside its outer ring, two holes that overlap, a hole inside another hole, or a hole that touches the boundary at two points and cuts the polygon in half: each one parses perfectly and draws plausibly, and each one breaks a rule the standard sets for polygons.

Finding these needs geometry, not grammar. The viewer compares every pair of edges whose bounding boxes overlap, after sorting the edges from left to right, which keeps ordinary shapes fast; the worst case still grows with the square of the edge count, so the check stops at a stated cap and says when it has. It uses ordinary double-precision arithmetic, so two edges that miss each other by a rounding error can be misjudged. That limit is real, and the page says so.

Flat area, round Earth, and the trip to GeoJSON

A WKT polygon has no idea what its numbers mean. If they are metres on a projected grid, the shoelace formula gives square metres and you are done. If they are longitude and latitude, the same formula gives square degrees, a unit that changes size with latitude. PostGIS makes this explicit. For its geometry type, area is a flat Cartesian figure in the units of the spatial reference. For its geography type, area is measured on the spheroid in square metres, and since version 2.2 that measurement uses GeographicLib.

The difference is not subtle. A square one degree on each side, sitting on the equator, covers 12,308.8 square km on the WGS 84 ellipsoid. Move the same square to between 60 and 61 degrees north and it shrinks to about 6,122.9 square km, half as much. In square degrees, both are exactly 1.

Measuring on the ellipsoid properly means treating each edge as a geodesic, the shortest path over the curved surface, and adding up the area between each edge and the equator. Charles Karney’s 2013 paper in the Journal of Geodesy gives a method accurate to round-off and reports errors in the area term of about 0.1 square metres. A polygon around a pole needs half the ellipsoid’s area added, a detail that catches out simpler formulas. GeographicLib’s documentation gives a test case anyone can repeat: a rough outline of Antarctica with a perimeter of 16,831,067.893 m and an area of 13,662,703,680,020.1 square metres. The viewer reproduces both figures to the stated decimals.

There is a catch in the other direction. GeoJSON, the JSON format for geometry, says a line between two positions is a straight line in longitude and latitude, and notes that it may differ markedly from the geodesic. For short edges the gap is negligible. For an edge across an ocean, the two readings describe different shapes, and so give different areas.

Converting to GeoJSON brings its own rules. Coordinates must be WGS 84 longitude and latitude, longitude first. A position may carry a height but should not carry more, so M values have nowhere to go. A shape that crosses the 180th meridian should be cut in two, because a ring that jumps from 179 to minus 179 degrees reads as one that wraps almost all the way round the world. The specification also notes that six decimal places of a degree come to about 10 centimetres, and that piling on digits mostly inflates the file.

None of this makes Well-Known Text a bad format. It is compact, readable and exact, which is why it has lasted. It simply leaves the meaning to the reader: which way the numbers are stored, what units they are in, whether the rings are closed and ordered, whether the shape is valid at all. Read it with that in mind and a single line of text becomes something you can check, measure and pass on without surprises.