h3 3.2.0

data/lib/h3/traversal.rb

@@ -0,0 +1,287 @@
+module H3
+  # Grid traversal functions
+  #
+  # @see https://uber.github.io/h3/#/documentation/api-reference/traversal
+  module Traversal
+    extend H3::Bindings::Base
+
+    # @!method max_kring_size(k)
+    #
+    # Derive the maximum k-ring size for distance k.
+    #
+    # @param [Integer] k K value.
+    #
+    # @example Derive the maximum k-ring size for k=5
+    #   H3.max_kring_size(5)
+    #   91
+    #
+    # @return [Integer] Maximum k-ring size.
+    attach_function :max_kring_size, :maxKringSize, [ :int ], :int
+
+    # @!method h3_distance(origin, h3_index)
+    #
+    # Derive the distance between two H3 indexes.
+    #
+    # @param [Integer] origin Origin H3 index
+    # @param [Integer] h3_index H3 index
+    #
+    # @example Derive the distance between two H3 indexes.
+    #   H3.h3_distance(617700169983721471, 617700169959866367)
+    #   5
+    #
+    # @return [Integer] Distance between indexes.
+    attach_function :h3_distance, :h3Distance, [ :h3_index, :h3_index], :int
+
+    # Derives H3 indexes within k distance of the origin H3 index.
+    #
+    # Similar to {k_ring}, except that an error is raised when one of the indexes
+    # returned is a pentagon or is in the pentagon distortion area.
+    #
+    # k-ring 0 is defined as the origin index, k-ring 1 is defined as k-ring 0
+    # and all neighboring indexes, and so on.
+    #
+    # Output is inserted into the array in order of increasing distance from the origin.
+    #
+    # @param [Integer] origin Origin H3 index
+    # @param [Integer] k K distance.
+    #
+    # @example Derive the hex range for a given H3 index with k of 0.
+    #   H3.hex_range(617700169983721471, 0)
+    #   [617700169983721471]
+    #
+    # @example Derive the hex range for a given H3 index with k of 1.
+    #   H3.hex_range(617700169983721471, 1)
+    #   [
+    #     617700169983721471, 617700170047946751, 617700169984245759,
+    #     617700169982672895, 617700169983983615, 617700170044276735,
+    #     617700170044014591
+    #   ]
+    #
+    # @raise [ArgumentError] Raised if the range contains a pentagon.
+    #
+    # @return [Array<Integer>] Array of H3 indexes within the k-range.
+    def hex_range(origin, k)
+      max_hexagons = max_kring_size(k)
+      hexagons = FFI::MemoryPointer.new(:ulong_long, max_hexagons)
+      pentagonal_distortion = Bindings::Private.hex_range(origin, k, hexagons)
+      raise(ArgumentError, "Specified hexagon range contains a pentagon") if pentagonal_distortion
+      hexagons.read_array_of_ulong_long(max_hexagons).reject(&:zero?)
+    end
+
+    # Derives H3 indexes within k distance of the origin H3 index.
+    #
+    # k-ring 0 is defined as the origin index, k-ring 1 is defined as k-ring 0
+    # and all neighboring indexes, and so on.
+    #
+    # @param [Integer] origin Origin H3 index
+    # @param [Integer] k K distance.
+    #
+    # @example Derive the k-ring for a given H3 index with k of 0.
+    #   H3.k_ring(617700169983721471, 0)
+    #   [617700169983721471]
+    #
+    # @example Derive the k-ring for a given H3 index with k of 1.
+    #   H3.k_ring(617700169983721471, 1)
+    #   [
+    #     617700169983721471, 617700170047946751, 617700169984245759,
+    #     617700169982672895, 617700169983983615, 617700170044276735,
+    #     617700170044014591
+    #   ]
+    #
+    # @return [Array<Integer>] Array of H3 indexes within the k-range.
+    def k_ring(origin, k)
+      max_hexagons = max_kring_size(k)
+      hexagons = FFI::MemoryPointer.new(:ulong_long, max_hexagons)
+      Bindings::Private.k_ring(origin, k, hexagons)
+      hexagons.read_array_of_ulong_long(max_hexagons).reject(&:zero?)
+    end
+
+    # Derives the hollow hexagonal ring centered at origin with sides of length k.
+    #
+    # An error is raised when one of the indexes returned is a pentagon or is
+    # in the pentagon distortion area.
+    #
+    # @param [Integer] origin Origin H3 index.
+    # @param [Integer] k K distance.
+    #
+    # @example Derive the hex ring for the H3 index at k = 1
+    #   H3.hex_ring(617700169983721471, 1)
+    #   [
+    #     617700170044014591, 617700170047946751, 617700169984245759,
+    #     617700169982672895, 617700169983983615, 617700170044276735
+    #   ]
+    #
+    # @raise [ArgumentError] Raised if the hex ring contains a pentagon.
+    #
+    # @return [Array<Integer>] Array of H3 indexes within the hex ring.
+    def hex_ring(origin, k)
+      max_hexagons = max_hex_ring_size(k)
+      hexagons = FFI::MemoryPointer.new(:ulong_long, max_hexagons)
+      pentagonal_distortion = Bindings::Private.hex_ring(origin, k, hexagons)
+      raise(ArgumentError, "The hex ring contains a pentagon") if pentagonal_distortion
+      hexagons.read_array_of_ulong_long(max_hexagons).reject(&:zero?)
+    end
+
+    # Derive the maximum hex ring size for a given distance k.
+    #
+    # NOTE: This method is not part of the H3 API and is added to this binding for convenience.
+    #
+    # @param [Integer] k K distance.
+    #
+    # @example Derive maximum hex ring size for k distance 6.
+    #   H3.max_hex_ring_size(6)
+    #   36
+    #
+    # @return [Integer] Maximum hex ring size.
+    def max_hex_ring_size(k)
+      k.zero? ? 1 : 6 * k
+    end
+
+    # Derives H3 indexes within k distance for each H3 index in the set.
+    #
+    # @param [Array<Integer>] h3_set Set of H3 indexes
+    # @param [Integer] k K distance.
+    # @param [Boolean] grouped Whether to group the output. Default true.
+    #
+    # @example Derive the hex ranges for a given H3 set with k of 0.
+    #   H3.hex_ranges([617700169983721471, 617700169982672895], 1)
+    #   {
+    #     617700169983721471 => [
+    #       [617700169983721471],
+    #       [
+    #         617700170047946751, 617700169984245759, 617700169982672895,
+    #         617700169983983615, 617700170044276735, 617700170044014591
+    #       ]
+    #     ],
+    #     617700169982672895 = > [
+    #       [617700169982672895],
+    #       [
+    #         617700169984245759, 617700169983197183, 617700169983459327,
+    #         617700169982935039, 617700169983983615, 617700169983721471
+    #       ]
+    #     ]
+    #   }
+    #
+    # @example Derive the hex ranges for a given H3 set with k of 0 ungrouped.
+    #   H3.hex_ranges([617700169983721471, 617700169982672895], 1, grouped: false)
+    #   [
+    #     617700169983721471, 617700170047946751, 617700169984245759,
+    #     617700169982672895, 617700169983983615, 617700170044276735,
+    #     617700170044014591, 617700169982672895, 617700169984245759,
+    #     617700169983197183, 617700169983459327, 617700169982935039,
+    #     617700169983983615, 617700169983721471
+    #   ]
+    #
+    # @raise [ArgumentError] Raised if any of the ranges contains a pentagon.
+    #
+    # @see #hex_range
+    #
+    # @return [Hash] Hash of H3 index keys, with array values grouped by k-ring.
+    def hex_ranges(h3_set, k, grouped: true)
+      h3_range_indexes = hex_ranges_ungrouped(h3_set, k)
+      return h3_range_indexes unless grouped
+      out = {}
+      h3_range_indexes.each_slice(max_kring_size(k)).each do |indexes|
+        h3_index = indexes.first
+
+        out[h3_index] = 0.upto(k).map do |j|
+          start  = j == 0 ? 0 : max_kring_size(j-1)
+          length = max_hex_ring_size(j)
+          indexes.slice(start, length)
+        end
+      end
+      out
+    end
+
+    # Derives the hex range for the given origin at k distance, sub-grouped by distance.
+    #
+    # @param [Integer] origin Origin H3 index.
+    # @param [Integer] k K distance.
+    #
+    # @example Derive hex range at distance 2
+    #   H3.hex_range_distances(617700169983721471, 2)
+    #   {
+    #     0 => [617700169983721471],
+    #     1 = >[
+    #       617700170047946751, 617700169984245759, 617700169982672895,
+    #       617700169983983615, 617700170044276735, 617700170044014591
+    #     ],
+    #     2 => [
+    #       617700170048995327, 617700170047684607, 617700170048471039,
+    #       617700169988177919, 617700169983197183, 617700169983459327,
+    #       617700169982935039, 617700175096053759, 617700175097102335,
+    #       617700170043752447, 617700170043490303, 617700170045063167
+    #     ]
+    #   }
+    #
+    # @raise [ArgumentError] Raised when the hex range contains a pentagon.
+    #
+    # @return [Hash] Hex range grouped by distance.
+    def hex_range_distances(origin, k)
+      max_out_size = max_kring_size(k)
+      out = FFI::MemoryPointer.new(H3_INDEX, max_out_size)
+      distances = FFI::MemoryPointer.new(:int, max_out_size)
+      pentagonal_distortion = Bindings::Private.hex_range_distances(origin, k, out, distances)
+      raise(ArgumentError, "Specified hexagon range contains a pentagon") if pentagonal_distortion
+
+      hexagons = out.read_array_of_ulong_long(max_out_size)
+      distances = distances.read_array_of_int(max_out_size)
+
+      Hash[
+        distances.zip(hexagons).group_by(&:first).map { |d, hs| [d, hs.map(&:last)] }
+      ]
+    end
+
+    # Derives the k-ring for the given origin at k distance, sub-grouped by distance.
+    #
+    # @param [Integer] origin Origin H3 index.
+    # @param [Integer] k K distance.
+    #
+    # @example Derive k-ring at distance 2
+    #   H3.k_ring_distances(617700169983721471, 2)
+    #   {
+    #     0 => [617700169983721471],
+    #     1 = >[
+    #       617700170047946751, 617700169984245759, 617700169982672895,
+    #       617700169983983615, 617700170044276735, 617700170044014591
+    #     ],
+    #     2 => [
+    #       617700170048995327, 617700170047684607, 617700170048471039,
+    #       617700169988177919, 617700169983197183, 617700169983459327,
+    #       617700169982935039, 617700175096053759, 617700175097102335,
+    #       617700170043752447, 617700170043490303, 617700170045063167
+    #     ]
+    #   }
+    #
+    # @return [Hash] Hash of k-ring distances grouped by distance.
+    def k_ring_distances(origin, k)
+      max_out_size = max_kring_size(k)
+      out = FFI::MemoryPointer.new(H3_INDEX, max_out_size)
+      distances = FFI::MemoryPointer.new(:int, max_out_size)
+      Bindings::Private.k_ring_distances(origin, k, out, distances)
+
+      hexagons = out.read_array_of_ulong_long(max_out_size)
+      distances = distances.read_array_of_int(max_out_size)
+
+      Hash[
+        distances.zip(hexagons).group_by(&:first).map { |d, hs| [d, hs.map(&:last)] }
+      ]
+    end
+
+    private
+
+    def hex_ranges_ungrouped(h3_set, k)
+      h3_set = h3_set.uniq
+      max_out_size = h3_set.size * max_kring_size(k)
+      out = FFI::MemoryPointer.new(H3_INDEX, max_out_size)
+      pentagonal_distortion = false
+      FFI::MemoryPointer.new(H3_INDEX, h3_set.size) do |h3_set_ptr|
+        h3_set_ptr.write_array_of_ulong_long(h3_set)
+        pentagonal_distortion = Bindings::Private.hex_ranges(h3_set_ptr, h3_set.size, k, out)
+      end
+      raise(ArgumentError, "One of the specified hexagon ranges contains a pentagon") if pentagonal_distortion
+
+      out.read_array_of_ulong_long(max_out_size)
+    end
+  end
+end

