geodetic 0.4.0 → 0.5.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f85da37953a9e974422502d62fbf82279fcf4f0ff71594ada2bb150e07cc75d1
-  data.tar.gz: a986282c09df583d9de453034f36e1a15c0d29cc016f586f09239f4f642d6fae
+  metadata.gz: 82e74456b38ec9c888ee70e68de3e626f0333b9f791c8de7779f5aa544cbbbc7
+  data.tar.gz: a76e9a726d4a503f0e2331f321de25a3b7c155e8712a27a18c53ba8e5ab27953
 SHA512:
-  metadata.gz: 2d72a9b0e9e1a0688f25659dbff3d35e8b1c001c72468d2d2bd5c64ffe9fd2f16315dbbe4ec429c545115268e7486db81b26c4f6c9d625de3a8089b82cbcf8df
-  data.tar.gz: 031eb9604c27d9683c74bf3483b913a5ddb065ed78bd5375f23297f39b923f5a6212498c236982a310afe25fa5ca300df0dfaaa60d8632ad02950c75c2662e15
+  metadata.gz: 4bd3b6a3c7664f9f0b20c7bd5c9cee52d80528fe91f97d5a9d2a8a48c9f8314d34027f50ba3b091581650965721e8275b268564ac6fb203fdc896c1f7fa25fa4
+  data.tar.gz: f7d83378049a016a388e2f8b4130179e7166704e20b10525a6f5c5a88a12a8812b703fe484dbfd8c40d7af7d8e6ddda7a903052575ea52b48a169c1ebff3fd8d

data/CHANGELOG.md

@@ -1,8 +1,5 @@
 # Changelog
 
-> [!CAUTION]
-> This gem is under active development. APIs and features may change without notice.
-
 All notable changes to this project will be documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
@@ -11,6 +8,88 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## [Unreleased]
 
 
+## [0.5.1] - 2026-03-10
+
+### Added
+
+- **`Geodetic::GeoJSON` class** — build GeoJSON FeatureCollections from any mix of Geodetic objects
+  - **Constructor**: `GeoJSON.new`, `GeoJSON.new(obj, ...)`, `GeoJSON.new([array])`
+  - **Accumulate**: `<<` accepts single objects or arrays; returns `self` for chaining
+  - **Query**: `size`/`length`, `empty?`, `each`, and all `Enumerable` methods
+  - **Remove**: `delete(obj)`, `clear`
+  - **Export**: `to_h` (Ruby Hash), `to_json`/`to_json(pretty: true)` (JSON string), `save(path, pretty: false)` (file output)
+  - Non-Feature objects auto-wrapped as GeoJSON Features with empty properties
+  - Feature objects carry `label` → `"name"` and `metadata` → `properties`
+- **`to_geojson` instance method** on all geometry types:
+  - All 18 coordinate classes → GeoJSON Point (via LLA; altitude included when non-zero)
+  - `Segment` → GeoJSON LineString (2 positions)
+  - `Path` → GeoJSON LineString (default) or Polygon (`as: :polygon`, auto-closes ring)
+  - `Areas::Polygon` and subclasses → GeoJSON Polygon
+  - `Areas::Circle` → GeoJSON Polygon (N-gon approximation, default 32 segments, configurable via `segments:`)
+  - `Areas::BoundingBox` → GeoJSON Polygon (4 corners, right-hand rule ring order)
+  - `Feature` → GeoJSON Feature with geometry and properties
+  - ENU/NED raise `ArgumentError` (relative systems require conversion first)
+- GeoJSON export example (`examples/09_geojson_export.rb`) — 10-section demo covering `to_geojson` on all geometry types, FeatureCollection building, delete/clear, Enumerable, and file export
+- Documentation: `docs/reference/geojson.md` (GeoJSON Export reference)
+
+### Fixed
+
+- Corrected stale numeric values in documentation:
+  - Seattle→Portland distance: 235393.17 → 235385.71 m (README, `docs/reference/conversions.md`)
+  - Seattle→Portland bearing: 188.2° → 186.25° (README, `docs/reference/conversions.md`, `docs/reference/arithmetic.md`)
+  - Seattle→Portland miles: 146.28 → 146.26 (README)
+  - Liberty→Empire bearing: 36.99° → 36.95° (README, `docs/reference/feature.md`)
+- Fixed `docs/index.md` Key Features list to include all 18 coordinate systems (was missing GEOREF, GARS, H3)
+
+### Changed
+
+- Updated README with GeoJSON Export section, key features bullet, and example 09 in the examples table
+- Updated `docs/index.md` with GeoJSON Export in key features and reference links
+- Updated `examples/README.md` with example 09 description
+
+## [0.5.0] - 2026-03-10
+
+### Added
+
+- **`Geodetic::Vector` class** — geodetic displacement pairing a Distance (magnitude) with a Bearing (direction)
+  - **Construction**: `Vector.new(distance:, bearing:)` with automatic coercion from numeric values
+  - **Components**: `north`, `east` — decomposed meters; `magnitude` — distance in meters
+  - **Factory methods**: `Vector.from_components(north:, east:)`, `Vector.from_segment(segment)`
+  - **Vincenty direct**: `destination_from(origin)` solves the direct geodetic problem on the WGS84 ellipsoid
+  - **Arithmetic**: `+`, `-` (component-wise), `*`, `/` (scalar), `-@` (unary minus); `Numeric * Vector` via coerce
+  - **Products**: `dot(other)`, `cross(other)`, `angle_between(other)`
+  - **Properties**: `zero?`, `normalize`, `reverse`/`inverse`
+  - **Comparable**: ordered by distance (magnitude)
+  - Near-zero results (< 1e-9 m) snap to clean zero vector
+- **Geodetic arithmetic with `+` operator** — build geometry from coordinates, vectors, and distances:
+  - `Coordinate + Coordinate` → Segment
+  - `Coordinate + Coordinate + Coordinate` → Path (via Segment + Coordinate → Path)
+  - `Coordinate + Segment` → Path
+  - `Segment + Coordinate` → Path
+  - `Segment + Segment` → Path
+  - `Coordinate + Distance` → Circle
+  - `Distance + Coordinate` → Circle (commutative)
+  - `Coordinate + Vector` → Segment (Vincenty direct)
+  - `Vector + Coordinate` → Segment (reverse start to coordinate)
+  - `Segment + Vector` → Path (extend from endpoint)
+  - `Vector + Segment` → Path (prepend via reverse)
+  - `Path + Vector` → Path (extend from last point)
+- **Translation with `*` operator and `translate` method** — uniform displacement across all geometric types:
+  - `Coordinate * Vector` → Coordinate (translated point)
+  - `Segment * Vector` → Segment (translated endpoints)
+  - `Path * Vector` → Path (translated waypoints)
+  - `Circle * Vector` → Circle (translated centroid, preserved radius)
+  - `Polygon * Vector` → Polygon (translated vertices)
+- **`Segment#to_vector`** — extract a Vector from a Segment's length and bearing
+- **`Path#to_corridor(width:)`** — convert a path into a Polygon corridor of a given width; uses mean bearing at interior waypoints to avoid self-intersection; accepts meters or a Distance object
+- **Geodetic arithmetic example** (`examples/08_geodetic_arithmetic.rb`) — 11-section demo covering all arithmetic operators, Vector class, translation, corridors, and composed operations
+- Documentation: `docs/reference/vector.md` (Vector reference), `docs/reference/arithmetic.md` (Geodetic Arithmetic reference)
+
+### Changed
+
+- Updated README with Vector, Geodetic Arithmetic, and Corridors sections; added to key features list
+- Updated `examples/README.md` with example 08 description
+
 ## [0.4.0] - 2026-03-10
 
 ### Added

