geodetic 0.5.2 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 44b5221a45f63382e712aa88d033d1cb0b8165f8804833a1fd8523a9d7d8ce32
-  data.tar.gz: 787dc88782b277262e15dde4fa1f61801894d1d34eff304dc63965147a3b10e8
+  metadata.gz: 7e34b06e1bf493a580a70871173cab9e79b442c1667a1d68e9b9b2cd6181b660
+  data.tar.gz: 3d7cdabbff9c142ae61812dfec12d92cf764cc85cf31458c41226d4f00cc19a2
 SHA512:
-  metadata.gz: ffb91f043c3c0c9a2bb6b44fad7952936121a09b18879350398cf260fd2be1f594f33c405df7cea0027f59c0e06679f1d4f718192d7626032a4b5fab195626f9
-  data.tar.gz: dd922521aa23db80a5d9fdf56dbb98dcdfab811f72a126978d9b8dffe248f72f3dd83c3cae1e41d3ee2a1cf11455d70120d6c81fff7523f3aac798397250fbca
+  metadata.gz: a8c06b5625fcbb2df864e913ec687f0075c971ff91910a295bfe112ab645bca2174b7d01e32cb9ef03aa9cad05311cfdee7c00572f629d9c4a5b26af70604d3e
+  data.tar.gz: 3a9e274d50a491b2b1b1791402e4e5ff5c52f2be2cf172162fadc8d246ef64cf8bc410bb7eb869b1c3d1748cbaa33eb4d7e7cddaf503f6a191fcac09b9c93024

data/CHANGELOG.md

@@ -8,6 +8,45 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## [Unreleased]
 
 
+## [0.6.0] - 2026-03-10
+
+### Added
+
+- **`Geodetic::WKT` module** — Well-Known Text serialization for all geometry types
+  - **`to_wkt(precision: 6, srid: nil)`** instance method on all 18 coordinate classes, Segment, Path, Areas::Polygon (and subclasses), Areas::Circle, Areas::BoundingBox, and Feature
+  - **Coordinate order**: longitude latitude (OGC Simple Features standard)
+  - **Z suffix**: automatically added when any point in the geometry has non-zero altitude; Z-dimensionality is uniform within each geometry
+  - **EWKT**: `srid:` option prepends `SRID=N;` for PostGIS compatibility
+  - **`WKT.parse(string)`** — parse WKT/EWKT into Geodetic objects (Point → LLA, LineString → Segment/Path, Polygon → Areas::Polygon, Multi*/GeometryCollection → Array)
+  - **`WKT.parse_with_srid(string)`** — returns `[object, srid]` tuple
+  - **`WKT.save!(path, *objects, srid:, precision:)`** — write one WKT per line
+  - **`WKT.load(path)`** — read WKT file into Array of Geodetic objects
+  - ENU/NED raise `ArgumentError` (relative systems cannot be exported)
+- **`Geodetic::WKB` module** — Well-Known Binary serialization for all geometry types
+  - **`to_wkb(srid: nil)`** and **`to_wkb_hex(srid: nil)`** instance methods on all 18 coordinate classes, Segment, Path, Areas::Polygon (and subclasses), Areas::Circle, Areas::BoundingBox, and Feature
+  - **Byte order**: output is always little-endian (NDR), matching PostGIS, GEOS, RGeo, and Shapely; parser supports both LE and BE input
+  - **ISO WKB Z**: type code + 1000 (Point Z = 1001, LineString Z = 1002, Polygon Z = 1003) when any point has non-zero altitude
+  - **EWKB**: `srid:` option embeds SRID via `0x20000000` flag for PostGIS compatibility
+  - **`WKB.parse(input)`** — parse WKB from binary or hex string (auto-detects encoding)
+  - **`WKB.parse_with_srid(input)`** — returns `[object, srid]` tuple
+  - **Binary file I/O**: `WKB.save!(path, *objects, srid:)` / `WKB.load(path)` — framed format (4-byte LE count + size-prefixed WKB)
+  - **Hex file I/O**: `WKB.save_hex!(path, *objects, srid:)` / `WKB.load_hex(path)` — one hex string per line, supports `#` comments
+  - Supports all WKB types: Point, LineString, Polygon, MultiPoint, MultiLineString, MultiPolygon, GeometryCollection
+  - ENU/NED raise `ArgumentError` (relative systems cannot be exported)
+- WKT example (`examples/10_wkt_serialization.rb`) — 10-section demo covering export, SRID/EWKT, Z-dimension, parsing, roundtrip, and file I/O
+- WKB example (`examples/11_wkb_serialization.rb`) — 10-section demo covering export, EWKB/SRID, Z-dimension, parsing, roundtrip, and binary/hex file I/O
+- WKB fixture files: `examples/sample_geometries.wkb` (9 geometries) and `examples/sample_geometries.wkb.hex` (15 geometries with comments)
+- 53 WKT tests (134 assertions) and 54 WKB tests (144 assertions)
+- Documentation: `docs/reference/wkt.md` and `docs/reference/wkb.md`
+
+### Changed
+
+- Updated README with WKT and WKB sections, key features, and examples 10-11 in the examples table
+- Updated `docs/index.md` with WKT and WKB in key features and reference links
+- Updated `examples/README.md` with example 10 and 11 descriptions
+- Updated `mkdocs.yml` nav with WKT and WKB reference pages
+- Added `require_relative "geodetic/wkt"` and `require_relative "geodetic/wkb"` to `lib/geodetic.rb`
+
 ## [0.5.2] - 2026-03-10
 
 ### Added

