geodetic 0.3.0 → 0.3.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6d81eb7c69d9aff7d512562f54e2413c91c8ff10b2361c9143a8afd0c1af0ca0
-  data.tar.gz: e7fb09dd1f7d4d97f57ea48f9cacb0e6afbd30abedab1aa04cbf1153c2fe4373
+  metadata.gz: f295df82e85611a9a7a7dd56593ae029d6ad096cc5c96021d5b59b4f4b001cc2
+  data.tar.gz: 6da1bc3461fd4f372b53f5458d322f8c14d1feb8a2afa93a2375cb5641674674
 SHA512:
-  metadata.gz: 90a2e1b8bbc1c6bdf59c7e326d4965f8ec85a16682bccba948fd1f104d7818a5fa34ee179fa00de0221cbfd0e9d9afbd5c667aac46c1a6c9c070b338618b461a
-  data.tar.gz: 85b40d6e961ec4782a9748232eed4191df1dd8a5f22df77afe68c63d64b6b23df0e8ff5ec4ae927038d60919a7825e09c2429bbd4aa8d4447b1737ff81aa4dfd
+  metadata.gz: 1a0b72935abf28bbcb41182f800d1bdb52466530565f13d75fec5f3eec14c0dac7680f8220f09c51cf4d60ed3b87fc53a3675ceb972f1cec17ca06cbd096d717
+  data.tar.gz: 754e5b64d8e1d333dafd270a6e21434d46102ea57e43fbba16b83bcecd9eb69eb4e834a51554c10eb59433f6d434930bf2664fca0d9c22b37cf7378e90cc106e

data/CHANGELOG.md

@@ -11,21 +11,73 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## [Unreleased]
 
 
-## [0.2.0] - 2026-03-08
+## [0.3.2] - 2026-03-09
 
 ### Added
 
