Getting started

The well-known binary representation

The well-known binary representation for OGC geometry (WKBGeometry), provides a portable representation of a geometry value as a contiguous stream of bytes. It permits geometry values to be exchanged between an ODBC client and an SQL database in binary form.

Functions are provided in the SQL, JAVA, and C-API to import and export the well-known binary representation of geometry.

The well-known binary representation of geometry defines an encoding for 2D simple feature geometry as defined by the OpenGIS Simple Features Specification for SQL, and ISO 19125. This encoding does not support elevations, measures, CAD, or annotation.

The well-known binary representation is a contiguous stream of bytes. It permits geometry to be exchanged between an ODBC client and an SQL database in binary form. Because these geometry functions require the definition of C structures to map the binary representation, they’re intended for use within a 3GL program and aren’t suited to a 4GL environment.

The well-known binary representation for geometry is obtained by serializing a geometry instance as a sequence of numeric types drawn from the set {Unsigned Integer, Double} and then serializing each numeric type as a sequence of bytes using one of two well-defined, standard binary representations for numeric types (NDR, XDR). The specific binary encoding  used for a geometry byte stream is described by a one-byte tag that precedes the serialized bytes. The only difference between the two encodings of geometry is byte order. The XDR encoding is big-endian, while the NDR encoding is little-endian.

Numeric type definitions

An ‘unsigned integer’ is a 32-bit (4 byte) data type that encodes a nonnegative integer in the range [0, 4294967295].

A ‘double’ is a 64-bit (8 byte) double-precision data type that encodes a double-precision number using the IEEE 754 double-precision format.

The above definitions are common to both XDR and NDR.

XDR (big endian) encoding of numeric types

The XDR representation of an unsigned integer is big-endian (most significant byte first).

The XDR representation of a double is big-endian (sign bit is first byte).

NDR (little endian) encoding of numeric types

The NDR representation of an unsigned integer is little-endian (least significant byte first).

The NDR representation of a double is little-endian (sign bit is last byte).

Conversion between the NDR and XDR representations of WKB geometry

Conversion between the NDR and XDR data types for unsigned integers and doubles is a simple operation involving reversing the order of bytes within each unsigned integer or double in the byte stream.

Description of WKBGeometry byte streams

The well-known binary representation for geometry is described below. The basic building block is the byte stream for a point that consists of two doubles. The byte streams for other geometries are built using the byte streams for geometries that have already been defined.

 

 

// Basic Type definitions

// byte : 1 byte

// uint32 : 32 bit unsigned integer  (4 bytes)

// double : double precision number (8 bytes)

 

// Building Blocks : Point, LinearRing

Point {
double x;
double y;
};

LinearRing   {
uint32 numPoints;
Point  points[numPoints];
}

enum wkbGeometryType {     
wkbPoint = 1,
wkbLineString = 2,
wkbPolygon = 3,
wkbMultiPoint = 4,
wkbMultiLineString = 5,
wkbMultiPolygon = 6,
wkbGeometryCollection = 7
};

enum wkbByteOrder {

   wkbXDR = 0,             // Big Endian

   wkbNDR = 1           // Little Endian

};

 

WKBPoint {
byte             byteOrder;
uint32        wkbType;                // 1
Point            point;
}

WKBLineString {
byte             byteOrder;
uint32        wkbType;                       // 2
uint32        numPoints;
Point            points[numPoints];
}

WKBPolygon {
byte             byteOrder;
uint32        wkbType;                       // 3
uint32        numRings;
LinearRing    rings[numRings];
}

WKBMultiPoint {
byte             byteOrder;
uint32        wkbType;                       // 4
uint32        num_wkbPoints;
WKBPoint         WKBPoints[num_wkbPoints];
}

WKBMultiLineString   {
byte             byteOrder;
uint32        wkbType;                       // 5
uint32        num_wkbLineStrings;
WKBLineString WKBLineStrings[num_wkbLineStrings];
}

wkbMultiPolygon {             
byte             byteOrder;                                            
uint32        wkbType;                       // 6
uint32        num_wkbPolygons;
WKBPolygon    wkbPolygons[num_wkbPolygons];
}

WKBGeometry  {
union {
WKBPoint                   point;
WKBLineString           linestring;
WKBPolygon              polygon;
WKBGeometryCollection   collection;
WKBMultiPoint           mpoint;
WKBMultiLineString      mlinestring;
WKBMultiPolygon         mpolygon;
}
};

 

WKBGeometryCollection {
byte             byte_order;
uint32        wkbType;                       // 7
uint32        num_wkbGeometries;
WKBGeometry      wkbGeometries[num_wkbGeometries]
}

 

 

Well-known binary representation for a geometry object in NDR format (B=1) of type polygon (T=3) with two linears (NR = 2) and each ring having three points (NP = 3).

Assertions for well-known binary representation for geometry

The well-known binary representation for geometry is designed to represent instances of the geometry types described in the geometry object model and in the OpenGIS Abstract Specification.  

These assertions imply the following for rings, polygons, and multipolygons: