12.17.8 空间运算符函数

# 12.17.8 空间运算符函数

OpenGIS 提出了许多可以生成几何图形的函数。它们旨在实现空间运算符。这些函数支持所有参数类型组合，除了那些根据开放地理空间联盟 (opens new window)规格。

MySQL 还实现了某些作为 OpenGIS 扩展的函数，如函数描述中所述。此外，第 12.17.7 节，“几何属性函数”，讨论了从现有几何构造新几何的几个函数。有关这些功能的说明，请参阅该部分：

ST_信封（*g*)
ST_起点（*ls*)
ST_EndPoint(*ls*)
ST_PointN(*ls*, *ñ*)
ST_ExteriorRing(*聚*)
ST_InteriorRingN(*聚*, *ñ*)
ST_GeometryN(*gc*, *ñ*)

除非另有说明，否则本节中的函数按如下方式处理其几何参数：
如果有任何论据空值，返回值为空值.
如果任何几何参数不是语法上格式良好的几何，则ER_GIS_INVALID_DATA (opens new window)发生错误。
如果任何几何参数是未定义的空间参考系统 (SRS) 中的语法结构良好的几何，则ER_SRS_NOT_FOUND (opens new window)发生错误。
对于采用多个几何参数的函数，如果这些参数不在同一个 SRS 中，则ER_GIS_DIFFERENT_SRIDS (opens new window)发生错误。
如果任何几何参数具有地理 SRS 的 SRID 值并且该函数不处理地理几何，则ER_NOT_IMPLEMENTED_FOR_GEOGRAPHIC_SRS (opens new window)发生错误。
对于地理 SRS 几何参数，如果任何参数的经度或纬度超出范围，则会发生错误：
- 如果经度值不在 (−180, 180] 范围内，则ER_GEOMETRY_PARAM_LONGITUDE_OUT_OF_RANGE (opens new window)发生错误（ER_LONGITUDE_OUT_OF_RANGE (opens new window)在 MySQL 8.0.12 之前）。
- 如果纬度值不在范围内[−90, 90]，一个ER_GEOMETRY_PARAM_LATITUDE_OUT_OF_RANGE (opens new window)发生错误（ER_LATITUDE_OUT_OF_RANGE (opens new window)在 MySQL 8.0.12 之前）。
  
  显示的范围以度为单位。如果 SRS 使用另一个单位，则范围使用其单位中的相应值。由于浮点运算，确切的范围限制略有偏差。
否则，返回值为非空值.

这些空间算子函数可用：
ST_Buffer(*g*, *d* [, *策略1* [, *策略2* [, *策略3*]]])

返回一个几何图形，该几何图形表示其与几何值的距离的所有点*g小于或等于距离d*.结果与几何参数位于相同的 SRS 中。

如果几何参数为空，ST_Buffer()返回一个空几何。

如果距离为 0，ST_Buffer()返回几何参数不变：
```
mysql> SET @pt = ST_GeomFromText('POINT(0 0)');
mysql> SELECT ST_AsText(ST_Buffer(@pt, 0));
+------------------------------+
| ST_AsText(ST_Buffer(@pt, 0)) |
+------------------------------+
| POINT(0 0)                   |
+------------------------------+
```
如果几何参数在笛卡尔 SRS 中：
- ST_Buffer()支持负距离多边形和多多边形值，并且对于包含多边形要么多多边形价值观。
- 如果结果减少太多以至于消失，则结果是空几何。
- 一个ER_WRONG_ARGUMENTS (opens new window)发生错误ST_Buffer()负距离为观点, 多点, 线串，和多行字符串值，并且对于不包含任何值的几何集合多边形要么多多边形价值观。
  
  如果几何参数在地理 SRS 中：
- 在 MySQL 8.0.26 之前，一个ER_NOT_IMPLEMENTED_FOR_GEOGRAPHIC_SRS (opens new window)发生错误。
- 从 MySQL 8.0.26 开始，观点地理 SRS 中的几何图形是允许的。对于非观点几何学，一个ER_NOT_IMPLEMENTED_FOR_GEOGRAPHIC_SRS (opens new window)错误仍然发生。
  
  对于允许地理的 MySQL 版本观点几何形状：
