4.1. GIS

4.2. SRID

4.3. WKB

4.4. ZM-Geometry

5.1.  Identifiers

The normative provisions in this standard are denoted by the URI

http://www.opengis.net/spec/ewkb/1.0

All requirements and conformance tests that appear in this document are denoted by partial URIs which are relative to this base.

6.1.  Introduction

The original WKB specification made no allowances for adding extra dimensions, like Z and M, that are common in GIS applications. It also had no space for embedding a spatial reference identifier (SRID), which made it unusable as a database import/export format.

The “Extended WKB” variant is a superset of the standard WKB, which allows applications to optionally add extra dimensions, and optionally embed an SRID.

The presence of extra dimensions shall be indicated by adding flag bits to the existing wkbType that appears in all WKB geometries.

6.2.  Extensions to Well Known Binary format

The 2d OpenGIS Simple Features specification has the following geometry types:

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

Listing 1 — OpenGIS Geometry Types

Z values in Simple Features co-ordinates (99-402r2) introduces a Z-presence flag (wkbZ) which shall be logically ORed with the type to specify the presence of a Z coordinate:

	wkbZ = 0x80000000

Listing 2 — Z Flag

Extended Well Known Binary shall use an M-presence flag (wkbM) to allow for XY, XYM, XYZ and XYZM geometries, and a SRID-presence flag to allow for embedded SRID:

	wkbM = 0x40000000
	wkbSRID = 0x20000000

Listing 3 — M Flag

Possible resulting geometry types are:

enum wkbGeometryTypeZ {

	wkbPoint = 1,
	wkbLineString = 2,
	wkbPolygon = 3,
	wkbMultiPoint = 4,
	wkbMultiLineString = 5,
	wkbMultiPolygon = 6,
	wkbGeometryCollection = 7,

	// | 0x80000000
	wkbPointZ = 0x80000001,
	wkbLineStringZ = 0x80000002,
	wkbPolygonZ = 0x80000003,
	wkbMultiPointZ = 0x80000004,
	wkbMultiLineStringZ = 0x80000005,
	wkbMultiPolygonZ = 0x80000006,
	wkbGeometryCollectionZ = 0x80000007,

	// | 0x40000000
	wkbPointM = 0x40000001,
	wkbLineStringM = 0x40000002,
	wkbPolygonM = 0x40000003,
	wkbMultiPointM = 0x40000004,
	wkbMultiLineStringM = 0x40000005,
	wkbMultiPolygonM = 0x40000006,
	wkbGeometryCollectionM = 0x40000007,

	// | 0x40000000 | 0x80000000
	wkbPointZM = 0xC0000001,
	wkbLineStringZM = 0xC0000002,
	wkbPolygonZM = 0xC0000003,
	wkbMultiPointZM = 0xC0000004,
	wkbMultiLineStringZM = 0xC0000005,
	wkbMultiPolygonZM = 0xC0000006,
	wkbGeometryCollectionZM = 0xC0000007,

	// | 0x20000000
	wkbPointS = 0x20000001,
	wkbLineStringS = 0x20000002,
	wkbPolygonS = 0x20000003,
	wkbMultiPointS = 0x20000004,
	wkbMultiLineStringS = 0x20000005,
	wkbMultiPolygonS = 0x20000006,
	wkbGeometryCollectionS = 0x20000007,

	// | 0x20000000 | 0x80000000
	wkbPointZS = 0xA0000001,
	wkbLineStringZS = 0xA0000002,
	wkbPolygonZS = 0xA0000003,
	wkbMultiPointZS = 0xA0000004,
	wkbMultiLineStringZS = 0xA0000005,
	wkbMultiPolygonZS = 0xA0000006,
	wkbGeometryCollectionZS = 0xA0000007,

	// | 0x20000000 | 0x40000000
	wkbPointMS = 0x60000001,
	wkbLineStringMS = 0x60000002,
	wkbPolygonMS = 0x60000003,
	wkbMultiPointMS = 0x60000004,
	wkbMultiLineStringMS = 0x60000005,
	wkbMultiPolygonMS = 0x60000006,
	wkbGeometryCollectionMS = 0x60000007,

	// | 0x20000000 | 0x40000000 | 0x80000000
	wkbPointZMS = 0xE0000001,
	wkbLineStringZMS = 0xE0000002,
	wkbPolygonZMS = 0xE0000003,
	wkbMultiPointZMS = 0xE0000004,
	wkbMultiLineStringZMS = 0xE0000005,
	wkbMultiPolygonZMS = 0xE0000006,
	wkbGeometryCollectionZMS = 0xE0000007,
}

