geodetic 0.0.1

data/docs/coordinate-systems/lla.md

@@ -0,0 +1,304 @@
+# Geodetic::Coordinates::LLA
+
+Latitude, Longitude, Altitude -- the most common geodetic coordinate system. Represents a position on (or above/below) the Earth's surface using angular degrees and a height in meters above the WGS84 reference ellipsoid.
+
+- A negative latitude is in the Southern hemisphere.
+- A negative longitude is in the Western hemisphere.
+- Altitude is in decimal meters above the ellipsoid.
+
+LLA is the **hub class** in the Geodetic library. It can convert directly to all other coordinate systems (ECEF, UTM, ENU, NED), making it the central interchange format.
+
+## Constructor
+
+```ruby
+Geodetic::Coordinates::LLA.new(lat: 0.0, lng: 0.0, alt: 0.0)
+```
+
+| Parameter | Type  | Default | Description                                |
+|-----------|-------|---------|--------------------------------------------|
+| `lat`     | Float | `0.0`   | Latitude in decimal degrees (-90..90)      |
+| `lng`     | Float | `0.0`   | Longitude in decimal degrees (-180..180)   |
+| `alt`     | Float | `0.0`   | Altitude in meters above the WGS84 ellipsoid |
+
+All values are coerced to `Float` via `.to_f`.
+
+### Validation
+
+The constructor raises `ArgumentError` if:
+
+- `lat` is outside the range `-90..90`
+- `lng` is outside the range `-180..180`
+
+## Attributes
+
+| Attribute   | Alias       | Access          |
+|-------------|-------------|-----------------|
+| `lat`       | `latitude`  | read/write      |
+| `lng`       | `longitude` | read/write      |
+| `alt`       | `altitude`  | read/write      |
+
+Setters validate ranges and coerce to `Float`. Setting `lat` outside `-90..90` or `lng` outside `-180..180` raises `ArgumentError`. The `alt` setter has no range constraint.
+
+## Conversions
+
+All conversion methods accept an optional `datum` parameter (defaults to `Geodetic::WGS84`).
+
+### to_ecef(datum = WGS84)
+
+Converts to Earth-Centered, Earth-Fixed Cartesian coordinates.
+
+```ruby
+lla = Geodetic::Coordinates::LLA.new(lat: 38.8977, lng: -77.0365, alt: 17.0)
+ecef = lla.to_ecef
+# => Geodetic::Coordinates::ECEF
+```
+
+### LLA.from_ecef(ecef, datum = WGS84)
+
+Creates an LLA from an ECEF instance. Raises `ArgumentError` if the argument is not an `ECEF`.
+
+### to_utm(datum = WGS84)
+
+Converts to Universal Transverse Mercator coordinates. The UTM zone and hemisphere are computed automatically from the longitude and latitude.
+
+```ruby
+utm = lla.to_utm
+# => Geodetic::Coordinates::UTM
+```
+
+### LLA.from_utm(utm, datum = WGS84)
+
+Creates an LLA from a UTM instance. Raises `ArgumentError` if the argument is not a `UTM`.
+
+### to_enu(reference_lla)
+
+Converts to East-North-Up local tangent plane coordinates relative to a reference LLA position.
+
+```ruby
+origin = Geodetic::Coordinates::LLA.new(lat: 38.8977, lng: -77.0365, alt: 17.0)
+point  = Geodetic::Coordinates::LLA.new(lat: 38.8987, lng: -77.0355, alt: 20.0)
+enu = point.to_enu(origin)
+# => Geodetic::Coordinates::ENU
+```
+
+Raises `ArgumentError` if `reference_lla` is not an `LLA`.
+
+### LLA.from_enu(enu, reference_lla)
+
+Creates an LLA from an ENU instance and a reference LLA origin. Raises `ArgumentError` if the arguments are not the expected types.
+
+### to_ned(reference_lla)
+
+Converts to North-East-Down local tangent plane coordinates relative to a reference LLA position.
+
+```ruby
+ned = point.to_ned(origin)
+# => Geodetic::Coordinates::NED
+```
+
+Raises `ArgumentError` if `reference_lla` is not an `LLA`.
+
+### LLA.from_ned(ned, reference_lla)
+
+Creates an LLA from a NED instance and a reference LLA origin. Raises `ArgumentError` if the arguments are not the expected types.
+
+## Serialization
+
+### to_s
+
+Returns a comma-separated string of `lat, lng, alt`.
+
+```ruby
+lla = Geodetic::Coordinates::LLA.new(lat: 38.8977, lng: -77.0365, alt: 17.0)
+lla.to_s
+# => "38.8977, -77.0365, 17.0"
+```
+
+### to_a
+
+Returns a three-element array `[lat, lng, alt]`.
+
+```ruby
+lla.to_a
+# => [38.8977, -77.0365, 17.0]
+```
+
+### LLA.from_string(string)
+
+Parses a comma-separated string into an LLA.
+
+```ruby
+lla = Geodetic::Coordinates::LLA.from_string("38.8977, -77.0365, 17.0")
+```
+
+### LLA.from_array(array)
+
+Creates an LLA from a three-element array `[lat, lng, alt]`.
+
+```ruby
+lla = Geodetic::Coordinates::LLA.from_array([38.8977, -77.0365, 17.0])
+```
+
+### to_dms
+
+Converts to a Degrees-Minutes-Seconds string with hemisphere indicators and altitude.
+
+```ruby
+lla = Geodetic::Coordinates::LLA.new(lat: 38.8977, lng: -77.0365, alt: 17.0)
+lla.to_dms
+# => "38° 53' 51.72\" N, 77° 2' 11.40\" W, 17.00 m"
+```
+
+### LLA.from_dms(dms_str)
+
+Parses a DMS-formatted string back into an LLA. The expected format is:
+
+```
+DD° MM' SS.ss" N/S, DDD° MM' SS.ss" E/W[, altitude m]
+```
+
+The altitude portion is optional and defaults to `0.0`.
+
+```ruby
+lla = Geodetic::Coordinates::LLA.from_dms("38° 53' 51.72\" N, 77° 2' 11.40\" W, 17.0 m")
+```
+
+Raises `ArgumentError` if the string does not match the expected format.
+
+## Additional Methods
+
+### ==(other)
+
+Compares two LLA instances for approximate equality. Returns `true` if:
+
+- `|lat difference| <= 1e-10`
+- `|lng difference| <= 1e-10`
+- `|alt difference| <= 1e-6`
+
+Returns `false` if `other` is not an `LLA`.
+
+```ruby
+a = Geodetic::Coordinates::LLA.new(lat: 38.8977, lng: -77.0365, alt: 17.0)
+b = Geodetic::Coordinates::LLA.new(lat: 38.8977, lng: -77.0365, alt: 17.0)
+a == b
+# => true
+```
+
+### to_gh36(precision: 10)
+
+Converts to Geohash-36 coordinates with configurable precision.
+
+```ruby
+gh36 = lla.to_gh36
+gh36 = lla.to_gh36(precision: 5)    # coarser precision
+# => Geodetic::Coordinates::GH36
+```
+
+### LLA.from_gh36(gh36_coord, datum = WGS84)
+
+Creates an LLA from a GH36 instance. Returns the midpoint of the geohash cell.
+
+```ruby
+lla = Geodetic::Coordinates::LLA.from_gh36(gh36)
+```
+
+## GeoidHeightSupport Mixin
+
+LLA includes the `Geodetic::GeoidHeightSupport` module, which provides methods for working with geoid heights and vertical datum conversions.
+
+### geoid_height(geoid_model = 'EGM2008')
+
+Returns the geoid undulation (in meters) at the coordinate's lat/lng for the specified geoid model.
+
+```ruby
+lla = Geodetic::Coordinates::LLA.new(lat: 38.8977, lng: -77.0365, alt: 17.0)
+lla.geoid_height
+# => Float (geoid undulation in meters)
+```
+
+Supported models: `'EGM96'`, `'EGM2008'`, `'GEOID18'`, `'GEOID12B'`.
+
+### orthometric_height(geoid_model = 'EGM2008')
+
+Returns the orthometric height (height above the geoid / mean sea level) by subtracting the geoid undulation from the ellipsoidal altitude.
+
+```ruby
+lla.orthometric_height
+# => Float (meters above geoid)
+```
+
+### convert_height_datum(from_datum, to_datum, geoid_model = 'EGM2008')
+
+Converts the altitude between vertical datums and returns a new LLA with the adjusted height. The original instance is not modified.
+
+```ruby
+lla_navd88 = lla.convert_height_datum('HAE', 'NAVD88')
+```
+
+Supported vertical datums: `'NAVD88'`, `'NGVD29'`, `'MSL'`, `'HAE'`.
+
+### Class Method: LLA.with_geoid_height(geoid_model = 'EGM2008')
+
+Sets the default geoid model for the class. Returns the class for chaining.
+
+```ruby
+Geodetic::Coordinates::LLA.with_geoid_height('EGM96')
+```
+
+## Code Examples
+
+### Round-trip conversion
+
+```ruby
+require 'geodetic'
+
+# Create an LLA coordinate
+lla = Geodetic::Coordinates::LLA.new(lat: 40.7128, lng: -74.0060, alt: 10.0)
+
+# Convert to ECEF and back
+ecef = lla.to_ecef
+lla_roundtrip = ecef.to_lla
+lla == lla_roundtrip
+# => true
+
+# Convert to UTM and back
+utm = lla.to_utm
+lla_roundtrip = utm.to_lla
+```
+
+### Local tangent plane
+
+```ruby
+origin = Geodetic::Coordinates::LLA.new(lat: 40.7128, lng: -74.0060, alt: 10.0)
+target = Geodetic::Coordinates::LLA.new(lat: 40.7138, lng: -74.0050, alt: 15.0)
+
+enu = target.to_enu(origin)
+ned = target.to_ned(origin)
+```
+
+### DMS formatting
+
+```ruby
+lla = Geodetic::Coordinates::LLA.new(lat: -33.8688, lng: 151.2093, alt: 58.0)
+puts lla.to_dms
+# => "33° 52' 7.68" S, 151° 12' 33.48" E, 58.00 m"
+
+restored = Geodetic::Coordinates::LLA.from_dms(lla.to_dms)
+```
+
+### Geoid height operations
+
+```ruby
+lla = Geodetic::Coordinates::LLA.new(lat: 38.8977, lng: -77.0365, alt: 50.0)
+
+# Get geoid undulation at this location
+puts lla.geoid_height           # EGM2008 (default)
+puts lla.geoid_height('EGM96')  # EGM96
+
+# Get height above mean sea level
+puts lla.orthometric_height
+
+# Convert from ellipsoidal height to NAVD88
+lla_navd88 = lla.convert_height_datum('HAE', 'NAVD88')
+puts lla_navd88.alt
+```

