geodetic 0.5.2 → 0.7.0

data/docs/reference/wkt.md

@@ -0,0 +1,354 @@
+# WKT Serialization Reference
+
+`Geodetic::WKT` provides [Well-Known Text](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry) (WKT) serialization for all Geodetic geometry types. WKT is the standard text format used by PostGIS, RGeo, Shapely, JTS, GEOS, and most GIS tools.
+
+Every geometry type gains a `to_wkt` instance method. The module also provides `WKT.parse` and `WKT.parse_with_srid` for importing WKT strings back into Geodetic objects.
+
+---
+
+## Export
+
+### Coordinates → POINT
+
+All 18 coordinate classes gain a `to_wkt` method. It converts the coordinate to LLA and returns a WKT POINT string.
+
+```ruby
+seattle = Geodetic::Coordinate::LLA.new(lat: 47.6205, lng: -122.3493, alt: 0.0)
+seattle.to_wkt
+# => "POINT(-122.3493 47.6205)"
+```
+
+**Altitude handling:** When altitude is non-zero, the Z suffix is added:
+
+```ruby
+Geodetic::Coordinate::LLA.new(lat: 47.62, lng: -122.35, alt: 184.0).to_wkt
+# => "POINT Z(-122.35 47.62 184.0)"
+```
+
+**Cross-system:** Any coordinate type works — UTM, ECEF, MGRS, etc. are converted to LLA internally.
+
+```ruby
+seattle.to_utm.to_wkt    # => "POINT(-122.3493 47.6205)"
+seattle.to_ecef.to_wkt   # => "POINT(-122.3493 47.6205)"
+```
+
+**ENU and NED:** These are relative coordinate systems. Calling `to_wkt` raises `ArgumentError`.
+
+```ruby
+enu = Geodetic::Coordinate::ENU.new(e: 100, n: 200, u: 10)
+enu.to_wkt  # => ArgumentError
+```
+
+### Options
+
+All `to_wkt` methods accept these keyword arguments:
+
+| Parameter | Default | Description |
+|-----------|---------|-------------|
+| `precision:` | `6` | Number of decimal places for coordinates |
+| `srid:` | `nil` | When set, prepends `SRID=N;` (EWKT format) |
+
+```ruby
+seattle.to_wkt(precision: 2)
+# => "POINT(-122.35 47.62)"
+
+seattle.to_wkt(srid: 4326)
+# => "SRID=4326;POINT(-122.3493 47.6205)"
+```
+
+---
+
+### Segment → LINESTRING
+
+```ruby
+seg = Geodetic::Segment.new(seattle, portland)
+seg.to_wkt
+# => "LINESTRING(-122.3493 47.6205, -122.6784 45.5152)"
+```
+
+---
+
+### 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_wkt
+# => "LINESTRING(-122.3493 47.6205, -122.6784 45.5152, -122.4194 37.7749)"
+
+route.to_wkt(as: :polygon)
+# => "POLYGON((-122.3493 47.6205, -122.6784 45.5152, -122.4194 37.7749, -122.3493 47.6205))"
+```
+
+**Edge cases:**
+
+| Condition | Behavior |
+|-----------|----------|
+| Empty path | Raises `ArgumentError` |
+| 1 coordinate (line_string) | Raises `ArgumentError` |
+| 2 coordinates (polygon) | Raises `ArgumentError` |
+
+---
+
+### Areas::Polygon → POLYGON
+
+```ruby
+poly = Geodetic::Areas::Polygon.new(boundary: [a, b, c])
+poly.to_wkt
+# => "POLYGON((-122.5 47.7, -122.1 47.5, -122.4 47.3, -122.5 47.7))"
+```
+
+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_wkt                 # => 32-gon
+circle.to_wkt(segments: 64)   # => 64-gon
+circle.to_wkt(segments: 8)    # => 8-gon
+```
+
+---
+
+### 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_wkt
+# => "POLYGON((-123.0 48.0, -121.0 48.0, -121.0 46.0, -123.0 46.0, -123.0 48.0))"
+```
+
+---
+
+### Feature → delegates to geometry
+
+WKT has no concept of properties or labels. `Feature#to_wkt` delegates directly to the underlying geometry.
+
+```ruby
+f = Geodetic::Feature.new(label: "Seattle", geometry: seattle, metadata: { pop: 750_000 })
+f.to_wkt
+# => "POINT(-122.3493 47.6205)"
+```
+
+---
+
+## Z-Dimension Consistency
+
+When any point in a geometry has non-zero altitude, **all** points in that geometry use the Z suffix. This follows the OGC rule that Z-dimensionality is uniform within a geometry.
+
+```ruby
+# seattle has alt=0, sf has alt=100
+path = Geodetic::Path.new(coordinates: [seattle, sf])
+path.to_wkt
+# => "LINESTRING Z(-122.3493 47.6205 0.0, -122.4194 37.7749 100.0)"
+
+# Both at alt=0 → no Z
+path2 = Geodetic::Path.new(coordinates: [seattle, portland])
+path2.to_wkt
+# => "LINESTRING(-122.3493 47.6205, -122.6784 45.5152)"
+```
+
+---
+
+## SRID / EWKT
+
+Pass `srid:` to any `to_wkt` call to produce Extended WKT (EWKT), the format used by PostGIS:
+
+```ruby
+seattle.to_wkt(srid: 4326)
+# => "SRID=4326;POINT(-122.3493 47.6205)"
+
+seg.to_wkt(srid: 4326)
+# => "SRID=4326;LINESTRING(-122.3493 47.6205, -122.6784 45.5152)"
+
+poly.to_wkt(srid: 4326)
+# => "SRID=4326;POLYGON((...))
+```
+
+Common SRIDs:
+
+| SRID | Description |
+|------|-------------|
+| 4326 | WGS84 geographic (lat/lng) |
+| 3857 | Web Mercator |
+| 32610 | UTM Zone 10N |
+
+---
+
+## File I/O
+
+### `WKT.save!(path, *objects, srid: nil, precision: 6)`
+
+Write one WKT string per line. Accepts individual objects or an array.
+
+```ruby
+Geodetic::WKT.save!("shapes.wkt", seattle, segment, polygon)
+Geodetic::WKT.save!("shapes.wkt", [seattle, segment, polygon])
+Geodetic::WKT.save!("shapes.wkt", seattle, polygon, srid: 4326, precision: 2)
+```
+
+Output file (one geometry per line):
+
+```
+POINT(-122.3493 47.6205)
+LINESTRING(-122.3493 47.6205, -122.6784 45.5152)
+POLYGON((-122.0 47.0, -121.0 46.0, -123.0 46.0, -122.0 47.0))
+```
+
+### `WKT.load(path)`
+
+Read a WKT file and return an Array of Geodetic objects. Blank lines are skipped.
+
+```ruby
+objects = Geodetic::WKT.load("shapes.wkt")
+# => [Coordinate::LLA, Segment, Areas::Polygon]
+```
+
+**Roundtrip:**
+
+```ruby
+Geodetic::WKT.save!("data.wkt", seattle, portland, polygon, srid: 4326)
+objects = Geodetic::WKT.load("data.wkt")
+```
+
+---
+
+## Import
+
+### `WKT.parse(string)`
+
+Parse a WKT string and return a Geodetic object (or Array for Multi*/GeometryCollection types).
+
+```ruby
+Geodetic::WKT.parse("POINT(-122.3493 47.6205)")
+# => Coordinate::LLA
+
+Geodetic::WKT.parse("LINESTRING(-122.35 47.62, -122.68 45.52)")
+# => Segment (2 points) or Path (3+ points)
+
+Geodetic::WKT.parse("POLYGON((-122.0 47.0, -121.0 46.0, -123.0 46.0, -122.0 47.0))")
+# => Areas::Polygon
+
+Geodetic::WKT.parse("MULTIPOINT((-122.35 47.62), (-122.68 45.52))")
+# => [LLA, LLA]
+
+Geodetic::WKT.parse("GEOMETRYCOLLECTION(POINT(-122.35 47.62), LINESTRING(...))")
+# => [LLA, Segment]
+```
+
+SRID prefixes are silently stripped:
+
+```ruby
+Geodetic::WKT.parse("SRID=4326;POINT(-122.35 47.62)")
+# => Coordinate::LLA (SRID discarded)
+```
+
+### `WKT.parse_with_srid(string)`
+
+Parse a WKT/EWKT string and return both the object and the SRID:
+
+```ruby
+obj, srid = Geodetic::WKT.parse_with_srid("SRID=4326;POINT(-122.3493 47.6205)")
+obj   # => Coordinate::LLA
+srid  # => 4326
+
+obj, srid = Geodetic::WKT.parse_with_srid("POINT(-122.3493 47.6205)")
+srid  # => nil
+```
+
+---
+
+## WKT → Geodetic Type Mapping
+
+| WKT Type | Geodetic Type |
+|----------|---------------|
+| POINT | `Coordinate::LLA` |
+| LINESTRING (2 points) | `Segment` |
+| LINESTRING (3+ points) | `Path` |
+| POLYGON | `Areas::Polygon` (outer ring only; holes are dropped) |
+| MULTIPOINT | Array of `Coordinate::LLA` |
+| MULTILINESTRING | Array of `Segment` or `Path` |
+| MULTIPOLYGON | Array of `Areas::Polygon` |
+| GEOMETRYCOLLECTION | Array of mixed types |
+
+All types support the Z suffix for 3D coordinates.
+
+---
+
+## Geometry Mapping (Export)
+
+| Geodetic Type | WKT 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 |
+
+---
+
+## Roundtrip Example
+
+```ruby
+require "geodetic"
+
+seattle = Geodetic::Coordinate::LLA.new(lat: 47.6205, lng: -122.3493, alt: 0)
+
+# Export
+wkt = seattle.to_wkt(srid: 4326)
+# => "SRID=4326;POINT(-122.3493 47.6205)"
+
+# Import
+obj, srid = Geodetic::WKT.parse_with_srid(wkt)
+obj.lat   # => 47.6205
+obj.lng   # => -122.3493
+srid      # => 4326
+
+# Re-export
+obj.to_wkt(srid: srid) == wkt  # => true
+```
+
+---
+
+## WKT Specification Notes
+
+- **Coordinate order** is `longitude latitude` (same as GeoJSON), per OGC Simple Features.
+- **Z suffix** indicates 3D coordinates: `POINT Z(lng lat alt)`.
+- **Polygon rings** are closed (first point = last point).
+- **EWKT** (Extended WKT) prepends `SRID=N;` — this is a PostGIS extension, not part of the OGC standard.
+- **No properties** — unlike GeoJSON, WKT is geometry-only. Feature labels and metadata are not preserved.
+
+---
+
+## Integration with PostGIS and RGeo
+
+WKT is the lingua franca for exchanging geometry between Ruby and spatial databases:
+
+```ruby
+# Writing to PostGIS
+wkt = polygon.to_wkt(srid: 4326)
+ActiveRecord::Base.connection.execute(
+  "INSERT INTO regions (geom) VALUES (ST_GeomFromEWKT('#{wkt}'))"
+)
+
+# Reading from PostGIS
+row = ActiveRecord::Base.connection.select_one("SELECT ST_AsEWKT(geom) FROM regions LIMIT 1")
+obj, srid = Geodetic::WKT.parse_with_srid(row["st_asewkt"])
+```
+
+WKT strings are also accepted by RGeo's `WKRep::WKTParser`, Shapely's `loads()`, JTS, GEOS, and virtually every GIS library.

