h3 3.2.0

data/lib/h3.rb

@@ -0,0 +1,36 @@
+require "ffi"
+require "rgeo/geo_json"
+
+require "h3/bindings"
+require "h3/geo_json"
+require "h3/hierarchy"
+require "h3/indexing"
+require "h3/inspection"
+require "h3/miscellaneous"
+require "h3/regions"
+require "h3/traversal"
+require "h3/unidirectional_edges"
+
+# The main H3 namespace.
+#
+# All public methods for the library are defined here.
+#
+# @see https://uber.github.io/h3/#/documentation/overview/introduction
+module H3
+  class << self
+    include GeoJSON
+    include Hierarchy
+    include Miscellaneous
+    include Indexing
+    include Inspection
+    include Regions
+    include Traversal
+    include UnidirectionalEdges
+  end
+
+  PREDICATES = %i(h3_indexes_neighbors h3_pentagon h3_res_class_3
+                  h3_unidirectional_edge_valid h3_valid).freeze
+  PREDICATES.each do |predicate|
+    singleton_class.send(:alias_method, "#{predicate}?".to_sym, predicate)
+  end
+end

data/lib/h3/bindings.rb

@@ -0,0 +1,12 @@
+require "h3/bindings/base"
+require "h3/bindings/structs"
+require "h3/bindings/private"
+
+module H3
+  # Internal bindings related modules and classes.
+  #
+  # These are intended to be used by the library's public methods
+  # and not to be used directly by client code.
+  module Bindings
+  end
+end

data/lib/h3/bindings/base.rb

@@ -0,0 +1,15 @@
+module H3
+  module Bindings
+    # Base for FFI Bindings.
+    #
+    # When extended, this module sets up FFI to use the H3 C library.
+    module Base
+      def self.extended(base)
+        base.extend FFI::Library
+        base.ffi_lib ["libh3", "libh3.1"]
+        base.typedef :ulong_long, :h3_index
+        base.const_set('H3_INDEX', :ulong_long)
+      end
+    end
+  end
+end

data/lib/h3/bindings/private.rb

@@ -0,0 +1,32 @@
+module H3
+  module Bindings
+    # Private H3 functions which should not be called directly.
+    #
+    # This module provides bindings that do not have to be invoked directly by clients
+    # of the library. They are used only internally to provide related public interface.
+    module Private
+      extend H3::Bindings::Base
+
+      attach_function :compact, [:pointer, :pointer, :int], :bool
+      attach_function :geo_to_h3, :geoToH3, [ Bindings::Structs::GeoCoord.by_ref, :int ], :h3_index
+      attach_function :h3_indexes_from_unidirectional_edge, :getH3IndexesFromUnidirectionalEdge, [ :h3_index, :pointer ], :void
+      attach_function :h3_unidirectional_edges_from_hexagon, :getH3UnidirectionalEdgesFromHexagon, [ :h3_index, :pointer ], :void
+      attach_function :h3_set_to_linked_geo, :h3SetToLinkedGeo, [ :pointer, :int, Bindings::Structs::LinkedGeoPolygon.by_ref ], :void
+      attach_function :h3_to_children, :h3ToChildren, [ :h3_index, :int, :pointer ], :void
+      attach_function :h3_to_geo, :h3ToGeo, [ :h3_index, Bindings::Structs::GeoCoord.by_ref ], :void
+      attach_function :h3_to_string, :h3ToString, [ :h3_index, :pointer, :int], :void
+      attach_function :h3_to_geo_boundary, :h3ToGeoBoundary, [:h3_index, Bindings::Structs::GeoBoundary.by_ref ], :void
+      attach_function :h3_unidirectional_edge_boundary, :getH3UnidirectionalEdgeBoundary, [:h3_index, :pointer], :void  
+      attach_function :hex_range, :hexRange, [ :h3_index, :int, :pointer ], :bool
+      attach_function :hex_range_distances, :hexRangeDistances, [:h3_index, :int, :pointer, :pointer], :bool
+      attach_function :hex_ranges, :hexRanges, [ :pointer, :int, :int, :pointer ], :bool
+      attach_function :hex_ring, :hexRing, [:h3_index, :int, :pointer], :bool
+      attach_function :k_ring, :kRing, [:h3_index, :int, :pointer], :void
+      attach_function :k_ring_distances, :kRingDistances, [:h3_index, :int, :pointer, :pointer], :bool
+      attach_function :max_polyfill_size, :maxPolyfillSize, [Bindings::Structs::GeoPolygon.by_ref, :int], :int
+      attach_function :max_uncompact_size, :maxUncompactSize, [:pointer, :int, :int], :int
+      attach_function :polyfill, [ :pointer, :int, :pointer ], :void
+      attach_function :uncompact, [:pointer, :int, :pointer, :int, :int], :bool
+    end
+  end
+end

