geodetic 0.1.0 → 0.3.0

data/lib/geodetic/coordinate/spatial_hash.rb

@@ -0,0 +1,342 @@
+# frozen_string_literal: true
+
+# Base class for spatial hash coordinate systems (GH, GH36, HAM, OLC, etc.)
+#
+# Spatial hash systems encode latitude/longitude into a string code that
+# represents a rectangular cell on the globe. They are immutable, 2D (no altitude),
+# and convert to/from other coordinate systems through LLA as intermediary.
+#
+# Subclass contract — MUST implement:
+#   encode(lat, lng, precision)   → String
+#   decode(code_string)           → { lat:, lng: }
+#   decode_bounds(code_string)    → { min_lat:, max_lat:, min_lng:, max_lng: }
+#   validate_code!(string)        → raises ArgumentError or nil
+#   set_code(normalized_string)   → sets the internal ivar (@geohash, @code, etc.)
+#   code_value                    → returns the internal ivar
+#   self.default_precision        → Integer
+#   self.hash_system_name         → Symbol (:gh, :gh36, :ham, :olc)
+#
+# MAY override:
+#   normalize(string)             → String (default: identity)
+#   to_s(truncate_to)
+#   valid?
+#   precision
+#   neighbors
+#   precision_in_meters
+
+module Geodetic
+  module Coordinate
+    class SpatialHash
+      require_relative '../datum'
+
+      # Direction offsets for neighbors: [lat_direction, lng_direction]
+      DIRECTIONS = {
+        N:  [ 1,  0],
+        S:  [-1,  0],
+        E:  [ 0,  1],
+        W:  [ 0, -1],
+        NE: [ 1,  1],
+        NW: [ 1, -1],
+        SE: [-1,  1],
+        SW: [-1, -1]
+      }.freeze
+
+      # Registry of spatial hash subclasses for cross-hash conversion generation
+      @hash_registry = {}
+
+      class << self
+        attr_reader :hash_registry
+
+        def register_hash_system(name, klass, default_precision:)
+          SpatialHash.hash_registry[name] = {
+            class_name: klass.name.split('::').last,
+            default_precision: default_precision
+          }
+        end
+
+        # Called once after all spatial hash subclasses are loaded.
+        # Generates cross-hash to_*/from_* methods with correct keyword names.
+        def finalize_cross_hash_conversions!
+          SpatialHash.hash_registry.each do |source_name, _source_config|
+            source_klass = Geodetic::Coordinate.const_get(SpatialHash.hash_registry[source_name][:class_name])
+
+            SpatialHash.hash_registry.each do |target_name, target_config|
+              next if source_name == target_name
+
+              target_class_name = target_config[:class_name]
+              precision_kwarg = "#{target_name}_precision"
+              default_prec = target_config[:default_precision]
+
+              # Instance method: to_<target>(datum = WGS84, <target>_precision: <default>)
+              unless source_klass.method_defined?(:"to_#{target_name}")
+                source_klass.class_eval <<~RUBY, __FILE__, __LINE__ + 1
+                  def to_#{target_name}(datum = WGS84, #{precision_kwarg}: #{default_prec})
+                    #{target_class_name}.new(to_lla(datum), precision: #{precision_kwarg})
+                  end
+                RUBY
+              end
+
+              # Class method: from_<target>(coord, datum = WGS84, precision = default_precision)
+              unless source_klass.respond_to?(:"from_#{target_name}")
+                source_klass.class_eval <<~RUBY, __FILE__, __LINE__ + 1
+                  def self.from_#{target_name}(coord, datum = WGS84, precision = default_precision)
+                    new(coord, precision: precision)
+                  end
+                RUBY
+              end
+            end
+          end
+        end
+
+        # Generate hash conversion methods (to_gh, from_gh, etc.) on non-hash coordinate classes.
+        # Styles:
+        #   :no_datum      — to_gh(precision: N), from_gh(coord, datum = WGS84)
+        #   :with_datum    — to_gh(datum = WGS84, precision: N), from_gh(coord, datum = WGS84)
+        #   :with_datum_and_precision — same to_* as :with_datum,
+        #                               from_gh(coord, datum = WGS84, precision = 5)
+        def generate_hash_conversions_for(target_klass, style: :no_datum)
+          SpatialHash.hash_registry.each do |hash_name, config|
+            hash_class_name = config[:class_name]
+            default_prec = config[:default_precision]
+
+            # Instance method: to_<hash>
+            unless target_klass.method_defined?(:"to_#{hash_name}")
+              case style
+              when :no_datum
+                target_klass.class_eval <<~RUBY, __FILE__, __LINE__ + 1
+                  def to_#{hash_name}(precision: #{default_prec})
+                    #{hash_class_name}.new(to_lla, precision: precision)
+                  end
+                RUBY
+              when :with_datum, :with_datum_and_precision
+                target_klass.class_eval <<~RUBY, __FILE__, __LINE__ + 1
+                  def to_#{hash_name}(datum = WGS84, precision: #{default_prec})
+                    #{hash_class_name}.new(to_lla(datum), precision: precision)
+                  end
+                RUBY
+              end
+            end
+
+            # Class method: from_<hash>
+            unless target_klass.respond_to?(:"from_#{hash_name}")
+              case style
+              when :no_datum, :with_datum
+                target_klass.class_eval <<~RUBY, __FILE__, __LINE__ + 1
+                  def self.from_#{hash_name}(coord, datum = WGS84)
+                    from_lla(coord.to_lla(datum), datum)
+                  end
+                RUBY
+              when :with_datum_and_precision
+                target_klass.class_eval <<~RUBY, __FILE__, __LINE__ + 1
+                  def self.from_#{hash_name}(coord, datum = WGS84, precision = 5)
+                    from_lla(coord.to_lla(datum), datum, precision)
+                  end
+                RUBY
+              end
+            end
+          end
+        end
+      end
+
+      def initialize(source, precision: self.class.default_precision)
+        case source
+        when String
+          normalized = normalize(source.strip)
+          validate_code!(normalized)
+          set_code(normalized)
+        when LLA
+          set_code(encode(source.lat, source.lng, precision))
+        else
+          if source.respond_to?(:to_lla)
+            lla = source.to_lla
+            set_code(encode(lla.lat, lla.lng, precision))
+          else
+            raise ArgumentError,
+              "Expected a code String or a coordinate object, got #{source.class}"
+          end
+        end
+      end
+
+      def precision
+        code_value.length
+      end
+
+      def to_s(truncate_to = nil)
+        if truncate_to
+          code_value[0, truncate_to.to_i]
+        else
+          code_value
+        end
+      end
+
+      def to_a
+        coords = decode(code_value)
+        [coords[:lat], coords[:lng]]
+      end
+
+      def self.from_array(array)
+        new(LLA.new(lat: array[0].to_f, lng: array[1].to_f))
+      end
+
+      def self.from_string(string)
+        new(string.strip)
+      end
+
+      # Decode to LLA (altitude is always 0.0 since spatial hashes are 2D)
+      def to_lla(datum = WGS84)
+        coords = decode(code_value)
+        lat = coords[:lat].clamp(-90.0, 90.0)
+        lng = coords[:lng].clamp(-180.0, 180.0)
+        LLA.new(lat: lat, lng: lng, alt: 0.0)
+      end
+
+      def self.from_lla(lla_coord, datum = WGS84, precision = default_precision)
+        new(lla_coord, precision: precision)
+      end
+
+      # --- Standard conversions (all chain through LLA) ---
+
+      def to_ecef(datum = WGS84)
+        to_lla(datum).to_ecef(datum)
+      end
+
+      def self.from_ecef(ecef_coord, datum = WGS84, precision = default_precision)
+        new(ecef_coord, precision: precision)
+      end
+
+      def to_utm(datum = WGS84)
+        to_lla(datum).to_utm(datum)
+      end
+
+      def self.from_utm(utm_coord, datum = WGS84, precision = default_precision)
+        new(utm_coord, precision: 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 = default_precision)
+        lla_coord = enu_coord.to_lla(reference_lla)
+        new(lla_coord, precision: 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 = default_precision)
+        lla_coord = ned_coord.to_lla(reference_lla)
+        new(lla_coord, precision: precision)
+      end
+
+      def to_mgrs(datum = WGS84, mgrs_precision = 5)
+        MGRS.from_lla(to_lla(datum), datum, mgrs_precision)
+      end
+
+      def self.from_mgrs(mgrs_coord, datum = WGS84, precision = default_precision)
+        new(mgrs_coord, precision: precision)
+      end
+
+      def to_usng(datum = WGS84, usng_precision = 5)
+        USNG.from_lla(to_lla(datum), datum, usng_precision)
+      end
+
+      def self.from_usng(usng_coord, datum = WGS84, precision = default_precision)
+        new(usng_coord, precision: 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 = default_precision)
+        new(wm_coord, precision: precision)
+      end
+
+      def to_ups(datum = WGS84)
+        UPS.from_lla(to_lla(datum), datum)
+      end
+
+      def self.from_ups(ups_coord, datum = WGS84, precision = default_precision)
+        new(ups_coord, precision: 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 = default_precision)
+        new(sp_coord, precision: precision)
+      end
+
+      def to_bng(datum = WGS84)
+        BNG.from_lla(to_lla(datum), datum)
+      end
+
+      def self.from_bng(bng_coord, datum = WGS84, precision = default_precision)
+        new(bng_coord, precision: precision)
+      end
+
+      # --- Equality and utility ---
+
+      def ==(other)
+        return false unless other.is_a?(self.class)
+        code_value == other.code_value
+      end
+
+      alias_method :to_slug, :to_s
+
+      # Returns all 8 neighboring cells
+      # Keys: :N, :S, :E, :W, :NE, :NW, :SE, :SW
+      def neighbors
+        bb = decode_bounds(code_value)
+        lat_step = bb[:max_lat] - bb[:min_lat]
+        lng_step = bb[:max_lng] - bb[:min_lng]
+        center_lat = (bb[:min_lat] + bb[:max_lat]) / 2.0
+        center_lng = (bb[:min_lng] + bb[:max_lng]) / 2.0
+        len = precision
+
+        DIRECTIONS.each_with_object({}) do |(dir, delta), result|
+          nlat = center_lat + delta[0] * lat_step
+          nlng = center_lng + delta[1] * lng_step
+
+          nlat = nlat.clamp(-89.99999999, 89.99999999)
+          nlng += 360.0 if nlng < -180.0
+          nlng -= 360.0 if nlng > 180.0
+
+          result[dir] = self.class.new(LLA.new(lat: nlat, lng: nlng), precision: len)
+        end
+      end
+
+      # Returns the cell as an Areas::Rectangle
+      def to_area
+        bb = decode_bounds(code_value)
+        nw = LLA.new(lat: bb[:max_lat], lng: bb[:min_lng], alt: 0.0)
+        se = LLA.new(lat: bb[:min_lat], lng: bb[:max_lng], alt: 0.0)
+        Areas::Rectangle.new(nw: nw, se: se)
+      end
+
+      # Returns precision in meters as {lat:, lng:}
+      def precision_in_meters
+        bb = decode_bounds(code_value)
+        lat_center = (bb[:min_lat] + bb[:max_lat]) / 2.0
+
+        lat_meters_per_deg = 111_320.0
+        lng_meters_per_deg = 111_320.0 * Math.cos(lat_center * Math::PI / 180.0)
+
+        lat_range = bb[:max_lat] - bb[:min_lat]
+        lng_range = bb[:max_lng] - bb[:min_lng]
+
+        { lat: lat_range * lat_meters_per_deg, lng: lng_range * lng_meters_per_deg }
+      end
+
+      protected
+
+      # Default normalize is identity — subclasses override (e.g., downcase, upcase)
+      def normalize(string)
+        string
+      end
+    end
+  end
+end

