geodetic 0.0.1 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: aff287312f66448c5c97edde02c099b6bb6fbfa3e465afe604b744e6c50676dc
-  data.tar.gz: 5800e7ac55fe3d6bd74a1383b21d9b7aae777d2999b42050e12a0b18633aca07
+  metadata.gz: 4b413145dfecf16a20a9c7ac563811ed5cc2ae5784ae07a246a88d589704173b
+  data.tar.gz: 64b5d90e49b653a42ba469248dbcd4723e4b561f59475862a20ba4c7ce28366e
 SHA512:
-  metadata.gz: a9f38b3a2587b77592d51549649042f25267929f09c515a5526fb53f5ca3a87a2ec8d665672ed0f90da2642f9ae00f1aa9b31db9bc076374b19ac6ec1f722fcf
-  data.tar.gz: d3ed9287c2fe9d942e387df0d53754f0acdbc497235ac7a72c415be367bd766bb5b814efaefa6568809e68b3f90b3e4f3d059456f203b0bd03b341c94df16a65
+  metadata.gz: e5902317105ba68039818520b7a0b0ca6938e0f349b3123efe2e0d100a16f670ed0bc7571292f5691f1fcba20e7e0644baea192bf91306da972725a5984d3e0f
+  data.tar.gz: '08dd192001b74b25a46303fc61572bd1b5da7899d0b995a8538bece0f3ef616db9a340c9e8c542a5577d09f2e4c8cade454dada0a275404b7b1c6bab3bc4278d'

data/CHANGELOG.md

@@ -10,6 +10,41 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [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)
+- **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
+  - `to_area` — returns the cell as a `Geodetic::Areas::Rectangle`
+  - `precision_in_meters` — cell size in meters as `{ lat:, lng: }`
+  - `to_slug` — URL-friendly string representation
+  - Configurable precision on construction
+- **Geographic areas** — `Geodetic::Areas::Circle`, `Geodetic::Areas::Polygon`, and `Geodetic::Areas::Rectangle` for point-in-area testing
+- **Bearing calculations** — universal `bearing_to` and `elevation_to` methods on all coordinate classes via `BearingMethods` mixin
+- **`Geodetic::Bearing` class** — immutable value type with compass directions, reciprocal, radians, arithmetic, and `Comparable`
+- **Validated setters** with type coercion and range validation on all mutable coordinate classes
+- **`to_s(precision)`** on all coordinate classes, `Distance`, and `Bearing` with class-specific defaults
+- **ENU and NED local methods** — `local_bearing_to` and `local_elevation_angle_to` for tangent-plane operations; NED adds `horizontal_distance_to`
+- **GitHub Pages documentation** site with MkDocs
+
+### Changed
+
+- Coordinate classes use `attr_reader` with validated setter methods instead of `attr_accessor`
+- ENU/NED bearing methods renamed: `bearing_to` → `local_bearing_to`, `elevation_angle_to` → `local_elevation_angle_to` (universal `bearing_to`/`elevation_to` now come from the mixin)
+
+### Fixed
+
+- ENU/NED argument mismatch in 8 coordinate classes — `to_enu`/`to_ned` passed extra `datum` arg that `LLA#to_enu`/`LLA#to_ned` does not accept
+- StatePlane `lambert_conformal_conic_to_lla` double `DEG_PER_RAD` conversion producing incorrect results
+- OLC floating-point encoding error — pre-computed `PAIR_RESOLUTIONS` with epsilon correction prevents truncation (e.g., Google HQ encoding "849VCWC8+R9")
+
 ## [0.0.1] - 2026-03-07
 
 Initial update from an old archived project.

data/README.md

@@ -1,23 +1,33 @@
 # Geodetic
 
-A Ruby gem for converting between geodetic coordinate systems. Supports 12 coordinate systems with full bidirectional conversions, plus geoid height calculations and geographic area operations.
-
-## Coordinate Systems
-
-| Class | Description |
-|-------|-------------|
-| `Coordinates::LLA` | Latitude, Longitude, Altitude (degrees/meters) |
-| `Coordinates::ECEF` | Earth-Centered, Earth-Fixed (meters) |
-| `Coordinates::UTM` | Universal Transverse Mercator |
-| `Coordinates::ENU` | East, North, Up (local tangent plane) |
-| `Coordinates::NED` | North, East, Down (local tangent plane) |
-| `Coordinates::MGRS` | Military Grid Reference System |
-| `Coordinates::USNG` | US National Grid |
-| `Coordinates::WebMercator` | Web Mercator / EPSG:3857 |
-| `Coordinates::UPS` | Universal Polar Stereographic |
-| `Coordinates::StatePlane` | US State Plane Coordinate System |
-| `Coordinates::BNG` | British National Grid |
-| `Coordinates::GH36` | Geohash-36 (spatial hash, URL-friendly) |
+> [!INFO]
+> See the [CHANGELOG](CHANGELOG.md) for the latest changes. The [examples directory has runnable demo apps](examples/) that show-off the various capabilities of the Geodetic library.
+
+<br>
+<table>
+<tr>
+<td width="50%" align="center" valign="top">
+<img src="docs/assets/images/geodetic.jpg" alt="Geodetic"><br>
+<em>"Convert coordinates. Map the world."</em>
+</td>
+<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>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>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>
+- <strong>Immutable Value Types</strong> - Distance and Bearing with arithmetic and comparison
+</td>
+</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>
 
 ## Installation
 
