14.16.8 Spatial Operator Functions — MySQL 8.4

14.16.8 Функции пространственных операторов

OpenGIS предлагает ряд функций, которые могут создавать геометрии. Они предназначены для реализации пространственных операторов. Эти функции поддерживают все комбинации типов аргументов, кроме тех, которые неприменимы согласно спецификации Open Geospatial Consortium.

MySQL также реализует определенные функции, которые являются расширениями OpenGIS, как указано в описаниях функций. Кроме того, в разделе 14.16.7 «Функции свойств геометрии» обсуждаются несколько функций, которые строят новые геометрии из существующих. Смотрите этот раздел для описаний этих функций:

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

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

Эти функции пространственных операторов доступны:

ST_Buffer(g, d [, strategy1 [, strategy2 [, strategy3]]])

Возвращает геометрию, представляющую все точки, расстояние от которых до геометрии со значением g меньше или равно расстоянию d. Результат находится в той же СКР, что и аргумент геометрии.

Если аргумент геометрии пустой, 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)                   |
+------------------------------+
```
Если аргумент геометрии находится в декартовой СКР:
- ST_Buffer() поддерживает отрицательные расстояния для значений Polygon и MultiPolygon, а также для наборов геометрий, содержащих значения Polygon или MultiPolygon.
- Если результат уменьшается настолько, что исчезает, результат представляет собой пустую геометрию.
- Возникает ошибка для ST_Buffer() с отрицательным расстоянием для значений Point, MultiPoint, LineString и MultiLineString, а также для наборов геометрий, не содержащих значений Polygon или MultiPolygon.
Геометрии Point в географической СКР разрешены, при соблюдении следующих условий:
- Если расстояние не отрицательно и стратегии не указаны, функция возвращает географический буфер Point в его СКР. Аргумент расстояния должен быть в единицах измерения СКР (в настоящее время всегда в метрах).
- Если расстояние отрицательное или указана любая стратегия (кроме NULL), возникает ошибка.
Для не-Point геометрий возникает ошибка.

ST_Buffer() допускает до трех необязательных аргументов стратегии после аргумента расстояния. Стратегии влияют на вычисление буфера. Эти аргументы являются строками байтовых значений, полученных функцией ST_Buffer_Strategy(), предназначенными для стратегий точек, соединения и завершения:
- Стратегии точек применяются к Point и MultiPoint геометриям. Если стратегия точки не указана, по умолчанию используется ST_Buffer_Strategy('point_circle', 32).
- Стратегии соединения применяются к LineString, MultiLineString, Polygon и MultiPolygon геометриям. Если стратегия соединения не указана, по умолчанию используется ST_Buffer_Strategy('join_round', 32).
- Стратегии завершения применяются к LineString и MultiLineString геометриям. Если стратегия завершения не указана, по умолчанию используется ST_Buffer_Strategy('end_round', 32).
Может быть указана не более одной стратегии каждого типа, и они могут быть указаны в любом порядке.

Если стратегии буфера недействительны, возникает ошибка. Стратегии недействительны в следующих случаях:
- Указано несколько стратегий одного типа (точка, соединение или завершение).
- В качестве стратегии передано значение, которое не является стратегией (например, произвольная двоичная строка или число).
- Передана стратегия Point, и геометрия не содержит значений Point или MultiPoint.
- Передана стратегия завершения или соединения, и геометрия не содержит значений LineString, Polygon, MultiLinestring или MultiPolygon.
```
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(strategy [, points_per_circle])

Эта функция возвращает строку байтов стратегии для использования с ST_Buffer() для влияния на вычисление буфера.

Информация о стратегиях доступна на сайте Boost.org.

Первый аргумент должен быть строкой, указывающей параметр стратегии:
- Для стратегий точек допустимые значения — '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() обрабатывает свои аргументы, как описано во введении к этому разделу, за исключением:
- Если любой аргумент недействителен, возникает ошибка.
- Если первый аргумент — 'point_square' или 'end_flat', аргумент points_per_circle не должен быть задан, иначе возникает ошибка.
ST_ConvexHull(g)

Возвращает геометрию, представляющую выпуклую оболочку значения геометрии g.

Эта функция вычисляет выпуклую оболочку геометрии, сначала проверяя, являются ли вершины коллинеарными. Если да, функция возвращает линейную оболочку, в противном случае — полигональную. Эта функция обрабатывает наборы геометрий, извлекая все вершины всех компонентов набора, создавая из них значение MultiPoint и вычисляя его выпуклую оболочку.

