orb

package module
Version: v0.2.1 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Jan 17, 2021 License: MIT Imports: 2 Imported by: 176

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 sub-package.
  • Mapbox Vector Tile - encoding and decoding as part of the 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, simplifing, 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 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)
}

Mapbox Vector Tiles

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

Documentation

Index

Constants

View Source
const EarthRadius = 6378137.0 // meters

EarthRadius is the radius of the earth in meters. It is used in geo distance calculations. To keep things consistent, this value matches WGS84 Web Mercator (EPSG:3857).

Variables

AllGeometries lists all possible types and values that a geometry interface can be. It should be used only for testing to verify functions that accept a Geometry will work in all cases.

View Source
var DefaultRoundingFactor = 1e6 // 6 decimal places

DefaultRoundingFactor is the default rounding factor used by the Round func.

Functions

func Equal

func Equal(g1, g2 Geometry) bool

Equal returns if the two geometrires are equal.

Types

type Bound

type Bound struct {
	Min, Max Point
}

A Bound represents a closed box or rectangle. To create a bound with two points you can do something like:

orb.MultiPoint{p1, p2}.Bound()

func (Bound) Bottom

func (b Bound) Bottom() float64

Bottom returns the bottom of the bound.

func (Bound) Bound

func (b Bound) Bound() Bound

Bound returns the the same bound.

func (Bound) Center

func (b Bound) Center() Point

Center returns the center of the bounds by "averaging" the x and y coords.

func (Bound) Contains

func (b Bound) Contains(point Point) bool

Contains determines if the point is within the bound. Points on the boundary are considered within.

func (Bound) Dimensions

func (b Bound) Dimensions() int

Dimensions returns 2 because a Bound is a 2d object.

func (Bound) Equal

func (b Bound) Equal(c Bound) bool

Equal returns if two bounds are equal.

func (Bound) Extend

func (b Bound) Extend(point Point) Bound

Extend grows the bound to include the new point.

func (Bound) GeoJSONType

func (b Bound) GeoJSONType() string

GeoJSONType returns the GeoJSON type for the object.

func (Bound) Intersects

func (b Bound) Intersects(bound Bound) bool

Intersects determines if two bounds intersect. Returns true if they are touching.

func (Bound) IsEmpty

func (b Bound) IsEmpty() bool

IsEmpty returns true if it contains zero area or if it's in some malformed negative state where the left point is larger than the right. This can be caused by padding too much negative.

func (Bound) IsZero

func (b Bound) IsZero() bool

IsZero return true if the bound just includes just null island.

func (Bound) Left

func (b Bound) Left() float64

Left returns the left of the bound.

func (Bound) LeftTop

func (b Bound) LeftTop() Point

LeftTop returns the upper left point of the bound.

func (Bound) Pad

func (b Bound) Pad(d float64) Bound

Pad extends the bound in all directions by the given value.

func (Bound) Right

func (b Bound) Right() float64

Right returns the right of the bound.

func (Bound) RightBottom

func (b Bound) RightBottom() Point

RightBottom return the lower right point of the bound.

func (Bound) ToPolygon

func (b Bound) ToPolygon() Polygon

ToPolygon converts the bound into a Polygon object.

func (Bound) ToRing

func (b Bound) ToRing() Ring

ToRing converts the bound into a loop defined by the boundary of the box.

func (Bound) Top

func (b Bound) Top() float64

Top returns the top of the bound.

func (Bound) Union

func (b Bound) Union(other Bound) Bound

Union extends this bound to contain the union of this and the given bound.

type Collection

type Collection []Geometry

A Collection is a collection of geometries that is also a Geometry.

func (Collection) Bound

func (c Collection) Bound() Bound

Bound returns the bounding box of all the Geometries combined.

func (Collection) Clone

func (c Collection) Clone() Collection

Clone returns a deep copy of the collection.

func (Collection) Dimensions

func (c Collection) Dimensions() int

Dimensions returns the max of the dimensions of the collection.

func (Collection) Equal

func (c Collection) Equal(collection Collection) bool

Equal compares two collections. Returns true if lengths are the same and all the sub geometries are the same and in the same order.

func (Collection) GeoJSONType

func (c Collection) GeoJSONType() string

GeoJSONType returns the geometry collection type.

type DistanceFunc

type DistanceFunc func(Point, Point) float64

A DistanceFunc is a function that computes the distance between two points.

type Geometry

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

Geometry is an interface that represents the shared attributes of a geometry.

func Clone

func Clone(g Geometry) Geometry

Clone will make a deep copy of the geometry.

func Round

func Round(g Geometry, factor ...int) Geometry

Round will round all the coordinates of the geometry to the given factor. The default is 6 decimal places.

type LineString

type LineString []Point