data/README.md

@@ -25,6 +25,8 @@
 - <strong>Vectors</strong> - Geodetic displacement (distance + bearing) with full arithmetic and Vincenty direct<br>
 - <strong>Geodetic Arithmetic</strong> - Compose geometry with operators: P1 + P2 → Segment, + P3 → Path, + Distance → Circle, * Vector → translate<br>
 - <strong>GeoJSON Export</strong> - Build FeatureCollections from any mix of objects and save to file<br>
+- <strong>WKT Serialization</strong> - Well-Known Text export/import with SRID/EWKT and Z-dimension support<br>
+- <strong>WKB Serialization</strong> - Well-Known Binary export/import with EWKB, SRID, hex encoding, and file I/O<br>
 - <strong>Validated Setters</strong> - Type coercion and range validation on all coordinate attributes<br>
 - <strong>Serialization</strong> - to_s(precision), to_a, from_string, from_array, DMS format<br>
 - <strong>Multiple Datums</strong> - WGS84, Clarke 1866, GRS 1980, Airy 1830, and more<br>
@@ -769,6 +771,73 @@ objects = Geodetic::GeoJSON.load("map.geojson")
 
 `load` returns an Array of Geodetic objects. Features with a `"name"` or non-empty properties round-trip as `Feature` objects; bare geometries with empty properties return as raw coordinates, segments, paths, or polygons. `GeoJSON.parse(hash)` does the same from an already-parsed Hash.
 
