h3 3.2.0

data/lib/h3/indexing.rb

@@ -0,0 +1,80 @@
+module H3
+  # Indexing functions.
+  #
+  # Coordinates are returned in degrees, in the form
+  #
+  #   [latitude, longitude]
+  #
+  # @see https://uber.github.io/h3/#/documentation/api-reference/indexing
+  module Indexing
+    # Derive H3 index for the given set of coordinates.
+    #
+    # @param [Array<Integer>] coords A coordinate pair.
+    # @param [Integer] resolution The desired resolution of the H3 index.
+    #
+    # @example Derive the H3 index for the given coordinates.
+    #   H3.geo_to_h3([52.24630137198303, -1.7358398437499998], 9)
+    #   617439284584775679
+    #
+    # @raise [ArgumentError] If coordinates are invalid.
+    #
+    # @return [Integer] H3 index.
+    def geo_to_h3(coords, resolution)
+      raise ArgumentError unless coords.is_a?(Array) && coords.count == 2
+
+      lat, lon = coords
+
+      if lat > 90 || lat < -90 || lon > 180 || lon < -180
+        raise(ArgumentError, "Invalid coordinates")
+      end
+
+      coords = Bindings::Structs::GeoCoord.new
+      coords[:lat] = degs_to_rads(lat)
+      coords[:lon] = degs_to_rads(lon)
+      Bindings::Private.geo_to_h3(coords, resolution)
+    end
+
+    # Derive coordinates for a given H3 index.
+    #
+    # The coordinates map to the centre of the hexagon at the given index.
+    #
+    # @param [Integer] h3_index A valid H3 index.
+    #
+    # @example Derive the central coordinates for the given H3 index.
+    #   H3.h3_to_geo(617439284584775679)
+    #   [52.245519061399506, -1.7363137757391423]
+    #
+    # @return [Array<Integer>] A coordinate pair.
+    def h3_to_geo(h3_index)
+      coords = Bindings::Structs::GeoCoord.new
+      Bindings::Private.h3_to_geo(h3_index, coords)
+      [rads_to_degs(coords[:lat]), rads_to_degs(coords[:lon])]
+    end
+
+    # Derive the geographical boundary as coordinates for a given H3 index.
+    #
+    # This will be a set of 6 coordinate pairs matching the vertexes of the
+    # hexagon represented by the given H3 index.
+    #
+    # If the H3 index is a pentagon, there will be only 5 coordinate pairs returned.
+    #
+    # @param [Integer] h3_index A valid H3 index.
+    #
+    # @example Derive the geographical boundary for the given H3 index.
+    #   H3.h3_to_geo_boundary(617439284584775679)
+    #   [
+    #     [52.247260929171055, -1.736809158397472], [52.24625850761068, -1.7389279144996015],
+    #     [52.244516619273476, -1.7384324668792375], [52.243777169245725, -1.7358184256304658],
+    #     [52.24477956752282, -1.7336997597088104], [52.246521439109415, -1.7341950448552204]
+    #   ]
+    #
+    # @return [Array<Array<Integer>>] An array of six coordinate pairs.
+    def h3_to_geo_boundary(h3_index)
+      geo_boundary = Bindings::Structs::GeoBoundary.new
+      Bindings::Private.h3_to_geo_boundary(h3_index, geo_boundary)
+      geo_boundary[:verts].take(geo_boundary[:num_verts] * 2).map do |d|
+        rads_to_degs(d)
+      end.each_slice(2).to_a
+    end
+  end
+end

data/lib/h3/inspection.rb

