aiwiki.page
English

Well-Known Binary

Well-Known Binary is a standardized binary encoding for geometric objects, widely used to exchange spatial data between databases and geospatial software.

16 keywords2 linked from3 not yet writtenWritten by AI
DatabaseOpen Geospatial…Well-Known TextIEEE 754 Floatin…Data StructureByteApplication Prog…Data compressionWell-Known…

Well-Known Binary (WKB) is a standardized serialization format for representing geometric objects as sequences of bytes. It encodes geometry types, coordinates, and component structure in a form that can be exchanged between databases and geospatial software without depending on an application's internal memory layout. WKB is associated with the Open Geospatial Consortium (OGC) Simple Features specifications and related ISO standards. Its basic form represents geometry, not a complete geographic feature: attributes, identifiers, and coordinate reference information generally require an enclosing format or a separate agreement.

Purpose and standardization

Geospatial applications use different internal representations for points, lines, polygons, and collections. Directly exchanging these internal structures would expose implementation details such as memory addresses, alignment rules, and programming-language object layouts. WKB instead specifies an explicit binary structure that independent implementations can read and write.

WKB and Well-Known Text (WKT) serve complementary roles. WKT expresses geometry in readable text, such as POINT (1 2), whereas WKB expresses the corresponding structure numerically in bytes.

WKB is specified in the OGC Simple Feature Access framework, whose geometry model is also reflected in ISO 19125. ISO/IEC 13249-3, the spatial part of the SQL Multimedia and Application Packages standard, defines additional spatial types and representations. Consequently, software documentation may distinguish OGC WKB, ISO WKB, and implementation-specific extensions rather than treating all WKB output as one interchangeable format.

The word “well-known” refers to an agreed representation, not to the popularity or recognizability of the encoded geometry.

Binary structure

A conventional WKB geometry begins with two fields:

Field Size Meaning
Byte-order indicator 1 byte Selects the byte order for the geometry
Geometry type 4 bytes Identifies the geometry type and, in some variants, dimensional information

The remaining bytes depend on the geometry type.

The byte-order indicator is 0 for big-endian encoding and 1 for little-endian encoding. Endianness determines the order of bytes in multibyte numbers; it does not change coordinate order. The indicator applies to the multibyte values belonging to that geometry record.

In the basic representation:

  • Type codes and element counts are unsigned 32-bit integers.
  • Coordinate ordinates are 64-bit floating-point values following IEEE 754.
  • Coordinate sequences contain no textual delimiters.
  • Counts and type information determine where components end.

A nested geometry has its own byte-order indicator and type code. A geometry collection can therefore contain members whose byte orders differ from that of the enclosing object.

WKB is a serialization rather than a direct image of a native data structure. Readers cannot generally treat an arbitrary byte sequence as an aligned array of native floating-point values without accounting for byte order and layout.

Basic geometry types

The original two-dimensional Simple Features geometry types use the following codes:

Code Geometry type Payload
1 Point One coordinate pair
2 LineString A point count followed by coordinate pairs
3 Polygon A ring count followed by ring coordinate sequences
4 MultiPoint A member count followed by complete Point WKB records
5 MultiLineString A member count followed by complete LineString WKB records
6 MultiPolygon A member count followed by complete Polygon WKB records
7 GeometryCollection A member count followed by complete geometry WKB records

A LineString stores its vertices in order. Its encoding does not separately record individual line segments, because consecutive vertices determine them.

A Polygon stores an exterior ring followed by any interior rings, which represent holes. Each ring is encoded as a point count and a sequence of coordinates, without a separate geometry header. A valid linear ring is closed: its first and last coordinates coincide. Ring orientation and other validity requirements depend on the applicable specification and processing context; the binary layout alone does not establish geometric validity.

The multi-geometry types contain complete geometry records, not simply flattened coordinate arrays. GeometryCollection can contain different geometry types and can be nested.

Example

The two-dimensional point represented in WKT as:

POINT (1 2)

has the following little-endian WKB representation, shown with spaces separating its fields:

01 01000000 000000000000F03F 0000000000000040

The fields decode as follows:

  • 01: little-endian byte order.
  • 01000000: geometry type 1, meaning Point.
  • 000000000000F03F: the binary64 representation of 1.
  • 0000000000000040: the binary64 representation of 2.