- 如果距离不为负且未指定策略，则函数返回观点在其 SRS 中。距离参数必须采用 SRS 距离单位（目前总是米）。
- 如果距离为负或任何策略（除了空值) 被指定，一个ER_WRONG_ARGUMENTS (opens new window)发生错误。
ST_Buffer()在距离参数之后最多允许三个可选策略参数。策略影响缓冲区计算。这些参数是由ST_Buffer_Strategy()函数，用于点、连接和结束策略：
- 积分策略适用于观点和多点几何形状。如果没有指定点策略，则默认为ST_Buffer_Strategy('point_circle', 32).
- 加入策略适用于线串,多行字符串,多边形，和多多边形几何形状。如果没有指定加入策略，则默认为ST_Buffer_Strategy('join_round', 32).
- 最终策略适用于线串和多行字符串几何形状。如果没有指定结束策略，则默认为ST_Buffer_Strategy('end_round', 32).
  
  每种类型最多可以指定一个策略，并且可以以任何顺序给出它们。
  
  如果缓冲策略无效，则ER_WRONG_ARGUMENTS (opens new window)发生错误。在以下任何情况下，策略均无效：
- 指定了给定类型（点、连接或结束）的多个策略。
- 不是策略的值（例如任意二进制字符串或数字）作为策略传递。
- 一种观点策略通过并且几何不包含观点要么多点价值观。
- 传递了结束或连接策略，并且几何不包含线串, 多边形, 多线串要么多多边形价值观。
```
mysql> SET @pt = ST_GeomFromText('POINT(0 0)');
mysql> SET @pt_strategy = ST_Buffer_Strategy('point_square');
mysql> SELECT ST_AsText(ST_Buffer(@pt, 2, @pt_strategy));
+--------------------------------------------+
| ST_AsText(ST_Buffer(@pt, 2, @pt_strategy)) |
+--------------------------------------------+
| POLYGON((-2 -2,2 -2,2 2,-2 2,-2 -2))       |
+--------------------------------------------+
```
```
mysql> SET @ls = ST_GeomFromText('LINESTRING(0 0,0 5,5 5)');
mysql> SET @end_strategy = ST_Buffer_Strategy('end_flat');
mysql> SET @join_strategy = ST_Buffer_Strategy('join_round', 10);
mysql> SELECT ST_AsText(ST_Buffer(@ls, 5, @end_strategy, @join_strategy))
+---------------------------------------------------------------+
| ST_AsText(ST_Buffer(@ls, 5, @end_strategy, @join_strategy))   |
+---------------------------------------------------------------+
| POLYGON((5 5,5 10,0 10,-3.5355339059327373 8.535533905932738, |
| -5 5,-5 0,0 0,5 0,5 5))                                       |
+---------------------------------------------------------------+
```
ST_Buffer_Strategy(*战略* [, *points_per_circle*])

此函数返回一个策略字节字符串以用于ST_Buffer()影响缓冲区计算。

有关策略的信息可在Boost.org (opens new window).

第一个参数必须是指示策略选项的字符串：
- 对于点策略，允许的值为'point_circle'和'point_square'.
- 对于连接策略，允许的值为'join_round'和'join_miter'.
- 对于最终策略，允许的值为'end_round'和'end_flat'.
  
  如果第一个参数是'point_circle','join_round','join_miter'，要么'end_round'，这*points_per_circle参数必须以正数值形式给出。最大值points_per_circle*价值是的价值max_points_in_geometry系统变量。
  
  例如，参见描述ST_Buffer().
ST_Buffer_Strategy()如本节介绍中所述处理其参数，但有以下例外：
- 如果任何参数无效，则ER_WRONG_ARGUMENTS (opens new window)发生错误。
- 如果第一个参数是'point_square'要么'end_flat'，这*points_per_circle*不得给出论据或ER_WRONG_ARGUMENTS (opens new window)发生错误。
ST_ConvexHull(*g*)

返回表示几何值的凸包的几何*g*.

