geodetic 0.0.1

data/docs/coordinate-systems/ecef.md

@@ -0,0 +1,215 @@
+# Geodetic::Coordinates::ECEF
+
+Earth-Centered, Earth-Fixed -- a Cartesian coordinate system with its origin at the center of mass of the Earth. The X axis points toward the intersection of the Prime Meridian and the Equator, the Y axis points toward 90 degrees East longitude on the Equator, and the Z axis points toward the North Pole. All values are in meters.
+
+ECEF is useful for satellite positioning, radar tracking, and any application requiring a simple Cartesian frame tied to the rotating Earth.
+
+## Constructor
+
+```ruby
+Geodetic::Coordinates::ECEF.new(x: 0.0, y: 0.0, z: 0.0)
+```
+
+| Parameter | Type  | Default | Description                     |
+|-----------|-------|---------|---------------------------------|
+| `x`       | Float | `0.0`   | X coordinate in meters          |
+| `y`       | Float | `0.0`   | Y coordinate in meters          |
+| `z`       | Float | `0.0`   | Z coordinate in meters          |
+
+All values are coerced to `Float` via `.to_f`. There is no range validation -- any real-valued triple is accepted.
+
+## Attributes
+
+| Attribute | Access     |
+|-----------|------------|
+| `x`       | read/write |
+| `y`       | read/write |
+| `z`       | read/write |
+
+## Conversions
+
+All conversion methods accept an optional `datum` parameter (defaults to `Geodetic::WGS84`).
+
+### to_lla(datum = WGS84)
+
+Converts to geodetic Latitude, Longitude, Altitude coordinates using an iterative algorithm. The iteration converges when both latitude and altitude changes are below `1e-12`, with a maximum of 100 iterations.
+
+```ruby
+ecef = Geodetic::Coordinates::ECEF.new(x: 1130730.0, y: -4828583.0, z: 3991570.0)
+lla = ecef.to_lla
+# => Geodetic::Coordinates::LLA
+```
+
+### ECEF.from_lla(lla, datum = WGS84)
+
+Creates an ECEF from an LLA instance. Raises `ArgumentError` if the argument is not an `LLA`.
+
+```ruby
+ecef = Geodetic::Coordinates::ECEF.from_lla(lla)
+```
+
+### to_utm(datum = WGS84)
+
+Converts to Universal Transverse Mercator coordinates. Internally converts to LLA first, then to UTM.
+
+```ruby
+utm = ecef.to_utm
+# => Geodetic::Coordinates::UTM
+```
+
+### ECEF.from_utm(utm, datum = WGS84)
+
+Creates an ECEF from a UTM instance. Raises `ArgumentError` if the argument is not a `UTM`.
+
+### to_enu(reference_ecef, reference_lla = nil)
+
+Converts to East-North-Up local tangent plane coordinates relative to a reference ECEF position. If `reference_lla` is not provided, it is computed from `reference_ecef` via `to_lla`.
+
+```ruby
+ref_ecef = Geodetic::Coordinates::ECEF.new(x: 1130730.0, y: -4828583.0, z: 3991570.0)
+point_ecef = Geodetic::Coordinates::ECEF.new(x: 1130740.0, y: -4828573.0, z: 3991580.0)
+enu = point_ecef.to_enu(ref_ecef)
+# => Geodetic::Coordinates::ENU
+```
+
+Raises `ArgumentError` if `reference_ecef` is not an `ECEF`.
+
+### ECEF.from_enu(enu, reference_ecef, reference_lla = nil)
+
+Creates an ECEF from an ENU instance and a reference ECEF origin. Raises `ArgumentError` if the arguments are not the expected types.
+
+### to_ned(reference_ecef, reference_lla = nil)
+
+Converts to North-East-Down local tangent plane coordinates. Internally converts to ENU first, then swaps axes to NED.
+
+```ruby
+ned = point_ecef.to_ned(ref_ecef)
+# => Geodetic::Coordinates::NED
+```
+
+### ECEF.from_ned(ned, reference_ecef, reference_lla = nil)
+
+Creates an ECEF from a NED instance and a reference ECEF origin. Raises `ArgumentError` if the arguments are not the expected types.
+
+## Serialization
+
+### to_s
+
+Returns a comma-separated string of `x, y, z`.
+
+```ruby
+ecef = Geodetic::Coordinates::ECEF.new(x: 1130730.0, y: -4828583.0, z: 3991570.0)
+ecef.to_s
+# => "1130730.0, -4828583.0, 3991570.0"
+```
+
+### to_a
+
+Returns a three-element array `[x, y, z]`.
+
+```ruby
+ecef.to_a
+# => [1130730.0, -4828583.0, 3991570.0]
+```
+
+### ECEF.from_string(string)
+
+Parses a comma-separated string into an ECEF.
+
+```ruby
+ecef = Geodetic::Coordinates::ECEF.from_string("1130730.0, -4828583.0, 3991570.0")
+```
+
+### ECEF.from_array(array)
+
+Creates an ECEF from a three-element array `[x, y, z]`.
+
+```ruby
+ecef = Geodetic::Coordinates::ECEF.from_array([1130730.0, -4828583.0, 3991570.0])
+```
+
+## Additional Methods
+
+### ==(other)
+
+Compares two ECEF instances for approximate equality. Returns `true` if the absolute difference for each of `x`, `y`, and `z` is `<= 1e-6` meters. Returns `false` if `other` is not an `ECEF`.
+
+```ruby
+a = Geodetic::Coordinates::ECEF.new(x: 1130730.0, y: -4828583.0, z: 3991570.0)
+b = Geodetic::Coordinates::ECEF.new(x: 1130730.0, y: -4828583.0, z: 3991570.0)
+a == b
+# => true
+```
+
+### distance_to(other, *others)
+
+Computes the Vincenty great-circle distance to one or more other coordinates. Accepts any coordinate type (coordinates are converted to LLA internally). Returns a `Distance` for a single target or an Array of `Distance` objects for multiple targets (radial distances from the receiver).
+
+```ruby
+a = Geodetic::Coordinates::ECEF.new(x: 1130730.0, y: -4828583.0, z: 3991570.0)
+b = Geodetic::Coordinates::ECEF.new(x: 1130740.0, y: -4828573.0, z: 3991580.0)
+a.distance_to(b)
+# => Distance (meters, great-circle distance)
+```
+
+### straight_line_distance_to(other, *others)
+
+Computes the Euclidean (straight-line) distance between two points in ECEF space. Accepts any coordinate type (coordinates are converted to ECEF internally). Returns a `Distance` for a single target or an Array of `Distance` objects for multiple targets.
+
+```ruby
+a.straight_line_distance_to(b)
+# => Distance (17.320508075688775 m)
+```
+
+## Code Examples
+
+### Round-trip conversion
+
+```ruby
+require 'geodetic'
+
+# Create an ECEF coordinate
+ecef = Geodetic::Coordinates::ECEF.new(x: 1130730.0, y: -4828583.0, z: 3991570.0)
+
+# Convert to LLA and back
+lla = ecef.to_lla
+ecef_roundtrip = lla.to_ecef
+ecef == ecef_roundtrip
+# => true
+```
+
+### Distance between two points
+
+```ruby
+station_a = Geodetic::Coordinates::ECEF.new(x: 1130730.0, y: -4828583.0, z: 3991570.0)
+station_b = Geodetic::Coordinates::ECEF.new(x: 1131000.0, y: -4828300.0, z: 3991800.0)
+
+# Great-circle distance (Vincenty)
+distance = station_a.distance_to(station_b)
+puts "Great-circle distance: #{distance.meters} meters"
+
+# Straight-line (Euclidean) distance
+straight = station_a.straight_line_distance_to(station_b)
+puts "Straight-line distance: #{straight.meters} meters"
+```
+
+### Local tangent plane from ECEF
+
+```ruby
+origin = Geodetic::Coordinates::ECEF.new(x: 1130730.0, y: -4828583.0, z: 3991570.0)
+target = Geodetic::Coordinates::ECEF.new(x: 1130740.0, y: -4828573.0, z: 3991580.0)
+
+# Provide reference LLA to avoid recomputing it
+ref_lla = origin.to_lla
+
+enu = target.to_enu(origin, ref_lla)
+ned = target.to_ned(origin, ref_lla)
+```
+
+### Using a non-default datum
+
+```ruby
+clarke66 = Geodetic::Datum.new(name: 'CLARKE_1866')
+ecef = Geodetic::Coordinates::ECEF.new(x: 1130730.0, y: -4828583.0, z: 3991570.0)
+lla = ecef.to_lla(clarke66)
+```