data/docs/coordinate-systems/mgrs.md

@@ -0,0 +1,81 @@
+# Geodetic::Coordinates::MGRS - Military Grid Reference System
+
+## Overview
+
+MGRS (Military Grid Reference System) is a geocoordinate standard used by NATO militaries for locating points on Earth. It is based on the UTM coordinate system, augmented with a lettering scheme for grid zone designators and 100km square identifiers.
+
+## Constructor
+
+### From a complete MGRS string
+
+```ruby
+MGRS.new(mgrs_string: "18SUJ2337006519")
+```
+
+### From individual components
+
+```ruby
+MGRS.new(
+  grid_zone:  "18S",
+  square_id:  "UJ",
+  easting:    23370,
+  northing:   06519,
+  precision:  5
+)
+```
+
+## String Representation
+
+| Method        | Description                                   |
+|---------------|-----------------------------------------------|
+| `from_string` | Parses an MGRS string into its components     |
+| `to_s`        | Returns the compact MGRS string representation |
+
+### Example
+
+```ruby
+mgrs = Geodetic::Coordinates::MGRS.new(mgrs_string: "18SUJ2337006519")
+mgrs.to_s  # => "18SUJ2337006519"
+```
+
+## Precision Levels
+
+MGRS supports five levels of precision, controlling the number of digits in the easting and northing components:
+
+| Precision | Digits (per axis) | Resolution |
+|-----------|--------------------|------------|
+| 1         | 1                  | 10 km      |
+| 2         | 2                  | 1 km       |
+| 3         | 3                  | 100 m      |
+| 4         | 4                  | 10 m       |
+| 5         | 5                  | 1 m        |
+
+## Components
+
+| Component    | Description                                        | Example |
+|--------------|----------------------------------------------------|---------|
+| `grid_zone`  | UTM zone number + latitude band letter              | `18S`   |
+| `square_id`  | 100km square identification (two-letter code)       | `UJ`    |
+| `easting`    | Easting within the 100km square                     | `23370` |
+| `northing`   | Northing within the 100km square                    | `06519` |
+| `precision`  | Number of digits per coordinate (1-5)               | `5`     |
+
+## Conversions
+
+MGRS converts to other coordinate systems via **UTM** and **LLA**:
+
+- **MGRS -> UTM** — Decomposes the grid zone and square ID back to UTM easting/northing.
+- **MGRS -> LLA** — Converts through UTM to latitude/longitude.
+
+## Example
+
+```ruby
+mgrs = Geodetic::Coordinates::MGRS.new(mgrs_string: "18SUJ2337006519")
+
+mgrs.grid_zone  # => "18S"
+mgrs.square_id  # => "UJ"
+mgrs.easting    # => 23370
+mgrs.northing   # => 06519
+mgrs.precision  # => 5
+mgrs.to_s       # => "18SUJ2337006519"
+```