data/README.md

@@ -22,6 +22,9 @@
 - <strong>Segments</strong> - Directed two-point line segments with projection, intersection, and interpolation<br>
 - <strong>Paths</strong> - Directed coordinate sequences with navigation, interpolation, closest approach, intersection, and area conversion<br>
 - <strong>Features</strong> - Named geometry wrapper with metadata and delegated distance/bearing<br>
+- <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>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>
@@ -71,11 +74,15 @@ require "geodetic"
 
 include Geodetic
 
-lla = Coordinates::LLA.new(lat: 47.6205, lng: -122.3493, alt: 184.0)
-ecef = Coordinates::ECEF.new(x: -2304643.57, y: -3638650.07, z: 4688674.43)
-utm = Coordinates::UTM.new(easting: 548894.0, northing: 5272748.0, altitude: 184.0, zone: 10, hemisphere: "N")
-enu = Coordinates::ENU.new(e: 100.0, n: 200.0, u: 50.0)
-ned = Coordinates::NED.new(n: 200.0, e: 100.0, d: -50.0)
+# lng:, lon:, and long: are all accepted for longitude
+lla = Coordinate::LLA.new(lat: 47.6205, lng: -122.3493, alt: 184.0)
+lla = Coordinate::LLA.new(lat: 47.6205, lon: -122.3493, alt: 184.0)
+lla = Coordinate::LLA.new(lat: 47.6205, long: -122.3493, alt: 184.0)
+# Readers: lla.lng, lla.lon, lla.long, lla.longitude all return the same value
+ecef = Coordinate::ECEF.new(x: -2304643.57, y: -3638650.07, z: 4688674.43)
+utm = Coordinate::UTM.new(easting: 548894.0, northing: 5272748.0, altitude: 184.0, zone: 10, hemisphere: "N")
+enu = Coordinate::ENU.new(e: 100.0, n: 200.0, u: 50.0)
+ned = Coordinate::NED.new(n: 200.0, e: 100.0, d: -50.0)
 ```
 
 ### GCS Shorthand
@@ -110,19 +117,19 @@ Geodetic::Coordinate.systems.map { |c| c.name.split('::').last }
 Every coordinate system can convert to and from every other system:
 
 ```ruby
-lla = Coordinates::LLA.new(lat: 47.6205, lng: -122.3493, alt: 184.0)
+lla = Coordinate::LLA.new(lat: 47.6205, lng: -122.3493, alt: 184.0)
 
 # LLA to other systems
 ecef = lla.to_ecef
 utm  = lla.to_utm
