orb

package module
v0.1.2 Latest Latest
Warning

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

 Go to latest Published: Feb 15, 2019 License: MIT Imports: 2 Imported by: 0

README

orb Build Status Coverage Status Go Report Card Godoc 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))

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

View Source 
var AllGeometries = []Geometry{
	nil,
	Point{},
	MultiPoint{},
	LineString{},
	MultiLineString{},
	Ring{},
	Polygon{},
	MultiPolygon{},
	Bound{},
	Collection{},

	MultiPoint(nil),
	LineString(nil),
	MultiLineString(nil),
	Ring(nil),
	Polygon(nil),
	MultiPolygon(nil),
	Collection(nil),

	Collection{Collection{Point{}}},
}

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.

Source Files

View all Source files

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
mvt/vectortile
Package vectortile is a generated protocol buffer package.
 Package vectortile is a generated protocol buffer package.
wkb
Package wkb is for decoding ESRI's Well Known Binary (WKB) format sepcification at http://edndoc.esri.com/arcsde/9.1/general_topics/wkb_representation.htm
 Package wkb is for decoding ESRI's Well Known Binary (WKB) format sepcification at http://edndoc.esri.com/arcsde/9.1/general_topics/wkb_representation.htm
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.
internal
length
mercator
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.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.