#### 12.16.5.2 `Geometry` Property Functions

12.16.5.2.1 General Geometry Functions
12.16.5.2.2 `Point` Functions
12.16.5.2.3 `LineString` Functions
12.16.5.2.4 `MultiLineString` Functions
12.16.5.2.5 `Polygon` Functions
12.16.5.2.6 `MultiPolygon` Functions
12.16.5.2.7 `GeometryCollection` Functions

Each function that belongs to this group takes a geometry value as its argument and returns some quantitative or qualitative property of the geometry. Some functions restrict their argument type. Such functions return `NULL` if the argument is of an incorrect geometry type. For example, `Area()` returns `NULL` if the object type is neither `Polygon` nor `MultiPolygon`.

##### 12.16.5.2.1 General Geometry Functions

The functions listed in this section do not restrict their argument and accept a geometry value of any type.

• Returns the inherent dimension of the geometry value `g`. The result can be –1, 0, 1, or 2. The meaning of these values is given in Section 12.16.2.2, “Class `Geometry`.

```mysql> `SELECT Dimension(GeomFromText('LineString(1 1,2 2)'));`
+------------------------------------------------+
| Dimension(GeomFromText('LineString(1 1,2 2)')) |
+------------------------------------------------+
|                                              1 |
+------------------------------------------------+
```
• Returns the Minimum Bounding Rectangle (MBR) for the geometry value `g`. The result is returned as a `Polygon` value.

The polygon is defined by the corner points of the bounding box:

```POLYGON((MINX MINY, MAXX MINY, MAXX MAXY, MINX MAXY, MINX MINY))
```
```mysql> `SELECT AsText(Envelope(GeomFromText('LineString(1 1,2 2)')));`
+-------------------------------------------------------+
| AsText(Envelope(GeomFromText('LineString(1 1,2 2)'))) |
+-------------------------------------------------------+
| POLYGON((1 1,2 1,2 2,1 2,1 1))                        |
+-------------------------------------------------------+
```
• Returns as a binary string the name of the geometry type of which the geometry instance `g` is a member. The name corresponds to one of the instantiable `Geometry` subclasses.

```mysql> `SELECT GeometryType(GeomFromText('POINT(1 1)'));`
+------------------------------------------+
| GeometryType(GeomFromText('POINT(1 1)')) |
+------------------------------------------+
| POINT                                    |
+------------------------------------------+
```
• Returns an integer indicating the Spatial Reference System ID for the geometry value `g`.

In MySQL, the SRID value is just an integer associated with the geometry value. All calculations are done assuming Euclidean (planar) geometry.

```mysql> `SELECT SRID(GeomFromText('LineString(1 1,2 2)',101));`
+-----------------------------------------------+
| SRID(GeomFromText('LineString(1 1,2 2)',101)) |
+-----------------------------------------------+
|                                           101 |
+-----------------------------------------------+
```

The OpenGIS specification also defines the following functions, which MySQL does not implement:

• Returns a geometry that is the closure of the combinatorial boundary of the geometry value `g`.

• This function is a placeholder that returns 0 for any valid geometry value, 1 for any invalid geometry value or `NULL`.

MySQL does not support GIS `EMPTY` values such as `POINT EMPTY`.

• In MySQL 5.0, this function is a placeholder that always returns 0.

The description of each instantiable geometric class given earlier in the chapter includes the specific conditions that cause an instance of that class to be classified as not simple. (See Section 12.16.2.1, “The Geometry Class Hierarchy”.)

##### 12.16.5.2.2 `Point` Functions

A `Point` consists of X and Y coordinates, which may be obtained using the following functions:

• Returns the X-coordinate value for the `Point` object `p` as a double-precision number.

```mysql> `SELECT X(POINT(56.7, 53.34));`
+-----------------------+
| X(POINT(56.7, 53.34)) |
+-----------------------+
|                  56.7 |
+-----------------------+
```
• Returns the Y-coordinate value for the `Point` object `p` as a double-precision number.

```mysql> `SELECT Y(POINT(56.7, 53.34));`
+-----------------------+
| Y(POINT(56.7, 53.34)) |
+-----------------------+
|                 53.34 |
+-----------------------+
```
##### 12.16.5.2.3 `LineString` Functions

