geodetic 0.1.0 → 0.3.0

data/lib/geodetic/coordinate/gars.rb

@@ -0,0 +1,233 @@
+# frozen_string_literal: true
+
+# GARS (Global Area Reference System) Coordinate
+# A standardized geospatial reference system developed by the National
+# Geospatial-Intelligence Agency (NGA). Divides Earth into hierarchical
+# grid cells at three precision levels.
+#
+# Format: NNNLLqk where:
+#   NNN = 3-digit longitude band (001-720, each 0.5°)
+#   LL  = 2-letter latitude band (AA-QZ, each 0.5°)
+#   q   = quadrant digit 1-4 (optional, subdivides to 0.25°)
+#   k   = keypad digit 1-9 (optional, subdivides to ~0.0833°)
+#
+# Quadrant layout (within 30' cell):
+#   +---+---+
+#   | 1 | 2 |  (north)
+#   +---+---+
+#   | 3 | 4 |  (south)
+#   +---+---+
+#
+# Keypad layout (within quadrant, telephone-style):
+#   +---+---+---+
+#   | 1 | 2 | 3 |
+#   +---+---+---+
+#   | 4 | 5 | 6 |
+#   +---+---+---+
+#   | 7 | 8 | 9 |
+#   +---+---+---+
+#
+# Valid code lengths: 5 (30'), 6 (15'), 7 (5')
+#
+# This is a 2D coordinate system (no altitude). Conversions to/from other
+# systems go through LLA as the intermediary.
+#
+# Usage:
+#   GARS.new("006AG39")                # from a GARS string
+#   GARS.new(lla_coord)                # from any coordinate (converts via LLA)
+#   GARS.new(utm_coord, precision: 6)  # 15-minute quadrant precision
+
+require_relative 'spatial_hash'
+
+module Geodetic
+  module Coordinate
+    class GARS < SpatialHash
+      # 24 letters (A-Z, omitting I and O)
+      LETTERS = 'ABCDEFGHJKLMNPQRSTUVWXYZ'.freeze
+      LETTERS_SET = LETTERS.chars.to_set.freeze
+
+      BANDS_PER_LETTER = 24
+
+      # Quadrant digit → [col, row] (col 0=west, row 0=south)
+      QUADRANT_DECODE = {
+        1 => [0, 1],  # NW
+        2 => [1, 1],  # NE
+        3 => [0, 0],  # SW
+        4 => [1, 0],  # SE
+      }.freeze
+
+      # Keypad digit → [col, row] (col 0=west, row 0=south)
+      KEYPAD_DECODE = {
+        1 => [0, 2], 2 => [1, 2], 3 => [2, 2],
+        4 => [0, 1], 5 => [1, 1], 6 => [2, 1],
+        7 => [0, 0], 8 => [1, 0], 9 => [2, 0],
+      }.freeze
+
+      VALID_LENGTHS = [5, 6, 7].freeze
+
+      attr_reader :code
+
+      def self.default_precision = 7
+      def self.hash_system_name = :gars
+
+      # --- Subclass contract implementations ---
+
+      def valid?
+        VALID_LENGTHS.include?(@code.length) && valid_characters?(@code)
+      end
+
+      def code_value
+        @code
+      end
+
+      protected
+
+      def normalize(string)
+        result = String.new(capacity: string.length)
+        string.each_char.with_index do |ch, i|
+          result << (i >= 3 && i <= 4 ? ch.upcase : ch)
+        end
+        result
+      end
+
+      def set_code(value)
+        @code = value
+      end
+
+      private
+
+      def encode(lat, lng, length = self.class.default_precision)
+        length = length.clamp(5, 7)
+
+        adj_lng = (lng + 180.0).clamp(0.0, 360.0 - 1e-10)
+        adj_lat = (lat + 90.0).clamp(0.0, 180.0 - 1e-10)
+
+        # Longitude band (1-720, each 0.5°)
+        lon_band = (adj_lng / 0.5).to_i + 1
+        lon_band = lon_band.clamp(1, 720)
+
+        # Latitude band (1-360, each 0.5°)
+        lat_band = (adj_lat / 0.5).to_i + 1
+        lat_band = lat_band.clamp(1, 360)
+
+        result = format("%03d", lon_band)
+        first_idx  = (lat_band - 1) / BANDS_PER_LETTER
+        second_idx = (lat_band - 1) % BANDS_PER_LETTER
+        result << LETTERS[first_idx] << LETTERS[second_idx]
+
+        return result if length <= 5
+
+        # Fractional position within 30' cell (0.0 to 1.0)
+        lon_frac = adj_lng / 0.5 - (lon_band - 1)
+        lat_frac = adj_lat / 0.5 - (lat_band - 1)
+
+        # Quadrant (1-4)
+        q_col = (lon_frac * 2).to_i.clamp(0, 1)
+        q_row = (lat_frac * 2).to_i.clamp(0, 1)
+        quadrant = (1 - q_row) * 2 + q_col + 1
+        result << quadrant.to_s
+
+        return result if length <= 6
+
+        # Keypad (1-9)
+        lon_within_q = lon_frac * 2 - q_col
+        lat_within_q = lat_frac * 2 - q_row
+        k_col = (lon_within_q * 3).to_i.clamp(0, 2)
+        k_row = (lat_within_q * 3).to_i.clamp(0, 2)
+        keypad = (2 - k_row) * 3 + k_col + 1
+        result << keypad.to_s
+
+        result
+      end
+
+      def decode(code)
+        bounds = decode_bounds(code)
+        {
+          lat: (bounds[:min_lat] + bounds[:max_lat]) / 2.0,
+          lng: (bounds[:min_lng] + bounds[:max_lng]) / 2.0
+        }
+      end
+
+      def decode_bounds(code)
+        lon_band = code[0, 3].to_i
+        first_idx  = LETTERS.index(code[3])
+        second_idx = LETTERS.index(code[4])
+        raise ArgumentError, "Invalid GARS latitude band: #{code[3..4]}" unless first_idx && second_idx
+
+        lat_band = first_idx * BANDS_PER_LETTER + second_idx + 1
+
+        lng = -180.0 + (lon_band - 1) * 0.5
+        lat = -90.0 + (lat_band - 1) * 0.5
+        lng_step = 0.5
+        lat_step = 0.5
+
+        if code.length >= 6
+          quadrant = code[5].to_i
+          q_col, q_row = QUADRANT_DECODE[quadrant]
+          raise ArgumentError, "Invalid GARS quadrant: #{code[5]}" unless q_col
+
+          lng += q_col * 0.25
+          lat += q_row * 0.25
+          lng_step = 0.25
+          lat_step = 0.25
+        end
+
+        if code.length >= 7
+          keypad = code[6].to_i
+          k_col, k_row = KEYPAD_DECODE[keypad]
+          raise ArgumentError, "Invalid GARS keypad: #{code[6]}" unless k_col
+
+          cell_size = 0.25 / 3.0
+          lng += k_col * cell_size
+          lat += k_row * cell_size
+          lng_step = cell_size
+          lat_step = cell_size
+        end
+
+        { min_lat: lat, max_lat: lat + lat_step, min_lng: lng, max_lng: lng + lng_step }
+      end
+
+      def validate_gars!(code)
+        raise ArgumentError, "GARS code cannot be empty" if code.empty?
+        unless VALID_LENGTHS.include?(code.length)
+          raise ArgumentError, "GARS code must be 5, 6, or 7 characters (got #{code.length})"
+        end
+        unless valid_characters?(code)
+          raise ArgumentError, "Invalid GARS code: #{code}"
+        end
+      end
+
+      alias_method :validate_code!, :validate_gars!
+
+      def valid_characters?(code)
+        # First 3 chars: digits forming 001-720
+        return false unless code[0, 3].match?(/\A\d{3}\z/)
+        lon_band = code[0, 3].to_i
+        return false unless lon_band >= 1 && lon_band <= 720
+
+        # Next 2 chars: valid letters
+        return false unless LETTERS_SET.include?(code[3])
+        return false unless LETTERS_SET.include?(code[4])
+
+        # First letter of lat band must be A-Q (index 0-14)
+        first_idx = LETTERS.index(code[3])
+        return false if first_idx > 14
+
+        if code.length >= 6
+          q = code[5].to_i
+          return false unless q >= 1 && q <= 4
+        end
+
+        if code.length >= 7
+          k = code[6].to_i
+          return false unless k >= 1 && k <= 9
+        end
+
+        true
+      end
+
+      register_hash_system(:gars, self, default_precision: 7)
+      Coordinate.register_class(self)
+    end
+  end
+end