data/examples/10_wkt_serialization.rb

@@ -0,0 +1,248 @@
+#!/usr/bin/env ruby
+
+# Demonstration of WKT (Well-Known Text) Serialization
+# Shows export, import, roundtrip, SRID/EWKT, and Z-dimension handling.
+
+require_relative "../lib/geodetic"
+
+include Geodetic
+
+LLA      = Coordinate::LLA
+Distance = Geodetic::Distance
+
+puts "=== WKT Serialization Demo ==="
+puts
+
+# ── 1. Coordinate → POINT ──────────────────────────────────────────
+
+puts "--- 1. Coordinate → POINT ---"
+puts
+
+seattle = LLA.new(lat: 47.6205, lng: -122.3493, alt: 0.0)
+puts "  seattle.to_wkt"
+puts "  => #{seattle.to_wkt}"
+puts
+
+# Works from any coordinate system — converts through LLA
+utm = seattle.to_utm
+puts "  seattle.to_utm.to_wkt"
+puts "  => #{utm.to_wkt}"
+puts
+
+# Altitude triggers Z suffix
+space_needle = LLA.new(lat: 47.6205, lng: -122.3493, alt: 184.0)
+puts "  With altitude:"
+puts "  => #{space_needle.to_wkt}"
+puts
+
+# Custom precision
+puts "  Custom precision (2):"
+puts "  => #{seattle.to_wkt(precision: 2)}"
+puts
+
+# ── 2. Segment → LINESTRING ────────────────────────────────────────
+
+puts "--- 2. Segment → LINESTRING ---"
+puts
+
+portland = LLA.new(lat: 45.5152, lng: -122.6784, alt: 0.0)
+seg = Segment.new(seattle, portland)
+puts "  #{seg.to_wkt}"
+puts
+
+# ── 3. Path → LINESTRING or POLYGON ────────────────────────────────
+
+puts "--- 3. Path → LINESTRING / POLYGON ---"
+puts
+
+sf = LLA.new(lat: 37.7749, lng: -122.4194, alt: 0.0)
+la = LLA.new(lat: 34.0522, lng: -118.2437, alt: 0.0)
+route = Path.new(coordinates: [seattle, portland, sf, la])
+puts "  Path as LINESTRING:"
+puts "  #{route.to_wkt}"
+puts
+
+triangle_path = Path.new(coordinates: [
+  LLA.new(lat: 47.0, lng: -122.5, alt: 0),
+  LLA.new(lat: 46.0, lng: -121.0, alt: 0),
+  LLA.new(lat: 46.0, lng: -123.0, alt: 0)
+])
+puts "  Path as POLYGON:"
+puts "  #{triangle_path.to_wkt(as: :polygon)}"
+puts
+
+# ── 4. Areas → POLYGON ─────────────────────────────────────────────
+
+puts "--- 4. Areas → POLYGON ---"
+puts
+
+a = LLA.new(lat: 47.7, lng: -122.5, alt: 0)
+b = LLA.new(lat: 47.5, lng: -122.1, alt: 0)
+c = LLA.new(lat: 47.3, lng: -122.4, alt: 0)
+poly = Areas::Polygon.new(boundary: [a, b, c])
+puts "  Polygon: #{poly.to_wkt(precision: 1)}"
+
+circle = Areas::Circle.new(centroid: seattle, radius: 10_000)
+circle_wkt = circle.to_wkt(segments: 8, precision: 4)
+puts "  Circle (8-gon): #{circle_wkt[0..60]}..."
+
+bbox = Areas::BoundingBox.new(
+  nw: LLA.new(lat: 48.0, lng: -123.0, alt: 0),
+  se: LLA.new(lat: 46.0, lng: -121.0, alt: 0)
+)
+puts "  BoundingBox: #{bbox.to_wkt(precision: 1)}"
+puts
+
+# ── 5. Feature delegates to geometry ───────────────────────────────
+
+puts "--- 5. Feature → delegates to geometry ---"
+puts
+
+city = Feature.new(label: "Seattle", geometry: seattle, metadata: { pop: 750_000 })
+puts "  Feature('Seattle').to_wkt"
+puts "  => #{city.to_wkt}"
+puts "  (WKT has no properties; label/metadata are lost)"
+puts
+
+# ── 6. SRID / EWKT ─────────────────────────────────────────────────
+
+puts "--- 6. SRID / EWKT ---"
+puts
+
+puts "  POINT with SRID:"
+puts "  => #{seattle.to_wkt(srid: 4326)}"
+
+puts "  LINESTRING with SRID:"
+puts "  => #{seg.to_wkt(srid: 4326)}"
+
+puts "  POLYGON with SRID:"
+puts "  => #{poly.to_wkt(srid: 4326, precision: 1)}"
+puts
+
+# ── 7. Z-dimension consistency ──────────────────────────────────────
+
+puts "--- 7. Z-dimension consistency ---"
+puts
+
+# When ANY point has altitude, ALL points get Z
+mixed = Path.new(coordinates: [seattle, space_needle])
+puts "  seattle (alt=0) + space_needle (alt=184):"
+puts "  => #{mixed.to_wkt}"
+puts "  (Both coordinates get Z even though seattle has alt=0)"
+puts
+
+no_alt = Path.new(coordinates: [seattle, portland])
+puts "  seattle + portland (both alt=0):"
+puts "  => #{no_alt.to_wkt}"
+puts "  (No Z suffix when all altitudes are zero)"
+puts
+
+# ── 8. Parsing WKT ─────────────────────────────────────────────────
+
+puts "--- 8. Parsing WKT ---"
+puts
+
+wkt_strings = [
+  "POINT(-122.3493 47.6205)",
+  "POINT Z(-122.3493 47.6205 184.0)",
+  "LINESTRING(-122.3493 47.6205, -122.6784 45.5152)",
+  "POLYGON((-122.0 47.0, -121.0 46.0, -123.0 46.0, -122.0 47.0))",
+  "MULTIPOINT((-122.35 47.62), (-122.68 45.52))",
+  "GEOMETRYCOLLECTION(POINT(-122.35 47.62), LINESTRING(-122.35 47.62, -122.68 45.52))"
+]
+
+wkt_strings.each do |wkt|
+  result = WKT.parse(wkt)
+  type = wkt[/\A\w+/]
+  if result.is_a?(Array)
+    puts "  #{type} → #{result.map { |r| r.class.name.split('::').last }.join(', ')}"
+  else
+    puts "  #{type} → #{result.class.name.split('::').last}"
+  end
+end
+puts
+
+# Parsing EWKT with SRID
+ewkt = "SRID=4326;POINT(-122.3493 47.6205)"
+obj, srid = WKT.parse_with_srid(ewkt)
+puts "  EWKT: #{ewkt}"
+puts "  → object: #{obj.class.name.split('::').last}(#{obj.to_s(4)}), srid: #{srid}"
+puts
+
+# ── 9. Roundtrip ───────────────────────────────────────────────────
+
+puts "--- 9. Roundtrip (export → parse → export) ---"
+puts
+
+objects = {
+  "POINT"      => seattle,
+  "POINT Z"    => space_needle,
+  "LINESTRING" => Segment.new(seattle, portland),
+  "PATH"       => Path.new(coordinates: [seattle, portland, sf]),
+  "POLYGON"    => poly,
+  "BBOX"       => bbox,
+  "SRID"       => seattle  # will use srid: 4326
+}
+
+objects.each do |label, obj|
+  srid = label == "SRID" ? 4326 : nil
+  original_wkt = obj.to_wkt(srid: srid)
+
+  if srid
+    parsed, parsed_srid = WKT.parse_with_srid(original_wkt)
+    roundtrip_wkt = parsed.to_wkt(srid: parsed_srid)
+  else
+    parsed = WKT.parse(original_wkt)
+    roundtrip_wkt = parsed.to_wkt
+  end
+
+  match = original_wkt == roundtrip_wkt ? "MATCH" : "DIFF"
+  puts "  #{label.ljust(12)} #{match}  #{original_wkt[0..55]}#{"..." if original_wkt.length > 55}"
+end
+puts
+
+# ── 10. File I/O (save & load) ──────────────────────────────────────
+
+puts "--- 10. File I/O (save & load) ---"
+puts
+
+output_path = File.join(__dir__, "geodetic_demo.wkt")
+
+save_objects = [seattle, space_needle, seg, poly, bbox]
+WKT.save!(output_path, save_objects)
+puts "  Saved #{save_objects.length} objects to: #{output_path}"
+puts "  File size: #{File.size(output_path)} bytes"
+puts
+
+puts "  File contents:"
+File.readlines(output_path, chomp: true).each_with_index do |line, i|
+  puts "    #{i + 1}: #{line}"
+end
+puts
+
+loaded = WKT.load(output_path)
+puts "  Loaded #{loaded.length} objects:"
+loaded.each do |obj|
+  puts "    #{obj.class.name.split('::').last}: #{obj.to_wkt(precision: 4)[0..60]}#{"..." if obj.to_wkt(precision: 4).length > 60}"
+end
+puts
+
+# Verify roundtrip
+puts "  Roundtrip check:"
+save_objects.zip(loaded).each_with_index do |(orig, back), i|
+  match = orig.to_wkt == back.to_wkt ? "MATCH" : "DIFF"
+  puts "    object #{i + 1}: #{match}"
+end
+puts
+
+# Save with SRID
+srid_path = File.join(__dir__, "geodetic_demo_srid.wkt")
+WKT.save!(srid_path, seattle, portland, srid: 4326, precision: 4)
+puts "  Saved with SRID=4326 to: #{srid_path}"
+File.readlines(srid_path, chomp: true).each { |line| puts "    #{line}" }
+puts
+
+# Clean up the SRID file
+File.delete(srid_path) if File.exist?(srid_path)
+
+puts "=== Done ==="