@@ -0,0 +1,105 @@
+module H3
+  # Index inspection functions.
+  #
+  # @see https://uber.github.io/h3/#/documentation/api-reference/inspection
+  module Inspection
+    extend H3::Bindings::Base
+
+    H3_TO_STR_BUF_SIZE = 32
+    private_constant :H3_TO_STR_BUF_SIZE
+
+    # @!method h3_resolution(h3_index)
+    #
+    # Derive the resolution of a given H3 index
+    #
+    # @param [Integer] h3_index A valid H3 index
+    #
+    # @example Derive the resolution of a H3 index
+    #   H3.h3_resolution(617700440100569087)
+    #   9
+    #
+    # @return [Integer] Resolution of H3 index
+    attach_function :h3_resolution, :h3GetResolution, [ :h3_index ], :int
+
+    # @!method h3_base_cell(h3_index)
+    #
+    # Derives the base cell number of the given H3 index
+    #
+    # @param [Integer] h3_index A valid H3 index
+    #
+    # @example Derive the base cell number of a H3 index
+    #   H3.h3_base_cell(617700440100569087)
+    #   20
+    #
+    # @return [Integer] Base cell number
+    attach_function :h3_base_cell, :h3GetBaseCell, [ :h3_index ], :int
+
+    # @!method string_to_h3(h3_string)
+    #
+    # Derives the H3 index for a given hexadecimal string representation.
+    #
+    # @param [String] h3_string A H3 index in hexadecimal form.
+    #
+    # @example Derive the H3 index from the given hexadecimal form.
+    #   H3.string_to_h3("8928308280fffff")
+    #   617700169958293503
+    #
+    # @return [Integer] H3 index
+    attach_function :string_to_h3, :stringToH3, [ :string ], :h3_index
+
+    # @!method h3_pentagon?(h3_index)
+    #
+    # Determine whether the given H3 index is a pentagon.
+    #
+    # @param [Integer] h3_index A valid H3 index.
+    #
+    # @example Check if H3 index is a pentagon
+    #   H3.h3_pentagon?(585961082523222015)
+    #   true
+    #
+    # @return [Boolean] True if the H3 index is a pentagon.
+    attach_function :h3_pentagon, :h3IsPentagon, [ :h3_index ], :bool
+
+    # @!method h3_res_class_3?(h3_index)
+    #
+    # Determine whether the given H3 index has a resolution with
+    # Class III orientation.
+    #
+    # @param [Integer] h3_index A valid H3 index.
+    #
+    # @example Check if H3 index has a class III resolution.
+    #   H3.h3_res_class_3?(599686042433355775)
+    #   true
+    #
+    # @return [Boolean] True if the H3 index has a class III resolution.
+    attach_function :h3_res_class_3, :h3IsResClassIII, [ :h3_index ], :bool
+
+    # @!method h3_valid?(h3_index)
+    #
+    # Determine whether the given H3 index is valid.
+    #
+    # @param [Integer] h3_index A H3 index.
+    #
+    # @example Check if H3 index is valid
+    #   H3.h3_valid?(599686042433355775)
+    #   true
+    #
+    # @return [Boolean] True if the H3 index is valid.
+    attach_function :h3_valid, :h3IsValid, [ :h3_index ], :bool
+
+    # Derives the hexadecimal string representation for a given H3 index.
+    #
+    # @param [Integer] h3_index A valid H3 index.
+    #
+    # @example Derive the given hexadecimal form for the H3 index
+    #   H3.h3_to_string(617700169958293503)
+    #   "89283470dcbffff"
+    #
+    # @return [String] H3 index in hexadecimal form.
+    def h3_to_string(h3_index)
+      h3_str = FFI::MemoryPointer.new(:char, H3_TO_STR_BUF_SIZE)
+      Bindings::Private.h3_to_string(h3_index, h3_str, H3_TO_STR_BUF_SIZE)
+      h3_str.read_string 
+    end
+  end
+end

data/lib/h3/miscellaneous.rb

@@ -0,0 +1,99 @@
+module H3
+  # Miscellaneous functions.
+  #
+  # @see https://uber.github.io/h3/#/documentation/api-reference/miscellaneous
+  module Miscellaneous
+    extend H3::Bindings::Base
+
+    # @!method degs_to_rads(degs)
+    #
+    # Convert a number expressed in degrees to its equivalent in radians.
+    #
+    # @param [Float] degs Value expressed in degrees.
+    #
+    # @example Convert degrees value to radians.
+    #   H3.degs_to_rads(19.61922082086965)
+    #   0.34242
+    #
+    # @return [Float] Value expressed in radians.
+    attach_function :degs_to_rads, :degsToRads, [ :double ], :double
+
+    # @!method edge_length_km(resolution)
+    #
+    # Derive the length of a hexagon edge in kilometres at the given resolution.
+    #
+    # @param [Integer] resolution Resolution.
+    #
+    # @example Derive length of edge in kilometres
+    #   H3.edge_length_km(3)
+    #   59.81085794
+    #
+    # @return [Float] Length of edge in kilometres
+    attach_function :edge_length_km, :edgeLengthKm, [ :int ], :double
+
+    # @!method edge_length_m(resolution)
+    #
+    # Derive the length of a hexagon edge in metres at the given resolution.
+    #
+    # @param [Integer] resolution Resolution.
+    #
+    # @example Derive length of edge in metres
+    #   H3.edge_length_m(6)
+    #   3229.482772
+    #
+    # @return [Float] Length of edge in metres
+    attach_function :edge_length_m, :edgeLengthM, [ :int ], :double
+
+    # @!method hex_area_km2(resolution)
+    #
+    # Average hexagon area in square kilometres at the given resolution.
+    #
+    # @param [Integer] resolution Resolution.
+    #
+    # @example Find the square kilometre size at resolution 5
+    #   H3.hex_area_km2(5)
+    #   252.9033645
+    #
+    # @return [Float] Average hexagon area in square kilometres.
+    attach_function :hex_area_km2, :hexAreaKm2, [ :int ], :double
+
+    # @!method hex_area_m2(resolution)
+    #
+    # Average hexagon area in square metres at the given resolution.
+    #
+    # @param [Integer] resolution Resolution.
+    #
+    # @example Find the square metre size at resolution 10
+    #   H3.hex_area_m2(10)
+    #   15047.5
+    #
+    # @return [Float] Average hexagon area in square metres.
+    attach_function :hex_area_m2, :hexAreaM2, [ :int ], :double
+
+    # @!method num_hexagons(resolution)
+    #
+    # Number of unique H3 indexes at the given resolution.
+    #
+    # @param [Integer] resolution Resolution.
+    #
+    # @example Find number of hexagons at resolution 6
+    #   H3.num_hexagons(6)
+    #   14117882
+    #
+    # @return [Integer] Number of unique hexagons
+    attach_function :num_hexagons, :numHexagons, [ :int ], :ulong_long
+
+    # @!method rads_to_degs(rads)
+    #
+    # Convert a number expressed in radians to its equivalent in degrees.
+    #
+    # @param [Float] rads Value expressed in radians.
+    #
+    # @example Convert radians value to degrees.
+    #   H3.rads_to_degs(0.34242)
+    #   19.61922082086965
+    #
+    # @return [Float] Value expressed in degrees.
+    attach_function :rads_to_degs, :radsToDegs, [ :double ], :double
+  end
+end