A `LineString` consists of `Point` values. You can extract particular points of a `LineString`, count the number of points that it contains, or obtain its length.

• Returns the `Point` that is the endpoint of the `LineString` value `ls`.

```mysql> `SET @ls = 'LineString(1 1,2 2,3 3)';`
mysql> `SELECT AsText(EndPoint(GeomFromText(@ls)));`
+-------------------------------------+
| AsText(EndPoint(GeomFromText(@ls))) |
+-------------------------------------+
| POINT(3 3)                          |
+-------------------------------------+
```
• Returns as a double-precision number the length of the `LineString` value `ls` in its associated spatial reference.

```mysql> `SET @ls = 'LineString(1 1,2 2,3 3)';`
mysql> `SELECT GLength(GeomFromText(@ls));`
+----------------------------+
| GLength(GeomFromText(@ls)) |
+----------------------------+
|            2.8284271247462 |
+----------------------------+
```

`GLength()` is a nonstandard name. It corresponds to the OpenGIS `Length()` function.

• Returns 1 if the `LineString` value `ls` is closed (that is, its `StartPoint()` and `EndPoint()` values are the same) and is simple (does not pass through the same point more than once). Returns 0 if `ls` is not closed, and –1 if it is `NULL`.

```mysql> `SET @ls1 = 'LineString(1 1,2 2,3 3,2 2)';`
Query OK, 0 rows affected (0.00 sec)

mysql> `SET @ls2 = 'LineString(1 1,2 2,3 3,1 1)';`
Query OK, 0 rows affected (0.00 sec)

mysql> `SELECT IsClosed(GeomFromText(@ls1));`
+------------------------------+
| IsClosed(GeomFromText(@ls1)) |
+------------------------------+
|                            0 |
+------------------------------+
1 row in set (0.00 sec)

mysql> `SELECT IsClosed(GeomFromText(@ls2));`
+------------------------------+
| IsClosed(GeomFromText(@ls2)) |
+------------------------------+
|                            1 |
+------------------------------+
1 row in set (0.00 sec)
```
• Returns the number of `Point` objects in the `LineString` value `ls`.

```mysql> `SET @ls = 'LineString(1 1,2 2,3 3)';`
mysql> `SELECT NumPoints(GeomFromText(@ls));`
+------------------------------+
| NumPoints(GeomFromText(@ls)) |
+------------------------------+
|                            3 |
+------------------------------+
```
• Returns the `N`-th `Point` in the `Linestring` value `ls`. Points are numbered beginning with 1.

```mysql> `SET @ls = 'LineString(1 1,2 2,3 3)';`
mysql> `SELECT AsText(PointN(GeomFromText(@ls),2));`
+-------------------------------------+
| AsText(PointN(GeomFromText(@ls),2)) |
+-------------------------------------+
| POINT(2 2)                          |
+-------------------------------------+
```
• Returns the `Point` that is the start point of the `LineString` value `ls`.

```mysql> `SET @ls = 'LineString(1 1,2 2,3 3)';`
mysql> `SELECT AsText(StartPoint(GeomFromText(@ls)));`
+---------------------------------------+
| AsText(StartPoint(GeomFromText(@ls))) |
+---------------------------------------+
| POINT(1 1)                            |
+---------------------------------------+
```
##### 12.16.5.2.4 `MultiLineString` Functions

These functions return properties of `MultiLineString` values.

• Returns as a double-precision number the length of the `MultiLineString` value `mls`. The length of `mls` is equal to the sum of the lengths of its elements.

```mysql> `SET @mls = 'MultiLineString((1 1,2 2,3 3),(4 4,5 5))';`
mysql> `SELECT GLength(GeomFromText(@mls));`
+-----------------------------+
| GLength(GeomFromText(@mls)) |
+-----------------------------+
|             4.2426406871193 |
+-----------------------------+
```

`GLength()` is a nonstandard name. It corresponds to the OpenGIS `Length()` function.

• Returns 1 if the `MultiLineString` value `mls` is closed (that is, the `StartPoint()` and `EndPoint()` values are the same for each `LineString` in `mls`). Returns 0 if `mls` is not closed, and –1 if it is `NULL`.

