Skip to content

Latest commit

 

History

History
148 lines (116 loc) · 7.77 KB

README.md

File metadata and controls

148 lines (116 loc) · 7.77 KB
Raw

H3 Logo

Build Coverage Status Go Report Card License GoDoc H3 Version

H3-Go is looking for a maintainer familiar with Go, C, and H3. Volunteers welcome! Please get in touch with us on the H3 Slack.

H3-Go

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

This is v4 of this library, supporting H3 v4.

Check out v3 or checkout the git tag for the version you need.

Migrating from v3?

Check out v3 to v4 migration guide. There have been no breaking changes to the format of H3 indexes. Indexes generated by older versions can be parsed in v4, and vice-versa.

Usage

Prerequisites

H3-Go requires CGO (CGO_ENABLED=1) in order to be built. Go should do the right thing when including this library:

The cgo tool is enabled by default for native builds on systems where it is expected to work. It is disabled by default when cross-compiling. You can control this by setting the CGO_ENABLED environment variable when running the go tool: set it to 1 to enable the use of cgo, and to 0 to disable it. The go tool will set the build constraint "cgo" if cgo is enabled. The special import "C" implies the "cgo" build constraint, as though the file also said "// +build cgo". Therefore, if cgo is disabled, files that import "C" will not be built by the go tool. (For more about build constraints see https://golang.org/pkg/go/build/#hdr-Build_Constraints).

If you see errors/warnings like "build constraints exclude all Go files...", then the cgo build constraint is likely disabled; try setting CGO_ENABLED=1 environment variable in your go build step.

Installation

go get github.com/uber/h3-go/v4

Quickstart

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

func ExampleLatLngToCell() {
 latLng := h3.NewLatLng(37.775938728915946, -122.41795063018799)
 resolution := 9 // between 0 (biggest cell) and 15 (smallest cell)

 cell := h3.LatLngToCell(latLng, resolution)

 fmt.Printf("%s", cell)
 // Output:
 // 8928308280fffff
}

C API

Notes

  • LatLng returns Lat and Lng as degrees, instead of radians.
  • H3 C API function prefixes of get have been dropped in support of Golang's Getter naming style.
  • Convenience methods have been added to various types where that type was the main or only argument.

Bindings

C API Go API
latLngToCell LatLngToCell, LatLng#Cell
cellToLatLng CellToLatLng, Cell#LatLng
cellToBoundary CellToBoundary, Cell#Boundary
gridDisk GridDisk, Cell#GridDisk
gridDiskDistances GridDiskDistances, Cell#GridDiskDistances
gridRingUnsafe N/A
polygonToCells PolygonToCells, GeoPolygon#Cells
cellsToMultiPolygon CellsToMultiPolygon
degsToRads DegsToRads
radsToDegs RadsToDegs
greatCircleDistance GreatCircleDistance* (3/3)
getHexagonAreaAvg HexagonAreaAvg* (3/3)
cellArea CellArea* (3/3)
getHexagonEdgeLengthAvg HexagonEdgeLengthAvg* (2/2)
exactEdgeLength EdgeLength* (3/3)
getNumCells NumCells
getRes0Cells Res0Cells
getPentagons Pentagons
getResolution Resolution
getBaseCellNumber BaseCellNumber, Cell#BaseCellNumber
stringToH3 IndexFromString, Cell#UnmarshalText
h3ToString IndexToString, Cell#String, Cell#MarshalText
isValidCell Cell#IsValid
cellToParent Cell#Parent, Cell#ImmediateParent
cellToChildren Cell#Children Cell#ImmediateChildren
cellToCenterChild Cell#CenterChild
compactCells CompactCells
uncompactCells UncompactCells
isResClassIII Cell#IsResClassIII
isPentagon Cell#IsPentagon
getIcosahedronFaces Cell#IcosahedronFaces
areNeighborCells Cell#IsNeighbor
cellsToDirectedEdge Cell#DirectedEdge
isValidDirectedEdge DirectedEdge#IsValid
getDirectedEdgeOrigin DirectedEdge#Origin
getDirectedEdgeDestination DirectedEdge#Destination
directedEdgeToCells DirectedEdge#Cells
originToDirectedEdges Cell#DirectedEdges
directedEdgeToBoundary DirectedEdge#Boundary
cellToVertex CellToVertex
cellToVertexes CellToVertexes
vertexToLatLng VertexToLatLng
isValidVertex IsValidVertex
gridDistance GridDistance, Cell#GridDistance
gridPathCells GridPath, Cell#GridPath
cellToLocalIj CellToLocalIJ
localIjToCell LocalIJToCell

CGO

The H3 C source code and header files are copied into this project to optimize for portability. h3-go can be imported into any Go project for any platform that CGO supports.

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.