geodetic 0.0.1

data/lib/geodetic/coordinates/ups.rb

@@ -0,0 +1,325 @@
+# frozen_string_literal: true
+
+# Universal Polar Stereographic (UPS) Coordinate System
+# Used for polar regions not covered by UTM (north of 84°N and south of 80°S)
+
+module Geodetic
+  module Coordinates
+    class UPS
+      require_relative '../datum'
+
+      attr_reader :easting, :northing, :hemisphere, :zone
+
+      # UPS Constants
+      FALSE_EASTING = 2000000.0   # meters
+      FALSE_NORTHING = 2000000.0  # meters
+      SCALE_FACTOR = 0.994        # Central scale factor
+
+      # UPS covers two zones: North (Y,Z) and South (A,B)
+      NORTH_ZONES = ['Y', 'Z']
+      SOUTH_ZONES = ['A', 'B']
+
+      def initialize(easting: 0.0, northing: 0.0, hemisphere: 'N', zone: 'Y')
+        @easting = easting.to_f
+        @northing = northing.to_f
+        @hemisphere = hemisphere.upcase
+        @zone = zone.upcase
+
+        validate_zone
+      end
+
+      def easting=(value)
+        @easting = value.to_f
+      end
+
+      def northing=(value)
+        @northing = value.to_f
+      end
+
+      def hemisphere=(value)
+        value = value.to_s.upcase
+        old_hemisphere = @hemisphere
+        @hemisphere = value
+        unless valid?
+          @hemisphere = old_hemisphere
+          raise ArgumentError, "Invalid UPS hemisphere '#{value}' for zone '#{@zone}'"
+        end
+      end
+
+      def zone=(value)
+        value = value.to_s.upcase
+        old_zone = @zone
+        @zone = value
+        unless valid?
+          @zone = old_zone
+          raise ArgumentError, "Invalid UPS zone '#{value}' for hemisphere '#{@hemisphere}'"
+        end
+      end
+
+      def to_s(precision = 2)
+        precision = precision.to_i
+        if precision == 0
+          "#{@easting.round}, #{@northing.round}, #{@hemisphere}, #{@zone}"
+        else
+          format("%.#{precision}f, %.#{precision}f, %s, %s", @easting, @northing, @hemisphere, @zone)
+        end
+      end
+
+      def to_a
+        [@easting, @northing, @hemisphere, @zone]
+      end
+
+      def self.from_array(array)
+        new(easting: array[0].to_f, northing: array[1].to_f, hemisphere: array[2].to_s, zone: array[3].to_s)
+      end
+
+      def self.from_string(string)
+        parts = string.split(',').map(&:strip)
+        new(easting: parts[0].to_f, northing: parts[1].to_f, hemisphere: parts[2].to_s, zone: parts[3].to_s)
+      end
+
+      def to_lla(datum = WGS84)
+        a = datum.a
+        e = datum.e
+        e2 = datum.e2
+
+        # Adjust for false origin
+        x = @easting - FALSE_EASTING
+        y = @northing - FALSE_NORTHING
+
+        # Calculate polar stereographic parameters
+        rho = Math.sqrt(x * x + y * y)
+
+        if rho < 1e-10  # At pole
+          lat = @hemisphere == 'N' ? 90.0 : -90.0
+          lng = 0.0
+        else
+          # Iterative calculation for latitude
+          if @hemisphere == 'N'
+            c = 2.0 * Math.atan(rho / (2.0 * a * SCALE_FACTOR * ((1.0 - e) / (1.0 + e)) ** (e / 2.0)))
+            lat = (Math::PI / 2.0) - c
+          else
+            c = 2.0 * Math.atan(rho / (2.0 * a * SCALE_FACTOR * ((1.0 + e) / (1.0 - e)) ** (e / 2.0)))
+            lat = c - (Math::PI / 2.0)
+          end
+
+          # Iterative refinement for latitude
+          5.times do
+            sin_lat = Math.sin(lat)
+            if @hemisphere == 'N'
+              t = Math.tan((Math::PI / 4.0) - (lat / 2.0)) / ((1.0 - e * sin_lat) / (1.0 + e * sin_lat)) ** (e / 2.0)
+              lat = (Math::PI / 2.0) - 2.0 * Math.atan(t * rho / (2.0 * a * SCALE_FACTOR))
+            else
+              t = Math.tan((Math::PI / 4.0) + (lat / 2.0)) / ((1.0 + e * sin_lat) / (1.0 - e * sin_lat)) ** (e / 2.0)
+              lat = 2.0 * Math.atan(t * rho / (2.0 * a * SCALE_FACTOR)) - (Math::PI / 2.0)
+            end
+          end
+
+          lat *= DEG_PER_RAD
+
+          # Calculate longitude
+          if @hemisphere == 'N'
+            lng = Math.atan2(x, -y) * DEG_PER_RAD
+          else
+            lng = Math.atan2(x, y) * DEG_PER_RAD
+          end
+
+          # Normalize longitude
+          lng = lng - 360.0 while lng > 180.0
+          lng = lng + 360.0 while lng < -180.0
+        end
+
+        LLA.new(lat: lat, lng: lng, alt: 0.0)
+      end
+
+      def self.from_lla(lla_coord, datum = WGS84)
+        lat = lla_coord.lat
+        lng = lla_coord.lng
+
+        # Determine hemisphere and zone
+        hemisphere = lat >= 0 ? 'N' : 'S'
+
+        # Determine zone based on longitude
+        if hemisphere == 'N'
+          zone = (lng >= 0) ? 'Z' : 'Y'
+        else
+          zone = (lng >= 0) ? 'B' : 'A'
+        end
+
+        a = datum.a
+        e = datum.e
+
+        lat_rad = lat * RAD_PER_DEG
+        lng_rad = lng * RAD_PER_DEG
+
+        sin_lat = Math.sin(lat_rad)
+
+        # Calculate polar stereographic projection
+        if lat.abs == 90.0  # At pole
+          x = 0.0
+          y = 0.0
+        else
+          if hemisphere == 'N'
+            t = Math.tan((Math::PI / 4.0) - (lat_rad / 2.0)) * ((1.0 + e * sin_lat) / (1.0 - e * sin_lat)) ** (e / 2.0)
+            rho = 2.0 * a * SCALE_FACTOR * t
+            x = rho * Math.sin(lng_rad)
+            y = -rho * Math.cos(lng_rad)
+          else
+            t = Math.tan((Math::PI / 4.0) + (lat_rad / 2.0)) * ((1.0 - e * sin_lat) / (1.0 + e * sin_lat)) ** (e / 2.0)
+            rho = 2.0 * a * SCALE_FACTOR * t
+            x = rho * Math.sin(lng_rad)
+            y = rho * Math.cos(lng_rad)
+          end
+        end
+
+        # Apply false origin
+        easting = x + FALSE_EASTING
+        northing = y + FALSE_NORTHING
+
+        new(easting: easting, northing: northing, hemisphere: hemisphere, zone: zone)
+      end
+
+      def to_ecef(datum = WGS84)
+        to_lla(datum).to_ecef(datum)
+      end
+
+      def self.from_ecef(ecef_coord, datum = WGS84)
+        lla_coord = ecef_coord.to_lla(datum)
+        from_lla(lla_coord, datum)
+      end
+
+      def to_utm(datum = WGS84)
+        to_lla(datum).to_utm(datum)
+      end
+
+      def self.from_utm(utm_coord, datum = WGS84)
+        lla_coord = utm_coord.to_lla(datum)
+        from_lla(lla_coord, datum)
+      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)
+        lla_coord = enu_coord.to_lla(reference_lla)
+        from_lla(lla_coord, datum)
+      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)
+        lla_coord = ned_coord.to_lla(reference_lla)
+        from_lla(lla_coord, datum)
+      end
+
+      def to_mgrs(datum = WGS84, precision = 5)
+        MGRS.from_lla(to_lla(datum), datum, precision)
+      end
+
+      def self.from_mgrs(mgrs_coord, datum = WGS84)
+        lla_coord = mgrs_coord.to_lla(datum)
+        from_lla(lla_coord, datum)
+      end
+
+      def to_web_mercator(datum = WGS84)
+        WebMercator.from_lla(to_lla(datum), datum)
+      end
+
+      def self.from_web_mercator(web_mercator_coord, datum = WGS84)
+        lla_coord = web_mercator_coord.to_lla(datum)
+        from_lla(lla_coord, datum)
+      end
+
+      def to_usng(datum = WGS84, precision = 5)
+        USNG.from_lla(to_lla(datum), datum, precision)
+      end
+
+      def self.from_usng(usng_coord, datum = WGS84)
+        lla_coord = usng_coord.to_lla(datum)
+        from_lla(lla_coord, datum)
+      end
+
+      def to_bng(datum = WGS84)
+        BNG.from_lla(to_lla(datum), datum)
+      end
+
+      def self.from_bng(bng_coord, datum = WGS84)
+        lla_coord = bng_coord.to_lla(datum)
+        from_lla(lla_coord, datum)
+      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)
+        lla_coord = sp_coord.to_lla(datum)
+        from_lla(lla_coord, datum)
+      end
+
+      def to_gh36(datum = WGS84, precision: 10)
+        GH36.new(to_lla(datum), precision: precision)
+      end
+
+      def self.from_gh36(gh36_coord, datum = WGS84)
+        lla_coord = gh36_coord.to_lla(datum)
+        from_lla(lla_coord, datum)
+      end
+
+      def ==(other)
+        return false unless other.is_a?(UPS)
+
+        (@easting - other.easting).abs <= 1e-6 &&
+        (@northing - other.northing).abs <= 1e-6 &&
+        @hemisphere == other.hemisphere && @zone == other.zone
+      end
+
+
+      # Grid convergence calculation
+      def grid_convergence(datum = WGS84)
+        lla = to_lla(datum)
+        lng_rad = lla.lng * RAD_PER_DEG
+
+        if @hemisphere == 'N'
+          convergence = lng_rad * DEG_PER_RAD
+        else
+          convergence = -lng_rad * DEG_PER_RAD
+        end
+
+        convergence
+      end
+
+      # Scale factor at point
+      def point_scale_factor(datum = WGS84)
+        lla = to_lla(datum)
+        lat_rad = lla.lat.abs * RAD_PER_DEG
+
+        e = datum.e
+        sin_lat = Math.sin(lat_rad)
+
+        # Simplified scale factor calculation
+        m = Math.cos(lat_rad) / Math.sqrt(1.0 - e * e * sin_lat * sin_lat)
+        t = Math.tan((Math::PI / 4.0) - (lat_rad / 2.0)) * ((1.0 + e * sin_lat) / (1.0 - e * sin_lat)) ** (e / 2.0)
+
+        scale = SCALE_FACTOR * (1.0 + t * t) / (2.0 * m)
+        scale
+      end
+
+      def valid?
+        (@hemisphere == 'N' && NORTH_ZONES.include?(@zone)) ||
+        (@hemisphere == 'S' && SOUTH_ZONES.include?(@zone))
+      end
+
+      private
+
+      def validate_zone
+        unless valid?
+          raise ArgumentError, "Invalid UPS zone '#{@zone}' for hemisphere '#{@hemisphere}'"
+        end
+      end
+    end
+  end
+end