此函数通过首先检查其顶点是否共线来计算几何的凸包。如果是，该函数返回一个线性外壳，否则返回一个多边形外壳。此函数通过提取集合的所有组件的所有顶点来处理几何集合，创建一个多点他们的价值，并计算其凸包。

ST_ConvexHull()如本节介绍中所述处理其参数，但有以下例外：
- 返回值为空值对于参数是空几何集合的附加条件。
```
mysql> SET @g = 'MULTIPOINT(5 0,25 0,15 10,15 25)';
mysql> SELECT ST_AsText(ST_ConvexHull(ST_GeomFromText(@g)));
+-----------------------------------------------+
| ST_AsText(ST_ConvexHull(ST_GeomFromText(@g))) |
+-----------------------------------------------+
| POLYGON((5 0,25 0,15 25,5 0))                 |
+-----------------------------------------------+
```
ST_差异（*g1*, *g2*)

返回表示几何值的点集差异的几何*g1和g2*.结果与几何参数在相同的 SRS 中。

从 MySQL 8.0.26 开始，ST_Difference()允许在笛卡尔或地理 SRS 中使用参数。在 MySQL 8.0.26 之前，ST_Difference()仅允许笛卡尔 SRS 中的参数；对于地理 SRS 中的参数，ER_NOT_IMPLEMENTED_FOR_GEOGRAPHIC_SRS (opens new window)发生错误。

ST_Difference()如本节介绍中所述处理其参数。
```
mysql> SET @g1 = Point(1,1), @g2 = Point(2,2);
mysql> SELECT ST_AsText(ST_Difference(@g1, @g2));
+------------------------------------+
| ST_AsText(ST_Difference(@g1, @g2)) |
+------------------------------------+
| POINT(1 1)                         |
+------------------------------------+
```
ST_Intersection(*g1*, *g2*)

返回表示几何值的点集交集的几何*g1和g2*.结果与几何参数在相同的 SRS 中。

从 MySQL 8.0.27 开始，ST_Intersection()允许在笛卡尔或地理 SRS 中使用参数。在 MySQL 8.0.27 之前，ST_Intersection()仅允许笛卡尔 SRS 中的参数；对于地理 SRS 中的参数，ER_NOT_IMPLEMENTED_FOR_GEOGRAPHIC_SRS (opens new window)发生错误。

ST_Intersection()如本节介绍中所述处理其参数。
```
mysql> SET @g1 = ST_GeomFromText('LineString(1 1, 3 3)');
mysql> SET @g2 = ST_GeomFromText('LineString(1 3, 3 1)');
mysql> SELECT ST_AsText(ST_Intersection(@g1, @g2));
+--------------------------------------+
| ST_AsText(ST_Intersection(@g1, @g2)) |
+--------------------------------------+
| POINT(2 2)                           |
+--------------------------------------+
```
ST_LineInterpolatePoint(*ls*, *分数距离*)

这个函数需要一个线串几何和范围内的小数距离[0.0, 1.0]并返回观点沿着线串在从起点到终点的距离的给定分数处。它可以用来回答诸如哪个观点位于几何参数所描述的道路的中途。

该功能实现为线串所有空间参考系统中的几何图形，包括笛卡尔和地理。

如果*分数距离*参数为 1.0，结果可能不完全是线串论点，但由于近似值计算中的数值不准确而接近它。

一个相关的功能，ST_LineInterpolatePoints(), 接受类似的参数，但返回一个多点包含由...组成观点沿值线串在从起点到终点的距离的每一部分。有关这两个函数的示例，请参见ST_LineInterpolatePoints()描述。

ST_LineInterpolatePoint()如本节介绍中所述处理其参数，但有以下例外：
- 如果几何参数不是线串，一个ER_UNEXPECTED_GEOMETRY_TYPE (opens new window)发生错误。
- 如果小数距离参数超出范围[0.0, 1.0]，一个ER_DATA_OUT_OF_RANGE (opens new window)发生错误。
ST_LineInterpolatePoint()是 OpenGIS 的 MySQL 扩展。此功能是在 MySQL 8.0.24 中添加的。

ST_LineInterpolatePoints(*ls*, *分数距离*)