-wm   = Coordinates::WebMercator.from_lla(lla)
-mgrs = Coordinates::MGRS.from_lla(lla)
+wm   = Coordinate::WebMercator.from_lla(lla)
+mgrs = Coordinate::MGRS.from_lla(lla)
 
 # Convert back
 lla_roundtrip = ecef.to_lla
 
 # Local coordinate systems require a reference point
-reference = Coordinates::LLA.new(lat: 47.62, lng: -122.35, alt: 0.0)
+reference = Coordinate::LLA.new(lat: 47.62, lng: -122.35, alt: 0.0)
 enu = lla.to_enu(reference)
 ned = lla.to_ned(reference)
 ```
@@ -132,15 +139,15 @@ ned = lla.to_ned(reference)
 All coordinate classes support `to_s`, `to_a`, `from_string`, and `from_array`. The `to_s` method accepts an optional precision parameter controlling the number of decimal places:
 
 ```ruby
-lla = Coordinates::LLA.new(lat: 47.6205, lng: -122.3493, alt: 184.0)
+lla = Coordinate::LLA.new(lat: 47.6205, lng: -122.3493, alt: 184.0)
 
 lla.to_s                            # => "47.620500, -122.349300, 184.00"
 lla.to_s(3)                         # => "47.620, -122.349, 184.00"
 lla.to_s(0)                         # => "48, -122, 184"
 lla.to_a                            # => [47.6205, -122.3493, 184.0]
 
-Coordinates::LLA.from_string("47.6205, -122.3493, 184.0")
-Coordinates::LLA.from_array([47.6205, -122.3493, 184.0])
+Coordinate::LLA.from_string("47.6205, -122.3493, 184.0")
+Coordinate::LLA.from_array([47.6205, -122.3493, 184.0])
 ```
 
 Default precisions by class: LLA=6, Bearing=4, all others=2. Passing `0` returns integers.
@@ -150,24 +157,24 @@ Default precisions by class: LLA=6, Bearing=4, all others=2. Passing `0` returns
 All coordinate classes provide setter methods with type coercion and validation:
 
 ```ruby
-lla = Coordinates::LLA.new(lat: 47.0, lng: -122.0, alt: 100.0)
+lla = Coordinate::LLA.new(lat: 47.0, lng: -122.0, alt: 100.0)
 lla.lat = 48.0                     # validates -90..90
 lla.lng = -121.0                   # validates -180..180
 lla.alt = 200.0                    # no range constraint
 lla.lat = 91.0                     # => ArgumentError
 
-utm = Coordinates::UTM.new(easting: 500000.0, northing: 5000000.0, zone: 10, hemisphere: 'N')
+utm = Coordinate::UTM.new(easting: 500000.0, northing: 5000000.0, zone: 10, hemisphere: 'N')
 utm.zone = 15                      # validates 1..60
 utm.hemisphere = 'S'               # validates 'N' or 'S'
 utm.easting = -1.0                 # => ArgumentError
 
 # UPS cross-validates hemisphere/zone combinations
-ups = Coordinates::UPS.new(hemisphere: 'N', zone: 'Y')
+ups = Coordinate::UPS.new(hemisphere: 'N', zone: 'Y')
 ups.zone = 'Z'                     # valid for hemisphere 'N'
 ups.zone = 'A'                     # => ArgumentError (rolls back)
 
 # BNG auto-updates grid_ref when easting/northing change
-bng = Coordinates::BNG.new(easting: 530000, northing: 180000)
+bng = Coordinate::BNG.new(easting: 530000, northing: 180000)
 bng.easting = 430000               # grid_ref automatically recalculated
 ```
 
@@ -176,10 +183,10 @@ ECEF, ENU, NED, and WebMercator setters coerce to float with no range constraint
 ### DMS (Degrees, Minutes, Seconds)
 
 ```ruby
-lla = Coordinates::LLA.new(lat: 37.7749, lng: -122.4192, alt: 15.0)
+lla = Coordinate::LLA.new(lat: 37.7749, lng: -122.4192, alt: 15.0)
 lla.to_dms    # => "37° 46' 29.64\" N, 122° 25' 9.12\" W, 15.00 m"
 
-Coordinates::LLA.from_dms("37° 46' 29.64\" N, 122° 25' 9.12\" W, 15.00 m")
+Coordinate::LLA.from_dms("37° 46' 29.64\" N, 122° 25' 9.12\" W, 15.00 m")
 ```
 
 ### String-Based Coordinate Systems
@@ -187,12 +194,12 @@ Coordinates::LLA.from_dms("37° 46' 29.64\" N, 122° 25' 9.12\" W, 15.00 m")
 MGRS and USNG use string representations:
 
 ```ruby
-mgrs = Coordinates::MGRS.new(mgrs_string: "18SUJ2337006519")
-mgrs = Coordinates::MGRS.from_string("18SUJ2337006519")
+mgrs = Coordinate::MGRS.new(mgrs_string: "18SUJ2337006519")
+mgrs = Coordinate::MGRS.from_string("18SUJ2337006519")
 mgrs.to_s    # => "18SUJ2337006519"
 