data/docs/coordinate-systems/ned.md

@@ -0,0 +1,83 @@
+# Geodetic::Coordinates::NED - North, East, Down
+
+## Overview
+
+NED (North, East, Down) is a local tangent plane coordinate system commonly used in aviation and navigation. It defines positions relative to a local reference point on the Earth's surface, with axes pointing North, East, and Down.
+
+## Constructor
+
+```ruby
+NED.new(n: 0.0, e: 0.0, d: 0.0)
+```
+
+All parameters are in **meters**.
+
+## Attribute Aliases
+
+| Primary | Alias   |
+|---------|---------|
+| `n`     | `north` |
+| `e`     | `east`  |
+| `d`     | `down`  |
+
+## Reference Point
+
+NED 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 NED and ENU, which does not require a reference point.
+
+## Conversions
+
+### Direct (no reference point needed)
+
+- **NED <-> ENU** — A simple axis remap:
+  ```
+  NED(n, e, d) <-> ENU(e, n, -d)
+  ```
+
+### Via reference point
+
+- **NED -> LLA** — Requires a reference LLA.
+- **NED -> ECEF** — Requires a reference LLA.
+
+## Methods
+
+| Method                          | Description                                                              |
+|---------------------------------|--------------------------------------------------------------------------|
+| `horizontal_distance_to(other)` | Horizontal (N-E plane) distance to another NED point (meters)            |
+| `local_bearing_to(other)`       | Bearing from this point to another NED point (degrees from north, 0-360) |
+| `local_elevation_angle_to(other)` | Elevation angle from this point to another NED point (degrees)         |
+| `distance_to_origin`            | Euclidean distance from this point to the origin (meters)                |
+| `elevation_angle`               | Elevation angle from the origin to this point (degrees)                  |
+| `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
+
+NED is a relative coordinate system. The universal `distance_to`, `straight_line_distance_to`, `bearing_to`, and `elevation_to` methods raise `ArgumentError` because NED 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 = ned.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::NED.new(n: 200.0, e: 100.0, d: -50.0)
+
+point.north  # => 200.0
+point.east   # => 100.0
+point.down   # => -50.0
+
+point.distance_to_origin            # => Euclidean distance in meters
+point.bearing_from_origin           # => Bearing in degrees from north
+point.elevation_angle               # => Elevation angle in degrees
+point.horizontal_distance_to_origin # => Horizontal distance in meters
+```

