geobin

README

Geobin

The Geobin Object represents tightly packed geometry that is compatible with GeoJSON RFC 7946.

Specification

The purpose of this package is to provide a new binary format for Tile38 geometries. Tile38 currently uses standard Go structs that contain nested pointer, slices, arrays, etc. This new format is stored as a contiguous byte stream that can be packed inside a Pair object. It also precalcs the bbox for fast spatial indexing.

This project is a (sweet) work in progress. The API will likely change between now and Tile38 v2.0 release.

Notes

• Objects take up no more than one allocation.
• 2D Point size is 17 bytes
• 3D Point size is 25 bytes
• Objects have precalculated bboxes
• Polygon detection formulas (Intersects, Within, etc) are currently bridging the Tile38 GeoJSON package. Hopefully this will be native by Tile38 2.0 launch.

Contact

Josh Baker @tidwall

License

Geobin source code is available under the MIT License.

Documentation

Index

• func GeohashDecode(hash string) (lat, lon float64, err error)
• func GeohashEncode(lat, lon float64, precision int) (string, error)
• type BBox
• type Geometry
  • func (g Geometry) PositionCount() int
• type GeometryType
  • func (t GeometryType) String() string
• type Object
  • func BBoxFromCenter(lat float64, lon float64, meters float64) Object
  • func Make2DPoint(x, y float64) Object
  • func Make2DRect(minX, minY, maxX, maxY float64) Object
  • func Make3DPoint(x, y, z float64) Object
  • func Make3DRect(minX, minY, minZ, maxX, maxY, maxZ float64) Object
  • func MakeString(str string) Object
  • func ParseJSON(json string) Object
  • func ParseJSONWithErrors(json string) (Object, error)
  • func WrapBinary(data []byte) Object
  • func (o Object) AppendJSON(b []byte) []byte
  • func (o Object) AppendString(b []byte) []byte
  • func (o Object) BBox() BBox
  • func (o Object) Binary() []byte
  • func (g Object) CalculatedBBox() BBox
  • func (g Object) CalculatedPoint() Position
  • func (o Object) Center(transformer func(minIn, maxIn [3]float64) (minOut, maxOut [3]float64)) [3]float64
  • func (o Object) Dims() int
  • func (o Object) ExData() []byte
  • func (g Object) Geohash(precision int) (string, error)
  • func (o Object) Geometry() Geometry
  • func (o Object) GeometryType() GeometryType
  • func (g Object) Intersects(o Object) bool
  • func (g Object) IntersectsBBox(bbox BBox) bool
  • func (g Object) IsBBoxDefined() bool
  • func (o Object) IsGeometry() bool
  • func (o Object) JSON() string
  • func (o Object) Members() []byte
  • func (g Object) Nearby(center Position, meters float64) bool
  • func (o Object) Position() Position
  • func (o Object) PositionCount() int
  • func (o Object) Rect(transformer func(minIn, maxIn [3]float64) (minOut, maxOut [3]float64)) (min, max [3]float64)
  • func (o Object) SetExData(data []byte) Object
  • func (g Object) Sparse(amount byte) []Object
  • func (o Object) String() string
  • func (o Object) StringBytes() []byte
  • func (g Object) Within(o Object) bool
  • func (g Object) WithinBBox(bbox BBox) bool
• type Position
  • func (p Position) Destination(meters, bearingDegrees float64) Position
  • func (p Position) DistanceTo(position Position) float64

Functions

func GeohashDecode

func GeohashDecode(hash string) (lat, lon float64, err error)

func GeohashEncode

func GeohashEncode(lat, lon float64, precision int) (string, error)

Types

type BBox

type BBox struct {
	Min, Max Position
}

type Geometry

type Geometry struct {
	Data   []byte
	Dims   int
	Type   GeometryType
	Simple bool
}

func (Geometry) PositionCount

func (g Geometry) PositionCount() int

type GeometryType

type GeometryType byte

GeometryType represents a geojson geometry type

const (
	Unknown GeometryType = iota
	Point
	MultiPoint
	LineString
	MultiLineString
	Polygon
	MultiPolygon
	GeometryCollection
	Feature
	FeatureCollection
)

func (GeometryType) String

func (t GeometryType) String() string

type Object

type Object struct {
	// contains filtered or unexported fields
}

Object represents a packed geobin object

func BBoxFromCenter

func BBoxFromCenter(lat float64, lon float64, meters float64) Object

func Make2DPoint

func Make2DPoint(x, y float64) Object

Make2DPoint returns a simple 2D point object.

func Make2DRect

func Make2DRect(minX, minY, maxX, maxY float64) Object

Make2DRect returns a simple 2D point object.

func Make3DPoint

