orb

orb is a foundational geometry library for Go that defines a small set of 2D geo and planar types — Point, LineString, Polygon, MultiPolygon, Collection, and Bound — as native Go slices and arrays rather than opaque structs. Because the types are just slices, they work directly with Go’s own make, append, len, and slice-notation builtins instead of requiring a bespoke builder API.

Around this small core, orb builds a rich ecosystem of sub-packages: geojson for marshaling GeoJSON Features and FeatureCollections (including a generic typed-properties variant), encoding/mvt for Mapbox Vector Tiles, encoding/wkb and encoding/ewkb for scanning geometry columns directly out of PostGIS query results, encoding/wkt for well-known text, plus geo, planar, clip, simplify, resample, quadtree, project, and maptile for the algorithms that operate on those types.

What You Get

• Core orb.Geometry types (Point, LineString, Polygon, MultiPolygon, Collection, Bound) implemented as native Go slices/arrays that work with make, append, len, and slice notation
• geojson sub-package for marshaling/unmarshaling GeoJSON Features and FeatureCollections, including a generic FeatureOf[P] variant for typed properties
• encoding/mvt, encoding/wkb, encoding/ewkb, and encoding/wkt sub-packages for Mapbox Vector Tiles, well-known binary (with database/sql Scanner support), and well-known text formats
• geo and planar sub-packages with distance, area, and centroid algorithms for WGS84 vs. projected coordinate contexts
• clip, simplify (Douglas-Peucker), resample, quadtree, project, and maptile sub-packages for geometric transforms and spatial indexing

Common Use Cases

• Serving Mapbox Vector Tiles from a Go tile server
• Scanning PostGIS WKB/EWKB geometry columns directly into Go structs
• Building and transforming GeoJSON APIs with typed feature properties
• Simplifying, clipping, and spatially indexing large geometry datasets

Under The Hood

Architecture The root package defines the core types (point.go, line_string.go, polygon.go, multi_*.go, ring.go, bound.go, geometry.go) as thin wrappers over Go’s native slice/array types, each implementing a shared Geometry interface (GeoJSONType, Dimensions, Bound, plus an unexported private() method used as a closed-interface type-switch guard). This lets every sub-package — clip, planar, geo, geojson, encoding/mvt, encoding/wkb, encoding/ewkb, encoding/wkt, simplify, resample, quadtree, project, maptile — operate polymorphically over any concrete geometry via type switches on Geometry, rather than depending on the root package’s public surface growing. Sub-packages fan out shallowly from the small core (each importing only orb, or composing naturally, e.g. encoding/mvt importing geojson and orb) with no circular dependencies, so adding a new algorithm sub-package touches nothing else, though the sealed private() interface does add friction for third-party geometry implementations.

Tech Stack A pure Go module (go 1.18, using generics for FeatureOf[P]) with almost no runtime dependencies: go.mod declares only github.com/gogo/protobuf (MVT protobuf encoding), github.com/paulmach/protoscan (a protobuf scanning helper by the same author), and go.mongodb.org/mongo-driver/v2 (BSON support for MongoDB). Build tooling is stock go build/go vet/go test; CI runs on GitHub Actions with actions/setup-go pinned to the version in go.mod, go vet, go test with coverage uploaded to Codecov, plus a separate golangci-lint workflow. There is no deployment target — it’s consumed as a versioned Go module via go get.

Code Quality Extensive test coverage: dozens of _test.go files pair 1:1 with implementation files across the module and its sub-packages (point.go/point_test.go, bound.go/bound_test.go, and so on), plus dedicated example_test.go files in several sub-packages that double as runnable pkg.go.dev documentation. Error handling is idiomatic Go — functions that can fail (geojson unmarshaling, WKB scanners) return an explicit error, with no swallowed errors observed in the files read. Every exported type and method carries a godoc comment, naming is consistent, generics are used for typed properties rather than any/interface{}, and CI enforces both go vet and golangci-lint.

API Design The library’s core ergonomic bet — defining geometry types as plain slices/arrays instead of structs with private fields — means developers manipulate geometries with Go’s own make/append/len/slice-notation rather than learning a bespoke builder API, which is unusual among geometry libraries and is the most-cited feature in its own README. The shared Geometry interface plus sub-package composition (clip.Geometry, planar.CentroidArea, geo.Distance) lets one call site handle any geometry kind via a type switch instead of one function per shape, keeping the amount of boilerplate needed to get started low, though shape-specific behavior lives in whichever sub-package cares rather than on the type itself.