geodetic 0.2.0 → 0.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 782ba82d99727dfa9a075fcdfb9dea89f631ebc78e0e105293745c64f77f9dae
-  data.tar.gz: 59e9c844470d77026a9929c8b9ffd01a5d065fd491d8efb67106b0903267c681
+  metadata.gz: 13b2b50f8ff03c2093abf1a2454f3db38942f9c32918eb23aab30b6c45a4146b
+  data.tar.gz: 2b3d5a7f325e2766196d2997e9c1781f0425abe016edeeb2fe4f155fc6a43f13
 SHA512:
-  metadata.gz: 38543deb9e8d62aa20b4a90c9602b0e97806d7d2f55dd9d308a138b9aea2b033e6f51656a9d247ce750d5abcd5298f170825a3f0e4f013a63198bc467e1f3d8c
-  data.tar.gz: fcb62fac876d350bd784d08bb17d45b7c14218a31ff6cfcce4be7e384e3f9a6a2c711ae3731b4a4241e5b34c062a8ddcdc2fb8ce6786ac114ff35d872ad8a7f3
+  metadata.gz: 1d0378c9df0e04f9bb3de688303abae35857c4fbc594a26094a983417baa55004ef7f7f4cef7c8db7511b8fc769d0a368420e7601cb04e12eaf887b324e51e61
+  data.tar.gz: c20dd6fa952579d8d035e1afd146d7337caa087efd71df4db17dcc3918b8cb4c561237f1cb5820167d9f84a64209da48a1dd38d0b46a5bccf0e3ce6959aa06d3

data/CHANGELOG.md

@@ -11,6 +11,36 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## [Unreleased]
 
 
+## [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
+- `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

data/README.md

@@ -13,12 +13,13 @@
 <td width="50%" valign="top">
 <strong>Key Features</strong><br>
 
-- <strong>17 Coordinate Systems</strong> - LLA, ECEF, UTM, ENU, NED, MGRS, USNG, Web Mercator, UPS, State Plane, BNG, GH36, GH, HAM, OLC, GEOREF, GARS<br>
+- <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>
 - <strong>Full Bidirectional Conversions</strong> - Every system converts to and from every other system<br>
 - <strong>Distance Calculations</strong> - Vincenty great-circle and straight-line with unit tracking<br>
 - <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>
@@ -27,7 +28,7 @@
 </tr>
 </table>
 
-<p>Geodetic enables precise conversion between geodetic coordinate systems in Ruby. All 17 coordinate systems support complete bidirectional conversions with high precision. Review the <a href="https://madbomber.github.io/geodetic/">full documentation website</a> and explore the <a href="examples/">runnable examples</a>.</p>
+<p>Geodetic enables precise conversion between geodetic coordinate systems in Ruby. All 18 coordinate systems support complete bidirectional conversions with high precision. Review the <a href="https://madbomber.github.io/geodetic/">full documentation website</a> and explore the <a href="examples/">runnable examples</a>.</p>
 
 ## Installation
 
@@ -43,6 +44,20 @@ Or install directly:
 gem install geodetic
 ```
 
+### Optional: H3 Hexagonal Index
+
+The H3 coordinate system requires Uber's [H3 C library](https://h3geo.org/) installed on your system. Without it, all other 17 coordinate systems work normally; H3 operations will raise a helpful error.
+
+```bash
+# macOS
+brew install h3
+
+# Linux (build from source)
+# See https://h3geo.org/docs/installation
+```
+
+You can also set the `LIBH3_PATH` environment variable to point to a custom `libh3` location.
+
 ## Usage
 
 ### Basic Coordinate Creation
@@ -63,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
@@ -171,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
@@ -187,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
 ```
 
@@ -216,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
@@ -231,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)
 ```