@@ -129,7 +139,7 @@ bng = Coordinates::BNG.new(easting: 530000, northing: 180000)
 bng.easting = 430000               # grid_ref automatically recalculated
 ```
 
-ECEF, ENU, NED, and WebMercator setters coerce to float with no range constraints. MGRS, USNG, GH36, Distance, and Bearing are immutable.
+ECEF, ENU, NED, and WebMercator setters coerce to float with no range constraints. MGRS, USNG, GH36, GH, HAM, OLC, Distance, and Bearing are immutable.
 
 ### DMS (Degrees, Minutes, Seconds)
 
@@ -396,6 +406,90 @@ gh36.precision              # => 10
 gh36.precision_in_meters    # => { lat: 0.31, lng: 0.62 }
 ```
 
+### Geohash (GH)
+
+The standard Geohash (base-32) algorithm by Gustavo Niemeyer, widely supported by Elasticsearch, Redis, PostGIS, and geocoding services:
+
+```ruby
+# From a geohash string
+gh = Coordinates::GH.new("dr5ru7")
+
+# From any coordinate
+gh = Coordinates::GH.new(lla)
+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: ... }
+
+# Bounding rectangle of the geohash cell
+area = gh.to_area    # => Areas::Rectangle
+area.includes?(gh.to_lla)  # => true
+
+# Precision info
+gh.precision              # => 6
+gh.precision_in_meters    # => { lat: 610.98, lng: 1221.97 }
+```
+
+### Maidenhead Locator (HAM)
+
+The Maidenhead Locator System used worldwide in amateur radio for grid square identification:
+
+```ruby
+# From a Maidenhead locator string
+ham = Coordinates::HAM.new("FN31pr")
+
+# From any coordinate
+ham = Coordinates::HAM.new(lla)
+ham = lla.to_ham(precision: 8)
+
+# Decode back to LLA
+lla = ham.to_lla
+
+# Neighbor cells
+ham.neighbors  # => { N: HAM, S: HAM, E: HAM, W: HAM, NE: ..., NW: ..., SE: ..., SW: ... }
+
+# Bounding rectangle of the grid square
+area = ham.to_area    # => Areas::Rectangle
+area.includes?(ham.to_lla)  # => true
+
+# Precision info
+ham.precision              # => 6
+ham.precision_in_meters    # => { lat: 4631.0, lng: 9260.0 }
+```
+
+### Open Location Code / Plus Codes (OLC)
+
+Google's open system for encoding locations into short, URL-friendly codes:
+
+```ruby
+# From a plus code string
+olc = Coordinates::OLC.new("849VCWC8+R9")
+
+# From any coordinate
+olc = Coordinates::OLC.new(lla)
+olc = lla.to_olc(precision: 11)
+
+# Decode back to LLA
+lla = olc.to_lla
+
+# Neighbor cells
+olc.neighbors  # => { N: OLC, S: OLC, E: OLC, W: OLC, NE: ..., NW: ..., SE: ..., SW: ... }
+
+# Bounding rectangle of the plus code cell
+area = olc.to_area    # => Areas::Rectangle
+area.includes?(olc.to_lla)  # => true
+
+# Precision info
+olc.precision              # => 10
+olc.precision_in_meters    # => { lat: 13.9, lng: 13.9 }
+```
+
 ### Geographic Areas
 
 ```ruby
@@ -448,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 12 coordinate systems, cross-system chains, and areas |
+| [`02_all_coordinate_systems.rb`](examples/02_all_coordinate_systems.rb) | All 15 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 |
 
@@ -460,6 +554,8 @@ ruby -Ilib examples/01_basic_conversions.rb
 
 ## Development
 
+For comprehensive guides and API documentation, visit **[https://madbomber.github.io/geodetic](https://madbomber.github.io/geodetic)**
+
 ```bash
 bin/setup          # Install dependencies
 rake test          # Run tests

