User's Guide and Reference

The OGC well-known binary (WKB) representations

DB2 Spatial Extender has several functions that generate geometries from binary representations:

ST_GeomFromWKB

Creates a geometry from a WKB representation of any geometry type.

ST_PointFromWKB

Creates a point from a point WKB representation.

ST_LineFromWKB

Creates a linestring from a linestring WKB representation.

ST_PolyFromWKB

Creates a polygon from a polygon WKB representation.

ST_MPointFromWKB

Creates a multipoint from a multipoint WKB representation.

ST_MLineFromWKB

Creates a multilinestring from a multilinestring WKB representation.

ST_MPolyFromWKB

Creates a multipolygon from a multipolygon WKB reprsentation.

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 programming language structures to map the binary representation, they are intended for use within a third generation language (3GL) program. They are not suited for a fourth generation language (4GL) environment. The ST_AsBinary function converts an existing geometry value into a well-known binary representation.

The well-known binary representation for geometry is obtained by serializing a geometry instance as a sequence of numeric types. These types are drawn from the set (unsigned integer, double), and then each numeric type is serialized as a sequence of bytes. The types are serialized using one of two well-defined, standard, binary representations for numeric types (NDR, XDR). A one-byte tag that precedes the serialized bytes describes the specific binary encoding (NDR or XDR) used for a geometry byte stream. The only difference between the two encoding of geometry is one of byte order: The XDR encoding is Big Endian; the NDR encoding is Little Endian.

Numeric type definitions

An unsigned integer is a 32 bit (4 byte) data type that encodes a non-negative 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.

These 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 NDR and XDR

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

Description of WKBGeometry byte streams

This section describes the well-known binary representation for geometry. The basic building block is the byte stream for a point, which consists of two doubles. The byte streams for other geometries are built using the byte streams for geometries that are already 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,
};
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;
    WKBMultiPoint            mpoint;
    WKBMultiLineString       mlinestring;
    WKBMultiPolygon          mpolygon;
  }
};
 

The following figure shows an NDR representation.

Figure 39. Representation in NDR format. (B=1) of type polygon (T=3) with 2 linears (NR=2), each ring having 3 points (NP=3).

Assertions for the WKB representation

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 cannot self intersect.

Polygons

No two linear rings in the boundary of a polygon can cross each other. The linear rings in the boundary of a polygon can intersect at most at a single point, but only as a tangent.

Multipolygons

The interiors of two polygons that are elements of a multipolygon cannot intersect. The boundaries of any two polygons that are elements of a multipolygon can touch at only a finite number of points.