Meziantou.Framework

WellKnownBinary Class

Namespace
Meziantou.Framework.Geo
Assembly
Meziantou.Framework.Geo.dll
Package
Meziantou.Framework.Geo 1.0.1
Source
WellKnownBinary.cs
Available in package assets
net10.0net11.0

Reads and writes the Well-Known Binary (WKB) representation of a geometry, as defined by the OGC Simple Features and ISO 19125, and the extended WKB of PostGIS (EWKB).

public static class WellKnownBinary

Remarks

The reader accepts both byte orders, for each nested geometry, the ISO type codes of the geometries with an altitude or a measure (1001 for a point with Z, 2001 with M, 3001 with Z and M), and the flags of EWKB (Z, M, and SRID followed by the SRID, which WellKnownBinary.Read returns). It keeps the Z values as GeoPosition.Altitude and the M values as GeoPosition.Measure, a NaN value becoming no altitude or no measure. An empty point, written with NaN coordinates as GEOS and PostGIS do, becomes an empty GeoMultiPoint, as a GeoPoint always has a position, and the empty points of a multipoint are skipped. The other types are rejected, such as a circular string, a triangle or a TIN.

The writer writes ISO WKB in little-endian order. A geometry has a single number of dimensions: when a position of the geometry has an altitude, every position is written with one (type codes 1001 to 1007), and a missing altitude is written as 0. Likewise, when a position has a measure, every position is written with one (type codes 2001 to 2007, or 3001 to 3007 with the altitudes), and a missing measure is written as NaN. The times of the positions are not written, as WKB has no place for them. PostGIS reads this WKB with ST_GeomFromWKB, and its hexadecimal text with a cast to geometry.

Methods

NameDescription
FormatHex(GeoGeometry)Writes the hexadecimal text of the WKB of a geometry, in little-endian order and in uppercase, as PostGIS writes a geometry value.
ParseHex(string)Reads the hexadecimal text of the WKB, or the EWKB, of a geometry, as PostGIS writes a geometry value.
ParseHex(string, int?)Reads the hexadecimal text of the WKB, or the EWKB, of a geometry, as PostGIS writes a geometry value, and the SRID of the EWKB.
Read(ReadOnlySpan<byte>)Reads the WKB, or the EWKB, of a geometry.
Read(ReadOnlySpan<byte>, int?)Reads the WKB, or the EWKB, of a geometry, and the SRID of the EWKB.
Write(GeoGeometry)Writes the WKB of a geometry, in little-endian order.
Write(GeoGeometry, IBufferWriter<byte>)Writes the WKB of a geometry, in little-endian order.

FormatHex(GeoGeometry)

WellKnownBinary.cs

Writes the hexadecimal text of the WKB of a geometry, in little-endian order and in uppercase, as PostGIS writes a geometry value.

public static string FormatHex(GeoGeometry geometry)

Parameters

geometry GeoGeometry
The geometry.

Returns

string The hexadecimal text of the WKB of the geometry.

Exceptions

ArgumentException
A position is not finite.

ParseHex overloads

ParseHex(string)

WellKnownBinary.cs

Reads the hexadecimal text of the WKB, or the EWKB, of a geometry, as PostGIS writes a geometry value.

public static GeoGeometry ParseHex(string hex)
Parameters
hex string
The hexadecimal text, in any case, such as 0101000000000000000000F03F0000000000000040.
Returns

GeoGeometry The geometry.

Exceptions
FormatException
The text is not hexadecimal, or not the WKB of a supported geometry.

ParseHex(string, int?)

WellKnownBinary.cs

Reads the hexadecimal text of the WKB, or the EWKB, of a geometry, as PostGIS writes a geometry value, and the SRID of the EWKB.

public static GeoGeometry ParseHex(string hex, out int? srid)
Parameters
hex string
The hexadecimal text, in any case, such as 0101000020E6100000000000000000F03F0000000000000040.
srid int?
The SRID of the root geometry of the EWKB, or null when it has none.
Returns

GeoGeometry The geometry, with the coordinates of the data: they are not converted.

Exceptions
FormatException
The text is not hexadecimal, or not the WKB of a supported geometry.

Read overloads

Read(ReadOnlySpan<byte>)

WellKnownBinary.cs

Reads the WKB, or the EWKB, of a geometry.

public static GeoGeometry Read(ReadOnlySpan<byte> data)
Parameters
data ReadOnlySpan<byte>
The WKB.
Returns

GeoGeometry The geometry.

Exceptions
FormatException
The data is not the WKB of a supported geometry, is truncated, or has bytes after the geometry.

Read(ReadOnlySpan<byte>, int?)

WellKnownBinary.cs

Reads the WKB, or the EWKB, of a geometry, and the SRID of the EWKB.

public static GeoGeometry Read(ReadOnlySpan<byte> data, out int? srid)
Parameters
data ReadOnlySpan<byte>
The WKB.
srid int?
The SRID of the root geometry of the EWKB, usually an EPSG code that CoordinateReferenceSystem.FromEpsg converts to a coordinate reference system, or null when it has none.
Returns

GeoGeometry The geometry, with the coordinates of the data: they are not converted.

Exceptions
FormatException
The data is not the WKB of a supported geometry, is truncated, or has bytes after the geometry.

Write overloads

Write(GeoGeometry)

WellKnownBinary.cs

Writes the WKB of a geometry, in little-endian order.

public static byte[] Write(GeoGeometry geometry)
Parameters
geometry GeoGeometry
The geometry.
Returns

byte[] The WKB of the geometry.

Exceptions
ArgumentException
A position is not finite.

Write(GeoGeometry, IBufferWriter<byte>)

WellKnownBinary.cs

Writes the WKB of a geometry, in little-endian order.

public static void Write(GeoGeometry geometry, IBufferWriter<byte> writer)
Parameters
geometry GeoGeometry
The geometry.
writer IBufferWriter<byte>
The writer to write the WKB to.
Exceptions
ArgumentException
A position is not finite.