Module: H3::Hierarchy

Extended by:
Bindings::Base
Included in:
H3
Defined in:
lib/h3/hierarchy.rb

Overview

Hierarchical grid functions.

See Also:

Instance Method Summary collapse

Methods included from Bindings::Base

attach_predicate_function, extended

Instance Method Details

#center_child(h3_index, child_resolution) ⇒ Integer

Returns the center child (finer) index contained by the given index at the given resolution.

Examples:

Find center child hexagon.

H3.center_child(613196570357137407, 10)
622203769609814015

Parameters:

  • h3_index (Integer) —

    A valid H3 index.

  • child_resoluton (Integer) —

    The desired resolution of the center child hexagon.

Returns:

  • (Integer) —

    H3 index of center child hexagon.



49
 
# File 'lib/h3/hierarchy.rb', line 49

attach_function :center_child, :h3ToCenterChild, [:h3_index, Resolution], :h3_index

#children(h3_index, child_resolution) ⇒ Array<Integer>

Derive child hexagons contained within the hexagon at the given H3 index.

Examples:

Find the child hexagons for a H3 index.

H3.children(613196570357137407, 9)
[
  617700169982672895, 617700169982935039, 617700169983197183, 617700169983459327,
  617700169983721471, 617700169983983615, 617700169984245759
]

Parameters:

  • h3_index (Integer) —

    A valid H3 index.

  • child_resolution (Integer) —

    The desired resolution of hexagons returned.

Returns:

  • (Array<Integer>) —

    H3 indexes of child hexagons.



64
65
66
67
68
69
 
# File 'lib/h3/hierarchy.rb', line 64

def children(h3_index, child_resolution)
  max_children = max_children(h3_index, child_resolution)
  out = H3Indexes.of_size(max_children)
  Bindings::Private.h3_to_children(h3_index, child_resolution, out)
  out.read
end

#compact(h3_set) ⇒ Array<Integer>

Compact a set of H3 indexes as best as possible.

In the case where the set cannot be compacted, the set is returned unchanged.

Examples:

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
]

Parameters:

  • h3_set (Array<Integer>) —

    An array of valid H3 indexes.

Returns:

  • (Array<Integer>) —

    Compacted set of H3 indexes.

Raises:

  • (RuntimeError) —

    Couldn’t attempt to compact given H3 indexes.



121
122
123
124
125
126
127
128
 
# File 'lib/h3/hierarchy.rb', line 121

def compact(h3_set)
  h3_set = H3Indexes.with_contents(h3_set)
  out = H3Indexes.of_size(h3_set.size)
  failure = Bindings::Private.compact(h3_set, out, out.size)

  raise "Couldn't compact given indexes" if failure
  out.read
end

#max_children(h3_index, child_resolution) ⇒ Integer

Derive maximum number of child hexagons possible at given resolution.

Examples:

Derive maximum number of child hexagons.

H3.max_children(613196570357137407, 10)
49

Parameters:

  • h3_index (Integer) —

    A valid H3 index.

  • child_resoluton (Integer) —

    The desired resolution of the child hexagons.

Returns:

  • (Integer) —

    Maximum number of child hexagons possible at given resolution.



34
 
# File 'lib/h3/hierarchy.rb', line 34

attach_function :max_children, :maxH3ToChildrenSize, [:h3_index, Resolution], :int

#max_uncompact_size(compacted_set, resolution) ⇒ Integer

Find the maximum uncompacted size of the given set of H3 indexes.

Examples:

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

Parameters:

  • compacted_set (Array<Integer>) —

    An array of valid H3 indexes.

  • resolution (Integer) —

    The desired resolution to uncompact to.

Returns:

  • (Integer) —

    Maximum size of uncompacted set.

Raises:

  • (ArgumentError) —

    Given resolution is invalid for h3_set.



89
90
91
92
93
94
 
# File 'lib/h3/hierarchy.rb', line 89

def max_uncompact_size(compacted_set, resolution)
  h3_set = H3Indexes.with_contents(compacted_set)
  size = Bindings::Private.max_uncompact_size(h3_set, compacted_set.size, resolution)
  raise(ArgumentError, "Couldn't estimate size. Invalid resolution?") if size.negative?
  size
end

#parent(h3_index, parent_resolution) ⇒ Integer

Derive the parent hexagon which contains the hexagon at the given H3 index.

Examples:

Find the parent hexagon for a H3 index.

H3.parent(613196570357137407, 6)
604189371209351167

Parameters:

  • h3_index (Integer) —

    A valid H3 index.

  • parent_resoluton (Integer) —

    The desired resolution of the parent hexagon.

Returns:

  • (Integer) —

    H3 index of parent hexagon.



20
 
# File 'lib/h3/hierarchy.rb', line 20

attach_function :parent, :h3ToParent, [:h3_index, Resolution], :h3_index

#uncompact(compacted_set, resolution) ⇒ Array<Integer>

Uncompact a set of H3 indexes to the given resolution.

Examples:

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
]

Parameters:

  • compacted_set (Array<Integer>) —

    An array of valid H3 indexes.

  • resolution (Integer) —

    The desired resolution to uncompact to.

Returns:

  • (Array<Integer>) —

    Uncompacted set of H3 indexes.

Raises:

  • (RuntimeError) —

    Couldn’t attempt to umcompact H3 indexes.



154
155
156
157
158
159
160
161
162
163
 
# File 'lib/h3/hierarchy.rb', line 154

def uncompact(compacted_set, resolution)
  max_size = max_uncompact_size(compacted_set, resolution)

  out = H3Indexes.of_size(max_size)
  h3_set = H3Indexes.with_contents(compacted_set)
  failure = Bindings::Private.uncompact(h3_set, compacted_set.size, out, max_size, resolution)

  raise "Couldn't uncompact given indexes" if failure
  out.read
end