geo

package
v2.4.0 Latest Latest
Warning

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

 Go to latest Published: Mar 20, 2024 License: Apache-2.0 Imports: 12 Imported by: 8

README

geo support in bleve

Latest bleve spatial capabilities are powered by spatial hierarchical tokens generated from s2geometry. You can find more details about the s2geometry basics here, and explore the extended functionality of our forked golang port of s2geometry lib here.

Users can continue to index and query geopoint field type and the existing queries like,

  • Point Distance
  • Bounded Rectangle
  • Bounded Polygon

as before.

New Spatial Field Type - geoshape

We have introduced a field type (geoshape) for representing the new spatial types.

Using the new geoshape field type, users can unblock the spatial capabilities
for the geojson shapes like,

  • Point
  • LineString
  • Polygon
  • MultiPoint
  • MultiLineString
  • MultiPolygon
  • GeometryCollection

In addition to these shapes, bleve will also support additional shapes like,

  • Circle
  • Envelope (Bounded box)

To specify GeoJSON data, use a nested field with:

  • a field named type that specifies the GeoJSON object type and the type value will be case-insensitive.
  • a field named coordinates that specifies the object's coordinates.
         "fieldName": { 
              "type": "GeoJSON Type", 
              "coordinates": <coordinates> 
           }
  • If specifying latitude and longitude coordinates, list the longitude first and then latitude.
  • Valid longitude values are between -180 and 180, both inclusive.
  • Valid latitude values are between -90 and 90, both inclusive.
  • Shapes would be internally represented as geodesics.
  • The GeoJSON specification strongly suggests splitting geometries so that neither of their parts crosses the antimeridian.

Examples for the various geojson shapes representations are as below.

Point

The following specifies a Point field in a document:

    { 
    "type": "point", 
    "coordinates": [75.05687713623047,22.53539059204079]
    }

Linestring

The following specifies a Linestring field in a document:

{ 
    "type": "linestring", 
    "coordinates": [ 
    [ 77.01416015625, 23.0797317624497], 
    [ 78.134765625, 20.385825381874263] 
    ] 
}

Polygon

The following specifies a Polygon field in a document:

{
 "type": "polygon",
 "coordinates": [ [ [ 85.605, 57.207], 
                    [ 86.396, 55.998], 
                    [ 87.033, 56.716], 
                    [ 85.605, 57.207] 
                ] ]
}

The first and last coordinates must match in order to close the polygon. And the exterior coordinates have to be in Counter Clockwise Order in a polygon. (CCW)

MultiPoint

The following specifies a Multipoint field in a document:

{
 "type": "multipoint",
 "coordinates": [
    [ -115.8343505859375, 38.45789034424927],
    [ -115.81237792968749, 38.19502155795575],
    [ -120.80017089843749, 36.54053616262899],
    [ -120.67932128906249, 36.33725319397006]
 ]
}

MultiLineString

The following specifies a MultiLineString field in a document:

{
 "type": "multilinestring",
 "coordinates": [
    [ [ -118.31726074, 35.250105158],[ -117.509765624, 35.3756141] ],
    [ [ -118.6962890, 34.624167789],[ -118.317260742, 35.03899204] ],
    [ [ -117.9492187, 35.146862906], [ -117.6745605, 34.41144164] ]
]
}

MultiPolygon

The following specifies a MultiPolygon field in a document:

{
 "type": "multipolygon",
 "coordinates": [
    [ [ [ -73.958, 40.8003 ], [ -73.9498, 40.7968 ], 
        [ -73.9737, 40.7648 ], [ -73.9814, 40.7681 ], 
        [ -73.958, 40.8003 ] ] ],


    [ [ [ -73.958, 40.8003 ], [ -73.9498, 40.7968 ], 
        [ -73.9737, 40.7648 ], [ -73.958, 40.8003 ] ] ]
 ]
}

GeometryCollection

The following specifies a GeometryCollection field in a document:

