12.17.7.4 Polygon および MultiPolygon プロパティ関数

このセクションの関数は、Polygon または MultiPolygon の値のプロパティを返します。

特に指定がないかぎり、このセクションの関数はジオメトリ引数を次のように処理します:

引数が NULL の場合、またはジオメトリ引数が空のジオメトリの場合、戻り値は NULL です。
ジオメトリ引数が構文的に整形式のジオメトリでない場合は、ER_GIS_INVALID_DATA エラーが発生します。
未定義の空間参照システム (SRS) でジオメトリ引数が構文的に整形式のジオメトリである場合、ER_SRS_NOT_FOUND エラーが発生します。
複数のジオメトリ引数を取る関数では、それらの引数が同じ SRS 内にない場合、ER_GIS_DIFFERENT_SRIDS エラーが発生します。
それ以外の場合、戻り値は NULL 以外です。

ポリゴンのプロパティを取得するには、次の関数を使用できます:

ST_Area({poly|mpoly})
空間参照システムで測定された、Polygon または MultiPolygon 引数の領域を示す倍精度数値を返します。
MySQL 8.0.13 では、ST_Area() はこのセクションの概要で説明されているように引数を処理しますが、次の例外があります:
- ジオメトリがジオメトリ学的に無効な場合は、結果が未定義の領域 (任意の数値) であるか、エラーが発生します。
- ジオメトリは有効だが、Polygon または MultiPolygon オブジェクトではない場合、ER_UNEXPECTED_GEOMETRY_TYPE エラーが発生します。
- ジオメトリがデカルト SRS 内の有効な Polygon である場合、結果はポリゴンのデカルト領域になります。
- ジオメトリがデカルト SRS 内の有効な MultiPolygon である場合、結果はポリゴンのデカルト領域の合計になります。
- ジオメトリが地理 SRS 内の有効な Polygon である場合、結果はその SRS 内のポリゴンの測地領域 (平方メートル) になります。
- ジオメトリが地理 SRS 内の有効な MultiPolygon である場合、結果はその SRS 内のポリゴンの測地領域の合計 (平方メートル) になります。
- 面積計算の結果が +inf になった場合は、ER_DATA_OUT_OF_RANGE エラーが発生します。
- ジオメトリに経度または緯度が範囲外の地理 SRS がある場合、エラーが発生します:
  - 経度の値が (−180, 180]の範囲内にない場合は、ER_GEOMETRY_PARAM_LONGITUDE_OUT_OF_RANGE エラーが発生します (MySQL 8.0.12 より前の ER_LONGITUDE_OUT_OF_RANGE)。
  - 緯度の値が[−90, 90]の範囲内にない場合は、ER_GEOMETRY_PARAM_LATITUDE_OUT_OF_RANGE エラーが発生します (MySQL 8.0.12 より前の ER_LATITUDE_OUT_OF_RANGE)。
  表示される範囲は度数です。浮動小数点演算のため、正確な範囲制限はわずかに偏差します。
