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.

FlatGeobuf Format Primer

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.