geodetic 0.5.2 → 0.7.0

data/examples/11_wkb_serialization.rb

@@ -0,0 +1,261 @@
+#!/usr/bin/env ruby
+
+# Demonstration of WKB (Well-Known Binary) Serialization
+# Shows export, import, roundtrip, SRID/EWKB, Z-dimension handling,
+# hex encoding, and file I/O in both binary and hex formats.
+
+require_relative "../lib/geodetic"
+
+include Geodetic
+
+LLA = Coordinate::LLA
+
+puts "=== WKB Serialization Demo ==="
+puts
+puts "  WKB is the binary counterpart to WKT — the format PostGIS, GEOS,"
+puts "  RGeo, and Shapely use for efficient geometry storage and transfer."
+puts "  Output is always little-endian (NDR), matching modern GIS conventions."
+puts
+
+# ── 1. Coordinate → POINT ──────────────────────────────────────────
+
+puts "--- 1. Coordinate → POINT ---"
+puts
+
+seattle = LLA.new(lat: 47.6205, lng: -122.3493, alt: 0.0)
+wkb = seattle.to_wkb
+puts "  seattle.to_wkb"
+puts "  => #{wkb.bytesize} bytes (binary)"
+puts
+
+hex = seattle.to_wkb_hex
+puts "  seattle.to_wkb_hex"
+puts "  => #{hex}"
+puts
+
+# Cross-system
+utm = seattle.to_utm
+puts "  seattle.to_utm.to_wkb_hex"
+puts "  => #{utm.to_wkb_hex}"
+puts
+
+# Altitude triggers Z type code (Point Z = 1001)
+space_needle = LLA.new(lat: 47.6205, lng: -122.3493, alt: 184.0)
+puts "  With altitude (Point Z):"
+puts "  => #{space_needle.to_wkb_hex}"
+puts
+
+# ── 2. Segment → LINESTRING ────────────────────────────────────────
+
+puts "--- 2. Segment → LINESTRING ---"
+puts
+
+portland = LLA.new(lat: 45.5152, lng: -122.6784, alt: 0.0)
+seg = Geodetic::Segment.new(seattle, portland)
+puts "  #{seg.to_wkb.bytesize} bytes: #{seg.to_wkb_hex}"
+puts
+
+# ── 3. Path → LINESTRING / POLYGON ────────────────────────────────
+
+puts "--- 3. Path → LINESTRING / POLYGON ---"
+puts
+
+sf = LLA.new(lat: 37.7749, lng: -122.4194, alt: 0.0)
+route = Path.new(coordinates: [seattle, portland, sf])
+puts "  Path (3 cities): #{route.to_wkb.bytesize} bytes"
+puts "  hex: #{route.to_wkb_hex[0..60]}..."
+puts
+
+triangle = 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)
+])
+poly_wkb = triangle.to_wkb(as: :polygon)
+puts "  Path as polygon: #{poly_wkb.bytesize} bytes"
+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_wkb.bytesize} bytes"
+
+circle = Areas::Circle.new(centroid: seattle, radius: 10_000)
+puts "  Circle (32-gon): #{circle.to_wkb.bytesize} bytes"
+puts "  Circle (8-gon):  #{circle.to_wkb(segments: 8).bytesize} bytes"
+
+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_wkb.bytesize} bytes"
+puts
+
+# ── 5. Feature delegates ───────────────────────────────────────────
+
+puts "--- 5. Feature → delegates to geometry ---"
+puts
+
+city = Feature.new(label: "Seattle", geometry: seattle, metadata: { pop: 750_000 })
+puts "  Feature('Seattle').to_wkb_hex"
+puts "  => #{city.to_wkb_hex}"
+puts "  (WKB has no properties; label/metadata are lost)"
+puts
+
+# ── 6. SRID / EWKB ─────────────────────────────────────────────────
+
+puts "--- 6. SRID / EWKB ---"
+puts
+
+puts "  POINT with SRID=4326:"
+puts "  => #{seattle.to_wkb_hex(srid: 4326)}"
+
+puts "  LINESTRING with SRID=4326:"
+puts "  => #{seg.to_wkb_hex(srid: 4326)}"
+puts
+
+# ── 7. Z-dimension consistency ──────────────────────────────────────
+
+puts "--- 7. Z-dimension consistency ---"
+puts
+
+sf_alt = LLA.new(lat: 37.7749, lng: -122.4194, alt: 100.0)
+mixed = Geodetic::Segment.new(seattle, sf_alt)
+puts "  seattle (alt=0) + sf (alt=100):"
+puts "  Type code: #{mixed.to_wkb[1, 4].unpack1("V")} (1002 = LineString Z)"
+puts "  Both points get Z even though seattle has alt=0"
+puts
+
+no_alt = Geodetic::Segment.new(seattle, portland)
+puts "  seattle + portland (both alt=0):"
+puts "  Type code: #{no_alt.to_wkb[1, 4].unpack1("V")} (2 = LineString)"
+puts
+
+# ── 8. Parsing WKB ─────────────────────────────────────────────────
+
+puts "--- 8. Parsing WKB ---"
+puts
+
+hex_samples = {
+  "POINT(1 2)"       => "0101000000000000000000f03f0000000000000040",
+  "LINESTRING(1..4)" => "010200000002000000000000000000f03f000000000000004000000000000008400000000000001040",
+  "POLYGON"          => "01030000000100000004000000000000000000f03f00000000000000400000000000000840000000000000104000000000000014400000000000001840000000000000f03f0000000000000040",
+  "MULTIPOINT"       => "0104000000020000000101000000000000000000f03f0000000000000040010100000000000000000008400000000000001040",
+  "GEOM_COLLECTION"  => "0107000000020000000101000000000000000000f03f0000000000000040010200000002000000000000000000f03f000000000000004000000000000008400000000000001040"
+}
+
+hex_samples.each do |label, hex|
+  result = WKB.parse(hex)
+  if result.is_a?(Array)
+    puts "  #{label.ljust(18)} → [#{result.map { |r| r.class.name.split('::').last }.join(', ')}]"
+  else
+    puts "  #{label.ljust(18)} → #{result.class.name.split('::').last}"
+  end
+end
+puts
+
+# Parse EWKB
+obj, srid = WKB.parse_with_srid("0101000020e61000008a1f63ee5a965ec08195438b6ccf4740")
+puts "  EWKB → #{obj.class.name.split('::').last}(#{obj.to_s(4)}), SRID=#{srid}"
+puts
+
+# Parse binary directly
+binary = seattle.to_wkb
+parsed = WKB.parse(binary)
+puts "  Binary parse → #{parsed.class.name.split('::').last}(#{parsed.to_s(4)})"
+puts
+
+# ── 9. Roundtrip ───────────────────────────────────────────────────
+
+puts "--- 9. Roundtrip (encode → parse → re-encode) ---"
+puts
+
+objects = {
+  "POINT"      => seattle,
+  "POINT Z"    => space_needle,
+  "LINESTRING" => Geodetic::Segment.new(seattle, portland),
+  "PATH"       => Path.new(coordinates: [seattle, portland, sf]),
+  "POLYGON"    => poly,
+  "BBOX"       => bbox,
+  "SRID"       => seattle
+}
+
+objects.each do |label, obj|
+  srid_val = label == "SRID" ? 4326 : nil
+  original = obj.to_wkb_hex(srid: srid_val)
+
+  if srid_val
+    parsed, parsed_srid = WKB.parse_with_srid(original)
+    roundtrip = parsed.to_wkb_hex(srid: parsed_srid)
+  else
+    parsed = WKB.parse(original)
+    roundtrip = parsed.to_wkb_hex
+  end
+
+  match = original == roundtrip ? "MATCH" : "DIFF"
+  puts "  #{label.ljust(12)} #{match}  #{original.length} hex chars"
+end
+puts
+
+# ── 10. File I/O ───────────────────────────────────────────────────
+
+puts "--- 10. File I/O ---"
+puts
+
+# Binary format
+bin_path = File.join(__dir__, "geodetic_demo.wkb")
+save_objects = [seattle, space_needle, seg, poly, bbox]
+WKB.save!(bin_path, save_objects)
+puts "  Binary: saved #{save_objects.length} objects to #{bin_path}"
+puts "  File size: #{File.size(bin_path)} bytes"
+
+loaded = WKB.load(bin_path)
+puts "  Loaded #{loaded.length} objects:"
+loaded.each do |obj|
+  puts "    #{obj.class.name.split('::').last} (#{obj.to_wkb.bytesize} bytes)"
+end
+puts
+
+# Hex format
+hex_path = File.join(__dir__, "geodetic_demo_output.wkb.hex")
+WKB.save_hex!(hex_path, save_objects)
+puts "  Hex: saved #{save_objects.length} objects to #{hex_path}"
+puts "  File contents:"
+File.readlines(hex_path, chomp: true).each_with_index do |line, i|
+  puts "    #{i + 1}: #{line[0..60]}#{"..." if line.length > 60}"
+end
+puts
+
+hex_loaded = WKB.load_hex(hex_path)
+puts "  Loaded #{hex_loaded.length} objects from hex file"
+puts
+
+# Roundtrip verification
+puts "  File roundtrip check:"
+save_objects.zip(loaded).each_with_index do |(orig, back), i|
+  match = orig.to_wkb_hex == back.to_wkb_hex ? "MATCH" : "DIFF"
+  puts "    object #{i + 1}: #{match}"
+end
+puts
+
+# Load the fixture files
+fixture_bin = File.join(__dir__, "sample_geometries.wkb")
+if File.exist?(fixture_bin)
+  fixture_objects = WKB.load(fixture_bin)
+  puts "  Fixture binary: loaded #{fixture_objects.length} geometries from sample_geometries.wkb"
+end
+
+fixture_hex = File.join(__dir__, "sample_geometries.wkb.hex")
+if File.exist?(fixture_hex)
+  hex_objects = WKB.load_hex(fixture_hex)
+  puts "  Fixture hex:    loaded #{hex_objects.length} geometries from sample_geometries.wkb.hex"
+end
+puts
+
+puts "=== Done ==="

