h3

package module
Version: v3.0.1+incompatible Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Jun 3, 2019 License: Apache-2.0 Imports: 5 Imported by: 10

README

Build Status Coverage Status License GoDoc H3 Version

H3-Go

This library provides Golang bindings for the H3 Core Library. For API reference, please see the H3 Documentation.

Usage

Installation

golang/dep
dep ensure -add github.com/uber/h3-go

Note: h3-go includes non-go directories that, by default, dep will prune. You can prevent this by including the following prune directive in your Gopkg.toml:

[prune]
	[[prune.project]]
		name = "github.com/uber/h3-go"
		non-go = false
		unused-packages = false
golang/cmd/go
go get github.com/uber/h3-go
Glide
glide install github.com/uber/h3-go

Quickstart

import "github.com/uber/h3-go"

func ExampleFromGeo() {
	geo := h3.GeoCoord{
		Latitude:  37.775938728915946,
		Longitude: -122.41795063018799,
	}
	resolution := 9
	fmt.Printf("%#x\n", h3.FromGeo(geo, resolution))
	// Output:
	// 0x8928308280fffff
}

Notes

API Differences

  • All GeoCoord structs return Latitude and Longitude as degrees, instead of radians.

Some superficial changes have been made relative to the H3 C core API in order to adhere to idiomatic Go styling. Most notable are the following:

  • H3 C API function prefixes of H3 have been dropped to reduce stutter in usage, e.g. h3.ToGeo(h).
  • H3 C functions that convert to H3Index have their names inverted to convert from something else to H3Index, e.g. GeoToH3 is renamed to h3.FromGeo.
  • H3 C API function prefixes of Get have been dropped in support of Golang's Getter naming style.

CGO

The H3 C source code and header files are copied into this project to optimize for portability. By including the C source files in the h3 Go package, there is no need to introduce a build process or a system dependency on an H3 binary. Effectively, this decision makes h3 as easy to use in a Go project as adding it as a dependency with your favorite dependency manager.

Contributing

Pull requests and Github issues are welcome. Please read our contributing guide for more information.

H3-Go is licensed under the Apache 2.0 License.

Documentation

Overview

Package h3 is the go binding for Uber's H3 Geo Index system. It uses cgo to link with a statically compiled h3 library

Index

Examples

Constants

View Source
const (
	// MaxCellBndryVerts is the maximum number of vertices that can be used
	// to represent the shape of a cell.
	MaxCellBndryVerts = C.MAX_CELL_BNDRY_VERTS

	// InvalidH3Index is a sentinel value for an invalid H3 index.
	InvalidH3Index = C.H3_INVALID_INDEX
)

Variables

View Source
var (
	// ErrPentagonEncountered is returned by functions that encounter a pentagon
	// and cannot handle it.
	ErrPentagonEncountered = errors.New("pentagon encountered")

	// ErrInvalidResolution is returned when the requested resolution is not valid
	ErrInvalidResolution = errors.New("resolution invalid")
)

Functions

func AreNeighbors

func AreNeighbors(h1, h2 H3Index) bool

AreNeighbors returns true if `h1` and `h2` are neighbors. Two indexes are neighbors if they share an edge.

func BaseCell

func BaseCell(h H3Index) int

BaseCell returns the integer ID of the base cell the H3Index `h` belongs to.

func HexRangeDistances

func HexRangeDistances(origin H3Index, k int) ([][]H3Index, error)

HexRangeDistances implements the C function `hexRangeDistances`.

func HexRanges

func HexRanges(origins []H3Index, k int) ([][]H3Index, error)

HexRanges implements the C function `hexRanges`.

func IsPentagon

func IsPentagon(h H3Index) bool

IsPentagon returns true if `h` is a pentagon.

func IsResClassIII

func IsResClassIII(h H3Index) bool

IsResClassIII returns true if `h` is a class III index. If false, `h` is a class II index.

func IsValid

func IsValid(h H3Index) bool

IsValid returns true if `h` is valid.

func KRingDistances

func KRingDistances(origin H3Index, k int) [][]H3Index

KRingDistances implements the C function `kRingDistances`.

func Resolution

func Resolution(h H3Index) int

Resolution returns the resolution of `h`.

func ToString

func ToString(h H3Index) string

ToString returns a string representation of an H3Index.

func UnidirectionalEdgeIsValid

