geodetic 0.2.0 → 0.3.1

data/docs/coordinate-systems/index.md

@@ -1,6 +1,6 @@
 # Coordinate Systems Overview
 
-The Geodetic gem supports 17 coordinate systems organized into six categories. All coordinate classes live under `Geodetic::Coordinate`.
+The Geodetic gem supports 18 coordinate systems organized into six categories. All coordinate classes live under `Geodetic::Coordinate`.
 
 ## Global Systems
 
@@ -46,6 +46,7 @@ The Geodetic gem supports 17 coordinate systems organized into six categories. A
 | **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). |
 
 ## Regional Systems
 
@@ -60,31 +61,32 @@ The Geodetic gem supports 17 coordinate systems organized into six categories. A
 
 Every coordinate system can convert to every other coordinate system. The table below confirms full interoperability:
 
-| From \ To | LLA | ECEF | UTM | ENU | NED | MGRS | USNG | WebMercator | UPS | StatePlane | BNG | GH36 | GH | HAM | OLC | GEOREF | GARS |
-|-----------|-----|------|-----|-----|-----|------|------|-------------|-----|------------|-----|------|----|----|-----|--------|------|
-| **LLA**        | --  | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y |
-| **ECEF**       | Y | --  | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y |
-| **UTM**        | Y | Y | --  | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y |
-| **ENU**        | Y | Y | Y | --  | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y |
-| **NED**        | Y | Y | Y | Y | --  | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y |
-| **MGRS**       | Y | Y | Y | Y | Y | --  | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y |
-| **USNG**       | Y | Y | Y | Y | Y | Y | --  | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y |
-| **WebMercator**| Y | Y | Y | Y | Y | Y | Y | --  | Y | Y | Y | Y | Y | Y | Y | Y | Y |
-| **UPS**        | Y | Y | Y | Y | Y | Y | Y | Y | --  | Y | Y | Y | Y | Y | Y | Y | Y |
-| **StatePlane** | Y | Y | Y | Y | Y | Y | Y | Y | Y | --  | Y | Y | Y | Y | Y | Y | Y |
-| **BNG**        | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | --  | Y | Y | Y | Y | Y | Y |
-| **GH36**       | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | --  | Y | Y | Y | Y | Y |
-| **GH**         | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | -- | Y | Y | Y | Y |
-| **HAM**        | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | -- | Y | Y | Y |
-| **OLC**        | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | -- | Y | Y |
-| **GEOREF**     | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | -- | Y |
-| **GARS**       | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | -- |
+| From \ To | LLA | ECEF | UTM | ENU | NED | MGRS | USNG | WebMercator | UPS | StatePlane | BNG | GH36 | GH | HAM | OLC | GEOREF | GARS | H3 |
+|-----------|-----|------|-----|-----|-----|------|------|-------------|-----|------------|-----|------|----|----|-----|--------|------|-----|
+| **LLA**        | --  | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y |
+| **ECEF**       | Y | --  | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y |
+| **UTM**        | Y | Y | --  | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y |
+| **ENU**        | Y | Y | Y | --  | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y |
+| **NED**        | Y | Y | Y | Y | --  | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y |
+| **MGRS**       | Y | Y | Y | Y | Y | --  | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y |
+| **USNG**       | Y | Y | Y | Y | Y | Y | --  | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y |
+| **WebMercator**| Y | Y | Y | Y | Y | Y | Y | --  | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y |
+| **UPS**        | Y | Y | Y | Y | Y | Y | Y | Y | --  | Y | Y | Y | Y | Y | Y | Y | Y | Y |
+| **StatePlane** | Y | Y | Y | Y | Y | Y | Y | Y | Y | --  | Y | Y | Y | Y | Y | Y | Y | Y |
+| **BNG**        | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | --  | Y | Y | Y | Y | Y | Y | Y |
+| **GH36**       | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | --  | Y | Y | Y | Y | Y | Y |
+| **GH**         | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | -- | Y | Y | Y | Y | Y |
+| **HAM**        | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | -- | Y | Y | Y | Y |
+| **OLC**        | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | -- | Y | Y | Y |
+| **GEOREF**     | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | -- | Y | Y |
+| **GARS**       | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | -- | Y |
+| **H3**         | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | -- |
 
 ## 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.
 
@@ -98,6 +100,6 @@ Conversions typically route through **LLA** or **ECEF** as intermediate steps:
 - **ECEF** is the intermediate for local tangent plane systems (ENU, NED), since the rotation from global Cartesian to local frames is straightforward in ECEF.
 - **ENU and NED** convert between each other directly by reordering axes and inverting the vertical component.
 - **MGRS and USNG** route through UTM, which in turn routes through LLA.
-- **WebMercator, UPS, BNG, StatePlane, GH36, GH, HAM, OLC, GEOREF, and GARS** all convert through LLA.
+- **WebMercator, UPS, BNG, StatePlane, GH36, GH, HAM, OLC, GEOREF, GARS, and H3** all convert through LLA.
 
 For example, converting from BNG to NED follows the chain: `BNG -> LLA -> ECEF -> ENU -> NED`. The gem handles this automatically when you call a conversion method.

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

@@ -9,12 +9,13 @@
 <td width="50%" valign="top">
 <h2>Key Features</h2>
 <lu>
-<li><strong>17 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<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>
 <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>
@@ -24,11 +25,11 @@
 </tr>
 </table>
 
-Geodetic is a Ruby gem for converting between geodetic coordinate systems. It provides a clean, consistent API for working with 17 coordinate systems, 16 geodetic datums, geoid height calculations, and geographic area computations.
+Geodetic is a Ruby gem for converting between geodetic coordinate systems. It provides a clean, consistent API for working with 18 coordinate systems, 16 geodetic datums, geoid height calculations, and geographic area computations.
 
 ## Coordinate Systems
 
-Geodetic supports full bidirectional conversion between all 17 coordinate systems:
+Geodetic supports full bidirectional conversion between all 18 coordinate systems:
 
 | System | Class | Description |
 |--------|-------|-------------|
@@ -49,18 +50,21 @@ Geodetic supports full bidirectional conversion between all 17 coordinate system
 | **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`) |
 
 ## 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`, 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 ────────────────────────────────────────────

data/examples/04_bearing_calculations.rb

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

data/examples/05_map_rendering/.gitignore

@@ -0,0 +1,2 @@
+tmp/
+/nyc_landmarks.png