geodetic 0.3.0 → 0.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6d81eb7c69d9aff7d512562f54e2413c91c8ff10b2361c9143a8afd0c1af0ca0
-  data.tar.gz: e7fb09dd1f7d4d97f57ea48f9cacb0e6afbd30abedab1aa04cbf1153c2fe4373
+  metadata.gz: 13b2b50f8ff03c2093abf1a2454f3db38942f9c32918eb23aab30b6c45a4146b
+  data.tar.gz: 2b3d5a7f325e2766196d2997e9c1781f0425abe016edeeb2fe4f155fc6a43f13
 SHA512:
-  metadata.gz: 90a2e1b8bbc1c6bdf59c7e326d4965f8ec85a16682bccba948fd1f104d7818a5fa34ee179fa00de0221cbfd0e9d9afbd5c667aac46c1a6c9c070b338618b461a
-  data.tar.gz: 85b40d6e961ec4782a9748232eed4191df1dd8a5f22df77afe68c63d64b6b23df0e8ff5ec4ae927038d60919a7825e09c2429bbd4aa8d4447b1737ff81aa4dfd
+  metadata.gz: 1d0378c9df0e04f9bb3de688303abae35857c4fbc594a26094a983417baa55004ef7f7f4cef7c8db7511b8fc769d0a368420e7601cb04e12eaf887b324e51e61
+  data.tar.gz: c20dd6fa952579d8d035e1afd146d7337caa087efd71df4db17dcc3918b8cb4c561237f1cb5820167d9f84a64209da48a1dd38d0b46a5bccf0e3ce6959aa06d3

data/CHANGELOG.md

@@ -11,21 +11,46 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## [Unreleased]
 
 
-## [0.2.0] - 2026-03-08
+## [0.3.1] - 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::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,7 @@
 - <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>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 +78,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 +201,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 +217,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 +246,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 +261,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 +270,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 +421,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 +448,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 +541,36 @@ rect.sw             # => computed SW corner
 rect.includes?(point)  # => true/false
 ```
 
+### Features
+
+`Feature` wraps a geometry (any coordinate or area) 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 +599,7 @@ 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) |
 
 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,7 @@
 <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>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 +57,14 @@ 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.
+- **Features** -- `Geodetic::Feature` wraps any coordinate or area 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,116 @@
+# 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 or any area class (`Circle`, `Polygon`, `Rectangle`). 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`
+
+When the geometry is an area, `distance_to` and `bearing_to` use the area's `centroid` as the reference point.
+
+---
+
+## 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.

data/docs/reference/map-rendering.md

@@ -0,0 +1,32 @@
+# Map Rendering with libgd-gis
+
+Geodetic coordinates and areas can be rendered on raster maps using the [libgd-gis](https://rubygems.org/gems/libgd-gis) gem, which provides tile-based basemap rendering on top of [ruby-libgd](https://rubygems.org/gems/ruby-libgd).
+
+## Overview
+
+The `libgd-gis` gem downloads map tiles and stitches them into a single raster image for a given bounding box and zoom level. Geodetic's coordinate objects provide the geographic data, and `GD::GIS::Geometry.project` converts longitude/latitude pairs into pixel positions on the rendered map. From there, ruby-libgd primitives (lines, circles, polygons, text, image compositing) can draw overlays on top of the basemap.
+
+This combination supports:
+
+- **Point markers** for any Geodetic coordinate
+- **Polygon overlays** from `Geodetic::Areas::Polygon` boundaries
+- **Bearing arrows** computed with `Feature#bearing_to` and drawn as lines with arrowheads
+- **Distance labels** using `Feature#distance_to` for annotation
+- **Icon compositing** with scaled PNG images positioned at projected coordinates
+- **Light and dark basemaps** via `:carto_light` and `:carto_dark`
+
+## Feature Class
+
+`Geodetic::Feature` wraps a geometry (any coordinate or area) with a label and a metadata hash. It delegates `distance_to` and `bearing_to` to its geometry, using the centroid for area geometries. This makes it straightforward to attach display properties like icon paths and categories alongside the spatial data.
+
+## Prerequisites
+
+```bash
+gem install libgd-gis
+brew install gd   # macOS
+# apt install libgd-dev   # Linux
+```
+
+## Example
+
+See [`examples/05_map_rendering/demo.rb`](https://github.com/madbomber/geodetic/tree/main/examples/05_map_rendering) for a complete working demo that renders NYC landmarks with icons, a Central Park polygon boundary, and bearing arrows between landmarks. The demo supports light/dark themes, icon scaling, and CLI flags for toggling features.

data/docs/reference/serialization.md

@@ -254,7 +254,7 @@ restored = Geodetic::Coordinate::LLA.from_dms(dms_string)
 | StatePlane | `easting, northing, zone_code` | 2 | `[easting, northing, zone_code]` | -- |
 | MGRS | `grid_zone+square+coords` | n/a | `[grid_zone, square_id, easting, northing, precision]` | String-based |
 | USNG | `grid_zone square coords` | n/a | `[grid_zone, square_id, easting, northing, precision]` | `to_full_format`, `to_abbreviated_format` |
-| GH36 | geohash string | n/a | `[lat, lng]` | `to_slug`, `to_area`, `neighbors` |
-| GH | geohash string | n/a | `[lat, lng]` | `to_slug`, `to_area`, `neighbors` |
-| HAM | locator string | n/a | `[lat, lng]` | `to_slug`, `to_area`, `neighbors` |
-| OLC | plus code string | n/a | `[lat, lng]` | `to_slug`, `to_area`, `neighbors` |
+| GH36 | geohash string | n/a | `[lat, lng]` | `to_area`, `neighbors` |
+| GH | geohash string | n/a | `[lat, lng]` | `to_area`, `neighbors` |
+| HAM | locator string | n/a | `[lat, lng]` | `to_area`, `neighbors` |
+| OLC | plus code string | n/a | `[lat, lng]` | `to_area`, `neighbors` |

data/examples/02_all_coordinate_systems.rb

@@ -161,9 +161,6 @@ def demo_coordinate_systems
   puts "   Precision: #{gh36_coord.precision} chars"
   puts "   Precision in meters: lat=#{gh36_coord.precision_in_meters[:lat].round(3)}m, lng=#{gh36_coord.precision_in_meters[:lng].round(3)}m"
 
-  # URL slug
-  puts "   URL slug: #{gh36_coord.to_slug}"
-
   # Reduced precision
   gh36_short = GH36.new(lla_coord, precision: 5)
   puts "   5-char precision: #{gh36_short.to_s}"

data/examples/03_distance_calculations.rb

@@ -6,6 +6,7 @@
 
 require_relative "../lib/geodetic"
 
+GCS      = Geodetic::Coordinate
 Distance = Geodetic::Distance
 
 # ── Notable locations ────────────────────────────────────────────