data/docs/coordinate-systems/enu.md

@@ -0,0 +1,77 @@
+# Geodetic::Coordinates::ENU - East, North, Up
+
+## Overview
+
+ENU (East, North, Up) is a local tangent plane coordinate system. It defines positions relative to a local reference point on the Earth's surface, with axes pointing East, North, and Up.
+
+## Constructor
+
+```ruby
+ENU.new(e: 0.0, n: 0.0, u: 0.0)
+```
+
+All parameters are in **meters**.
+
+## Attribute Aliases
+
+| Primary | Alias   |
+|---------|---------|
+| `e`     | `east`  |
+| `n`     | `north` |
+| `u`     | `up`    |
+
+## Reference Point
+
+ENU is a local coordinate system. Conversions to and from global coordinate systems (such as LLA or ECEF) require a **reference point** specified as an LLA coordinate. This reference point defines the origin of the local tangent plane.
+
+The one exception is the conversion between ENU and NED, which does not require a reference point.
+
+## Conversions
+
+### Direct (no reference point needed)
+
+- **ENU <-> NED** — A simple axis remap: `ENU(e, n, u)` corresponds to `NED(n, e, -u)`.
+
+### Via reference point
+
+- **ENU -> LLA** — Requires a reference LLA.
+- **ENU -> ECEF** — Requires a reference LLA.
+
+## Methods
+
+| Method                          | Description                                                        |
+|---------------------------------|--------------------------------------------------------------------|
+| `horizontal_distance_to(other)` | Horizontal (E-N plane) distance to another ENU point (meters)      |
+| `local_bearing_to(other)`       | Bearing from this point to another ENU point (degrees from north, 0-360) |
+| `distance_to_origin`            | Euclidean distance from this point to the origin (meters)          |
+| `bearing_from_origin`           | Bearing from the origin to this point (degrees from north, 0-360)  |
+| `horizontal_distance_to_origin` | Horizontal distance from this point to the origin (meters)         |
+
+### Universal Distance and Bearing Methods
+
+ENU is a relative coordinate system. The universal `distance_to`, `straight_line_distance_to`, `bearing_to`, and `elevation_to` methods raise `ArgumentError` because ENU cannot be converted to an absolute system without a reference point. Convert to an absolute system first:
+
+```ruby
+ref = Geodetic::Coordinates::LLA.new(lat: 47.62, lng: -122.35, alt: 0.0)
+lla = enu.to_lla(ref)
+lla.distance_to(other_lla)   # Vincenty great-circle distance
+lla.bearing_to(other_lla)    # Great-circle forward azimuth (Bearing object)
+```
+
+## Bearing Convention
+
+Bearing is measured in **degrees from north**, clockwise, in the range **0-360**.
+
+## Example
+
+```ruby
+point = Geodetic::Coordinates::ENU.new(e: 100.0, n: 200.0, u: 50.0)
+
+point.east   # => 100.0
+point.north  # => 200.0
+point.up     # => 50.0
+
+point.distance_to_origin            # => Euclidean distance in meters
+point.bearing_from_origin           # => Bearing in degrees from north
+point.horizontal_distance_to_origin # => Horizontal distance in meters
+```