{
 "type": "geometrycollection",
 "geometries": [
    {
      "type": "multipoint",
      "coordinates": [
         [ -73.9580, 40.8003 ],
         [ -73.9498, 40.7968 ],
         [ -73.9737, 40.7648 ],
         [ -73.9814, 40.7681 ]
      ]
    },
    {
      "type": "multilinestring",
      "coordinates": [
         [ [ -73.96943, 40.78519 ], [ -73.96082, 40.78095 ] ],
         [ [ -73.96415, 40.79229 ], [ -73.95544, 40.78854 ] ],
         [ [ -73.97162, 40.78205 ], [ -73.96374, 40.77715 ] ],
         [ [ -73.97880, 40.77247 ], [ -73.97036, 40.76811 ] ]
      ]
    },
    {
      "type" : "polygon",
      "coordinates" : [
    [ [ 0 , 0 ] , [ 3 , 6 ] , [ 6 , 1 ] , [ 0 , 0 ] ],
    [ [ 2 , 2 ] , [ 3 , 3 ] , [ 4 , 2 ] , [ 2 , 2 ] ]
    ]
   }
]
}

Circle

If the user wishes to cover a circular region over the earth’s surface, then they could use this shape. A sample circular shape is as below.

{ 
 "type": "circle", 
 "coordinates": [75.05687713623047,22.53539059204079],
 "radius": "1000m"
}

Circle is specified over the center point coordinates along with the radius. Example formats supported for radius are: "5in" , "5inch" , "7yd" , "7yards", "9ft" , "9feet", "11km", "11kilometers", "3nm" "3nauticalmiles", "13mm" , "13millimeters", "15cm", "15centimeters", "17mi", "17miles" "19m" or "19meters".

If the unit cannot be determined, the entire string is parsed and the unit of meters is assumed.

Envelope

Envelope type, which consists of coordinates for upper left and lower right points of the shape to represent a bounding rectangle in the format [[minLon, maxLat], [maxLon, minLat]].

{
    "type": "envelope",
    "coordinates": [
      [72.83, 18.979],
      [78.508,17.4555]
    ]
}

GeoShape Query

Geoshape query support three types/filters of spatial querying capability across those heterogeneous types of documents indexed.

Query Structure:
{
  "query": {
    "geometry": {
      "shape": {
        "type": "<shapeType>", 
        "coordinates": [[[ ]]]
      },
      "relation": "<<filterName>>"
    }
  }
}

shapeType => can be any of the aforementioned types like Point, LineString, Polygon, MultiPoint, Geometrycollection, MultiLineString, MultiPolygon, Circle and Envelope.

filterName => can be any of the 3 types like intersects, contains and within.

Relation
FilterName Description
intersects Return all documents whose shape field intersects the query geometry.
contains Return all documents whose shape field contains the query geometry
within Return all documents whose shape field is within the query geometry.
Older Implementation

First, all of this geo code is a Go adaptation of the Lucene 5.3.2 sandbox geo support.

Notes

  • All of the APIs will use float64 for lon/lat values.
  • When describing a point in function arguments or return values, we always use the order lon, lat.
  • High level APIs will use TopLeft and BottomRight to describe bounding boxes. This may not map cleanly to min/max lon/lat when crossing the dateline. The lower level APIs will use min/max lon/lat and require the higher-level code to split boxes accordingly.

Documentation

Index

Constants

View Source 
const (
	PointType              = "point"
	MultiPointType         = "multipoint"
	LineStringType         = "linestring"
	MultiLineStringType    = "multilinestring"
	PolygonType            = "polygon"
	MultiPolygonType       = "multipolygon"
	GeometryCollectionType = "geometrycollection"
	CircleType             = "circle"
	EnvelopeType           = "envelope"
)

Variables

View Source 
var GeoBits uint = 32

GeoBits is the number of bits used for a single geo point Currently this is 32bits for lon and 32bits for lat

View Source 
var GlueBytes = []byte("##")

GlueBytes primarily for quicker filtering of docvalues during the filtering phase.

View Source 
var GlueBytesOffset = len(GlueBytes)

Functions

func BoundingBoxContains 

func BoundingBoxContains(lon, lat, minLon, minLat, maxLon, maxLat float64) bool

BoundingBoxContains checks whether the lon/lat point is within the box

func BoundingRectangleForPolygon 

func BoundingRectangleForPolygon(polygon []Point) (
	float64, float64, float64, float64, error)

func DecodeGeoHash 

func DecodeGeoHash(geoHash string) (float64, float64)

DecodeGeoHash decodes the string geohash faster with higher precision. This api is in experimental phase.

