WKB: ISO und EWKB lesen, ISO schreiben, über die Factory
SpatialNET.IO bekommt WKB (Wkb neben Wkt und GeoJson), weil Hosts mit Datenbank (PostGIS, SQL Server, GeoPackage-Blobs) Geometrien in diesem Format austauschen und gView bereits einen Reader hat. Es folgt dem Muster aus ADR 0009: Beim Lesen entstehen alle Geometrien über die Geometrie-Factory, es gibt kein Feature-Modell, und ein KBS wird nicht ausgewertet. Das Lesen akzeptiert ISO-WKB und EWKB (die PostGIS-Variante mit Flags), das Schreiben erzeugt ISO-WKB in Little Endian. Z und M werden unterstützt (ADR 0015). Das hebt den Ausschluss von WKB aus ADR 0009 auf; der Rest dieses ADR gilt weiter.
English version: 0016-wkb-iso-schreiben-ewkb-lesen-ueber-factory.md
Consequences
- Ort:
SpatialNET.IO, NamespaceSpatialNET.IO. Kein neues Paket, keine neue Abhängigkeit (System.Buffers.Binarygehört zum Framework).SpatialNET.Corebleibt reine Verträge. Für die Package Validation ist das nur eine Ergänzung. - API (dieselbe Form wie
Wkt, ADR 0009):Wkb.Read(ReadOnlySpan<byte>, IGeometryFactory? factory = null)liefertIGeometry2D,Wkb.Read<T>(…)erwartet eine Art,Wkb.ReadAll(…)liefertIReadOnlyList<IGeometry2D>.ToWkb(this IGeometry2D, WkbOptions? options = null)liefertbyte[].WkbOptionshatZModeundMModemit derselben Bedeutung wie inWktOptions.- Keine Stream-, Hex- oder Text-Überladungen. Wer einen
Streamoder Hex-String hat, wandelt ihn vorher um; das hält die Oberfläche klein und lässt sich ohne Bruch erweitern.
- Lesen:
- Formate: ISO-WKB (Typcodes 1–6 sowie 1000/2000/3000 für Z/M/ZM) und EWKB (Flag-Bits
0x80000000Z,0x40000000M,0x20000000SRID). Beide Byte-Reihenfolgen. Sie wird je Geometrie-Header gelesen, auch verschachtelte Teile einer Multi-Geometrie dürfen verschieden sein. - Gemischte Codes werden akzeptiert: ISO-Dimensionscodes zusammen mit dem SRID-Flag, wie NTS sie schreibt.
- Typen: Point, LineString, Polygon, MultiPoint, MultiLineString und MultiPolygon werden wie bei WKT abgebildet (ADR 0009): Punkt auf
IPoint2D, ein Punkt mit NaN-Koordinaten (die WKB-Form vonPOINT EMPTY) und MultiPoint aufIMultiPoint2D, Linien aufIPolyline2D, Flächen aufIPolygon2D. - GeometryCollection wird von
ReadmitNotSupportedExceptionabgelehnt und vonReadAllflachgeklopft, genau wie bei WKT und GeoJSON. Eine Geometry-Collection gibt es im Modell nicht (ADR 0002). - Kurven (CircularString, CompoundCurve, CurvePolygon, MultiCurve, MultiSurface), andere Flächenarten, TIN und Dreiecke werfen
NotSupportedException. Die Hosts linearisieren Kurven selbst (Karte #1), und der Typcode steht in der Meldung. - SRID in einem EWKB-Header wird gelesen und verworfen, dieselbe Linie wie beim KBS in GeoJSON.
- Z und M bleiben erhalten, wenn die Factory sie unterstützt (ADR 0015), sonst werden sie verworfen. Eine Koordinate, die in einem Z- oder M-Slot
NaNist, heißt „keins“. - Ungültige Eingabe stürzt nie ab: abgeschnittene Daten, eine unbekannte Byte-Reihenfolge oder ein unbekannter Typ und überzählige Bytes hinter der Geometrie werfen
FormatExceptionmit dem Byte-Offset. Eine Anzahl (Punkte, Ringe, Teile), die nicht in die restlichen Bytes passt, wird abgelehnt, bevor etwas angelegt wird; ein gefälschter Header kann so keinen Speicherfehler auslösen. Geometrisch ungültige, aber syntaktisch korrekte Eingabe geht unverändert an die Factory, wie bei WKT.
- Formate: ISO-WKB (Typcodes 1–6 sowie 1000/2000/3000 für Z/M/ZM) und EWKB (Flag-Bits
- Schreiben:
- ISO-WKB, Little Endian, schlankster Typ wie bei WKT: ein Polygon aus einer Teilfläche ist ein Polygon, mehrere Teilflächen ein MultiPolygon, ein Pfad ein LineString, mehrere ein MultiLineString, ein Multipoint bleibt MultiPoint. Ein einzelner Punkt ist ein Point; ein leerer Multipoint ist ein MultiPoint mit null Punkten, der Writer muss den NaN-Punkt also nie erzeugen.
- Ringe sind geschlossen, Außenringe gegen den Uhrzeigersinn, Löcher im Uhrzeigersinn, entartete Ringe entfallen (dieselbe Normalisierung wie beim WKT-Writer, damit beide die Struktur des Ergebnisses gleich festlegen).
- Z folgt
ZMode(Autoschreibt Z nur, wenn ein Punkt eine Höhe ungleich 0 hat, weil Hosts wie gView immerZ = 0liefern), M folgtMMode(geschrieben, wenn ein Punkt M hat; Punkte ohne M bekommen NaN). - Nicht endliches X oder Y wirft
ArgumentException, wie im GeoJSON-Writer, weil die meisten Abnehmer es nicht zurücklesen können und ein NaN-Paar mit dem Marker des leeren Punkts kollidieren würde. - Es wird keine SRID geschrieben. Wer EWKB oder einen GeoPackage-Header braucht, baut ihn um die ISO-Bytes.
- Herkunft des Codes: Der gView-Reader (
gView.Framework.OGC, gleicher Inhaber, Apache-2.0) ist der Ausgangspunkt für die Formatbehandlung, der Code wird aber gegenCoordinateund die Factory neu geschrieben, damit kein gView-Typ in die Bibliothek gelangt. Seine Kurven- und SRID-Behandlung wird durch die Regeln oben ersetzt. Ein Eintrag inTHIRD-PARTY-NOTICES.mdist nicht nötig, weil es derselbe Rechteinhaber ist. - Tests (ADR 0008): Fixtures passen nicht, weil das Ergebnis Bytes sind und keine Geometrie aus einem Algorithmus.
- Orakel: NTS
WKBReaderundWKBWriter, in beide Richtungen. Was wir schreiben, liest NTS zu denselben Koordinaten, und was NTS schreibt (auch EWKB mit SRID, Big Endian, Z und M), lesen wir. Z und M werden über die Ordinaten verglichen, die NTS meldet. - Property-Tests (CsCheck): Round-Trip
ToWkb→Readüber zufällige Geometrien mit Z, M und leeren Teilen, für die Referenz-Implementierung und die Fremd-Implementierung; WKB stimmt mit WKT in der normalisierten Struktur überein. - Handgeschriebene Fälle: beide Byte-Reihenfolgen, verschachtelte Byte-Reihenfolgen, EWKB-Flags mit und ohne SRID, der NaN-Punkt, jeder abgelehnte Typ, abgeschnittene und gefälschte Eingabe (Anzahlen, Offsets), M gleich 0 ist ein Messwert.
- Die
Covers-Regel aus ADR 0008 ist erfüllt, indem diese TestsWkb.Read,Wkb.ReadAllundToWkbnennen.
- Orakel: NTS
- Playground: unverändert; WKB ist dort kein Eingabeformat.
Considered Options
- WKB draußen lassen, Hosts nutzen eigene Reader (verworfen: jeder Host mit Datenbank braucht einen, und der von gView existiert; das IO-Paket ist der Ort für Formate, ADR 0009)
- EWKB schreiben (verworfen: ISO ist der Standard, und PostGIS liest ihn; EWKB mit SRID würde ein KBS einführen, das IO bewusst nicht trägt)
- Nur ISO lesen (verworfen: PostGIS
ST_AsEWKBund viele Bibliotheken erzeugen weiter EWKB) - Die SRID behalten (verworfen: braucht einen Platz im Modell; das
crsaus GeoJSON wird aus demselben Grund verworfen) - Kurven beim Lesen in Linien umwandeln (verworfen für jetzt: braucht einen Toleranzparameter und eine eigene Entscheidung; die Hosts linearisieren bereits)
- Stream-, Hex- und nur-
byte[]-Überladungen von Anfang an (verworfen: größere Oberfläche für Bequemlichkeit, die ein Aufrufer in einer Zeile ergänzt; lässt sich später ohne Bruch hinzufügen) - Den gView-Code unverändert übernehmen (verworfen: er erzeugt gView-Typen und kennt keine Factory)
- Ein eigenes Paket
SpatialNET.IO.Wkb(verworfen: keine Abhängigkeit rechtfertigt es; ADR 0014 hat dasselbe für den Index begründet)