The highest tagged major version is
README
¶
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
GeoCoordstructs returnLatitudeandLongitudeas 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
H3have been dropped to reduce stutter in usage, e.g.h3.ToGeo(h). - H3 C functions that convert to
H3Indexhave their names inverted to convert from something else toH3Index, e.g.GeoToH3is renamed toh3.FromGeo. - H3 C API function prefixes of
Gethave been dropped in support of Golang'sGetternaming 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.
Legal and Licensing
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 ¶
- Constants
- Variables
- func AreNeighbors(h1, h2 H3Index) bool
- func BaseCell(h H3Index) int
- func HexRangeDistances(origin H3Index, k int) ([][]H3Index, error)
- func HexRanges(origins []H3Index, k int) ([][]H3Index, error)
- func IsPentagon(h H3Index) bool
- func IsResClassIII(h H3Index) bool
- func IsValid(h H3Index) bool
- func KRingDistances(origin H3Index, k int) [][]H3Index
- func Resolution(h H3Index) int
- func ToString(h H3Index) string
- func UnidirectionalEdgeIsValid(edge H3Index) bool
- type GeoBoundary
- type GeoCoord
- type GeoPolygon
- type H3Index
- func Compact(in []H3Index) []H3Index
- func DestinationFromUnidirectionalEdge(edge H3Index) H3Index
- func FromGeo(geoCoord GeoCoord, res int) H3Index
- func FromString(hStr string) H3Index
- func FromUnidirectionalEdge(edge H3Index) (origin, destination H3Index)
- func HexRange(origin H3Index, k int) ([]H3Index, error)
- func HexRing(origin H3Index, k int) ([]H3Index, error)
- func KRing(origin H3Index, k int) []H3Index
- func OriginFromUnidirectionalEdge(edge H3Index) H3Index
- func Polyfill(gp GeoPolygon, res int) []H3Index
- func ToChildren(parent H3Index, childRes int) []H3Index
- func ToParent(child H3Index, parentRes int) (parent H3Index)
- func ToUnidirectionalEdges(h H3Index) []H3Index
- func Uncompact(in []H3Index, res int) ([]H3Index, error)
- func UnidirectionalEdge(origin, destination H3Index) H3Index
Examples ¶
Constants ¶
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 ¶
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 ¶
AreNeighbors returns true if `h1` and `h2` are neighbors. Two indexes are neighbors if they share an edge.
func HexRangeDistances ¶
HexRangeDistances implements the C function `hexRangeDistances`.
func IsResClassIII ¶
IsResClassIII returns true if `h` is a class III index. If false, `h` is a class II index.
func KRingDistances ¶
KRingDistances implements the C function `kRingDistances`.
func UnidirectionalEdgeIsValid ¶
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.
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 ¶
H3Index is a type alias for the C type `H3Index`. Effectively H3Index is a `uint64`.
func Compact ¶
Compact merges full sets of children into their parent `H3Index` recursively, until no more merges are possible.
func DestinationFromUnidirectionalEdge ¶
DestinationFromUnidirectionalEdge returns the destination of a unidirectional edge.
func FromGeo ¶
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 ¶
FromString returns an H3Index parsed from a string.
func FromUnidirectionalEdge ¶
FromUnidirectionalEdge returns the origin and destination from a unidirectional edge.
func OriginFromUnidirectionalEdge ¶
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 ¶
ToChildren returns all the `H3Index`es of `parent` at resolution `childRes`. `childRes` must be larger than the resolution of `parent`.
func ToParent ¶
ToParent returns the `H3Index` of the cell that contains `child` at resolution `parentRes`. `parentRes` must be less than the resolution of `child`.
func ToUnidirectionalEdges ¶
ToUnidirectionalEdges returns the six (or five if pentagon) unidirectional edges from `h` to each of `h`'s neighbors.
func Uncompact ¶
Uncompact splits every `H3Index` in `in` if its resolution is greater than `res` recursively. Returns all the `H3Index`es at resolution `res`.
func UnidirectionalEdge ¶
UnidirectionalEdge returns a unidirectional `H3Index` from `origin` to `destination`.
Source Files