-usng = Coordinates::USNG.new(usng_string: "18T WL 12345 67890")
-usng = Coordinates::USNG.from_string("18T WL 12345 67890")
+usng = Coordinate::USNG.new(usng_string: "18T WL 12345 67890")
+usng = Coordinate::USNG.from_string("18T WL 12345 67890")
 usng.to_s    # => "18T WL 12345 67890"
 ```
 
@@ -208,9 +215,9 @@ portland = Geodetic::Coordinate::LLA.new(lat: 45.5152, lng: -122.6784, alt: 0.0)
 sf = Geodetic::Coordinate::LLA.new(lat: 37.7749, lng: -122.4194, alt: 0.0)
 
 d = seattle.distance_to(portland)         # => Distance (meters)
-d.meters                                  # => 235393.17
+d.meters                                  # => 235385.71
 d.to_km.to_f                             # => 235.39
-d.to_mi.to_f                             # => 146.28
+d.to_mi.to_f                             # => 146.26
 
 seattle.distance_to(portland, sf)         # => [Distance, Distance] (radial)
 seattle.distance_to([portland, sf])       # => [Distance, Distance] (radial)
@@ -252,12 +259,12 @@ seattle = Geodetic::Coordinate::LLA.new(lat: 47.6205, lng: -122.3493, alt: 0.0)
 portland = Geodetic::Coordinate::LLA.new(lat: 45.5152, lng: -122.6784, alt: 0.0)
 
 b = seattle.bearing_to(portland)   # => Bearing
-b.degrees                          # => 188.2
-b.to_radians                      # => 3.28...
+b.degrees                          # => 186.25
+b.to_radians                      # => 3.25...
 b.to_compass                      # => "S"
 b.to_compass(points: 8)           # => "S"
 b.reverse                         # => Bearing (back azimuth)
-b.to_s                            # => "188.2036°"
+b.to_s                            # => "186.2539°"
 ```
 
 **Instance method `elevation_to`** — vertical look angle:
@@ -403,7 +410,7 @@ geoid.convert_vertical_datum(47.6205, -122.3493, 184.0, "HAE", "NAVD88")
 The `GeoidHeightSupport` module is mixed into LLA for convenience:
 
 ```ruby
-lla = Coordinates::LLA.new(lat: 47.6205, lng: -122.3493, alt: 184.0)
+lla = Coordinate::LLA.new(lat: 47.6205, lng: -122.3493, alt: 184.0)
 lla.geoid_height              # => geoid undulation in meters
 lla.orthometric_height        # => height above mean sea level
 ```
@@ -414,10 +421,10 @@ A spatial hashing coordinate that encodes lat/lng into a compact, URL-friendly s
 
 ```ruby
 # From a geohash string
-gh36 = Coordinates::GH36.new("bdrdC26BqH")
+gh36 = Coordinate::GH36.new("bdrdC26BqH")
 
 # From any coordinate
-gh36 = Coordinates::GH36.new(lla)
+gh36 = Coordinate::GH36.new(lla)
 gh36 = lla.to_gh36(precision: 8)
 
 # Decode back to LLA
@@ -441,10 +448,10 @@ The standard Geohash (base-32) algorithm by Gustavo Niemeyer, widely supported b
 
 ```ruby
 # From a geohash string
-gh = Coordinates::GH.new("dr5ru7")
+gh = Coordinate::GH.new("dr5ru7")
 
 # From any coordinate
-gh = Coordinates::GH.new(lla)
+gh = Coordinate::GH.new(lla)
 gh = lla.to_gh(precision: 8)
 
 # Decode back to LLA
@@ -468,10 +475,10 @@ The Maidenhead Locator System used worldwide in amateur radio for grid square id
 
 ```ruby
 # From a Maidenhead locator string
-ham = Coordinates::HAM.new("FN31pr")
+ham = Coordinate::HAM.new("FN31pr")
 
 # From any coordinate
-ham = Coordinates::HAM.new(lla)
+ham = Coordinate::HAM.new(lla)
 ham = lla.to_ham(precision: 8)
 
 # Decode back to LLA
@@ -495,10 +502,10 @@ Google's open system for encoding locations into short, URL-friendly codes:
 
 ```ruby
 # From a plus code string
-olc = Coordinates::OLC.new("849VCWC8+R9")
+olc = Coordinate::OLC.new("849VCWC8+R9")
 
 # From any coordinate
-olc = Coordinates::OLC.new(lla)
+olc = Coordinate::OLC.new(lla)
 olc = lla.to_olc(precision: 11)
 
 # Decode back to LLA