-- **3 new coordinate systems** bringing the total from 15 to 18:
-  - `Geodetic::Coordinate::GEOREF` — World Geographic Reference System (aviation/military geocode with variable precision from 15-degree tiles to 0.001-minute resolution)
-  - `Geodetic::Coordinate::GARS` — Global Area Reference System (NGA standard with 30-minute cells, 15-minute quadrants, and 5-minute keypads)
-  - `Geodetic::Coordinate::H3` — Uber's H3 Hexagonal Hierarchical Index (16 resolution levels, hexagonal cells via `libh3` C library through `fiddle`)
-- Full cross-system conversions for GEOREF, GARS, and H3 — all 18 coordinate systems convert to/from every other system (324 conversion paths)
-- Spatial hash features for GEOREF, GARS, and H3: `neighbors`, `to_area`, `precision_in_meters`, `to_slug`, configurable precision
+- **`Geodetic::Path` class** — directed, ordered sequence of unique coordinates for modeling routes, trails, and boundaries
+  - **Navigation**: `first`, `last`, `next`, `prev`, `segments`, `size`, `empty?`
+  - **Membership**: `include?`/`includes?` (waypoint check), `contains?`/`inside?` (on-segment check with configurable tolerance)
+  - **Spatial**: `nearest_waypoint`, `closest_coordinate_to`, `distance_to`, `bearing_to` using geometric projection onto segments
+  - **Closest points**: `closest_points_to` for Path-to-Path, Path-to-Polygon, Path-to-Rectangle, and Path-to-Circle
+  - **Computed**: `total_distance`, `segment_distances`, `segment_bearings`, `reverse`
+  - **Subpath/split**: `between(from, to)` extracts a subpath; `split_at(coord)` divides into two paths sharing the split point
+  - **Interpolation**: `at_distance(distance)` finds the coordinate at a given distance along the path
+  - **Bounding box**: `bounds` returns an `Areas::Rectangle`
+  - **Polygon conversion**: `to_polygon` closes the path (validates no self-intersection)
+  - **Intersection**: `intersects?(other_path)` detects crossing segments
+  - **Equality**: `==` compares coordinates in order
+  - **Enumerable**: includes `Enumerable` via `each` — supports `map`, `select`, `any?`, `to_a`, etc.
+  - **Non-mutating operators**: `+` and `-` accept both coordinates and paths
+  - **Mutating operators**: `<<`, `>>`, `prepend`, `insert(after:/before:)`, `delete`/`remove` — all accept paths as well as coordinates
+- **Path operations example** (`examples/06_path_operations.rb`) — 19-section demo covering all Path capabilities with a Manhattan walking route
+- Documentation: `docs/reference/path.md` (Path reference)
+
+### Changed
+
+- Updated `Geodetic::Feature` to support Path as a geometry type — delegates `distance_to` and `bearing_to` using geometric projection
+- Updated README, `docs/index.md`, `docs/reference/feature.md`, `examples/README.md`, and mkdocs nav to include Path class
+
+## [0.3.1] - 2026-03-09
+
+### Added
+
+- **`Geodetic::Feature` class** — wraps any coordinate or area geometry with a `label` and `metadata` hash; delegates `distance_to` and `bearing_to` to the underlying geometry, using the centroid for area geometries
+- **Map rendering example** (`examples/05_map_rendering/`) — renders NYC landmarks on a raster map using [libgd-gis](https://rubygems.org/gems/libgd-gis), demonstrating Feature objects, polygon overlays, bearing arrows, icon compositing, and light/dark theme support
+- `examples/README.md` describing all five example scripts
+- Documentation: `docs/reference/feature.md` (Feature reference) and `docs/reference/map-rendering.md` (libgd-gis integration guide)
+
+### Changed
+
+- Updated README, `docs/index.md`, and mkdocs nav to include Feature class and map rendering example
+
+## [0.3.0] - 2026-03-08
+
+### Added
+
+- **H3 Hexagonal Hierarchical Index** (`Geodetic::Coordinate::H3`) — Uber's spatial indexing system, bringing total to 18 coordinate systems (324 conversion paths)
+- H3 uses Ruby's `fiddle` to call the H3 v4 C API directly — no gem dependency beyond `fiddle`
 - H3-specific features: `grid_disk(k)`, `parent(res)`, `children(res)`, `pentagon?`, `cell_area`, `h3_index`, `resolution` (0-15)
 - H3 `to_area` returns `Areas::Polygon` (6 vertices for hexagons, 5 for pentagons) instead of `Areas::Rectangle`
 - H3 `neighbors` returns Array of 6 cells instead of directional Hash with 8 cardinal keys
 - Graceful degradation: H3 raises clear error with installation instructions if `libh3` is not found; all other coordinate systems work normally
-- Documentation pages: `docs/coordinate-systems/georef.md`, `docs/coordinate-systems/gars.md`, and `docs/coordinate-systems/h3.md`
+- `H3.available?` class method to check for libh3 at runtime
+- Documentation page: `docs/coordinate-systems/h3.md`
+
+### Changed
+
+- Updated all documentation to reflect 18 coordinate systems (README, docs, gemspec, CLAUDE.md)
+
+## [0.2.0] - 2026-03-08
+
+### Added
+
+- **2 new coordinate systems** bringing the total from 15 to 17:
+  - `Geodetic::Coordinate::GEOREF` — World Geographic Reference System (aviation/military geocode with variable precision from 15-degree tiles to 0.001-minute resolution)
+  - `Geodetic::Coordinate::GARS` — Global Area Reference System (NGA standard with 30-minute cells, 15-minute quadrants, and 5-minute keypads)
+- Full cross-system conversions for GEOREF and GARS — all 17 coordinate systems convert to/from every other system (289 conversion paths)
+- Spatial hash features for GEOREF and GARS: `neighbors`, `to_area`, `precision_in_meters`, `to_slug`, configurable precision
+- Documentation pages: `docs/coordinate-systems/georef.md` and `docs/coordinate-systems/gars.md`
 
 ### Changed
 

data/README.md

@@ -19,6 +19,8 @@
 - <strong>Bearing Calculations</strong> - Forward azimuth, back azimuth, compass directions, elevation angles<br>
 - <strong>Geoid Height Support</strong> - EGM96, EGM2008, GEOID18, GEOID12B models<br>
 - <strong>Geographic Areas</strong> - Circle, Polygon, and Rectangle with point-in-area tests<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>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>
@@ -77,14 +79,29 @@ ned = Coordinates::NED.new(n: 200.0, e: 100.0, d: -50.0)
 
 ### GCS Shorthand
 
-`GCS` is a top-level alias for `Geodetic::Coordinate`, providing a concise way to create and work with coordinates:
+For convenience, you can define a short alias in your application:
 
 ```ruby
 require "geodetic"
 
-# Use GCS as a shorthand for Geodetic::Coordinate
-seattle = GCS::LLA.new(lat: 47.6205, lng: -122.3493, alt: 184.0)
-ecef = GCS::ECEF.new(x: -2304643.57, y: -3638650.07, z: 4688674.43)
+GCS = Geodetic::Coordinate
+
+seattle = Geodetic::Coordinate::LLA.new(lat: 47.6205, lng: -122.3493, alt: 184.0)
+ecef = Geodetic::Coordinate::ECEF.new(x: -2304643.57, y: -3638650.07, z: 4688674.43)
+```
+
+### Discovering Coordinate Systems
+
+List all available coordinate systems at runtime:
+
+```ruby
+Geodetic::Coordinate.systems
+# => [Geodetic::Coordinate::LLA, Geodetic::Coordinate::ECEF, Geodetic::Coordinate::UTM, ...]
+
+# Get short names
+Geodetic::Coordinate.systems.map { |c| c.name.split('::').last }
+# => ["LLA", "ECEF", "UTM", "ENU", "NED", "MGRS", "USNG", "WebMercator",
+#     "UPS", "StatePlane", "BNG", "GH36", "GH", "HAM", "OLC", "GEOREF", "GARS", "H3"]
 ```
 
 ### Coordinate Conversions
@@ -185,9 +202,9 @@ Universal distance methods work across all coordinate types and return `Distance
 **Instance method `distance_to`** — Vincenty great-circle distance:
 
 ```ruby
-seattle = GCS::LLA.new(lat: 47.6205, lng: -122.3493, alt: 0.0)
-portland = GCS::LLA.new(lat: 45.5152, lng: -122.6784, alt: 0.0)
-sf = GCS::LLA.new(lat: 37.7749, lng: -122.4194, alt: 0.0)
+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)
+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
@@ -201,23 +218,23 @@ seattle.distance_to([portland, sf])       # => [Distance, Distance] (radial)
 **Class method `distance_between`** — consecutive chain distances:
 
 ```ruby
-GCS.distance_between(seattle, portland)        # => Distance
-GCS.distance_between(seattle, portland, sf)    # => [Distance, Distance] (chain)
-GCS.distance_between([seattle, portland, sf])  # => [Distance, Distance] (chain)
+Geodetic::Coordinate.distance_between(seattle, portland)        # => Distance
+Geodetic::Coordinate.distance_between(seattle, portland, sf)    # => [Distance, Distance] (chain)
+Geodetic::Coordinate.distance_between([seattle, portland, sf])  # => [Distance, Distance] (chain)
 ```
 
 **Straight-line (ECEF Euclidean) versions:**
 
 ```ruby
 seattle.straight_line_distance_to(portland)              # => Distance
-GCS.straight_line_distance_between(seattle, portland)    # => Distance
+Geodetic::Coordinate.straight_line_distance_between(seattle, portland)    # => Distance
 ```
 
 **Cross-system distances** — works between any coordinate types:
 
 ```ruby
 utm = seattle.to_utm
-mgrs = GCS::MGRS.from_lla(portland)
+mgrs = Geodetic::Coordinate::MGRS.from_lla(portland)
 utm.distance_to(mgrs)    # => Distance
 ```
 