data/docs/coordinate-systems/state-plane.md

@@ -0,0 +1,60 @@
+# Geodetic::Coordinates::StatePlane
+
+## US State Plane Coordinate System
+
+The State Plane Coordinate System (SPCS) is a set of 124 geographic zones used across the United States. Each zone uses either a Lambert Conformal Conic or Transverse Mercator projection, chosen to minimize distortion within that zone. Units are typically expressed in **US Survey Feet**.
+
+## Constructor
+
+```ruby
+point = Geodetic::Coordinates::StatePlane.new(
+  easting:   0.0,
+  northing:  0.0,
+  zone_code: 'CA_I',
+  datum:     Geodetic::Datum::WGS84
+)
+```
+
+- `easting` — Easting coordinate (typically in US Survey Feet)
+- `northing` — Northing coordinate (typically in US Survey Feet)
+- `zone_code` — Identifier for the State Plane zone
+- `datum` — The geodetic datum; stored internally on the coordinate object
+
+## Available Zones
+
+The following zone codes are currently supported:
+
+| Zone Code | State / Region |
+|---|---|
+| `CA_I` | California, Zone I |
+| `CA_II` | California, Zone II |
+| `TX_NORTH` | Texas, North |
+| `FL_EAST` | Florida, East |
+| `NY_LONG_ISLAND` | New York, Long Island |
+
+## Projections
+
+Each zone uses one of two map projections depending on its geographic shape:
+
+- **Lambert Conformal Conic** — Used for zones that are wider east-to-west
+- **Transverse Mercator** — Used for zones that are longer north-to-south
+
+## Unit Conversion
+
+```ruby
+meters_point    = point.to_meters
+feet_point      = point.to_us_survey_feet
+```
+
+## Methods
+
+| Method | Description |
+|---|---|
+| `zone_info` | Returns metadata about the current zone (projection type, parameters, bounds) |
+| `valid?` | Returns `true` if the coordinates fall within the defined zone bounds |
+| `zones_for_state(state)` | Class method. Returns available zone codes for a given US state |
+| `find_zone_for_lla(lla)` | Class method. Determines the appropriate State Plane zone for a given LLA coordinate |
+
+## Datum
+
+The `StatePlane` coordinate object stores its associated datum internally, accessible for reference during conversions and transformations.