LineString represents a set of points to be thought of as a polyline.

func (LineString) Bound

func (ls LineString) Bound() Bound

Bound returns a rect around the line string. Uses rectangular coordinates.

func (LineString) Clone

func (ls LineString) Clone() LineString

Clone returns a new copy of the line string.

func (LineString) Dimensions

func (ls LineString) Dimensions() int

Dimensions returns 1 because a LineString is a 1d object.

func (LineString) Equal

func (ls LineString) Equal(lineString LineString) bool

Equal compares two line strings. Returns true if lengths are the same and all points are Equal.

func (LineString) GeoJSONType

func (ls LineString) GeoJSONType() string

GeoJSONType returns the GeoJSON type for the object.

func (LineString) Reverse

func (ls LineString) Reverse()

Reverse will reverse the line string. This is done inplace, ie. it modifies the original data.

type MultiLineString

type MultiLineString []LineString

MultiLineString is a set of polylines.

func (MultiLineString) Bound

func (mls MultiLineString) Bound() Bound

Bound returns a bound around all the line strings.

func (MultiLineString) Clone

func (mls MultiLineString) Clone() MultiLineString

Clone returns a new deep copy of the multi line string.

func (MultiLineString) Dimensions

func (mls MultiLineString) Dimensions() int

Dimensions returns 1 because a MultiLineString is a 2d object.

func (MultiLineString) Equal

func (mls MultiLineString) Equal(multiLineString MultiLineString) bool

Equal compares two multi line strings. Returns true if lengths are the same and all points are Equal.

func (MultiLineString) GeoJSONType

func (mls MultiLineString) GeoJSONType() string

GeoJSONType returns the GeoJSON type for the object.

type MultiPoint

type MultiPoint []Point

A MultiPoint represents a set of points in the 2D Eucledian or Cartesian plane.

func (MultiPoint) Bound

func (mp MultiPoint) Bound() Bound

Bound returns a bound around the points. Uses rectangular coordinates.

func (MultiPoint) Clone

func (mp MultiPoint) Clone() MultiPoint

Clone returns a new copy of the points.

func (MultiPoint) Dimensions

func (mp MultiPoint) Dimensions() int

Dimensions returns 0 because a MultiPoint is a 0d object.

func (MultiPoint) Equal

func (mp MultiPoint) Equal(multiPoint MultiPoint) bool

Equal compares two MultiPoint objects. Returns true if lengths are the same and all points are Equal, and in the same order.

func (MultiPoint) GeoJSONType

func (mp MultiPoint) GeoJSONType() string

GeoJSONType returns the GeoJSON type for the object.

type MultiPolygon

type MultiPolygon []Polygon

MultiPolygon is a set of polygons.

func (MultiPolygon) Bound

func (mp MultiPolygon) Bound() Bound

Bound returns a bound around the multi-polygon.

func (MultiPolygon) Clone

func (mp MultiPolygon) Clone() MultiPolygon

Clone returns a new deep copy of the multi-polygon.

func (MultiPolygon) Dimensions

func (mp MultiPolygon) Dimensions() int

Dimensions returns 2 because a MultiPolygon is a 2d object.

func (MultiPolygon) Equal

func (mp MultiPolygon) Equal(multiPolygon MultiPolygon) bool

Equal compares two multi-polygons.

func (MultiPolygon) GeoJSONType

func (mp MultiPolygon) GeoJSONType() string

GeoJSONType returns the GeoJSON type for the object.

type Orientation

type Orientation int8

Orientation defines the order of the points in a polygon or closed ring.

const (
	// CCW stands for Counter Clock Wise
	CCW Orientation = 1

	// CW stands for Clock Wise
	CW Orientation = -1
)

Constants to define orientation. They follow the right hand rule for orientation.

type Point

type Point [2]float64

A Point is a Lon/Lat 2d point.

func (Point) Bound

func (p Point) Bound() Bound

Bound returns a single point bound of the point.

func (Point) Dimensions

func (p Point) Dimensions() int

Dimensions returns 0 because a point is a 0d object.

func (Point) Equal

func (p Point) Equal(point Point) bool

Equal checks if the point represents the same point or vector.

func (Point) GeoJSONType

func (p Point) GeoJSONType() string

GeoJSONType returns the GeoJSON type for the object.

func (Point) Lat

func (p Point) Lat() float64

Lat returns the vertical, latitude coordinate of the point.

func (Point) Lon

func (p Point) Lon() float64

Lon returns the horizontal, longitude coordinate of the point.

func (Point) Point

func (p Point) Point() Point

Point returns itself so it implements the Pointer interface.

func (Point) X

func (p Point) X() float64

X returns the horizontal coordinate of the point.

func (Point) Y

func (p Point) Y() float64

Y returns the vertical coordinate of the point.