+### WKT Serialization
+
+`WKT` provides Well-Known Text export and import for all geometry types. WKT is the standard format used by PostGIS, RGeo, Shapely, JTS, and most GIS tools.
+
+```ruby
+seattle.to_wkt                        # => "POINT(-122.3493 47.6205)"
+seattle.to_wkt(srid: 4326)           # => "SRID=4326;POINT(-122.3493 47.6205)"
+seattle.to_wkt(precision: 2)         # => "POINT(-122.35 47.62)"
+
+Segment.new(seattle, portland).to_wkt # => "LINESTRING(-122.3493 47.6205, -122.6784 45.5152)"
+route.to_wkt                          # => "LINESTRING(...)"
+polygon.to_wkt                        # => "POLYGON((...))
+circle.to_wkt(segments: 64)          # => "POLYGON((...))  (64-gon)"
+feature.to_wkt                        # => delegates to geometry (WKT has no properties)
+```
+
+Altitude triggers the Z suffix. When any point has altitude, all points in that geometry get Z:
+
+```ruby
+Geodetic::Coordinate::LLA.new(lat: 47.62, lng: -122.35, alt: 184.0).to_wkt
+# => "POINT Z(-122.35 47.62 184.0)"
+```
+
+**File I/O and parsing:**
+
+```ruby
+# Save to file (one WKT per line)
+Geodetic::WKT.save!("shapes.wkt", seattle, segment, polygon, srid: 4326)
+
+# Load from file
+objects = Geodetic::WKT.load("shapes.wkt")
+# => [Coordinate::LLA, Segment, Areas::Polygon]
+
+# Parse a single WKT string
+obj = Geodetic::WKT.parse("POINT(-122.3493 47.6205)")
+obj, srid = Geodetic::WKT.parse_with_srid("SRID=4326;POLYGON((-122 47, -121 46, -123 46, -122 47))")
+```
+
+### WKB Serialization
+
+`WKB` provides Well-Known Binary export and import — the binary counterpart to WKT used by PostGIS, GEOS, RGeo, and Shapely for efficient geometry storage. Output is always little-endian (NDR).
+
+```ruby
+seattle.to_wkb                        # => 21-byte binary string
+seattle.to_wkb_hex                    # => "01010000008a1f63ee5a965ec0..."
+seattle.to_wkb_hex(srid: 4326)       # => EWKB with embedded SRID
+
+Segment.new(seattle, portland).to_wkb_hex  # => LINESTRING hex
+polygon.to_wkb_hex                         # => POLYGON hex
+```
+
+**File I/O (binary and hex):**
+
+```ruby
+# Binary format (framed: count + size-prefixed WKB)
+Geodetic::WKB.save!("shapes.wkb", seattle, segment, polygon)
+objects = Geodetic::WKB.load("shapes.wkb")
+
+# Hex format (one hex string per line, supports comments)
+Geodetic::WKB.save_hex!("shapes.wkb.hex", seattle, segment, polygon)
+objects = Geodetic::WKB.load_hex("shapes.wkb.hex")
+
+# Parse a single hex or binary string
+obj = Geodetic::WKB.parse("01010000008a1f63ee5a965ec08195438b6ccf4740")
+obj, srid = Geodetic::WKB.parse_with_srid(ewkb_hex)
+```
+
 ### Web Mercator Tile Coordinates
 
 ```ruby
@@ -802,6 +871,8 @@ The [`examples/`](examples/) directory contains runnable demo scripts showing pr
 | [`07_segments_and_shapes.rb`](examples/07_segments_and_shapes.rb) | Segment and polygon subclasses: Triangle, Rectangle, Pentagon, Hexagon, Octagon with containment, edges, and bounding boxes |
 | [`08_geodetic_arithmetic.rb`](examples/08_geodetic_arithmetic.rb) | Geodetic arithmetic: building geometry with + (Segments, Paths, Circles), Vector class (Vincenty direct, components, arithmetic, dot/cross products), translation with * (Coordinates, Segments, Paths, Circles, Polygons), and corridors |
 | [`09_geojson_export.rb`](examples/09_geojson_export.rb) | GeoJSON export: `to_geojson` on all geometry types, `GeoJSON` class for building FeatureCollections with `<<`, delete/clear, Enumerable, and `save` to file |
+| [`10_wkt_serialization.rb`](examples/10_wkt_serialization.rb) | WKT serialization: `to_wkt` on all geometry types, SRID/EWKT, Z-dimension handling, parsing, and roundtrip verification |
+| [`11_wkb_serialization.rb`](examples/11_wkb_serialization.rb) | WKB serialization: `to_wkb`/`to_wkb_hex` on all geometry types, EWKB/SRID, Z-dimension, parsing, roundtrip, and binary/hex file I/O |
 
 Run any example with:
 

data/docs/index.md

@@ -19,6 +19,8 @@
 <li><strong>Paths</strong> - Directed coordinate sequences with navigation, interpolation, closest approach, intersection, and area conversion<br>
 <li><strong>Features</strong> - Named geometry wrapper with metadata and delegated distance/bearing<br>
 <li><strong>GeoJSON Export</strong> - Build FeatureCollections from any mix of objects and save to file<br>
+<li><strong>WKT Serialization</strong> - Well-Known Text export/import with SRID/EWKT and Z-dimension support<br>
+<li><strong>WKB Serialization</strong> - Well-Known Binary export/import with EWKB, SRID, hex encoding, and file I/O<br>
 <li><strong>Validated Setters</strong> - Type coercion and range validation on all coordinate attributes<br>
 <li><strong>Serialization</strong> - to_s(precision), to_a, from_string, from_array, DMS format<br>
 <li><strong>Multiple Datums</strong> - WGS84, Clarke 1866, GRS 1980, Airy 1830, and more<br>
@@ -114,4 +116,6 @@ puts lla_again.to_s
 - [Vector](reference/vector.md)
 - [Arithmetic](reference/arithmetic.md)
 - [GeoJSON Export](reference/geojson.md)
+- [WKT Serialization](reference/wkt.md)
+- [WKB Serialization](reference/wkb.md)
 - [Map Rendering](reference/map-rendering.md)

data/docs/reference/wkb.md

@@ -0,0 +1,385 @@
+# WKB Serialization Reference
+
+`Geodetic::WKB` provides [Well-Known Binary](https://en.wikipedia.org/wiki/Well-known_binary_representation_of_geometry) (WKB) serialization for all Geodetic geometry types. WKB is the binary counterpart to WKT, used by PostGIS, GEOS, RGeo, Shapely, and most GIS tools for efficient geometry storage and transfer.
+
+Every geometry type gains `to_wkb` and `to_wkb_hex` instance methods. The module also provides `WKB.parse` and `WKB.parse_with_srid` for importing WKB data back into Geodetic objects.
+
+**Byte order:** Output is always little-endian (NDR), matching PostGIS, GEOS, RGeo, Shapely, and virtually all modern GIS tools. Big-endian (XDR) input is fully supported by the parser.
+
+---
+
+## Export
+
+### Coordinates → POINT
+
+All 18 coordinate classes gain `to_wkb` and `to_wkb_hex` methods. They convert the coordinate to LLA and return WKB binary or hex-encoded output.
+
+```ruby
+seattle = Geodetic::Coordinate::LLA.new(lat: 47.6205, lng: -122.3493, alt: 0.0)
+
+seattle.to_wkb           # => 21-byte binary string
+seattle.to_wkb_hex       # => "01010000008a1f63ee5a965ec08195438b6ccf4740"
+```
+
+**Altitude handling:** When altitude is non-zero, the Z type code is used (Point Z = 1001):
+
+```ruby
+Geodetic::Coordinate::LLA.new(lat: 47.62, lng: -122.35, alt: 184.0).to_wkb_hex
+# => "01e90300008a1f63ee5a965ec08195438b6ccf47400000000000006740"
+```
+
+**Cross-system:** Any coordinate type works — UTM, ECEF, MGRS, etc. are converted to LLA internally.
+
+```ruby
+seattle.to_utm.to_wkb_hex    # => hex string
+seattle.to_ecef.to_wkb_hex   # => hex string
+```
+
+**ENU and NED:** These are relative coordinate systems. Calling `to_wkb` raises `ArgumentError`.
+
+---
+
+### Segment → LINESTRING
+
+```ruby
+seg = Geodetic::Segment.new(seattle, portland)
+seg.to_wkb           # => 41-byte binary string
+seg.to_wkb_hex       # => hex string
+```
+
+---
+
+### Path → LINESTRING / POLYGON
+
+Returns a LINESTRING by default. Pass `as: :polygon` for a closed POLYGON.
+
+```ruby
+route = Geodetic::Path.new(coordinates: [seattle, portland, sf])
+route.to_wkb              # => LINESTRING binary
+route.to_wkb(as: :polygon) # => POLYGON binary
+```
+
+---
+
+### Areas::Polygon → POLYGON
+
+```ruby
+poly = Geodetic::Areas::Polygon.new(boundary: [a, b, c])
+poly.to_wkb       # => binary
+poly.to_wkb_hex   # => hex string
+```
+
+All Polygon subclasses (`Triangle`, `Rectangle`, `Pentagon`, `Hexagon`, `Octagon`) inherit this method.
+
+---
+
+### Areas::Circle → POLYGON
+
+Approximated as a regular N-gon. Default is 32 segments.
+
+```ruby
+circle = Geodetic::Areas::Circle.new(centroid: seattle, radius: 10_000)
+
+circle.to_wkb                   # => 32-gon binary (541 bytes)
+circle.to_wkb(segments: 64)     # => 64-gon
+circle.to_wkb(segments: 8)      # => 8-gon (157 bytes)
+```
+
+---
+
+### Areas::BoundingBox → POLYGON
+
+5 positions (4 corners + closing point).
+
+```ruby
+bbox = Geodetic::Areas::BoundingBox.new(
+  nw: Geodetic::Coordinate::LLA.new(lat: 48.0, lng: -123.0, alt: 0),
+  se: Geodetic::Coordinate::LLA.new(lat: 46.0, lng: -121.0, alt: 0)
+)
+bbox.to_wkb       # => 93-byte binary
+bbox.to_wkb_hex   # => hex string
+```
+
+---
+
+### Feature → delegates to geometry
+
+WKB has no concept of properties or labels. `Feature#to_wkb` delegates directly to the underlying geometry.
+
+```ruby
+f = Geodetic::Feature.new(label: "Seattle", geometry: seattle, metadata: { pop: 750_000 })
+f.to_wkb_hex   # => same as seattle.to_wkb_hex
+```
+
+---
+
+## Options
+
+All `to_wkb` and `to_wkb_hex` methods accept:
+
+| Parameter | Default | Description |
+|-----------|---------|-------------|
+| `srid:` | `nil` | When set, produces EWKB with embedded SRID |
+
+---
+
+## Z-Dimension Consistency
+
+When any point in a geometry has non-zero altitude, **all** points in that geometry use the Z type code. This follows the OGC rule that Z-dimensionality is uniform within a geometry.
+
+```ruby
+# seattle (alt=0) + sf (alt=100) → LineString Z (type code 1002)
+mixed = Geodetic::Segment.new(seattle, sf_with_altitude)
+mixed.to_wkb  # type code = 1002 (LineString Z)
+
+# Both at alt=0 → LineString (type code 2)
+flat = Geodetic::Segment.new(seattle, portland)
+flat.to_wkb   # type code = 2 (LineString)
+```
+
+---
+
+## SRID / EWKB
+
+Pass `srid:` to any `to_wkb` or `to_wkb_hex` call to produce Extended WKB (EWKB), the format used by PostGIS:
+
+```ruby
+seattle.to_wkb_hex(srid: 4326)
+# => "0101000020e61000008a1f63ee5a965ec08195438b6ccf4740"
+
+seg.to_wkb_hex(srid: 4326)
+# => "0102000020e6100000020000008a1f63ee..."
+```
+
+EWKB embeds the SRID in the type code using the `0x20000000` flag, followed by a 4-byte SRID value.
+
+Common SRIDs:
+
+| SRID | Description |
+|------|-------------|
+| 4326 | WGS84 geographic (lat/lng) |
+| 3857 | Web Mercator |
+| 32610 | UTM Zone 10N |
+
+---
+
+## File I/O
+
+### Binary Format
+
+#### `WKB.save!(path, *objects, srid: nil)`
+
+Write geometries to a binary file using a framed format: 4-byte LE count, then for each geometry a 4-byte LE size followed by raw WKB bytes. Accepts individual objects or an array.
+
+```ruby
+Geodetic::WKB.save!("shapes.wkb", seattle, segment, polygon)
+Geodetic::WKB.save!("shapes.wkb", [seattle, segment, polygon])
+Geodetic::WKB.save!("shapes.wkb", seattle, polygon, srid: 4326)
+```
+
+#### `WKB.load(path)`
+
+Read a binary WKB file and return an Array of Geodetic objects.
+
+```ruby
+objects = Geodetic::WKB.load("shapes.wkb")
+# => [Coordinate::LLA, Segment, Areas::Polygon]
+```
+
+### Hex Format
+
+#### `WKB.save_hex!(path, *objects, srid: nil)`
+
+Write one hex-encoded WKB string per line. Human-readable and diff-friendly.
+
+```ruby
+Geodetic::WKB.save_hex!("shapes.wkb.hex", seattle, segment, polygon)
+```
+
+Output file:
+
+```
+01010000008a1f63ee5a965ec08195438b6ccf4740
+0102000000020000008a1f63ee5a965ec0...
+01030000000100000004000000...
+```
+
+#### `WKB.load_hex(path)`
+
+Read a hex WKB file and return an Array of Geodetic objects. Blank lines and lines starting with `#` are skipped.
+
+```ruby
+objects = Geodetic::WKB.load_hex("shapes.wkb.hex")
+# => [Coordinate::LLA, Segment, Areas::Polygon]
+```
+
+### Roundtrip
+
+```ruby
+objects = [seattle, segment, polygon]
+
+# Binary roundtrip
+Geodetic::WKB.save!("data.wkb", objects)
+loaded = Geodetic::WKB.load("data.wkb")
+
+# Hex roundtrip
+Geodetic::WKB.save_hex!("data.wkb.hex", objects, srid: 4326)
+loaded = Geodetic::WKB.load_hex("data.wkb.hex")
+```
+
+---
+
+## Import
+
+### `WKB.parse(input)`
+
+Parse a WKB binary string or hex string and return a Geodetic object (or Array for Multi*/GeometryCollection types). Auto-detects binary vs hex encoding.
+
+```ruby
+Geodetic::WKB.parse("01010000008a1f63ee5a965ec08195438b6ccf4740")
+# => Coordinate::LLA
+
+Geodetic::WKB.parse(binary_string)
+# => Coordinate::LLA
+```
+
+### `WKB.parse_with_srid(input)`
+
+Parse WKB/EWKB and return both the object and the SRID:
+
+```ruby
+obj, srid = Geodetic::WKB.parse_with_srid("0101000020e61000008a1f63ee5a965ec08195438b6ccf4740")
+obj   # => Coordinate::LLA
+srid  # => 4326
+
+obj, srid = Geodetic::WKB.parse_with_srid(plain_wkb_hex)
+srid  # => nil
+```
+
+---
+
+## WKB → Geodetic Type Mapping
+
+| WKB Type Code | WKB Type | Geodetic Type |
+|---------------|----------|---------------|
+| 1 | POINT | `Coordinate::LLA` |
+| 2 (2 points) | LINESTRING | `Segment` |
+| 2 (3+ points) | LINESTRING | `Path` |
+| 3 | POLYGON | `Areas::Polygon` (outer ring only; holes are dropped) |
+| 4 | MULTIPOINT | Array of `Coordinate::LLA` |
+| 5 | MULTILINESTRING | Array of `Segment` or `Path` |
+| 6 | MULTIPOLYGON | Array of `Areas::Polygon` |
+| 7 | GEOMETRYCOLLECTION | Array of mixed types |
+
+Z variants (type + 1000) are supported: Point Z = 1001, LineString Z = 1002, Polygon Z = 1003.
+
+---
+
+## Geometry Mapping (Export)
+
+| Geodetic Type | WKB Type | Notes |
+|---------------|----------|-------|
+| Any coordinate (LLA, UTM, ECEF, ...) | POINT | Converts through LLA |
+| `Segment` | LINESTRING | 2 positions |
+| `Path` | LINESTRING | N positions (default) |
+| `Path` (with `as: :polygon`) | POLYGON | Auto-closes the ring |
+| `Areas::Polygon` (and subclasses) | POLYGON | Boundary ring already closed |
+| `Areas::Circle` | POLYGON | Approximated as N-gon (default 32) |
+| `Areas::BoundingBox` | POLYGON | 4 corners, closed |
+| `Feature` | Delegates to geometry | Properties are lost |
+
+---
+
+## WKB Binary Structure
+
+Each WKB geometry starts with:
+
+| Offset | Size | Description |
+|--------|------|-------------|
+| 0 | 1 byte | Byte order: `0x01` = little-endian (NDR), `0x00` = big-endian (XDR) |
+| 1 | 4 bytes | Type code (uint32) |
+| 5 | 4 bytes | SRID (uint32, only in EWKB when SRID flag is set) |
+| 5 or 9 | varies | Geometry data (IEEE 754 doubles) |
+
+**Type codes:**
+
+| Code | Type | Z Code |
+|------|------|--------|
+| 1 | Point | 1001 |
+| 2 | LineString | 1002 |
+| 3 | Polygon | 1003 |
+| 4 | MultiPoint | 1004 |
+| 5 | MultiLineString | 1005 |
+| 6 | MultiPolygon | 1006 |
+| 7 | GeometryCollection | 1007 |
+
+**EWKB flags** (OR'd into type code):
+
+| Flag | Value | Description |
+|------|-------|-------------|
+| SRID | `0x20000000` | SRID follows the type code |
+| Z | `0x80000000` | Coordinates include Z values |
+
+---
+
+## Roundtrip Example
+
+```ruby
+require "geodetic"
+
+seattle = Geodetic::Coordinate::LLA.new(lat: 47.6205, lng: -122.3493, alt: 0)
+
+# Export
+hex = seattle.to_wkb_hex(srid: 4326)
+# => "0101000020e61000008a1f63ee5a965ec08195438b6ccf4740"
+
+# Import
+obj, srid = Geodetic::WKB.parse_with_srid(hex)
+obj.lat   # => 47.6205
+obj.lng   # => -122.3493
+srid      # => 4326
+
+# Re-export
+obj.to_wkb_hex(srid: srid) == hex  # => true
+```
+
+---
+
+## Integration with PostGIS and RGeo
+
+WKB is the preferred format for exchanging geometry with spatial databases:
+
+```ruby
+# Writing to PostGIS (hex format)
+hex = polygon.to_wkb_hex(srid: 4326)
+ActiveRecord::Base.connection.execute(
+  "INSERT INTO regions (geom) VALUES (ST_GeomFromWKB(decode('#{hex}', 'hex'), 4326))"
+)
+
+# Or using EWKB directly
+ewkb_hex = polygon.to_wkb_hex(srid: 4326)
+ActiveRecord::Base.connection.execute(
+  "INSERT INTO regions (geom) VALUES ('#{ewkb_hex}')"
+)
+
+# Reading from PostGIS
+row = ActiveRecord::Base.connection.select_one("SELECT ST_AsEWKB(geom)::text FROM regions LIMIT 1")
+obj, srid = Geodetic::WKB.parse_with_srid(row["st_asewkb"])
+```
+
+WKB binary is also accepted by RGeo's `WKRep::WKBParser`, Shapely's `wkb.loads()`, JTS, GEOS, and virtually every GIS library.
+
+---
+
+## WKB vs WKT
+
+| | WKB | WKT |
+|---|-----|-----|
+| **Format** | Binary | Text |
+| **Size** | Compact | Larger |
+| **Human-readable** | No (use hex) | Yes |
+| **Speed** | Faster to parse | Slower |
+| **Use case** | Database storage, wire transfer | Debugging, config files, SQL |
+| **SRID support** | EWKB flag | EWKT prefix |
+
+Both formats support the same geometry types and Z-dimension handling.