data/lib/geodetic/{coordinates → coordinate}/state_plane.rb

@@ -5,7 +5,7 @@
 # Each state has one or more zones with specific parameters
 
 module Geodetic
-  module Coordinates
+  module Coordinate
     class StatePlane
       require_relative '../datum'
 
@@ -287,6 +287,33 @@ module Geodetic
         from_lla(lla_coord, zone_code, datum)
       end
 
+      def to_georef(datum = nil, precision: 8)
+        GEOREF.new(to_lla(datum), precision: precision)
+      end
+
+      def self.from_georef(georef_coord, zone_code, datum = WGS84)
+        lla_coord = georef_coord.to_lla(datum)
+        from_lla(lla_coord, zone_code, datum)
+      end
+
+      def to_gars(datum = nil, precision: 7)
+        GARS.new(to_lla(datum), precision: precision)
+      end
+
+      def self.from_gars(gars_coord, zone_code, datum = WGS84)
+        lla_coord = gars_coord.to_lla(datum)
+        from_lla(lla_coord, zone_code, datum)
+      end
+
+      def to_h3(datum = nil, precision: 7)
+        H3.new(to_lla(datum), precision: precision)
+      end
+
+      def self.from_h3(h3_coord, zone_code, datum = WGS84)
+        lla_coord = h3_coord.to_lla(datum)
+        from_lla(lla_coord, zone_code, datum)
+      end
+
       # Unit conversion methods
       def to_meters
         zone_info = ZONES[@zone_code]