Listing 4 — ZM Geometries

If the SRID flag is set, its value shall be encoded as a 4-byte integer right after the type integer.

If only wkbZ or wkbM flags are set, Point coordinates shall be XYZ or XYM respectively.

If both wkbZ and wkbM flags are set, Point coordinates shall be XYZM (Z first).

6.3.  Empty Geometry Handling

For geometries with a counter (nPoints for LineString, nRings for Polygon, nPoints for MultiPoint, nLines for MultiLineString, nPolygons for MultiPolygon, nGeometries for GeometryCollection), an Empty geometry can be represented by setting the counter to zero.

For an empty Point, which does not have a counter, an empty geometry is signalled by setting all coordinates to an IEEE-754 quiet NaN value (big endian 0×7ff8000000000000 or little endian 0x000000000000f87f depending on the endian value of the WKB).

6.4.  Illustrative Examples

Here is the structure and flagging for a 3D point — the dimensionaly flag indicates a Z dimension, and the point member therefore has three coordinates.

wkbZ = 0x80000000
wkbM = 0x40000000
wkbSRID = 0x20000000

enum wkbGeometryTypeZ {

    wkbPoint = 1,
    wkbLineString = 2,
    wkbPolygon = 3,
    wkbMultiPoint = 4,
    wkbMultiLineString = 5,
    wkbMultiPolygon = 6,
    wkbGeometryCollection = 7,

    // | 0x80000000
    wkbPointZ = 0x80000001,
    wkbLineStringZ = 0x80000002,
    wkbPolygonZ = 0x80000003,
    wkbMultiPointZ = 0x80000004,
    wkbMultiLineStringZ = 0x80000005,
    wkbMultiPolygonZ = 0x80000006,
    wkbGeometryCollectionZ = 0x80000007,
}

WKBPointZ {
    byte   byteOrder; // wkbXDR or wkbNDR
    uint32 wkbType;   // wkbPointZ = (wkbPoint | wkbZ) = 0x80000001
    Point {
        Double x;
        Double y;
        Double z;
    }
}

Listing 5 — 3D Point

When the optional wkbSRID is added to the wkbType, an SRID number is inserted after the wkbType number.

WKBPointS {
    byte   byteOrder; // wkbXDR or wkbNDR
    uint32 wkbType;   // wkbPointS = (wkbPoint | wkbSRID) = 0x20000001
    uint32 SRID;
    Point {
        Double x;
        Double y;
    }
}

Listing 6 — Point With SRID

The dimensionality and SRID flags may also be combined. Here is a 3D point with an embedded SRID.

WKBPointS {
    byte   byteOrder; // wkbXDR or wkbNDR
    uint32 wkbType;   // wkbPointS = (wkbPoint | wbkZ | wkbSRID) = 0xA0000001
    uint32 SRID;
    Point {
        Double x;
        Double y;
        Double z;
    }
}

Listing 7 — 3D Point With SRID

The following example demonstrates a ZM-Point geometry at the location (10,20) with:

WKBPoint {

	byte    byteOrder;      // wkbXDR or wkbNDR

	uint32  wkbType;        // (wkbPoint+wkbZ+wkbM+wkbSRID) =
			        // 0xE0000001

	uint32  SRID;           // 4326

	Point {
		Double    x;    // 10.0
		Double    y;    // 20.0
		Double    z;    // 30.0
		Double    m;    // 40.0
	}
}

Listing 8 — ZM Point With SRID

6.5.  Writing Extended WKB

/* Read a linestring */
const char* linestring = "LINESTRING(0 0 1, 1 1 1, 2 1 2)";
GEOSWKBReader* reader = GEOSWKBReader_create();
GEOSGeom* geom = GEOSWKTReader_read(reader, linestring);
GEOSSetSRID(geom, 4326);

/* Write it out as Extended WKB */
GEOSWKBWriter* writer = GEOSWKBWriter_create();
/* Next line only needed before GEOS 3.12 */
GEOSWKBWriter_setOutputDimension(writer, 3);
GEOSWKBWriter_setFlavor(writer, GEOS_WKB_EXTENDED);
GEOSWKBWriter_setIncludeSRID(writer, 1);

/* Generate the WKB , and store the output length */
size_t wkb_size;
unsigned char* wkb = GEOSWKBWriter_write(writer, geom, &wkb_size);

/* do something ... */

/* Free the WKB */
GEOSFree(wkb);
GEOSGeom_destroy(geom);

Listing 9 — Writing EWKB