data/examples/12_geos_benchmark.rb

@@ -0,0 +1,258 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# GEOS Performance Benchmark
+#
+# Compares pure Ruby spatial operations against GEOS-accelerated versions.
+# Uses GEODETIC_GEOS_DISABLE env var to force Ruby-only execution, then
+# runs the same operations with GEOS enabled.
+#
+# Requires: brew install geos
+# Run:      ruby -Ilib examples/12_geos_benchmark.rb
+
+require_relative '../lib/geodetic'
+require 'benchmark'
+
+LLA     = Geodetic::Coordinate::LLA
+Polygon = Geodetic::Areas::Polygon
+Path    = Geodetic::Path
+Segment = Geodetic::Segment
+Geos    = Geodetic::Geos
+
+unless Geos::LibGEOS.available?
+  abort "libgeos_c not found. Install with: brew install geos"
+end
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+def make_polygon(n_vertices, center_lat: 40.0, center_lng: -74.0, radius_deg: 1.0)
+  step = 360.0 / n_vertices
+  boundary = n_vertices.times.map do |i|
+    angle = i * step * Geodetic::RAD_PER_DEG
+    LLA.new(
+      lat: center_lat + radius_deg * Math.sin(angle),
+      lng: center_lng + radius_deg * Math.cos(angle),
+      alt: 0.0
+    )
+  end
+  Polygon.new(boundary: boundary)
+end
+
+def make_path(n_points, start_lat: 40.0, start_lng: -74.0, step_deg: 0.01, zigzag: 0.001)
+  coords = n_points.times.map do |i|
+    LLA.new(
+      lat: start_lat + (i.even? ? zigzag : -zigzag),
+      lng: start_lng + i * step_deg,
+      alt: 0.0
+    )
+  end
+  Path.new(coordinates: coords)
+end
+
+def section(title)
+  puts
+  puts "=" * 70
+  puts title
+  puts "=" * 70
+end
+
+def speedup(ruby_time, geos_time)
+  return "N/A" if geos_time == 0
+  ratio = ruby_time / geos_time
+  format("%.1fx", ratio)
+end
+
+# ---------------------------------------------------------------------------
+# Collect timings for Ruby-only vs GEOS
+# ---------------------------------------------------------------------------
+
+results = []
+
+# --- 1. Polygon validation ------------------------------------------------
+
+section "1. POLYGON VALIDATION"
+puts "   Ruby uses O(n^2) pairwise segment tests."
+puts "   GEOS uses an O(n log n) spatial index."
+
+[50, 100, 500].each do |n|
+  boundary = n.times.map do |i|
+    angle = i * (360.0 / n) * Geodetic::RAD_PER_DEG
+    LLA.new(lat: 40.0 + Math.sin(angle), lng: -74.0 + Math.cos(angle), alt: 0.0)
+  end
+  iterations = n <= 100 ? 500 : 50
+
+  puts "\n  #{n} vertices, #{iterations} iterations:"
+
+  # Ruby-only (disable GEOS)
+  ENV['GEODETIC_GEOS_DISABLE'] = '1'
+  ruby_time = Benchmark.realtime do
+    iterations.times { Polygon.new(boundary: boundary.dup) }
+  end
+
+  # GEOS-enabled
+  ENV.delete('GEODETIC_GEOS_DISABLE')
+  geos_time = Benchmark.realtime do
+    iterations.times { Polygon.new(boundary: boundary.dup) }
+  end
+
+  puts format("    Ruby:  %8.4fs", ruby_time)
+  puts format("    GEOS:  %8.4fs  (%s faster)", geos_time, speedup(ruby_time, geos_time))
+  results << { test: "Validation #{n}v", ruby: ruby_time, geos: geos_time }
+end
+
+# --- 2. Point-in-polygon --------------------------------------------------
+
+section "2. POINT-IN-POLYGON"
+puts "   Ruby uses winding-number with bearing calculations."
+puts "   GEOS uses computational geometry contains test."
+puts "   Threshold: polygons with >= #{Polygon::GEOS_INCLUDES_THRESHOLD} vertices use GEOS."
+
+test_point = LLA.new(lat: 40.0, lng: -74.0, alt: 0.0)
+
+[8, 30, 100, 500].each do |n|
+  polygon = make_polygon(n)
+  iterations = n <= 100 ? 5_000 : 1_000
+
+  above = n >= Polygon::GEOS_INCLUDES_THRESHOLD
+  label = above ? "GEOS" : "Ruby (below threshold)"
+  puts "\n  #{n} vertices -> #{label}, #{iterations} iterations:"
+
+  ENV['GEODETIC_GEOS_DISABLE'] = '1'
+  ruby_time = Benchmark.realtime do
+    iterations.times { polygon.includes?(test_point) }
+  end
+
+  ENV.delete('GEODETIC_GEOS_DISABLE')
+  geos_time = Benchmark.realtime do
+    iterations.times { polygon.includes?(test_point) }
+  end
+
+  puts format("    Ruby:  %8.4fs", ruby_time)
+  puts format("    GEOS:  %8.4fs  (%s faster)", geos_time, speedup(ruby_time, geos_time))
+  results << { test: "Includes #{n}v", ruby: ruby_time, geos: geos_time }
+end
+
+# --- 3. Path intersection -------------------------------------------------
+
+section "3. PATH INTERSECTION"
+puts "   Ruby uses O(n*m) pairwise segment tests."
+puts "   GEOS uses spatial indexing for fast intersection."
+puts "   Non-intersecting paths with overlapping bounds (worst case for Ruby)."
+
+[100, 500, 1000].each do |n|
+  # Two zigzag paths: bounds overlap but segments don't cross.
+  # Ruby must check all O(n*m) segment pairs before returning false.
+  path1 = make_path(n, start_lat: 40.0, zigzag: 0.05)
+  path2 = make_path(n, start_lat: 40.08, zigzag: 0.05)
+  iterations = [5000 / n, 5].max
+
+  puts "\n  #{n} points per path, #{iterations} iterations:"
+
+  ENV['GEODETIC_GEOS_DISABLE'] = '1'
+  ruby_time = Benchmark.realtime do
+    iterations.times { path1.intersects?(path2) }
+  end
+
+  ENV.delete('GEODETIC_GEOS_DISABLE')
+  geos_time = Benchmark.realtime do
+    iterations.times { path1.intersects?(path2) }
+  end
+
+  puts format("    Ruby:  %8.4fs", ruby_time)
+  puts format("    GEOS:  %8.4fs  (%s faster)", geos_time, speedup(ruby_time, geos_time))
+  results << { test: "Path intersect #{n}pt", ruby: ruby_time, geos: geos_time }
+end
+
+# --- 4. Batch containment with PreparedGeometry ----------------------------
+
+section "4. BATCH CONTAINMENT (PreparedGeometry)"
+puts "   Testing 1,000 random points against a 100-vertex polygon."
+puts "   PreparedGeometry builds a spatial index once, then queries are O(log n)."
+
+srand(42) # reproducible random points
+polygon = make_polygon(100)
+test_points = 1_000.times.map do
+  LLA.new(lat: 39.0 + rand * 2.0, lng: -75.0 + rand * 2.0, alt: 0.0)
+end
+
+ENV['GEODETIC_GEOS_DISABLE'] = '1'
+ruby_time = Benchmark.realtime do
+  test_points.each { |pt| polygon.includes?(pt) }
+end
+
+ENV.delete('GEODETIC_GEOS_DISABLE')
+geos_one_shot_time = Benchmark.realtime do
+  test_points.each { |pt| polygon.includes?(pt) }
+end
+
+prepared_time = Benchmark.realtime do
+  prepared = Geos.prepare(polygon)
+  test_points.each { |pt| prepared.contains?(pt) }
+  prepared.release
+end
+
+puts format("\n    Ruby:          %8.4fs", ruby_time)
+puts format("    GEOS one-shot: %8.4fs  (%s faster)", geos_one_shot_time, speedup(ruby_time, geos_one_shot_time))
+puts format("    GEOS prepared: %8.4fs  (%s faster)", prepared_time, speedup(ruby_time, prepared_time))
+results << { test: "Batch 1k points", ruby: ruby_time, geos: prepared_time }
+
+# --- 5. Segment intersection (Ruby wins) ----------------------------------
+
+section "5. SINGLE SEGMENT INTERSECTION (Ruby wins here)"
+puts "   For trivial operations, FFI overhead exceeds the computation cost."
+puts "   Geodetic correctly keeps Ruby for this case."
+
+seg1 = Segment.new(
+  LLA.new(lat: 0.0, lng: 0.0, alt: 0.0),
+  LLA.new(lat: 2.0, lng: 2.0, alt: 0.0)
+)
+seg2 = Segment.new(
+  LLA.new(lat: 0.0, lng: 2.0, alt: 0.0),
+  LLA.new(lat: 2.0, lng: 0.0, alt: 0.0)
+)
+iterations = 50_000
+
+ruby_time = Benchmark.realtime { iterations.times { seg1.intersects?(seg2) } }
+geos_time = Benchmark.realtime { iterations.times { Geos.intersects?(seg1, seg2) } }
+
+puts format("\n    Ruby:  %8.4fs", ruby_time)
+puts format("    GEOS:  %8.4fs  (Ruby is %s faster)", geos_time, speedup(geos_time, ruby_time))
+
+# --- 6. GEOS-only operations ----------------------------------------------
+
+section "6. GEOS-ONLY OPERATIONS (no Ruby equivalent)"
+puts "   These capabilities are only available when GEOS is installed."
+
+poly_a = make_polygon(100, center_lat: 40.0, center_lng: -74.0, radius_deg: 1.0)
+poly_b = make_polygon(100, center_lat: 40.5, center_lng: -73.5, radius_deg: 1.0)
+iterations = 500
+
+puts "\n  Two 100-vertex polygons, #{iterations} iterations each:"
+Benchmark.bm(22) do |x|
+  x.report("  intersection")    { iterations.times { Geos.intersection(poly_a, poly_b) } }
+  x.report("  difference")      { iterations.times { Geos.difference(poly_a, poly_b) } }
+  x.report("  symmetric_diff")  { iterations.times { Geos.symmetric_difference(poly_a, poly_b) } }
+  x.report("  convex_hull")     { iterations.times { Geos.convex_hull(poly_a) } }
+  x.report("  simplify(0.01)")  { iterations.times { Geos.simplify(poly_a, 0.01) } }
+  x.report("  is_valid?")       { iterations.times { Geos.is_valid?(poly_a) } }
+  x.report("  area")            { iterations.times { Geos.area(poly_a) } }
+  x.report("  nearest_points")  { iterations.times { Geos.nearest_points(poly_a, poly_b) } }
+end
+
+# --- Summary ---------------------------------------------------------------
+
+section "SUMMARY"
+puts
+puts format("  %-25s %10s %10s %10s", "Test", "Ruby", "GEOS", "Speedup")
+puts "  " + "-" * 57
+
+results.each do |r|
+  puts format("  %-25s %9.4fs %9.4fs %10s",
+    r[:test], r[:ruby], r[:geos], speedup(r[:ruby], r[:geos]))
+end
+
+puts
+puts "  Note: GEOS acceleration is automatic when libgeos_c is installed."
+puts "  Set GEODETIC_GEOS_DISABLE=1 to force pure Ruby for all operations."