@@ -473,6 +500,8 @@ module Geodetic
 
         new(easting: x, northing: y, zone_code: zone_code, datum: datum)
       end
+
+      Coordinate.register_class(self)
     end
   end
 end

data/lib/geodetic/{coordinates → coordinate}/ups.rb

@@ -4,7 +4,7 @@
 # Used for polar regions not covered by UTM (north of 84°N and south of 80°S)
 
 module Geodetic
-  module Coordinates
+  module Coordinate
     class UPS
       require_relative '../datum'
 
@@ -260,42 +260,6 @@ module Geodetic
         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 to_gh(datum = WGS84, precision: 12)
-        GH.new(to_lla(datum), precision: precision)
-      end
-
-      def self.from_gh(gh_coord, datum = WGS84)
-        lla_coord = gh_coord.to_lla(datum)
-        from_lla(lla_coord, datum)
-      end
-
-      def to_ham(datum = WGS84, precision: 6)
-        HAM.new(to_lla(datum), precision: precision)
-      end
-
-      def self.from_ham(ham_coord, datum = WGS84)
-        lla_coord = ham_coord.to_lla(datum)
-        from_lla(lla_coord, datum)
-      end
-
-      def to_olc(datum = WGS84, precision: 10)
-        OLC.new(to_lla(datum), precision: precision)
-      end
-
-      def self.from_olc(olc_coord, datum = WGS84)
-        lla_coord = olc_coord.to_lla(datum)
-        from_lla(lla_coord, datum)
-      end
-
       def ==(other)
         return false unless other.is_a?(UPS)
 
