Getting started |

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.

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.

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).

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 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.

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).

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:

**Linear rings—**Rings are simple and closed, which means that linear rings may not self intersect.**Polygons—**No two linear rings in the boundary of a polygon may cross each other. The linear rings in the boundary of a polygon may intersect, at most, at a single point but only as a tangent.**Multipolygons—**The interiors of two polygons that are elements of a multipolygon may not intersect. The boundaries of any two polygons that are elements of a multipolygon may touch at only a finite number of points.