geodetic 0.1.0 → 0.3.0

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

@@ -17,11 +17,11 @@
 #   GH36.new(lla_coord)                 # from any coordinate (converts via LLA)
 #   GH36.new(utm_coord, precision: 8)   # with custom precision
 
-module Geodetic
-  module Coordinates
-    class GH36
-      require_relative '../datum'
+require_relative 'spatial_hash'
 
+module Geodetic
+  module Coordinate
+    class GH36 < SpatialHash
       # 6x6 encoding matrix mapping (row, col) to character
       # Row 0 is the northernmost latitude slice; row 5 is southernmost
       # Col 0 is the westernmost longitude slice; col 5 is easternmost
@@ -41,9 +41,6 @@ module Geodetic
       VALID_CHARS = '23456789bBCdDFgGhHjJKlLMnNPqQrRtTVWX'
       VALID_CHARS_SET = VALID_CHARS.chars.to_set.freeze
 
-      # Default hash length (10 chars gives sub-meter precision)
-      DEFAULT_LENGTH = 10
-
       # Reverse lookup: character -> [row, col] in the matrix
       CHAR_INDEX = {}.tap do |h|
         MATRIX.each_with_index do |row, r|
@@ -68,183 +65,22 @@ module Geodetic
 
       attr_reader :geohash
 
-      # Create a GH36 from a geohash string or any coordinate object.
-      #
-      #   GH36.new("bdrdC26BqH")              # from geohash string
-      #   GH36.new(lla)                        # from LLA coordinate
-      #   GH36.new(utm, precision: 8)          # from any coordinate with custom precision
-      def initialize(source, precision: DEFAULT_LENGTH)
-        case source
-        when String
-          validate_geohash!(source)
-          @geohash = source
-        when LLA
-          @geohash = encode(source.lat, source.lng, precision)
-        else
-          if source.respond_to?(:to_lla)
-            lla = source.to_lla
-            @geohash = encode(lla.lat, lla.lng, precision)
-          else
-            raise ArgumentError,
-              "Expected a geohash String or a coordinate object, got #{source.class}"
-          end
-        end
-      end
-
-      def precision
-        @geohash.length
-      end
-
-      def to_s(truncate_to = nil)
-        if truncate_to
-          @geohash[0, truncate_to.to_i]
-        else
-          @geohash
-        end
-      end
-
-      def to_a
-        coords = decode(@geohash)
-        [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 GH36 is 2D)
-      def to_lla(datum = WGS84)
-        coords = decode(@geohash)
-        LLA.new(lat: coords[:lat], lng: coords[:lng], alt: 0.0)
-      end
-
-      def self.from_lla(lla_coord, datum = WGS84, precision = DEFAULT_LENGTH)
-        new(lla_coord, precision: precision)
-      end
+      def self.default_precision = 10
+      def self.hash_system_name = :gh36
 
-      # All other conversions 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_LENGTH)
-        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_LENGTH)
-        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_LENGTH)
-        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_LENGTH)
-        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_LENGTH)
-        new(mgrs_coord, precision: precision)
-      end
+      # --- Subclass contract implementations ---
 
-      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_LENGTH)
-        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_LENGTH)
-        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_LENGTH)
-        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_LENGTH)
-        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_LENGTH)
-        new(bng_coord, precision: precision)
-      end
-
-      def to_gh(datum = WGS84, gh_precision: 12)
-        GH.new(to_lla(datum), precision: gh_precision)
-      end
-
-      def self.from_gh(gh_coord, datum = WGS84, precision = DEFAULT_LENGTH)
-        new(gh_coord, precision: precision)
-      end
-
-      def to_ham(datum = WGS84, ham_precision: 6)
-        HAM.new(to_lla(datum), precision: ham_precision)
-      end
-
-      def self.from_ham(ham_coord, datum = WGS84, precision = DEFAULT_LENGTH)
-        new(ham_coord, precision: precision)
-      end
-
-      def to_olc(datum = WGS84, olc_precision: 10)
-        OLC.new(to_lla(datum), precision: olc_precision)
-      end
-
-      def self.from_olc(olc_coord, datum = WGS84, precision = DEFAULT_LENGTH)
-        new(olc_coord, precision: precision)
+      def valid?
+        @geohash.length > 0 && @geohash.each_char.all? { |c| VALID_CHARS_SET.include?(c) }
       end
 