func DegreesToRadians 

func DegreesToRadians(d float64) float64

DegreesToRadians converts an angle in degrees to radians

func EncodeGeoHash 

func EncodeGeoHash(lat, lon float64) string

func ExtractCircle added in v2.3.3 

func ExtractCircle(thing interface{}) ([]float64, string, bool)

ExtractCircle takes an interface{} and tries it's best to interpret the center point coordinates and the radius for a given circle shape.

func ExtractGeoPoint 

func ExtractGeoPoint(thing interface{}) (lon, lat float64, success bool)

ExtractGeoPoint takes an arbitrary interface{} and tries it's best to interpret it is as geo point. Supported formats: Container: slice length 2 (GeoJSON) 

first element lon, second element lat

string (coordinates separated by comma, or a geohash) 

first element lat, second element lon

map[string]interface{} 

exact keys lat and lon or lng

struct 

w/exported fields case-insensitive match on lat and lon or lng

struct 

satisfying Later and Loner or Lnger interfaces

in all cases values must be some sort of numeric-like thing: int/uint/float

func ExtractGeoShapeCoordinates added in v2.3.3 

func ExtractGeoShapeCoordinates(coordValue interface{},
	typ string) ([][][][]float64, string, bool)

ExtractGeoShapeCoordinates takes an interface{} and tries it's best to interpret the coordinates for any of the given geoshape typ like a point, multipoint, linestring, multilinestring, polygon, multipolygon,

func ExtractGeometryCollection added in v2.3.3 

func ExtractGeometryCollection(thing interface{}) ([][][][][]float64, []string, bool)

ExtractGeometryCollection takes an interface{} and tries it's best to interpret all the member geojson shapes within it.

func GetSpatialAnalyzerPlugin added in v2.3.3 

func GetSpatialAnalyzerPlugin(typ string) index.SpatialAnalyzerPlugin

GetSpatialAnalyzerPlugin retrieves the given implementation type.

func Haversin 

func Haversin(lon1, lat1, lon2, lat2 float64) float64

Haversin computes the distance between two points. This implemenation uses the sloppy math implemenations which trade off accuracy for performance. The distance returned is in kilometers.

func MortonHash 

func MortonHash(lon, lat float64) uint64

MortonHash computes the morton hash value for the provided geo point This point is ordered as lon, lat.

func MortonUnhashLat 

func MortonUnhashLat(hash uint64) float64

MortonUnhashLat extracts the latitude value from the provided morton hash.

func MortonUnhashLon 

func MortonUnhashLon(hash uint64) float64

MortonUnhashLon extracts the longitude value from the provided morton hash.

func NewBoundedPolygon added in v2.3.3 

func NewBoundedPolygon(coordinates []Point) *boundedPolygon

func NewBoundedRectangle added in v2.3.3 

func NewBoundedRectangle(minLat, minLon, maxLat,
	maxLon float64) *boundedRectangle

func NewGeoCircle added in v2.3.3 

func NewGeoCircle(points []float64, radius string) index.GeoJSON

func NewGeoCircleShape added in v2.3.3 

func NewGeoCircleShape(cp []float64,
	radius string) (index.GeoJSON, []byte, error)

NewGeoCircleShape instantiate a circle shape and prefix the byte contents with certain glue bytes that can be used later while filering the doc values.

func NewGeoEnvelope added in v2.3.3 

func NewGeoEnvelope(points [][]float64) index.GeoJSON

func NewGeoJsonLinestring added in v2.3.3 

func NewGeoJsonLinestring(points [][]float64) index.GeoJSON

func NewGeoJsonMultiPoint added in v2.3.3 

func NewGeoJsonMultiPoint(points [][]float64) index.GeoJSON

func NewGeoJsonMultiPolygon added in v2.3.3 

func NewGeoJsonMultiPolygon(points [][][][]float64) index.GeoJSON

func NewGeoJsonMultilinestring added in v2.3.3 

func NewGeoJsonMultilinestring(points [][][]float64) index.GeoJSON

func NewGeoJsonPoint added in v2.3.3 

func NewGeoJsonPoint(points []float64) index.GeoJSON

func NewGeoJsonPolygon added in v2.3.3 

func NewGeoJsonPolygon(points [][][]float64) index.GeoJSON

