geodetic 0.6.0 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7e34b06e1bf493a580a70871173cab9e79b442c1667a1d68e9b9b2cd6181b660
-  data.tar.gz: 3d7cdabbff9c142ae61812dfec12d92cf764cc85cf31458c41226d4f00cc19a2
+  metadata.gz: 0c20a680d6ffe0e6a82f3a0b7e8f6b1a428baa951b7122c0be75079f667f1099
+  data.tar.gz: 28031d89b1a5705cc28f6ddc751034d982e51581544f44a1d46a8792d8fd0f50
 SHA512:
-  metadata.gz: a8c06b5625fcbb2df864e913ec687f0075c971ff91910a295bfe112ab645bca2174b7d01e32cb9ef03aa9cad05311cfdee7c00572f629d9c4a5b26af70604d3e
-  data.tar.gz: 3a9e274d50a491b2b1b1791402e4e5ff5c52f2be2cf172162fadc8d246ef64cf8bc410bb7eb869b1c3d1748cbaa33eb4d7e7cddaf503f6a191fcac09b9c93024
+  metadata.gz: 4c41de7eb8e8bdb61921dfca83310a2d5ed0978d9bd6f0f1d3f06ce33bd877070581c873396a33b80b40722ec741f93f5e80cf2afb0e90561f5a28d2dc6e7953
+  data.tar.gz: 8ce010a527e660a01fab3b93d8a9e4f90bceb688dd753a5a634cbf3d25ba3deaf2b8bc8038e8926767d8bd017a26e09074aa3be1d94df1813bc6407d56865ab0

data/CHANGELOG.md