-      def ==(other)
-        return false unless other.is_a?(GH36)
-        @geohash == other.geohash
+      def code_value
+        @geohash
       end
 
-      def valid?
-        @geohash.length > 0 && @geohash.each_char.all? { |c| VALID_CHARS_SET.include?(c) }
-      end
+      # --- GH36-specific overrides (matrix-based algorithms) ---
 
-      # Returns all 8 neighboring geohash cells as GH36 instances
-      # Keys: :N, :S, :E, :W, :NE, :NW, :SE, :SW
+      # Uses recursive matrix-based neighbor calculation instead of bounds-based
       def neighbors
         DIRECTIONS.each_with_object({}) do |(dir, delta), result|
           hash = self.class.send(:neighbor_hash, @geohash, delta[0], delta[1])
@@ -252,7 +88,7 @@ module Geodetic
         end
       end
 
-      # Returns the geohash cell as an Areas::Rectangle
+      # Uses decode_bounds via class method
       def to_area
         bb = self.class.send(:decode_bounds, @geohash)
         nw = LLA.new(lat: bb[:max_lat], lng: bb[:min_lng], alt: 0.0)
@@ -260,20 +96,23 @@ module Geodetic
         Areas::Rectangle.new(nw: nw, se: se)
       end
 
-      # Returns precision in meters as {lat:, lng:}
+      # Uses formula-based precision instead of bounds-based
       def precision_in_meters
         one_degree_meters = (2 * Math::PI * 6_370_000) / 360.0
         lat_prec = (90.0 / (MATRIX_SIDE ** precision)) * one_degree_meters
         { lat: lat_prec, lng: lat_prec * 2 }
       end
 
-      # URL-friendly slug (the geohash itself is already URL-safe)
-      alias_method :to_slug, :to_s
+      protected
+
+      def set_code(value)
+        @geohash = value
+      end
 
       private
 
       # Encode lat/lng to a geohash string of given length
-      def encode(lat, lng, length = DEFAULT_LENGTH)
+      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
 
@@ -323,7 +162,7 @@ module Geodetic
         }
       end
 
-      # Decode a geohash string to its bounding box
+      # Decode a geohash string to its bounding box (class method for neighbor_hash access)
       def self.decode_bounds(geohash)
         lat_min, lat_max = -90.0, 90.0
         lng_min, lng_max = -180.0, 180.0
@@ -353,9 +192,6 @@ module Geodetic
       # Compute a neighbor hash by adjusting the last character's position
       # in the matrix. When the adjustment wraps beyond the matrix edge,
       # we recurse on the parent prefix and carry the wrap.
-      #
-      # Matrix layout: row 0 = north (high lat), row 5 = south (low lat)
-      #                col 0 = west (low lng),  col 5 = east (high lng)
       def self.neighbor_hash(hash, row_delta, col_delta)
         return hash if hash.empty?
 
@@ -373,7 +209,7 @@ module Geodetic
         carry_col = 0
 
         if new_row < 0
-          carry_row = row_delta  # Propagate same direction
+          carry_row = row_delta
           new_row += MATRIX_SIDE
         elsif new_row >= MATRIX_SIDE
           carry_row = row_delta
@@ -403,6 +239,11 @@ module Geodetic
           raise ArgumentError, "Invalid Geohash-36 characters: #{invalid.join(', ')}"
         end
       end
+
+      alias_method :validate_code!, :validate_geohash!
+
+      register_hash_system(:gh36, self, default_precision: 10)
+      Coordinate.register_class(self)
     end
   end
 end

data/lib/geodetic/coordinate/h3.rb