data/docs/coordinate-systems/gh36.md

@@ -0,0 +1,192 @@
+# Geodetic::Coordinates::GH36
+
+## Geohash-36
+
+Geohash-36 is a hierarchical spatial hashing algorithm that encodes latitude/longitude into a compact, URL-friendly string using a case-sensitive 36-character alphabet. It uses a 6x6 grid subdivision (radix-36) providing higher precision per character than standard Geohash (radix-32).
+
+Character set: `23456789bBCdDFgGhHjJKlLMnNPqQrRtTVWX`
+(avoids vowels, vowel-like numbers, and ambiguous characters like 0/O, 1/I/l)
+
+GH36 is a **2D coordinate system** (no altitude). Conversions to/from other systems go through LLA as the intermediary. Each geohash string represents a rectangular cell; the coordinate's point value is the cell's midpoint.
+
+## Constructor
+
+```ruby
+# From a geohash string
+coord = Geodetic::Coordinates::GH36.new("bdrdC26BqH")
+
+# From any coordinate (converts via LLA)
+coord = Geodetic::Coordinates::GH36.new(lla_coord)
+coord = Geodetic::Coordinates::GH36.new(utm_coord, precision: 8)
+```
+
+| Parameter   | Type              | Default | Description                                  |
+|-------------|-------------------|---------|----------------------------------------------|
+| `source`    | String or Coord   | —       | A geohash string or any coordinate object    |
+| `precision` | Integer           | 10      | Hash length (ignored when source is a String) |
+
+Raises `ArgumentError` if the source is an empty string, contains invalid characters, or is not a recognized coordinate type.
+
+## Attributes
+
+| Attribute | Type   | Access    | Description                     |
+|-----------|--------|-----------|---------------------------------|
+| `geohash` | String | read-only | The geohash-36 encoded string   |
+
+GH36 is **immutable** — there are no setter methods.
+
+## Precision
+
+The precision (hash length) determines the size of the cell:
+
+| Length | Approximate Resolution |
+|--------|----------------------|
+| 5      | ~1.4 km              |
+| 8      | ~6.5 m               |
+| 10     | ~0.3 m (default)     |
+
+```ruby
+coord.precision              # => 10 (hash length)
+coord.precision_in_meters    # => { lat: 0.31, lng: 0.62 }
+```
+
+Longer hashes yield finer precision. Longitude precision is always coarser than latitude (cells are wider than tall).
+
+## Conversions
+
+All conversions chain through LLA. The datum parameter defaults to `Geodetic::WGS84`.
+
+### Instance Methods
+
+```ruby
+coord.to_lla                    # => LLA (midpoint 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                   # identity (via mixin)
+```
+
+### Class Methods
+
+```ruby
+GH36.from_lla(lla_coord)
+GH36.from_ecef(ecef_coord)
+GH36.from_utm(utm_coord)
+GH36.from_web_mercator(wm_coord)
+# ... and all other coordinate systems
+```
+
+### LLA Convenience Methods
+
+```ruby
+lla = Geodetic::Coordinates::LLA.new(lat: 40.689167, lng: -74.044444)
+gh36 = lla.to_gh36                    # default precision 10
+gh36 = lla.to_gh36(precision: 5)      # custom precision
+
+lla = Geodetic::Coordinates::LLA.from_gh36(gh36)
+```
+
+## Serialization
+
+### `to_s(truncate_to = nil)`
+
+Returns the geohash string. An optional integer truncates to that length.
+
+```ruby
+coord = GH36.new("bdrdC26BqH")
+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.
+
+```ruby
+coord.to_a    # => [40.689, -74.044]
+```
+
+### `from_string` / `from_array`
+
+```ruby
+GH36.from_string("bdrdC26BqH")         # from geohash string
+GH36.from_array([40.689, -74.044])      # from [lat, lng]
+```
+
+## Neighbors
+
+Returns all 8 adjacent geohash cells as GH36 instances.
+
+```ruby
+coord = GH36.new(LLA.new(lat: 40.0, lng: -74.0))
+neighbors = coord.neighbors
+# => { N: GH36, S: GH36, E: GH36, W: GH36, NE: GH36, NW: GH36, SE: GH36, SW: GH36 }
+
+neighbors[:N].to_lla.lat > coord.to_lla.lat   # => true
+neighbors[:E].to_lla.lng > coord.to_lla.lng   # => true
+```
+
+Neighbor computation propagates carries when the adjustment wraps beyond the matrix edge, recursing on the parent prefix.
+
+## Area
+
+The `to_area` method returns the geohash cell as a `Geodetic::Areas::Rectangle`.
+
+```ruby
+area = coord.to_area
+# => Geodetic::Areas::Rectangle
+
+area.includes?(coord.to_lla)    # => true (midpoint is inside the cell)
+area.nw                         # => LLA (northwest corner)
+area.se                         # => LLA (southeast corner)
+```
+
+## Equality
+
+Two GH36 instances are equal if their geohash strings match exactly.
+
+```ruby
+GH36.new("bdrdC26BqH") == GH36.new("bdrdC26BqH")   # => true
+GH36.new("bdrdC26BqH") == GH36.new("bdrdC26Bq2")   # => false
+```
+
+## `valid?`
+
+Returns `true` if all characters are in the valid Geohash-36 alphabet.
+
+```ruby
+coord.valid?    # => true
+```
+
+## Universal Distance and Bearing Methods
+
+GH36 supports all universal distance and bearing methods via the `DistanceMethods` and `BearingMethods` mixins:
+
+```ruby
+a = GH36.new(LLA.new(lat: 40.689167, lng: -74.044444))
+b = GH36.new(LLA.new(lat: 51.504444, lng: -0.086666))
+
+a.distance_to(b)                # => Distance (~5,570 km)
+a.straight_line_distance_to(b)  # => Distance
+a.bearing_to(b)                 # => Bearing (~51°)
+a.elevation_to(b)               # => Float (degrees)
+```
+
+Cross-system distances work too:
+
+```ruby
+utm = seattle_lla.to_utm
+gh36 = GH36.new(portland_lla)
+utm.distance_to(gh36)    # => Distance
+```

data/docs/coordinate-systems/index.md

@@ -0,0 +1,93 @@
+# Coordinate Systems Overview
+
+The Geodetic gem supports 12 coordinate systems organized into six categories. All coordinate classes live under `Geodetic::Coordinates`.
+
+## Global Systems
+
+| System | Class | Description |
+|--------|-------|-------------|
+| **LLA** | `Geodetic::Coordinates::LLA` | Latitude, Longitude, Altitude. The most common geographic coordinate system, expressing positions in decimal degrees with altitude in meters. Negative longitude is the Western hemisphere; negative latitude is the Southern hemisphere. |
+| **ECEF** | `Geodetic::Coordinates::ECEF` | Earth-Centered, Earth-Fixed. A Cartesian coordinate system with the origin at the Earth's center of mass. Positions are expressed as X, Y, Z in meters. Commonly used in satellite navigation and aerospace applications. |
+| **UTM** | `Geodetic::Coordinates::UTM` | Universal Transverse Mercator. Divides the Earth into 60 zones (each 6 degrees of longitude), projecting positions as easting/northing in meters within a zone and hemisphere. Covers latitudes 80S to 84N. |
+
+## Local Tangent Plane Systems
+
+| System | Class | Description |
+|--------|-------|-------------|
+| **ENU** | `Geodetic::Coordinates::ENU` | East, North, Up. A local tangent plane coordinate system centered on a reference point. Axes point East, North, and Up relative to the reference. Distances are in meters. Used in robotics, surveying, and local navigation. |
+| **NED** | `Geodetic::Coordinates::NED` | North, East, Down. A local tangent plane coordinate system centered on a reference point. Axes point North, East, and Down. Used extensively in aerospace and aviation applications. Mathematically related to ENU by axis reordering and sign inversion. |
+
+## Military and Grid Systems
+
+| System | Class | Description |
+|--------|-------|-------------|
+| **MGRS** | `Geodetic::Coordinates::MGRS` | Military Grid Reference System. An alphanumeric system based on UTM that identifies positions using grid zone designator, 100km square identifier, and numeric easting/northing. Variable precision from 10km down to 1m. |
+| **USNG** | `Geodetic::Coordinates::USNG` | United States National Grid. Based on MGRS but formatted with spaces for readability. Used primarily within the United States for emergency services and land management. |
+
+## Web Mapping
+
+| System | Class | Description |
+|--------|-------|-------------|
+| **WebMercator** | `Geodetic::Coordinates::WebMercator` | Web Mercator (EPSG:3857). Also known as Pseudo-Mercator or Spherical Mercator. The projection used by Google Maps, OpenStreetMap, and Bing Maps. Positions are X/Y in meters. Latitude is clamped to approximately +/-85.05 degrees. Includes tile and pixel coordinate methods for web mapping applications. |
+
+## Polar
+
+| System | Class | Description |
+|--------|-------|-------------|
+| **UPS** | `Geodetic::Coordinates::UPS` | Universal Polar Stereographic. Covers the polar regions not handled by UTM (north of 84N and south of 80S). Uses a stereographic projection centered on each pole with zones Y/Z (north) and A/B (south). |
+
+## Spatial Hashing
+
+| System | Class | Description |
+|--------|-------|-------------|
+| **GH36** | `Geodetic::Coordinates::GH36` | Geohash-36. A hierarchical spatial hashing algorithm that encodes latitude/longitude into a compact, URL-friendly string using a case-sensitive 36-character alphabet (radix-36). Each hash represents a rectangular cell; the coordinate value is the cell midpoint. Supports neighbor lookup, area extraction via `to_area`, and configurable precision (default 10 characters for sub-meter resolution). |
+
+## Regional Systems
+
+| System | Class | Description |
+|--------|-------|-------------|
+| **StatePlane** | `Geodetic::Coordinates::StatePlane` | State Plane Coordinate System. US state-based coordinate systems using Lambert Conformal Conic or Transverse Mercator projections. Each state has one or more zones with specific parameters. Coordinates are typically in US Survey Feet. |
+| **BNG** | `Geodetic::Coordinates::BNG` | British National Grid. The official coordinate system for Great Britain, based on the OSGB36 datum with the Airy 1830 ellipsoid. Uses a Transverse Mercator projection and an alphanumeric grid reference system (e.g., "TQ 30 80"). |
+
+---
+
+## Conversion Matrix
+
+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 |
+|-----------|-----|------|-----|-----|-----|------|------|-------------|-----|------------|-----|------|
+| **LLA**        | --  | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y |
+| **ECEF**       | Y | --  | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y |
+| **UTM**        | Y | Y | --  | Y | Y | Y | Y | Y | Y | Y | Y | Y |
+| **ENU**        | Y | Y | Y | --  | Y | Y | Y | Y | Y | Y | Y | Y |
+| **NED**        | Y | Y | Y | Y | --  | Y | Y | Y | Y | Y | Y | Y |
+| **MGRS**       | Y | Y | Y | Y | Y | --  | Y | Y | Y | Y | Y | Y |
+| **USNG**       | Y | Y | Y | Y | Y | Y | --  | Y | Y | Y | Y | Y |
+| **WebMercator**| Y | Y | Y | Y | Y | Y | Y | --  | Y | Y | Y | Y |
+| **UPS**        | Y | Y | Y | Y | Y | Y | Y | Y | --  | Y | Y | Y |
+| **StatePlane** | Y | Y | Y | Y | Y | Y | Y | Y | Y | --  | Y | Y |
+| **BNG**        | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | --  | Y |
+| **GH36**       | 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 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.
+
+See the [Conversions Reference](../reference/conversions.md#distance-calculations) for details on distances and [Bearing Calculations](../reference/conversions.md#bearing-calculations) for bearings.
+
+> **Note:** ENU and NED are relative systems and must be converted to an absolute system (e.g., LLA) before using universal distance and bearing methods. They retain `local_bearing_to` and `local_elevation_angle_to` for tangent-plane operations.
+
+## Conversion Paths
+
+Conversions typically route through **LLA** or **ECEF** as intermediate steps:
+
+- **LLA** serves as the universal hub. Most systems convert to LLA first, then from LLA to the target system.
+- **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, and GH36** 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.