flatgeobuf

orb-flatgeobuf

FlatGeobuf format support for the orb geometry library.

This package provides reading and writing of FlatGeobuf files with orb geometry types and GeoJSON features with properties.

Features

• Write FlatGeobuf files from orb geometries or GeoJSON FeatureCollections
• Read FlatGeobuf files into orb geometries or GeoJSON FeatureCollections
• Spatial queries using the built-in Hilbert R-tree index
• Property support with automatic type inference from GeoJSON properties
• All orb geometry types supported: Point, MultiPoint, LineString, MultiLineString, Polygon, MultiPolygon, Collection, Ring, Bound

Performance

FlatGeobuf offers significant performance advantages over GeoJSON, particularly for coordinate-heavy geometries and spatial queries.

Benchmark Results

Payload Size Comparison

Serialization Speed

Deserialization Speed

Spatial Query Performance

This is where FlatGeobuf truly shines - the built-in R-tree index enables O(log n) spatial queries:

Key Takeaways

• Complex geometries: FlatGeobuf provides 35-51% smaller payloads for coordinate-heavy data
• Simple points: GeoJSON may be smaller due to FlatGeobuf's header overhead
• Read performance: FlatGeobuf is consistently 17-18x faster to deserialize
• Spatial queries: The built-in R-tree index makes FlatGeobuf 175x+ faster for spatial lookups
• Memory efficiency: FlatGeobuf uses ~6x less memory and allocations during parsing

Run the benchmarks yourself:

go test -bench=. -benchmem
go test -v -run "TestPerformanceSummary"

Installation

go get github.com/tingold/orb-flatgeobuf

Usage

Writing FlatGeobuf Files

Write Geometries

package main

import (
    "os"
    
    "github.com/paulmach/orb"
    flatgeobuf "github.com/tingold/orb-flatgeobuf"
)

func main() {
    geometries := []orb.Geometry{
        orb.Point{-122.4194, 37.7749},
        orb.Point{-73.9857, 40.7484},
        orb.Point{-87.6298, 41.8781},
    }
    
    file, _ := os.Create("points.fgb")
    defer file.Close()
    
    opts := &flatgeobuf.Options{
        Name:         "cities",
        Description:  "Major US cities",
        IncludeIndex: true,
        CRS:          flatgeobuf.WGS84(),
    }
    
    err := flatgeobuf.Write(file, geometries, opts)
    if err != nil {
        panic(err)
    }
}

Write GeoJSON Features with Properties

package main

import (
    "os"
    
    "github.com/paulmach/orb"
    "github.com/paulmach/orb/geojson"
    flatgeobuf "github.com/tingold/orb-flatgeobuf"
)

func main() {
    fc := geojson.NewFeatureCollection()
    
    f1 := geojson.NewFeature(orb.Point{-122.4194, 37.7749})
    f1.Properties = geojson.Properties{
        "name":       "San Francisco",
        "population": 884363,
        "capital":    false,
    }
    fc.Append(f1)
    
    f2 := geojson.NewFeature(orb.Point{-73.9857, 40.7484})
    f2.Properties = geojson.Properties{
        "name":       "New York",
        "population": 8336817,
        "capital":    false,
    }
    fc.Append(f2)
    
    file, _ := os.Create("cities.fgb")
    defer file.Close()
    
    err := flatgeobuf.WriteFeatures(file, fc, nil)
    if err != nil {
        panic(err)
    }
}

Reading FlatGeobuf Files

Read All Features

package main

import (
    "fmt"
    
    flatgeobuf "github.com/tingold/orb-flatgeobuf"
)

func main() {
    reader, err := flatgeobuf.NewReader("cities.fgb")
    if err != nil {
        panic(err)
    }
    defer reader.Close()
    
    // Get file metadata
    header := reader.Header()
    fmt.Printf("Layer: %s\n", header.Name)
    fmt.Printf("Geometry Type: %s\n", header.GeometryType)
    fmt.Printf("Feature Count: %d\n", header.FeaturesCount)
    fmt.Printf("Has Index: %v\n", header.HasIndex)
    
    // Print column schema
    for _, col := range header.Columns {
        fmt.Printf("Column: %s (%s)\n", col.Name, col.Type)
    }
    
    // Read all features
    fc, err := reader.ReadAll()
    if err != nil {
        panic(err)
    }
    
    for _, f := range fc.Features {
        fmt.Printf("Geometry: %v\n", f.Geometry)
        fmt.Printf("Properties: %v\n", f.Properties)
    }
}