data/lib/geodetic/coordinate/georef.rb

@@ -0,0 +1,204 @@
+# frozen_string_literal: true
+
+# GEOREF (World Geographic Reference System) Coordinate
+# A grid-based geocode for specifying locations on Earth, developed by the
+# US military and adopted by ICAO for air navigation and air defense reporting.
+#
+# Encoding reads longitude first, then latitude. Uses a false coordinate
+# system: longitude + 180°, latitude + 90° to make all values positive.
+#
+# Structure:
+#   Chars 1-2: 15° tiles (24 lng × 12 lat letters)
+#   Chars 3-4: 1° degree subdivision (15 letters each)
+#   Chars 5+:  Minutes as even-length digit pairs (lng digits, then lat digits)
+#
+# Valid code lengths: 2, 4, 8, 10, 12, 14 characters
+# (not 6 — minimum numeric portion is 2 digits per axis)
+#
+# This is a 2D coordinate system (no altitude). Conversions to/from other
+# systems go through LLA as the intermediary.
+#
+# Usage:
+#   GEOREF.new("GJPJ3417")              # from a GEOREF string
+#   GEOREF.new(lla_coord)               # from any coordinate (converts via LLA)
+#   GEOREF.new(utm_coord, precision: 10) # with 0.1-minute precision
+
+require_relative 'spatial_hash'
+
+module Geodetic
+  module Coordinate
+    class GEOREF < SpatialHash
+      # 24 letters for longitude tiles (A-Z, omitting I and O)
+      TILE_LNG_CHARS = 'ABCDEFGHJKLMNPQRSTUVWXYZ'.freeze
+
+      # 12 letters for latitude tiles (A-M, omitting I)
+      TILE_LAT_CHARS = 'ABCDEFGHJKLM'.freeze
+
+      # 15 letters for degree subdivisions (A-Q, omitting I and O)
+      DEGREE_CHARS = 'ABCDEFGHJKLMNPQ'.freeze
+
+      TILE_LNG_SET = TILE_LNG_CHARS.chars.to_set.freeze
+      TILE_LAT_SET = TILE_LAT_CHARS.chars.to_set.freeze
+      DEGREE_SET   = DEGREE_CHARS.chars.to_set.freeze
+
+      # Valid code lengths (no length 6 — can't have single-digit minutes)
+      VALID_LENGTHS = [2, 4, 8, 10, 12, 14].freeze
+
+      attr_reader :code
+
+      def self.default_precision = 8
+      def self.hash_system_name = :georef
+
+      # --- Subclass contract implementations ---
+
+      def valid?
+        VALID_LENGTHS.include?(@code.length) && valid_characters?(@code)
+      end
+
+      def code_value
+        @code
+      end
+
+      protected
+
+      def normalize(string)
+        string.upcase
+      end
+
+      def set_code(value)
+        @code = value
+      end
+
+      private
+
+      def encode(lat, lng, length = self.class.default_precision)
+        # Snap to nearest valid length
+        length = VALID_LENGTHS.min_by { |v| (v - length).abs }
+
+        # Normalize to positive values, clamping at boundaries
+        adj_lng = (lng + 180.0).clamp(0.0, 360.0 - 1e-10)
+        adj_lat = (lat + 90.0).clamp(0.0, 180.0 - 1e-10)
+
+        result = String.new(capacity: length)
+
+        # Tile: 15° cells
+        lng_tile = (adj_lng / 15.0).to_i.clamp(0, 23)
+        lat_tile = (adj_lat / 15.0).to_i.clamp(0, 11)
+        result << TILE_LNG_CHARS[lng_tile] << TILE_LAT_CHARS[lat_tile]
+        return result if length <= 2
+
+        # Degree within tile: 1° cells
+        lng_within_tile = adj_lng - lng_tile * 15.0
+        lat_within_tile = adj_lat - lat_tile * 15.0
+        lng_deg = lng_within_tile.to_i.clamp(0, 14)
+        lat_deg = lat_within_tile.to_i.clamp(0, 14)
+        result << DEGREE_CHARS[lng_deg] << DEGREE_CHARS[lat_deg]
+        return result if length <= 4
+
+        # Minutes (numeric pairs, easting then northing)
+        lng_minutes = (lng_within_tile - lng_deg) * 60.0
+        lat_minutes = (lat_within_tile - lat_deg) * 60.0
+
+        num_digits = (length - 4) / 2
+        scale = 10**(num_digits - 2)
+
+        lng_val = (lng_minutes * scale).to_i.clamp(0, 60 * scale - 1)
+        lat_val = (lat_minutes * scale).to_i.clamp(0, 60 * scale - 1)
+
+        result << format("%0#{num_digits}d", lng_val)
+        result << format("%0#{num_digits}d", lat_val)
+
+        result
+      end
+
+      def decode(code)
+        bounds = decode_bounds(code)
+        {
+          lat: (bounds[:min_lat] + bounds[:max_lat]) / 2.0,
+          lng: (bounds[:min_lng] + bounds[:max_lng]) / 2.0
+        }
+      end
+
+      def decode_bounds(code)
+        adj_lng = 0.0
+        adj_lat = 0.0
+
+        # Tile
+        lng_tile = TILE_LNG_CHARS.index(code[0])
+        lat_tile = TILE_LAT_CHARS.index(code[1])
+        raise ArgumentError, "Invalid GEOREF tile: #{code[0..1]}" unless lng_tile && lat_tile
+
+        adj_lng = lng_tile * 15.0
+        adj_lat = lat_tile * 15.0
+        lng_step = 15.0
+        lat_step = 15.0
+
+        if code.length >= 4
+          lng_deg = DEGREE_CHARS.index(code[2])
+          lat_deg = DEGREE_CHARS.index(code[3])
+          raise ArgumentError, "Invalid GEOREF degree: #{code[2..3]}" unless lng_deg && lat_deg
+
+          adj_lng += lng_deg
+          adj_lat += lat_deg
+          lng_step = 1.0
+          lat_step = 1.0
+        end
+
+        if code.length > 4
+          num_digits = (code.length - 4) / 2
+          lng_min_str = code[4, num_digits]
+          lat_min_str = code[4 + num_digits, num_digits]
+
+          scale = 10**(num_digits - 2)
+          lng_min = lng_min_str.to_f / scale
+          lat_min = lat_min_str.to_f / scale
+
+          adj_lng += lng_min / 60.0
+          adj_lat += lat_min / 60.0
+
+          lng_step = 1.0 / (60.0 * scale)
+          lat_step = 1.0 / (60.0 * scale)
+        end
+
+        lng = adj_lng - 180.0
+        lat = adj_lat - 90.0
+
+        { min_lat: lat, max_lat: lat + lat_step, min_lng: lng, max_lng: lng + lng_step }
+      end
+
+      def validate_georef!(code)
+        raise ArgumentError, "GEOREF code cannot be empty" if code.empty?
+        unless VALID_LENGTHS.include?(code.length)
+          raise ArgumentError,
+            "GEOREF code must be 2, 4, 8, 10, 12, or 14 characters (got #{code.length})"
+        end
+        unless valid_characters?(code)
+          raise ArgumentError, "Invalid GEOREF code: #{code}"
+        end
+      end
+
+      alias_method :validate_code!, :validate_georef!
+
+      def valid_characters?(code)
+        return false unless TILE_LNG_SET.include?(code[0])
+        return false unless TILE_LAT_SET.include?(code[1])
+
+        if code.length >= 4
+          return false unless DEGREE_SET.include?(code[2])
+          return false unless DEGREE_SET.include?(code[3])
+        end
+
+        if code.length > 4
+          digits = code[4..]
+          return false unless digits.match?(/\A\d+\z/)
+          return false unless digits.length.even?
+        end
+
+        true
+      end
+
+      register_hash_system(:georef, self, default_precision: 8)
+      Coordinate.register_class(self)
+    end
+  end
+end

