geodetic 0.5.2 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 44b5221a45f63382e712aa88d033d1cb0b8165f8804833a1fd8523a9d7d8ce32
-  data.tar.gz: 787dc88782b277262e15dde4fa1f61801894d1d34eff304dc63965147a3b10e8
+  metadata.gz: 0c20a680d6ffe0e6a82f3a0b7e8f6b1a428baa951b7122c0be75079f667f1099
+  data.tar.gz: 28031d89b1a5705cc28f6ddc751034d982e51581544f44a1d46a8792d8fd0f50
 SHA512:
-  metadata.gz: ffb91f043c3c0c9a2bb6b44fad7952936121a09b18879350398cf260fd2be1f594f33c405df7cea0027f59c0e06679f1d4f718192d7626032a4b5fab195626f9
-  data.tar.gz: dd922521aa23db80a5d9fdf56dbb98dcdfab811f72a126978d9b8dffe248f72f3dd83c3cae1e41d3ee2a1cf11455d70120d6c81fff7523f3aac798397250fbca
+  metadata.gz: 4c41de7eb8e8bdb61921dfca83310a2d5ed0978d9bd6f0f1d3f06ce33bd877070581c873396a33b80b40722ec741f93f5e80cf2afb0e90561f5a28d2dc6e7953
+  data.tar.gz: 8ce010a527e660a01fab3b93d8a9e4f90bceb688dd753a5a634cbf3d25ba3deaf2b8bc8038e8926767d8bd017a26e09074aa3be1d94df1813bc6407d56865ab0

data/CHANGELOG.md

@@ -8,6 +8,81 @@ 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
+
+- **`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,9 @@
 - <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>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>
@@ -63,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
@@ -769,6 +792,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 +892,10 @@ 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 |
+| [`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/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/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.