WKB: read ISO and EWKB, write ISO, through the factory
SpatialNET.IO gets WKB (Wkb next to Wkt and GeoJson), because hosts with a database (PostGIS, SQL Server, GeoPackage blobs) exchange geometries in this format, and gView already has a reader. It follows the pattern of ADR 0009: reading creates all geometries through the geometry factory, there is no feature model, and a CRS is not evaluated. Reading accepts ISO WKB and EWKB (the PostGIS flavour with flags), writing produces ISO WKB in little endian. Z and M are supported (ADR 0015). This lifts the exclusion of WKB from ADR 0009; the rest of that ADR stands.
German version: 0016-wkb-iso-schreiben-ewkb-lesen-ueber-factory.de.md
Consequences
- Placement:
SpatialNET.IO, namespaceSpatialNET.IO. No new package, no new dependency (System.Buffers.Binaryis part of the framework).SpatialNET.Corestays contracts only. For the package validation this is an addition only. - API (the same shape as
Wkt, ADR 0009):Wkb.Read(ReadOnlySpan<byte>, IGeometryFactory? factory = null)returnsIGeometry2D,Wkb.Read<T>(…)expects a kind,Wkb.ReadAll(…)returnsIReadOnlyList<IGeometry2D>.ToWkb(this IGeometry2D, WkbOptions? options = null)returnsbyte[].WkbOptionshasZModeandMModewith the same meaning as inWktOptions.- No stream, hex or text overloads. A caller that has a
Streamor a hex string converts it first; this keeps the surface small and can be extended without a break.
- Reading:
- Formats: ISO WKB (type codes 1–6 plus 1000/2000/3000 for Z/M/ZM) and EWKB (flag bits
0x80000000Z,0x40000000M,0x20000000SRID). Both byte orders. The byte order is read per geometry header, so nested parts of a multi geometry may differ. - Mixed codes are accepted: ISO dimension codes together with the SRID flag, as NTS writes them.
- Types: Point, LineString, Polygon, MultiPoint, MultiLineString and MultiPolygon map as for WKT (ADR 0009): a point to
IPoint2D, a point with NaN coordinates (the WKB form ofPOINT EMPTY) and a MultiPoint toIMultiPoint2D, line strings toIPolyline2D, polygons toIPolygon2D. - GeometryCollection is rejected by
ReadwithNotSupportedExceptionand flattened byReadAll, exactly as in WKT and GeoJSON. There is no geometry collection in the model (ADR 0002). - Curves (CircularString, CompoundCurve, CurvePolygon, MultiCurve, MultiSurface), other surfaces, TIN and triangles throw
NotSupportedException. The hosts linearise curves themselves (map #1), and the type code is named in the message. - SRID in an EWKB header is read and discarded, the same line as for the CRS in GeoJSON.
- Z and M are kept if the factory supports them (ADR 0015), otherwise dropped. A coordinate that is
NaNin a Z or M slot means "none". - Invalid input never crashes: truncated data, an unknown byte order or type, and trailing bytes after the geometry throw
FormatExceptionwith the byte offset. A count (points, rings, parts) that cannot fit into the remaining bytes is rejected before anything is allocated, so a forged header cannot cause an out-of-memory error. Geometrically invalid but syntactically correct input is passed to the factory unchanged, as for WKT.
- Formats: ISO WKB (type codes 1–6 plus 1000/2000/3000 for Z/M/ZM) and EWKB (flag bits
- Writing:
- ISO WKB, little endian, leanest type as for WKT: a polygon of one part is a Polygon, several parts a MultiPolygon, one path a LineString, several a MultiLineString, a multipoint stays a MultiPoint. A single point is a Point; an empty multipoint is a MultiPoint with zero points, so the writer never has to emit the NaN point.
- Rings are closed, shells counter-clockwise, holes clockwise, degenerate rings dropped (the same normalisation as the WKT writer, so both agree on the structure of the result).
- Z follows
ZMode(Autowrites Z only if some point has a height other than 0, because hosts such as gView always deliverZ = 0), M followsMMode(written if some point has M; points without M get NaN). - Non-finite X or Y throws
ArgumentException, as in the GeoJSON writer, because most consumers cannot read them back, and a NaN pair would collide with the marker of the empty point. - No SRID is written. A caller that needs EWKB or a GeoPackage header builds it around the ISO bytes.
- Origin of the code: gView's reader (
gView.Framework.OGC, same owner, Apache-2.0) is the starting point for the format handling, but the code is rewritten againstCoordinateand the factory, so that no gView type enters the library. Its curve and SRID handling is replaced by the rules above. No entry inTHIRD-PARTY-NOTICES.mdis needed, because it is the same copyright holder. - Tests (ADR 0008): fixtures do not apply, because the result is bytes and not a geometry from an algorithm.
- Oracle: the NTS
WKBReaderandWKBWriter, in both directions. What we write, NTS reads to the same coordinates, and what NTS writes (including EWKB with SRID, big endian, Z and M), we read. Z and M are compared through the ordinates NTS reports. - Property tests (CsCheck): round trip
ToWkb→Readover random geometries with Z, M and empty parts, for the reference implementation and the foreign implementation; WKB agrees with WKT on the normalised structure. - Hand-written cases: both byte orders, nested byte orders, EWKB flags with and without SRID, the NaN point, every rejected type, truncated and forged input (counts, offsets), M of zero is a measure.
- The
Coversrule of ADR 0008 is met by namingWkb.Read,Wkb.ReadAllandToWkbin these tests.
- Oracle: the NTS
- Playground: unchanged; WKB is not an input format there.
Considered Options
- Keep WKB out and let hosts use their own readers (rejected: every host with a database needs one, and gView's already exists; the IO package is the place for formats, ADR 0009)
- Write EWKB (rejected: ISO is the standard and PostGIS reads it; EWKB with SRID would reintroduce a CRS that IO deliberately does not carry)
- Read ISO only (rejected: PostGIS
ST_AsEWKBand many libraries still produce EWKB) - Keep the SRID (rejected: it needs a place in the model; the
crsof GeoJSON is dropped for the same reason) - Convert curves to line strings on reading (rejected for now: needs a tolerance parameter and its own decision; hosts linearise already)
- Stream, hex and
byte[]-only overloads on day one (rejected: a larger surface for conveniences that a caller adds in one line; can be added later without a break) - Take the gView code unchanged (rejected: it creates gView types and has no factory)
- A separate package
SpatialNET.IO.Wkb(rejected: no dependency justifies it; ADR 0014 argued the same for the index)