文档首页
MySQL 8.4 参考手册
相关文档 下载本手册
PDF (US Ltr) - 39.9Mb
PDF (A4) - 40.0Mb
手册页 (TGZ) - 258.5Kb
手册页 (Zip) - 365.5Kb
信息 (Gzip) - 4.0Mb
信息 (Zip) - 4.0Mb


MySQL 8.4 参考手册  /  ...  /  空间便捷函数

14.16.13 空间便捷函数

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

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

  • 如果任何参数为 NULL,则返回值为 NULL

  • 如果任何几何参数不是语法上格式良好的几何图形,则会发生 ER_GIS_INVALID_DATA 错误。

  • 如果任何几何参数是在未定义的空间参考系 (SRS) 中语法上格式良好的几何图形,则会发生 ER_SRS_NOT_FOUND 错误。

  • 对于采用多个几何参数的函数,如果这些参数不在同一个 SRS 中,则会发生 ER_GIS_DIFFERENT_SRIDS 错误。

  • 否则,返回值为非 NULL

以下便捷函数可用:

  • ST_Distance_Sphere(g1, g2 [, radius])

    返回球体上 PointMultiPoint 参数之间的最小球面距离,以米为单位。(对于通用的距离计算,请参见 ST_Distance() 函数。)可选的 radius 参数应以米为单位。

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

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

    ST_Distance_Sphere() 按照本节介绍中描述的方式处理其参数,但以下情况除外:

    • 支持的几何参数组合为 PointPoint,或 PointMultiPoint(以任何参数顺序)。如果至少一个几何图形既不是 Point 也不是 MultiPoint,并且其 SRID 为 0,则会发生 ER_NOT_IMPLEMENTED_FOR_CARTESIAN_SRS 错误。如果至少一个几何图形既不是 Point 也不是 MultiPoint,并且其 SRID 引用了地理 SRS,则会发生 ER_NOT_IMPLEMENTED_FOR_GEOGRAPHIC_SRS 错误。如果任何几何图形引用了投影 SRS,则会发生 ER_NOT_IMPLEMENTED_FOR_PROJECTED_SRS 错误。

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

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

    • 如果 radius 参数存在但不是正数,则会发生 ER_NONPOSITIVE_RADIUS 错误。

    • 如果距离超过双精度数的范围,则会发生 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)

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

    唯一有效的空几何图形以空几何图形集合值的形式表示。在这种情况下,ST_IsValid() 返回 1。MySQL 不支持 GIS EMPTY 值,例如 POINT EMPTY

    ST_IsValid() 按照本节介绍中描述的方式处理其参数,但以下情况除外:

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

      显示的范围以度为单位。如果 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)

    返回围绕两个点形成的矩形,作为 PointLineStringPolygon

    计算是使用笛卡尔坐标系完成的,而不是在球体、球体或地球上完成的。

    给定两个点 pt1pt2ST_MakeEnvelope() 在像这样的抽象平面上创建结果几何图形

    • 如果 pt1pt2 相等,则结果是点 pt1

    • 否则,如果 (pt1, pt2) 是垂直或水平线段,则结果是线段 (pt1, pt2)

    • 否则,结果是以 pt1pt2 为对角点的多边形。

    结果几何图形的 SRID 为 0。

    ST_MakeEnvelope() 处理其参数的方式如本节介绍中所述,但以下情况除外

    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_Simplify(g, max_distance)

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

    几何图形可以是任何几何图形类型,尽管 Douglas-Peucker 算法实际上可能不会处理每种类型。几何图形集合的处理方式是将其组件逐个提供给简化算法,并将返回的几何图形放入几何图形集合中作为结果。

    max_distance 参数是要删除的顶点到其他线段的距离(以输入坐标为单位)。将删除此距离内简化线串的顶点。

    根据 Boost.Geometry,几何图形可能会因简化过程而变得无效,并且该过程可能会创建自相交。要检查结果的有效性,请将其传递给 ST_IsValid()

    ST_Simplify() 处理其参数的方式如本节介绍中所述,但以下情况除外

    • 如果 max_distance 参数不是正数或为 NaN,则会出现 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)

    根据 OGC 规范验证几何图形。几何图形的语法可以是正确的(WKB 值加 SRID),但几何图形无效。例如,此多边形的几何图形无效:POLYGON((0 0, 0 0, 0 0, 0 0, 0 0))

    如果几何图形在语法上格式正确且几何图形有效,则 ST_Validate() 返回该几何图形;如果参数在语法上格式不正确、几何图形无效或为 NULL,则返回 NULL

    ST_Validate() 可用于过滤掉无效的几何图形数据,尽管需要付出一定的代价。对于需要不受无效数据影响的更精确结果的应用程序来说,这种代价可能是值得的。

    如果几何图形参数有效,则按原样返回,但如果输入的 PolygonMultiPolygon 具有顺时针环,则在检查有效性之前会反转这些环。如果几何图形有效,则返回具有反转环的值。

    唯一有效的空几何图形以空几何图形集合值的 형태 来表示。在这种情况下,ST_Validate() 会直接返回它,而无需 further 检查。

    ST_Validate() 处理其参数的方式如本节介绍中所述,但以下情况除外

    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)          |
    +------------------------------+