data/docs/coordinate-systems/gh.md

@@ -0,0 +1,282 @@
+# Geodetic::Coordinates::GH
+
+## Geohash (Base-32)
+
+The standard geohash algorithm by Gustavo Niemeyer that encodes latitude/longitude into a compact string using a 32-character alphabet. It uses interleaved longitude and latitude bits, with each 5-bit group mapped to a base-32 character.
+
+Character set: `0123456789bcdefghjkmnpqrstuvwxyz`
+(excludes `a`, `i`, `l`, `o` to avoid ambiguity)
+
+This is the de facto standard for spatial hashing, natively supported by Elasticsearch, Redis, PostGIS, and many geocoding services.
+
+GH 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::GH.new("dr5ru7")
+
+# From any coordinate (converts via LLA)
+coord = Geodetic::Coordinates::GH.new(lla_coord)
+coord = Geodetic::Coordinates::GH.new(utm_coord, precision: 8)
+```
+
+| Parameter   | Type              | Default | Description                                  |
+|-------------|-------------------|---------|----------------------------------------------|
+| `source`    | String or Coord   | —       | A geohash string or any coordinate object    |
+| `precision` | Integer           | 12      | 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. String input is case-insensitive (automatically downcased).
+
+## Attributes
+
+| Attribute | Type   | Access    | Description                     |
+|-----------|--------|-----------|---------------------------------|
+| `geohash` | String | read-only | The geohash base-32 encoded string |
+
+GH is **immutable** — there are no setter methods.
+
+## Precision
+
+The precision (hash length) determines the size of the cell:
+
+| Length | Approximate Resolution |
+|--------|----------------------|
+| 1      | ~5,000 km            |
+| 4      | ~20 km               |
+| 6      | ~610 m               |
+| 8      | ~19 m                |
+| 12     | ~0.019 m (default)   |
+
+```ruby
+coord.precision              # => 12 (hash length)
+coord.precision_in_meters    # => { lat: 0.019, lng: 0.019 }
+```
+
+Longer hashes yield finer precision.
+
+## 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
+```
+
+### Class Methods
+
+```ruby
+GH.from_lla(lla_coord)
+GH.from_ecef(ecef_coord)
+GH.from_utm(utm_coord)
+GH.from_web_mercator(wm_coord)
+GH.from_gh36(gh36_coord)
+# ... and all other coordinate systems
+```
+
+### LLA Convenience Methods
+
+```ruby
+lla = Geodetic::Coordinates::LLA.new(lat: 40.689167, lng: -74.044444)
+gh = lla.to_gh                    # default precision 12
+gh = lla.to_gh(precision: 6)      # custom precision
+
+lla = Geodetic::Coordinates::LLA.from_gh(gh)
+```
+
+## Serialization
+
+### `to_s(truncate_to = nil)`
+
+Returns the geohash string. An optional integer truncates to that length.
+
+```ruby
+coord = GH.new("dr5ru7c5g200")
+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.
+
+```ruby
+coord.to_a    # => [40.689, -74.044]
+```
+
+### `from_string` / `from_array`
+
+```ruby
+GH.from_string("dr5ru7")              # from geohash string
+GH.from_array([40.689, -74.044])       # from [lat, lng]
+```
+
+## Neighbors
+
+Returns all 8 adjacent geohash cells as GH instances.
+
+```ruby
+coord = GH.new(LLA.new(lat: 40.0, lng: -74.0))
+neighbors = coord.neighbors
+# => { N: GH, S: GH, E: GH, W: GH, NE: GH, NW: GH, SE: GH, SW: GH }
+
+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 geohash. Longitude wraps correctly near the antimeridian (180/-180 boundary).
+
+## 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 GH instances are equal if their geohash strings match exactly.
+
+```ruby
+GH.new("dr5ru7") == GH.new("dr5ru7")   # => true
+GH.new("dr5ru7") == GH.new("dr5ru8")   # => false
+```
+
+## `valid?`
+
+Returns `true` if all characters are in the valid base-32 geohash alphabet.
+
+```ruby
+coord.valid?    # => true
+```
+
+## Universal Distance and Bearing Methods
+
+GH supports all universal distance and bearing methods via the `DistanceMethods` and `BearingMethods` mixins:
+
+```ruby
+a = GH.new(LLA.new(lat: 40.689167, lng: -74.044444))
+b = GH.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
+gh = GH.new(portland_lla)
+utm.distance_to(gh)    # => Distance
+```
+
+## GH vs GH36
+
+GH (base-32) and GH36 (base-36) are both spatial hashing systems that encode latitude/longitude into compact strings. They differ in alphabet, encoding strategy, ecosystem support, and resolution characteristics.
+
+### Design Differences
+
+| Feature | GH (base-32) | GH36 (base-36) |
+|---------|-------------|----------------|
+| Algorithm | Bit-interleaved lat/lng, 5 bits per character | 6x6 matrix subdivision per character |
+| Alphabet | 32 chars: `0-9, b-z` (excludes `a, i, l, o`) | 36 chars: `23456789bBCdDFgGhHjJKlLMnNPqQrRtTVWX` |
+| Case sensitivity | Case-insensitive | Case-sensitive |
+| Default precision | 12 characters | 10 characters |
+| Information density | 5 bits/char (log2(32) = 5.0) | ~5.17 bits/char (log2(36) = 5.17) |
+
+GH interleaves longitude and latitude bits — odd-numbered bits encode longitude, even-numbered bits encode latitude. Each group of 5 bits maps to one base-32 character. This means GH cells alternate between being wider-than-tall and taller-than-wide at each precision level.
+
+GH36 subdivides the coordinate space using a 6x6 character matrix at each level. This yields slightly more information per character (5.17 vs 5.0 bits) but requires a case-sensitive alphabet.
+
+### Precision Comparison
+
+Cell dimensions at the equator for each hash length:
+
+| Length | GH (base-32) | GH36 (base-36) |
+|--------|-------------|----------------|
+| 1 | 5,009 km x 4,628 km | 1,668 km x 3,335 km |
+| 2 | 626 km x 1,251 km | 278 km x 556 km |
+| 3 | 157 km x 157 km | 46 km x 93 km |
+| 4 | 20 km x 39 km | 7.7 km x 15 km |
+| 5 | 4.9 km x 4.9 km | 1.3 km x 2.6 km |
+| 6 | 611 m x 1,223 m | 214 m x 429 m |
+| 7 | 153 m x 153 m | 36 m x 71 m |
+| 8 | 19 m x 38 m | 6.0 m x 11.9 m |
+| 9 | 4.8 m x 4.8 m | 0.99 m x 1.99 m |
+| 10 | 0.60 m x 1.19 m | 0.17 m x 0.33 m |
+| 11 | 0.15 m x 0.15 m | — |
+| 12 | 0.019 m x 0.037 m | — |
+
+At their default precisions:
+
+- **GH at 12 characters**: ~19 mm x 37 mm (sub-centimeter)
+- **GH36 at 10 characters**: ~17 cm x 33 cm (sub-meter)
+
+GH36 achieves better resolution per character due to its larger alphabet, but GH compensates by defaulting to a longer hash. At equal string lengths, GH36 cells are smaller. At their respective defaults, GH cells are roughly 9x smaller.
+
+### Ecosystem Support
+
+| System | GH (base-32) | GH36 (base-36) |
+|--------|:------------:|:--------------:|
+| Elasticsearch | Native `geo_point` type | — |
+| Redis | `GEOADD`/`GEOSEARCH` commands | — |
+| PostGIS | `ST_GeoHash()` function | — |
+| MongoDB | `2dsphere` index | — |
+| Google S2 | Compatible cell IDs | — |
+| Geocoding APIs | Widely supported | — |
+
+GH (base-32) is the de facto standard. Virtually all spatial databases and services that support geohashing use the base-32 algorithm. GH36 is a niche alternative designed for URL-friendly strings with no ambiguous characters.
+
+### When to Use Which
+
+**Choose GH (base-32) when:**
+- Integrating with external services (Elasticsearch, Redis, PostGIS)
+- Storing geohashes in databases that expect the standard format
+- Performing proximity searches using prefix matching
+- Interoperating with third-party geocoding or mapping APIs
+
+**Choose GH36 (base-36) when:**
+- You need a self-contained spatial hash with no external dependencies
+- Case-sensitive storage is acceptable
+- You want to avoid vowels and ambiguous characters in user-facing strings
+- Slightly better resolution per character matters
+
+### Converting Between GH and GH36
+
+```ruby
+gh = Geodetic::Coordinates::GH.new("dr5ru7")
+gh36 = gh.to_gh36                    # => GH36 instance
+gh_back = gh36.to_gh                 # => GH instance
+
+# Both decode to the same approximate location
+gh.to_lla.lat   # => 40.71...
+gh36.to_lla.lat # => 40.71...
+```
+
+Note that roundtrip conversion is not lossless — each system quantizes coordinates to its own grid, so converting GH -> GH36 -> GH may produce a slightly different hash string that decodes to the same approximate location.