@@ -520,22 +527,22 @@ olc.precision_in_meters    # => { lat: 13.9, lng: 13.9 }
 
 ```ruby
 # Circle area
-center = Coordinates::LLA.new(lat: 47.6205, lng: -122.3493, alt: 0.0)
+center = Coordinate::LLA.new(lat: 47.6205, lng: -122.3493, alt: 0.0)
 circle = Areas::Circle.new(centroid: center, radius: 1000.0)  # 1km radius
 
 # Polygon area
 points = [
-  Coordinates::LLA.new(lat: 47.60, lng: -122.35, alt: 0.0),
-  Coordinates::LLA.new(lat: 47.63, lng: -122.35, alt: 0.0),
-  Coordinates::LLA.new(lat: 47.63, lng: -122.33, alt: 0.0),
-  Coordinates::LLA.new(lat: 47.60, lng: -122.33, alt: 0.0),
+  Coordinate::LLA.new(lat: 47.60, lng: -122.35, alt: 0.0),
+  Coordinate::LLA.new(lat: 47.63, lng: -122.35, alt: 0.0),
+  Coordinate::LLA.new(lat: 47.63, lng: -122.33, alt: 0.0),
+  Coordinate::LLA.new(lat: 47.60, lng: -122.33, alt: 0.0),
 ]
 polygon = Areas::Polygon.new(boundary: points)
 polygon.centroid    # => computed centroid as LLA
 
 # BoundingBox area (accepts any coordinate type)
-nw = Coordinates::LLA.new(lat: 41.0, lng: -75.0)
-se = Coordinates::LLA.new(lat: 40.0, lng: -74.0)
+nw = Coordinate::LLA.new(lat: 41.0, lng: -75.0)
+se = Coordinate::LLA.new(lat: 40.0, lng: -74.0)
 rect = Areas::BoundingBox.new(nw: nw, se: se)
 rect.centroid       # => LLA at center
 rect.ne             # => computed NE corner
@@ -626,18 +633,18 @@ route.select { |c| c.lat > 40.72 }
 ```ruby
 liberty = Feature.new(
   label:    "Statue of Liberty",
-  geometry: Coordinates::LLA.new(lat: 40.6892, lng: -74.0445, alt: 0),
+  geometry: Coordinate::LLA.new(lat: 40.6892, lng: -74.0445, alt: 0),
   metadata: { category: "monument", year: 1886 }
 )
 
 empire = Feature.new(
   label:    "Empire State Building",
-  geometry: Coordinates::LLA.new(lat: 40.7484, lng: -73.9857, alt: 0),
+  geometry: Coordinate::LLA.new(lat: 40.7484, lng: -73.9857, alt: 0),
   metadata: { category: "building", floors: 102 }
 )
 
 liberty.distance_to(empire).to_km   # => "8.24 km"