data/lib/h3/unidirectional_edges.rb

@@ -0,0 +1,146 @@
+module H3
+  # Unidirectional edge functions
+  # 
+  # @see https://uber.github.io/h3/#/documentation/api-reference/unidirectional-edges
+  module UnidirectionalEdges
+    extend H3::Bindings::Base
+
+    # @!method h3_indexes_neighbors?(origin, destination)
+    #
+    # Determine whether two H3 indexes are neighbors.
+    #
+    # @param [Integer] origin Origin H3 index
+    # @param [Integer] destination Destination H3 index
+    #
+    # @example Check two H3 indexes
+    #   H3.h3_indexes_neighbors?(617700169958293503, 617700169958031359)
+    #   true
+    #
+    # @return [Boolean] True if indexes are neighbors
+    attach_function :h3_indexes_neighbors, :h3IndexesAreNeighbors, [ :h3_index, :h3_index ], :bool
+
+    # @!method h3_unidirectional_edge_valid?(h3_index)
+    #
+    # Determine whether the given H3 index represents an edge.
+    #
+    # @param [Integer] h3_index H3 index
+    #
+    # @example Check if H3 index is a valid unidirectional edge.
+    #   H3.h3_unidirectional_edge_valid?(1266218516299644927)
+    #   true
+    #
+    # @return [Boolean] True if H3 index is a valid unidirectional edge
+    attach_function :h3_unidirectional_edge_valid,
+                :h3UnidirectionalEdgeIsValid,
+                [ :h3_index ],
+                :bool
+
+    # @!method h3_unidirectional_edge(origin, destination)
+    #
+    # Derives the H3 index of the edge from the given H3 indexes.
+    #
+    # @param [Integer] origin H3 index
+    # @param [Integer] destination H3 index
+    #
+    # @example Derive the H3 edge index between two H3 indexes
+    #   H3.h3_unidirectional_edge(617700169958293503, 617700169958031359)
+    #   1626506486489284607
+    #
+    # @return [Integer] H3 edge index
+    attach_function :h3_unidirectional_edge,
+                    :getH3UnidirectionalEdge,
+                    [ :h3_index, :h3_index ],
+                    :h3_index
+
+    # @!method destination_from_unidirectional_edge(edge)
+    #
+    # Derive destination H3 index from edge.
+    #
+    # @param [Integer] edge H3 edge index
+    #
+    # @example Get destination index from edge
+    #   H3.destination_from_unidirectional_edge(1266218516299644927)
+    #   617700169961177087
+    #
+    # @return [Integer] H3 index
+    attach_function :destination_from_unidirectional_edge,
+                    :getDestinationH3IndexFromUnidirectionalEdge,
+                    [ :h3_index ],
+                    :h3_index
+
+    # @!method origin_from_unidirectional_edge(edge)
+    #
+    # Derive origin H3 index from edge.
+    #
+    # @param [Integer] edge H3 edge index
+    #
+    # @example Get origin index from edge
+    #   H3.origin_from_unidirectional_edge(1266218516299644927)
+    #   617700169958293503
+    #
+    # @return [Integer] H3 index
+    attach_function :origin_from_unidirectional_edge,
+                    :getOriginH3IndexFromUnidirectionalEdge,
+                    [ :h3_index ],
+                    :h3_index
+
+    # Derive origin and destination H3 indexes from edge.
+    #
+    # Returned in the form
+    #
+    #   [origin, destination]
+    #
+    # @param [Integer] edge H3 edge index
+    #
+    # @example Get origin and destination indexes from edge
+    #   H3.h3_indexes_from_unidirectional_edge(1266218516299644927)
+    #   [617700169958293503, 617700169961177087]
+    #
+    # @return [Array<Integer>] H3 index array.
+    def h3_indexes_from_unidirectional_edge(edge)
+      max_hexagons = 2
+      origin_destination = FFI::MemoryPointer.new(:ulong_long, max_hexagons)
+      Bindings::Private.h3_indexes_from_unidirectional_edge(edge, origin_destination)
+      origin_destination.read_array_of_ulong_long(max_hexagons).reject(&:zero?)
+    end
+
+    # Derive unidirectional edges for a H3 index.
+    #
+    # @param [Integer] origin H3 index
+    #
+    # @example Get unidirectional indexes from hexagon
+    #   H3.h3_unidirectional_edges_from_hexagon(1266218516299644927)
+    #   [
+    #     1266218516299644927, 1338276110337572863, 1410333704375500799,
+    #     1482391298413428735, 1554448892451356671, 1626506486489284607
+    #   ]
+    #
+    # @return [Array<Integer>] H3 index array.
+    def h3_unidirectional_edges_from_hexagon(origin)
+      max_edges = 6
+      edges = FFI::MemoryPointer.new(:ulong_long, max_edges)
+      Bindings::Private.h3_unidirectional_edges_from_hexagon(origin, edges)
+      edges.read_array_of_ulong_long(max_edges).reject(&:zero?)
+    end
+
+    # Derive coordinates for edge boundary.
+    #
+    # @param [Integer] edge H3 edge index
+    #
+    # @example 
+    #   H3.h3_unidirectional_edge_boundary(1266218516299644927)
+    #   [
+    #     [37.77820687262237, -122.41971895414808],
+    #     [37.77652420699321, -122.42079024541876]
+    #   ]
+    #
+    # @return [Array<Array<Float>>] Edge boundary coordinates for a hexagon
+    def h3_unidirectional_edge_boundary(edge)
+      geo_boundary = Bindings::Structs::GeoBoundary.new
+      Bindings::Private.h3_unidirectional_edge_boundary(edge, 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/version.rb

@@ -0,0 +1,3 @@
+module H3
+  VERSION = "3.2.0"
+end

data/spec/geo_json_spec.rb

@@ -0,0 +1,118 @@
+RSpec.describe H3 do
+  # http://geojson.io is helpful for setting up test fixtures
+  describe ".geo_json_to_coordinates" do
+    let(:input) do
+      File.read(File.join(File.dirname(__FILE__), "support/fixtures/banbury.json"))
+    end
+    let(:coordinates) do
+      [
+        [
+          [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]
+        ]
+      ]
+    end
+
+    subject(:geo_json_to_coordinates) { H3.geo_json_to_coordinates(input) }
+
+    it { is_expected.to eq coordinates }
+
+    context "when given a feature" do
+      let(:input) do
+        File.read(File.join(File.dirname(__FILE__), "support/fixtures/banbury_feature.json"))
+      end
+
+      it { is_expected.to eq coordinates }
+    end
+
+    context "when given a feature collection" do
+      let(:input) do
+        File.read(File.join(File.dirname(__FILE__), "support/fixtures/banbury_feature_collection.json"))
+      end
+
+      it { is_expected.to eq coordinates }
+    end
+
+    context "when given bad input" do
+      let(:input) { "blah" }
+
+      it "raises an error" do
+        expect { geo_json_to_coordinates }.to raise_error(ArgumentError)
+      end
+    end
+  end
+
+  describe ".coordinates_to_geo_json" do
+    let(:input) do
+      [
+        [
+          [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]
+        ]
+      ]
+    end
+    let(:geojson) do
+      File.read(File.join(File.dirname(__FILE__), "support/fixtures/banbury.json"))
+    end
+
+    subject(:coordinates_to_geo_json) { H3.coordinates_to_geo_json(input) }
+
+    it { is_expected.to eq geojson }
+
+    context "when given bad input" do
+      let(:input) { "blah" }
+
+      it "raises an error" do
+        expect { coordinates_to_geo_json }.to raise_error(ArgumentError)
+      end
+    end
+
+    context "when given nested bad input" do
+      let(:input) { [[],[[[[]]]]] }
+
+      it "raises an error" do
+        expect { coordinates_to_geo_json }.to raise_error(ArgumentError)
+      end
+    end
+  end
+end