type Pointer

type Pointer interface {
	Point() Point
}

Pointer is something that can be represented by a point.

type Polygon

type Polygon []Ring

Polygon is a closed area. The first LineString is the outer ring. The others are the holes. Each LineString is expected to be closed ie. the first point matches the last.

func (Polygon) Bound

func (p Polygon) Bound() Bound

Bound returns a bound around the polygon.

func (Polygon) Clone

func (p Polygon) Clone() Polygon

Clone returns a new deep copy of the polygon. All of the rings are also cloned.

func (Polygon) Dimensions

func (p Polygon) Dimensions() int

Dimensions returns 2 because a Polygon is a 2d object.

func (Polygon) Equal

func (p Polygon) Equal(polygon Polygon) bool

Equal compares two polygons. Returns true if lengths are the same and all points are Equal.

func (Polygon) GeoJSONType

func (p Polygon) GeoJSONType() string

GeoJSONType returns the GeoJSON type for the object.

type Projection

type Projection func(Point) Point

A Projection a function that moves a point from one space to another.

type Ring

type Ring LineString

Ring represents a set of ring on the earth.

func (Ring) Bound

func (r Ring) Bound() Bound

Bound returns a rect around the ring. Uses rectangular coordinates.

func (Ring) Clone

func (r Ring) Clone() Ring

Clone returns a new copy of the ring.

func (Ring) Closed

func (r Ring) Closed() bool

Closed will return true if the ring is a real ring. ie. 4+ points and the first and last points match. NOTE: this will not check for self-intersection.

func (Ring) Dimensions

func (r Ring) Dimensions() int

Dimensions returns 2 because a Ring is a 2d object.

func (Ring) Equal

func (r Ring) Equal(ring Ring) bool

Equal compares two rings. Returns true if lengths are the same and all points are Equal.

func (Ring) GeoJSONType

func (r Ring) GeoJSONType() string

GeoJSONType returns the GeoJSON type for the object.

func (Ring) Orientation

func (r Ring) Orientation() Orientation

Orientation returns 1 if the the ring is in couter-clockwise order, return -1 if the ring is the clockwise order and 0 if the ring is degenerate and had no area.

func (Ring) Reverse

func (r Ring) Reverse()

Reverse changes the direction of the ring. This is done inplace, ie. it modifies the original data.

type Simplifier

type Simplifier interface {
	Simplify(g Geometry) Geometry
	LineString(ls LineString) LineString
	MultiLineString(mls MultiLineString) MultiLineString
	Ring(r Ring) Ring
	Polygon(p Polygon) Polygon
	MultiPolygon(mp MultiPolygon) MultiPolygon
	Collection(c Collection) Collection
}

A Simplifier is something that can simplify geometry.

Directories

Path Synopsis
Package clip is a library for clipping geometry to a bounding box.
Package clip is a library for clipping geometry to a bounding box.
smartclip
Package smartclip performs a more advanced clipping algorithm so it can deal with correctly oriented open rings and polygon.
Package smartclip performs a more advanced clipping algorithm so it can deal with correctly oriented open rings and polygon.
encoding
mvt
wkb
Package wkb is for decoding ESRI's Well Known Binary (WKB) format sepcification at https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry#Well-known_binary
Package wkb is for decoding ESRI's Well Known Binary (WKB) format sepcification at https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry#Well-known_binary
wkt
Package geo computes properties on geometries assuming they are lon/lat data.
Package geo computes properties on geometries assuming they are lon/lat data.
Package geojson is a library for encoding and decoding GeoJSON into Go structs using the geometries in the orb package.
Package geojson is a library for encoding and decoding GeoJSON into Go structs using the geometries in the orb package.
Package maptile defines a Tile type and methods to work with web map projected tile data.
Package maptile defines a Tile type and methods to work with web map projected tile data.
tilecover
Package tilecover computes the covering set of tiles for an orb.Geometry.
Package tilecover computes the covering set of tiles for an orb.Geometry.
Package planar computes properties on geometries assuming they are in 2d euclidean space.
Package planar computes properties on geometries assuming they are in 2d euclidean space.
Package project defines projections to and from Mercator and WGS84 along with helpers to apply them to orb geometry types.
Package project defines projections to and from Mercator and WGS84 along with helpers to apply them to orb geometry types.
Package quadtree implements a quadtree using rectangular partitions.
Package quadtree implements a quadtree using rectangular partitions.
Package resample has a couple functions for resampling line geometry into more or less evenly spaces points.
Package resample has a couple functions for resampling line geometry into more or less evenly spaces points.
Package simplify implements several reducing/simplifying functions for `orb.Geometry` types.
Package simplify implements several reducing/simplifying functions for `orb.Geometry` types.
internal

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL