geodetic 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4b413145dfecf16a20a9c7ac563811ed5cc2ae5784ae07a246a88d589704173b
-  data.tar.gz: 64b5d90e49b653a42ba469248dbcd4723e4b561f59475862a20ba4c7ce28366e
+  metadata.gz: 782ba82d99727dfa9a075fcdfb9dea89f631ebc78e0e105293745c64f77f9dae
+  data.tar.gz: 59e9c844470d77026a9929c8b9ffd01a5d065fd491d8efb67106b0903267c681
 SHA512:
-  metadata.gz: e5902317105ba68039818520b7a0b0ca6938e0f349b3123efe2e0d100a16f670ed0bc7571292f5691f1fcba20e7e0644baea192bf91306da972725a5984d3e0f
-  data.tar.gz: '08dd192001b74b25a46303fc61572bd1b5da7899d0b995a8538bece0f3ef616db9a340c9e8c542a5577d09f2e4c8cade454dada0a275404b7b1c6bab3bc4278d'
+  metadata.gz: 38543deb9e8d62aa20b4a90c9602b0e97806d7d2f55dd9d308a138b9aea2b033e6f51656a9d247ce750d5abcd5298f170825a3f0e4f013a63198bc467e1f3d8c
+  data.tar.gz: fcb62fac876d350bd784d08bb17d45b7c14218a31ff6cfcce4be7e384e3f9a6a2c711ae3731b4a4241e5b34c062a8ddcdc2fb8ce6786ac114ff35d872ad8a7f3

data/CHANGELOG.md

@@ -10,15 +10,34 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+
+## [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
+
+- **Namespace renamed**: `Geodetic::Coordinates` is now `Geodetic::Coordinate` (singular)
+- **SpatialHash base class** (`lib/geodetic/coordinate/spatial_hash.rb`) — GH36, GH, HAM, OLC, GEOREF, and GARS now inherit from a shared base class that provides common behavior (neighbors, to_area, precision_in_meters, serialization, encoding/decoding contract)
+- **Auto-generated hash conversions** — `SpatialHash.generate_hash_conversions_for` replaces 232 lines of hand-written boilerplate `to_gh`/`from_gh`/`to_ham`/`from_ham`/etc. methods across 7 coordinate classes
+- **Self-registration** — each coordinate class calls `Coordinate.register_class(self)` at load time; `ALL_COORD_CLASSES` is populated from the registry instead of a manual list
+
 ## [0.1.0] - 2026-03-08
 
 ### Added
 
 - **4 new coordinate systems** bringing the total from 11 to 15:
-  - `Geodetic::Coordinates::GH36` — Geohash-36 (radix-36 spatial hash, URL-friendly)
-  - `Geodetic::Coordinates::GH` — Geohash base-32 (standard geohash, supported by Elasticsearch, Redis, PostGIS)
-  - `Geodetic::Coordinates::HAM` — Maidenhead Locator System (amateur radio grid squares)
-  - `Geodetic::Coordinates::OLC` — Open Location Code / Plus Codes (Google's location encoding)
+  - `Geodetic::Coordinate::GH36` — Geohash-36 (radix-36 spatial hash, URL-friendly)
+  - `Geodetic::Coordinate::GH` — Geohash base-32 (standard geohash, supported by Elasticsearch, Redis, PostGIS)
+  - `Geodetic::Coordinate::HAM` — Maidenhead Locator System (amateur radio grid squares)
+  - `Geodetic::Coordinate::OLC` — Open Location Code / Plus Codes (Google's location encoding)
 - **Full cross-system conversions** — all 15 coordinate systems convert to/from every other system (225 conversion paths)
 - **Spatial hash features** for GH36, GH, HAM, and OLC:
   - `neighbors` — returns all 8 adjacent grid cells

data/README.md

@@ -13,7 +13,7 @@
 <td width="50%" valign="top">
 <strong>Key Features</strong><br>
 
-- <strong>15 Coordinate Systems</strong> - LLA, ECEF, UTM, ENU, NED, MGRS, USNG, Web Mercator, UPS, State Plane, BNG, GH36, GH, HAM, OLC<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>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>
@@ -27,7 +27,7 @@
 </tr>
 </table>
 
-<p>Geodetic enables precise conversion between geodetic coordinate systems in Ruby. All 15 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 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>
 
 ## Installation
 
@@ -63,12 +63,12 @@ ned = Coordinates::NED.new(n: 200.0, e: 100.0, d: -50.0)
 
 ### GCS Shorthand
 
-`GCS` is a top-level alias for `Geodetic::Coordinates`, providing a concise way to create and work with coordinates:
+`GCS` is a top-level alias for `Geodetic::Coordinate`, providing a concise way to create and work with coordinates:
 
 ```ruby
 require "geodetic"
 
-# Use GCS as a shorthand for Geodetic::Coordinates
+# 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)
 ```
@@ -542,7 +542,7 @@ 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 15 coordinate systems, cross-system chains, and areas |
+| [`02_all_coordinate_systems.rb`](examples/02_all_coordinate_systems.rb) | All 17 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 |
 

data/docs/coordinate-systems/bng.md

@@ -1,4 +1,4 @@
-# Geodetic::Coordinates::BNG
+# Geodetic::Coordinate::BNG
 
 ## British National Grid
 
@@ -9,13 +9,13 @@ The British National Grid (BNG) is the official coordinate system for Great Brit
 Create a BNG coordinate from numeric easting/northing values:
 
 ```ruby
-point = Geodetic::Coordinates::BNG.new(easting: 530000.0, northing: 180000.0)
+point = Geodetic::Coordinate::BNG.new(easting: 530000.0, northing: 180000.0)
 ```
 
 Alternatively, create from an alphanumeric grid reference string:
 
 ```ruby
-point = Geodetic::Coordinates::BNG.new(grid_ref: "TQ 300000 800000")
+point = Geodetic::Coordinate::BNG.new(grid_ref: "TQ 300000 800000")
 ```
 
 ## Grid References
@@ -52,8 +52,8 @@ point.valid?  # => true if within Great Britain bounds
 The universal `distance_to` method computes the Vincenty great-circle distance to any other coordinate type, returning a `Distance` object. The `straight_line_distance_to` method computes the Euclidean distance in ECEF space. The universal `bearing_to` method computes the great-circle forward azimuth, returning a `Bearing` object. All accept single or multiple targets.
 
 ```ruby
-bng_a = Geodetic::Coordinates::BNG.new(easting: 530000.0, northing: 180000.0)
-bng_b = Geodetic::Coordinates::BNG.new(easting: 540000.0, northing: 190000.0)
+bng_a = Geodetic::Coordinate::BNG.new(easting: 530000.0, northing: 180000.0)
+bng_b = Geodetic::Coordinate::BNG.new(easting: 540000.0, northing: 190000.0)
 bng_a.distance_to(bng_b)                # => Distance (great-circle)
 bng_a.straight_line_distance_to(bng_b)  # => Distance (Euclidean)
 bng_a.bearing_to(bng_b)                 # => Bearing (great-circle forward azimuth)

data/docs/coordinate-systems/ecef.md

@@ -1,4 +1,4 @@
-# Geodetic::Coordinates::ECEF
+# Geodetic::Coordinate::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.
 
@@ -7,7 +7,7 @@ ECEF is useful for satellite positioning, radar tracking, and any application re
 ## Constructor
 
 ```ruby
-Geodetic::Coordinates::ECEF.new(x: 0.0, y: 0.0, z: 0.0)
+Geodetic::Coordinate::ECEF.new(x: 0.0, y: 0.0, z: 0.0)
 ```
 
 | Parameter | Type  | Default | Description                     |
@@ -35,9 +35,9 @@ All conversion methods accept an optional `datum` parameter (defaults to `Geodet
 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)
+ecef = Geodetic::Coordinate::ECEF.new(x: 1130730.0, y: -4828583.0, z: 3991570.0)
 lla = ecef.to_lla
-# => Geodetic::Coordinates::LLA
+# => Geodetic::Coordinate::LLA
 ```
 
 ### ECEF.from_lla(lla, datum = WGS84)
@@ -45,7 +45,7 @@ lla = ecef.to_lla
 Creates an ECEF from an LLA instance. Raises `ArgumentError` if the argument is not an `LLA`.
 
 ```ruby
-ecef = Geodetic::Coordinates::ECEF.from_lla(lla)
+ecef = Geodetic::Coordinate::ECEF.from_lla(lla)
 ```
 
 ### to_utm(datum = WGS84)
@@ -54,7 +54,7 @@ Converts to Universal Transverse Mercator coordinates. Internally converts to LL
 
 ```ruby
 utm = ecef.to_utm
-# => Geodetic::Coordinates::UTM
+# => Geodetic::Coordinate::UTM
 ```
 
 ### ECEF.from_utm(utm, datum = WGS84)
@@ -66,10 +66,10 @@ Creates an ECEF from a UTM instance. Raises `ArgumentError` if the argument is n
 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)
+ref_ecef = Geodetic::Coordinate::ECEF.new(x: 1130730.0, y: -4828583.0, z: 3991570.0)
+point_ecef = Geodetic::Coordinate::ECEF.new(x: 1130740.0, y: -4828573.0, z: 3991580.0)
 enu = point_ecef.to_enu(ref_ecef)
-# => Geodetic::Coordinates::ENU
+# => Geodetic::Coordinate::ENU
 ```
 
 Raises `ArgumentError` if `reference_ecef` is not an `ECEF`.
@@ -84,7 +84,7 @@ Converts to North-East-Down local tangent plane coordinates. Internally converts
 
 ```ruby
 ned = point_ecef.to_ned(ref_ecef)
-# => Geodetic::Coordinates::NED
+# => Geodetic::Coordinate::NED
 ```
 
 ### ECEF.from_ned(ned, reference_ecef, reference_lla = nil)
@@ -98,7 +98,7 @@ Creates an ECEF from a NED instance and a reference ECEF origin. Raises `Argumen
 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 = Geodetic::Coordinate::ECEF.new(x: 1130730.0, y: -4828583.0, z: 3991570.0)
 ecef.to_s
 # => "1130730.0, -4828583.0, 3991570.0"
 ```
@@ -117,7 +117,7 @@ ecef.to_a
 Parses a comma-separated string into an ECEF.
 
 ```ruby
-ecef = Geodetic::Coordinates::ECEF.from_string("1130730.0, -4828583.0, 3991570.0")
+ecef = Geodetic::Coordinate::ECEF.from_string("1130730.0, -4828583.0, 3991570.0")
 ```
 
 ### ECEF.from_array(array)
@@ -125,7 +125,7 @@ ecef = Geodetic::Coordinates::ECEF.from_string("1130730.0, -4828583.0, 3991570.0
 Creates an ECEF from a three-element array `[x, y, z]`.
 
 ```ruby
-ecef = Geodetic::Coordinates::ECEF.from_array([1130730.0, -4828583.0, 3991570.0])
+ecef = Geodetic::Coordinate::ECEF.from_array([1130730.0, -4828583.0, 3991570.0])
 ```
 
 ## Additional Methods
@@ -135,8 +135,8 @@ ecef = Geodetic::Coordinates::ECEF.from_array([1130730.0, -4828583.0, 3991570.0]
 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 = Geodetic::Coordinate::ECEF.new(x: 1130730.0, y: -4828583.0, z: 3991570.0)
+b = Geodetic::Coordinate::ECEF.new(x: 1130730.0, y: -4828583.0, z: 3991570.0)
 a == b
 # => true
 ```
@@ -146,8 +146,8 @@ a == b
 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 = Geodetic::Coordinate::ECEF.new(x: 1130730.0, y: -4828583.0, z: 3991570.0)
+b = Geodetic::Coordinate::ECEF.new(x: 1130740.0, y: -4828573.0, z: 3991580.0)
 a.distance_to(b)
 # => Distance (meters, great-circle distance)
 ```
@@ -169,7 +169,7 @@ a.straight_line_distance_to(b)
 require 'geodetic'
 
 # Create an ECEF coordinate
-ecef = Geodetic::Coordinates::ECEF.new(x: 1130730.0, y: -4828583.0, z: 3991570.0)
+ecef = Geodetic::Coordinate::ECEF.new(x: 1130730.0, y: -4828583.0, z: 3991570.0)
 
 # Convert to LLA and back
 lla = ecef.to_lla
@@ -181,8 +181,8 @@ ecef == ecef_roundtrip
 ### 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)
+station_a = Geodetic::Coordinate::ECEF.new(x: 1130730.0, y: -4828583.0, z: 3991570.0)
+station_b = Geodetic::Coordinate::ECEF.new(x: 1131000.0, y: -4828300.0, z: 3991800.0)
 
 # Great-circle distance (Vincenty)
 distance = station_a.distance_to(station_b)
@@ -196,8 +196,8 @@ 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)
+origin = Geodetic::Coordinate::ECEF.new(x: 1130730.0, y: -4828583.0, z: 3991570.0)
+target = Geodetic::Coordinate::ECEF.new(x: 1130740.0, y: -4828573.0, z: 3991580.0)
 
 # Provide reference LLA to avoid recomputing it
 ref_lla = origin.to_lla
@@ -210,6 +210,6 @@ ned = target.to_ned(origin, ref_lla)
 
 ```ruby
 clarke66 = Geodetic::Datum.new(name: 'CLARKE_1866')
-ecef = Geodetic::Coordinates::ECEF.new(x: 1130730.0, y: -4828583.0, z: 3991570.0)
+ecef = Geodetic::Coordinate::ECEF.new(x: 1130730.0, y: -4828583.0, z: 3991570.0)
 lla = ecef.to_lla(clarke66)
 ```

data/docs/coordinate-systems/enu.md

@@ -1,4 +1,4 @@
-# Geodetic::Coordinates::ENU - East, North, Up
+# Geodetic::Coordinate::ENU - East, North, Up
 
 ## Overview
 
@@ -52,7 +52,7 @@ The one exception is the conversion between ENU and NED, which does not require
 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)
+ref = Geodetic::Coordinate::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)
@@ -65,7 +65,7 @@ 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 = Geodetic::Coordinate::ENU.new(e: 100.0, n: 200.0, u: 50.0)
 
 point.east   # => 100.0
 point.north  # => 200.0

data/docs/coordinate-systems/gars.md

@@ -0,0 +1,246 @@
+# Geodetic::Coordinate::GARS
+
+## Global Area Reference System
+
+GARS is a standardized geospatial reference system developed by the National Geospatial-Intelligence Agency (NGA). It divides the Earth into hierarchical grid cells at three precision levels, designed for military targeting, air defense, and joint operations.
+
+The encoding uses a false coordinate origin that shifts longitude by +180 and latitude by +90. Cells are identified by a combination of numeric longitude bands, alphabetic latitude bands, and optional subdivision digits:
+
+| Level | Characters | Size | Description |
+|-------|-----------|------|-------------|
+| **30-minute cell** | 5 (NNNll) | 30' x 30' | 3-digit lon band + 2-letter lat band |
+| **Quadrant** | 6 (NNNllq) | 15' x 15' | + quadrant digit 1-4 |
+| **Keypad** | 7 (NNNllqk) | 5' x 5' | + keypad digit 1-9 |
+
+### Quadrant Layout
+
+Within each 30-minute cell, quadrants are numbered:
+
+```
++---+---+
+| 1 | 2 |  (north)
++---+---+
+| 3 | 4 |  (south)
++---+---+
+```
+
+### Keypad Layout
+
+Within each quadrant, keypads follow telephone-style numbering:
+
+```
++---+---+---+
+| 1 | 2 | 3 |  (north)
++---+---+---+
+| 4 | 5 | 6 |
++---+---+---+
+| 7 | 8 | 9 |  (south)
++---+---+---+
+```
+
+GARS is a **2D coordinate system** (no altitude). Conversions to/from other systems go through LLA as the intermediary. Each code represents a rectangular cell; the coordinate's point value is the cell's midpoint.
+
+## Constructor
+
+```ruby
+# From a GARS string
+coord = Geodetic::Coordinate::GARS.new("006AG39")
+
+# From any coordinate (converts via LLA)
+coord = Geodetic::Coordinate::GARS.new(lla_coord)
+coord = Geodetic::Coordinate::GARS.new(utm_coord, precision: 6)
+```
+
+| Parameter   | Type              | Default | Description                          |
+|-------------|-------------------|---------|--------------------------------------|
+| `source`    | String or Coord   | --      | A GARS string or any coordinate object |
+| `precision` | Integer           | 7       | Code length: 5, 6, or 7             |
+
+Raises `ArgumentError` if the source string is empty, has an invalid length, contains an out-of-range longitude band (must be 001-720), invalid latitude letters (I and O excluded), invalid quadrant digit (must be 1-4), or invalid keypad digit (must be 1-9). Letter input is case-insensitive (normalized to uppercase).
+
+## Attributes
+
+| Attribute | Type   | Access    | Description            |
+|-----------|--------|-----------|------------------------|
+| `code`    | String | read-only | The GARS code string   |
+
+GARS is **immutable** -- there are no setter methods.
+
+## Precision
+
+The precision (code length) determines the size of the encoded cell:
+
+| Length | Level | Approximate Cell Size |
+|--------|-------|----------------------|
+| 5      | 30-minute cell | ~55.6 km x 55.6 km |
+| 6      | 15-minute quadrant | ~27.8 km x 27.8 km |
+| 7      | 5-minute keypad | ~9.3 km x 9.3 km |
+
+```ruby
+coord.precision              # => 7 (code length)
+coord.precision_in_meters    # => { lat: ~9260, lng: ~... }
+```
+
+## 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
+coord.to_gh
+coord.to_ham
+coord.to_olc
+coord.to_georef
+```
+
+### Class Methods
+
+```ruby
+GARS.from_lla(lla_coord)
+GARS.from_ecef(ecef_coord)
+GARS.from_utm(utm_coord)
+GARS.from_web_mercator(wm_coord)
+GARS.from_gh(gh_coord)
+GARS.from_georef(georef_coord)
+# ... and all other coordinate systems
+```
+
+### LLA Convenience Methods
+
+```ruby
+lla = Geodetic::Coordinate::LLA.new(lat: 40.7128, lng: -74.0060)
+gars = lla.to_gars                    # default precision 7
+gars = lla.to_gars(precision: 5)      # 30-minute cell only
+
+lla = Geodetic::Coordinate::LLA.from_gars(gars)
+```
+
+## Serialization
+
+### `to_s(truncate_to = nil)`
+
+Returns the GARS string. An optional integer truncates to that precision (re-encodes from decoded coordinates).
+
+```ruby
+coord = GARS.new("006AG39")
+coord.to_s       # => "006AG39"
+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.
+
+```ruby
+coord.to_a    # => [lat, lng]
+```
+
+### `from_string` / `from_array`
+
+```ruby
+GARS.from_string("006AG39")           # from GARS string
+GARS.from_array([40.0, -74.0])        # from [lat, lng]
+```
+
+## Neighbors
+
+Returns all 8 adjacent cells as GARS instances.
+
+```ruby
+coord = GARS.new("361HN35")
+neighbors = coord.neighbors
+# => { N: GARS, S: GARS, E: GARS, W: GARS, NE: GARS, NW: GARS, SE: GARS, SW: GARS }
+
+neighbors[:N].to_lla.lat > coord.to_lla.lat   # => true
+neighbors[:E].to_lla.lng > coord.to_lla.lng   # => true
+```
+
+Neighbors preserve the same precision as the original code. Latitude is clamped to valid range near the poles; longitude wraps at the antimeridian.
+
+## Area
+
+The `to_area` method returns the GARS 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 GARS instances are equal if their code strings match exactly.
+
+```ruby
+GARS.new("006AG39") == GARS.new("006AG39")   # => true
+GARS.new("006AG39") == GARS.new("006AG38")   # => false
+```
+
+## `valid?`
+
+Returns `true` if the code has a valid length (5, 6, or 7), a longitude band between 001-720, valid latitude letters (A-Z excluding I and O), a valid quadrant digit (1-4), and a valid keypad digit (1-9).
+
+```ruby
+coord.valid?    # => true
+```
+
+## Universal Distance and Bearing Methods
+
+GARS supports all universal distance and bearing methods via the `DistanceMethods` and `BearingMethods` mixins:
+
+```ruby
+a = GARS.new("361HN35")
+b = GARS.new("212LX43")
+
+a.distance_to(b)                # => Distance
+a.straight_line_distance_to(b)  # => Distance
+a.bearing_to(b)                 # => Bearing
+a.elevation_to(b)               # => Float (degrees)
+```
+
+## Encoding Details
+
+### Longitude Bands
+
+720 bands of 0.5 degrees each, numbered 001-720 from west to east:
+- Band 001: -180.0 to -179.5
+- Band 361: 0.0 to 0.5
+- Band 720: 179.5 to 180.0
+
+### Latitude Bands
+
+360 bands of 0.5 degrees each, encoded as 2-letter pairs (AA-QZ) from south to north:
+- AA: -90.0 to -89.5
+- HN: 0.0 to 0.5
+- QZ: 89.5 to 90.0
+
+The 24-letter alphabet (A-Z, excluding I and O) gives 24 x 15 = 360 valid combinations.
+
+## Well-Known GARS Codes
+
+| Location | GARS Code | Description |
+|----------|-----------|-------------|
+| Null Island (0, 0) | 361HN | 30-minute cell at equator/prime meridian |
+| New York City | 212LX43 | 5-minute cell |
+| Western boundary | 001xx | Longitude -180.0 |