data/lib/geodetic/coordinate/gh.rb

@@ -0,0 +1,161 @@
+# frozen_string_literal: true
+
+# Geohash (Base-32) Coordinate System
+# The standard geohash algorithm by Gustavo Niemeyer that encodes latitude/longitude
+# into a compact string using a 32-character alphabet (0-9, b-z excluding a, i, l, o).
+# Uses interleaved longitude and latitude bits.
+#
+# Widely supported by Elasticsearch, Redis, PostGIS, and many geocoding services.
+#
+# This is a 2D coordinate system (no altitude). Conversions to/from other
+# systems go through LLA as the intermediary.
+#
+# Usage:
+#   GH.new("dr5ru7")                    # from a geohash string
+#   GH.new(lla_coord)                   # from any coordinate (converts via LLA)
+#   GH.new(utm_coord, precision: 8)     # with custom precision
+
+require_relative 'spatial_hash'
+
+module Geodetic
+  module Coordinate
+    class GH < SpatialHash
+      # Base-32 alphabet used by the standard geohash algorithm
+      BASE32 = '0123456789bcdefghjkmnpqrstuvwxyz'
+
+      # Reverse lookup: character -> index (0..31)
+      CHAR_INDEX = {}.tap do |h|
+        BASE32.each_char.with_index { |ch, i| h[ch] = i }
+      end.freeze
+
+      attr_reader :geohash
+
+      def self.default_precision = 12
+      def self.hash_system_name = :gh
+
+      # --- Subclass contract implementations ---
+
+      def valid?
+        @geohash.length > 0 && @geohash.each_char.all? { |c| CHAR_INDEX.key?(c) }
+      end
+
+      # Expose code_value for base class equality and other shared methods
+      def code_value
+        @geohash
+      end
+
+      protected
+
+      def normalize(string)
+        string.downcase
+      end
+
+      def set_code(value)
+        @geohash = value
+      end
+
+      private
+
+      # Encode lat/lng to a geohash string of given length using bit interleaving
+      def encode(lat, lng, length = self.class.default_precision)
+        lat_min, lat_max = -90.0, 90.0
+        lng_min, lng_max = -180.0, 180.0
+
+        result = String.new(capacity: length)
+        bits = 0
+        ch_idx = 0
+        even_bit = true  # true = longitude bit, false = latitude bit
+
+        while result.length < length
+          if even_bit
+            mid = (lng_min + lng_max) / 2.0
+            if lng >= mid
+              ch_idx = (ch_idx << 1) | 1
+              lng_min = mid
+            else
+              ch_idx = ch_idx << 1
+              lng_max = mid
+            end
+          else
+            mid = (lat_min + lat_max) / 2.0
+            if lat >= mid
+              ch_idx = (ch_idx << 1) | 1
+              lat_min = mid
+            else
+              ch_idx = ch_idx << 1
+              lat_max = mid
+            end
+          end
+
+          even_bit = !even_bit
+          bits += 1
+
+          if bits == 5
+            result << BASE32[ch_idx]
+            bits = 0
+            ch_idx = 0
+          end
+        end
+
+        result
+      end
+
+      # Decode a geohash string to lat/lng (returns midpoint of bounding box)
+      def decode(geohash)
+        bounds = decode_bounds(geohash)
+        {
+          lat: (bounds[:min_lat] + bounds[:max_lat]) / 2.0,
+          lng: (bounds[:min_lng] + bounds[:max_lng]) / 2.0
+        }
+      end
+
+      # Decode a geohash string to its bounding box
+      def decode_bounds(geohash)
+        lat_min, lat_max = -90.0, 90.0
+        lng_min, lng_max = -180.0, 180.0
+        even_bit = true
+
+        geohash.each_char do |ch|
+          idx = CHAR_INDEX[ch]
+          raise ArgumentError, "Invalid geohash character: #{ch}" unless idx
+
+          4.downto(0) do |i|
+            bit = (idx >> i) & 1
+            if even_bit
+              mid = (lng_min + lng_max) / 2.0
+              if bit == 1
+                lng_min = mid
+              else
+                lng_max = mid
+              end
+            else
+              mid = (lat_min + lat_max) / 2.0
+              if bit == 1
+                lat_min = mid
+              else
+                lat_max = mid
+              end
+            end
+            even_bit = !even_bit
+          end
+        end
+
+        { min_lat: lat_min, max_lat: lat_max, min_lng: lng_min, max_lng: lng_max }
+      end
+
+      def validate_geohash!(geohash)
+        raise ArgumentError, "Geohash string cannot be empty" if geohash.empty?
+        normalized = geohash.downcase
+        invalid = normalized.chars.reject { |c| CHAR_INDEX.key?(c) }
+        unless invalid.empty?
+          raise ArgumentError, "Invalid geohash characters: #{invalid.join(', ')}"
+        end
+      end
+
+      alias_method :validate_code!, :validate_geohash!
+
+      register_hash_system(:gh, self, default_precision: 12)
+      Coordinate.register_class(self)
+    end
+  end
+end