func UnidirectionalEdgeIsValid(edge H3Index) bool

UnidirectionalEdgeIsValid returns true if `edge` is a valid unidirectional edge index.

Types

type GeoBoundary

type GeoBoundary []GeoCoord

GeoBoundary is a slice of `GeoCoord`. Note, `len(GeoBoundary)` will never exceed `MaxCellBndryVerts`.

func ToGeoBoundary

func ToGeoBoundary(h H3Index) GeoBoundary

ToGeoBoundary returns a `GeoBoundary` of the H3Index `h`.

func UnidirectionalEdgeBoundary

func UnidirectionalEdgeBoundary(edge H3Index) GeoBoundary

UnidirectionalEdgeBoundary returns the geocoordinates of a unidirectional edge boundary.

type GeoCoord

type GeoCoord struct {
	Latitude, Longitude float64
}

GeoCoord is a struct for geographic coordinates.

func ToGeo

func ToGeo(h H3Index) GeoCoord

ToGeo returns the geographic centerpoint of an H3Index `h`.

type GeoPolygon

type GeoPolygon struct {
	// Geofence is the exterior boundary of the polygon
	Geofence []GeoCoord

	// Holes is a slice of interior boundary (holes) in the polygon
	Holes [][]GeoCoord
}

GeoPolygon is a geofence with 0 or more geofence holes

type H3Index

type H3Index = C.H3Index

H3Index is a type alias for the C type `H3Index`. Effectively H3Index is a `uint64`.

func Compact

func Compact(in []H3Index) []H3Index

Compact merges full sets of children into their parent `H3Index` recursively, until no more merges are possible.

func DestinationFromUnidirectionalEdge

func DestinationFromUnidirectionalEdge(edge H3Index) H3Index

DestinationFromUnidirectionalEdge returns the destination of a unidirectional edge.

func FromGeo

func FromGeo(geoCoord GeoCoord, res int) H3Index

FromGeo returns the H3Index at resolution `res` for a geographic coordinate.

Example
geo := GeoCoord{
	Latitude:  37.775938728915946,
	Longitude: -122.41795063018799,
}
resolution := 9
fmt.Printf("%#x\n", FromGeo(geo, resolution))
Output:

0x8928308280fffff

func FromString

func FromString(hStr string) H3Index

FromString returns an H3Index parsed from a string.

func FromUnidirectionalEdge

func FromUnidirectionalEdge(
	edge H3Index,
) (origin, destination H3Index)

FromUnidirectionalEdge returns the origin and destination from a unidirectional edge.

func HexRange

func HexRange(origin H3Index, k int) ([]H3Index, error)

HexRange implements the C function `hexRange`.

func HexRing

func HexRing(origin H3Index, k int) ([]H3Index, error)

HexRing implements the C function `hexRing`.

func KRing

func KRing(origin H3Index, k int) []H3Index

KRing implements the C function `kRing`.

func OriginFromUnidirectionalEdge

func OriginFromUnidirectionalEdge(edge H3Index) H3Index

OriginFromUnidirectionalEdge returns the origin of a unidirectional edge.

func Polyfill

func Polyfill(gp GeoPolygon, res int) []H3Index

Polyfill returns the hexagons at the given resolution whose centers are within the geofences given in the GeoPolygon struct.

func ToChildren

func ToChildren(parent H3Index, childRes int) []H3Index

ToChildren returns all the `H3Index`es of `parent` at resolution `childRes`. `childRes` must be larger than the resolution of `parent`.

func ToParent

func ToParent(child H3Index, parentRes int) (parent H3Index)

ToParent returns the `H3Index` of the cell that contains `child` at resolution `parentRes`. `parentRes` must be less than the resolution of `child`.

func ToUnidirectionalEdges

func ToUnidirectionalEdges(h H3Index) []H3Index

ToUnidirectionalEdges returns the six (or five if pentagon) unidirectional edges from `h` to each of `h`'s neighbors.

func Uncompact

func Uncompact(in []H3Index, res int) ([]H3Index, error)

Uncompact splits every `H3Index` in `in` if its resolution is greater than `res` recursively. Returns all the `H3Index`es at resolution `res`.

func UnidirectionalEdge

func UnidirectionalEdge(origin, destination H3Index) H3Index

UnidirectionalEdge returns a unidirectional `H3Index` from `origin` to `destination`.

Source Files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL