Module: H3::Indexing

Included in:
H3
Defined in:
lib/h3/indexing.rb

Overview

Indexing functions.

Coordinates are returned in degrees, in the form

[latitude, longitude]

See Also:

Instance Method Summary collapse

Instance Method Details

#geo_to_h3(coords, resolution) ⇒ Integer

Derive H3 index for the given set of coordinates.

Examples:

Derive the H3 index for the given coordinates.

H3.geo_to_h3([52.24630137198303, -1.7358398437499998], 9)
617439284584775679

Parameters:

  • coords (Array<Integer>) —

    A coordinate pair.

  • resolution (Integer) —

    The desired resolution of the H3 index.

Returns:

  • (Integer) —

    H3 index.

Raises:

  • (ArgumentError) —

    If coordinates are invalid.



22
23
24
25
26
27
28
29
30
31
32
33
34
35
 
# File 'lib/h3/indexing.rb', line 22

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

#h3_to_geo(h3_index) ⇒ Array<Integer>

Derive coordinates for a given H3 index.

The coordinates map to the centre of the hexagon at the given index.

Examples:

Derive the central coordinates for the given H3 index.

H3.h3_to_geo(617439284584775679)
[52.245519061399506, -1.7363137757391423]

Parameters:

  • h3_index (Integer) —

    A valid H3 index.

Returns:

  • (Array<Integer>) —

    A coordinate pair.



48
49
50
51
52
 
# File 'lib/h3/indexing.rb', line 48

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

#h3_to_geo_boundary(h3_index) ⇒ Array<Array<Integer>>

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.

Examples:

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]
]

Parameters:

  • h3_index (Integer) —

    A valid H3 index.

Returns:

  • (Array<Array<Integer>>) —

    An array of six coordinate pairs.



72
73
74
75
76
77
78
 
# File 'lib/h3/indexing.rb', line 72

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