cockroach: github.com/cockroachdb/cockroach/pkg/geo/geogfn

## package geogfn

`import "github.com/cockroachdb/cockroach/pkg/geo/geogfn"`

### Constants ¶

`const SpheroidErrorFraction = 0.05`

SpheroidErrorFraction is an error fraction to compensate for using a sphere to calculate the distance for what is actually a spheroid. The distance calculation has an error that is bounded by (2 * spheroid.Flattening)%. This 5% margin is pretty safe.

### func Area¶Uses

`func Area(g *geo.Geography, useSphereOrSpheroid UseSphereOrSpheroid) (float64, error)`

Area returns the area of a given Geography.

### func Azimuth¶Uses

`func Azimuth(a *geo.Geography, b *geo.Geography) (*float64, error)`

Azimuth returns the azimuth in radians of the segment defined by the given point geometries. The azimuth is angle is referenced from north, and is positive clockwise. North = 0; East = π/2; South = π; West = 3π/2. Returns nil if the two points are the same. Returns an error if any of the two Geography items are not points.

### func BestGeomProjection¶Uses

`func BestGeomProjection(boundingRect s2.Rect) (geoprojbase.Proj4Text, error)`

BestGeomProjection translates roughly to the ST_BestSRID function in PostGIS. It attempts to find the best projection for a bounding box into an accurate geometry-type projection.

The algorithm is described by ST_Buffer/ST_Intersection documentation (paraphrased):

```It first determines the best SRID that fits the bounding box of the 2 geography objects (ST_Intersection only).
It favors a north/south pole projection, then UTM, then LAEA for smaller zones, otherwise falling back
to web mercator.
If geography objects are within one half zone UTM but not the same UTM it will pick one of those.
After the calculation is complete, it will fall back to WGS84 Geography.
```

### func Centroid¶Uses

`func Centroid(g *geo.Geography, useSphereOrSpheroid UseSphereOrSpheroid) (*geo.Geography, error)`

Centroid returns the Centroid of a given Geography.

NOTE: In the case of (Multi)Polygon Centroid result, it doesn't mirror with PostGIS's result. We are using the same algorithm of dividing into triangles. However, The PostGIS implementation differs as it cuts triangles in a different way - namely, it fixes the first point in the exterior ring as the first point of the triangle, whereas we always update the reference point to be the first point of the ring when moving from one ring to another.

Ideally, both implementations should provide the same result. However, the centroid of the triangles is the vectorized mean of all the points, not the actual projection in the Spherical surface, which causes a small inaccuracies. This inaccuracy will eventually grow if there is a substantial number of a triangle with a larger area.

### func CoveredBy¶Uses

`func CoveredBy(a *geo.Geography, b *geo.Geography) (bool, error)`

CoveredBy returns whether geography A is covered by geography B. See Covers for limitations.

### func Covers¶Uses

`func Covers(a *geo.Geography, b *geo.Geography) (bool, error)`

Covers returns whether geography A covers geography B.

This calculation is done on the sphere.

Due to minor inaccuracies and lack of certain primitives in S2, precision for Covers will be for up to 1cm.

Current limitations (which are also limitations in PostGIS): * POLYGON/LINESTRING only works as "contains" - if any point of the LINESTRING

```touches the boundary of the polygon, we will return false but should be true - e.g.
SELECT st_covers(
'multipolygon(((0.0 0.0, 1.0 0.0, 1.0 1.0, 0.0 1.0, 0.0 0.0)), ((1.0 0.0, 2.0 0.0, 2.0 1.0, 1.0 1.0, 1.0 0.0)))',
'linestring(0.0 0.0, 1.0 0.0)'::geography
);
```

* Furthermore, LINESTRINGS that are covered in multiple POLYGONs inside

```MULTIPOLYGON but NOT within a single POLYGON in the MULTIPOLYGON
currently return false but should be true, e.g.
SELECT st_covers(
'multipolygon(((0.0 0.0, 1.0 0.0, 1.0 1.0, 0.0 1.0, 0.0 0.0)), ((1.0 0.0, 2.0 0.0, 2.0 1.0, 1.0 1.0, 1.0 0.0)))',
'linestring(0.0 0.0, 2.0 0.0)'::geography
);
```

### func DWithin¶Uses

```func DWithin(
a *geo.Geography, b *geo.Geography, distance float64, useSphereOrSpheroid UseSphereOrSpheroid,
) (bool, error)```

DWithin returns whether a is within distance d of b, i.e. Distance(a, b) <= d. If A or B contains empty Geography objects, this will return false.

### func Distance¶Uses

```func Distance(
a *geo.Geography, b *geo.Geography, useSphereOrSpheroid UseSphereOrSpheroid,
) (float64, error)```

Distance returns the distance between geographies a and b on a sphere or spheroid. Returns a geo.EmptyGeometryError if any of the Geographies are EMPTY.

### func Intersects¶Uses

`func Intersects(a *geo.Geography, b *geo.Geography) (bool, error)`

Intersects returns whether geography A intersects geography B. This calculation is done on the sphere. Precision of intersect measurements is up to 1cm.

### func Length¶Uses

`func Length(g *geo.Geography, useSphereOrSpheroid UseSphereOrSpheroid) (float64, error)`

Length returns length of a given Geography.

### func Perimeter¶Uses

`func Perimeter(g *geo.Geography, useSphereOrSpheroid UseSphereOrSpheroid) (float64, error)`

Perimeter returns the perimeter of a given Geography.

### func Project¶Uses

`func Project(g *geo.Geography, distance float64, azimuth s1.Angle) (*geo.Geography, error)`

Project returns calculate a projected point given a source point, a distance and a azimuth.

### func Segmentize¶Uses

`func Segmentize(geography *geo.Geography, segmentMaxLength float64) (*geo.Geography, error)`

Segmentize return modified Geography having no segment longer that given maximum segment length. This works by dividing each segment by a power of 2 to find the smallest power less than or equal to the segmentMaxLength.

### type UseSphereOrSpheroid¶Uses

`type UseSphereOrSpheroid bool`

UseSphereOrSpheroid indicates whether to use a Sphere or Spheroid for certain calculations.

```const (
// UseSpheroid indicates to use the spheroid for calculations.
UseSpheroid UseSphereOrSpheroid = true
// UseSphere indicates to use the sphere for calculations.
UseSphere UseSphereOrSpheroid = false
)```

Package geogfn imports 13 packages (graph) and is imported by 3 packages. Updated 2020-08-12. Refresh now. Tools for package owners.