@@ -347,6 +311,8 @@ module Geodetic
           raise ArgumentError, "Invalid UPS zone '#{@zone}' for hemisphere '#{@hemisphere}'"
         end
       end
+
+      Coordinate.register_class(self)
     end
   end
 end

data/lib/geodetic/{coordinates → coordinate}/usng.rb

@@ -5,7 +5,7 @@
 # Used primarily within the United States for emergency services and land management
 
 module Geodetic
-  module Coordinates
+  module Coordinate
     class USNG
       require_relative '../datum'
       require_relative 'mgrs'
@@ -139,38 +139,6 @@ module Geodetic
         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 to_gh(datum = WGS84, precision: 12)
-        GH.new(to_lla(datum), precision: precision)
-      end
-
-      def self.from_gh(gh_coord, datum = WGS84, precision = 5)
-        from_lla(gh_coord.to_lla(datum), datum, precision)
-      end
-
-      def to_ham(datum = WGS84, precision: 6)
-        HAM.new(to_lla(datum), precision: precision)
-      end
-
-      def self.from_ham(ham_coord, datum = WGS84, precision = 5)
-        from_lla(ham_coord.to_lla(datum), datum, precision)
-      end
-
-      def to_olc(datum = WGS84, precision: 10)
-        OLC.new(to_lla(datum), precision: precision)
-      end
-
-      def self.from_olc(olc_coord, datum = WGS84, precision = 5)
-        from_lla(olc_coord.to_lla(datum), datum, precision)
-      end
-
       def ==(other)
         return false unless other.is_a?(USNG)
 
