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: