geodetic 0.5.0 → 0.5.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 495ba0272532d5591ecbb37869857675af00014d6863849c79c6fbef35e590c3
-  data.tar.gz: dcb68a4385f7a888fbfb37b421d2f82c66aae077bda8557ce2a7b60c57e38b35
+  metadata.gz: 82e74456b38ec9c888ee70e68de3e626f0333b9f791c8de7779f5aa544cbbbc7
+  data.tar.gz: a76e9a726d4a503f0e2331f321de25a3b7c155e8712a27a18c53ba8e5ab27953
 SHA512:
-  metadata.gz: 8f276d8924aad177efc94aee0037f1fbd4e1cb655668ed54ff5ba0e471c16dd91687966577505057e31a144ea545adf3d8843535ca0705fca69fc5e5bf9a3637
-  data.tar.gz: f2d8102549b1502099d149453f5b18d8143b5799e3d3f5c2c4f947c86b7e2de1355e74916ae3b0d7376652fdb547ebd48488bff2eba18d60211da4ff0ff030a3
+  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,45 @@ 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

data/README.md

@@ -24,6 +24,7 @@
 - <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>
@@ -73,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
@@ -112,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)
 ```
@@ -134,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.
@@ -152,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
 ```
 
@@ -178,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
@@ -189,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"
 ```
 
@@ -210,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)
@@ -254,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:
@@ -405,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
 ```
