14.16.9.1 Spatial Relation Functions That Use Object Shapes — MySQL 8.4

14.16.9.1 Функции пространственных отношений, использующие формы объектов

Спецификация OpenGIS определяет следующие функции для проверки отношений между двумя геометрическими значениями g1 и g2, используя точные формы объектов. Значения возврата 1 и 0 соответствуют истинному и ложному значениям соответственно, за исключением функций расстояния, которые возвращают значения расстояния.

Функции в этом разделе обнаруживают аргументы в картезианских или географических пространственных системах отсчета (SRS) и возвращают результаты, соответствующие SRS.

Если не указано иное, функции в этом разделе обрабатывают свои геометрические аргументы следующим образом:

Если какой-либо аргумент является NULL или какой-либо геометрический аргумент представляет собой пустую геометрию, значение возврата равно NULL.
Если какой-либо геометрический аргумент не является синтаксически корректной геометрией, возникает ошибка.
Если какой-либо геометрический аргумент является синтаксически корректной геометрией в неопределенной пространственной системе отсчета (SRS), возникает ошибка.
Для функций, принимающих несколько геометрических аргументов, если эти аргументы не находятся в одной и той же SRS, возникает ошибка.
Если какой-либо геометрический аргумент геометрически некорректен, результат равен истинному или ложному (не определено какое), или возникает ошибка.
Для геометрических аргументов SRS, если какой-либо аргумент имеет долготу или широту, выходящую за пределы диапазона, возникает ошибка:
- Если значение долготы не находится в диапазоне (−180, 180], возникает ошибка.
- Если значение широты не находится в диапазоне [−90, 90], возникает ошибка.
Указанные диапазоны приведены в градусах. Если SRS использует другую единицу измерения, диапазон использует соответствующие значения в этой единице. Точные пределы диапазона немного отличаются из-за арифметики с плавающей запятой.
В противном случае возвращаемое значение является не-NULL.

Некоторые функции в этом разделе допускают аргумент единицы измерения, который указывает единицу длины для возвращаемого значения. Если не указано иное, функции обрабатывают свой аргумент единицы измерения следующим образом:

Единица измерения поддерживается, если она найдена в таблице INFORMATION_SCHEMA ST_UNITS_OF_MEASURE. См. раздел 28.3.37 «Таблица INFORMATION_SCHEMA ST_UNITS_OF_MEASURE».
Если единица измерения указана, но не поддерживается MySQL, возникает ошибка.
Если указана поддерживаемая линейная единица измерения, а SRID равен 0, возникает ошибка.
Если указана поддерживаемая линейная единица измерения, а SRID не равен 0, результат возвращается в этой единице.
Если единица измерения не указана, результат возвращается в единицах SRS геометрий, будь то картезианские или географические. В настоящее время все SRS MySQL выражены в метрах.

Эти функции, использующие формы объектов, доступны для проверки отношений геометрий:

ST_Contains(g1, g2)

Возвращает 1 или 0, чтобы указать, полностью ли g1 содержит g2 (это означает, что g1 и g2 не должны пересекаться). Эта взаимосвязь является обратной той, которая проверяется функцией ST_Within().

ST_Contains() обрабатывает свои аргументы, как описано во введении к этому разделу.

mysql> SET @g1 = ST_GeomFromText('Polygon((0 0,0 3,3 3,3 0,0 0))'),
    ->     @p1 = ST_GeomFromText('Point(1 1)'),
    ->     @p2 = ST_GeomFromText('Point(3 3)'),
    ->     @p3 = ST_GeomFromText('Point(5 5)');
Query OK, 0 rows affected (0.00 sec)

mysql> SELECT
    ->   ST_Contains(@g1, @p1), ST_Within(@p1, @g1),
    ->   ST_Disjoint(@g1, @p1), ST_Intersects(@g1, @p1)\G
*************************** 1. row ***************************
  ST_Contains(@g1, @p1): 1
    ST_Within(@p1, @g1): 1
  ST_Disjoint(@g1, @p1): 0
ST_Intersects(@g1, @p1): 1
1 row in set (0.00 sec)

mysql> SELECT
    ->   ST_Contains(@g1, @p2), ST_Within(@p2, @g1),
    ->   ST_Disjoint(@g1, @p2), ST_Intersects(@g1, @p2)\G
*************************** 1. row ***************************
  ST_Contains(@g1, @p2): 0
    ST_Within(@p2, @g1): 0
  ST_Disjoint(@g1, @p2): 0
ST_Intersects(@g1, @p2): 1
1 row in set (0.00 sec)

mysql>
    -> SELECT
    ->   ST_Contains(@g1, @p3), ST_Within(@p3, @g1),
    ->   ST_Disjoint(@g1, @p3), ST_Intersects(@g1, @p3)\G
*************************** 1. row ***************************
  ST_Contains(@g1, @p3): 0
    ST_Within(@p3, @g1): 0
  ST_Disjoint(@g1, @p3): 1
ST_Intersects(@g1, @p3): 0
1 row in set (0.00 sec)

ST_Crosses(g1, g2)