data/docs/coordinate-systems/ups.md

@@ -0,0 +1,53 @@
+# Geodetic::Coordinates::UPS
+
+## Universal Polar Stereographic
+
+The Universal Polar Stereographic (UPS) coordinate system covers the polar regions of the Earth that fall outside the UTM grid: latitudes north of 84°N and south of 80°S. It uses a stereographic projection centered on each pole.
+
+## Constructor
+
+```ruby
+point = Geodetic::Coordinates::UPS.new(
+  easting:    0.0,
+  northing:   0.0,
+  hemisphere: 'N',
+  zone:       'Y'
+)
+```
+
+- `easting` — Easting coordinate in meters
+- `northing` — Northing coordinate in meters
+- `hemisphere` — `'N'` for the North Pole region, `'S'` for the South Pole region
+- `zone` — UPS zone letter
+
+## Zones
+
+UPS divides each polar region into two zones based on longitude:
+
+| Hemisphere | Zones | Longitude Range |
+|---|---|---|
+| North | Y, Z | Y: 180°W to 0°; Z: 0° to 180°E |
+| South | A, B | A: 180°W to 0°; B: 0° to 180°E |
+
+## False Origin
+
+Both easting and northing use a **false origin of 2,000,000 meters** to ensure all coordinate values remain positive within the projection.
+
+## Methods
+
+| Method | Description |
+|---|---|
+| `grid_convergence` | Returns the angular difference between grid north and true north at the point |
+| `point_scale_factor` | Returns the scale distortion factor at the point's location |
+| `valid?` | Returns `true` if the coordinates represent a valid UPS position |
+
+### Universal Distance Methods
+
+The universal `distance_to` method computes the Vincenty great-circle distance (in meters) to any other coordinate type. The `straight_line_distance_to` method computes the Euclidean distance in ECEF space. Both accept single or multiple targets.
+
+```ruby
+ups_a = Geodetic::Coordinates::UPS.new(easting: 2000000.0, northing: 2000000.0, hemisphere: 'N', zone: 'Z')
+ups_b = Geodetic::Coordinates::UPS.new(easting: 2100000.0, northing: 2100000.0, hemisphere: 'N', zone: 'Z')
+ups_a.distance_to(ups_b)                # => Distance (meters, great-circle)
+ups_a.straight_line_distance_to(ups_b)  # => Distance (meters, Euclidean)
+```

data/docs/coordinate-systems/usng.md

@@ -0,0 +1,74 @@
+# Geodetic::Coordinates::USNG - US National Grid
+
+## Overview
+
+USNG (US National Grid) is a coordinate system based on MGRS, adopted for use by US emergency services and civilian agencies. It provides a consistent, interoperable grid reference system across the United States.
+
+## Constructor
+
+### From a complete USNG string
+
+```ruby
+USNG.new(usng_string: "18T WL 12345 67890")
+```
+
+### From individual components
+
+```ruby
+USNG.new(
+  grid_zone:  "18T",
+  square_id:  "WL",
+  easting:    12345,
+  northing:   67890,
+  precision:  5
+)
+```
+
+## Format Differences from MGRS
+
+USNG uses a **spaced format** for readability, whereas MGRS uses a compact (unspaced) format:
+
+| System | Format                    |
+|--------|---------------------------|
+| USNG   | `18T WL 12345 67890`      |
+| MGRS   | `18TWL1234567890`         |
+
+## String Representation
+
+| Method                   | Description                                         |
+|--------------------------|-----------------------------------------------------|
+| `from_string`            | Parses a USNG string into its components            |
+| `to_s`                   | Returns the USNG string representation              |
+| `to_full_format`         | Returns the full spaced USNG format                 |
+| `to_abbreviated_format`  | Returns an abbreviated representation               |
+
+## Validation
+
+| Method   | Description                                                       |
+|----------|-------------------------------------------------------------------|
+| `valid?` | Checks that the zone designator falls within valid US zones       |
+
+## Conversions
+
+USNG converts through **MGRS** internally. All coordinate conversions follow the chain:
+
+```
+USNG <-> MGRS <-> UTM <-> LLA
+```
+
+## Example
+
+```ruby
+usng = Geodetic::Coordinates::USNG.new(usng_string: "18T WL 12345 67890")
+
+usng.grid_zone  # => "18T"
+usng.square_id  # => "WL"
+usng.easting    # => 12345
+usng.northing   # => 67890
+usng.precision  # => 5
+
+usng.to_s                  # => "18T WL 12345 67890"
+usng.to_full_format        # => Full spaced format
+usng.to_abbreviated_format # => Abbreviated format
+usng.valid?                # => true (if within valid US zones)
+```