Spatial Query with Index

package main

import (
    "fmt"
    
    "github.com/paulmach/orb"
    flatgeobuf "github.com/tingold/orb-flatgeobuf"
)

func main() {
    reader, err := flatgeobuf.NewReader("cities.fgb")
    if err != nil {
        panic(err)
    }
    defer reader.Close()
    
    // Query features in California bounding box
    bounds := orb.Bound{
        Min: orb.Point{-124.409591, 32.534156},
        Max: orb.Point{-114.131211, 42.009518},
    }
    
    fc, err := reader.Search(bounds)
    if err != nil {
        panic(err)
    }
    
    fmt.Printf("Found %d features in bounds\n", len(fc.Features))
}

Read Geometries Only

// Read just the geometries (no properties)
geometries, err := reader.ReadGeometries()

// Or search for geometries
geometries, err := reader.SearchGeometries(bounds)

Reading from Byte Data

data, _ := os.ReadFile("file.fgb")

reader, err := flatgeobuf.NewReaderFromData(data)
if err != nil {
    panic(err)
}
defer reader.Close()

API Reference

Types

Options

type Options struct {
    Name         string  // Layer name
    Description  string  // Layer description
    IncludeIndex bool    // Include spatial index (default: true)
    CRS          *CRS    // Coordinate reference system
}

CRS

type CRS struct {
    Code        int     // EPSG code (e.g., 4326 for WGS84)
    Name        string  // CRS name
    Description string  // CRS description
    WKT         string  // Well-Known Text representation
}

// Helper function for WGS84
func WGS84() *CRS

Header

type Header struct {
    Name          string       // Layer name
    Description   string       // Layer description
    GeometryType  string       // "Point", "Polygon", "Unknown", etc.
    FeaturesCount uint64       // Number of features
    Envelope      [4]float64   // Bounding box [minX, minY, maxX, maxY]
    CRS           *CRS         // Coordinate reference system
    HasIndex      bool         // Whether file has spatial index
    Columns       []ColumnInfo // Property schema
}

ColumnInfo

type ColumnInfo struct {
    Name        string  // Column name
    Type        string  // "Bool", "Int", "Long", "Double", "String", "Json"
    Title       string  // Human-readable title
    Description string  // Column description
    Nullable    bool    // Whether column can be null
}

Writing Functions

// Write geometries to FlatGeobuf format
func Write(w io.Writer, geometries []orb.Geometry, opts *Options) error

// Write a FeatureCollection to FlatGeobuf format
func WriteFeatures(w io.Writer, fc *geojson.FeatureCollection, opts *Options) error

// Write a single feature to FlatGeobuf format
func WriteFeature(w io.Writer, f *geojson.Feature, opts *Options) error

Reader

// Create a reader from a file path (memory-mapped)
func NewReader(path string) (*Reader, error)

// Create a reader from byte data
func NewReaderFromData(data []byte) (*Reader, error)

// Get file metadata
func (r *Reader) Header() *Header

// Read all features as a FeatureCollection
func (r *Reader) ReadAll() (*geojson.FeatureCollection, error)

// Read all geometries without properties
func (r *Reader) ReadGeometries() ([]orb.Geometry, error)

// Spatial query using the built-in index
func (r *Reader) Search(bounds orb.Bound) (*geojson.FeatureCollection, error)

// Spatial query returning only geometries
func (r *Reader) SearchGeometries(bounds orb.Bound) ([]orb.Geometry, error)

// Release resources
func (r *Reader) Close() error

Supported Geometry Types

Property Type Mapping

Related Projects

• orb - Core geometry types
• orb-predicates - Geometry predicates (Contains, Intersects, etc.)
• orb-operations - Geometry operations (Union, Intersection, etc.)
• FlatGeobuf - FlatGeobuf specification

License

MIT License - see LICENSE for details.