ST_ConvexHull() обрабатывает свои аргументы, как описано во введении к этому разделу, с этим исключением:
- Возвращаемое значение — NULL для дополнительного условия, что аргументом является пустой набор геометрий.
```
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_Difference(g1, g2)

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

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. Результат находится в той же СКР, что и аргументы геометрии.

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, fractional_distance)

Эта функция принимает геометрию LineString и дробную дистанцию в диапазоне [0.0, 1.0] и возвращает Point вдоль LineString на заданной доле расстояния от начальной точки до конечной. Её можно использовать для ответа на вопросы, такие как, какая Point находится посредине дороги, описанной аргументом геометрии.

Функция реализована для геометрий LineString во всех системах пространственных координат, как декартовых, так и географических.

Если аргумент fractional_distance равен 1.0, результат может не быть точно последней точкой аргумента LineString, а точкой, близкой к ней, из-за числовых погрешностей в вычислениях приближённых значений.

Связанная функция ST_LineInterpolatePoints() принимает аналогичные аргументы, но возвращает MultiPoint, состоящую из Point значений вдоль LineString на каждой доле расстояния от начальной точки до конечной. Примеры обеих функций см. в описании ST_LineInterpolatePoints().

ST_LineInterpolatePoint() обрабатывает свои аргументы так, как описано в введении к этому разделу, с этими исключениями:
- Если аргумент геометрии не является LineString, возникает ошибка.
- Если аргумент дробной дистанции находится вне диапазона [0.0, 1.0], возникает ошибка.
ST_LineInterpolatePoint() — это расширение MySQL для OpenGIS.
ST_LineInterpolatePoints(ls, fractional_distance)

Эта функция принимает геометрию LineString и дробную дистанцию в диапазоне (0.0, 1.0] и возвращает MultiPoint, состоящую из начальной LineString точки плюс Point значений вдоль LineString на каждой доле расстояния от начальной точки до конечной. Её можно использовать для ответа на вопросы, например, какие Point значения лежат на каждой 10%-ной части дороги, описанной аргументом геометрии.

Функция реализована для геометрий LineString во всех системах пространственных координат, как декартовых, так и географических.

Если аргумент fractional_distance делит 1.0 без остатка, результат может не содержать последнюю точку аргумента LineString, а точку, близкую к ней, из-за числовых погрешностей в вычислениях приближённых значений.

Связанная функция ST_LineInterpolatePoint() принимает аналогичные аргументы, но возвращает Point вдоль LineString на заданной доле расстояния от начальной точки до конечной.

ST_LineInterpolatePoints() обрабатывает свои аргументы так, как описано в введении к этому разделу, с этими исключениями:
- Если аргумент геометрии не является LineString, возникает ошибка.
- Если аргумент дробной дистанции находится вне диапазона [0.0, 1.0], возникает ошибка.
```
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() — это расширение MySQL для OpenGIS.
ST_PointAtDistance(ls, distance)

Эта функция принимает геометрию LineString и расстояние в диапазоне [0.0, ST_Length(ls)] в единицах системы пространственных координат (СКС) LineString и возвращает Point вдоль LineString на этом расстоянии от начальной точки. Её можно использовать для ответа на вопросы, например, какое Point значение находится на расстоянии 400 метров от начала дороги, описанной аргументом геометрии.

Функция реализована для LineString геометрий во всех системах пространственных координат, как декартовых, так и географических.

ST_PointAtDistance() обрабатывает свои аргументы так, как описано в введении к этому разделу, с этими исключениями:
- Если аргумент геометрии не является LineString, возникает ошибка.
- Если аргумент расстояния находится вне диапазона [0.0, ST_Length(ls)], возникает ошибка.
ST_PointAtDistance() — это расширение MySQL для OpenGIS.
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))
```
Результат находится в той же СКС, что и аргументы геометрии.

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)

Преобразует геометрию из одной системы пространственных координат (СКС) в другую. Результатом является геометрия того же типа, что и входная геометрия, со всеми координатами, преобразованными в целевой SRID, target_srid. MySQL поддерживает все СКС, определённые EPSG, за исключением перечисленных здесь:
- EPSG 1042 Krovak Modified
- EPSG 1043 Krovak Modified (North Orientated)
- EPSG 9816 Tunisia Mining Grid
- EPSG 9826 Lambert Conic Conformal (West Orientated)
ST_Transform() обрабатывает свои аргументы так, как описано в введении к этому разделу, с этими исключениями:
- Геометрические аргументы, имеющие значение SRID для географической СКС, не приводят к ошибке.
- Если аргумент геометрии или целевого SRID имеет значение SRID, которое относится к неопределённой системе пространственных координат (СКС), возникает ошибка.
- Если геометрия находится в СКС, из которой ST_Transform() не может выполнить преобразование, возникает ошибка.
- Если целевой SRID находится в СКС, в которую ST_Transform() не может выполнить преобразование, возникает ошибка.
- Если геометрия находится в СКС, которая не является WGS 84 и не имеет пункта TOWGS84, возникает ошибка.
- Если целевой SRID находится в СКС, которая не является WGS 84 и не имеет пункта TOWGS84, возникает ошибка.
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_Union(g1, g2)

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

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