地理空间函数

地理空间函数

以ST_前缀开头的openLooKeng 地理空间函数支持SQL/MM规范，并符合开放地理空间联盟(OGC)的OpenGIS规范。因此，许多openLooKeng地理空间函数要求（更准确地说是假定）所操作的几何图形是简单且有效的。例如，计算在外部定义了一个洞的多边形的面积或者通过非简单边界线构造一个多边形是没有意义的。

openLooKeng地理空间函数支持熟知文本(WKT)和熟知二进制(WKB)形式的空间对象：

POINT (0 0)
LINESTRING (0 0, 1 1, 1 2)
POLYGON ((0 0, 4 0, 4 4, 0 4, 0 0), (1 1, 2 1, 2 2, 1 2, 1 1))
MULTIPOINT (0 0, 1 2)
MULTILINESTRING ((0 0, 1 1, 1 2), (2 3, 3 2, 5 4))
MULTIPOLYGON (((0 0, 4 0, 4 4, 0 4, 0 0), (1 1, 2 1, 2 2, 1 2, 1 1)), ((-1 -1, -1 -2, -2 -2, -2 -1, -1 -1)))
GEOMETRYCOLLECTION (POINT(2 3), LINESTRING (2 3, 3 4))

使用ST_GeometryFromText和ST_GeomFromBinary函数可以从WKT或WKB创建几何对象。

SphericalGeography类型提供对地理坐标（有时称为大地坐标、lat/lon或lon/lat）上表示的空间特征的原生支持。地理坐标是以角度单位（角度）表示的球面坐标。

Geometry类型的基础是平面。平面上两点之间的最短路径是一条直线。这意味着可以使用笛卡尔数学知识和直线向量来计算几何计算（面积、距离、长度、交点等）。

SphericalGeography类型的基础是球面。球面上两点之间的最短路径是一个大圆弧。这意味着必须使用更复杂的数学知识在球面上进行地理计算（面积、距离、长度、交点等）计算。不支持需要考虑世界实际呈球形的精确测量。

测量函数ST_Distance和ST_Length的返回值以米为单位；ST_Area的返回值以平方米为单位。

使用to_spherical_geography()函数可以将几何对象转换为地理对象。

例如，在欧几里得平面上ST_Distance(ST_Point(-71.0882, 42.3607), ST_Point(-74.1197, 40.6976))返回3.4577并且该值与传入的值具有相同的单位，而ST_Distance(to_spherical_geography(ST_Point(-71.0882, 42.3607)), to_spherical_geography(ST_Point(-74.1197, 40.6976)))返回312822.179，该值以米为单位。

构造函数

ST_AsBinary(Geometry) -> varbinary

返回几何图像的WKB表示形式。

ST_AsText(Geometry) -> varchar

返回几何图像的WKT表示形式。对于空的几何图形，ST_AsText(ST_LineFromText('LINESTRING EMPTY'))将生成'MULTILINESTRING EMPTY'，ST_AsText(ST_Polygon('POLYGON EMPTY'))将生成'MULTIPOLYGON EMPTY'。

ST_GeometryFromText(varchar) -> Geometry

从WKT表示形式返回一个几何类型对象。

ST_GeomFromBinary(varbinary) -> Geometry

从WKB表示形式返回一个几何类型对象。

ST_LineFromText(varchar) -> LineString

从WKT表示形式返回一个几何类型LineString对象。

ST_LineString(array(Point)) -> LineString

返回由一个点数组形成的LineString。如果输入数组中的非空点少于两个，则返回空LineString。如果该数组中的任何元素为NULL、空或与前一个元素相同，则抛出异常。返回的几何图形可能不是简单的几何图形，例如，可能自相交或可能包含重复的顶点，具体取决于输入。

ST_MultiPoint(array(Point)) -> MultiPoint

返回通过指定的点形成的MultiPoint几何对象。如果输入数组为空，则返回NULL。如果数组中的任何元素为NULL或空，则抛出异常。如果输入数组有重复项，则返回的几何图形可能不是简单图形，可能包含重复的点。

ST_Point(double, double) -> Point

返回具有给定坐标值的几何类型Point对象。

ST_Polygon(varchar) -> Polygon

从WKT表示形式返回一个几何类型Polygon对象。

to_spherical_geography(Geometry) -> SphericalGeography

将Geometry对象转换为地球半径球面上的SphericalGeography对象。该函数仅适用于二维空间中定义的POINT、MULTIPOINT、LINESTRING、MULTILINESTRING、POLYGON和MULTIPOLYGON几何图形或此类几何图形的GEOMETRYCOLLECTION。对于输入几何形状的每个点，该函数验证point.x是否处于[-180.0, 180.0]范围之内以及point.y是否处于[-90.0, 90.0]范围之内，并且将其作为（经度、纬度）度数来构造SphericalGeography结果的形状。

to_geometry(SphericalGeography) -> Geometry

将SphericalGeography对象转换为Geometry对象。

关系测试

ST_Contains(Geometry, Geometry) -> boolean