func NewGeoJsonShape added in v2.3.3 

func NewGeoJsonShape(coordinates [][][][]float64, typ string) (
	index.GeoJSON, []byte, error)

func NewGeometryCollection added in v2.3.3 

func NewGeometryCollection(coordinates [][][][][]float64,
	typs []string) (index.GeoJSON, []byte, error)

NewGeometryCollection instantiate a geometrycollection and prefix the byte contents with certain glue bytes that can be used later while filering the doc values.

func NewPointDistance added in v2.3.3 

func NewPointDistance(centerLat, centerLon,
	dist float64) *pointDistance

func ParseDistance 

func ParseDistance(d string) (float64, error)

ParseDistance attempts to parse a distance string and return distance in meters. Example formats supported: "5in" "5inch" "7yd" "7yards" "9ft" "9feet" "11km" "11kilometers" "3nm" "3nauticalmiles" "13mm" "13millimeters" "15cm" "15centimeters" "17mi" "17miles" "19m" "19meters" If the unit cannot be determined, the entire string is parsed and the unit of meters is assumed. If the number portion cannot be parsed, 0 and the parse error are returned.

func ParseDistanceUnit 

func ParseDistanceUnit(u string) (float64, error)

ParseDistanceUnit attempts to parse a distance unit and return the multiplier for converting this to meters. If the unit cannot be parsed then 0 and the error message is returned.

func ParseGeoJSONShape added in v2.3.3 

func ParseGeoJSONShape(input json.RawMessage) (index.GeoJSON, error)

func ParseGeoShapeField added in v2.3.3 

func ParseGeoShapeField(thing interface{}) (interface{}, string, error)

func RadiansToDegrees 

func RadiansToDegrees(r float64) float64

RadiansToDegrees converts an angle in radians to degress

func RectFromPointDistance 

func RectFromPointDistance(lon, lat, dist float64) (float64, float64, float64, float64, error)

func RectIntersects 

func RectIntersects(aMinX, aMinY, aMaxX, aMaxY, bMinX, bMinY, bMaxX, bMaxY float64) bool

RectIntersects checks whether rectangles a and b intersect

func RectWithin 

func RectWithin(aMinX, aMinY, aMaxX, aMaxY, bMinX, bMinY, bMaxX, bMaxY float64) bool

RectWithin checks whether box a is within box b

func RegisterSpatialAnalyzerPlugin added in v2.3.3 

func RegisterSpatialAnalyzerPlugin(plugin index.SpatialAnalyzerPlugin)

RegisterSpatialAnalyzerPlugin registers the given plugin implementation.

Types

type Point 

type Point struct {
	Lon float64 `json:"lon"`
	Lat float64 `json:"lat"`
}

Point represents a geo point.

func (*Point) Contains added in v2.3.3 

func (p *Point) Contains(s index.GeoJSON) (bool, error)

func (*Point) IndexTokens added in v2.3.3 

func (p *Point) IndexTokens(s *S2SpatialAnalyzerPlugin) []string

func (*Point) Intersects added in v2.3.3 

func (p *Point) Intersects(s index.GeoJSON) (bool, error)

func (*Point) QueryTokens added in v2.3.3 

func (p *Point) QueryTokens(s *S2SpatialAnalyzerPlugin) []string

func (*Point) Type added in v2.3.3 

func (p *Point) Type() string

func (*Point) Value added in v2.3.4 

func (p *Point) Value() ([]byte, error)

type S2SpatialAnalyzerPlugin added in v2.3.3 

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

S2SpatialAnalyzerPlugin is an implementation of the index.SpatialAnalyzerPlugin interface.

func (*S2SpatialAnalyzerPlugin) GetIndexTokens added in v2.3.3 

func (s *S2SpatialAnalyzerPlugin) GetIndexTokens(queryShape index.GeoJSON) []string

func (*S2SpatialAnalyzerPlugin) GetQueryTokens added in v2.3.3 

func (s *S2SpatialAnalyzerPlugin) GetQueryTokens(queryShape index.GeoJSON) []string

func (*S2SpatialAnalyzerPlugin) Type added in v2.3.3 

func (s *S2SpatialAnalyzerPlugin) Type() string

Source Files

View all Source files

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.