Module: H3::Indexing

Extended by:
Bindings::Base
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

Methods included from Bindings::Base

extended

Instance Method Details

#from_geo_coordinates(coords, resolution) ⇒ Integer

Derive H3 index for the given set of coordinates.

Examples:

Derive the H3 index for the given coordinates.

H3.from_geo_coordinates([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.



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

def from_geo_coordinates(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 = GeoCoord.new
  coords[:lat] = degs_to_rads(lat)
  coords[:lon] = degs_to_rads(lon)
  Bindings::Private.geo_to_h3(coords, resolution)
end

#geo_to_h3(coords, resolution) ⇒ Object

Deprecated.

Please use #from_geo_coordinates instead.



39
40
41
 
# File 'lib/h3/indexing.rb', line 39

def geo_to_h3(coords, resolution)
  from_geo_coordinates(coords, resolution)
end

#h3_to_geo(h3_index) ⇒ Object

Deprecated.

Please use #to_geo_coordinates instead.



62
63
64
 
# File 'lib/h3/indexing.rb', line 62

def h3_to_geo(h3_index)
  to_geo_coordinates(h3_index)
end

#h3_to_geo_boundary(h3_index) ⇒ Object

Deprecated.

Please use #to_boundary instead.



94
95
96
 
# File 'lib/h3/indexing.rb', line 94

def h3_to_geo_boundary(h3_index)
  to_boundary(h3_index)
end

#to_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.to_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.



85
86
87
88
89
90
91
 
# File 'lib/h3/indexing.rb', line 85

def to_boundary(h3_index)
  geo_boundary = GeoBoundary.new
  Bindings::Private.h3_to_geo_boundary(h3_index, geo_boundary)
  geo_boundary[:verts].take(geo_boundary[:num_verts]).map do |d|
    [rads_to_degs(d[:lat]), rads_to_degs(d[:lon])]
  end
end

#to_geo_coordinates(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.to_geo_coordinates(617439284584775679)
[52.245519061399506, -1.7363137757391423]

Parameters:

  • h3_index (Integer) —

    A valid H3 index.

Returns:

  • (Array<Integer>) —

    A coordinate pair.



55
56
57
58
59
 
# File 'lib/h3/indexing.rb', line 55

def to_geo_coordinates(h3_index)
  coords = GeoCoord.new
  Bindings::Private.h3_to_geo(h3_index, coords)
  [rads_to_degs(coords[:lat]), rads_to_degs(coords[:lon])]
end