Две геометрии пространственно пересекаются, если их пространственная взаимосвязь обладает следующими свойствами:
- Если g1 и g2 не являются одновременно одномерными: g1 пересекает g2, если внутренняя часть g2 имеет общие точки с внутренней частью g1, но g2 не охватывает всю внутреннюю часть g1.
- Если g1 и g2 одномерны: Если прямые пересекаются в конечном числе точек (то есть, нет общих отрезков, только отдельные общие точки).
Данная функция возвращает 1 или 0, чтобы указать, пространственно ли g1 пересекает g2.

ST_Crosses() обрабатывает свои аргументы, как описано во введении к этому разделу, за исключением того, что возвращаемое значение равно NULL для следующих дополнительных условий:
- g1 имеет размерность 2 (Polygon или MultiPolygon).
- g2 имеет размерность 1 (Point или MultiPoint).
ST_Disjoint(g1, g2)

Возвращает 1 или 0, чтобы указать, пространственно ли g1 не пересекается с g2.

ST_Disjoint() обрабатывает свои аргументы, как описано во введении к этому разделу.
ST_Distance(g1, g2 [, unit])

Возвращает расстояние между g1 и g2, измеренное в единицах длины пространственной системы координат (СК) геометрических аргументов или в единицах опционального аргумента unit, если он указан.

Данная функция обрабатывает коллекции геометрий, возвращая кратчайшее расстояние между всеми комбинациями компонентов двух геометрических аргументов.

ST_Distance() обрабатывает геометрические аргументы, как описано во введении к этому разделу, с этими исключениями:
- ST_Distance() распознает аргументы в географической (эллипсоидальной) пространственной системе координат и возвращает геодезическое расстояние по эллипсоиду. ST_Distance() поддерживает вычисление расстояний для географических аргументов СК всех типов геометрий.
- Если любой аргумент геометрически некорректен, либо результат — неопределенное расстояние (то есть, может быть любым числом), либо возникает ошибка.
- Если промежуточный или конечный результат производит NaN или отрицательное число, возникает ошибка.
ST_Distance() позволяет указать единицу линейной величины для возвращаемого значения расстояния с помощью опционального аргумента unit, который ST_Distance() обрабатывает, как описано во введении к этому разделу.
```
mysql> SET @g1 = ST_GeomFromText('POINT(1 1)');
mysql> SET @g2 = ST_GeomFromText('POINT(2 2)');
mysql> SELECT ST_Distance(@g1, @g2);
+-----------------------+
| ST_Distance(@g1, @g2) |
+-----------------------+
|    1.4142135623730951 |
+-----------------------+

mysql> SET @g1 = ST_GeomFromText('POINT(1 1)', 4326);
mysql> SET @g2 = ST_GeomFromText('POINT(2 2)', 4326);
mysql> SELECT ST_Distance(@g1, @g2);
+-----------------------+
| ST_Distance(@g1, @g2) |
+-----------------------+
|     156874.3859490455 |
+-----------------------+
mysql> SELECT ST_Distance(@g1, @g2, 'metre');
+--------------------------------+
| ST_Distance(@g1, @g2, 'metre') |
+--------------------------------+
|              156874.3859490455 |
+--------------------------------+
mysql> SELECT ST_Distance(@g1, @g2, 'foot');
+-------------------------------+
| ST_Distance(@g1, @g2, 'foot') |
+-------------------------------+
|             514679.7439273146 |
+-------------------------------+
```
Для специального случая вычисления расстояний на сфере см. функцию ST_Distance_Sphere().
ST_Equals(g1, g2)

Возвращает 1 или 0, чтобы указать, пространственно ли g1 равно g2.

ST_Equals() обрабатывает свои аргументы, как описано во введении к этому разделу, за исключением того, что не возвращает NULL для пустых геометрических аргументов.
```
mysql> SET @g1 = Point(1,1), @g2 = Point(2,2);
mysql> SELECT ST_Equals(@g1, @g1), ST_Equals(@g1, @g2);
+---------------------+---------------------+
| ST_Equals(@g1, @g1) | ST_Equals(@g1, @g2) |
+---------------------+---------------------+
|                   1 |                   0 |
+---------------------+---------------------+
```
ST_FrechetDistance(g1, g2 [, unit])

Возвращает дискретное расстояние Фреше между двумя геометриями, отражающее их сходство. Результат — число двойной точности, измеренное в единицах длины пространственной системы координат (СК) геометрических аргументов или в единицах длины аргумента unit, если этот аргумент задан.

Эта функция реализует дискретное расстояние Фреше, что означает, что оно ограничено расстояниями между точками геометрий. Например, для двух LineString аргументов рассматриваются только точки, явно указанные в геометриях. Точки на отрезках между этими точками не рассматриваются.