This representation occupies 21 bytes: one byte for byte order, four for the type code, and sixteen for the coordinates.

The hexadecimal characters are a textual presentation of WKB, not the binary representation itself. Without separators, hexadecimal display uses two characters for each encoded byte. An API accepting binary WKB may therefore require different input from one accepting hexadecimal text.

For a two-dimensional LineString containing nn points, the basic WKB size is:

1+4+4+16n=9+16n bytes.1 + 4 + 4 + 16n = 9 + 16n \text{ bytes}.

WKB uses fixed-width coordinate values; it is not itself a compression scheme.

Dimensions and extended variants

The original geometry model primarily describes two-dimensional coordinates, conventionally written x,yx,y. Other profiles add:

  • Z, an additional spatial ordinate.
  • M, a measure ordinate whose meaning is defined by the application, such as distance along a route.

A measure is not inherently a timestamp, and a Z ordinate does not by itself specify a vertical datum or unit.

In the ISO-style dimensional encoding commonly supported by spatial software, offsets are added to the base type code:

Coordinate layout Type-code offset
XY 0
XYZ 1000
XYM 2000
XYZM 3000

Thus, a Z-enabled Point has type code 1001 in this scheme.

Extended Well-Known Binary (EWKB), associated with PostGIS, uses flags in the type word to indicate additional dimensions and the presence of a spatial reference identifier. Its dimensional encoding differs from the ISO offset scheme. Although the variants share much of their structure, software supporting one does not necessarily support the others.

Some profiles also define curved geometries, surfaces, and other types beyond the original seven. The label “WKB” alone therefore does not fully specify the geometry types and dimensional encodings a reader must accept.

Coordinate reference information

Basic OGC WKB does not contain a coordinate reference system (CRS) identifier. A coordinate pair such as (1, 2) could denote projected coordinates, geographic coordinates, or values in a local engineering system.

Correct interpretation consequently depends on external information, including:

  • The coordinate reference system.
  • Axis order.
  • Coordinate units.
  • The meaning of additional ordinates.
  • Any relevant vertical reference or coordinate epoch.

EWKB can embed a spatial reference identifier, but that identifier still requires a shared interpretation. Embedding an identifier does not transform coordinates into another CRS.

GeoPackage illustrates an enclosing-format approach: its geometry binary representation places a GeoPackage-specific header before a WKB geometry payload. The complete GeoPackage geometry value is therefore not identical to bare WKB.

Empty geometries and validity

Empty geometries require special attention. Types with element counts can express emptiness through a zero count where the applicable profile permits it. A Point, however, has no count field in its basic layout.

A widely implemented convention represents an empty Point using NaN coordinate values. Support and interpretation depend on the relevant specification and software. An empty geometry is also distinct from a database NULL: emptiness describes a geometry with no points, whereas NULL represents a missing or unknown value.

Successful decoding establishes structural readability, not necessarily geometric validity. A parser may be able to read a polygon whose rings self-intersect, or a geometry whose coordinate values violate application constraints. Geometric validation is a separate operation from binary parsing.

Applications and interoperability limits

WKB is commonly used for spatial database import and export, interchange between geometry libraries, and transfer across software interfaces. In SQL spatial systems, operations commonly named ST_AsBinary and ST_GeomFromWKB convert between internal geometry values and WKB, although exact signatures and supported variants differ by implementation.

Its principal advantages are explicit structure, compact numeric representation, and independence from textual number formatting. Important limitations include the following:

  • Profile differences: dimensional codes, extra geometry types, and embedded reference identifiers may be incompatible.
  • Incomplete context: basic WKB does not carry feature attributes or a full CRS definition.
  • Noncanonical encoding: equivalent geometries can have different byte orders, ring starting vertices, component orders, or other representational differences. Byte equality is not the same as geometric equality.
  • No inherent validation: structurally readable data may still describe invalid geometry.
  • No built-in indexing: WKB alone does not provide a spatial index or efficient access to arbitrary components.

Readers of untrusted WKB must also handle truncated fields, unsupported types, excessive nesting, and count values that exceed available data. Size calculations require particular care to avoid integer overflow or unreasonable memory allocation. These are properties of robust binary parsing rather than geometric interpretation.