当且仅当第二个几何图形的任何点都不位于第一个几何图形的外部，并且第一个几何图形的内部至少有一个点位于第二个几何图形的内部时返回true。

ST_Crosses(Geometry, Geometry) -> boolean

如果提供的几何图形具有一些（但不是全部）共同的内部点，则返回true。

ST_Disjoint(Geometry, Geometry) -> boolean

如果给定的几何图形未在空间中相交（即未占据相同的空间），则返回true。

ST_Equals(Geometry, Geometry) -> boolean

如果给定的几何图形表示相同的几何图形，则返回true。

ST_Intersects(Geometry, Geometry) -> boolean

如果给定的几何图形在二维空间中相交（占据任何相同的空间），则返回true；如果未相交，则返回false。

ST_Overlaps(Geometry, Geometry) -> boolean

如果给定的几何图形占据相同的空间并具有相同的尺寸，但彼此之间不完全包含，则返回true。

ST_Relate(Geometry, Geometry) -> boolean

如果第一个几何图形与第二个几何图形在空间上相关，则返回true。

ST_Touches(Geometry, Geometry) -> boolean

如果给定的几何图形至少有一个共同点，但其内部不相交，则返回true。

ST_Within(Geometry, Geometry) -> boolean

如果第一个几何图形完全位于第二个几何图形的内部，则返回true。

运算

geometry_union(array(Geometry)) -> Geometry

返回表示输入几何图形的点集并集的几何图形。该函数与array_agg相结合对输入几何图形进行首次聚集的性能可能要好于geometry_union_agg，但需要消耗更多的内存。

ST_Boundary(Geometry) -> Geometry

返回该几何图形的组合边界的闭包。

ST_Buffer(Geometry, distance) -> Geometry

返回表示与指定几何图形的距离小于等于指定距离的所有点的几何图形。

ST_Difference(Geometry, Geometry) -> Geometry

返回表示给定几何图形的点集差集的几何图形值。

ST_Envelope(Geometry) -> Geometry

返回几何图形的外接矩形。

ST_EnvelopeAsPts(Geometry) -> array(Geometry)

返回一个包含两个点的数组：几何图形的外接矩形的左下角和右上角。如果输入几何图形为空，则返回NULL。

ST_ExteriorRing(Geometry) -> Geometry

返回表示输入多边形外环的折线。

ST_Intersection(Geometry, Geometry) -> Geometry

返回表示两个几何图形的点集交集的几何图形值。

ST_SymDifference(Geometry, Geometry) -> Geometry

返回表示两个几何图形的点集对称差集的几何图形值。

ST_Union(Geometry, Geometry) -> Geometry

返回表示输入几何图形的点集并集的几何图形。

另请参见：geometry_union、geometry_union_agg

访问器

ST_Area(Geometry) -> double

返回几何图形的二维欧几里得面积。

对于Point和LineString类型，返回0.0。对于GeometryCollection类型，返回各个几何图形的面积之和。

ST_Area(SphericalGeography) -> double

返回一个多边形或多多边形的面积（以平方米为单位，使用地球的球面模型）。

ST_Centroid(Geometry) -> Geometry

返回作为几何图形的数学质心的点值。

ST_ConvexHull(Geometry) -> Geometry

返回包含所有输入几何图形的最小凸几何图形。

ST_CoordDim(Geometry) -> bigint

返回几何图形的坐标维度。

ST_Dimension(Geometry) -> bigint

返回该几何对象的固有维度，该维度必须小于等于坐标维度。

ST_Distance(Geometry, Geometry) -> double

返回两个几何图形之间的二维笛卡尔最小距离（基于空间参考），以投影单元为单位。

ST_Distance(SphericalGeography, SphericalGeography) -> double

返回两个SphericalGeography点之间的大圆距离（以米为单位）。

ST_GeometryN(Geometry, index) -> Geometry

返回给定索引处的几何元素（索引从1开始）。如果几何图形是几何图形的集合（例如GEOMETRYCOLLECTION或MULTI*），则返回给定索引处的几何图形。如果给定的索引小于1或大于集合中的元素总数，则返回NULL。使用ST_NumGeometries可以求出元素的总数。奇异几何图形（例如POINT、LINESTRING、POLYGON）被视为包含一个元素的集合。空几何图形被视为空集合。

ST_InteriorRingN(Geometry, index) -> Geometry

返回指定索引处的内环元素（索引从1开始）。如果给定的索引小于1或大于输入几何图形中内环的总数，则返回NULL。如果输入几何图形不是多边形，则抛出错误。使用 ST_NumInteriorRing可以求出元素的总数。

ST_GeometryType(Geometry) -> varchar

返回几何图形的类型。

ST_IsClosed(Geometry) -> boolean

如果折线的起点和终点重合，则返回true。

ST_IsEmpty(Geometry) -> boolean

如果该Geometry是一个空GeometryCollection、Polygon、Point等，则返回true。

ST_IsSimple(Geometry) -> boolean

如果该Geometry没有异常的几何点（如自相交或自切），则返回true。

ST_IsRing(Geometry) -> boolean

