geodetic 0.0.1

data/lib/geodetic/coordinates/lla.rb

@@ -0,0 +1,268 @@
+# frozen_string_literal: true
+
+################################
+## Latitude, Longitude, Altitude
+##
+## A negative longitude is the Western hemisphere.
+## A negative latitude is in the Southern hemisphere.
+## Altitude is in decimal meters
+
+require_relative '../datum'
+require_relative '../geoid_height'
+
+module Geodetic
+  module Coordinates
+    class LLA
+      include GeoidHeightSupport
+      attr_reader :lat, :lng, :alt
+      alias_method :latitude, :lat
+      alias_method :longitude, :lng
+      alias_method :altitude, :alt
+
+      def initialize(lat: 0.0, lng: 0.0, alt: 0.0)
+        @lat = lat.to_f
+        @lng = lng.to_f
+        @alt = alt.to_f
+
+        validate_coordinates!
+      end
+
+      def lat=(value)
+        value = value.to_f
+        raise ArgumentError, "Latitude must be a finite number" if value.nan? || value.infinite?
+        raise ArgumentError, "Latitude must be between -90 and 90 degrees" if value < -90 || value > 90
+        @lat = value
+      end
+      alias_method :latitude=, :lat=
+
+      def lng=(value)
+        value = value.to_f
+        raise ArgumentError, "Longitude must be a finite number" if value.nan? || value.infinite?
+        raise ArgumentError, "Longitude must be between -180 and 180 degrees" if value < -180 || value > 180
+        @lng = value
+      end
+      alias_method :longitude=, :lng=
+
+      def alt=(value)
+        value = value.to_f
+        raise ArgumentError, "Altitude must be a finite number" if value.nan? || value.infinite?
+        @alt = value
+      end
+      alias_method :altitude=, :alt=
+
+      def to_ecef(datum = WGS84)
+        latitude_rad  = @lat * RAD_PER_DEG
+        longitude_rad = @lng * RAD_PER_DEG
+
+        a  = datum.a
+        e2 = datum.e2
+
+        n = a / Math.sqrt(1 - e2 * (Math.sin(latitude_rad))**2)
+
+        cos_lat = Math.cos(latitude_rad)
+        sin_lat = Math.sin(latitude_rad)
+        cos_lon = Math.cos(longitude_rad)
+        sin_lon = Math.sin(longitude_rad)
+
+        x = (n + @alt) * cos_lat * cos_lon
+        y = (n + @alt) * cos_lat * sin_lon
+        z = (n * (1 - e2) + @alt) * sin_lat
+
+        ECEF.new(x: x, y: y, z: z)
+      end
+
+      def self.from_ecef(ecef, datum = WGS84)
+        raise ArgumentError, "Expected ECEF" unless ecef.is_a?(ECEF)
+
+        ecef.to_lla(datum)
+      end
+
+      def to_utm(datum = WGS84)
+        lat_rad = @lat * RAD_PER_DEG
+        lon_rad = @lng * RAD_PER_DEG
+
+        zone = (((@lng + 180) / 6).floor + 1).to_i
+        zone = 60 if zone > 60
+        zone = 1 if zone < 1
+
+        a = datum.a
+        e2 = datum.e2
+        e4 = e2 * e2
+        e6 = e4 * e2
+
+        lon0_deg = (zone - 1) * 6 - 180 + 3
+        lon0_rad = lon0_deg * RAD_PER_DEG
+
+        k0 = 0.9996
+
+        sin_lat = Math.sin(lat_rad)
+        cos_lat = Math.cos(lat_rad)
+        tan_lat = Math.tan(lat_rad)
+
+        n = a / Math.sqrt(1 - e2 * sin_lat**2)
+        t = tan_lat
+        t2 = t * t
+        c = e2 * cos_lat**2 / (1 - e2)
+        aa = cos_lat * (lon_rad - lon0_rad)
+
+        # Meridional arc — distance along the meridian from equator to lat_rad
+        m = a * ((1 - e2 / 4 - 3 * e4 / 64 - 5 * e6 / 256) * lat_rad -
+                 (3 * e2 / 8 + 3 * e4 / 32 + 45 * e6 / 1024) * Math.sin(2 * lat_rad) +
+                 (15 * e4 / 256 + 45 * e6 / 1024) * Math.sin(4 * lat_rad) -
+                 (35 * e6 / 3072) * Math.sin(6 * lat_rad))
+
+        x = k0 * n * (aa +
+                       (1 - t2 + c) * aa**3 / 6 +
+                       (5 - 18 * t2 + t2**2 + 72 * c - 58 * e2 / (1 - e2)) * aa**5 / 120)
+
+        y = k0 * (m + n * t * (aa**2 / 2 +
+                                (5 - t2 + 9 * c + 4 * c**2) * aa**4 / 24 +
+                                (61 - 58 * t2 + t2**2 + 600 * c - 330 * e2 / (1 - e2)) * aa**6 / 720))
+
+        x += 500000
+        y += 10000000 if @lat < 0
+
+        hemisphere = @lat >= 0 ? 'N' : 'S'
+
+        UTM.new(easting: x, northing: y, altitude: @alt, zone: zone, hemisphere: hemisphere)
+      end
+
+      def self.from_utm(utm, datum = WGS84)
+        raise ArgumentError, "Expected UTM" unless utm.is_a?(UTM)
+
+        utm.to_lla(datum)
+      end
+
+      def to_ned(reference_lla)
+        raise ArgumentError, "Expected LLA" unless reference_lla.is_a?(LLA)
+
+        ecef = self.to_ecef
+        ref_ecef = reference_lla.to_ecef
+
+        ecef.to_ned(ref_ecef, reference_lla)
+      end
+
+      def self.from_ned(ned, reference_lla)
+        raise ArgumentError, "Expected NED" unless ned.is_a?(NED)
+        raise ArgumentError, "Expected LLA" unless reference_lla.is_a?(LLA)
+
+        ned.to_lla(reference_lla)
+      end
+
+      def to_enu(reference_lla)
+        raise ArgumentError, "Expected LLA" unless reference_lla.is_a?(LLA)
+
+        ecef = self.to_ecef
+        ref_ecef = reference_lla.to_ecef
+
+        ecef.to_enu(ref_ecef, reference_lla)
+      end
+
+      def self.from_enu(enu, reference_lla)
+        raise ArgumentError, "Expected ENU" unless enu.is_a?(ENU)
+        raise ArgumentError, "Expected LLA" unless reference_lla.is_a?(LLA)
+
+        enu.to_lla(reference_lla)
+      end
+
+      def to_dms
+        lat_abs = @lat.abs
+        lat_deg = lat_abs.floor
+        lat_min_total = (lat_abs - lat_deg) * 60.0
+        lat_min = lat_min_total.floor
+        lat_sec = (lat_min_total - lat_min) * 60.0
+        lat_hemi = @lat >= 0 ? 'N' : 'S'
+
+        lon_abs = @lng.abs
+        lon_deg = lon_abs.floor
+        lon_min_total = (lon_abs - lon_deg) * 60.0
+        lon_min = lon_min_total.floor
+        lon_sec = (lon_min_total - lon_min) * 60.0
+        lon_hemi = @lng >= 0 ? 'E' : 'W'
+
+        lat_str = format("%d° %d' %.2f\" %s", lat_deg, lat_min, lat_sec, lat_hemi)
+        lon_str = format("%d° %d' %.2f\" %s", lon_deg, lon_min, lon_sec, lon_hemi)
+        alt_str = format("%.2f m", @alt)
+
+        "#{lat_str}, #{lon_str}, #{alt_str}"
+      end
+
+      def self.from_dms(dms_str)
+        regex = /^\s*([0-9]+)°\s*([0-9]+)'\s*([0-9]+(?:\.[0-9]+)?)"\s*([NS])\s*,\s*([0-9]+)°\s*([0-9]+)'\s*([0-9]+(?:\.[0-9]+)?)"\s*([EW])\s*(?:,\s*([\-+]?[0-9]+(?:\.[0-9]+)?)\s*m?)?\s*$/i
+        m = dms_str.match(regex)
+        raise ArgumentError, "Invalid DMS format" unless m
+
+        lat_deg = m[1].to_i
+        lat_min = m[2].to_i
+        lat_sec = m[3].to_f
+        lat_hemi = m[4].upcase
+
+        lon_deg = m[5].to_i
+        lon_min = m[6].to_i
+        lon_sec = m[7].to_f
+        lon_hemi = m[8].upcase
+
+        alt = m[9] ? m[9].to_f : 0.0
+
+        lat = lat_deg + lat_min / 60.0 + lat_sec / 3600.0
+        lat = -lat if lat_hemi == 'S'
+
+        lng = lon_deg + lon_min / 60.0 + lon_sec / 3600.0
+        lng = -lng if lon_hemi == 'W'
+
+        new(lat: lat, lng: lng, alt: alt)
+      end
+
+      def to_gh36(precision: 10)
+        GH36.new(self, precision: precision)
+      end
+
+      def self.from_gh36(gh36_coord, datum = WGS84)
+        gh36_coord.to_lla(datum)
+      end
+
+      def to_s(precision = 6)
+        precision = precision.to_i
+        if precision == 0
+          "#{@lat.round}, #{@lng.round}, #{@alt.round}"
+        else
+          alt_precision = [precision, 2].min
+          format("%.#{precision}f, %.#{precision}f, %.#{alt_precision}f", @lat, @lng, @alt)
+        end
+      end
+
+      def to_a
+        [@lat, @lng, @alt]
+      end
+
+      def self.from_array(array)
+        new(lat: array[0].to_f, lng: array[1].to_f, alt: array[2].to_f)
+      end
+
+      def self.from_string(string)
+        parts = string.split(',').map(&:strip)
+        new(lat: parts[0].to_f, lng: parts[1].to_f, alt: parts[2].to_f)
+      end
+
+      def ==(other)
+        return false unless other.is_a?(LLA)
+
+        delta_lat = (@lat - other.lat).abs
+        delta_lng = (@lng - other.lng).abs
+        delta_alt = (@alt - other.alt).abs
+
+        delta_lat <= 1e-6 && delta_lng <= 1e-6 && delta_alt <= 1e-6
+      end
+
+      private
+
+      def validate_coordinates!
+        raise ArgumentError, "Latitude must be a finite number" if @lat.nan? || @lat.infinite?
+        raise ArgumentError, "Longitude must be a finite number" if @lng.nan? || @lng.infinite?
+        raise ArgumentError, "Altitude must be a finite number" if @alt.nan? || @alt.infinite?
+        raise ArgumentError, "Latitude must be between -90 and 90 degrees" if @lat < -90 || @lat > 90
+        raise ArgumentError, "Longitude must be between -180 and 180 degrees" if @lng < -180 || @lng > 180
+      end
+    end
+  end
+end