@@ -416,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
@@ -443,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
@@ -470,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
@@ -497,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
@@ -522,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
@@ -628,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(
@@ -723,14 +728,46 @@ 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
@@ -755,6 +792,7 @@ The [`examples/`](examples/) directory contains runnable demo scripts showing pr
 | [`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"). |
 
 ---
 

data/docs/index.md

@@ -9,7 +9,7 @@
 <td width="50%" valign="top">
 <h2>Key Features</h2>
 <lu>
-<li><strong>18 Coordinate Systems</strong> - LLA, ECEF, UTM, ENU, NED, MGRS, USNG, Web Mercator, UPS, State Plane, BNG, GH36, GH, HAM, OLC<br>
+<li><strong>18 Coordinate Systems</strong> - LLA, ECEF, UTM, ENU, NED, MGRS, USNG, Web Mercator, UPS, State Plane, BNG, GH36, GH, HAM, OLC, GEOREF, GARS, H3<br>
 <li><strong>Full Bidirectional Conversions</strong> - Every system converts to and from every other system<br>
 <li><strong>Distance Calculations</strong> - Vincenty great-circle and straight-line with unit tracking<br>
 <li><strong>Bearing Calculations</strong> - Forward azimuth, back azimuth, compass directions, elevation angles<br>
@@ -18,6 +18,7 @@
 <li><strong>Segments</strong> - Directed two-point line segments with projection, intersection, and interpolation<br>
 <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>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>
@@ -35,33 +36,33 @@ Geodetic supports full bidirectional conversion between all 18 coordinate system
 
 | System | Class | Description |
 |--------|-------|-------------|
-| **LLA** | `Geodetic::Coordinate::LLA` | Latitude, Longitude, Altitude |
-| **ECEF** | `Geodetic::Coordinate::ECEF` | Earth-Centered, Earth-Fixed (X, Y, Z) |
-| **UTM** | `Geodetic::Coordinate::UTM` | Universal Transverse Mercator |
-| **ENU** | `Geodetic::Coordinate::ENU` | East, North, Up (local tangent plane) |
-| **NED** | `Geodetic::Coordinate::NED` | North, East, Down (local tangent plane) |
-| **MGRS** | `Geodetic::Coordinate::MGRS` | Military Grid Reference System |
-| **USNG** | `Geodetic::Coordinate::USNG` | United States National Grid |
-| **WebMercator** | `Geodetic::Coordinate::WebMercator` | Web Mercator projection (EPSG:3857) |
-| **UPS** | `Geodetic::Coordinate::UPS` | Universal Polar Stereographic |
-| **StatePlane** | `Geodetic::Coordinate::StatePlane` | State Plane Coordinate System |
-| **BNG** | `Geodetic::Coordinate::BNG` | British National Grid |
-| **GH36** | `Geodetic::Coordinate::GH36` | Geohash-36 (spatial hash, URL-friendly) |
-| **GH** | `Geodetic::Coordinate::GH` | Geohash base-32 (standard geohash, widely supported) |
-| **HAM** | `Geodetic::Coordinate::HAM` | Maidenhead Locator System (amateur radio grid squares) |
-| **OLC** | `Geodetic::Coordinate::OLC` | Open Location Code / Plus Codes (Google's location encoding) |
-| **GEOREF** | `Geodetic::Coordinate::GEOREF` | World Geographic Reference System (aviation/military) |
-| **GARS** | `Geodetic::Coordinate::GARS` | Global Area Reference System (NGA standard) |
-| **H3** | `Geodetic::Coordinate::H3` | Uber's hexagonal hierarchical index (requires `libh3`) |
+| [**LLA**](coordinate-systems/lla.md) | `Geodetic::Coordinate::LLA` | Latitude, Longitude, Altitude |
+| [**ECEF**](coordinate-systems/ecef.md) | `Geodetic::Coordinate::ECEF` | Earth-Centered, Earth-Fixed (X, Y, Z) |
+| [**UTM**](coordinate-systems/utm.md) | `Geodetic::Coordinate::UTM` | Universal Transverse Mercator |
+| [**ENU**](coordinate-systems/enu.md) | `Geodetic::Coordinate::ENU` | East, North, Up (local tangent plane) |
+| [**NED**](coordinate-systems/ned.md) | `Geodetic::Coordinate::NED` | North, East, Down (local tangent plane) |
+| [**MGRS**](coordinate-systems/mgrs.md) | `Geodetic::Coordinate::MGRS` | Military Grid Reference System |
+| [**USNG**](coordinate-systems/usng.md) | `Geodetic::Coordinate::USNG` | United States National Grid |
+| [**WebMercator**](coordinate-systems/web-mercator.md) | `Geodetic::Coordinate::WebMercator` | Web Mercator projection (EPSG:3857) |
+| [**UPS**](coordinate-systems/ups.md) | `Geodetic::Coordinate::UPS` | Universal Polar Stereographic |
+| [**StatePlane**](coordinate-systems/state-plane.md) | `Geodetic::Coordinate::StatePlane` | State Plane Coordinate System |
+| [**BNG**](coordinate-systems/bng.md) | `Geodetic::Coordinate::BNG` | British National Grid |
+| [**GH36**](coordinate-systems/gh36.md) | `Geodetic::Coordinate::GH36` | Geohash-36 (spatial hash, URL-friendly) |
+| [**GH**](coordinate-systems/gh.md) | `Geodetic::Coordinate::GH` | Geohash base-32 (standard geohash, widely supported) |
+| [**HAM**](coordinate-systems/ham.md) | `Geodetic::Coordinate::HAM` | Maidenhead Locator System (amateur radio grid squares) |
+| [**OLC**](coordinate-systems/olc.md) | `Geodetic::Coordinate::OLC` | Open Location Code / Plus Codes (Google's location encoding) |
+| [**GEOREF**](coordinate-systems/georef.md) | `Geodetic::Coordinate::GEOREF` | World Geographic Reference System (aviation/military) |
+| [**GARS**](coordinate-systems/gars.md) | `Geodetic::Coordinate::GARS` | Global Area Reference System (NGA standard) |
+| [**H3**](coordinate-systems/h3.md) | `Geodetic::Coordinate::H3` | Uber's hexagonal hierarchical index (requires `libh3`) |
 
 ## Additional Features
 
-- **16 geodetic datums** -- WGS84, GRS 1980, Clarke 1866, Airy 1830, Bessel 1841, and more. All conversion methods accept an optional datum parameter, defaulting to WGS84.
-- **Geoid height calculations** -- Convert between ellipsoidal and orthometric heights using models such as EGM96, EGM2008, GEOID18, and GEOID12B.
-- **Geographic areas** -- `Geodetic::Areas::Circle`, `Geodetic::Areas::Polygon`, `Geodetic::Areas::BoundingBox`, plus polygon subclasses (`Triangle`, `Rectangle`, `Pentagon`, `Hexagon`, `Octagon`) for point-in-area testing.
-- **Segments** -- `Geodetic::Segment` is a directed two-point line segment with projection, intersection detection, interpolation, and membership testing. It is the geometric primitive underlying Path and Polygon operations.
-- **Paths** -- `Geodetic::Path` is a directed, ordered sequence of unique coordinates supporting navigation, segment analysis, interpolation, closest approach (geometric projection), containment testing, bounding boxes, polygon conversion, and path intersection detection.
-- **Features** -- `Geodetic::Feature` wraps any coordinate, area, or path with a label and metadata hash, delegating `distance_to` and `bearing_to` to the underlying geometry.
+- **[16 geodetic datums](reference/datums.md)** -- WGS84, GRS 1980, Clarke 1866, Airy 1830, Bessel 1841, and more. All conversion methods accept an optional datum parameter, defaulting to WGS84.
+- **[Geoid height calculations](reference/geoid-height.md)** -- Convert between ellipsoidal and orthometric heights using models such as EGM96, EGM2008, GEOID18, and GEOID12B.
+- **[Geographic areas](reference/areas.md)** -- `Geodetic::Areas::Circle`, `Geodetic::Areas::Polygon`, `Geodetic::Areas::BoundingBox`, plus polygon subclasses (`Triangle`, `Rectangle`, `Pentagon`, `Hexagon`, `Octagon`) for point-in-area testing.
+- **[Segments](reference/segment.md)** -- `Geodetic::Segment` is a directed two-point line segment with projection, intersection detection, interpolation, and membership testing. It is the geometric primitive underlying Path and Polygon operations.
+- **[Paths](reference/path.md)** -- `Geodetic::Path` is a directed, ordered sequence of unique coordinates supporting navigation, segment analysis, interpolation, closest approach (geometric projection), containment testing, bounding boxes, polygon conversion, and path intersection detection.
+- **[Features](reference/feature.md)** -- `Geodetic::Feature` wraps any coordinate, area, or path with a label and metadata hash, delegating `distance_to` and `bearing_to` to the underlying geometry.
 
 ## Design Principles
 
@@ -91,5 +92,26 @@ puts lla_again.to_s
 
 ## Documentation
 
-- [Getting Started: Installation](getting-started/installation.md)
-- [Getting Started: Quick Start](getting-started/quick-start.md)
+### Getting Started
+
+- [Installation](getting-started/installation.md)
+- [Quick Start](getting-started/quick-start.md)
+
+### Coordinate Systems
+
+- [Coordinate Systems Overview](coordinate-systems/index.md)
+
+### Reference
+
+- [Conversions](reference/conversions.md)
+- [Serialization](reference/serialization.md)
+- [Datums](reference/datums.md)
+- [Geoid Height](reference/geoid-height.md)
+- [Areas](reference/areas.md)
+- [Path](reference/path.md)
+- [Segment](reference/segment.md)
+- [Feature](reference/feature.md)
+- [Vector](reference/vector.md)
+- [Arithmetic](reference/arithmetic.md)
+- [GeoJSON Export](reference/geojson.md)
+- [Map Rendering](reference/map-rendering.md)

data/docs/reference/arithmetic.md

@@ -30,7 +30,7 @@ seg = seattle + portland  # => Geodetic::Segment
 seg.start_point           # => seattle
 seg.end_point             # => portland
 seg.length                # => Distance (~235 km)
-seg.bearing               # => Bearing (~188°)
+seg.bearing               # => Bearing (~186°)
 ```
 
 Works across any coordinate system — the Segment converts both points to LLA internally:

data/docs/reference/conversions.md

@@ -250,7 +250,7 @@ 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)
 
 # Radial distances from receiver
-seattle.distance_to(portland)          # => Distance (235393.17 m)
+seattle.distance_to(portland)          # => Distance (235385.71 m)
 seattle.distance_to(portland, sf)      # => [Distance, Distance] (Array)
 
 # Consecutive chain distances
@@ -274,7 +274,7 @@ Both `distance_to` and `straight_line_distance_to` accept any coordinate type. C
 ```ruby
 utm = seattle.to_utm
 mgrs = Geodetic::Coordinate::MGRS.from_lla(portland)
-utm.distance_to(mgrs)    # => Distance (235393.17 m)
+utm.distance_to(mgrs)    # => Distance (235385.71 m)
 ```
 
 ### ENU and NED (Relative Systems)
@@ -308,7 +308,7 @@ sf = Geodetic::Coordinate::LLA.new(lat: 37.7749, lng: -122.4194, alt: 0.0)
 
 # Forward azimuth
 b = seattle.bearing_to(portland)       # => Bearing
-b.degrees                              # => 188.2...
+b.degrees                              # => 186.25...
 b.to_compass(points: 8)               # => "S"
 b.reverse                             # => Bearing (back azimuth)
 

data/docs/reference/feature.md

@@ -65,7 +65,7 @@ liberty.distance_to(LLA.new(lat: 40.7484, lng: -73.9857, alt: 0))
 Returns a `Geodetic::Bearing` from this feature to another feature, coordinate, or area. Uses the same centroid resolution as `distance_to`.
 
 ```ruby
-liberty.bearing_to(empire).degrees      # => 36.99
+liberty.bearing_to(empire).degrees      # => 36.95
 liberty.bearing_to(empire).to_compass   # => "NE"
 ```