flatgeobuf
Native Go library implementing FlatGeobuf, a
performant binary encoding for geographic data based on
FlatBuffers.
Getting Started
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
}
Compatibility
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.
Package Map
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
.
License
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.
Acknowledgements
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.
Shameless Plugs
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.