data/lib/geodetic/coordinates/mgrs.rb

@@ -0,0 +1,317 @@
+# frozen_string_literal: true
+
+# Military Grid Reference System (MGRS) Coordinate
+# Converts between MGRS grid references and other coordinate systems
+# MGRS is based on UTM but uses a more compact alphanumeric format
+
+module Geodetic
+  module Coordinates
+    class MGRS
+      require_relative '../datum'
+
+      attr_reader :grid_zone_designator, :square_identifier, :easting, :northing, :precision
+
+      # MGRS 100km square identification letters
+      SET1_E = 'ABCDEFGHJKLMNPQRSTUVWXYZ'  # Columns (exclude I and O)
+      SET2_E = 'ABCDEFGHJKLMNPQRSTUVWXYZ'  # Columns for odd UTM zones
+      SET1_N = 'ABCDEFGHJKLMNPQRSTUV'      # Rows (exclude I and O, stop at V)
+      SET2_N = 'FGHJKLMNPQRSTUVABCDE'      # Rows for even-numbered 100km squares
+
+      def initialize(mgrs_string: nil, grid_zone: nil, square_id: nil, easting: nil, northing: nil, precision: 5)
+        if mgrs_string
+          parse_mgrs_string(mgrs_string)
+        else
+          @grid_zone_designator = grid_zone
+          @square_identifier = square_id
+          @easting = easting.to_f
+          @northing = northing.to_f
+          @precision = precision
+        end
+      end
+
+      def to_s
+        if @precision == 1
+          "#{@grid_zone_designator}#{@square_identifier}"
+        else
+          east_str = ("%0#{@precision}d" % (@easting / (10 ** (5 - @precision)))).to_s
+          north_str = ("%0#{@precision}d" % (@northing / (10 ** (5 - @precision)))).to_s
+          "#{@grid_zone_designator}#{@square_identifier}#{east_str}#{north_str}"
+        end
+      end
+
+      def self.from_string(string)
+        new(mgrs_string: string)
+      end
+
+      def to_utm
+        # Extract zone number and hemisphere from grid zone designator
+        zone_number = @grid_zone_designator[0..-2].to_i
+        zone_letter = @grid_zone_designator[-1]
+        hemisphere = (zone_letter >= 'N') ? 'N' : 'S'
+
+        # Convert 100km square to UTM coordinates
+        utm_easting, utm_northing = square_to_utm(zone_number, @square_identifier, @easting, @northing)
+
+        UTM.new(easting: utm_easting, northing: utm_northing, zone: zone_number, hemisphere: hemisphere)
+      end
+
+      def self.from_utm(utm_coord, precision = 5)
+        # Create instance to access instance methods
+        temp_instance = new()
+
+        # Get 100km square identifier
+        square_id = temp_instance.utm_to_square(utm_coord.zone, utm_coord.easting, utm_coord.northing)
+
+        # Calculate position within the 100km square
+        square_easting = utm_coord.easting % 100000
+        square_northing = utm_coord.northing % 100000
+
+        # Create grid zone designator using hemisphere-aware band letter
+        if utm_coord.hemisphere == 'N'
+          zone_letter = get_zone_letter(utm_coord.northing)
+        else
+          zone_letter = get_zone_letter_south(utm_coord.northing)
+        end
+        grid_zone = "#{utm_coord.zone}#{zone_letter}"
+
+        new(grid_zone: grid_zone, square_id: square_id, easting: square_easting, northing: square_northing, precision: precision)
+      end
+
+      def to_lla(datum = WGS84)
+        utm_coord = to_utm
+        utm_coord.to_lla(datum)
+      end
+
+      def self.from_lla(lla_coord, datum = WGS84, precision = 5)
+        utm_coord = UTM.from_lla(lla_coord, datum)
+        from_utm(utm_coord, precision)
+      end
+
+      def to_ecef(datum = WGS84)
+        to_lla(datum).to_ecef(datum)
+      end
+
+      def self.from_ecef(ecef_coord, datum = WGS84, precision = 5)
+        lla_coord = ecef_coord.to_lla(datum)
+        from_lla(lla_coord, datum, precision)
+      end
+
+      def to_enu(reference_lla, datum = WGS84)
+        to_lla(datum).to_enu(reference_lla)
+      end
+
+      def self.from_enu(enu_coord, reference_lla, datum = WGS84, precision = 5)
+        lla_coord = enu_coord.to_lla(reference_lla)
+        from_lla(lla_coord, datum, precision)
+      end
+
+      def to_ned(reference_lla, datum = WGS84)
+        to_lla(datum).to_ned(reference_lla)
+      end
+
+      def self.from_ned(ned_coord, reference_lla, datum = WGS84, precision = 5)
+        lla_coord = ned_coord.to_lla(reference_lla)
+        from_lla(lla_coord, datum, precision)
+      end
+
+      def to_web_mercator(datum = WGS84)
+        WebMercator.from_lla(to_lla(datum), datum)
+      end
+
+      def self.from_web_mercator(wm_coord, datum = WGS84, precision = 5)
+        from_lla(wm_coord.to_lla(datum), datum, precision)
+      end
+
+      def to_ups(datum = WGS84)
+        UPS.from_lla(to_lla(datum), datum)
+      end
+
+      def self.from_ups(ups_coord, datum = WGS84, precision = 5)
+        from_lla(ups_coord.to_lla(datum), datum, precision)
+      end
+
+      def to_usng
+        USNG.from_mgrs(self)
+      end
+
+      def self.from_usng(usng_coord)
+        usng_coord.to_mgrs
+      end
+
+      def to_state_plane(zone_code, datum = WGS84)
+        StatePlane.from_lla(to_lla(datum), zone_code, datum)
+      end
+
+      def self.from_state_plane(sp_coord, datum = WGS84, precision = 5)
+        from_lla(sp_coord.to_lla(datum), datum, precision)
+      end
+
+      def to_bng(datum = WGS84)
+        BNG.from_lla(to_lla(datum), datum)
+      end
+
+      def self.from_bng(bng_coord, datum = WGS84, precision = 5)
+        from_lla(bng_coord.to_lla(datum), datum, precision)
+      end
+
+      def to_gh36(datum = WGS84, precision: 10)
+        GH36.new(to_lla(datum), precision: precision)
+      end
+
+      def self.from_gh36(gh36_coord, datum = WGS84, precision = 5)
+        from_lla(gh36_coord.to_lla(datum), datum, precision)
+      end
+
+      def ==(other)
+        return false unless other.is_a?(MGRS)
+
+        @grid_zone_designator == other.grid_zone_designator &&
+        @square_identifier == other.square_identifier &&
+        (@easting - other.easting).abs <= 1e-6 &&
+        (@northing - other.northing).abs <= 1e-6 &&
+        @precision == other.precision
+      end
+
+      def to_a
+        [@grid_zone_designator, @square_identifier, @easting, @northing, @precision]
+      end
+
+      def self.from_array(array)
+        new(grid_zone: array[0], square_id: array[1], easting: array[2].to_f, northing: array[3].to_f, precision: (array[4] || 5).to_i)
+      end
+
+      def utm_to_square(zone_number, easting, northing)
+        # Calculate 100km square column
+        col_index = ((easting - 100000) / 100000).floor
+        col_index = (col_index + (zone_number - 1) * 8) % 24
+
+        if zone_number % 2 == 1  # Odd zones
+          col_letter = SET1_E[col_index]
+        else  # Even zones
+          col_letter = SET2_E[col_index]
+        end
+
+        # Calculate 100km square row
+        row_index = (northing / 100000).floor % 20
+        if ((zone_number - 1) / 6).floor % 2 == 1
+          row_letter = SET2_N[row_index]
+        else
+          row_letter = SET1_N[row_index]
+        end
+
+        "#{col_letter}#{row_letter}"
+      end
+
+      private
+
+      def parse_mgrs_string(mgrs_string)
+        mgrs = mgrs_string.upcase.gsub(/\s/, '')
+
+        # Extract grid zone designator (first 2-3 characters: zone number + letter)
+        if mgrs.match(/^(\d{1,2}[A-Z])/)
+          @grid_zone_designator = $1
+          remainder = mgrs[($1.length)..-1]
+        else
+          raise ArgumentError, "Invalid MGRS format: #{mgrs_string}"
+        end
+
+        # Extract 100km square identifier (next 2 characters)
+        if remainder.length >= 2
+          @square_identifier = remainder[0..1]
+          coords = remainder[2..-1]
+        else
+          raise ArgumentError, "Invalid MGRS format: missing square identifier"
+        end
+
+        # Extract coordinates (remaining characters, split evenly)
+        if coords.length == 0
+          @precision = 1  # Grid square only
+          @easting = 0.0
+          @northing = 0.0
+        elsif coords.length % 2 == 0
+          @precision = coords.length / 2
+          coord_multiplier = 10 ** (5 - @precision)
+          @easting = coords[0...@precision].to_i * coord_multiplier
+          @northing = coords[@precision..-1].to_i * coord_multiplier
+        else
+          raise ArgumentError, "Invalid MGRS format: uneven coordinate length"
+        end
+      end
+
+      def square_to_utm(zone_number, square_id, easting, northing)
+        col_letter = square_id[0]
+        row_letter = square_id[1]
+
+        # Calculate easting from column letter
+        # For odd zones, columns start at A=1 (100km), for even zones offset by 8
+        set = (zone_number % 2 == 1) ? SET1_E : SET2_E
+        col_index = set.index(col_letter) || 0
+
+        # Column letters cycle with zone: each zone spans 8 columns (A-H for zone 1, J-R for zone 2, etc.)
+        # The easting within the zone is: (col_index - zone_offset) * 100000 + 100000
+        zone_set = (zone_number - 1) % 3  # 0, 1, or 2
+        col_in_zone = col_index - (zone_set * 8)
+        col_in_zone += 24 if col_in_zone < 0
+        utm_easting = (col_in_zone + 1) * 100000 + easting
+
+        # Calculate northing from row letter
+        # Row letters cycle every 2,000,000m (20 letters × 100km)
+        if ((zone_number - 1) / 6).floor % 2 == 1
+          row_index = SET2_N.index(row_letter) || 0
+        else
+          row_index = SET1_N.index(row_letter) || 0
+        end
+        base_northing = row_index * 100000 + northing
+
+        # Use the grid zone letter (latitude band) to find the correct 2,000,000m cycle
+        zone_letter = @grid_zone_designator[-1]
+        min_northing = min_northing_for_band(zone_letter)
+
+        # Find the cycle that puts northing closest to the band's expected range
+        utm_northing = base_northing
+        while utm_northing < min_northing
+          utm_northing += 2000000
+        end
+
+        [utm_easting, utm_northing]
+      end
+
+      # Approximate minimum northing (in meters) for each UTM latitude band letter
+      def min_northing_for_band(letter)
+        band_min = {
+          'C' => 1100000, 'D' => 2000000, 'E' => 2800000, 'F' => 3700000,
+          'G' => 4600000, 'H' => 5500000, 'J' => 6400000, 'K' => 7300000,
+          'L' => 8200000, 'M' => 9100000, 'N' => 0, 'P' => 800000,
+          'Q' => 1700000, 'R' => 2600000, 'S' => 3500000, 'T' => 4400000,
+          'U' => 5300000, 'V' => 6200000, 'W' => 7000000, 'X' => 7900000
+        }
+        band_min[letter.upcase] || 0
+      end
+
+      def self.get_zone_letter(northing)
+        # For northern hemisphere, estimate latitude from northing
+        # then map to the correct band letter
+        # Approximate: latitude ≈ northing / 111320 (meters per degree)
+        approx_lat = northing / 111320.0
+        latitude_to_band_letter(approx_lat)
+      end
+
+      def self.get_zone_letter_south(northing)
+        # For southern hemisphere, northing uses false northing of 10,000,000
+        approx_lat = (northing - 10000000.0) / 111320.0
+        latitude_to_band_letter(approx_lat)
+      end
+
+      def self.latitude_to_band_letter(lat)
+        # MGRS latitude band letters: C through X (excluding I and O)
+        # Each band covers 8° except X which covers 12° (72-84°N)
+        bands = 'CDEFGHJKLMNPQRSTUVWX'
+        return 'C' if lat < -80
+        return 'X' if lat >= 72
+        index = ((lat + 80) / 8).floor
+        index = [0, [index, bands.length - 1].min].max
+        bands[index]
+      end
+    end
+  end
+end