ST_FrechetDistance() обрабатывает геометрические аргументы, как описано во введении к этому разделу, с этими исключениями:
- Геометрии могут иметь декартову или географическую СК, но поддерживаются только LineString значения. Если аргументы находятся в одной декартовой или географической СК, но ни один из них не является LineString, возникает ошибка или , в зависимости от типа СК.
ST_FrechetDistance() обрабатывает свой опциональный аргумент unit, как описано во введении к этому разделу.
```
mysql> SET @ls1 = ST_GeomFromText('LINESTRING(0 0,0 5,5 5)');
mysql> SET @ls2 = ST_GeomFromText('LINESTRING(0 1,0 6,3 3,5 6)');
mysql> SELECT ST_FrechetDistance(@ls1, @ls2);
+--------------------------------+
| ST_FrechetDistance(@ls1, @ls2) |
+--------------------------------+
|             2.8284271247461903 |
+--------------------------------+

mysql> SET @ls1 = ST_GeomFromText('LINESTRING(0 0,0 5,5 5)', 4326);
mysql> SET @ls2 = ST_GeomFromText('LINESTRING(0 1,0 6,3 3,5 6)', 4326);
mysql> SELECT ST_FrechetDistance(@ls1, @ls2);
+--------------------------------+
| ST_FrechetDistance(@ls1, @ls2) |
+--------------------------------+
|              313421.1999416798 |
+--------------------------------+
mysql> SELECT ST_FrechetDistance(@ls1, @ls2, 'foot');
+----------------------------------------+
| ST_FrechetDistance(@ls1, @ls2, 'foot') |
+----------------------------------------+
|                     1028284.7767115477 |
+----------------------------------------+
```
ST_HausdorffDistance(g1, g2 [, unit])

Возвращает дискретное расстояние Хаусдорфа между двумя геометриями, отражающее их сходство. Результат — число двойной точности, измеренное в единицах длины пространственной системы координат (СК) геометрических аргументов или в единицах длины аргумента unit, если этот аргумент задан.

Эта функция реализует дискретное расстояние Хаусдорфа, что означает, что она ограничена расстояниями между точками геометрий. Например, для двух LineString аргументов рассматриваются только точки, явно указанные в геометриях. Точки на отрезках между этими точками не рассматриваются.

ST_HausdorffDistance() обрабатывает геометрические аргументы, как описано во введении к этому разделу, с этими исключениями:
- Если геометрические аргументы находятся в одной декартовой или географической СК, но не в поддерживаемой комбинации, возникает ошибка или , в зависимости от типа СК. Поддерживаются следующие комбинации:
  - LineString и LineString
  - Point и MultiPoint
  - LineString и MultiLineString
  - MultiPoint и MultiPoint
  - MultiLineString и MultiLineString
ST_HausdorffDistance() обрабатывает свой опциональный аргумент unit, как описано во введении к этому разделу.
```
mysql> SET @ls1 = ST_GeomFromText('LINESTRING(0 0,0 5,5 5)');
mysql> SET @ls2 = ST_GeomFromText('LINESTRING(0 1,0 6,3 3,5 6)');
mysql> SELECT ST_HausdorffDistance(@ls1, @ls2);
+----------------------------------+
| ST_HausdorffDistance(@ls1, @ls2) |
+----------------------------------+
|                                1 |
+----------------------------------+

mysql> SET @ls1 = ST_GeomFromText('LINESTRING(0 0,0 5,5 5)', 4326);
mysql> SET @ls2 = ST_GeomFromText('LINESTRING(0 1,0 6,3 3,5 6)', 4326);
mysql> SELECT ST_HausdorffDistance(@ls1, @ls2);
+----------------------------------+
| ST_HausdorffDistance(@ls1, @ls2) |
+----------------------------------+
|               111319.49079326246 |
+----------------------------------+
mysql> SELECT ST_HausdorffDistance(@ls1, @ls2, 'foot');
+------------------------------------------+
| ST_HausdorffDistance(@ls1, @ls2, 'foot') |
+------------------------------------------+
|                        365221.4264870815 |
+------------------------------------------+
```
ST_Intersects(g1, g2)

Возвращает 1 или 0, чтобы указать, пространственно ли g1 пересекает g2.

ST_Intersects() обрабатывает свои аргументы, как описано во введении к этому разделу.

ST_Overlaps(g1, g2)

Две геометрии пространственно перекрываются, если они пересекаются, и их пересечение приводит к геометрии той же размерности, но не равной ни одной из заданных геометрий.

Эта функция возвращает 1 или 0, чтобы указать, перекрывается ли g1 пространственно g2.

ST_Overlaps() обрабатывает свои аргументы, как описано во введении к этому разделу, за исключением того, что возвращаемое значение равно NULL для дополнительного условия, что размерности двух геометрий не равны.
ST_Touches(g1, g2)

Две геометрии пространственно касаются, если их внутренности не пересекаются, но граница одной из геометрий пересекает либо границу, либо внутренность другой.

Эта функция возвращает 1 или 0, чтобы указать, касается ли g1 пространственно g2.

ST_Touches() обрабатывает свои аргументы, как описано во введении к этому разделу, за исключением того, что возвращаемое значение равно NULL для дополнительного условия, что обе геометрии имеют размерность 0 (Point или MultiPoint).
ST_Within(g1, g2)

Возвращает 1 или 0, чтобы указать, находится ли g1 пространственно внутри g2. Это проверяет обратное отношение, как ST_Contains().

ST_Within() обрабатывает свои аргументы, как описано во введении к этому разделу.