@@ -240,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
 ```
 
@@ -391,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: ... }
 
@@ -421,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: ... }
 
@@ -517,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
@@ -542,9 +596,10 @@ The [`examples/`](examples/) directory contains runnable demo scripts showing pr
 | Script | Description |
 |--------|-------------|
 | [`01_basic_conversions.rb`](examples/01_basic_conversions.rb) | LLA, ECEF, UTM, ENU, NED conversions and roundtrips |
-| [`02_all_coordinate_systems.rb`](examples/02_all_coordinate_systems.rb) | All 17 coordinate systems, cross-system chains, and areas |
+| [`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

@@ -0,0 +1,308 @@
+# Geodetic::Coordinate::H3
+
+## H3 Hexagonal Hierarchical Index
+
+H3 is Uber's hierarchical geospatial indexing system that divides the globe into hexagonal cells (and 12 pentagons per resolution level) using an icosahedron projection. Each cell is identified by a 64-bit integer, typically displayed as a 15-character hex string like `872a1072bffffff`.
+
+**H3 requires the `libh3` C library** installed on your system. Without it, all other coordinate systems work normally; H3 operations raise a clear error message with installation instructions.
+
+### Prerequisites
+
+```bash
+# macOS (Homebrew)
+brew install h3
+
+# Linux (build from source)
+git clone https://github.com/uber/h3.git
+cd h3
+cmake -B build -DCMAKE_INSTALL_PREFIX=/usr/local
+cmake --build build
+sudo cmake --install build
+```
+
+You can also set the `LIBH3_PATH` environment variable to specify a custom library path:
+
+```bash
+export LIBH3_PATH=/path/to/libh3.dylib
+```
+
+Geodetic searches these paths automatically:
+- `/opt/homebrew/lib/libh3.dylib` (macOS ARM Homebrew)
+- `/usr/local/lib/libh3.dylib` (macOS Intel Homebrew)
+- `/usr/lib/libh3.so` (Linux system)
+- `/usr/local/lib/libh3.so` (Linux local install)
+
+### Key Differences from Other Spatial Hashes
+
+| Feature | GH/OLC/GARS/GEOREF/HAM | H3 |
+|---------|------------------------|-----|
+| Cell shape | Rectangle | Hexagon (6 vertices) |
+| `to_area` returns | `Areas::Rectangle` | `Areas::Polygon` |
+| `neighbors` returns | Hash with 8 cardinal keys | Array of 6 cells |
+| Code format | String | 64-bit integer (hex string) |
+| Dependency | None (pure Ruby) | `libh3` (C library via fiddle) |
+
+H3 is a **2D coordinate system** (no altitude). Conversions to/from other systems go through LLA as the intermediary. Each hex string represents a hexagonal cell; the coordinate's point value is the cell's centroid.
+
+## Constructor
+
+```ruby
+# From a hex string
+coord = Geodetic::Coordinate::H3.new("872a1072bffffff")
+
+# From a hex string with 0x prefix
+coord = Geodetic::Coordinate::H3.new("0x872a1072bffffff")
+
+# From a 64-bit integer
+coord = Geodetic::Coordinate::H3.new(0x872a1072bffffff)
+
+# From any coordinate (converts via LLA)
+coord = Geodetic::Coordinate::H3.new(lla_coord)
+coord = Geodetic::Coordinate::H3.new(utm_coord, precision: 9)
+```
+
+| Parameter   | Type                    | Default | Description                                |
+|-------------|-------------------------|---------|--------------------------------------------|
+| `source`    | String, Integer, or Coord | --    | An H3 hex string, integer, or coordinate   |
+| `precision` | Integer                 | 7       | H3 resolution level (0-15)                 |
+
+Raises `ArgumentError` if the source string is empty, contains invalid hex characters, or does not represent a valid H3 cell index. String input is case-insensitive (normalized to lowercase). The `0x` prefix is stripped automatically.
+
+## Attributes
+
+| Attribute  | Type    | Access    | Description                     |
+|------------|---------|-----------|----------------------------------|
+| `code`     | String  | read-only | The hex string representation    |
+| `h3_index` | Integer | read-only | The 64-bit H3 cell index         |
+
+H3 is **immutable** -- there are no setter methods.
+
+## Resolution
+
+H3 uses "resolution" (0-15) instead of string-length precision. Higher resolution means smaller cells.
+
+| Resolution | Approximate Cell Area | Approximate Edge Length |
+|------------|----------------------|------------------------|
+| 0          | 4,357,449 km^2       | 1,108 km               |
+| 1          | 609,788 km^2         | 419 km                 |
+| 2          | 86,801 km^2          | 158 km                 |
+| 3          | 12,393 km^2          | 60 km                  |
+| 4          | 1,770 km^2           | 23 km                  |
+| 5          | 252 km^2             | 8.5 km                 |
+| 6          | 36 km^2              | 3.2 km                 |
+| 7          | 5.2 km^2 (default)   | 1.2 km                 |
+| 8          | 0.74 km^2            | 461 m                  |
+| 9          | 0.105 km^2           | 174 m                  |
+| 10         | 0.015 km^2           | 66 m                   |
+| 11         | 0.002 km^2           | 25 m                   |
+| 12         | 307 m^2              | 9.4 m                  |
+| 13         | 43 m^2               | 3.6 m                  |
+| 14         | 6.2 m^2              | 1.3 m                  |
+| 15         | 0.9 m^2              | 0.5 m                  |
+
+```ruby
+coord.resolution             # => 7 (alias: coord.precision)
+coord.cell_area              # => 5182586.98 (square meters)
+coord.precision_in_meters    # => { lat: ~2276, lng: ~2276, area_m2: ~5182586 }
+```
+
+## Checking Availability
+
+```ruby
+Geodetic::Coordinate::H3.available?   # => true if libh3 is found
+```
+
+## Conversions
+
+All conversions chain through LLA. The datum parameter defaults to `Geodetic::WGS84`.
+
+### Instance Methods
+
+```ruby
+coord.to_lla                    # => LLA (centroid of the cell)
+coord.to_ecef
+coord.to_utm
+coord.to_enu(reference_lla)
+coord.to_ned(reference_lla)
+coord.to_mgrs
+coord.to_usng
+coord.to_web_mercator
+coord.to_ups
+coord.to_state_plane(zone_code)
+coord.to_bng
+coord.to_gh36
+coord.to_gh
+coord.to_ham
+coord.to_olc
+coord.to_georef
+coord.to_gars
+```
+
+### Class Methods
+
+```ruby
+H3.from_lla(lla_coord)
+H3.from_ecef(ecef_coord)
+H3.from_utm(utm_coord)
+H3.from_web_mercator(wm_coord)
+H3.from_gh(gh_coord)
+H3.from_georef(georef_coord)
+H3.from_gars(gars_coord)
+# ... and all other coordinate systems
+```
+
+### LLA Convenience Methods
+
+```ruby
+lla = Geodetic::Coordinate::LLA.new(lat: 40.689167, lng: -74.044444)
+h3 = lla.to_h3                    # default resolution 7
+h3 = lla.to_h3(precision: 9)      # resolution 9
+
+lla = Geodetic::Coordinate::LLA.from_h3(h3)
+```
+
+## Serialization
+
+### `to_s(format = nil)`
+
+Returns the hex string. Pass `:integer` to get the 64-bit integer value.
+
+```ruby
+coord = H3.new("872a1072bffffff")
+coord.to_s             # => "872a1072bffffff"
+coord.to_s(:integer)   # => 608693941536498687
+coord.h3_index         # => 608693941536498687
+```
+
+### `to_a`
+
+Returns `[lat, lng]` of the cell centroid.
+
+```ruby
+coord.to_a    # => [40.685..., -74.030...]
+```
+
+### `from_string` / `from_array`
+
+```ruby
+H3.from_string("872a1072bffffff")           # from hex string
+H3.from_array([40.689167, -74.044444])       # from [lat, lng]
+```
+
+## Neighbors
+
+Returns all adjacent cells as an Array of H3 instances. Hexagons have 6 neighbors; pentagons have 5.
+
+Note: unlike the rectangular spatial hashes which return a directional Hash (`:N`, `:S`, etc.), H3 returns a flat Array because hexagonal cells do not have cardinal directions.
+
+```ruby
+coord = H3.new("872a1072bffffff")
+neighbors = coord.neighbors
+# => [H3, H3, H3, H3, H3, H3]
+
+neighbors.length    # => 6
+```
+
+## Grid Disk
+
+The `grid_disk(k)` method returns all cells within `k` steps. This is a generalization of `neighbors` (which is `grid_disk(1)` minus self).
+
+```ruby
+coord.grid_disk(0)     # => [self] (1 cell)
+coord.grid_disk(1)     # => [self + 6 neighbors] (7 cells)
+coord.grid_disk(2)     # => 19 cells
+```
+
+## Parent and Children
+
+Navigate the H3 hierarchy by moving to coarser or finer resolution levels.
+
+```ruby
+coord = H3.new("872a1072bffffff")    # resolution 7
+parent = coord.parent(5)              # => H3 at resolution 5
+parent.resolution                     # => 5
+
+children = coord.children(8)          # => Array of 7 H3 cells at resolution 8
+children.length                       # => 7
+children.first.resolution             # => 8
+```
+
+`parent` raises `ArgumentError` if the target resolution is not coarser (lower number). `children` raises `ArgumentError` if the target resolution is not finer (higher number).
+
+## Area
+
+The `to_area` method returns the hexagonal cell boundary as an `Areas::Polygon` with 6 vertices (5 for pentagons).
+
+```ruby
+area = coord.to_area
+# => Geodetic::Areas::Polygon
+
+area.includes?(coord.to_lla)    # => true (centroid is inside the cell)
+area.boundary.length             # => 7 (6 vertices + closing point)
+```
+
+## Pentagon Detection
+
+12 cells at each resolution level are pentagons (artifacts of the icosahedral projection). These have 5 neighbors and 5 boundary vertices instead of 6.
+
+```ruby
+coord.pentagon?    # => false (most cells are hexagons)
+```
+
+## Cell Area
+
+```ruby
+coord.cell_area    # => 5182586.98 (square meters)
+```
+
+## Equality
+
+Two H3 instances are equal if their hex strings match exactly.
+
+```ruby
+H3.new("872a1072bffffff") == H3.new("872a1072bffffff")       # => true
+H3.new("872a1072bffffff") == H3.new(0x872a1072bffffff)       # => true (integer)
+H3.new("872a1072bffffff") == H3.new("87195da49ffffff")       # => false
+```
+
+## `valid?`
+
+Returns `true` if the H3 cell index is valid according to the H3 library.
+
+```ruby
+coord.valid?    # => true
+```
+
+## Universal Distance and Bearing Methods
+
+H3 supports all universal distance and bearing methods via the `DistanceMethods` and `BearingMethods` mixins:
+
+```ruby
+a = H3.new("872a1072bffffff")     # Statue of Liberty area
+b = H3.new("87195da49ffffff")     # London area
+
+a.distance_to(b)                # => Distance (~5,570 km)
+a.straight_line_distance_to(b)  # => Distance
+a.bearing_to(b)                 # => Bearing
+a.elevation_to(b)               # => Float (degrees)
+```
+
+## Well-Known H3 Cells
+
+| Location | H3 Index (res 7) | Resolution |
+|----------|------------------|------------|
+| Statue of Liberty | `872a1072bffffff` | 7 |
+| London | `87195da49ffffff` | 7 |
+| Null Island (0, 0) | `87754e64dffffff` | 7 |
+
+## Implementation Notes
+
+Geodetic uses Ruby's `fiddle` (part of the standard library) to call the H3 v4 C API directly. No gem dependency beyond `fiddle` is required. The H3 C library must be installed separately.
+
+The library search order is:
+1. `LIBH3_PATH` environment variable
+2. `/opt/homebrew/lib/libh3.dylib` (macOS ARM)
+3. `/usr/local/lib/libh3.dylib` (macOS Intel)
+4. `/usr/lib/libh3.so` (Linux)
+5. `/usr/local/lib/libh3.so` (Linux local)
+6. Architecture-specific Linux paths

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.