这个函数需要一个线串几何和范围内的小数距离 (0.0, 1.0] 并返回多点由线串起点，加观点沿值线串在从起点到终点的距离的每一部分。它可以用来回答诸如哪个观点值位于几何参数所描述的道路上的每 10%。

该功能实现为线串所有空间参考系统中的几何图形，包括笛卡尔和地理。

如果*分数距离*参数将 1.0 除以零余数结果可能不包含最后一个点线串论点，但由于近似值计算中的数值不准确而接近它。

一个相关的功能，ST_LineInterpolatePoint(), 接受类似的参数，但返回观点沿着线串在从起点到终点的距离的给定分数处。

ST_LineInterpolatePoints()如本节介绍中所述处理其参数，但有以下例外：

如果几何参数不是线串，一个ER_UNEXPECTED_GEOMETRY_TYPE (opens new window)发生错误。
如果小数距离参数超出范围[0.0, 1.0]，一个ER_DATA_OUT_OF_RANGE (opens new window)发生错误。

mysql> SET @ls1 = ST_GeomFromText('LINESTRING(0 0,0 5,5 5)');
mysql> SELECT ST_AsText(ST_LineInterpolatePoint(@ls1, .5));
+----------------------------------------------+
| ST_AsText(ST_LineInterpolatePoint(@ls1, .5)) |
+----------------------------------------------+
| POINT(0 5)                                   |
+----------------------------------------------+
mysql> SELECT ST_AsText(ST_LineInterpolatePoint(@ls1, .75));
+-----------------------------------------------+
| ST_AsText(ST_LineInterpolatePoint(@ls1, .75)) |
+-----------------------------------------------+
| POINT(2.5 5)                                  |
+-----------------------------------------------+
mysql> SELECT ST_AsText(ST_LineInterpolatePoint(@ls1, 1));
+---------------------------------------------+
| ST_AsText(ST_LineInterpolatePoint(@ls1, 1)) |
+---------------------------------------------+
| POINT(5 5)                                  |
+---------------------------------------------+
mysql> SELECT ST_AsText(ST_LineInterpolatePoints(@ls1, .25));
+------------------------------------------------+
| ST_AsText(ST_LineInterpolatePoints(@ls1, .25)) |
+------------------------------------------------+
| MULTIPOINT((0 2.5),(0 5),(2.5 5),(5 5))        |
+------------------------------------------------+

ST_LineInterpolatePoints()是 OpenGIS 的 MySQL 扩展。此功能是在 MySQL 8.0.24 中添加的。

ST_PointAtDistance(*ls*, *距离*)

这个函数需要一个线串几何和距离在 [0.0,ST_长度（*ls*)] 以空间参考系统 (SRS) 为单位测量线串，并返回观点沿着线串在距起点的那个距离。它可以用来回答诸如哪个观点值是距离几何参数描述的道路起点 400 米。

该功能实现为线串所有空间参考系统中的几何图形，包括笛卡尔和地理。

ST_PointAtDistance()如本节介绍中所述处理其参数，但有以下例外：
- 如果几何参数不是线串，一个ER_UNEXPECTED_GEOMETRY_TYPE (opens new window)发生错误。
- 如果小数距离参数超出范围 [0.0,ST_长度（*ls*)]，一个ER_DATA_OUT_OF_RANGE (opens new window)发生错误。
ST_PointAtDistance()是 OpenGIS 的 MySQL 扩展。此功能是在 MySQL 8.0.24 中添加的。

ST_SymDifference(*g1*, *g2*)

返回表示几何值的点集对称差的几何*g1和g2*，其定义为：

g1 symdifference g2 := (g1 union g2) difference (g1 intersection g2)

或者，在函数调用表示法中：

ST_SymDifference(g1, g2) = ST_Difference(ST_Union(g1, g2), ST_Intersection(g1, g2))

结果与几何参数在相同的 SRS 中。

从 MySQL 8.0.27 开始，ST_SymDifference()允许在笛卡尔或地理 SRS 中使用参数。在 MySQL 8.0.27 之前，ST_SymDifference()仅允许笛卡尔 SRS 中的参数；对于地理 SRS 中的参数，ER_NOT_IMPLEMENTED_FOR_GEOGRAPHIC_SRS (opens new window)发生错误。