@@ -230,8 +247,8 @@ Universal bearing methods work across all coordinate types and return `Bearing`
 **Instance method `bearing_to`** — great-circle forward azimuth:
 
 ```ruby
-seattle = GCS::LLA.new(lat: 47.6205, lng: -122.3493, alt: 0.0)
-portland = GCS::LLA.new(lat: 45.5152, lng: -122.6784, alt: 0.0)
+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
@@ -245,8 +262,8 @@ b.to_s                            # => "188.2036°"
 **Instance method `elevation_to`** — vertical look angle:
 
 ```ruby
-a = GCS::LLA.new(lat: 47.62, lng: -122.35, alt: 0.0)
-b = GCS::LLA.new(lat: 47.62, lng: -122.35, alt: 5000.0)
+a = Geodetic::Coordinate::LLA.new(lat: 47.62, lng: -122.35, alt: 0.0)
+b = Geodetic::Coordinate::LLA.new(lat: 47.62, lng: -122.35, alt: 5000.0)
 
 a.elevation_to(b)   # => 89.9... (degrees, nearly straight up)
 ```
@@ -254,15 +271,15 @@ a.elevation_to(b)   # => 89.9... (degrees, nearly straight up)
 **Class method `bearing_between`** — consecutive chain bearings:
 
 ```ruby