@@ -8,6 +8,42 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## [Unreleased]
 
 
+## [0.7.0] - 2026-03-10
+
+### Added
+
+- **`Geodetic::Geos` module** — optional GEOS C library integration via `fiddle` for accelerated spatial operations
+  - **Library binding**: auto-discovers `libgeos_c` on macOS and Linux; uses reentrant `_r` API for thread safety
+  - **Predicates**: `Geos.contains?(a, b)`, `Geos.intersects?(a, b)`, `Geos.is_valid?(geom)`, `Geos.is_valid_reason(geom)`
+  - **Boolean operations**: `Geos.intersection(a, b)`, `Geos.difference(a, b)`, `Geos.symmetric_difference(a, b)`, `Geos.union(geom)`
+  - **Geometry construction**: `Geos.buffer(geom, distance)`, `Geos.buffer_with_style(geom, distance, ...)`, `Geos.convex_hull(geom)`, `Geos.simplify(geom, tolerance)`, `Geos.make_valid(geom)`
+  - **Measurements**: `Geos.area(geom)`, `Geos.length(geom)`, `Geos.distance(a, b)`, `Geos.nearest_points(a, b)`
+  - **`PreparedGeometry`**: `Geos.prepare(polygon)` builds a spatial index for O(log n) batch `contains?`/`intersects?` queries
+  - **Graceful degradation**: `Geos.available?` returns false when `libgeos_c` is not installed; all operations fall back to pure Ruby
+  - **`GEODETIC_GEOS_DISABLE` env var**: forces pure Ruby for all operations even when GEOS is installed
+  - **`LIBGEOS_PATH` env var**: specify a custom `libgeos_c` library path
+  - All GEOS operations accept any Geodetic geometry type and return standard Geodetic objects (Polygon, Path, LLA, etc.)
+- **GEOS-accelerated polygon validation** — `Polygon.new` delegates self-intersection validation to GEOS when available, using O(n log n) spatial indexing vs Ruby's O(n^2) pairwise test
+- **GEOS-accelerated point-in-polygon** — `polygon.includes?(point)` uses GEOS for polygons with 15+ vertices (`Polygon::GEOS_INCLUDES_THRESHOLD`); below threshold, Ruby's winding-number algorithm is faster
+- **GEOS-accelerated path intersection** — `path.intersects?(other_path)` uses GEOS when available (wins at all tested sizes vs Ruby's O(n*m) brute-force)
+- **Improved Ruby polygon validation** — added `validate_distinct_vertices!` and `validate_noncollinear!` checks so pure Ruby matches GEOS accuracy for degenerate polygons
+- GEOS benchmark example (`examples/12_geos_benchmark.rb`) — compares Ruby vs GEOS performance across polygon validation, point-in-polygon, path intersection, PreparedGeometry batch containment, single segment (Ruby wins), and GEOS-only operations
+- GEOS operations example (`examples/13_geos_operations.rb`) — 11-section demo covering boolean overlay, buffering, convex hull, simplification, validity checking, geometry repair, planar measurements, nearest points, PreparedGeometry, operation chaining, and GeoJSON/WKT export of results
+- 27 GEOS tests covering all operations, predicates, PreparedGeometry, and error handling
+- 3 new polygon validation tests: collinear boundary, insufficient distinct vertices, all-same-point
+- Documentation: `docs/reference/geos-acceleration.md` (installation, automatic dispatch, performance expectations, API reference)
+
+### Changed
+
+- Updated README with GEOS Acceleration feature, optional dependency section, and examples 12-13 in the examples table
+- Updated `examples/README.md` with example 12 and 13 descriptions
+- Updated `examples/sample_geometries.wkb.hex` to use valid (non-degenerate) triangles in polygon entries
+
+### Fixed
+
+- WKB test data used collinear triangle `(1,2)-(3,4)-(5,6)` which is now correctly rejected; updated to valid triangle `(1,2)-(3,4)-(5,2)`
+- Polygon validation error message regex in tests updated to match both Ruby and GEOS formats
+
 ## [0.6.0] - 2026-03-10
 
 ### Added

data/README.md

@@ -27,6 +27,7 @@
 - <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>GEOS Acceleration</strong> - Optional native acceleration for polygon validation, point-in-polygon, path intersection, and boolean operations<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>
@@ -65,6 +66,26 @@ brew install h3
 
 You can also set the `LIBH3_PATH` environment variable to point to a custom `libh3` location.
 
+### Optional: GEOS Spatial Acceleration
+
+The [GEOS](https://libgeos.org/) library accelerates polygon validation, point-in-polygon tests, path intersection, and adds boolean geometry operations (intersection, difference, convex hull, etc.). Without it, all operations use pure Ruby implementations. Geodetic automatically uses GEOS when available and falls back to Ruby when it is not.
+
+```bash
+# macOS
+brew install geos
+
+# Linux (Debian/Ubuntu)
+sudo apt-get install libgeos-dev
+```
+
+Geodetic uses GEOS selectively — only where it provides a measurable speedup. Single segment intersections stay in Ruby (FFI overhead exceeds the computation cost). For polygons with fewer than 15 vertices, point-in-polygon tests also stay in Ruby.
+
+Set `GEODETIC_GEOS_DISABLE=1` to force pure Ruby for all operations, even when GEOS is installed. See [GEOS Acceleration](docs/reference/geos-acceleration.md) for detailed performance analysis and [example 12](examples/12_geos_benchmark.rb) for a runnable benchmark.
+
+```ruby
+Geodetic::Geos.available?  # => true when libgeos_c is found and not disabled
+```
+
 ## Usage
 
 ### Basic Coordinate Creation
@@ -873,6 +894,8 @@ The [`examples/`](examples/) directory contains runnable demo scripts showing pr
 | [`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 |
+| [`12_geos_benchmark.rb`](examples/12_geos_benchmark.rb) | GEOS performance benchmark: polygon validation, point-in-polygon, path intersection, PreparedGeometry batch containment, and GEOS-only boolean operations |
+| [`13_geos_operations.rb`](examples/13_geos_operations.rb) | GEOS-only operations: boolean overlay (intersection, difference, symmetric difference, union), buffering, convex hull, simplification, validity checking, geometry repair, planar measurements, nearest points, PreparedGeometry, and operation chaining |
 
 Run any example with:
 

data/docs/reference/geos-acceleration.md

@@ -0,0 +1,170 @@
+# GEOS Acceleration
+
+Geodetic optionally integrates with the [GEOS](https://libgeos.org/) (Geometry Engine - Open Source) C library to accelerate spatial operations. When `libgeos_c` is available, Geodetic transparently delegates performance-critical geometry operations to GEOS while keeping pure Ruby as the fallback.
+
+## Installation
+
+```bash
+# macOS
+brew install geos
+
+# Linux (Debian/Ubuntu)
+sudo apt-get install libgeos-dev
+
+# Linux (Fedora/RHEL)
+sudo dnf install geos-devel
+```
+
+Verify installation:
+
+```ruby
+require "geodetic"
+Geodetic::Geos.available?  # => true
+```
+
+## How It Works
+
+Geodetic uses Ruby's `fiddle` stdlib (the same approach used for H3) to call the GEOS C API directly — no compiled extensions or external gems required. The integration uses the reentrant `_r` API for thread safety.
+
+The bridge works through WKT serialization:
+
+1. Geodetic objects are converted to WKT via `to_wkt`
+2. GEOS parses the WKT into its internal geometry representation
+3. GEOS performs the operation using optimized C code with spatial indexing
+4. Results are converted back to WKT and parsed into Geodetic objects
+
+This approach keeps the integration simple and maintainable while providing significant performance gains for complex geometries.
+
+## Automatic Dispatch
+
+Geodetic selectively uses GEOS only where it provides a measurable speedup. The dispatch logic is built into the existing classes:
+
+### Polygon Validation
+
+`Polygon.new(boundary: [...])` automatically validates the boundary for self-intersection. GEOS uses an O(n log n) spatial index compared to Ruby's O(n^2) pairwise segment test.
+
+- GEOS is used at **all polygon sizes** when available
+- Speedup grows with vertex count: ~2x at 50 vertices, ~5x at 100, ~50x+ at 500
+
+### Point-in-Polygon
+
+`polygon.includes?(point)` tests whether a point lies inside a polygon.
+
+- GEOS is used for polygons with **15 or more vertices** (`Polygon::GEOS_INCLUDES_THRESHOLD`)
+- Below 15 vertices, Ruby's winding-number algorithm is faster (FFI overhead dominates)
+- Above the threshold, GEOS provides 2-10x speedup depending on polygon complexity
+
+### Path Intersection
+
+`path.intersects?(other_path)` tests whether two paths cross.
+
+- GEOS is **always used** when available (wins at all tested sizes)
+- Ruby uses O(n*m) brute-force segment pair testing
+- GEOS uses spatial indexing for efficient intersection detection
+- Speedup is most dramatic for non-intersecting paths with overlapping bounds (worst case for Ruby): 10x at 100 points, 100x+ at 1000 points
+
+### Where Ruby Wins
+
+Single segment intersection (`segment.intersects?(other_segment)`) stays in pure Ruby at all times. The FFI marshaling overhead for a single pair of line segments exceeds the computation cost. Geodetic does not use GEOS for this operation.
+
+## PreparedGeometry
+
+For batch operations (testing many points against the same polygon), `PreparedGeometry` builds a spatial index once and reuses it for O(log n) queries:
+
+```ruby
+polygon = Geodetic::Areas::Polygon.new(boundary: vertices)
+prepared = Geodetic::Geos.prepare(polygon)
+
+points.each do |pt|
+  prepared.contains?(pt)  # O(log n) per query
+end
+
+prepared.release  # free the GEOS geometry
+```
+
+This is significantly faster than calling `polygon.includes?` in a loop, which creates a new GEOS geometry for each call.
+
+## GEOS-Only Operations
+
+GEOS provides operations that have no pure Ruby equivalent in Geodetic:
+
+```ruby
+Geos = Geodetic::Geos
+
+# Boolean operations — return Geodetic objects
+Geos.intersection(poly_a, poly_b)        # area of overlap
+Geos.difference(poly_a, poly_b)          # A minus B
+Geos.symmetric_difference(poly_a, poly_b) # area in either but not both
+
+# Geometry analysis
+Geos.convex_hull(polygon)                # smallest convex polygon
+Geos.simplify(polygon, tolerance)        # Douglas-Peucker simplification
+Geos.make_valid(polygon)                 # repair invalid geometry
+Geos.is_valid?(polygon)                  # OGC validity check
+Geos.is_valid_reason(polygon)            # human-readable validity reason
+
+# Measurements
+Geos.area(polygon)                       # area in coordinate units
+Geos.length(path)                        # length in coordinate units
+Geos.distance(geom_a, geom_b)           # minimum distance
+
+# Spatial relationships
+Geos.nearest_points(geom_a, geom_b)     # closest point pair
+Geos.contains?(polygon, point)          # containment test
+Geos.intersects?(geom_a, geom_b)        # intersection test
+
+# Buffering
+Geos.buffer(geometry, width)            # buffer zone
+Geos.buffer_with_style(geometry, width, quad_segs:, cap_style:, join_style:)
+```
+
+## Disabling GEOS
+
+Set the `GEODETIC_GEOS_DISABLE` environment variable to force pure Ruby for all operations:
+
+```bash
+GEODETIC_GEOS_DISABLE=1 ruby -Ilib my_script.rb
+```
+
+```ruby
+ENV['GEODETIC_GEOS_DISABLE'] = '1'
+Geodetic::Geos.available?  # => false (even when libgeos_c is installed)
+```
+
+This is useful for:
+
+- Benchmarking Ruby vs GEOS performance (see example 12)
+- Debugging to isolate whether an issue is in GEOS or Ruby code
+- Running in environments where GEOS cannot be installed
+
+## Performance Expectations
+
+The following table shows representative speedups measured with [example 12](../../examples/12_geos_benchmark.rb). Actual results vary by hardware and polygon complexity.
+
+| Operation | Size | Typical Speedup |
+|-----------|------|-----------------|
+| Polygon validation | 50 vertices | ~2x |
+| Polygon validation | 100 vertices | ~5x |
+| Polygon validation | 500 vertices | ~50x |
+| Point-in-polygon | 30 vertices | ~2x |
+| Point-in-polygon | 100 vertices | ~5x |
+| Point-in-polygon | 500 vertices | ~10x |
+| Path intersection | 100 points | ~10x |
+| Path intersection | 500 points | ~50x |
+| Path intersection | 1000 points | ~100x |
+| Batch containment (prepared) | 1000 points × 100v | ~20x |
+| Single segment | 2 points | Ruby is ~2x faster |
+
+Run the benchmark yourself:
+
+```bash
+ruby -Ilib examples/12_geos_benchmark.rb
+```
+
+## Architecture Notes
+
+- **Thread safety**: Uses the reentrant GEOS `_r` API with per-process context initialization
+- **No compiled extensions**: Uses `fiddle` from Ruby's stdlib, same pattern as the H3 integration
+- **Graceful degradation**: All operations work without GEOS; it is purely an optimization
+- **WKT bridge**: Geometries are serialized to WKT for transfer between Ruby and GEOS, leveraging Geodetic's existing WKT infrastructure
+- **Memory management**: GEOS geometries and readers/writers are properly freed via `GEOSGeom_destroy_r`, `GEOSWKTReader_destroy_r`, etc.

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."