data/lib/h3/regions.rb

@@ -0,0 +1,239 @@
+module H3
+  # Region functions.
+  #
+  # @see https://uber.github.io/h3/#/documentation/api-reference/regions 
+  module Regions
+    extend H3::Bindings::Base
+
+    # Derive the maximum number of H3 indexes that could be returned from the input.
+    #
+    # @param [String, Array<Array<Array<Float>>>] geo_polygon Either a GeoJSON string or a coordinates nested array.
+    # @param [Integer] resolution Resolution.
+    #
+    # @example Derive maximum number of hexagons for given GeoJSON document.
+    #   geo_json = "{\"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.max_polyfill_size(geo_json, 9)
+    #   33391
+    #
+    # @example Derive maximum number of hexagons for a nested array of coordinates.
+    #   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.max_polyfill_size(coordinates, 9)
+    #   33391
+    #
+    # @return [Integer] Maximum number of hexagons needed to polyfill given area.
+    def max_polyfill_size(geo_polygon, resolution)
+      geo_polygon = geo_json_to_coordinates(geo_polygon) if geo_polygon.is_a?(String)
+      Bindings::Private.max_polyfill_size(build_polygon(geo_polygon), resolution)
+    end
+
+    # Derive a list of H3 indexes that fall within a given geo polygon structure.
+    #
+    # @param [String, Array<Array<Array<Float>>>] geo_polygon Either a GeoJSON string or a coordinates nested array.
+    # @param [Integer] resolution Resolution.
+    #
+    # @example Derive hexagons for given GeoJSON document.
+    #   geo_json = "{\"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.polyfill(geo_json, 5)
+    #   [
+    #     599424968551301119, 599424888020664319, 599424970698784767, 599424964256333823,
+    #     599424969625042943, 599425001837297663, 599425000763555839
+    #   ]
+    #
+    # @example Derive hexagons for a nested array of coordinates.
+    #   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.polyfill(coordinates, 5)
+    #   [
+    #     599424968551301119, 599424888020664319, 599424970698784767, 599424964256333823,
+    #     599424969625042943, 599425001837297663, 599425000763555839
+    #   ]
+    #
+    # @return [Array<Integer>] Hexagons needed to polyfill given area.
+    def polyfill(geo_polygon, resolution)
+      geo_polygon = geo_json_to_coordinates(geo_polygon) if geo_polygon.is_a?(String)
+      max_size = max_polyfill_size(geo_polygon, resolution)
+      out = FFI::MemoryPointer.new(H3_INDEX, max_size)
+      Bindings::Private.polyfill(build_polygon(geo_polygon), resolution, out)
+      out.read_array_of_ulong_long(max_size).reject(&:zero?)
+    end
+
+    # Derive a nested array of coordinates from a list of H3 indexes.
+    #
+    # @param [Array<Integer>] h3_indexes A list of H3 indexes.
+    #
+    # @example Get a set of coordinates from a given list of H3 indexes.
+    #   h3_indexes = [
+    #     599424968551301119, 599424888020664319, 599424970698784767,
+    #     599424964256333823, 599424969625042943, 599425001837297663,
+    #     599425000763555839
+    #   ]
+    #   H3.h3_set_to_linked_geo(h3_indexes)
+    #   [
+    #     [
+    #       [52.24425364171531, -1.6470570189756442], [52.19515282473624, -1.7508281227260887],
+    #       [52.10973325363767, -1.7265910686763437], [52.06042870859474, -1.8301115887419024],
+    #       [51.97490199314513, -1.8057974545517919], [51.9387204737266, -1.6783497689296265],
+    #       [51.853128001893175, -1.654344796003053], [51.81682604752331, -1.5274195136674955],
+    #       [51.866019925789956, -1.424329996292339], [51.829502535462176, -1.2977583914075301],
+    #       [51.87843896218677, -1.1946402363628545], [51.96394676922824, -1.21787542551618],
+    #       [52.01267958543637, -1.1145114691876956], [52.09808058649905, -1.1376655003242908],
+    #       [52.134791926560325, -1.26456988729442], [52.22012854584846, -1.2880298658365215],
+    #       [52.25672060485973, -1.4154623025177386], [52.20787927927604, -1.5192658757247421]
+    #     ]
+    #   ]
+    #
+    # @return [Array<Array<Array<Float>>>] Nested array of coordinates.
+    def h3_set_to_linked_geo(h3_indexes)
+      h3_indexes.uniq!
+      linked_geo_polygon = Bindings::Structs::LinkedGeoPolygon.new
+      FFI::MemoryPointer.new(H3_INDEX, h3_indexes.size) do |hexagons_ptr|
+        hexagons_ptr.write_array_of_ulong_long(h3_indexes)
+        Bindings::Private.h3_set_to_linked_geo(hexagons_ptr, h3_indexes.size, linked_geo_polygon)
+      end
+
+      extract_linked_geo_polygon(linked_geo_polygon).first
+    end
+
+    private
+
+    def extract_linked_geo_polygon(linked_geo_polygon)
+      return if linked_geo_polygon.null?
+
+      geo_polygons = [linked_geo_polygon]
+
+      until linked_geo_polygon[:next].null? do
+        geo_polygons << linked_geo_polygon[:next]
+        linked_geo_polygon = linked_geo_polygon[:next]
+      end
+
+      geo_polygons.map(&method(:extract_geo_polygon))
+    end
+
+    def extract_geo_polygon(geo_polygon)
+      extract_linked_geo_loop(geo_polygon[:first]) unless geo_polygon[:first].null?
+    end
+
+    def extract_linked_geo_loop(linked_geo_loop)
+      return if linked_geo_loop.null?
+
+      geo_loops = [linked_geo_loop]
+
+      until linked_geo_loop[:next].null? do
+        geo_loops << linked_geo_loop[:next]
+        linked_geo_loop = linked_geo_loop[:next]
+      end
+
+      geo_loops.map(&method(:extract_geo_loop))
+    end
+
+    def extract_geo_loop(geo_loop)
+      extract_linked_geo_coord(geo_loop[:first]) unless geo_loop[:first].null?
+    end
+
+    def extract_linked_geo_coord(linked_geo_coord)
+      return if linked_geo_coord.null?
+
+      geo_coords = [linked_geo_coord]
+
+      until linked_geo_coord[:next].null? do
+        geo_coords << linked_geo_coord[:next]
+        linked_geo_coord = linked_geo_coord[:next]
+      end
+
+      geo_coords.map(&method(:extract_geo_coord))
+    end
+
+    def extract_geo_coord(geo_coord)
+      [
+        rads_to_degs(geo_coord[:vertex][:lat]),
+        rads_to_degs(geo_coord[:vertex][:lon])
+      ]
+    end
+
+    def build_polygon(input)
+      outline, *holes = input
+      geo_polygon = Bindings::Structs::GeoPolygon.new
+      geo_polygon[:geofence] = build_geofence(outline)
+      len = holes.count
+      geo_polygon[:num_holes] = len
+      geofences = holes.map(&method(:build_geofence))
+      ptr = FFI::MemoryPointer.new(Bindings::Structs::GeoFence, len)
+      fence_structs = geofences.count.times.map do |i|
+        Bindings::Structs::GeoFence.new(ptr + i * Bindings::Structs::GeoFence.size())
+      end
+      geofences.each_with_index do |geofence, i|
+        fence_structs[i][:num_verts] = geofence[:num_verts]
+        fence_structs[i][:verts] = geofence[:verts]
+      end
+      geo_polygon[:holes] = ptr
+      geo_polygon
+    end
+
+    def build_geofence(input)
+      geo_fence = Bindings::Structs::GeoFence.new
+      len = input.count
+      geo_fence[:num_verts] = len
+      ptr = FFI::MemoryPointer.new(Bindings::Structs::GeoCoord, len)
+      coords = 0.upto(len).map do |i|
+        Bindings::Structs::GeoCoord.new(ptr + i * Bindings::Structs::GeoCoord.size)
+      end
+      input.each_with_index do |(lat, lon), i|
+        coords[i][:lat] = degs_to_rads(lat)
+        coords[i][:lon] = degs_to_rads(lon)
+      end
+      geo_fence[:verts] = ptr
+      geo_fence
+    end
+  end
+end