ST_SymDifference()如本节介绍中所述处理其参数。

mysql> SET @g1 = ST_GeomFromText('MULTIPOINT(5 0,15 10,15 25)');
mysql> SET @g2 = ST_GeomFromText('MULTIPOINT(1 1,15 10,15 25)');
mysql> SELECT ST_AsText(ST_SymDifference(@g1, @g2));
+---------------------------------------+
| ST_AsText(ST_SymDifference(@g1, @g2)) |
+---------------------------------------+
| MULTIPOINT((1 1),(5 0))               |
+---------------------------------------+

ST_Transform(*g*, *target_srid*)

将几何图形从一个空间参考系统 (SRS) 转换为另一个。返回值是与输入几何具有相同类型的几何，所有坐标都转换为目标 SRID，target_srid.转换支持仅限于地理 SRS，除非几何参数的 SRID 与目标 SRID 值相同，在这种情况下，返回值是任何有效 SRS 的输入几何。

ST_Transform()如本节介绍中所述处理其参数，但有以下例外：
- 具有地理 SRS 的 SRID 值的几何参数不会产生错误。
- 如果几何或目标 SRID 参数具有引用未定义空间参考系统 (SRS) 的 SRID 值，则ER_SRS_NOT_FOUND (opens new window)发生错误。
- 如果几何在 SRS 中ST_Transform()不能从，一个ER_TRANSFORM_SOURCE_SRS_NOT_SUPPORTED (opens new window)发生错误。
- 如果目标 SRID 在 SRS 中ST_Transform()不能转换为，一个ER_TRANSFORM_TARGET_SRS_NOT_SUPPORTED (opens new window)发生错误。
- 如果几何位于不是 WGS 84 且没有 TOWGS84 子句的 SRS 中，则ER_TRANSFORM_SOURCE_SRS_MISSING_TOWGS84 (opens new window)发生错误。
- 如果目标 SRID 位于不是 WGS 84 且没有 TOWGS84 子句的 SRS 中，则ER_TRANSFORM_TARGET_SRS_MISSING_TOWGS84 (opens new window)发生错误。
ST_SRID(*g*, *target_srid*)和ST_Transform(*g*, *target_srid*)区别如下：
- ST_SRID()更改几何 SRID 值而不转换其坐标。
- ST_Transform()除了更改其 SRID 值之外，还转换几何坐标。
```
mysql> SET @p = ST_GeomFromText('POINT(52.381389 13.064444)', 4326);
mysql> SELECT ST_AsText(@p);
+----------------------------+
| ST_AsText(@p)              |
+----------------------------+
| POINT(52.381389 13.064444) |
+----------------------------+
mysql> SET @p = ST_Transform(@p, 4230);
mysql> SELECT ST_AsText(@p);
+---------------------------------------------+
| ST_AsText(@p)                               |
+---------------------------------------------+
| POINT(52.38208611407426 13.065520672345304) |
+---------------------------------------------+
```
ST_联合（*g1*, *g2*)

返回表示几何值的点集并集的几何*g1和g2*.结果与几何参数在相同的 SRS 中。

从 MySQL 8.0.26 开始，ST_Union()允许在笛卡尔或地理 SRS 中使用参数。在 MySQL 8.0.26 之前，ST_Union()仅允许笛卡尔 SRS 中的参数；对于地理 SRS 中的参数，ER_NOT_IMPLEMENTED_FOR_GEOGRAPHIC_SRS (opens new window)发生错误。

ST_Union()如本节介绍中所述处理其参数。
```
mysql> SET @g1 = ST_GeomFromText('LineString(1 1, 3 3)');
mysql> SET @g2 = ST_GeomFromText('LineString(1 3, 3 1)');
mysql> SELECT ST_AsText(ST_Union(@g1, @g2));
+--------------------------------------+
| ST_AsText(ST_Union(@g1, @g2))        |
+--------------------------------------+
| MULTILINESTRING((1 1,3 3),(1 3,3 1)) |
+--------------------------------------+
```

← 12.17.7.5 GeometryCollection 属性函数 12.17.9 测试几何对象之间空间关系的函数 →