data/lib/geodetic/coordinates/usng.rb

@@ -0,0 +1,274 @@
+# frozen_string_literal: true
+
+# US National Grid (USNG) Coordinate System
+# Based on MGRS but uses a slightly different format and always uses meter precision
+# Used primarily within the United States for emergency services and land management
+
+module Geodetic
+  module Coordinates
+    class USNG
+      require_relative '../datum'
+      require_relative 'mgrs'
+
+      attr_reader :grid_zone_designator, :square_identifier, :easting, :northing, :precision
+
+      def initialize(usng_string: nil, grid_zone: nil, square_id: nil, easting: nil, northing: nil, precision: 5)
+        if usng_string
+          parse_usng_string(usng_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(usng_string: string)
+      end
+
+      # Convert to MGRS (the underlying format)
+      def to_mgrs
+        mgrs_string = "#{@grid_zone_designator}#{@square_identifier}"
+        if @precision > 1
+          east_str = ("%0#{@precision}d" % (@easting / (10 ** (5 - @precision)))).to_s
+          north_str = ("%0#{@precision}d" % (@northing / (10 ** (5 - @precision)))).to_s
+          mgrs_string += "#{east_str}#{north_str}"
+        end
+        MGRS.new(mgrs_string: mgrs_string)
+      end
+
+      def self.from_mgrs(mgrs_coord)
+        # Extract components from MGRS
+        grid_zone = mgrs_coord.grid_zone_designator
+        square_id = mgrs_coord.square_identifier
+        easting = mgrs_coord.easting
+        northing = mgrs_coord.northing
+        precision = mgrs_coord.precision
+
+        new(grid_zone: grid_zone, square_id: square_id, easting: easting, northing: northing, precision: precision)
+      end
+
+      def to_utm
+        to_mgrs.to_utm
+      end
+
+      def self.from_utm(utm_coord, precision = 5)
+        mgrs_coord = MGRS.from_utm(utm_coord, precision)
+        from_mgrs(mgrs_coord)
+      end
+
+      def to_lla(datum = WGS84)
+        to_mgrs.to_lla(datum)
+      end
+
+      def self.from_lla(lla_coord, datum = WGS84, precision = 5)
+        mgrs_coord = MGRS.from_lla(lla_coord, datum, precision)
+        from_mgrs(mgrs_coord)
+      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_ups(datum = WGS84)
+        UPS.from_lla(to_lla(datum), datum)
+      end
+
+      def self.from_ups(ups_coord, datum = WGS84, precision = 5)
+        lla_coord = ups_coord.to_lla(datum)
+        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(web_mercator_coord, datum = WGS84, precision = 5)
+        lla_coord = web_mercator_coord.to_lla(datum)
+        from_lla(lla_coord, 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_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_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?(USNG)
+
+        @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
+
+      # USNG-specific formatting methods
+      def to_full_format
+        "#{@grid_zone_designator} #{@square_identifier} #{@easting.round.to_s.rjust(5, '0')} #{@northing.round.to_s.rjust(5, '0')}"
+      end
+
+      def to_abbreviated_format
+        # Common abbreviation drops leading zeros and trailing precision
+        east_str = @easting.round.to_s.gsub(/^0+/, '')
+        north_str = @northing.round.to_s.gsub(/^0+/, '')
+        east_str = '0' if east_str.empty?
+        north_str = '0' if north_str.empty?
+        "#{@grid_zone_designator} #{@square_identifier} #{east_str} #{north_str}"
+      end
+
+
+      # Get adjacent grid squares
+      def adjacent_squares
+        squares = {}
+
+        # This is a simplified version - real implementation would need
+        # to handle zone boundaries and square identifier cycling
+        offsets = {
+          north: [0, 100000],
+          northeast: [100000, 100000],
+          east: [100000, 0],
+          southeast: [100000, -100000],
+          south: [0, -100000],
+          southwest: [-100000, -100000],
+          west: [-100000, 0],
+          northwest: [-100000, 100000]
+        }
+
+        offsets.each do |direction, (de, dn)|
+          begin
+            new_east = @easting + de
+            new_north = @northing + dn
+            adjacent_usng = USNG.new(grid_zone: @grid_zone_designator, square_id: @square_identifier,
+                                     easting: new_east, northing: new_north, precision: @precision)
+            squares[direction] = adjacent_usng
+          rescue => e
+            # Skip invalid adjacent squares (e.g., crossing zone boundaries)
+            squares[direction] = nil
+          end
+        end
+
+        squares
+      end
+
+      # Validate USNG coordinate
+      def valid?
+        # Check if this falls within CONUS/Alaska/Hawaii UTM zones
+        valid_zones = %w[10S 10T 10U 11S 11T 11U 12S 12T 12U 13S 13T 13U 14S 14T 14U 15S 15T 15U 16S 16T 16U 17S 17T 17U 18S 18T 18U 19S 19T 19U]
+
+        return false unless valid_zones.include?(@grid_zone_designator)
+        return false unless @square_identifier.length == 2
+        return false unless @easting >= 0 && @easting < 100000
+        return false unless @northing >= 0 && @northing < 100000
+
+        true
+      end
+
+      private
+
+      def parse_usng_string(usng_string)
+        usng = usng_string.upcase.strip
+
+        # USNG format: "18T WL 12345 67890" or "18TWL1234567890"
+        # Handle both spaced and non-spaced formats
+
+        if usng.include?(' ')
+          parts = usng.split(/\s+/)
+
+          if parts.length < 2
+            raise ArgumentError, "Invalid USNG format: #{usng_string}"
+          end
+
+          @grid_zone_designator = parts[0]
+          @square_identifier = parts[1]
+
+          if parts.length >= 4
+            # Full coordinate format
+            east_str = parts[2]
+            north_str = parts[3]
+            @precision = east_str.length
+
+            coord_multiplier = 10 ** (5 - @precision)
+            @easting = east_str.to_i * coord_multiplier
+            @northing = north_str.to_i * coord_multiplier
+          else
+            # Grid square only
+            @precision = 1
+            @easting = 0.0
+            @northing = 0.0
+          end
+        else
+          # Non-spaced format - delegate to MGRS parser
+          mgrs_coord = MGRS.new(mgrs_string: usng_string)
+          @grid_zone_designator = mgrs_coord.grid_zone_designator
+          @square_identifier = mgrs_coord.square_identifier
+          @easting = mgrs_coord.easting
+          @northing = mgrs_coord.northing
+          @precision = mgrs_coord.precision
+        end
+      end
+    end
+  end
+end