```mysql> `SET @mls = 'MultiLineString((1 1,2 2,3 3),(4 4,5 5))';`
mysql> `SELECT IsClosed(GeomFromText(@mls));`
+------------------------------+
| IsClosed(GeomFromText(@mls)) |
+------------------------------+
|                            0 |
+------------------------------+
```
##### 12.16.5.2.5 `Polygon` Functions

These functions return properties of `Polygon` values.

• Returns as a double-precision number the area of the `Polygon` value `poly`, as measured in its spatial reference system.

```mysql> `SET @poly = 'Polygon((0 0,0 3,3 0,0 0),(1 1,1 2,2 1,1 1))';`
mysql> `SELECT Area(GeomFromText(@poly));`
+---------------------------+
| Area(GeomFromText(@poly)) |
+---------------------------+
|                         4 |
+---------------------------+
```
• Returns the exterior ring of the `Polygon` value `poly` as a `LineString`.

```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 AsText(ExteriorRing(GeomFromText(@poly)));`
+-------------------------------------------+
| AsText(ExteriorRing(GeomFromText(@poly))) |
+-------------------------------------------+
| LINESTRING(0 0,0 3,3 3,3 0,0 0)           |
+-------------------------------------------+
```
• Returns the `N`-th interior ring for the `Polygon` value `poly` as a `LineString`. Rings are numbered beginning with 1.

```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 AsText(InteriorRingN(GeomFromText(@poly),1));`
+----------------------------------------------+
| AsText(InteriorRingN(GeomFromText(@poly),1)) |
+----------------------------------------------+
| LINESTRING(1 1,1 2,2 2,2 1,1 1)              |
+----------------------------------------------+
```
• Returns the number of interior rings in the `Polygon` value `poly`.

```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 NumInteriorRings(GeomFromText(@poly));`
+---------------------------------------+
| NumInteriorRings(GeomFromText(@poly)) |
+---------------------------------------+
|                                     1 |
+---------------------------------------+
```
##### 12.16.5.2.6 `MultiPolygon` Functions

These functions return properties of `MultiPolygon` values.

• Returns as a double-precision number the area of the `MultiPolygon` value `mpoly`, as measured in its spatial reference system.

```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 Area(GeomFromText(@mpoly));`
+----------------------------+
| Area(GeomFromText(@mpoly)) |
+----------------------------+
|                          8 |
+----------------------------+
```
• Returns the mathematical centroid for the `MultiPolygon` value `mpoly` as a `Point`. The result is not guaranteed to be on the `MultiPolygon`.

```mysql> `SET @poly =`
-> `GeomFromText('POLYGON((0 0,10 0,10 10,0 10,0 0),(5 5,7 5,7 7,5 7,5 5))');`
mysql> `SELECT GeometryType(@poly),AsText(Centroid(@poly));`
+---------------------+--------------------------------------------+
| GeometryType(@poly) | AsText(Centroid(@poly))                    |
+---------------------+--------------------------------------------+
| POLYGON             | POINT(4.958333333333333 4.958333333333333) |
+---------------------+--------------------------------------------+
```

The OpenGIS specification also defines the following function, which MySQL does not implement:

• `PointOnSurface(mpoly)`

Returns a `Point` value that is guaranteed to be on the `MultiPolygon` value `mpoly`.

##### 12.16.5.2.7 `GeometryCollection` Functions

These functions return properties of `GeometryCollection` values.

• Returns the `N`-th geometry in the `GeometryCollection` value `gc`. Geometries are numbered beginning with 1.

```mysql> `SET @gc = 'GeometryCollection(Point(1 1),LineString(2 2, 3 3))';`
mysql> `SELECT AsText(GeometryN(GeomFromText(@gc),1));`
+----------------------------------------+
| AsText(GeometryN(GeomFromText(@gc),1)) |
+----------------------------------------+
| POINT(1 1)                             |
+----------------------------------------+
```
• Returns the number of geometries in the `GeometryCollection` value `gc`.

```mysql> `SET @gc = 'GeometryCollection(Point(1 1),LineString(2 2, 3 3))';`
mysql> `SELECT NumGeometries(GeomFromText(@gc));`
+----------------------------------+
| NumGeometries(GeomFromText(@gc)) |
+----------------------------------+
|                                2 |
+----------------------------------+
```