@@ -293,6 +261,8 @@ module Geodetic
           @precision = mgrs_coord.precision
         end
       end
+
+      Coordinate.register_class(self)
     end
   end
 end

data/lib/geodetic/{coordinates → coordinate}/utm.rb

@@ -3,7 +3,7 @@
 require_relative '../datum'
 
 module Geodetic
-  module Coordinates
+  module Coordinate
     class UTM
       attr_reader :easting, :northing, :altitude, :zone, :hemisphere
       alias_method :x, :easting
@@ -196,38 +196,6 @@ module Geodetic
         from_lla(bng_coord.to_lla, datum)
       end
 
-      def to_gh36(precision: 10)
-        GH36.new(to_lla, precision: precision)
-      end
-
-      def self.from_gh36(gh36_coord, datum = WGS84)
-        from_lla(gh36_coord.to_lla, datum)
-      end
-
-      def to_gh(precision: 12)
-        GH.new(to_lla, precision: precision)
-      end
-
-      def self.from_gh(gh_coord, datum = WGS84)
-        from_lla(gh_coord.to_lla, datum)
-      end
-
-      def to_ham(precision: 6)
-        HAM.new(to_lla, precision: precision)
-      end
-
-      def self.from_ham(ham_coord, datum = WGS84)
-        from_lla(ham_coord.to_lla, datum)
-      end
-
-      def to_olc(precision: 10)
-        OLC.new(to_lla, precision: precision)
-      end
-
-      def self.from_olc(olc_coord, datum = WGS84)
-        from_lla(olc_coord.to_lla, datum)
-      end
-
       def to_s(precision = 2)
         precision = precision.to_i
         if precision == 0
@@ -280,6 +248,8 @@ module Geodetic
         raise ArgumentError, "Easting must be positive" if @easting < 0
         raise ArgumentError, "Northing must be positive" if @northing < 0
       end
+
+      Coordinate.register_class(self)
     end
   end
 end

data/lib/geodetic/{coordinates → coordinate}/web_mercator.rb

@@ -5,7 +5,7 @@
 # Used by Google Maps, OpenStreetMap, Bing Maps, and most web mapping services
 
 module Geodetic
-  module Coordinates
+  module Coordinate
     class WebMercator
       require_relative '../datum'
 
@@ -153,38 +153,6 @@ module Geodetic
         from_lla(bng_coord.to_lla, datum)
       end
 
-      def to_gh36(precision: 10)
-        GH36.new(to_lla, precision: precision)
-      end
-
-      def self.from_gh36(gh36_coord, datum = WGS84)
-        from_lla(gh36_coord.to_lla, datum)
-      end
-
-      def to_gh(precision: 12)
-        GH.new(to_lla, precision: precision)
-      end
-
-      def self.from_gh(gh_coord, datum = WGS84)
-        from_lla(gh_coord.to_lla, datum)
-      end
-
-      def to_ham(precision: 6)
-        HAM.new(to_lla, precision: precision)
-      end
-
-      def self.from_ham(ham_coord, datum = WGS84)
-        from_lla(ham_coord.to_lla, datum)
-      end
-
-      def to_olc(precision: 10)
-        OLC.new(to_lla, precision: precision)
-      end
-
-      def self.from_olc(olc_coord, datum = WGS84)
-        from_lla(olc_coord.to_lla, datum)
-      end
-
       # Tile coordinate methods for web mapping
       def to_tile_coordinates(zoom_level)
         lat_lng = to_lla
@@ -261,6 +229,8 @@ module Geodetic
           east: se.x
         }
       end
+
+      Coordinate.register_class(self)
     end
   end
 end