-GCS.bearing_between(seattle, portland)        # => Bearing
-GCS.bearing_between(seattle, portland, sf)    # => [Bearing, Bearing] (chain)
+Geodetic::Coordinate.bearing_between(seattle, portland)        # => Bearing
+Geodetic::Coordinate.bearing_between(seattle, portland, sf)    # => [Bearing, Bearing] (chain)
 ```
 
 **Cross-system bearings** — works between any coordinate types:
 
 ```ruby
 utm = seattle.to_utm
-mgrs = GCS::MGRS.from_lla(portland)
+mgrs = Geodetic::Coordinate::MGRS.from_lla(portland)
 utm.bearing_to(mgrs)    # => Bearing
 ```
 
@@ -405,9 +422,6 @@ gh36 = lla.to_gh36(precision: 8)
 # Decode back to LLA
 lla = gh36.to_lla
 
-# URL slug (the hash itself is URL-safe)
-gh36.to_slug    # => "bdrdC26BqH"
-
 # Neighbor cells
 gh36.neighbors  # => { N: GH36, S: GH36, E: GH36, W: GH36, NE: ..., NW: ..., SE: ..., SW: ... }
 
@@ -435,9 +449,6 @@ gh = lla.to_gh(precision: 8)
 # Decode back to LLA
 lla = gh.to_lla
 
-# URL slug (the hash itself is URL-safe)
-gh.to_slug    # => "dr5ru7"
-
 # Neighbor cells
 gh.neighbors  # => { N: GH, S: GH, E: GH, W: GH, NE: ..., NW: ..., SE: ..., SW: ... }
 
@@ -531,6 +542,76 @@ rect.sw             # => computed SW corner
 rect.includes?(point)  # => true/false
 ```
 
+### Paths
+
+`Path` is a directed, ordered sequence of unique coordinates representing routes, trails, or boundaries.
+
+```ruby
+route = Path.new(coordinates: [battery_park, wall_street, brooklyn_bridge, city_hall])
+
+# Navigation
+route.first                      # => starting waypoint
+route.next(wall_street)          # => brooklyn_bridge
+route.total_distance.to_km       # => "3.42 km"
+
+# Build incrementally
+trail = Path.new
+trail << start << middle << finish
+trail >> new_start               # prepend
+
+# Combine paths
+combined = downtown + uptown     # concatenate
+trimmed  = combined - detour     # remove coordinates
+
+# Closest approach (geometric projection, not just waypoints)
+route.closest_coordinate_to(off_path_point)
+route.distance_to(target)
+route.closest_points_to(other_path)  # path-to-path
+
+# Spatial operations
+sub = route.between(a, b)        # extract subpath
+left, right = route.split_at(c)  # split at waypoint
+route.at_distance(Distance.km(2)) # interpolate along path
+route.bounds                     # => Areas::Rectangle
+route.to_polygon                 # close into polygon
+route.intersects?(other_path)    # crossing detection
+route.contains?(point)           # on-segment check
+
+# Enumerable
+route.map { |c| c.lat }
+route.select { |c| c.lat > 40.72 }
+```
+
+### Features
+
+`Feature` wraps a geometry (any coordinate, area, or path) with a label and a metadata hash. It delegates `distance_to` and `bearing_to` to its geometry, using the centroid for area geometries.
+
+```ruby
+liberty = Feature.new(
+  label:    "Statue of Liberty",
+  geometry: Coordinates::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),
+  metadata: { category: "building", floors: 102 }
+)
+
+liberty.distance_to(empire).to_km   # => "8.24 km"
+liberty.bearing_to(empire).degrees  # => 36.99
+
+# Area geometries use the centroid for distance/bearing
+park = Feature.new(
+  label:    "Central Park",
+  geometry: Areas::Polygon.new(boundary: [...])
+)
+park.distance_to(liberty).to_km     # => "12.47 km"
+```
+
+All three attributes (`label`, `geometry`, `metadata`) are mutable.
+
 ### Web Mercator Tile Coordinates
 
 ```ruby
@@ -559,6 +640,8 @@ The [`examples/`](examples/) directory contains runnable demo scripts showing pr
 | [`02_all_coordinate_systems.rb`](examples/02_all_coordinate_systems.rb) | All 18 coordinate systems, cross-system chains, and areas |
 | [`03_distance_calculations.rb`](examples/03_distance_calculations.rb) | Distance class features, unit conversions, and arithmetic |
 | [`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 |
 
 Run any example with:
 