@@ -0,0 +1,413 @@
+# frozen_string_literal: true
+
+# H3 (Uber's Hexagonal Hierarchical Spatial Index) Coordinate
+#
+# A hierarchical geospatial index that divides the globe into hexagonal cells
+# (and 12 pentagons) at 16 resolution levels (0-15). Each cell is identified
+# by a 64-bit integer (H3Index), typically displayed as a 15-character hex string.
+#
+# REQUIRES: libh3 shared library (brew install h3)
+# Uses Ruby's fiddle (stdlib) to call H3 v4 C API — no gem dependency.
+#
+# Key differences from other spatial hashes:
+#   - Cells are hexagons (6 vertices), not rectangles
+#   - to_area returns Areas::Polygon, not Areas::Rectangle
+#   - neighbors returns an Array (6 cells), not a directional Hash
+#   - "precision" maps to H3 resolution (0-15), not string length
+#
+# Usage:
+#   H3.new("872a1072bffffff")              # from hex string
+#   H3.new(0x872a1072bffffff)              # from integer
+#   H3.new(lla_coord)                      # from any coordinate
+#   H3.new(lla_coord, precision: 9)        # resolution 9
+
+require_relative 'spatial_hash'
+
+module Geodetic
+  module Coordinate
+    class H3 < SpatialHash
+      # --- FFI bindings to libh3 via fiddle ---
+
+      module LibH3
+        require 'fiddle'
+
+        SEARCH_PATHS = [
+          ENV['LIBH3_PATH'],
+          '/opt/homebrew/lib/libh3.dylib',
+          '/opt/homebrew/lib/libh3.1.dylib',
+          '/usr/local/lib/libh3.dylib',
+          '/usr/local/lib/libh3.1.dylib',
+          '/usr/lib/libh3.so',
+          '/usr/lib/libh3.so.1',
+          '/usr/local/lib/libh3.so',
+          '/usr/local/lib/libh3.so.1',
+          '/usr/lib/x86_64-linux-gnu/libh3.so',
+          '/usr/lib/aarch64-linux-gnu/libh3.so',
+        ].compact.freeze
+
+        @handle = nil
+        @available = false
+
+        class << self
+          attr_reader :handle
+
+          def available?
+            @available
+          end
+
+          def require_library!
+            return if @available
+            raise Geodetic::Error,
+              "libh3 not found. Install H3: brew install h3 (macOS) " \
+              "or see https://h3geo.org/docs/installation. " \
+              "Set LIBH3_PATH env var to specify a custom library path."
+          end
+        end
+
+        begin
+          path = SEARCH_PATHS.find { |p| File.exist?(p) }
+          if path
+            @handle = Fiddle.dlopen(path)
+            @available = true
+          end
+        rescue Fiddle::DLError
+          @available = false
+        end
+
+        # Struct sizes
+        SIZEOF_LATLNG = 2 * Fiddle::SIZEOF_DOUBLE          # 16 bytes
+        SIZEOF_CELL_BOUNDARY = 8 + 10 * SIZEOF_LATLNG       # 168 bytes (int + pad + 10 LatLngs)
+        SIZEOF_H3INDEX = Fiddle::SIZEOF_LONG_LONG            # 8 bytes
+        SIZEOF_INT64 = Fiddle::SIZEOF_LONG_LONG              # 8 bytes
+
+        # Function bindings (lazy-loaded)
+        def self.bind(name, args, ret)
+          return nil unless @available
+          ptr = @handle[name]
+          Fiddle::Function.new(ptr, args, ret)
+        rescue Fiddle::DLError
+          nil
+        end
+
+        # H3Error latLngToCell(const LatLng *g, int res, H3Index *out)
+        F_LAT_LNG_TO_CELL = bind('latLngToCell',
+          [Fiddle::TYPE_VOIDP, Fiddle::TYPE_INT, Fiddle::TYPE_VOIDP],
+          Fiddle::TYPE_INT)
+
+        # H3Error cellToLatLng(H3Index h3, LatLng *g)
+        F_CELL_TO_LAT_LNG = bind('cellToLatLng',
+          [Fiddle::TYPE_LONG_LONG, Fiddle::TYPE_VOIDP],
+          Fiddle::TYPE_INT)
+
+        # H3Error cellToBoundary(H3Index h3, CellBoundary *gp)
+        F_CELL_TO_BOUNDARY = bind('cellToBoundary',
+          [Fiddle::TYPE_LONG_LONG, Fiddle::TYPE_VOIDP],
+          Fiddle::TYPE_INT)
+
+        # int getResolution(H3Index h)
+        F_GET_RESOLUTION = bind('getResolution',
+          [Fiddle::TYPE_LONG_LONG],
+          Fiddle::TYPE_INT)
+
+        # int isValidCell(H3Index h)
+        F_IS_VALID_CELL = bind('isValidCell',
+          [Fiddle::TYPE_LONG_LONG],
+          Fiddle::TYPE_INT)
+
+        # int isPentagon(H3Index h)
+        F_IS_PENTAGON = bind('isPentagon',
+          [Fiddle::TYPE_LONG_LONG],
+          Fiddle::TYPE_INT)
+
+        # H3Error gridDisk(H3Index origin, int k, H3Index *out)
+        F_GRID_DISK = bind('gridDisk',
+          [Fiddle::TYPE_LONG_LONG, Fiddle::TYPE_INT, Fiddle::TYPE_VOIDP],
+          Fiddle::TYPE_INT)
+
+        # H3Error maxGridDiskSize(int k, int64_t *out)
+        F_MAX_GRID_DISK_SIZE = bind('maxGridDiskSize',
+          [Fiddle::TYPE_INT, Fiddle::TYPE_VOIDP],
+          Fiddle::TYPE_INT)
+
+        # H3Error cellAreaM2(H3Index h, double *out)
+        F_CELL_AREA_M2 = bind('cellAreaM2',
+          [Fiddle::TYPE_LONG_LONG, Fiddle::TYPE_VOIDP],
+          Fiddle::TYPE_INT)
+
+        # H3Error cellToParent(H3Index h, int parentRes, H3Index *out)
+        F_CELL_TO_PARENT = bind('cellToParent',
+          [Fiddle::TYPE_LONG_LONG, Fiddle::TYPE_INT, Fiddle::TYPE_VOIDP],
+          Fiddle::TYPE_INT)
+
+        # H3Error cellToChildrenSize(H3Index h, int childRes, int64_t *out)
+        F_CELL_TO_CHILDREN_SIZE = bind('cellToChildrenSize',
+          [Fiddle::TYPE_LONG_LONG, Fiddle::TYPE_INT, Fiddle::TYPE_VOIDP],
+          Fiddle::TYPE_INT)
+
+        # H3Error cellToChildren(H3Index h, int childRes, H3Index *out)
+        F_CELL_TO_CHILDREN = bind('cellToChildren',
+          [Fiddle::TYPE_LONG_LONG, Fiddle::TYPE_INT, Fiddle::TYPE_VOIDP],
+          Fiddle::TYPE_INT)
+
+        # --- High-level wrappers ---
+
+        def self.lat_lng_to_cell(lat_rad, lng_rad, resolution)
+          require_library!
+          latlng = Fiddle::Pointer.malloc(SIZEOF_LATLNG, Fiddle::RUBY_FREE)
+          latlng[0, SIZEOF_LATLNG] = [lat_rad, lng_rad].pack('d2')
+          out = Fiddle::Pointer.malloc(SIZEOF_H3INDEX, Fiddle::RUBY_FREE)
+          err = F_LAT_LNG_TO_CELL.call(latlng, resolution, out)
+          raise ArgumentError, "H3 latLngToCell error (code #{err})" unless err == 0
+          out[0, SIZEOF_H3INDEX].unpack1('Q')
+        end
+
+        def self.cell_to_lat_lng(h3_index)
+          require_library!
+          latlng = Fiddle::Pointer.malloc(SIZEOF_LATLNG, Fiddle::RUBY_FREE)
+          err = F_CELL_TO_LAT_LNG.call(h3_index, latlng)
+          raise ArgumentError, "H3 cellToLatLng error (code #{err})" unless err == 0
+          lat_rad, lng_rad = latlng[0, SIZEOF_LATLNG].unpack('d2')
+          { lat: lat_rad * DEG_PER_RAD, lng: lng_rad * DEG_PER_RAD }
+        end
+
+        def self.cell_to_boundary(h3_index)
+          require_library!
+          cb = Fiddle::Pointer.malloc(SIZEOF_CELL_BOUNDARY, Fiddle::RUBY_FREE)
+          err = F_CELL_TO_BOUNDARY.call(h3_index, cb)
+          raise ArgumentError, "H3 cellToBoundary error (code #{err})" unless err == 0
+          num_verts = cb[0, 4].unpack1('i')
+          # Vertices start at offset 8 (4 byte int + 4 byte padding)
+          verts = cb[8, num_verts * SIZEOF_LATLNG].unpack("d#{num_verts * 2}")
+          (0...num_verts).map do |i|
+            { lat: verts[i * 2] * DEG_PER_RAD, lng: verts[i * 2 + 1] * DEG_PER_RAD }
+          end
+        end
+
+        def self.get_resolution(h3_index)
+          require_library!
+          F_GET_RESOLUTION.call(h3_index)
+        end
+
+        def self.is_valid_cell(h3_index)
+          require_library!
+          F_IS_VALID_CELL.call(h3_index) == 1
+        end
+
+        def self.is_pentagon(h3_index)
+          require_library!
+          F_IS_PENTAGON.call(h3_index) == 1
+        end
+
+        def self.grid_disk(h3_index, k)
+          require_library!
+          size_ptr = Fiddle::Pointer.malloc(SIZEOF_INT64, Fiddle::RUBY_FREE)
+          err = F_MAX_GRID_DISK_SIZE.call(k, size_ptr)
+          raise ArgumentError, "H3 maxGridDiskSize error (code #{err})" unless err == 0
+          max_size = size_ptr[0, SIZEOF_INT64].unpack1('q')
+
+          out = Fiddle::Pointer.malloc(max_size * SIZEOF_H3INDEX, Fiddle::RUBY_FREE)
+          err = F_GRID_DISK.call(h3_index, k, out)
+          raise ArgumentError, "H3 gridDisk error (code #{err})" unless err == 0
+
+          out[0, max_size * SIZEOF_H3INDEX].unpack("Q#{max_size}").reject(&:zero?)
+        end
+
+        def self.cell_area_m2(h3_index)
+          require_library!
+          out = Fiddle::Pointer.malloc(Fiddle::SIZEOF_DOUBLE, Fiddle::RUBY_FREE)
+          err = F_CELL_AREA_M2.call(h3_index, out)
+          raise ArgumentError, "H3 cellAreaM2 error (code #{err})" unless err == 0
+          out[0, Fiddle::SIZEOF_DOUBLE].unpack1('d')
+        end
+
+        def self.cell_to_parent(h3_index, parent_res)
+          require_library!
+          out = Fiddle::Pointer.malloc(SIZEOF_H3INDEX, Fiddle::RUBY_FREE)
+          err = F_CELL_TO_PARENT.call(h3_index, parent_res, out)
+          raise ArgumentError, "H3 cellToParent error (code #{err})" unless err == 0
+          out[0, SIZEOF_H3INDEX].unpack1('Q')
+        end
+
+        def self.cell_to_children(h3_index, child_res)
+          require_library!
+          size_ptr = Fiddle::Pointer.malloc(SIZEOF_INT64, Fiddle::RUBY_FREE)
+          err = F_CELL_TO_CHILDREN_SIZE.call(h3_index, child_res, size_ptr)
+          raise ArgumentError, "H3 cellToChildrenSize error (code #{err})" unless err == 0
+          count = size_ptr[0, SIZEOF_INT64].unpack1('q')
+
+          out = Fiddle::Pointer.malloc(count * SIZEOF_H3INDEX, Fiddle::RUBY_FREE)
+          err = F_CELL_TO_CHILDREN.call(h3_index, child_res, out)
+          raise ArgumentError, "H3 cellToChildren error (code #{err})" unless err == 0
+
+          out[0, count * SIZEOF_H3INDEX].unpack("Q#{count}").reject(&:zero?)
+        end
+      end
+
+      # --- Class configuration ---
+
+      attr_reader :code
+
+      def self.default_precision = 7
+      def self.hash_system_name = :h3
+
+      def self.available?
+        LibH3.available?
+      end
+
+      # --- Constructor ---
+
+      def initialize(source, precision: self.class.default_precision)
+        case source
+        when Integer
+          hex = format('%x', source)
+          validate_code!(hex)
+          set_code(hex)
+        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 an H3 hex String, Integer, or coordinate object, got #{source.class}"
+          end
+        end
+      end
+
+      # --- H3-specific methods ---
+
+      # The 64-bit H3 cell index
+      def h3_index
+        @h3_index ||= code.to_i(16)
+      end
+
+      # H3 resolution (0-15)
+      def precision
+        @resolution ||= LibH3.get_resolution(h3_index)
+      end
+      alias_method :resolution, :precision
+
+      # Is this cell a pentagon? (12 per resolution level)
+      def pentagon?
+        LibH3.is_pentagon(h3_index)
+      end
+
+      # Parent cell at a coarser resolution
+      def parent(parent_resolution)
+        raise ArgumentError, "Parent resolution must be < #{resolution}" unless parent_resolution < resolution
+        parent_idx = LibH3.cell_to_parent(h3_index, parent_resolution)
+        self.class.new(parent_idx)
+      end
+
+      # Child cells at a finer resolution
+      def children(child_resolution)
+        raise ArgumentError, "Child resolution must be > #{resolution}" unless child_resolution > resolution
+        child_indices = LibH3.cell_to_children(h3_index, child_resolution)
+        child_indices.map { |idx| self.class.new(idx) }
+      end
+
+      # All cells within k steps (k=0 returns self, k=1 returns 7 cells, etc.)
+      def grid_disk(k = 1)
+        indices = LibH3.grid_disk(h3_index, k)
+        indices.map { |idx| self.class.new(idx) }
+      end
+
+      # Cell area in square meters
+      def cell_area
+        LibH3.cell_area_m2(h3_index)
+      end
+
+      # --- Override SpatialHash methods ---
+
+      def valid?
+        LibH3.is_valid_cell(h3_index)
+      end
+
+      # Returns all adjacent cells as an Array of H3 instances.
+      # Hexagons have 6 neighbors; pentagons have 5.
+      # Note: returns Array, not directional Hash (hexagons have no cardinal directions).
+      def neighbors
+        indices = LibH3.grid_disk(h3_index, 1)
+        indices.reject { |idx| idx == h3_index }.map { |idx| self.class.new(idx) }
+      end
+
+      # Returns the hexagonal cell boundary as an Areas::Polygon.
+      def to_area
+        verts = LibH3.cell_to_boundary(h3_index)
+        boundary = verts.map { |v| LLA.new(lat: v[:lat], lng: v[:lng], alt: 0.0) }
+        Areas::Polygon.new(boundary: boundary)
+      end
+
+      # Returns approximate precision in meters as { lat:, lng:, area_m2: }
+      def precision_in_meters
+        area = cell_area
+        edge = Math.sqrt(area)
+        { lat: edge, lng: edge, area_m2: area }
+      end
+
+      def to_s(format = nil)
+        if format == :integer
+          h3_index
+        else
+          code
+        end
+      end
+
+      def code_value
+        @code
+      end
+
+      protected
+
+      def normalize(string)
+        string.downcase.delete_prefix('0x')
+      end
+
+      def set_code(value)
+        @code = value
+        @h3_index = nil
+        @resolution = nil
+      end
+
+      private
+
+      def encode(lat, lng, resolution = self.class.default_precision)
+        resolution = resolution.clamp(0, 15)
+        lat_rad = lat * RAD_PER_DEG
+        lng_rad = lng * RAD_PER_DEG
+        idx = LibH3.lat_lng_to_cell(lat_rad, lng_rad, resolution)
+        format('%x', idx)
+      end
+
+      def decode(code_string)
+        idx = code_string.to_i(16)
+        LibH3.cell_to_lat_lng(idx)
+      end
+
+      def decode_bounds(code_string)
+        idx = code_string.to_i(16)
+        verts = LibH3.cell_to_boundary(idx)
+        lats = verts.map { |v| v[:lat] }
+        lngs = verts.map { |v| v[:lng] }
+        { min_lat: lats.min, max_lat: lats.max, min_lng: lngs.min, max_lng: lngs.max }
+      end
+
+      def validate_h3!(code_string)
+        raise ArgumentError, "H3 code cannot be empty" if code_string.empty?
+        raise ArgumentError, "Invalid H3 hex string: #{code_string}" unless code_string.match?(/\A[0-9a-f]+\z/)
+        idx = code_string.to_i(16)
+        raise ArgumentError, "Invalid H3 cell index: #{code_string}" unless LibH3.is_valid_cell(idx)
+      end
+
+      alias_method :validate_code!, :validate_h3!
+
+      register_hash_system(:h3, self, default_precision: 7)
+      Coordinate.register_class(self)
+    end
+  end
+end