Module: H3::Traversal
Overview
Grid traversal functions
Instance Method Summary collapse
-
#distance(origin, h3_index) ⇒ Integer
Derive the distance between two H3 indexes.
-
#hex_range(origin, k) ⇒ Array<Integer>
Derives H3 indexes within k distance of the origin H3 index.
-
#hex_range_distances(origin, k) ⇒ Hash
Derives the hex range for the given origin at k distance, sub-grouped by distance.
-
#hex_ranges(h3_set, k, grouped: true) ⇒ Hash
Derives H3 indexes within k distance for each H3 index in the set.
-
#hex_ring(origin, k) ⇒ Array<Integer>
Derives the hollow hexagonal ring centered at origin with sides of length k.
-
#k_ring(origin, k) ⇒ Array<Integer>
Derives H3 indexes within k distance of the origin H3 index.
-
#k_ring_distances(origin, k) ⇒ Hash
Derives the k-ring for the given origin at k distance, sub-grouped by distance.
-
#line(origin, destination) ⇒ Array<Integer>
Derives the H3 indexes found in a line between an origin H3 index and a destination H3 index (inclusive of origin and destination).
-
#line_size(origin, destination) ⇒ Integer
Derive the number of hexagons present in a line between two H3 indexes.
-
#max_hex_ring_size(k) ⇒ Integer
Derive the maximum hex ring size for a given distance k.
-
#max_kring_size(k) ⇒ Integer
Derive the maximum k-ring size for distance k.
Methods included from Bindings::Base
attach_predicate_function, extended
Instance Method Details
#distance(origin, h3_index) ⇒ Integer
Derive the distance between two H3 indexes.
33 |
# File 'lib/h3/traversal.rb', line 33 attach_function :distance, :h3Distance, %i[h3_index h3_index], :k_distance |
#hex_range(origin, k) ⇒ Array<Integer>
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.
82 83 84 85 86 87 88 |
# File 'lib/h3/traversal.rb', line 82 def hex_range(origin, k) max_hexagons = max_kring_size(k) out = H3Indexes.of_size(max_hexagons) pentagonal_distortion = Bindings::Private.hex_range(origin, k, out) raise(ArgumentError, "Specified hexagon range contains a pentagon") if pentagonal_distortion out.read end |
#hex_range_distances(origin, k) ⇒ Hash
Derives the hex range for the given origin at k distance, sub-grouped by distance.
233 234 235 236 237 238 239 240 241 242 243 244 245 246 |
# File 'lib/h3/traversal.rb', line 233 def hex_range_distances(origin, k) max_out_size = max_kring_size(k) out = H3Indexes.of_size(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 distances = distances.read_array_of_int(max_out_size) Hash[ distances.zip(hexagons).group_by(&:first).map { |d, hs| [d, hs.map(&:last)] } ] end |
#hex_ranges(h3_set, k, grouped: true) ⇒ Hash
Derives H3 indexes within k distance for each H3 index in the set.
199 200 201 202 203 204 205 206 207 |
# File 'lib/h3/traversal.rb', line 199 def hex_ranges(h3_set, k, grouped: true) h3_range_indexes = hex_ranges_ungrouped(h3_set, k) return h3_range_indexes unless grouped h3_range_indexes.each_slice(max_kring_size(k)).each_with_object({}) do |indexes, out| h3_index = indexes.first out[h3_index] = k_rings_for_hex_range(indexes, k) end end |
#hex_ring(origin, k) ⇒ Array<Integer>
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.
136 137 138 139 140 141 142 |
# File 'lib/h3/traversal.rb', line 136 def hex_ring(origin, k) max_hexagons = max_hex_ring_size(k) out = H3Indexes.of_size(max_hexagons) pentagonal_distortion = Bindings::Private.hex_ring(origin, k, out) raise(ArgumentError, "The hex ring contains a pentagon") if pentagonal_distortion out.read end |
#k_ring(origin, k) ⇒ Array<Integer>
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.
111 112 113 114 115 116 |
# File 'lib/h3/traversal.rb', line 111 def k_ring(origin, k) max_hexagons = max_kring_size(k) out = H3Indexes.of_size(max_hexagons) Bindings::Private.k_ring(origin, k, out) out.read end |
#k_ring_distances(origin, k) ⇒ Hash
Derives the k-ring for the given origin at k distance, sub-grouped by distance.
270 271 272 273 274 275 276 277 278 279 280 281 282 |
# File 'lib/h3/traversal.rb', line 270 def k_ring_distances(origin, k) max_out_size = max_kring_size(k) out = H3Indexes.of_size(max_out_size) distances = FFI::MemoryPointer.new(:int, max_out_size) Bindings::Private.k_ring_distances(origin, k, out, distances) hexagons = out.read distances = distances.read_array_of_int(max_out_size) Hash[ distances.zip(hexagons).group_by(&:first).map { |d, hs| [d, hs.map(&:last)] } ] end |
#line(origin, destination) ⇒ Array<Integer>
Derives the H3 indexes found in a line between an origin H3 index and a destination H3 index (inclusive of origin and destination).
300 301 302 303 304 305 306 |
# File 'lib/h3/traversal.rb', line 300 def line(origin, destination) max_hexagons = line_size(origin, destination) hexagons = H3Indexes.of_size(max_hexagons) res = Bindings::Private.h3_line(origin, destination, hexagons) raise(ArgumentError, "Could not compute line") if res.negative? hexagons.read end |
#line_size(origin, destination) ⇒ Integer
Derive the number of hexagons present in a line between two H3 indexes.
This value is simply ‘h3_distance(origin, destination) + 1` when a line is computable.
Returns a negative number if a line cannot be computed e.g. a pentagon was encountered, or the hexagons are too far apart.
52 |
# File 'lib/h3/traversal.rb', line 52 attach_function :line_size, :h3LineSize, %i[h3_index h3_index], :int |
#max_hex_ring_size(k) ⇒ Integer
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.
155 156 157 |
# File 'lib/h3/traversal.rb', line 155 def max_hex_ring_size(k) k.zero? ? 1 : 6 * k end |
#max_kring_size(k) ⇒ Integer
Derive the maximum k-ring size for distance k.
19 |
# File 'lib/h3/traversal.rb', line 19 attach_function :max_kring_size, :maxKringSize, %i[k_distance], :int |