data/docs/coordinate-systems/gars.md

@@ -141,10 +141,6 @@ coord.to_s(6)    # => "006AG3"
 coord.to_s(5)    # => "006AG"
 ```
 
-### `to_slug`
-
-Alias for `to_s`. GARS codes are already URL-safe.
-
 ### `to_a`
 
 Returns `[lat, lng]` of the cell midpoint.

data/docs/coordinate-systems/georef.md

@@ -122,10 +122,6 @@ coord.to_s(4)    # => "GJPJ"
 coord.to_s(2)    # => "GJ"
 ```
 
-### `to_slug`
-
-Alias for `to_s`. GEOREF codes are already URL-safe.
-
 ### `to_a`
 
 Returns `[lat, lng]` of the cell midpoint.

data/docs/coordinate-systems/gh.md

@@ -110,10 +110,6 @@ coord.to_s       # => "dr5ru7c5g200"
 coord.to_s(6)    # => "dr5ru7"
 ```
 
-### `to_slug`
-
-Alias for `to_s`. The geohash is already URL-safe.
-
 ### `to_a`
 
 Returns `[lat, lng]` of the cell midpoint.

data/docs/coordinate-systems/gh36.md

@@ -105,10 +105,6 @@ coord.to_s       # => "bdrdC26BqH"
 coord.to_s(5)    # => "bdrdC"
 ```
 
-### `to_slug`
-
-Alias for `to_s`. The geohash is already URL-safe.
-
 ### `to_a`
 
 Returns `[lat, lng]` of the cell midpoint.

data/docs/coordinate-systems/h3.md

@@ -174,10 +174,6 @@ coord.to_s(:integer)   # => 608693941536498687
 coord.h3_index         # => 608693941536498687
 ```
 
-### `to_slug`
-
-Alias for `to_s`. H3 hex strings are already URL-safe.
-
 ### `to_a`
 
 Returns `[lat, lng]` of the cell centroid.

data/docs/coordinate-systems/ham.md

@@ -118,10 +118,6 @@ coord.to_s(6)    # => "FN31pr"
 coord.to_s(4)    # => "FN31"
 ```
 
-### `to_slug`
-
-Alias for `to_s`. The locator is already URL-safe.
-
 ### `to_a`
 
 Returns `[lat, lng]` of the cell midpoint.

data/docs/coordinate-systems/index.md

@@ -84,9 +84,9 @@ Every coordinate system can convert to every other coordinate system. The table
 
 ## Universal Distance and Bearing Calculations
 
-All coordinate systems support universal distance calculations via `distance_to` (Vincenty great-circle) and `straight_line_distance_to` (ECEF Euclidean). These methods work across different coordinate types -- for example, computing the distance from a UTM coordinate to an MGRS coordinate. Class-level methods `GCS.distance_between` and `GCS.straight_line_distance_between` compute consecutive chain distances across a sequence of coordinates.
+All coordinate systems support universal distance calculations via `distance_to` (Vincenty great-circle) and `straight_line_distance_to` (ECEF Euclidean). These methods work across different coordinate types -- for example, computing the distance from a UTM coordinate to an MGRS coordinate. Class-level methods `Geodetic::Coordinate.distance_between` and `Geodetic::Coordinate.straight_line_distance_between` compute consecutive chain distances across a sequence of coordinates.
 
