geodetic 0.0.1

data/docs/coordinate-systems/utm.md

@@ -0,0 +1,257 @@
+# Geodetic::Coordinates::UTM
+
+Universal Transverse Mercator -- a projected coordinate system that divides the Earth into 60 longitudinal zones (each 6 degrees wide) and two hemispheres (North and South). Positions within each zone are expressed as easting and northing distances in meters from the zone's origin. UTM is widely used in military, engineering, and surveying applications because it provides a flat, metric grid that minimizes distortion within each zone.
+
+## Constructor
+
+```ruby
+Geodetic::Coordinates::UTM.new(easting: 0.0, northing: 0.0, altitude: 0.0, zone: 1, hemisphere: 'N')
+```
+
+| Parameter    | Type    | Default | Description                                 |
+|--------------|---------|---------|---------------------------------------------|
+| `easting`    | Float   | `0.0`   | Easting in meters (must be >= 0)            |
+| `northing`   | Float   | `0.0`   | Northing in meters (must be >= 0)           |
+| `altitude`   | Float   | `0.0`   | Altitude in meters above the ellipsoid      |
+| `zone`       | Integer | `1`     | UTM zone number (1..60)                     |
+| `hemisphere` | String  | `'N'`   | Hemisphere: `'N'` (North) or `'S'` (South) |
+
+Numeric values are coerced via `.to_f` / `.to_i`. The hemisphere string is uppercased automatically.
+
+### Validation
+
+The constructor raises `ArgumentError` if:
+
+- `zone` is outside the range `1..60`
+- `hemisphere` is not `'N'` or `'S'`
+- `easting` is negative
+- `northing` is negative
+
+## Attributes
+
+| Attribute    | Alias | Access     |
+|--------------|-------|------------|
+| `easting`    | `x`   | read/write |
+| `northing`   | `y`   | read/write |
+| `altitude`   | `z`   | read/write |
+| `zone`       | --    | read/write |
+| `hemisphere` | --    | read/write |
+
+Setters validate and coerce types. `easting` and `northing` must be non-negative (`ArgumentError`). `zone` must be `1..60`. `hemisphere` must be `'N'` or `'S'` (auto-upcased). `altitude` has no range constraint.
+
+## Conversions
+
+All conversion methods accept an optional `datum` parameter (defaults to `Geodetic::WGS84`).
+
+### to_lla(datum = WGS84)
+
+Converts to geodetic Latitude, Longitude, Altitude coordinates. Uses a series expansion for the inverse UTM projection.
+
+```ruby
+utm = Geodetic::Coordinates::UTM.new(easting: 580000.0, northing: 4510000.0, zone: 18, hemisphere: 'N')
+lla = utm.to_lla
+# => Geodetic::Coordinates::LLA
+```
+
+### UTM.from_lla(lla, datum = WGS84)
+
+Creates a UTM from an LLA instance. The zone and hemisphere are computed automatically. Raises `ArgumentError` if the argument is not an `LLA`.
+
+```ruby
+utm = Geodetic::Coordinates::UTM.from_lla(lla)
+```
+
+### to_ecef(datum = WGS84)
+
+Converts to Earth-Centered, Earth-Fixed Cartesian coordinates. Internally converts to LLA first, then to ECEF.
+
+```ruby
+ecef = utm.to_ecef
+# => Geodetic::Coordinates::ECEF
+```
+
+### UTM.from_ecef(ecef, datum = WGS84)
+
+Creates a UTM from an ECEF instance. Raises `ArgumentError` if the argument is not an `ECEF`.
+
+### to_enu(reference_lla, datum = WGS84)
+
+Converts to East-North-Up local tangent plane coordinates relative to a reference LLA position.
+
+```ruby
+origin = Geodetic::Coordinates::LLA.new(lat: 40.7128, lng: -74.0060, alt: 10.0)
+enu = utm.to_enu(origin)
+# => Geodetic::Coordinates::ENU
+```
+
+Raises `ArgumentError` if `reference_lla` is not an `LLA`.
+
+### UTM.from_enu(enu, reference_lla, datum = WGS84)
+
+Creates a UTM from an ENU instance and a reference LLA origin. Raises `ArgumentError` if the arguments are not the expected types.
+
+### to_ned(reference_lla, datum = WGS84)
+
+Converts to North-East-Down local tangent plane coordinates relative to a reference LLA position.
+
+```ruby
+ned = utm.to_ned(origin)
+# => Geodetic::Coordinates::NED
+```
+
+Raises `ArgumentError` if `reference_lla` is not an `LLA`.
+
+### UTM.from_ned(ned, reference_lla, datum = WGS84)
+
+Creates a UTM 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 `easting, northing, altitude, zone, hemisphere`.
+
+```ruby
+utm = Geodetic::Coordinates::UTM.new(easting: 580000.0, northing: 4510000.0, altitude: 10.0, zone: 18, hemisphere: 'N')
+utm.to_s
+# => "580000.0, 4510000.0, 10.0, 18, N"
+```
+
+### to_a
+
+Returns a five-element array `[easting, northing, altitude, zone, hemisphere]`.
+
+```ruby
+utm.to_a
+# => [580000.0, 4510000.0, 10.0, 18, "N"]
+```
+
+### UTM.from_string(string)
+
+Parses a comma-separated string into a UTM.
+
+```ruby
+utm = Geodetic::Coordinates::UTM.from_string("580000.0, 4510000.0, 10.0, 18, N")
+```
+
+### UTM.from_array(array)
+
+Creates a UTM from a five-element array `[easting, northing, altitude, zone, hemisphere]`.
+
+```ruby
+utm = Geodetic::Coordinates::UTM.from_array([580000.0, 4510000.0, 10.0, 18, "N"])
+```
+
+## Additional Methods
+
+### ==(other)
+
+Compares two UTM instances for approximate equality. Returns `true` if:
+
+- `|easting difference| <= 1e-6`
+- `|northing difference| <= 1e-6`
+- `|altitude difference| <= 1e-6`
+- `zone` values are equal
+- `hemisphere` values are equal
+
+Returns `false` if `other` is not a `UTM`.
+
+```ruby
+a = Geodetic::Coordinates::UTM.new(easting: 580000.0, northing: 4510000.0, zone: 18, hemisphere: 'N')
+b = Geodetic::Coordinates::UTM.new(easting: 580000.0, northing: 4510000.0, zone: 18, hemisphere: 'N')
+a == b
+# => true
+```
+
+### distance_to(other, *others)
+
+Computes the Vincenty great-circle distance to one or more other coordinates. Works across UTM zones and across different coordinate types (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::UTM.new(easting: 580000.0, northing: 4510000.0, altitude: 10.0, zone: 18, hemisphere: 'N')
+b = Geodetic::Coordinates::UTM.new(easting: 580100.0, northing: 4510200.0, altitude: 15.0, zone: 18, hemisphere: 'N')
+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. Returns a `Distance` for a single target or an Array of `Distance` objects for multiple targets.
+
+```ruby
+a.straight_line_distance_to(b)
+# => Distance (meters)
+```
+
+### same_zone?(other)
+
+Returns `true` if both UTM instances share the same zone number and hemisphere.
+
+```ruby
+a = Geodetic::Coordinates::UTM.new(easting: 580000.0, northing: 4510000.0, zone: 18, hemisphere: 'N')
+b = Geodetic::Coordinates::UTM.new(easting: 590000.0, northing: 4520000.0, zone: 18, hemisphere: 'N')
+a.same_zone?(b)
+# => true
+```
+
+Raises `ArgumentError` if `other` is not a `UTM`.
+
+### central_meridian
+
+Returns the central meridian longitude (in degrees) for the UTM zone.
+
+```ruby
+utm = Geodetic::Coordinates::UTM.new(zone: 18, hemisphere: 'N')
+utm.central_meridian
+# => -75
+```
+
+The formula is: `(zone - 1) * 6 - 180 + 3`.
+
+## Code Examples
+
+### Round-trip conversion
+
+```ruby
+require 'geodetic'
+
+# Start with an LLA and convert to UTM
+lla = Geodetic::Coordinates::LLA.new(lat: 40.7128, lng: -74.0060, alt: 10.0)
+utm = lla.to_utm
+puts utm.to_s
+# zone and hemisphere are determined automatically
+
+# Convert back to LLA
+lla_roundtrip = utm.to_lla
+```
+
+### Distance calculations
+
+```ruby
+point_a = Geodetic::Coordinates::UTM.new(
+  easting: 583960.0, northing: 4507523.0,
+  altitude: 10.0, zone: 18, hemisphere: 'N'
+)
+point_b = Geodetic::Coordinates::UTM.new(
+  easting: 584060.0, northing: 4507623.0,
+  altitude: 15.0, zone: 18, hemisphere: 'N'
+)
+
+# Great-circle distance (works across zones and coordinate types)
+puts "Distance:    #{point_a.distance_to(point_b).meters} m"
+
+# Straight-line (Euclidean) distance
+puts "Straight:    #{point_a.straight_line_distance_to(point_b).meters} m"
+
+puts "Same zone?   #{point_a.same_zone?(point_b)}"
+```
+
+### Working with zones
+
+```ruby
+# Check which zone a location falls in
+lla = Geodetic::Coordinates::LLA.new(lat: 48.8566, lng: 2.3522, alt: 35.0)  # Paris
+utm = lla.to_utm
+puts "Zone: #{utm.zone}#{utm.hemisphere}"       # => "31N"
+puts "Central meridian: #{utm.central_meridian}" # => 3
+```

data/docs/coordinate-systems/web-mercator.md

@@ -0,0 +1,67 @@
+# Geodetic::Coordinates::WebMercator
+
+## Web Mercator (EPSG:3857)
+
+Web Mercator is the de facto standard projection used by major web mapping platforms including Google Maps, OpenStreetMap, and Bing Maps. It projects the Earth onto a square grid using a spherical Mercator projection, making it well-suited for tiled map rendering.
+
+## Constructor
+
+```ruby
+point = Geodetic::Coordinates::WebMercator.new(x: 0.0, y: 0.0)
+```
+
+Parameters `x` and `y` are specified in **meters** from the projection origin (the intersection of the Equator and the Prime Meridian).
+
+## Constants
+
+| Constant | Description |
+|---|---|
+| `EARTH_RADIUS` | Radius of the Earth used for projection calculations |
+| `ORIGIN_SHIFT` | Half the circumference of the Earth at the Equator; defines the extent of the projected coordinate space |
+| `MAX_LATITUDE` | Maximum representable latitude (~85.051°); the projection is undefined beyond this limit |
+
+## Tile Coordinate Methods
+
+Convert between Web Mercator coordinates and map tile indices at a given zoom level.
+
+```ruby
+tile_x, tile_y = point.to_tile_coordinates(zoom)
+
+point = Geodetic::Coordinates::WebMercator.from_tile_coordinates(x, y, zoom)
+```
+
+## Pixel Coordinate Methods
+
+Convert between Web Mercator coordinates and pixel positions at a given zoom level and tile size.
+
+```ruby
+pixel_x, pixel_y = point.to_pixel_coordinates(zoom, tile_size)
+
+point = Geodetic::Coordinates::WebMercator.from_pixel_coordinates(x, y, zoom, tile_size)
+```
+
+## Tile Bounds
+
+Retrieve the bounding box of a specific tile.
+
+```ruby
+bounds = Geodetic::Coordinates::WebMercator.tile_bounds(tile_x, tile_y, zoom)
+```
+
+## Validation and Utility Methods
+
+| Method | Description |
+|---|---|
+| `valid?` | Returns `true` if the coordinates fall within the valid Web Mercator extent |
+| `clamp!` | Clamps coordinates to the valid range, modifying the object in place |
+
+### 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
+wm_a = Geodetic::Coordinates::WebMercator.new(x: -13627665.0, y: 6044499.0)
+wm_b = Geodetic::Coordinates::WebMercator.new(x: -13631157.0, y: 5694043.0)
+wm_a.distance_to(wm_b)                # => Distance (meters, great-circle)
+wm_a.straight_line_distance_to(wm_b)  # => Distance (meters, Euclidean)
+```

data/docs/getting-started/installation.md

@@ -0,0 +1,65 @@
+# Installation
+
+## Requirements
+
+Geodetic is tested with **Ruby 4.0.1**. It has no runtime dependencies beyond the Ruby standard library.
+
+## Add to Your Gemfile
+
+```ruby
+gem "geodetic"
+```
+
+Then run:
+
+```sh
+bundle install
+```
+
+## Or Install Directly
+
+```sh
+gem install geodetic
+```
+
+## Require the Gem
+
+The simplest way to load Geodetic is to require the top-level module:
+
+```ruby
+require "geodetic"
+```
+
+This loads the core module, the `Geodetic::Datum` class, and the `Geodetic::GeoidHeight` support. Coordinate types are loaded on demand when you first perform a conversion.
+
+## Requiring Specific Coordinate Types
+
+If you want to use a coordinate class directly without going through a conversion, require it explicitly:
+
+```ruby
+require "geodetic"
+require "geodetic/coordinates/lla"
+require "geodetic/coordinates/ecef"
+require "geodetic/coordinates/utm"
+require "geodetic/coordinates/enu"
+require "geodetic/coordinates/ned"
+require "geodetic/coordinates/mgrs"
+require "geodetic/coordinates/usng"
+require "geodetic/coordinates/web_mercator"
+require "geodetic/coordinates/ups"
+require "geodetic/coordinates/state_plane"
+require "geodetic/coordinates/bng"
+```
+
+You only need to require the types you plan to construct directly. Conversion methods handle their own requires internally.
+
+## Verify the Installation
+
+```ruby
+require "geodetic"
+require "geodetic/coordinates/lla"
+
+lla = Geodetic::Coordinates::LLA.new(lat: 47.6205, lng: -122.3493, alt: 184.0)
+puts lla.to_s
+#=> "47.6205, -122.3493, 184.0"
+```

data/docs/getting-started/quick-start.md

@@ -0,0 +1,175 @@
+# Quick Start
+
+This guide walks through the core features of Geodetic using the Seattle Space Needle as a reference point.
+
+## 1. Create an LLA Coordinate
+
+LLA (Latitude, Longitude, Altitude) is the most common starting point. All constructors use keyword arguments.
+
+```ruby
+require "geodetic"
+require "geodetic/coordinates/lla"
+
+space_needle = Geodetic::Coordinates::LLA.new(
+  lat: 47.6205,
+  lng: -122.3493,
+  alt: 184.0
+)
+
+puts space_needle.lat       #=> 47.6205
+puts space_needle.longitude #=> -122.3493 (alias for lng)
+puts space_needle.alt       #=> 184.0
+```
+
+## 2. Convert to ECEF
+
+ECEF (Earth-Centered, Earth-Fixed) represents a position as X, Y, Z coordinates in meters relative to the center of the Earth.
+
+```ruby
+ecef = space_needle.to_ecef
+
+puts ecef.x  # X coordinate in meters
+puts ecef.y  # Y coordinate in meters
+puts ecef.z  # Z coordinate in meters
+
+# Convert back to LLA
+lla = ecef.to_lla
+puts lla.to_s  #=> "47.6205, -122.3493, 184.0"
+```
+
+## 3. Convert to UTM
+
+UTM (Universal Transverse Mercator) is widely used in mapping and surveying.
+
+```ruby
+utm = space_needle.to_utm
+
+puts utm.easting     # easting in meters
+puts utm.northing    # northing in meters
+puts utm.altitude    # altitude in meters
+puts utm.zone        # UTM zone number (e.g., 10)
+puts utm.hemisphere  # "N" or "S"
+
+# Convert back to LLA
+lla = utm.to_lla
+```
+
+## 4. Convert to Local Coordinates (ENU and NED)
+
+Local tangent plane coordinate systems require a reference point. ENU (East, North, Up) and NED (North, East, Down) are commonly used in navigation and aerospace.
+
+```ruby
+# Define a reference point (e.g., a nearby base station)
+reference = Geodetic::Coordinates::LLA.new(
+  lat: 47.6062,
+  lng: -122.3321,
+  alt: 0.0
+)
+
+# Convert to ENU relative to the reference
+enu = space_needle.to_enu(reference)
+
+puts enu.east   # meters east of reference (alias: e)
+puts enu.north  # meters north of reference (alias: n)
+puts enu.up     # meters above reference (alias: u)
+
+# Convert to NED relative to the reference
+ned = space_needle.to_ned(reference)
+
+puts ned.north  # meters north of reference (alias: n)
+puts ned.east   # meters east of reference (alias: e)
+puts ned.down   # meters below reference (alias: d)
+
+# ENU and NED convert directly to each other
+ned_from_enu = enu.to_ned
+enu_from_ned = ned.to_enu
+
+# Convert back to LLA
+lla = enu.to_lla(reference)
+```
+
+## 5. Use DMS Format
+
+LLA coordinates can be displayed and parsed in Degrees, Minutes, Seconds format.
+
+```ruby
+# Convert to DMS string
+dms = space_needle.to_dms
+puts dms  #=> "47 37' 13.80\" N, 122 20' 57.48\" W, 184.00 m"
+
+# Parse a DMS string back to LLA
+lla = Geodetic::Coordinates::LLA.from_dms("47 37' 13.80\" N, 122 20' 57.48\" W, 184.00 m")
+puts lla.lat  #=> 47.6205
+```
+
+## 6. Serialize and Deserialize
+
+Every coordinate type supports `to_s`, `to_a`, `from_string`, and `from_array` for serialization.
+
+```ruby
+# Serialize to string and array
+str = space_needle.to_s    #=> "47.6205, -122.3493, 184.0"
+arr = space_needle.to_a    #=> [47.6205, -122.3493, 184.0]
+
+# Deserialize
+lla_from_str = Geodetic::Coordinates::LLA.from_string(str)
+lla_from_arr = Geodetic::Coordinates::LLA.from_array(arr)
+
+# Works the same for all coordinate types
+ecef = space_needle.to_ecef
+ecef_str = ecef.to_s
+ecef_arr = ecef.to_a
+ecef_restored = Geodetic::Coordinates::ECEF.from_string(ecef_str)
+ecef_restored = Geodetic::Coordinates::ECEF.from_array(ecef_arr)
+```
+
+## 7. Work with Datums
+
+Geodetic ships with 16 geodetic datums. All conversion methods default to WGS84 but accept an optional datum parameter.
+
+```ruby
+# List available datums
+Geodetic::Datum.list
+
+# Use a specific datum
+clarke = Geodetic::Datum.new(name: "CLARKE_1866")
+
+ecef_clarke = space_needle.to_ecef(clarke)
+utm_clarke  = space_needle.to_utm(clarke)
+
+# Inspect datum properties
+puts clarke.name    #=> "CLARKE_1866"
+puts clarke.desc    #=> "Clarke 1866"
+puts clarke.a       #=> 6378206.4 (semi-major axis in meters)
+puts clarke.b       #=> 6356583.7999989809 (semi-minor axis in meters)
+puts clarke.f       #=> flattening
+puts clarke.e2      #=> eccentricity squared
+
+# Look up datum info without creating an instance
+info = Geodetic::Datum.get("WGS84")
+puts info["desc"]   #=> "World Geodetic System 1984"
+```
+
+Available datums include: WGS84, WGS72, GRS_1980, CLARKE_1866, CLARKE_1880, AIRY, MODIFIED_AIRY, AUSTRALIAN_NATIONAL, BESSEL_1841, EVEREST_INDIA_1830, EVEREST_BRUNEI_E_MALAYSIA, EVEREST_W_MALAYSIA_SINGAPORE, HELMERT_1906, HOUGH_1960, INTERNATIONAL_1924, and SOUTH_AMERICAN_1969.
+
+## 8. Geoid Height
+
+The `GeoidHeight` class converts between ellipsoidal heights (HAE) and orthometric heights (e.g., NAVD88, MSL). LLA coordinates include geoid height support directly.
+
+```ruby
+# Get the geoid undulation at a location
+undulation = space_needle.geoid_height
+puts undulation  # geoid height in meters (EGM2008 model)
+
+# Get orthometric height (height above mean sea level)
+ortho = space_needle.orthometric_height
+puts ortho  # orthometric height in meters
+
+# Convert between vertical datums
+lla_navd88 = space_needle.convert_height_datum("HAE", "NAVD88")
+
+# Use a different geoid model
+undulation_egm96 = space_needle.geoid_height("EGM96")
+```
+
+Available geoid models: EGM96, EGM2008, GEOID18, GEOID12B.

data/docs/index.md

@@ -0,0 +1,58 @@
+# Geodetic
+
+Geodetic is a Ruby gem for converting between geodetic coordinate systems. It provides a clean, consistent API for working with 12 coordinate systems, 16 geodetic datums, geoid height calculations, and geographic area computations.
+
+## Coordinate Systems
+
+Geodetic supports full bidirectional conversion between all 12 coordinate systems:
+
+| System | Class | Description |
+|--------|-------|-------------|
+| **LLA** | `Geodetic::Coordinates::LLA` | Latitude, Longitude, Altitude |
+| **ECEF** | `Geodetic::Coordinates::ECEF` | Earth-Centered, Earth-Fixed (X, Y, Z) |
+| **UTM** | `Geodetic::Coordinates::UTM` | Universal Transverse Mercator |
+| **ENU** | `Geodetic::Coordinates::ENU` | East, North, Up (local tangent plane) |
+| **NED** | `Geodetic::Coordinates::NED` | North, East, Down (local tangent plane) |
+| **MGRS** | `Geodetic::Coordinates::MGRS` | Military Grid Reference System |
+| **USNG** | `Geodetic::Coordinates::USNG` | United States National Grid |
+| **WebMercator** | `Geodetic::Coordinates::WebMercator` | Web Mercator projection (EPSG:3857) |
+| **UPS** | `Geodetic::Coordinates::UPS` | Universal Polar Stereographic |
+| **StatePlane** | `Geodetic::Coordinates::StatePlane` | State Plane Coordinate System |
+| **BNG** | `Geodetic::Coordinates::BNG` | British National Grid |
+| **GH36** | `Geodetic::Coordinates::GH36` | Geohash-36 (spatial hash, URL-friendly) |
+
+## Additional Features
+
+- **16 geodetic datums** -- WGS84, GRS 1980, Clarke 1866, Airy 1830, Bessel 1841, and more. All conversion methods accept an optional datum parameter, defaulting to WGS84.
+- **Geoid height calculations** -- Convert between ellipsoidal and orthometric heights using models such as EGM96, EGM2008, GEOID18, and GEOID12B.
+- **Geographic areas** -- `Geodetic::Areas::Circle`, `Geodetic::Areas::Polygon`, and `Geodetic::Areas::Rectangle` for point-in-area testing.
+
+## Design Principles
+
+- All constructors use **keyword arguments** for clarity.
+- Every coordinate system supports **serialization** via `to_s` and `to_a`, and **deserialization** via `from_string` and `from_array`.
+- Conversions are available as instance methods (`to_ecef`, `to_utm`, etc.) and class-level factory methods (`from_ecef`, `from_utm`, etc.).
+
+## Quick Example
+
+```ruby
+require "geodetic"
+
+# Create an LLA coordinate (Seattle Space Needle)
+lla = Geodetic::Coordinates::LLA.new(lat: 47.6205, lng: -122.3493, alt: 184.0)
+
+# Convert to ECEF
+ecef = lla.to_ecef
+puts ecef.to_s
+#=> "-2689653.22..., -4251180.82..., 4696587.81..."
+
+# Convert back to LLA
+lla_again = ecef.to_lla
+puts lla_again.to_s
+#=> "47.6205, -122.3493, 184.0"
+```
+
+## Documentation
+
+- [Getting Started: Installation](getting-started/installation.md)
+- [Getting Started: Quick Start](getting-started/quick-start.md)