Native Go library implementing FlatGeobuf, a performant binary encoding for geographic data based on FlatBuffers.
Read the docs:
Get the code:
$ go get github.com/gogama/flatgeobuf
Read a Flatgeobuf file, search the index, etc.:
package getStartedReading
import (
"os"
"github.com/gogama/flatgeobuf/flatgeobuf"
)
func main() {
f, _ := os.Open("example.fgb")
r := flatgeobuf.NewFileReader(f)
// Use methods on FileReader 'r' to read header; read or search index; or
// read features. Use a PropReader to read feature properties.
// https://pkg.go.dev/github.com/gogama/flatgeobuf/flatgeobuf#FileReader
}
Write a Flatgeobuf file, create index of features, etc.:
package getStartedWriting
import (
"os"
"github.com/gogama/flatgeobuf/flatgeobuf"
)
func main() {
f, _ := os.Create("example.fgb")
w := flatgeobuf.NewFileWriter(f)
// Use methods on FileWriter 'w' to write header; write index; write
// features; or index and write features together.
// https://pkg.go.dev/github.com/gogama/flatgeobuf/flatgeobuf#FileWriter
}
Works with all Go versions 1.20 and up.
Find detailed FlatGeobuf file format documentation at flatgeobuf.org. The short form explanation is that the FlatGeobuf format is really four different formats in one.
- H: The Header format, which is a variable-sized FlatBuffer table.
- I (optional): The optional Index format, which is a packed Hilbert R-tree index in a custom format.
- DATA: Sequence of Features, each of which is a variable-sized FlatBuffer table.
- PROPERTIES: Each Feature contains a properties buffer which is a key/value pair sequence in a custom format.
This library provides abstractions to cleanly and efficiently work with all four of the above formats.
There are three main Go packages:
Package | Purpose | Key Types and Functions |
---|---|---|
flatgeobuf |
Read and write FlatGeobuf files, including Feature properties | flatgeobuf.FileReader , flatgeobuf.FileWriter , flatgeobuf.PropReader , flatgeobuf.PropWriter |
flatgeobuf/flat |
FlatBuffer tables generated by flatc |
flat.Header , flat.Feature |
packedrtree |
Packed Hilbert R-Tree format, use with flatgeobuf or standalone |
packedrtree.PackedRTree , packedrtree.Seek |
The nifty FlatGeobuf efficient I/O characteristics (streaming/random read
efficiency) are built in to flatgeobuf.FileReader
and packedrtree.Seek
if
you provide them with a standard io.ReadSeeker
. You can efficiently host huge
FlatGeobuf files on HTTP services that support HTTP Range read requests, like
Amazon S3, by wrapping the HTTP Range requests in an io.ReadSeeker
.
This project is licensed under the terms of the MIT License.
Some *.fgb
files in flatgeobuf/testdata/
are copied from the
official FlatGeobuf repository and licensed separately under the
BSD-2-Clause License. See flatgeobuf/testdata/flatgeobuf/LICENSE
.
The code in package flat
is generated using flatc
from the official
GitHub repository's FlatBuffer schema.
Thanks to @bjornharrtell for developing the FlatGeobuf specification and @thehoneymad for getting me interested in it. Thanks to JetBrains, for generously donating an open source license for their GoLand IDE.
Geospatially, check out the Overture project.
Within Gogama projects, Incite is a fantastic library to smooth out working with AWS CloudWatch Logs, and httpx is an excellent, if criminally underused, robust HTTP client.