data/lib/h3/bindings/structs.rb

@@ -0,0 +1,59 @@
+module H3
+  module Bindings
+    # FFI Structs.
+    #
+    # These match the structs defined in H3's header file and are required
+    # to correctly interact with the library's functions.
+    module Structs
+      extend FFI::Library
+
+      class GeoCoord < FFI::Struct
+        layout :lat, :double,
+               :lon, :double
+      end
+
+      class GeoBoundary < FFI::Struct
+        layout :num_verts, :int,
+               :verts, [:double, 20] # array of GeoCoord structs (must be fixed length)
+      end
+
+      class GeoFence < FFI::Struct
+        layout :num_verts, :int,
+               :verts, :pointer # array of GeoCoord structs
+      end
+
+      class GeoPolygon < FFI::Struct
+        layout :geofence, GeoFence,
+               :num_holes, :int,
+               :holes, :pointer # array of GeoFence structs
+      end
+
+      class GeoMultiPolygon < FFI::Struct
+        layout :num_polygons, :int,
+               :polygons, :pointer # array of GeoPolygon structs
+      end
+
+      class LinkedGeoCoord < FFI::Struct
+        layout :vertex, GeoCoord,
+               :next, LinkedGeoCoord.ptr
+      end
+
+      class LinkedGeoLoop < FFI::Struct
+        layout :first, LinkedGeoCoord.ptr,
+               :last, LinkedGeoCoord.ptr,
+               :next, LinkedGeoLoop.ptr
+      end
+
+      class LinkedGeoPolygon < FFI::Struct
+        layout :first, LinkedGeoLoop.ptr,
+               :last, LinkedGeoLoop.ptr,
+               :next, LinkedGeoPolygon.ptr
+      end
+
+      class CoordIJ < FFI::Struct
+        layout :i, :int,
+               :j, :int
+      end
+    end
+  end
+end

data/lib/h3/geo_json.rb

