Popularity
7.2
Stable
Activity
4.3
-
908
21
103

Description

Package orb defines a set of types for working with 2d geo and planar/projected geometric data in Golang. There are a set of sub-packages that use these types to do interesting things. They each provider their own README with extra info.

Programming language: Go
License: MIT License
Tags: GIS     Geospatial     WKB     Geo     Geojson     Wkt     Mapbox-vector-lite     2d    
Latest version: v0.5.0

orb alternatives and similar packages

Based on the "GIS" category.
Alternatively, view orb alternatives based on common mentions on social networks and blogs.

  • go-geom

    Package geom implements efficient geometry types for geospatial applications.
  • polyline

    Package polyline implements a Google Maps Encoding Polyline encoder and decoder.
  • Revolutionize your code reviews with AI. CodeRabbit offers PR summaries, code walkthroughs, 1-click suggestions, and AST-based analysis. Boost productivity and code quality across all major languages with each PR.
    Promo coderabbit.ai
    CodeRabbit Logo
  • WGS84

    A zero-dependency Go package for coordinate transformations.
  • go-kml

    Package kml provides convenience methods for creating and writing KML documents.
  • UTM

    3.0 5.2 orb VS UTM
    Bidirectional UTM-WGS84 converter for golang :earth_africa: :globe_with_meridians:
  • go-gpx

    Package gpx provides convenience types for reading and writing GPX files.
  • go-sypexgeo

    SypexGeo library for Go (provides access data from SypexGeo IP database files)
  • doarama.go

    DISCONTINUED. Go client library for the Doarama GPS track visualizer

Do you think we are missing an alternative of orb or a related project?

Add another 'GIS' Package

README

orb CI codecov Go Report Card Go Reference

Package orb defines a set of types for working with 2d geo and planar/projected geometric data in Golang. There are a set of sub-packages that use these types to do interesting things. They each provider their own README with extra info.

Interesting features

  • Simple types - allow for natural operations using the make, append, len, [s:e] builtins.
  • GeoJSON - support as part of the [geojson](geojson) sub-package.
  • Mapbox Vector Tile - encoding and decoding as part of the [encoding/mvt](encoding/mvt) sub-package.
  • Direct to type from DB query results - by scanning WKB data directly into types.
  • Rich set of sub-packages - including [clipping](clip), [simplifing](simplify), [quadtree](quadtree) and more.

Type definitions

type Point [2]float64
type MultiPoint []Point

type LineString []Point
type MultiLineString []LineString

type Ring LineString
type Polygon []Ring
type MultiPolygon []Polygon

type Collection []Geometry

type Bound struct { Min, Max Point }

Defining the types as slices allows them to be accessed in an idiomatic way using Go's built-in functions such at make, append, len and with slice notation like [s:e]. For example:

ls := make(orb.LineString, 0, 100)
ls = append(ls, orb.Point{1, 1})
point := ls[0]

Shared Geometry interface

All of the base types implement the orb.Geometry interface defined as:

type Geometry interface {
    GeoJSONType() string
    Dimensions() int // e.g. 0d, 1d, 2d
    Bound() Bound
}

This interface is accepted by functions in the sub-packages which then act on the base types correctly. For example:

l := clip.Geometry(bound, geom)

will use the appropriate clipping algorithm depending on if the input is 1d or 2d, e.g. a orb.LineString or a orb.Polygon.

Only a few methods are defined directly on these type, for example Clone, Equal, GeoJSONType. Other operation that depend on geo vs. planar contexts are defined in the respective sub-package. For example:

  • Computing the geo distance between two point:

    p1 := orb.Point{-72.796408, -45.407131}
    p2 := orb.Point{-72.688541, -45.384987}
    
    geo.Distance(p1, p2)
    
  • Compute the planar area and centroid of a polygon:

    poly := orb.Polygon{...}
    centroid, area := planar.CentroidArea(poly)
    

GeoJSON

The [geojson](geojson) sub-package implements Marshalling and Unmarshalling of GeoJSON data. Features are defined as:

type Feature struct {
    ID         interface{}  `json:"id,omitempty"`
    Type       string       `json:"type"`
    Geometry   orb.Geometry `json:"geometry"`
    Properties Properties   `json:"properties"`
}

Defining the geometry as an orb.Geometry interface along with sub-package functions accepting geometries allows them to work together to create easy to follow code. For example, clipping all the geometries in a collection:

fc, err := geojson.UnmarshalFeatureCollection(data)
for _, f := range fc {
    f.Geometry = clip.Geometry(bound, f.Geometry)
}

The library supports third party "encoding/json" replacements such github.com/json-iterator/go. See the [geojson](geojson) readme for more details.

Mapbox Vector Tiles

The [encoding/mvt](encoding/mvt) sub-package implements Marshalling and Unmarshalling MVT data. This package uses sets of geojson.FeatureCollection to define the layers, keyed by the layer name. For example:

collections := map[string]*geojson.FeatureCollection{}

// Convert to a layers object and project to tile coordinates.
layers := mvt.NewLayers(collections)
layers.ProjectToTile(maptile.New(x, y, z))

// In order to be used as source for MapboxGL geometries need to be clipped
// to max allowed extent. (uncomment next line)
// layers.Clip(mvt.MapboxGLDefaultExtentBound)

// Simplify the geometry now that it's in tile coordinate space.
layers.Simplify(simplify.DouglasPeucker(1.0))

// Depending on use-case remove empty geometry, those too small to be
// represented in this tile space.
// In this case lines shorter than 1, and areas smaller than 2.
layers.RemoveEmpty(1.0, 2.0)

// encoding using the Mapbox Vector Tile protobuf encoding.
data, err := layers.Marshal() // this data is NOT gzipped.

// Sometimes MVT data is stored and transfered gzip compressed. In that case:
data, err := layers.MarshalGzipped()

Decoding WKB from a database query

Geometries are usually returned from databases in WKB format. The [encoding/wkb](encoding/wkb) sub-package offers helpers to "scan" the data into the base types directly. For example:

row := db.QueryRow("SELECT ST_AsBinary(point_column) FROM postgis_table")

var p orb.Point
err := row.Scan(wkb.Scanner(&p))

db.Exec("INSERT INTO table (point_column) VALUES (ST_GeomFromWKB(?))", wkb.Value(p))

Scanning directly from MySQL columns is supported. By default MySQL returns geometry data as WKB but prefixed with a 4 byte SRID. To support this, if the data is not valid WKB, the code will strip the first 4 bytes, the SRID, and try again. This works for most use cases.

List of sub-package utilities

  • [clip](clip) - clipping geometry to a bounding box
  • [encoding/mvt](encoding/mvt) - encoded and decoding from Mapbox Vector Tiles
  • [encoding/wkb](encoding/wkb) - well-known binary as well as helpers to decode from the database queries
  • [encoding/wkt](encoding/wkt) - well-known text encoding
  • [geojson](geojson) - working with geojson and the types in this package
  • [maptile](maptile) - working with mercator map tiles and quadkeys
  • [project](project) - project geometries between geo and planar contexts
  • [quadtree](quadtree) - quadtree implementation using the types in this package
  • [resample](resample) - resample points in a line string geometry
  • [simplify](simplify) - linear geometry simplifications like Douglas-Peucker