当且仅当线是闭合且简单的时返回true。

ST_IsValid(Geometry) -> boolean

当且仅当输入几何图形形状规则时返回true。使用geometry_invalid_reason可以确定几何图形形状不规则的原因。

ST_Length(Geometry) -> double

使用二维平面上的欧几里得测量返回单个折线或多折线的长度（基于空间参考），仪投影单元为单位。

ST_PointN(LineString, index) -> Point

返回在给定索引处（索引从1开始）的折线顶点。如果给定的索引小于1或大于集合中的元素总数，则返回NULL。使用ST_NumPoints可以求出元素的总数。

ST_Points(Geometry) -> array(Point)

返回包含一条折线中的点的数组。

ST_XMax(Geometry) -> double

返回几何图形边界框的X坐标最大值。

ST_YMax(Geometry) -> double

返回几何图形边界框的Y坐标最大值。

ST_XMin(Geometry) -> double

返回几何图形边界框的X坐标最小值。

ST_YMin(Geometry) -> double

返回几何图形边界框的Y坐标最小值。

ST_StartPoint(Geometry) -> point

以Point形式返回LineString几何图形的第一个点。这是ST_PointN(geometry, 1)的简化形式。

simplify_geometry(Geometry, double) -> Geometry

使用Douglas-Peucker算法返回输入几何图形的“简化”版本。将避免创建无效的推导几何图形（尤其是多边形）。

ST_EndPoint(Geometry) -> point

以Point形式返回LineString几何图形的最后一个点。这是ST_PointN(geometry, ST_NumPoints(geometry))的简化形式。

ST_X(Point) -> double

返回点的X坐标。

ST_Y(Point) -> double

返回点的Y坐标。

ST_InteriorRings(Geometry) -> Geometry

返回包含输入几何图形中的所有内环的数组，如果多边形没有内环，则返回空数组。如果输入几何图形为空，则返回NULL。如果输入几何图形不是多边形，则抛出错误。

ST_NumGeometries(Geometry) -> bigint

返回集合中几何图形的数量。如果几何图形是几何图形集合（例如GEOMETRYCOLLECTION或MULTI*），则返回几何图形的数量：对于单个几何图形，返回1；对于空几何图形，返回0。

ST_Geometries(Geometry) -> Geometry

返回包含指定集合中的几何图形的数组。如果输入几何图形不是多几何图形，则返回一个单元素数组。如果输入几何图形为空，则返回NULL。

ST_NumPoints(Geometry) -> bigint

返回几何图形中点的数量。这是对SQL/MM ST_NumPoints函数的扩展，该函数仅适用于点和折线。

ST_NumInteriorRing(Geometry) -> bigint

返回多边形内环集合的基数。

line_locate_point(LineString, Point) -> double

返回一个介于0和1之间的浮点数，该浮点数表示LineString上距离给定Point最近的点的位置（作为总二维线长的一部分）。

如果LineString或Point为空或NULL，则返回NULL。

geometry_invalid_reason(Geometry) -> varchar

返回输入几何图形无效的原因。如果输入有效，则返回NULL。

great_circle_distance(latitude1, longitude1, latitude2, longitude2)-> double

返回地球表面两点间以千米为单位的大圆距离。

聚合

convex_hull_agg(Geometry) -> Geometry

返回包含所有输入几何图形的最小凸几何图形。

geometry_union_agg(Geometry) -> Geometry

返回表示所有输入几何图形的点集并集的几何图形。

Bing图块

这些函数使几何图形和Bing图块相互转换。

bing_tile(x, y, zoom_level) -> BingTile

从XY坐标和缩放级别创建Bing图块对象。支持的缩放级别为1至23。

bing_tile(quadKey) -> BingTile

从四叉树键创建Bing图块对象。

bing_tile_at(latitude, longitude, zoom_level) -> BingTile

返回一个具有给定缩放级别的Bing图块，其中包含一个具有给定纬度和经度的点。纬度必须处于[-85.05112878, 85.05112878]范围之内。经度必须处于[-180, 180]范围之内。支持的缩放级别为1至23。

bing_tiles_around(latitude, longitude, zoom_level) -> array(BingTile)

返回围绕由纬度和经度参数指定的点且具有给定缩放级别的Bing图块集合。

bing_tiles_around(latitude, longitude, zoom_level, radius_in_km) -> array(BingTile)

返回一个在指定（纬度、经度）点周围覆盖具有指定半径（以km为单位）的圆的Bing图块（具有指定的缩放级别）最小集合。

bing_tile_coordinates(tile) -> row<x, y>

返回给定Bing图块的XY坐标。

bing_tile_polygon(tile) -> Geometry

返回给定Bing图块的多边形表示形式。

bing_tile_quadkey(tile) -> varchar

返回给定Bing图块的四叉树键。

bing_tile_zoom_level(tile) -> tinyint

返回给定Bing图块的缩放级别。

geometry_to_bing_tiles(geometry, zoom_level) -> array(BingTile)

返回在给定缩放级别完全覆盖给定几何图形的Bing图块最小集合。支持的缩放级别为1至23。