MySQL 8.0.13 より前では、ST_Area() はこのセクションの概要で説明されているように引数を処理しますが、次の例外があります:
- 次元 0 または 1 の引数の場合、結果は 0 です。
- ジオメトリが空の場合、戻り値は NULL ではなく 0 です。
- ジオメトリコレクションの場合、結果はすべてのコンポーネントの面積値の合計になります。ジオメトリコレクションが空の場合、その領域は 0(ゼロ) として返されます。
- ジオメトリに地理空間参照システム (SRS) の SRID 値がある場合、ER_NOT_IMPLEMENTED_FOR_GEOGRAPHIC_SRS エラーが発生します。
```
mysql> SET @poly =
       'Polygon((0 0,0 3,3 0,0 0),(1 1,1 2,2 1,1 1))';
mysql> SELECT ST_Area(ST_GeomFromText(@poly));
+---------------------------------+
| ST_Area(ST_GeomFromText(@poly)) |
+---------------------------------+
|                               4 |
+---------------------------------+

mysql> SET @mpoly =
       'MultiPolygon(((0 0,0 3,3 3,3 0,0 0),(1 1,1 2,2 2,2 1,1 1)))';
mysql> SELECT ST_Area(ST_GeomFromText(@mpoly));
+----------------------------------+
| ST_Area(ST_GeomFromText(@mpoly)) |
+----------------------------------+
|                                8 |
+----------------------------------+
```
ST_Centroid({poly|mpoly})
Polygon または MultiPolygon 引数の数学的重心を Point として返します。結果が MultiPolygon 上にある保証はありません。
この関数は、コレクション内の最上位ディメンションのコンポーネントの中心点を計算してジオメトリコレクションを処理します。このようなコンポーネントは、集中計算のために単一の MultiPolygon、MultiLineString または MultiPoint に抽出および作成されます。
ST_Centroid() は、このセクションの概要で説明されているように引数を処理しますが、次の例外があります:
- 引数が空のジオメトリコレクションであるという追加条件では、戻り値は NULL です。
- ジオメトリに地理空間参照システム (SRS) の SRID 値がある場合、ER_NOT_IMPLEMENTED_FOR_GEOGRAPHIC_SRS エラーが発生します。
```
mysql> SET @poly =
       ST_GeomFromText('POLYGON((0 0,10 0,10 10,0 10,0 0),(5 5,7 5,7 7,5 7,5 5))');
mysql> SELECT ST_GeometryType(@poly),ST_AsText(ST_Centroid(@poly));
+------------------------+--------------------------------------------+
| ST_GeometryType(@poly) | ST_AsText(ST_Centroid(@poly))              |
+------------------------+--------------------------------------------+
| POLYGON                | POINT(4.958333333333333 4.958333333333333) |
+------------------------+--------------------------------------------+
```

ST_ExteriorRing(poly)

Polygon 値 poly の外側のリングを LineString として返します。

ST_ExteriorRing() は、このセクションの概要で説明されているように引数を処理します。

mysql> SET @poly =
       'Polygon((0 0,0 3,3 3,3 0,0 0),(1 1,1 2,2 2,2 1,1 1))';
mysql> SELECT ST_AsText(ST_ExteriorRing(ST_GeomFromText(@poly)));
+----------------------------------------------------+
| ST_AsText(ST_ExteriorRing(ST_GeomFromText(@poly))) |
+----------------------------------------------------+
| LINESTRING(0 0,0 3,3 3,3 0,0 0)                    |
+----------------------------------------------------+

ST_InteriorRingN(poly, N)

Polygon 値 poly の N 番目の内側のリングを LineString として返します。リングの番号は 1 から始まります。

ST_InteriorRingN() は、このセクションの概要で説明されているように引数を処理します。

mysql> SET @poly =
       'Polygon((0 0,0 3,3 3,3 0,0 0),(1 1,1 2,2 2,2 1,1 1))';
mysql> SELECT ST_AsText(ST_InteriorRingN(ST_GeomFromText(@poly),1));
+-------------------------------------------------------+
| ST_AsText(ST_InteriorRingN(ST_GeomFromText(@poly),1)) |
+-------------------------------------------------------+
| LINESTRING(1 1,1 2,2 2,2 1,1 1)                       |
+-------------------------------------------------------+

ST_NumInteriorRing(poly), ST_NumInteriorRings(poly)

Polygon 値 poly 内の内側のリングの数を返します。

ST_NumInteriorRing() および ST_NuminteriorRings() は、このセクションの概要で説明されているように引数を処理します。

mysql> SET @poly =
       'Polygon((0 0,0 3,3 3,3 0,0 0),(1 1,1 2,2 2,2 1,1 1))';
mysql> SELECT ST_NumInteriorRings(ST_GeomFromText(@poly));
+---------------------------------------------+
| ST_NumInteriorRings(ST_GeomFromText(@poly)) |
+---------------------------------------------+
|                                           1 |
+---------------------------------------------+