https://github.com/gogama/flatgeobuf
Flatgeobuf binary geospatial encoding Go library
https://github.com/gogama/flatgeobuf
flatgeobuf geospatial geospatial-database go golang
Last synced: 6 months ago
JSON representation
Flatgeobuf binary geospatial encoding Go library
- Host: GitHub
- URL: https://github.com/gogama/flatgeobuf
- Owner: gogama
- License: mit
- Created: 2023-05-29T22:08:58.000Z (about 3 years ago)
- Default Branch: main
- Last Pushed: 2023-12-21T05:32:16.000Z (over 2 years ago)
- Last Synced: 2024-08-08T02:42:36.873Z (almost 2 years ago)
- Topics: flatgeobuf, geospatial, geospatial-database, go, golang
- Language: Go
- Homepage:
- Size: 14.3 MB
- Stars: 15
- Watchers: 3
- Forks: 2
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE
- Authors: AUTHORS
Awesome Lists containing this project
README
# flatgeobuf
Native Go library implementing [FlatGeobuf](https://flatgeobuf.org/), a
performant binary encoding for geographic data based on
[FlatBuffers](https://flatbuffers.dev/).
## Getting Started
Read the docs:
[](https://pkg.go.dev/github.com/gogama/flatgeobuf)
Get the code:
```shell
$ go get github.com/gogama/flatgeobuf
```
Read a Flatgeobuf file, search the index, _etc._:
```go
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._:
```go
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](https://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](https://github.com/flatgeobuf/flatgeobuf/blob/master/src/fbs/header.fbs#L67-L82).
- 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](https://github.com/flatgeobuf/flatgeobuf/blob/master/src/fbs/feature.fbs#L16-L20).
- 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](https://github.com/flatgeobuf/flatgeobuf/tree/master/src/fbs).
## 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](https://overturemaps.org/)
project.
Within Gogama projects, [Incite](https://github.com/gogama/incite) is a
fantastic library to smooth out working with AWS CloudWatch Logs, and
[httpx](https://github.com/gogama/httpx) is an excellent, if criminally
underused, robust HTTP client.