func Make3DPoint(x, y, z float64) Object

Make3DPoint returns a simple 3D point object.

func Make3DRect

func Make3DRect(minX, minY, minZ, maxX, maxY, maxZ float64) Object

Make3DRect returns a simple 3D rect object.

func MakeString

func MakeString(str string) Object

MakeString returns a non-geometry string object.

func ParseJSON

func ParseJSON(json string) Object

ParseJSON parses GeoJSON and returns an geobin object.

func ParseJSONWithErrors

func ParseJSONWithErrors(json string) (Object, error)

func WrapBinary

func WrapBinary(data []byte) Object

WrapBinary creates an object by wrapping data.

func (Object) AppendJSON

func (o Object) AppendJSON(b []byte) []byte

AppendJSON appends the JSON representation of the object to to the provided input bytes and returns the modified slice.

func (Object) AppendString

func (o Object) AppendString(b []byte) []byte

AppendString appends the string representation of the object to to the provided input bytes and returns the modified slice.

func (Object) BBox

func (o Object) BBox() BBox

BBox returns the bounding box of the object.

func (Object) Binary

func (o Object) Binary() []byte

Binary returns the raw geobin bytes.

func (Object) CalculatedBBox

func (g Object) CalculatedBBox() BBox

CalculatedBBox is exterior bbox containing the object.

func (Object) CalculatedPoint

func (g Object) CalculatedPoint() Position

CalculatedPoint is a point representation of the object.

func (Object) Center

func (o Object) Center(
	transformer func(minIn, maxIn [3]float64) (minOut, maxOut [3]float64),
) [3]float64

Center returns a point that represents the center point of the object's bounding box. The transformer function allows for transforming the the bouning area.

func (Object) Dims

func (o Object) Dims() int

Dims returns the number of dimensions for the geometry object. The result will be 0, 2, or 3.

func (Object) ExData

func (o Object) ExData() []byte

ExData returns the ExData component of the object.

func (Object) Geohash

func (g Object) Geohash(precision int) (string, error)

Geohash converts the object to a geohash value.

func (Object) Geometry

func (o Object) Geometry() Geometry

func (Object) GeometryType

func (o Object) GeometryType() GeometryType

GeometryType returns the geometry type for the object.

func (Object) Intersects

func (g Object) Intersects(o Object) bool

Intersects detects if the object intersects another object.

func (Object) IntersectsBBox

func (g Object) IntersectsBBox(bbox BBox) bool

IntersectsBBox detects if the object intersects a bbox.

func (Object) IsBBoxDefined

func (g Object) IsBBoxDefined() bool

IsBBoxDefined returns true if the object has a defined bbox.

func (Object) IsGeometry

func (o Object) IsGeometry() bool

IsGeometry returns true if the object is a geometry.

func (Object) JSON

func (o Object) JSON() string

JSON returns a JSON representation of the object. Geometries are converted to GeoJSON and strings are simple JSON strings.

func (Object) Members

func (o Object) Members() []byte

Members returns the Members component of the object. This is a JSON document containing the "id" and "properties" members. returns nil if no members are defined.

func (Object) Nearby

func (g Object) Nearby(center Position, meters float64) bool

Nearby detects if the object is nearby a position.

func (Object) Position

func (o Object) Position() Position

Position returns a point that represents the center point of the object.

func (Object) PositionCount

func (o Object) PositionCount() int

PositionCount returns the total number of points in the geometry.

func (Object) Rect

func (o Object) Rect(
	transformer func(minIn, maxIn [3]float64) (minOut, maxOut [3]float64),
) (min, max [3]float64)

Rect returns the bounding box of the Object. The transformer parameter allows for transforming the bounding box prior to returning.

func (Object) SetExData

func (o Object) SetExData(data []byte) Object

SetExData creates a copy of the object with the ExData component set to the specified data. The original object is not altered.

func (Object) Sparse

func (g Object) Sparse(amount byte) []Object

func (Object) String

func (o Object) String() string

String returns a string representation of the object.

func (Object) StringBytes

func (o Object) StringBytes() []byte

StringBytes returns a string representation of the object as bytes.

func (Object) Within

func (g Object) Within(o Object) bool

Within detects if the object is fully contained inside another object.

func (Object) WithinBBox

func (g Object) WithinBBox(bbox BBox) bool

WithinBBox detects if the object is fully contained inside a bbox.

type Position

type Position struct {
	X, Y, Z float64
}

Position represents an 3D point

func (Position) Destination

func (p Position) Destination(meters, bearingDegrees float64) Position

Destination calculates a new position based on the distance and bearing.

func (Position) DistanceTo

func (p Position) DistanceTo(position Position) float64

DistanceTo calculates the distance to a position