-All coordinate systems also support universal bearing calculations via `bearing_to` (great-circle forward azimuth) and `elevation_to` (vertical look angle). These return `Bearing` and `Float` objects respectively. The class-level method `GCS.bearing_between` computes consecutive chain bearings.
+All coordinate systems also support universal bearing calculations via `bearing_to` (great-circle forward azimuth) and `elevation_to` (vertical look angle). These return `Bearing` and `Float` objects respectively. The class-level method `Geodetic::Coordinate.bearing_between` computes consecutive chain bearings.
 
 See the [Conversions Reference](../reference/conversions.md#distance-calculations) for details on distances and [Bearing Calculations](../reference/conversions.md#bearing-calculations) for bearings.
 

data/docs/coordinate-systems/olc.md

@@ -123,10 +123,6 @@ coord.to_s(8)    # => "849VCWC8+"
 coord.to_s(4)    # => "84900000+"
 ```
 
-### `to_slug`
-
-Alias for `to_s`. Plus codes are already URL-safe.
-
 ### `to_a`
 
 Returns `[lat, lng]` of the cell midpoint.

data/docs/index.md

@@ -15,6 +15,8 @@
 <li><strong>Bearing Calculations</strong> - Forward azimuth, back azimuth, compass directions, elevation angles<br>
 <li><strong>Geoid Height Support</strong> - EGM96, EGM2008, GEOID18, GEOID12B models<br>
 <li><strong>Geographic Areas</strong> - Circle, Polygon, and Rectangle with point-in-area tests<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>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>
@@ -56,12 +58,15 @@ Geodetic supports full bidirectional conversion between all 18 coordinate system
 - **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`, and `Geodetic::Areas::Rectangle` for point-in-area testing.
+- **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.
 
 ## Design Principles
 
 - All constructors use **keyword arguments** for clarity.
 - Every coordinate system supports **serialization** via `to_s` and `to_a`, and **deserialization** via `from_string` and `from_array`.
 - Conversions are available as instance methods (`to_ecef`, `to_utm`, etc.) and class-level factory methods (`from_ecef`, `from_utm`, etc.).
+- All registered coordinate systems are discoverable at runtime via `Geodetic::Coordinate.systems`.
 
 ## Quick Example
 

data/docs/reference/conversions.md

@@ -240,31 +240,31 @@ Universal distance methods are available on all coordinate types and work across
 ### Great-Circle Distance (Vincenty)
 
 - **`distance_to(other, *others)`** — Instance method. Computes the Vincenty great-circle distance from the receiver to one or more target coordinates. Returns a `Distance` for a single target, or an Array of `Distance` objects for multiple targets (radial distances from the receiver).
-- **`GCS.distance_between(*coords)`** — Class method on `Geodetic::Coordinate` (aliased as `GCS`). Computes consecutive chain distances between an ordered sequence of coordinates. Returns a `Distance` for two coordinates, or an Array of `Distance` objects for three or more.
+- **`Geodetic::Coordinate.distance_between(*coords)`** — Class method on `Geodetic::Coordinate`. Computes consecutive chain distances between an ordered sequence of coordinates. Returns a `Distance` for two coordinates, or an Array of `Distance` objects for three or more.
 
 > **`Distance` objects** wrap a distance value and provide unit-aware access. Call `.meters` to get the raw Float value in meters, or `.to_f` to get the value in the current display unit.
 
 ```ruby
-seattle = GCS::LLA.new(lat: 47.6205, lng: -122.3493, alt: 0.0)
-portland = GCS::LLA.new(lat: 45.5152, lng: -122.6784, alt: 0.0)
-sf = GCS::LLA.new(lat: 37.7749, lng: -122.4194, alt: 0.0)
+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)
+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, sf)      # => [Distance, Distance] (Array)
 
 # Consecutive chain distances
-GCS.distance_between(seattle, portland, sf)  # => [Distance, Distance] (Array)
+Geodetic::Coordinate.distance_between(seattle, portland, sf)  # => [Distance, Distance] (Array)
 ```
 
 ### Straight-Line Distance (ECEF Euclidean)
 
 - **`straight_line_distance_to(other, *others)`** — Instance method. Computes the Euclidean distance in ECEF (3D Cartesian) space. Returns a `Distance` for a single target, or an Array of `Distance` objects for multiple targets.
-- **`GCS.straight_line_distance_between(*coords)`** — Class method. Computes consecutive chain Euclidean distances.
+- **`Geodetic::Coordinate.straight_line_distance_between(*coords)`** — Class method. Computes consecutive chain Euclidean distances.
 
 ```ruby
 seattle.straight_line_distance_to(portland)              # => Distance
-GCS.straight_line_distance_between(seattle, portland)    # => Distance
+Geodetic::Coordinate.straight_line_distance_between(seattle, portland)    # => Distance
 ```
 
 ### Cross-System Distances
@@ -273,7 +273,7 @@ Both `distance_to` and `straight_line_distance_to` accept any coordinate type. C
 
 ```ruby
 utm = seattle.to_utm
-mgrs = GCS::MGRS.from_lla(portland)
+mgrs = Geodetic::Coordinate::MGRS.from_lla(portland)
 utm.distance_to(mgrs)    # => Distance (235393.17 m)
 ```
 
@@ -282,7 +282,7 @@ utm.distance_to(mgrs)    # => Distance (235393.17 m)
 ENU and NED are relative coordinate systems and do not support `distance_to` or `straight_line_distance_to` directly. Convert to an absolute system first:
 
 ```ruby
-ref = GCS::LLA.new(lat: 47.62, lng: -122.35, alt: 0.0)
+ref = Geodetic::Coordinate::LLA.new(lat: 47.62, lng: -122.35, alt: 0.0)
 lla = enu.to_lla(ref)
 lla.distance_to(other_lla)
 ```
@@ -299,12 +299,12 @@ Universal bearing methods are available on all coordinate types and work across
 
 - **`bearing_to(other)`** — Instance method. Computes the great-circle forward azimuth from the receiver to the target coordinate. Returns a `Bearing` object.
 - **`elevation_to(other)`** — Instance method. Computes the vertical look angle (elevation) from the receiver to the target. Returns a Float in degrees (-90 to +90).
-- **`GCS.bearing_between(*coords)`** — Class method on `Geodetic::Coordinate` (aliased as `GCS`). Computes consecutive chain bearings between an ordered sequence of coordinates. Returns a `Bearing` for two coordinates, or an Array of `Bearing` objects for three or more.
+- **`Geodetic::Coordinate.bearing_between(*coords)`** — Class method on `Geodetic::Coordinate`. Computes consecutive chain bearings between an ordered sequence of coordinates. Returns a `Bearing` for two coordinates, or an Array of `Bearing` objects for three or more.
 
 ```ruby
-seattle = GCS::LLA.new(lat: 47.6205, lng: -122.3493, alt: 0.0)
-portland = GCS::LLA.new(lat: 45.5152, lng: -122.6784, alt: 0.0)
-sf = GCS::LLA.new(lat: 37.7749, lng: -122.4194, alt: 0.0)
+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)
+sf = Geodetic::Coordinate::LLA.new(lat: 37.7749, lng: -122.4194, alt: 0.0)
 
 # Forward azimuth
 b = seattle.bearing_to(portland)       # => Bearing
@@ -316,7 +316,7 @@ b.reverse                             # => Bearing (back azimuth)
 seattle.elevation_to(portland)         # => Float (degrees)
 
 # Consecutive chain bearings
-GCS.bearing_between(seattle, portland, sf)  # => [Bearing, Bearing]
+Geodetic::Coordinate.bearing_between(seattle, portland, sf)  # => [Bearing, Bearing]
 ```
 
 ### Cross-System Bearings
@@ -325,7 +325,7 @@ GCS.bearing_between(seattle, portland, sf)  # => [Bearing, Bearing]
 
 ```ruby
 utm = seattle.to_utm
-mgrs = GCS::MGRS.from_lla(portland)
+mgrs = Geodetic::Coordinate::MGRS.from_lla(portland)
 utm.bearing_to(mgrs)    # => Bearing
 ```
 

data/docs/reference/feature.md

@@ -0,0 +1,117 @@
+# Feature Reference
+
+`Geodetic::Feature` wraps a geometry with a human-readable label and an arbitrary metadata hash. It provides a single object that ties spatial data to application-level information like names, categories, and display properties.
+
+---
+
+## Constructor
+
+```ruby
+Feature.new(
+  label:    "Statue of Liberty",
+  geometry: Geodetic::Coordinate::LLA.new(lat: 40.6892, lng: -74.0445, alt: 0),
+  metadata: { category: "monument", year: 1886 }
+)
+```
+
+The `geometry` parameter accepts any coordinate class, any area class (`Circle`, `Polygon`, `Rectangle`), or a `Path`. The `metadata` hash is optional and defaults to `{}`.
+
+---
+
+## Attributes
+
+| Attribute  | Type   | Mutable | Description |
+|------------|--------|---------|-------------|
+| `label`    | String | Yes     | A display name for the feature |
+| `geometry` | Object | Yes     | A coordinate or area object |
+| `metadata` | Hash   | Yes     | Arbitrary key-value pairs |
+
+All three attributes have both reader and writer methods.
+
+---
+
+## Geometry Types
+
+A Feature's geometry can be any of:
+
+- **Coordinate** — any of the 18 coordinate classes (`LLA`, `ECEF`, `UTM`, etc.)
+- **Area** — `Areas::Circle`, `Areas::Polygon`, or `Areas::Rectangle`
+- **Path** — a `Geodetic::Path` representing a route or trail
+
+When the geometry is an area, `distance_to` and `bearing_to` use the area's `centroid` as the reference point. When the geometry is a Path, `distance_to` and `bearing_to` use geometric projection to find the closest approach point on the path.
+
+---
+
+## Methods
+
+### `distance_to(other)`
+
+Returns a `Geodetic::Distance` between this feature and another feature, coordinate, or area. When either side is an area geometry, its centroid is used.
+
+The `other` parameter can be a `Feature`, a coordinate, or an area.
+
+```ruby
+liberty = Feature.new(label: "Liberty", geometry: LLA.new(lat: 40.6892, lng: -74.0445, alt: 0))
+empire  = Feature.new(label: "Empire",  geometry: LLA.new(lat: 40.7484, lng: -73.9857, alt: 0))
+
+liberty.distance_to(empire).to_km   # => "8.24 km"
+
+# Also works with a raw coordinate
+liberty.distance_to(LLA.new(lat: 40.7484, lng: -73.9857, alt: 0))
+```
+
+### `bearing_to(other)`
+
+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).to_compass   # => "NE"
+```
+
+### `to_s`
+
+Returns `"label (geometry.to_s)"`.
+
+```ruby
+liberty.to_s  # => "Liberty (40.689200, -74.044500, 0.00)"
+```
+
+### `inspect`
+
+Returns a detailed string with label, geometry, and metadata.
+
+```ruby
+liberty.inspect
+# => "#<Geodetic::Feature name=\"Liberty\" geometry=#<Geodetic::Coordinate::LLA ...> metadata={}>"
+```
+
+---
+
+## Area Geometry Example
+
+```ruby
+park_boundary = Areas::Polygon.new(boundary: [
+  LLA.new(lat: 40.7679, lng: -73.9818, alt: 0),
+  LLA.new(lat: 40.7649, lng: -73.9727, alt: 0),
+  LLA.new(lat: 40.8003, lng: -73.9494, alt: 0),
+  LLA.new(lat: 40.8008, lng: -73.9585, alt: 0),
+])
+
+park = Feature.new(label: "Central Park", geometry: park_boundary)
+
+# distance_to uses the polygon's centroid
+park.distance_to(liberty)   # => Distance
+park.bearing_to(liberty)    # => Bearing
+```
+
+---
+
+## Centroid Resolution
+
+When computing distances and bearings, Feature resolves the underlying point as follows:
+
+- If the geometry responds to `centroid` (all area classes do), the centroid is used.
+- Otherwise, the geometry itself is used directly (all coordinate classes).
+
+This applies to both the source feature and the target. When the target is a Feature, its geometry is resolved the same way. When the target is a raw coordinate or area, the same logic applies.