### 12.17.13 空间便利函数

本节中的函数提供了对几何值的便捷操作。

除非另有说明，本节中的函数按如下方式处理其几何参数：

-   如果有任何论据`空值`，返回值为`空值`.

-   如果任何几何参数不是语法上格式良好的几何，则[`ER_GIS_INVALID_DATA`](https://dev.mysql.com/doc/mysql-errors/8.0/en/server-error-reference.html#error_er_gis_invalid_data)发生错误。

-   如果任何几何参数是未定义的空间参考系统 (SRS) 中的语法结构良好的几何，则[`ER_SRS_NOT_FOUND`](https://dev.mysql.com/doc/mysql-errors/8.0/en/server-error-reference.html#error_er_srs_not_found)发生错误。

-   对于采用多个几何参数的函数，如果这些参数不在同一个 SRS 中，则[`ER_GIS_DIFFERENT_SRIDS`](https://dev.mysql.com/doc/mysql-errors/8.0/en/server-error-reference.html#error_er_gis_different_srids)发生错误。

-   否则，返回值为非`空值`.

    这些便利功能可用：

-   [](<>)

    [`ST_Distance_Sphere(*`g1`*, *`g2`* [, *`半径`*])`](spatial-convenience-functions.html#function_st-distance-sphere)

    [](<>)

    返回之间的最小球面距离`观点`要么`多点`球体上的参数，以米为单位。（对于通用距离计算，请参阅[`ST_Distance()`](spatial-relation-functions-object-shapes.html#function_st-distance)功能。）可选的*`半径`*参数应以米为单位。

    如果两个几何参数都是有效的笛卡尔`观点`要么`多点`SRID 0 中的值，返回值是具有提供半径的球体上两个几何形状之间的最短距离。如果省略，则默认半径为 6,370,986 米，点 X 和 Y 坐标分别解释为经度和纬度，以度为单位。

    如果两个几何参数都有效`观点`要么`多点`在地理空间参考系统 (SRS) 中的值，返回值是具有提供半径的球体上两个几何图形之间的最短距离。如果省略，则默认半径等于平均半径，定义为 (2a+b)/3，其中 a 是 SRS 的长半轴，b 是短半轴。

    [`ST_Distance_Sphere()`](spatial-convenience-functions.html#function_st-distance-sphere)如本节介绍中所述处理其参数，但有以下例外：

    -   支持的几何参数组合是`观点`和`观点`， 要么`观点`和`多点`（以任何参数顺序）。如果至少有一个几何既不是`观点`也不`多点`, 其 SRID 为 0, 一个[`ER_NOT_IMPLEMENTED_FOR_CARTESIAN_SRS`](https://dev.mysql.com/doc/mysql-errors/8.0/en/server-error-reference.html#error_er_not_implemented_for_cartesian_srs)发生错误。如果至少有一个几何既不是`观点`也不`多点`, 它的 SRID 指的是一个地理 SRS, 一个[`ER_NOT_IMPLEMENTED_FOR_GEOGRAPHIC_SRS`](https://dev.mysql.com/doc/mysql-errors/8.0/en/server-error-reference.html#error_er_not_implemented_for_geographic_srs)发生错误。如果任何几何图形指的是投影的 SRS，则[`ER_NOT_IMPLEMENTED_FOR_PROJECTED_SRS`](https://dev.mysql.com/doc/mysql-errors/8.0/en/server-error-reference.html#error_er_not_implemented_for_projected_srs)发生错误。

    -   如果任何参数的经度或纬度超出范围，则会发生错误：

        -   如果经度值不在 (−180, 180] 范围内，则[`ER_GEOMETRY_PARAM_LONGITUDE_OUT_OF_RANGE`](https://dev.mysql.com/doc/mysql-errors/8.0/en/server-error-reference.html#error_er_geometry_param_longitude_out_of_range)发生错误（[`ER_LONGITUDE_OUT_OF_RANGE`](https://dev.mysql.com/doc/mysql-errors/8.0/en/server-error-reference.html#error_er_longitude_out_of_range)在 MySQL 8.0.12 之前）。

        -   如果纬度值不在范围内[−90, 90]， 一个[`ER_GEOMETRY_PARAM_LATITUDE_OUT_OF_RANGE`](https://dev.mysql.com/doc/mysql-errors/8.0/en/server-error-reference.html#error_er_geometry_param_latitude_out_of_range)发生错误（[`ER_LATITUDE_OUT_OF_RANGE`](https://dev.mysql.com/doc/mysql-errors/8.0/en/server-error-reference.html#error_er_latitude_out_of_range)在 MySQL 8.0.12 之前）。

            显示的范围以度为单位。如果 SRS 使用另一个单位，则范围使用其单位中的相应值。由于浮点运算，确切的范围限制略有偏差。

    -   如果*`半径`*论据存在但不是肯定的，一个[`ER_NONPOSITIVE_RADIUS`](https://dev.mysql.com/doc/mysql-errors/8.0/en/server-error-reference.html#error_er_nonpositive_radius)发生错误。

    -   如果距离超出双精度数的范围，则[`ER_STD_OVERFLOW_ERROR`](https://dev.mysql.com/doc/mysql-errors/8.0/en/server-error-reference.html#error_er_std_overflow_error)发生错误。

    ```
    mysql> SET @pt1 = ST_GeomFromText('POINT(0 0)');
    mysql> SET @pt2 = ST_GeomFromText('POINT(180 0)');
    mysql> SELECT ST_Distance_Sphere(@pt1, @pt2);
    +--------------------------------+
    | ST_Distance_Sphere(@pt1, @pt2) |
    +--------------------------------+
    |             20015042.813723423 |
    +--------------------------------+
    ```

-   [](<>)

    [`ST_IsValid(*`g`*)`](spatial-convenience-functions.html#function_st-isvalid)

    [](<>)

    如果参数在几何上有效，则返回 1，如果参数在几何上无效，则返回 0。几何有效性由 OGC 规范定义。

    唯一有效的空几何以空几何集合值的形式表示。[`ST_IsValid()`](spatial-convenience-functions.html#function_st-isvalid)在这种情况下返回 1。MySQL 不支持 GIS`空的`值，例如`空点`.

    [`ST_IsValid()`](spatial-convenience-functions.html#function_st-isvalid)如本节介绍中所述处理其参数，但有以下例外：

    -   如果几何图形的地理 SRS 的经度或纬度超出范围，则会发生错误：

        -   如果经度值不在 (−180, 180] 范围内，则[`ER_GEOMETRY_PARAM_LONGITUDE_OUT_OF_RANGE`](https://dev.mysql.com/doc/mysql-errors/8.0/en/server-error-reference.html#error_er_geometry_param_longitude_out_of_range)发生错误（[`ER_LONGITUDE_OUT_OF_RANGE`](https://dev.mysql.com/doc/mysql-errors/8.0/en/server-error-reference.html#error_er_longitude_out_of_range)在 MySQL 8.0.12 之前）。

        -   如果纬度值不在范围内[−90, 90]， 一个[`ER_GEOMETRY_PARAM_LATITUDE_OUT_OF_RANGE`](https://dev.mysql.com/doc/mysql-errors/8.0/en/server-error-reference.html#error_er_geometry_param_latitude_out_of_range)发生错误（[`ER_LATITUDE_OUT_OF_RANGE`](https://dev.mysql.com/doc/mysql-errors/8.0/en/server-error-reference.html#error_er_latitude_out_of_range)在 MySQL 8.0.12 之前）。

            显示的范围以度为单位。如果 SRS 使用另一个单位，则范围使用其单位中的相应值。由于浮点运算，确切的范围限制略有偏差。

    ```
    mysql> SET @ls1 = ST_GeomFromText('LINESTRING(0 0,-0.00 0,0.0 0)');
    mysql> SET @ls2 = ST_GeomFromText('LINESTRING(0 0, 1 1)');
    mysql> SELECT ST_IsValid(@ls1);
    +------------------+
    | ST_IsValid(@ls1) |
    +------------------+
    |                0 |
    +------------------+
    mysql> SELECT ST_IsValid(@ls2);
    +------------------+
    | ST_IsValid(@ls2) |
    +------------------+
    |                1 |
    +------------------+
    ```

-   [](<>)

    [`ST_MakeEnvelope(*`pt1`*, *`pt2`*)`](spatial-convenience-functions.html#function_st-makeenvelope)

    [](<>)

    返回围绕两个点形成包络的矩形，作为`观点`,`线串`， 要么`多边形`.

    使用笛卡尔坐标系而不是在球体、椭球体或地球上进行计算。

    给出两点*`pt1`*和*`pt2`*,[`ST_MakeEnvelope()`](spatial-convenience-functions.html#function_st-makeenvelope)在抽象平面上创建结果几何，如下所示：

    -   如果*`pt1`*和*`pt2`*相等，结果就是重点*`pt1`*.

    -   否则，如果`(*`pt1`*, *`pt2`*)`是垂直或水平线段，结果是线段`(*`pt1`*, *`pt2`*)`.

    -   否则，结果是一个多边形，使用*`pt1`*和*`pt2`*作为对角点。

        结果几何的 SRID 为 0。

    [`ST_MakeEnvelope()`](spatial-convenience-functions.html#function_st-makeenvelope)如本节介绍中所述处理其参数，但有以下例外：

    -   如果论据不是`观点`价值观，一个[`ER_WRONG_ARGUMENTS`](https://dev.mysql.com/doc/mysql-errors/8.0/en/server-error-reference.html#error_er_wrong_arguments)发生错误。

    -   一个[`ER_GIS_INVALID_DATA`](https://dev.mysql.com/doc/mysql-errors/8.0/en/server-error-reference.html#error_er_gis_invalid_data)两个点的任意坐标值是无限的或`钠`.

    -   如果任何几何具有地理空间参考系统 (SRS) 的 SRID 值，则[`ER_NOT_IMPLEMENTED_FOR_GEOGRAPHIC_SRS`](https://dev.mysql.com/doc/mysql-errors/8.0/en/server-error-reference.html#error_er_not_implemented_for_geographic_srs)发生错误。

    ```
    mysql> SET @pt1 = ST_GeomFromText('POINT(0 0)');
    mysql> SET @pt2 = ST_GeomFromText('POINT(1 1)');
    mysql> SELECT ST_AsText(ST_MakeEnvelope(@pt1, @pt2));
    +----------------------------------------+
    | ST_AsText(ST_MakeEnvelope(@pt1, @pt2)) |
    +----------------------------------------+
    | POLYGON((0 0,1 0,1 1,0 1,0 0))         |
    +----------------------------------------+
    ```

-   [](<>)

    [`ST_简化（*`g`*, *`最大距离`*)`](spatial-convenience-functions.html#function_st-simplify)

    [](<>)

    使用 Douglas-Peucker 算法简化几何并返回相同类型的简化值。

    几何可以是任何几何类型，尽管 Douglas-Peucker 算法实际上可能不会处理所有类型。几何集合通过将其组件一一提供给简化算法进行处理，并将返回的几何作为结果放入几何集合中。

    这*`最大距离`*参数是顶点到要删除的其他段的距离（以输入坐标为单位）。简化线串此距离内的顶点将被移除。

    根据 Boost.Geometry，几何图形可能由于简化过程而变得无效，并且该过程可能会产生自相交。要检查结果的有效性，请将其传递给[`ST_IsValid()`](spatial-convenience-functions.html#function_st-isvalid).

    [`ST_Simplify()`](spatial-convenience-functions.html#function_st-simplify)如本节介绍中所述处理其参数，但有以下例外：

    -   如果*`最大距离`*论证不是肯定的，或者是`钠`， 一个[`ER_WRONG_ARGUMENTS`](https://dev.mysql.com/doc/mysql-errors/8.0/en/server-error-reference.html#error_er_wrong_arguments)发生错误。

    ```
    mysql> SET @g = ST_GeomFromText('LINESTRING(0 0,0 1,1 1,1 2,2 2,2 3,3 3)');
    mysql> SELECT ST_AsText(ST_Simplify(@g, 0.5));
    +---------------------------------+
    | ST_AsText(ST_Simplify(@g, 0.5)) |
    +---------------------------------+
    | LINESTRING(0 0,0 1,1 1,2 3,3 3) |
    +---------------------------------+
    mysql> SELECT ST_AsText(ST_Simplify(@g, 1.0));
    +---------------------------------+
    | ST_AsText(ST_Simplify(@g, 1.0)) |
    +---------------------------------+
    | LINESTRING(0 0,3 3)             |
    +---------------------------------+
    ```

-   [](<>)

    [`ST_Validate(*`g`*)`](spatial-convenience-functions.html#function_st-validate)

    [](<>)

    根据 OGC 规范验证几何。几何可以在语法上是格式正确的（WKB 值加上 SRID），但在几何上是无效的。例如，这个多边形在几何上是无效的：`多边形((0 0, 0 0, 0 0, 0 0, 0 0))`

    [`ST_Validate()`](spatial-convenience-functions.html#function_st-validate)如果它在语法上格式正确并且在几何上有效，则返回几何，`空值`如果参数在语法上不是格式正确的或在几何上无效或不是`空值`.

    [`ST_Validate()`](spatial-convenience-functions.html#function_st-validate)可用于过滤掉无效的几何数据，尽管要付出代价。对于需要不受无效数据污染的更精确结果的应用程序，这种惩罚可能是值得的。

    如果几何参数有效，则按原样返回，除非输入`多边形`要么`多多边形`有顺时针环，这些环在检查有效性之前被反转。如果几何图形有效，则返回具有反转环的值。

    唯一有效的空几何以空几何集合值的形式表示。[`ST_Validate()`](spatial-convenience-functions.html#function_st-validate)在这种情况下，直接返回它而无需进一步检查。

    从 MySQL 8.0.13 开始，[`ST_Validate()`](spatial-convenience-functions.html#function_st-validate)如本节介绍中所述处理其参数，但有以下例外：

    -   如果几何图形的地理 SRS 的经度或纬度超出范围，则会发生错误：

        -   如果经度值不在 (−180, 180] 范围内，则[`ER_GEOMETRY_PARAM_LONGITUDE_OUT_OF_RANGE`](https://dev.mysql.com/doc/mysql-errors/8.0/en/server-error-reference.html#error_er_geometry_param_longitude_out_of_range)发生错误（[`ER_LONGITUDE_OUT_OF_RANGE`](https://dev.mysql.com/doc/mysql-errors/8.0/en/server-error-reference.html#error_er_longitude_out_of_range)在 MySQL 8.0.12 之前）。

        -   如果纬度值不在范围内[−90, 90]， 一个[`ER_GEOMETRY_PARAM_LATITUDE_OUT_OF_RANGE`](https://dev.mysql.com/doc/mysql-errors/8.0/en/server-error-reference.html#error_er_geometry_param_latitude_out_of_range)发生错误（[`ER_LATITUDE_OUT_OF_RANGE`](https://dev.mysql.com/doc/mysql-errors/8.0/en/server-error-reference.html#error_er_latitude_out_of_range)在 MySQL 8.0.12 之前）。

            显示的范围以度为单位。由于浮点运算，确切的范围限制略有偏差。

        在 MySQL 8.0.13 之前，[`ST_Validate()`](spatial-convenience-functions.html#function_st-validate)如本节介绍中所述处理其参数，但有以下例外：

    -   如果几何图形在语法上不是格式正确的，则返回值为`空值`.一个[`ER_GIS_INVALID_DATA`](https://dev.mysql.com/doc/mysql-errors/8.0/en/server-error-reference.html#error_er_gis_invalid_data)不会发生错误。

    -   如果几何具有地理空间参考系统 (SRS) 的 SRID 值，则[`ER_NOT_IMPLEMENTED_FOR_GEOGRAPHIC_SRS`](https://dev.mysql.com/doc/mysql-errors/8.0/en/server-error-reference.html#error_er_not_implemented_for_geographic_srs)发生错误。

    ```
    mysql> SET @ls1 = ST_GeomFromText('LINESTRING(0 0)');
    mysql> SET @ls2 = ST_GeomFromText('LINESTRING(0 0, 1 1)');
    mysql> SELECT ST_AsText(ST_Validate(@ls1));
    +------------------------------+
    | ST_AsText(ST_Validate(@ls1)) |
    +------------------------------+
    | NULL                         |
    +------------------------------+
    mysql> SELECT ST_AsText(ST_Validate(@ls2));
    +------------------------------+
    | ST_AsText(ST_Validate(@ls2)) |
    +------------------------------+
    | LINESTRING(0 0,1 1)          |
    +------------------------------+
    ```