@@ -0,0 +1,169 @@
+module H3
+  # GeoJSON helper methods.
+  #
+  # This module allows conversions between GeoJSON polygon data and a nested set of coordinates.
+  # 
+  # It should be noted that H3 describes coordinates as number pairs in the form
+  #
+  #   [latitude, longitude]
+  #
+  # whereas the GeoJSON standard uses
+  #
+  #   [longitude, latitude]
+  #
+  # Both use degrees.
+  #
+  # == Coordinates Array
+  #
+  # We use a nested array to hold coordinates describing a geographical region.
+  #
+  # The first element in the array is an external geofence boundary, composed of an array of
+  # coordinates as 2-element arrays of the form [latitude, longitude].
+  #
+  # Any further elements in the array are further geofence arrays of coordinates which describe
+  # holes that may be present in the polygon.
+  #
+  # Specific examples are shown in the individual method details.
+  #
+  # @see http://geojson.io geojson.io - A graphical tool to see GeoJSON data rendered on a world map.
+  # @see https://tools.ietf.org/html/rfc7946 The GeoJSON RFC standard.
+  module GeoJSON
+    # Convert a GeoJSON document to a nested array of coordinates.
+    #
+    # @param [String] input The GeoJSON document. This can be a feature collection, feature,
+    #   or polygon. If a feature collection is provided, the first feature is used.
+    #
+    # @example Convert a GeoJSON document of Banbury to a set of nested coordinates.
+    #   document = "{\"type\":\"Polygon\",\"coordinates\":[
+    #     [
+    #       [-1.7358398437499998,52.24630137198303], [-1.8923950195312498,52.05249047600099],
+    #       [-1.56829833984375,51.891749018068246], [-1.27716064453125,51.91208502557545],
+    #       [-1.19476318359375,52.032218104145294], [-1.24420166015625,52.19413974159753],
+    #       [-1.5902709960937498,52.24125614966341], [-1.7358398437499998,52.24630137198303]
+    #     ],
+    #     [
+    #       [-1.58203125,52.12590076522272], [-1.476287841796875,52.12590076522272],
+    #       [-1.46392822265625,52.075285904832334], [-1.58203125,52.06937709602395],
+    #       [-1.58203125,52.12590076522272]
+    #     ],
+    #     [
+    #       [-1.4556884765625,52.01531743663362], [-1.483154296875,51.97642166216334],
+    #       [-1.3677978515625,51.96626938051444], [-1.3568115234375,52.0102459910103],
+    #       [-1.4556884765625,52.01531743663362]
+    #     ]
+    #   ]}"
+    #   H3.geo_json_to_coordinates(document)
+    #   [
+    #     [
+    #       [52.24630137198303, -1.7358398437499998], [52.05249047600099, -1.8923950195312498],
+    #       [51.891749018068246, -1.56829833984375], [51.91208502557545, -1.27716064453125],
+    #       [52.032218104145294, -1.19476318359375], [52.19413974159753, -1.24420166015625],
+    #       [52.24125614966341, -1.5902709960937498], [52.24630137198303, -1.7358398437499998]
+    #     ],
+    #     [
+    #       [52.12590076522272, -1.58203125], [52.12590076522272, -1.476287841796875],
+    #       [52.075285904832334, -1.46392822265625], [52.06937709602395, -1.58203125],
+    #       [52.12590076522272, -1.58203125]
+    #     ],
+    #     [
+    #       [52.01531743663362, -1.4556884765625], [51.97642166216334, -1.483154296875],
+    #       [51.96626938051444, -1.3677978515625], [52.0102459910103, -1.3568115234375],
+    #       [52.01531743663362, -1.4556884765625]
+    #     ]
+    #   ]
+    #
+    # @raise [ArgumentError] Failed to parse the GeoJSON document.
+    #
+    # @return [Array<Array<Array>>] Nested array of coordinates.
+    def geo_json_to_coordinates(input)
+      geom = RGeo::GeoJSON.decode(input)
+      coordinates = if geom.respond_to?(:first) # feature collection
+                      geom.first.geometry.coordinates
+                    elsif geom.respond_to?(:geometry) # feature
+                      geom.geometry.coordinates
+                    elsif geom.respond_to?(:coordinates) # polygon
+                      geom.coordinates
+                    else
+                      failed_to_parse!
+                    end
+      swap_lat_lon(coordinates) || failed_to_parse!
+    rescue JSON::ParserError
+      failed_to_parse!
+    end
+
+    # Convert a nested array of coordinates to a GeoJSON document
+    #
+    # @param [Array<Array<Array>>] coordinates Nested array of coordinates.
+    #
+    # @example Convert a set of nested coordinates of Banbury to a GeoJSON document.
+    #   coordinates = [
+    #     [
+    #       [52.24630137198303, -1.7358398437499998], [52.05249047600099, -1.8923950195312498],
+    #       [51.891749018068246, -1.56829833984375], [51.91208502557545, -1.27716064453125],
+    #       [52.032218104145294, -1.19476318359375], [52.19413974159753, -1.24420166015625],
+    #       [52.24125614966341, -1.5902709960937498], [52.24630137198303, -1.7358398437499998]
+    #     ],
+    #     [
+    #       [52.12590076522272, -1.58203125], [52.12590076522272, -1.476287841796875],
+    #       [52.075285904832334, -1.46392822265625], [52.06937709602395, -1.58203125],
+    #       [52.12590076522272, -1.58203125]
+    #     ],
+    #     [
+    #       [52.01531743663362, -1.4556884765625], [51.97642166216334, -1.483154296875],
+    #       [51.96626938051444, -1.3677978515625], [52.0102459910103, -1.3568115234375],
+    #       [52.01531743663362, -1.4556884765625]
+    #     ]
+    #   ]
+    #   H3.coordinates_to_geo_json(coordinates)
+    #   "{\"type\":\"Polygon\",\"coordinates\":[
+    #     [
+    #       [-1.7358398437499998,52.24630137198303], [-1.8923950195312498,52.05249047600099],
+    #       [-1.56829833984375,51.891749018068246], [-1.27716064453125,51.91208502557545],
+    #       [-1.19476318359375,52.032218104145294], [-1.24420166015625,52.19413974159753],
+    #       [-1.5902709960937498,52.24125614966341], [-1.7358398437499998,52.24630137198303]
+    #     ],
+    #     [
+    #       [-1.58203125,52.12590076522272], [-1.476287841796875,52.12590076522272],
+    #       [-1.46392822265625,52.075285904832334], [-1.58203125,52.06937709602395],
+    #       [-1.58203125,52.12590076522272]
+    #     ],
+    #     [
+    #       [-1.4556884765625,52.01531743663362], [-1.483154296875,51.97642166216334],
+    #       [-1.3677978515625,51.96626938051444], [-1.3568115234375,52.0102459910103],
+    #       [-1.4556884765625,52.01531743663362]
+    #     ]
+    #   ]}"
+    #
+    # @raise [ArgumentError] Failed to parse the given coordinates.
+    #
+    # @return [String] GeoJSON document.
+    def coordinates_to_geo_json(coordinates)
+      coordinates = swap_lat_lon(coordinates)
+      outer_coords, *inner_coords = coordinates
+      factory = RGeo::Cartesian.simple_factory
+      exterior = factory.linear_ring(outer_coords.map { |lon, lat| factory.point(lon, lat) })
+      interior_rings = inner_coords.map do |polygon|
+        factory.linear_ring(polygon.map { |lon, lat| factory.point(lon, lat) })
+      end
+      polygon = factory.polygon(exterior, interior_rings)
+      RGeo::GeoJSON.encode(polygon).to_json
+    rescue RGeo::Error::InvalidGeometry, NoMethodError
+      invalid_coordinates!
+    end
+
+    private
+
+    # geo-json coordinates use [lon, lat], h3 uses [lat, lon]
+    def swap_lat_lon(coordinates)
+      coordinates.map { |polygon| polygon.map { |x, y| [y, x] } }
+    end
+
+    def failed_to_parse!
+      raise ArgumentError, "Could not parse given input. Please use a GeoJSON polygon."
+    end
+
+    def invalid_coordinates!
+      raise ArgumentError, "Could not parse given coordinates."
+    end
+  end
+end

