📚 H3 - Awesome Go Library for Geographic
Go bindings for H3, a hierarchical hexagonal geospatial indexing system.
Detailed Description of H3
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
returnsLat
andLng
as degrees, instead of radians.- H3 C API function prefixes of
get
have been dropped in support of Golang'sGetter
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.