-liberty.bearing_to(empire).degrees  # => 36.99
+liberty.bearing_to(empire).degrees  # => 36.95
 
 # Area geometries use the centroid for distance/bearing
 park = Feature.new(
@@ -649,14 +656,118 @@ park.distance_to(liberty).to_km     # => "12.47 km"
 
 All three attributes (`label`, `geometry`, `metadata`) are mutable.
 
+### Vectors
+
+`Vector` pairs a `Distance` (magnitude) with a `Bearing` (direction) to represent a geodetic displacement. It solves the Vincenty direct problem to compute destination points.
+
+```ruby
+v = Geodetic::Vector.new(distance: 10_000, bearing: 90.0)
+v = Geodetic::Vector.new(distance: Distance.km(10), bearing: Bearing.new(90))
+
+v.north          # => north component in meters
+v.east           # => east component in meters
+v.magnitude      # => distance in meters
+v.reverse        # => same distance, opposite bearing
+v.normalize      # => unit vector (1 meter)
+```
+
+**Vector arithmetic:**
+
+```ruby
+v1 + v2          # => Vector (component-wise addition)
+v1 - v2          # => Vector (component-wise subtraction)
+v * 3            # => Vector (scale distance)
+v / 2            # => Vector (scale distance)
+-v               # => Vector (reverse bearing)
+v.dot(v2)        # => Float (dot product)
+v.cross(v2)      # => Float (2D cross product)
+```
+
+**Factory methods:**
+
+```ruby
+Vector.from_components(north: 1000, east: 500)
+Vector.from_segment(segment)
+segment.to_vector
+```
+
+### Geodetic Arithmetic
+
+Operators build geometry from coordinates, vectors, and distances:
+
+```ruby
+# Building geometry with +
+p1 + p2                    # => Segment
+p1 + p2 + p3              # => Path
+p1 + segment              # => Path
+segment + p3              # => Path
+segment + segment          # => Path
+p1 + distance              # => Circle
+p1 + vector                # => Segment (to destination)
+segment + vector           # => Path (extend from endpoint)
+vector + segment           # => Path (prepend via reverse)
+path + vector              # => Path (extend from last point)
+vector + coordinate        # => Segment
+distance + coordinate      # => Circle
+
+# Translation with * or .translate
+p1 * vector                # => Coordinate (translated point)
+segment * vector           # => Segment (translated endpoints)
+path * vector              # => Path (translated waypoints)
+circle * vector            # => Circle (translated centroid)
+polygon * vector           # => Polygon (translated vertices)
+```
+
+### Corridors
+
+Convert a path into a polygon corridor of a given width:
+
+```ruby
+route = seattle + portland + sf
+corridor = route.to_corridor(width: 1000)        # 1km wide polygon
+corridor = route.to_corridor(width: Distance.km(1))
+```
+
+### GeoJSON Export
+
+`GeoJSON` builds a GeoJSON FeatureCollection from any mix of Geodetic objects and writes it to a file.
+
+```ruby
+gj = Geodetic::GeoJSON.new
+gj << seattle
+gj << [portland, sf, la]
+gj << Feature.new(label: "Route", geometry: route, metadata: { mode: "driving" })
+gj << Areas::Circle.new(centroid: seattle, radius: 10_000)
+
+gj.size        # => 6
+gj.to_h        # => {"type" => "FeatureCollection", "features" => [...]}
+gj.to_json     # => compact JSON string
+gj.save("map.geojson", pretty: true)
+```
+
+Every geometry type has a `to_geojson` method returning a GeoJSON-compatible Hash:
+
+```ruby
+seattle.to_geojson                        # => {"type" => "Point", ...}
+Segment.new(seattle, portland).to_geojson # => {"type" => "LineString", ...}
+route.to_geojson                          # => {"type" => "LineString", ...}
+route.to_geojson(as: :polygon)            # => {"type" => "Polygon", ...}
+polygon.to_geojson                        # => {"type" => "Polygon", ...}
+circle.to_geojson(segments: 64)           # => {"type" => "Polygon", ...} (64-gon)
+bbox.to_geojson                           # => {"type" => "Polygon", ...}
+feature.to_geojson                        # => {"type" => "Feature", ...}
+```
+
+Features carry their `label` as `"name"` and `metadata` as `properties` in the GeoJSON output. Non-Feature objects added to the collection are auto-wrapped as Features with empty properties.
+
 ### Web Mercator Tile Coordinates
 
 ```ruby
-wm = Coordinates::WebMercator.from_lla(lla)
+wm = Coordinate::WebMercator.from_lla(lla)
 wm.to_tile_coordinates(15)     # => [x_tile, y_tile, zoom]
 wm.to_pixel_coordinates(15)    # => [x_pixel, y_pixel, zoom]
 
-Coordinates::WebMercator.from_tile_coordinates(5241, 11438, 15)
+Coordinate::WebMercator.from_tile_coordinates(5241, 11438, 15)
 ```
 
 ## Available Datums
@@ -679,6 +790,9 @@ The [`examples/`](examples/) directory contains runnable demo scripts showing pr
 | [`04_bearing_calculations.rb`](examples/04_bearing_calculations.rb) | Bearing class, compass directions, elevation angles, and chain bearings |
 | [`05_map_rendering/`](examples/05_map_rendering/) | Render landmarks on a raster map with Feature objects, polygon areas, bearing arrows, and icons using [libgd-gis](https://rubygems.org/gems/libgd-gis) |
 | [`06_path_operations.rb`](examples/06_path_operations.rb) | Path class: construction, navigation, mutation, path arithmetic, closest approach, containment, Enumerable, equality, subpaths, split, interpolation, bounding boxes, polygon conversion, intersection, path-to-path/area closest points, and Feature integration |
+| [`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 |
 
 Run any example with:
 

data/docs/coordinate-systems/index.md

@@ -6,54 +6,54 @@ The Geodetic gem supports 18 coordinate systems organized into six categories. A
 
 | System | Class | Description |
 |--------|-------|-------------|
-| **LLA** | `Geodetic::Coordinate::LLA` | Latitude, Longitude, Altitude. The most common geographic coordinate system, expressing positions in decimal degrees with altitude in meters. Negative longitude is the Western hemisphere; negative latitude is the Southern hemisphere. |
-| **ECEF** | `Geodetic::Coordinate::ECEF` | Earth-Centered, Earth-Fixed. A Cartesian coordinate system with the origin at the Earth's center of mass. Positions are expressed as X, Y, Z in meters. Commonly used in satellite navigation and aerospace applications. |
-| **UTM** | `Geodetic::Coordinate::UTM` | Universal Transverse Mercator. Divides the Earth into 60 zones (each 6 degrees of longitude), projecting positions as easting/northing in meters within a zone and hemisphere. Covers latitudes 80S to 84N. |
+| [**LLA**](lla.md) | `Geodetic::Coordinate::LLA` | Latitude, Longitude, Altitude. The most common geographic coordinate system, expressing positions in decimal degrees with altitude in meters. Negative longitude is the Western hemisphere; negative latitude is the Southern hemisphere. |
+| [**ECEF**](ecef.md) | `Geodetic::Coordinate::ECEF` | Earth-Centered, Earth-Fixed. A Cartesian coordinate system with the origin at the Earth's center of mass. Positions are expressed as X, Y, Z in meters. Commonly used in satellite navigation and aerospace applications. |
+| [**UTM**](utm.md) | `Geodetic::Coordinate::UTM` | Universal Transverse Mercator. Divides the Earth into 60 zones (each 6 degrees of longitude), projecting positions as easting/northing in meters within a zone and hemisphere. Covers latitudes 80S to 84N. |
 
 ## Local Tangent Plane Systems
 
 | System | Class | Description |
 |--------|-------|-------------|
-| **ENU** | `Geodetic::Coordinate::ENU` | East, North, Up. A local tangent plane coordinate system centered on a reference point. Axes point East, North, and Up relative to the reference. Distances are in meters. Used in robotics, surveying, and local navigation. |
-| **NED** | `Geodetic::Coordinate::NED` | North, East, Down. A local tangent plane coordinate system centered on a reference point. Axes point North, East, and Down. Used extensively in aerospace and aviation applications. Mathematically related to ENU by axis reordering and sign inversion. |
+| [**ENU**](enu.md) | `Geodetic::Coordinate::ENU` | East, North, Up. A local tangent plane coordinate system centered on a reference point. Axes point East, North, and Up relative to the reference. Distances are in meters. Used in robotics, surveying, and local navigation. |
+| [**NED**](ned.md) | `Geodetic::Coordinate::NED` | North, East, Down. A local tangent plane coordinate system centered on a reference point. Axes point North, East, and Down. Used extensively in aerospace and aviation applications. Mathematically related to ENU by axis reordering and sign inversion. |
 
 ## Military and Grid Systems
 
 | System | Class | Description |
 |--------|-------|-------------|
-| **MGRS** | `Geodetic::Coordinate::MGRS` | Military Grid Reference System. An alphanumeric system based on UTM that identifies positions using grid zone designator, 100km square identifier, and numeric easting/northing. Variable precision from 10km down to 1m. |
-| **USNG** | `Geodetic::Coordinate::USNG` | United States National Grid. Based on MGRS but formatted with spaces for readability. Used primarily within the United States for emergency services and land management. |
+| [**MGRS**](mgrs.md) | `Geodetic::Coordinate::MGRS` | Military Grid Reference System. An alphanumeric system based on UTM that identifies positions using grid zone designator, 100km square identifier, and numeric easting/northing. Variable precision from 10km down to 1m. |
+| [**USNG**](usng.md) | `Geodetic::Coordinate::USNG` | United States National Grid. Based on MGRS but formatted with spaces for readability. Used primarily within the United States for emergency services and land management. |
 
 ## Web Mapping
 
 | System | Class | Description |
 |--------|-------|-------------|
-| **WebMercator** | `Geodetic::Coordinate::WebMercator` | Web Mercator (EPSG:3857). Also known as Pseudo-Mercator or Spherical Mercator. The projection used by Google Maps, OpenStreetMap, and Bing Maps. Positions are X/Y in meters. Latitude is clamped to approximately +/-85.05 degrees. Includes tile and pixel coordinate methods for web mapping applications. |
+| [**WebMercator**](web-mercator.md) | `Geodetic::Coordinate::WebMercator` | Web Mercator (EPSG:3857). Also known as Pseudo-Mercator or Spherical Mercator. The projection used by Google Maps, OpenStreetMap, and Bing Maps. Positions are X/Y in meters. Latitude is clamped to approximately +/-85.05 degrees. Includes tile and pixel coordinate methods for web mapping applications. |
 
 ## Polar
 
 | System | Class | Description |
 |--------|-------|-------------|
-| **UPS** | `Geodetic::Coordinate::UPS` | Universal Polar Stereographic. Covers the polar regions not handled by UTM (north of 84N and south of 80S). Uses a stereographic projection centered on each pole with zones Y/Z (north) and A/B (south). |
+| [**UPS**](ups.md) | `Geodetic::Coordinate::UPS` | Universal Polar Stereographic. Covers the polar regions not handled by UTM (north of 84N and south of 80S). Uses a stereographic projection centered on each pole with zones Y/Z (north) and A/B (south). |
 
 ## Spatial Hashing
 
 | System | Class | Description |
 |--------|-------|-------------|
-| **GH36** | `Geodetic::Coordinate::GH36` | Geohash-36. A hierarchical spatial hashing algorithm that encodes latitude/longitude into a compact, URL-friendly string using a case-sensitive 36-character alphabet (radix-36). Each hash represents a rectangular cell; the coordinate value is the cell midpoint. Supports neighbor lookup, area extraction via `to_area`, and configurable precision (default 10 characters for sub-meter resolution). |
-| **GH** | `Geodetic::Coordinate::GH` | Geohash (base-32). The standard geohash algorithm by Gustavo Niemeyer using a 32-character alphabet (`0-9, b-z` excluding `a, i, l, o`). The de facto standard for spatial hashing, natively supported by Elasticsearch, Redis, PostGIS, and many geocoding services. Supports neighbor lookup, area extraction, and configurable precision (default 12 characters for sub-centimeter resolution). |
-| **HAM** | `Geodetic::Coordinate::HAM` | Maidenhead Locator System. A hierarchical grid system used worldwide in amateur radio that encodes positions using alternating letter/digit pairs (e.g., `FN31pr`). Four levels of precision: Field (18x18), Square (10x10), Subsquare (24x24), Extended (10x10). Supports neighbor lookup, area extraction, and configurable precision (default 6 characters for ~5 km resolution). |
-| **OLC** | `Geodetic::Coordinate::OLC` | Open Location Code (Plus Codes). Google's open system for encoding locations into short codes like `849VCWC8+R9`. Uses a 20-character alphabet with 5 paired levels of base-20 encoding plus optional grid refinement. Includes a `+` separator at position 8. Supports neighbor lookup, area extraction, and configurable precision (default 10 characters for ~14 m resolution). |
-| **GEOREF** | `Geodetic::Coordinate::GEOREF` | World Geographic Reference System. A geocode system used in aviation and military applications that encodes positions using letter tiles (15° grid), letter degree subdivisions, and numeric minute pairs. Uses a 24-letter alphabet (A-Z excluding I and O). Supports variable precision from 15° tiles (2 chars) down to 0.01-minute resolution (12 chars). Default precision is 8 characters (1-minute resolution). |
-| **GARS** | `Geodetic::Coordinate::GARS` | Global Area Reference System. An NGA standard that divides the world into 30-minute cells identified by a 3-digit longitude band (001-720) and 2-letter latitude band. Cells are subdivided into 15-minute quadrants (1-4) and 5-minute keypads (1-9, telephone layout). Variable precision: 5 chars (30'), 6 chars (15'), 7 chars (5'). Default precision is 7 characters. |
-| **H3** | `Geodetic::Coordinate::H3` | H3 Hexagonal Hierarchical Index. Uber's spatial indexing system that divides the globe into hexagonal cells (and 12 pentagons) at 16 resolution levels (0-15). Each cell is a 64-bit integer displayed as a hex string. Unlike the rectangular spatial hashes, `to_area` returns an `Areas::Polygon` with 6 vertices (5 for pentagons) and `neighbors` returns an Array of 6 cells. **Requires `libh3` installed** (`brew install h3` on macOS). |
+| [**GH36**](gh36.md) | `Geodetic::Coordinate::GH36` | Geohash-36. A hierarchical spatial hashing algorithm that encodes latitude/longitude into a compact, URL-friendly string using a case-sensitive 36-character alphabet (radix-36). Each hash represents a rectangular cell; the coordinate value is the cell midpoint. Supports neighbor lookup, area extraction via `to_area`, and configurable precision (default 10 characters for sub-meter resolution). |
+| [**GH**](gh.md) | `Geodetic::Coordinate::GH` | Geohash (base-32). The standard geohash algorithm by Gustavo Niemeyer using a 32-character alphabet (`0-9, b-z` excluding `a, i, l, o`). The de facto standard for spatial hashing, natively supported by Elasticsearch, Redis, PostGIS, and many geocoding services. Supports neighbor lookup, area extraction, and configurable precision (default 12 characters for sub-centimeter resolution). |
+| [**HAM**](ham.md) | `Geodetic::Coordinate::HAM` | Maidenhead Locator System. A hierarchical grid system used worldwide in amateur radio that encodes positions using alternating letter/digit pairs (e.g., `FN31pr`). Four levels of precision: Field (18x18), Square (10x10), Subsquare (24x24), Extended (10x10). Supports neighbor lookup, area extraction, and configurable precision (default 6 characters for ~5 km resolution). |
+| [**OLC**](olc.md) | `Geodetic::Coordinate::OLC` | Open Location Code (Plus Codes). Google's open system for encoding locations into short codes like `849VCWC8+R9`. Uses a 20-character alphabet with 5 paired levels of base-20 encoding plus optional grid refinement. Includes a `+` separator at position 8. Supports neighbor lookup, area extraction, and configurable precision (default 10 characters for ~14 m resolution). |
+| [**GEOREF**](georef.md) | `Geodetic::Coordinate::GEOREF` | World Geographic Reference System. A geocode system used in aviation and military applications that encodes positions using letter tiles (15° grid), letter degree subdivisions, and numeric minute pairs. Uses a 24-letter alphabet (A-Z excluding I and O). Supports variable precision from 15° tiles (2 chars) down to 0.01-minute resolution (12 chars). Default precision is 8 characters (1-minute resolution). |
+| [**GARS**](gars.md) | `Geodetic::Coordinate::GARS` | Global Area Reference System. An NGA standard that divides the world into 30-minute cells identified by a 3-digit longitude band (001-720) and 2-letter latitude band. Cells are subdivided into 15-minute quadrants (1-4) and 5-minute keypads (1-9, telephone layout). Variable precision: 5 chars (30'), 6 chars (15'), 7 chars (5'). Default precision is 7 characters. |
+| [**H3**](h3.md) | `Geodetic::Coordinate::H3` | H3 Hexagonal Hierarchical Index. Uber's spatial indexing system that divides the globe into hexagonal cells (and 12 pentagons) at 16 resolution levels (0-15). Each cell is a 64-bit integer displayed as a hex string. Unlike the rectangular spatial hashes, `to_area` returns an `Areas::Polygon` with 6 vertices (5 for pentagons) and `neighbors` returns an Array of 6 cells. **Requires `libh3` installed** (`brew install h3` on macOS). |
 
 ## Regional Systems
 
 | System | Class | Description |
 |--------|-------|-------------|
-| **StatePlane** | `Geodetic::Coordinate::StatePlane` | State Plane Coordinate System. US state-based coordinate systems using Lambert Conformal Conic or Transverse Mercator projections. Each state has one or more zones with specific parameters. Coordinates are typically in US Survey Feet. |
-| **BNG** | `Geodetic::Coordinate::BNG` | British National Grid. The official coordinate system for Great Britain, based on the OSGB36 datum with the Airy 1830 ellipsoid. Uses a Transverse Mercator projection and an alphanumeric grid reference system (e.g., "TQ 30 80"). |
+| [**StatePlane**](state-plane.md) | `Geodetic::Coordinate::StatePlane` | State Plane Coordinate System. US state-based coordinate systems using Lambert Conformal Conic or Transverse Mercator projections. Each state has one or more zones with specific parameters. Coordinates are typically in US Survey Feet. |
+| [**BNG**](bng.md) | `Geodetic::Coordinate::BNG` | British National Grid. The official coordinate system for Great Britain, based on the OSGB36 datum with the Airy 1830 ellipsoid. Uses a Transverse Mercator projection and an alphanumeric grid reference system (e.g., "TQ 30 80"). |
 
 ---