data/lib/h3/hierarchy.rb

@@ -0,0 +1,160 @@
+module H3
+  # Hierarchical grid functions.
+  #
+  # @see https://uber.github.io/h3/#/documentation/api-reference/hierarchy
+  module Hierarchy
+    extend H3::Bindings::Base
+
+    # @!method h3_to_parent(h3_index, parent_resolution)
+    #
+    # Derive the parent hexagon which contains the hexagon at the given H3 index.
+    #
+    # @param [Integer] h3_index A valid H3 index.
+    # @param [Integer] parent_resoluton The desired resolution of the parent hexagon.
+    #
+    # @example Find the parent hexagon for a H3 index.
+    #   H3.h3_to_parent(613196570357137407, 6)
+    #   604189371209351167
+    #
+    # @return [Integer] H3 index of parent hexagon.
+    attach_function :h3_to_parent, :h3ToParent, [ :h3_index, :int ], :h3_index
+
+    # @!method max_h3_to_children_size(h3_index, child_resolution)
+    #
+    # Derive maximum number of child hexagons possible at given resolution.
+    #
+    # @param [Integer] h3_index A valid H3 index.
+    # @param [Integer] child_resoluton The desired resolution of the child hexagons.
+    #
+    # @example Derive maximum number of child hexagons.
+    #    H3.max_h3_to_children_size(613196570357137407, 10)
+    #    49
+    #
+    # @return [Integer] Maximum number of child hexagons possible at given resolution.
+    attach_function :max_h3_to_children_size, :maxH3ToChildrenSize, [ :h3_index, :int ], :int
+
+    # Derive child hexagons contained within the hexagon at the given H3 index.
+    #
+    # @param [Integer] h3_index A valid H3 index.
+    # @param [Integer] child_resolution The desired resolution of hexagons returned.
+    #
+    # @example Find the child hexagons for a H3 index.
+    #   H3.h3_to_children(613196570357137407, 9)
+    #   [
+    #     617700169982672895, 617700169982935039, 617700169983197183, 617700169983459327,
+    #     617700169983721471, 617700169983983615, 617700169984245759
+    #   ]
+    #
+    # @return [Array<Integer>] H3 indexes of child hexagons.
+    def h3_to_children(h3_index, child_resolution)
+      max_children = max_h3_to_children_size(h3_index, child_resolution)
+      h3_children = FFI::MemoryPointer.new(H3_INDEX, max_children)
+      Bindings::Private.h3_to_children(h3_index, child_resolution, h3_children)
+      h3_children.read_array_of_ulong_long(max_children).reject(&:zero?)
+    end
+
+    # Find the maximum uncompacted size of the given set of H3 indexes.
+    #
+    # @param [Array<Integer>] compacted_set An array of valid H3 indexes.
+    # @param [Integer] resolution The desired resolution to uncompact to.
+    #
+    # @example Find the maximum uncompacted size of the given set.
+    #   h3_set = [
+    #     617700440093229055, 617700440092704767, 617700440100569087, 617700440013012991,
+    #     617700440013275135, 617700440092180479, 617700440091656191, 617700440092966911,
+    #     617700440100831231, 617700440100044799, 617700440101617663, 617700440081956863,
+    #     613196840447246335
+    #   ]
+    #   H3.max_uncompact_size(h3_set, 10)
+    #   133
+    #
+    # @raise [ArgumentError] Given resolution is invalid for h3_set.
+    #
+    # @return [Integer] Maximum size of uncompacted set.
+    def max_uncompact_size(compacted_set, resolution)
+      compacted_set = compacted_set.uniq
+      FFI::MemoryPointer.new(H3_INDEX, compacted_set.size) do |hexagons_ptr|
+        hexagons_ptr.write_array_of_ulong_long(compacted_set)
+        size = Bindings::Private.max_uncompact_size(hexagons_ptr, compacted_set.size, resolution)
+        raise(ArgumentError, "Couldn't estimate size. Invalid resolution?") if size < 0
+        return size
+      end
+    end
+
+    # Compact a set of H3 indexes as best as possible.
+    #
+    # In the case where the set cannot be compacted, the set is returned unchanged.
+    #
+    # @param [Array<Integer>] h3_set An array of valid H3 indexes.
+    #
+    # @example Compact the given set.
+    #   h3_set = [
+    #     617700440073043967, 617700440072781823, 617700440073568255, 617700440093229055,
+    #     617700440092704767, 617700440100569087, 617700440074092543, 617700440073830399,
+    #     617700440074354687, 617700440073306111, 617700440013012991, 617700440013275135,
+    #     617700440092180479, 617700440091656191, 617700440092966911, 617700440100831231,
+    #     617700440100044799, 617700440101617663, 617700440081956863
+    #   ]
+    #   H3.compact(h3_set)
+    #   [
+    #     617700440093229055, 617700440092704767, 617700440100569087, 617700440013012991,
+    #     617700440013275135, 617700440092180479, 617700440091656191, 617700440092966911,
+    #     617700440100831231, 617700440100044799, 617700440101617663, 617700440081956863,
+    #     613196840447246335
+    #   ]
+    #
+    # @raise [RuntimeError] Couldn't attempt to compact given H3 indexes.
+    #
+    # @return [Array<Integer>] Compacted set of H3 indexes.
+    def compact(h3_set)
+      h3_set = h3_set.uniq
+      failure = false
+      out = FFI::MemoryPointer.new(H3_INDEX, h3_set.size)
+      FFI::MemoryPointer.new(H3_INDEX, h3_set.size) do |hexagons_ptr|
+        hexagons_ptr.write_array_of_ulong_long(h3_set)
+        failure = Bindings::Private.compact(hexagons_ptr, out, h3_set.size)
+      end
+      
+      raise "Couldn't compact given indexes" if failure
+      out.read_array_of_ulong_long(h3_set.size).reject(&:zero?)
+    end
+
+    # Uncompact a set of H3 indexes to the given resolution.
+    #
+    # @param [Array<Integer>] compacted_set An array of valid H3 indexes.
+    # @param [Integer] resolution The desired resolution to uncompact to.
+    #
+    # @example Compact the given set.
+    #   h3_set = [
+    #     617700440093229055, 617700440092704767, 617700440100569087, 617700440013012991,
+    #     617700440013275135, 617700440092180479, 617700440091656191, 617700440092966911,
+    #     617700440100831231, 617700440100044799, 617700440101617663, 617700440081956863,
+    #     613196840447246335
+    #   ]
+    #   H3.uncompact(h3_set)
+    #   [
+    #     617700440093229055, 617700440092704767, 617700440100569087, 617700440013012991,
+    #     617700440013275135, 617700440092180479, 617700440091656191, 617700440092966911,
+    #     617700440100831231, 617700440100044799, 617700440101617663, 617700440081956863,
+    #     617700440072781823, 617700440073043967, 617700440073306111, 617700440073568255,
+    #     617700440073830399, 617700440074092543, 617700440074354687
+    #   ]
+    #
+    # @raise [RuntimeError] Couldn't attempt to umcompact H3 indexes.
+    #
+    # @return [Array<Integer>] Uncompacted set of H3 indexes.
+    def uncompact(compacted_set, resolution)
+      max_size = max_uncompact_size(compacted_set, resolution)
+
+      failure = false
+      out = FFI::MemoryPointer.new(H3_INDEX, max_size)
+      FFI::MemoryPointer.new(H3_INDEX, compacted_set.size) do |hexagons_ptr|
+        hexagons_ptr.write_array_of_ulong_long(compacted_set)
+        failure = Bindings::Private.uncompact(hexagons_ptr, compacted_set.size, out, max_size, resolution)
+      end
+      
+      raise "Couldn't uncompact given indexes" if failure
+      out.read_array_of_ulong_long(max_size).reject(&:zero?)
+    end
+  end
+end