# Geometry Accessors

GeometryType

Returns the type of a geometry as text.

    			text GeometryType
    			geometry  geomA

### Description

Returns the type of the geometry as a string. Eg: 'LINESTRING', 'POLYGON', 'MULTIPOINT', etc.

OGC SPEC s2.1.1.1 - Returns the name of the instantiable subtype of Geometry of which this Geometry instance is a member. The name of the instantiable subtype of Geometry is returned as a string.

This function also indicates if the geometry is measured, by returning a string of the form 'POINTM'.

Enhanced: 2.0.0 support for Polyhedral surfaces, Triangles and TIN was introduced.

&sfs_compliant;

&curve_support;

&Z_support;

&P_support;

&T_support;

### Examples

    SELECT GeometryType('LINESTRING(77.29 29.07,77.42 29.26,77.27 29.31,77.29 29.07)'::geometry);

    LINESTRING

    SELECT ST_GeometryType('POLYHEDRALSURFACE( ((0 0 0,0 0 1,0 1 1,0 1 0,0 0 0)),
    ((0 0 0,0 1 0,1 1 0,1 0 0,0 0 0)),((0 0 0,1 0 0,1 0 1,0 0 1,0 0 0)),
    ((1 1 0,1 1 1,1 0 1,1 0 0,1 1 0)),
    ((0 1 0,0 1 1,1 1 1,1 1 0,0 1 0)),((0 0 1,1 0 1,1 1 1,0 1 1,0 0 1)) )');
        POLYHEDRALSURFACE

    SELECT GeometryType(geom) as result
    FROM
      (SELECT
         'TIN (((
                  0 0 0,
                  0 0 1,
                  0 1 0,
                  0 0 0
              )),((
                  0 0 0,
                  0 1 0,
                  1 1 0,
                  0 0 0
              ))
              )'::geometry  AS geom
      ) AS g;

    TIN

### See Also

ST_GeometryType

ST_Boundary

Returns the boundary of a geometry.

    			geometry ST_Boundary

    			geometry  geomA

### Description

Returns the closure of the combinatorial boundary of this Geometry. The combinatorial boundary is defined as described in section 3.12.3.2 of the OGC SPEC. Because the result of this function is a closure, and hence topologically closed, the resulting boundary can be represented using representational geometry primitives as discussed in the OGC SPEC, section 3.12.2.

Performed by the GEOS module

Prior to 2.0.0, this function throws an exception if used with `GEOMETRYCOLLECTION`. From 2.0.0 up it will return NULL instead (unsupported input).

&sfs_compliant; OGC SPEC s2.1.1.1

&sqlmm_compliant; SQL-MM IEC 13249-3: 5.1.17

&Z_support;

Enhanced: 2.1.0 support for Triangle was introduced

Changed: 3.2.0 support for TIN, does not use geos, does not linearize curves

### Examples

LineString with boundary points overlaid.

    SELECT ST_Boundary(geom)
    FROM (SELECT 'LINESTRING(100 150,50 60,70 80,160 170)'::geometry As geom) As f;

    MULTIPOINT((100 150),(160 170))

Polygon holes with the boundary MultiLineString overlaid.

    SELECT ST_Boundary(geom)
    FROM (SELECT
    'POLYGON (( 10 130,50 190,110 190,140 150,150 80,100 10,20 40,10 130 ),
        ( 70 40,100 50,120 80,80 110,50 90,70 40 ))'::geometry As geom) As f;

    MULTILINESTRING((10 130,50 190,110 190,140 150,150 80,100 10,20 40,10 130),
            (70 40,100 50,120 80,80 110,50 90,70 40))

    SELECT ST_Boundary('LINESTRING(1 1,0 0,-1 1)');

    MULTIPOINT((1 1),(-1 1))

    SELECT ST_Boundary('POLYGON((1 1,0 0,-1 1,1 1))');

    LINESTRING(1 1,0 0,-1 1,1 1)

This example uses a 3D polygon.

    SELECT ST_Boundary('POLYGON((1 1 1,0 0 1,-1 1 1,1 1 1))');

    LINESTRING(1 1 1,0 0 1,-1 1 1,1 1 1)

This example uses a 3D MultiLineString.

    SELECT ST_Boundary('MULTILINESTRING((1 1 1,0 0 0.5,-1 1 1),(1 1 0.5,0 0 0.5,-1 1 0.5,1 1 0.5) )');

    MULTIPOINT(1 1 1,-1 1 1)

### See Also

ST_AsText, ST_ExteriorRing, ST_MakePolygon

ST_BoundingDiagonal

Returns the diagonal of a geometry's bounding box.

    				geometry ST_BoundingDiagonal

    				geometry  geom
    				boolean  fits=false

### Description

Returns the diagonal of the supplied geometry's bounding box as a LineString. The diagonal is a 2-point LineString with the minimum values of each dimension in its start point and the maximum values in its end point. If the input geometry is empty, the diagonal line is a LINESTRING EMPTY.

The optional `fits` parameter specifies if the best fit is needed. If false, the diagonal of a somewhat larger bounding box can be accepted (which is faster to compute for geometries with many vertices). In either case, the bounding box of the returned diagonal line always covers the input geometry.

The returned geometry retains the SRID and dimensionality (Z and M presence) of the input geometry.

In degenerate cases (i.e. a single vertex in input) the returned linestring will be formally invalid (no interior). The result is still topologically valid.

Availability: 2.2.0

&Z_support;

&M_support;

### Examples

This example shows a polygon together with the diagonal of its bounding box.

    WITH input AS (
      SELECT 'POLYGON((10 20,30 60,70 40,90 10,50 -10,10 20))'::geometry AS geom
    )
    SELECT geom AS input_polygon,
           ST_BoundingDiagonal(geom) AS diagonal
    FROM input;

    POLYGON((10 20,30 60,70 40,90 10,50 -10,10 20)) | LINESTRING(10 -10,90 60)

This example returns the minimum X coordinate of a buffer around a point.

    SELECT ST_X(ST_StartPoint(ST_BoundingDiagonal(
      ST_Buffer(ST_Point(0, 0), 10)
    )));

    -10

### See Also

ST_StartPoint, ST_EndPoint, ST_X, ST_Y, ST_Z, ST_M, ST_Envelope

ST_CoordDim

Return the coordinate dimension of a geometry.

    			integer ST_CoordDim
    			geometry  geomA

### Description

Return the coordinate dimension of the ST_Geometry value.

This is the MM compliant alias name for ST_NDims

&sfs_compliant;

&sqlmm_compliant; SQL-MM 3: 5.1.3

&curve_support;

&Z_support;

&P_support;

&T_support;

### Examples

    SELECT ST_CoordDim('CIRCULARSTRING(1 2 3,1 3 4,5 6 7,8 9 10,11 12 13)');

    3

    SELECT ST_CoordDim(ST_Point(1, 2));

    2

### See Also

ST_NDims

ST_Dimension

Returns the topological dimension of a geometry.

    			integer ST_Dimension

    			geometry  g

### Description

Return the topological dimension of this Geometry object, which must be less than or equal to the coordinate dimension. OGC SPEC s2.1.1.1 - returns 0 for `POINT`, 1 for `LINESTRING`, 2 for `POLYGON`, and the largest dimension of the components of a `GEOMETRYCOLLECTION`. If the dimension is unknown (e.g. for an empty `GEOMETRYCOLLECTION`) 0 is returned.

&sqlmm_compliant; SQL-MM 3: 5.1.2

A `TIN`, including a closed TIN surface, is a surface geometry and has dimension 2. Use CG_MakeSolid to make the solid representation explicit; the resulting 3D solid has dimension 3. Solid geometry semantics, such as volume, are handled separately by the SQL/MM 3D solid functions (SQL-MM IEC 13249-3: 9.1).

Enhanced: 2.0.0 support for Polyhedral surfaces and TINs was introduced. No longer throws an exception if given empty geometry.

Prior to 2.0.0, this function throws an exception if used with empty geometry.

&P_support;

&T_support;

### Examples

    SELECT ST_Dimension('GEOMETRYCOLLECTION(LINESTRING(1 1,0 0), POINT(0 0))');

    1

    SELECT ST_Dimension('TIN Z (((0 0 0,0 0 1,0 1 0,0 0 0)),((0 0 0,0 1 0,1 0 0,0 0 0)),((0 0 0,1 0 0,0 0 1,0 0 0)),((1 0 0,0 1 0,0 0 1,1 0 0)))');

    2

### See Also

ST_NDims, CG_MakeSolid, CG_Volume

ST_Dump

Returns a set of `geometry_dump` rows for the components of a geometry.

    			geometry_dump[] ST_Dump
    			geometry  g1

### Description

A set-returning function (SRF) that extracts the components of a geometry. It returns a set of geometry_dump rows, each containing a geometry (`geom` field) and an array of integers (`path` field).

For an atomic geometry type (POINT,LINESTRING,POLYGON) a single record is returned with an empty `path` array and the input geometry as `geom`. For a collection or multi-geometry a record is returned for each of the collection components, and the `path` denotes the position of the component inside the collection.

ST_Dump is useful for expanding geometries. It is the inverse of a ST_Collect / GROUP BY, in that it creates new rows. For example it can be use to expand MULTIPOLYGONS into POLYGONS.

Enhanced: 2.0.0 support for Polyhedral surfaces, Triangles and TIN was introduced.

Availability: PostGIS 1.0.0RC1. Requires PostgreSQL 7.3 or higher.

Prior to 1.3.4, this function crashes if used with geometries that contain CURVES. This is fixed in 1.3.4+

&curve_support;

&P_support;

&T_support;

&Z_support;

### Examples

Dump the components of geometries stored in a table.

    SELECT sometable.field1,
           (ST_Dump(sometable.geom)).geom AS geom
    FROM sometable;

Break a CompoundCurve into its constituent LineStrings and CircularStrings.

    SELECT a.geom, ST_HasArc(a.geom)
      FROM ( SELECT (ST_Dump(p_geom)).geom AS geom
             FROM (SELECT 'COMPOUNDCURVE(CIRCULARSTRING(0 0,1 1,1 0),(1 0,0 1))'::geometry AS p_geom) AS b
            ) AS a;

              st_asewkt          | st_hasarc
    -----------------------------+----------
     CIRCULARSTRING(0 0,1 1,1 0) | t
     LINESTRING(1 0,0 1)         | f
    (2 rows)

This example breaks a PolyhedralSurface into its faces.

    SELECT (a.p_geom).path[1] As path,(a.p_geom).geom As geom_ewkt
      FROM (SELECT ST_Dump('POLYHEDRALSURFACE(
    ((0 0 0,0 0 1,0 1 1,0 1 0,0 0 0)),
    ((0 0 0,0 1 0,1 1 0,1 0 0,0 0 0)),((0 0 0,1 0 0,1 0 1,0 0 1,0 0 0)),((1 1 0,1 1 1,1 0 1,1 0 0,1 1 0)),
    ((0 1 0,0 1 1,1 1 1,1 1 0,0 1 0)),((0 0 1,1 0 1,1 1 1,0 1 1,0 0 1))
    )' ) AS p_geom )  AS a;

     path |                geom_ewkt
    ------+------------------------------------------
        1 | POLYGON((0 0 0,0 0 1,0 1 1,0 1 0,0 0 0))
        2 | POLYGON((0 0 0,0 1 0,1 1 0,1 0 0,0 0 0))
        3 | POLYGON((0 0 0,1 0 0,1 0 1,0 0 1,0 0 0))
        4 | POLYGON((1 1 0,1 1 1,1 0 1,1 0 0,1 1 0))
        5 | POLYGON((0 1 0,0 1 1,1 1 1,1 1 0,0 1 0))
        6 | POLYGON((0 0 1,1 0 1,1 1 1,0 1 1,0 0 1))

This example uses a TIN geometry.

    SELECT (g.gdump).path,(g.gdump).geom as wkt
      FROM
        (SELECT
           ST_Dump('TIN (((
                    0 0 0,
                    0 0 1,
                    0 1 0,
                    0 0 0
                )),((
                    0 0 0,
                    0 1 0,
                    1 1 0,
                    0 0 0
                ))
                )' ) AS gdump
        ) AS g;

     path |                 wkt
    ------+-------------------------------------
     {1}  | TRIANGLE((0 0 0,0 0 1,0 1 0,0 0 0))
     {2}  | TRIANGLE((0 0 0,0 1 0,1 1 0,0 0 0))

### See Also

geometry_dump, PostGIS_Geometry_DumpFunctions, ST_Collect, ST_GeometryN

ST_DumpPoints

Returns a set of `geometry_dump` rows for the coordinates in a geometry.

    				geometry_dump[] ST_DumpPoints
    				geometry  geom

### Description

A set-returning function (SRF) that extracts the coordinates (vertices) of a geometry. It returns a set of geometry_dump rows, each containing a geometry (`geom` field) and an array of integers (`path` field).

- the `geom` field `POINT`s represent the coordinates of the supplied geometry.

- the `path` field (an `integer[]`) is an index enumerating the coordinate positions in the elements of the supplied geometry. The indices are 1-based. For example, for a `LINESTRING` the paths are `{i}` where `i` is the `nth` coordinate in the `LINESTRING`. For a `POLYGON` the paths are `{i,j}` where `i` is the ring number (1 is outer; inner rings follow) and `j` is the coordinate position in the ring.

To obtain a single geometry containing the coordinates use ST_Points.

Enhanced: 2.1.0 Faster speed. Reimplemented as native-C.

Enhanced: 2.0.0 support for Polyhedral surfaces, Triangles and TIN was introduced.

Availability: 1.5.0

&curve_support;

&P_support;

&T_support;

&Z_support;

### Examples

Explode a table of LineStrings into their vertices.

    SELECT edge_id, (dp).path[1] As index,(dp).geom As wktnode
    FROM (SELECT 1 As edge_id,
        ST_DumpPoints(ST_GeomFromText('LINESTRING(1 2,3 4,10 10)')) AS dp
         UNION ALL
         SELECT 2 As edge_id,
        ST_DumpPoints(ST_GeomFromText('LINESTRING(3 5,5 6,9 10)')) AS dp
       ) As foo;

     edge_id | index |    wktnode
    ---------+-------+--------------
           1 |     1 | POINT(1 2)
           1 |     2 | POINT(3 4)
           1 |     3 | POINT(10 10)
           2 |     1 | POINT(3 5)
           2 |     2 | POINT(5 6)
           2 |     3 | POINT(9 10)

Dump every vertex from a mixed GeometryCollection.

    SELECT path,geom
    FROM (
      SELECT (ST_DumpPoints(g.geom)).*
      FROM
        (SELECT
           'GEOMETRYCOLLECTION(
              POINT ( 0 1 ),
              LINESTRING ( 0 3,3 4 ),
              POLYGON (( 2 0,2 3,0 2,2 0 )),
              POLYGON (( 3 0,3 3,6 3,6 0,3 0 ),
                       ( 5 1,4 2,5 2,5 1 )),
              MULTIPOLYGON (
                      (( 0 5,0 8,4 8,4 5,0 5 ),
                       ( 1 6,3 6,2 7,1 6 )),
                      (( 5 4,5 8,6 7,5 4 ))
              )
            )'::geometry AS geom
        ) AS g
      ) j;

       path    | st_astext
    -----------+------------
     {1,1}     | POINT(0 1)
     {2,1}     | POINT(0 3)
     {2,2}     | POINT(3 4)
     {3,1,1}   | POINT(2 0)
     {3,1,2}   | POINT(2 3)
     {3,1,3}   | POINT(0 2)
     {3,1,4}   | POINT(2 0)
     {4,1,1}   | POINT(3 0)
     {4,1,2}   | POINT(3 3)
     {4,1,3}   | POINT(6 3)
     {4,1,4}   | POINT(6 0)
     {4,1,5}   | POINT(3 0)
     {4,2,1}   | POINT(5 1)
     {4,2,2}   | POINT(4 2)
     {4,2,3}   | POINT(5 2)
     {4,2,4}   | POINT(5 1)
     {5,1,1,1} | POINT(0 5)
     {5,1,1,2} | POINT(0 8)
     {5,1,1,3} | POINT(4 8)
     {5,1,1,4} | POINT(4 5)
     {5,1,1,5} | POINT(0 5)
     {5,1,2,1} | POINT(1 6)
     {5,1,2,2} | POINT(3 6)
     {5,1,2,3} | POINT(2 7)
     {5,1,2,4} | POINT(1 6)
     {5,2,1,1} | POINT(5 4)
     {5,2,1,2} | POINT(5 8)
     {5,2,1,3} | POINT(6 7)
     {5,2,1,4} | POINT(5 4)
    (29 rows)

Collect the dumped vertices to visualize them over the source geometry.

    WITH source(geom) AS (VALUES (
      'GEOMETRYCOLLECTION(
         POINT (0 1),
         LINESTRING (0 3,3 4),
         POLYGON ((2 0,2 3,0 2,2 0)),
         POLYGON ((3 0,3 3,6 3,6 0,3 0),(5 1,4 2,5 2,5 1)),
         MULTIPOLYGON (((0 5,0 8,4 8,4 5,0 5),(1 6,3 6,2 7,1 6)),
                       ((5 4,5 8,6 7,5 4))))'::geometry
    ))
    SELECT ST_Collect((dp).geom ORDER BY (dp).path) AS vertices
    FROM source
    CROSS JOIN LATERAL ST_DumpPoints(source.geom) AS dp;

    MULTIPOINT((0 1),(0 3),(3 4),(2 0),(2 3),(0 2),(2 0),(3 0),(3 3),(6 3),(6 0),(3 0),(5 1),(4 2),(5 2),(5 1),(0 5),(0 8),(4 8),(4 5),(0 5),(1 6),(3 6),(2 7),(1 6),(5 4),(5 8),(6 7),(5 4))

This example uses a cube represented as a PolyhedralSurface.

    SELECT (g.gdump).path,(g.gdump).geom as wkt
      FROM
        (SELECT
           ST_DumpPoints('POLYHEDRALSURFACE( ((0 0 0,0 0 1,0 1 1,0 1 0,0 0 0)),
    ((0 0 0,0 1 0,1 1 0,1 0 0,0 0 0)),((0 0 0,1 0 0,1 0 1,0 0 1,0 0 0)),
    ((1 1 0,1 1 1,1 0 1,1 0 0,1 1 0)),
    ((0 1 0,0 1 1,1 1 1,1 1 0,0 1 0)),((0 0 1,1 0 1,1 1 1,0 1 1,0 0 1)) )' ) AS gdump
        ) AS g;

      path   |     wkt
    ---------+--------------
     {1,1,1} | POINT(0 0 0)
     {1,1,2} | POINT(0 0 1)
     {1,1,3} | POINT(0 1 1)
     {1,1,4} | POINT(0 1 0)
     {1,1,5} | POINT(0 0 0)
     {2,1,1} | POINT(0 0 0)
     {2,1,2} | POINT(0 1 0)
     {2,1,3} | POINT(1 1 0)
     {2,1,4} | POINT(1 0 0)
     {2,1,5} | POINT(0 0 0)
     {3,1,1} | POINT(0 0 0)
     {3,1,2} | POINT(1 0 0)
     {3,1,3} | POINT(1 0 1)
     {3,1,4} | POINT(0 0 1)
     {3,1,5} | POINT(0 0 0)
     {4,1,1} | POINT(1 1 0)
     {4,1,2} | POINT(1 1 1)
     {4,1,3} | POINT(1 0 1)
     {4,1,4} | POINT(1 0 0)
     {4,1,5} | POINT(1 1 0)
     {5,1,1} | POINT(0 1 0)
     {5,1,2} | POINT(0 1 1)
     {5,1,3} | POINT(1 1 1)
     {5,1,4} | POINT(1 1 0)
     {5,1,5} | POINT(0 1 0)
     {6,1,1} | POINT(0 0 1)
     {6,1,2} | POINT(1 0 1)
     {6,1,3} | POINT(1 1 1)
     {6,1,4} | POINT(0 1 1)
     {6,1,5} | POINT(0 0 1)
    (30 rows)

This example uses a Triangle geometry.

    SELECT (g.gdump).path,(g.gdump).geom as wkt
      FROM
        (SELECT
           ST_DumpPoints('TRIANGLE ((
                    0 0,
                    0 9,
                    9 0,
                    0 0
                ))' ) AS gdump
        ) AS g;

     path |    wkt
    ------+------------
     {1,1} | POINT(0 0)
     {1,2} | POINT(0 9)
     {1,3} | POINT(9 0)
     {1,4} | POINT(0 0)

This example uses a TIN geometry.

    SELECT (g.gdump).path,(g.gdump).geom as wkt
      FROM
        (SELECT
           ST_DumpPoints('TIN (((
                    0 0 0,
                    0 0 1,
                    0 1 0,
                    0 0 0
                )),((
                    0 0 0,
                    0 1 0,
                    1 1 0,
                    0 0 0
                ))
                )' ) AS gdump
        ) AS g;

      path   |     wkt
    ---------+--------------
     {1,1,1} | POINT(0 0 0)
     {1,1,2} | POINT(0 0 1)
     {1,1,3} | POINT(0 1 0)
     {1,1,4} | POINT(0 0 0)
     {2,1,1} | POINT(0 0 0)
     {2,1,2} | POINT(0 1 0)
     {2,1,3} | POINT(1 1 0)
     {2,1,4} | POINT(0 0 0)
    (8 rows)

### See Also

geometry_dump, PostGIS_Geometry_DumpFunctions, ST_Dump, ST_DumpRings, ST_Points

ST_DumpSegments

Returns a set of `geometry_dump` rows for the segments in a geometry.

    				geometry_dump[] ST_DumpSegments
    				geometry  geom

### Description

A set-returning function (SRF) that extracts the segments of a geometry. It returns a set of geometry_dump rows, each containing a geometry (`geom` field) and an array of integers (`path` field).

- the `geom` field `LINESTRING`s represent the linear segments of the supplied geometry, while the `CIRCULARSTRING`s represent the arc segments.

- the `path` field (an `integer[]`) is an index enumerating the segment start point positions in the elements of the supplied geometry. The indices are 1-based. For example, for a `LINESTRING` the paths are `{i}` where `i` is the `nth` segment start point in the `LINESTRING`. For a `POLYGON` the paths are `{i,j}` where `i` is the ring number (1 is outer; inner rings follow) and `j` is the segment start point position in the ring.

Availability: 3.2.0

&T_support;

&Z_support;

### Standard Geometry Examples

    SELECT path,geom
    FROM (
        SELECT (ST_DumpSegments(g.geom)).*
        FROM (SELECT 'GEOMETRYCOLLECTION(
        LINESTRING(1 1,3 3,4 4),
        POLYGON((5 5,6 6,7 7,5 5))
    )'::geometry AS geom
            ) AS g
    ) j;

      path   │      st_astext
    ---------------------------------
     {1,1}   │ LINESTRING(1 1,3 3)
     {1,2}   │ LINESTRING(3 3,4 4)
     {2,1,1} │ LINESTRING(5 5,6 6)
     {2,1,2} │ LINESTRING(6 6,7 7)
     {2,1,3} │ LINESTRING(7 7,5 5)
    (5 rows)

### TIN and Triangle Examples

This example uses a Triangle geometry.

    SELECT path,geom
    FROM (
        SELECT (ST_DumpSegments(g.geom)).*
        FROM (SELECT 'TRIANGLE((
            0 0,
            0 9,
            9 0,
            0 0
        ))'::geometry AS geom
            ) AS g
    ) j;

     path  │      st_astext
     ---------------------------------
     {1,1} │ LINESTRING(0 0,0 9)
     {1,2} │ LINESTRING(0 9,9 0)
     {1,3} │ LINESTRING(9 0,0 0)
    (3 rows)

This example uses a TIN geometry.

    SELECT path,geom
    FROM (
        SELECT (ST_DumpSegments(g.geom)).*
        FROM (SELECT 'TIN(((
            0 0 0,
            0 0 1,
            0 1 0,
            0 0 0
        )),((
            0 0 0,
            0 1 0,
            1 1 0,
            0 0 0
        ))
        )'::geometry AS geom
            ) AS g
    ) j;

      path   │        st_asewkt
      ---------------------------------
     {1,1,1} │ LINESTRING(0 0 0,0 0 1)
     {1,1,2} │ LINESTRING(0 0 1,0 1 0)
     {1,1,3} │ LINESTRING(0 1 0,0 0 0)
     {2,1,1} │ LINESTRING(0 0 0,0 1 0)
     {2,1,2} │ LINESTRING(0 1 0,1 1 0)
     {2,1,3} │ LINESTRING(1 1 0,0 0 0)
    (6 rows)

### See Also

geometry_dump, PostGIS_Geometry_DumpFunctions, ST_Dump, ST_DumpRings

ST_DumpRings

Returns a set of `geometry_dump` rows for the exterior and interior rings of a Polygon.

    			geometry_dump[] ST_DumpRings
    			geometry  a_polygon

### Description

A set-returning function (SRF) that extracts the rings of a polygon. It returns a set of geometry_dump rows, each containing a geometry (`geom` field) and an array of integers (`path` field).

The `geom` field contains each ring as a POLYGON. The `path` field is an integer array of length 1 containing the polygon ring index. The exterior ring (shell) has index 0. The interior rings (holes) have indices of 1 and higher.

This only works for POLYGON geometries, not MULTIPOLYGONs. Use ST_Dump to extract polygon elements from polygonal geometries: `ST_DumpRings((ST_Dump(geom)).geom )`

Availability: PostGIS 1.1.3. Requires PostgreSQL 7.3 or higher.

&Z_support;

### Examples

Extracting all rings as polygons.

    SELECT polyTable.field1, polyTable.field1,
          (ST_DumpRings(polyTable.geom)).geom As geom
    FROM polyTable

Extracting shell and holes from a polygon.

    SELECT path,geom As geom
    FROM ST_DumpRings('POLYGON ((1 9,9 9,9 1,1 1,1 9),(2 2,2 3,3 3,3 2,2 2),(4 2,4 4,6 4,6 2,4 2))');

     path |              geom
    ------+--------------------------------
     {0}  | POLYGON((1 9,9 9,9 1,1 1,1 9))
     {1}  | POLYGON((2 2,2 3,3 3,3 2,2 2))
     {2}  | POLYGON((4 2,4 4,6 4,6 2,4 2))

Finding interior rings which lie close to the exterior ring.

    WITH poly AS (
      SELECT 'POLYGON ((
          0 0, 10 0, 10 10, 0 10, 0 0
        ), (
          1 1, 1 2, 2 2, 2 1, 1 1
        ), (
          8.5 1, 8.5 2, 9.5 2, 9.5 1, 8.5 1
        ))'::geometry AS geom
    ),
    rings AS (
      SELECT d.path[1] AS ring_no,
             ST_Boundary(d.geom) AS ring_geom
      FROM poly
      CROSS JOIN LATERAL ST_DumpRings(poly.geom) AS d
    ),
    shell AS (
      SELECT ring_geom
      FROM rings
      WHERE ring_no = 0
    ),
    holes AS (
      SELECT ring_no, ring_geom
      FROM rings
      WHERE ring_no > 0
    )
    SELECT h.ring_no,
           ST_Normalize(ST_Multi(ST_LineMerge(
             ST_Intersection(ST_Buffer(s.ring_geom, 1.0), h.ring_geom)
           ))) AS close_part
    FROM shell AS s
    JOIN holes AS h
      ON ST_DWithin(s.ring_geom, h.ring_geom, 1.0);

     ring_no |                   close_part
    ---------+-------------------------------------------------
           1 | MULTILINESTRING((1 2,1 1,2 1))
           2 | MULTILINESTRING((8.5 1,9 1,9.5 1,9.5 2,9 2))

### See Also

geometry_dump, PostGIS_Geometry_DumpFunctions, ST_Boundary, ST_Buffer, ST_Dump, ST_DWithin, ST_ExteriorRing, ST_InteriorRingN, ST_Intersection

ST_EndPoint

Returns the last point of a LineString, CircularLineString, or NURBSCurve.

    			geometry ST_EndPoint

    			geometry  g

### Description

Returns the last point of a `LINESTRING`, `CIRCULARLINESTRING`, or `NURBSCURVE` geometry as a `POINT`. Returns `NULL` if the input is not a `LINESTRING`, `CIRCULARLINESTRING`, or `NURBSCURVE`.

&sqlmm_compliant; SQL-MM 3: 7.1.4

&Z_support;

&curve_support;

Changed: 2.0.0 no longer works with single geometry MultiLineStrings. In older versions of PostGIS a single-line MultiLineString would work with this function and return the end point. In 2.0.0 it returns NULL like any other MultiLineString. The old behavior was an undocumented feature, but people who assumed they had their data stored as LINESTRING may experience these returning NULL in 2.0.0.

### Examples

End point of a LineString

    SELECT ST_EndPoint('LINESTRING(1 1,2 2,3 3)'::geometry);

    POINT(3 3)

End point of a non-LineString is NULL

    SELECT ST_EndPoint('POINT(1 1)'::geometry) IS NULL AS is_null;

    t

End point of a 3D LineString

3D endpoint.

    SELECT ST_EndPoint('LINESTRING(1 1 2,1 2 3,0 0 5)');

    POINT(0 0 5)

End point of a CircularString

    SELECT ST_EndPoint('CIRCULARSTRING(5 2,-3 2,-2 1,-4 2,6 3)'::geometry);

    POINT(6 3)

End point of a NURBSCurve

    SELECT ST_EndPoint('NURBSCURVE(2, (0 0, 1 1, 2 0))'::geometry);

    POINT(2 0)

### See Also

ST_PointN, ST_StartPoint

ST_Envelope

Returns a geometry representing the bounding box of a geometry.

    				geometry ST_Envelope

    				geometry  g1

### Description

Returns the double-precision (float8) minimum bounding box for the supplied geometry, as a geometry. The polygon is defined by the corner points of the bounding box ((`MINX`, `MINY`), (`MINX`, `MAXY`), (`MAXX`, `MAXY`), (`MAXX`, `MINY`), (`MINX`, `MINY`)). (PostGIS will add a `ZMIN`/`ZMAX` coordinate as well).

Degenerate cases (vertical lines, points) will return a geometry of lower dimension than `POLYGON`, ie. `POINT` or `LINESTRING`.

Availability: 1.5.0 behavior changed to output double precision instead of float4

&sfs_compliant; s2.1.1.1

&sqlmm_compliant; SQL-MM 3: 5.1.19

### Examples

    SELECT ST_Envelope('POINT(1 3)'::geometry);

    POINT(1 3)

    SELECT ST_Envelope('LINESTRING(0 0,1 3)'::geometry);

    POLYGON((0 0,0 3,1 3,1 0,0 0))

    SELECT ST_Envelope('POLYGON((0 0,0 1,1.0000001 1,1.0000001 0,0 0))'::geometry);

    POLYGON((0 0,0 1,1.0000001 1,1.0000001 0,0 0))

    SELECT ST_Envelope('POLYGON((0 0,0 1,1.0000000001 1,1.0000000001 0,0 0))'::geometry);

    POLYGON((0 0,0 1,1.0000000001 1,1.0000000001 0,0 0))

    SELECT Box3D(geom), Box2D(geom), ST_Envelope(geom) As envelopewkt
        FROM (SELECT 'POLYGON((0 0,0 1000012333334.34545678,1.0000001 1,1.0000001 0,0 0))'::geometry As geom) As foo;

Envelope of a point and LineString.

    SELECT ST_Envelope(ST_Collect(
                'LINESTRING(55 75,125 150)',
                ST_Point(20, 80)
                )) As wktenv;

    POLYGON((20 75,20 150,125 150,125 75,20 75))

### See Also

Box2D, Box3D, ST_OrientedEnvelope

ST_ExteriorRing

Returns a LineString representing the exterior ring of a Polygon.

    			geometry ST_ExteriorRing

    			geometry  a_polygon

### Description

Returns a LINESTRING representing the exterior ring (shell) of a POLYGON. Returns NULL if the geometry is not a polygon.

This function does not support MULTIPOLYGONs. For MULTIPOLYGONs use in conjunction with ST_GeometryN or ST_Dump

&sfs_compliant; 2.1.5.1

&sqlmm_compliant; SQL-MM 3: 8.2.3, 8.3.3

&Z_support;

### Examples

Extract the exterior ring from a Polygon with a hole.

    WITH input(geom) AS (VALUES (
      'POLYGON((0 0,2 9,9 11,14 6,12 0,0 0),(4 3,9 3,10 7,5 8,4 3))'::geometry
    ))
    SELECT geom AS input_polygon,
           ST_ExteriorRing(geom) AS exterior_ring
    FROM input;

    POLYGON((0 0,2 9,9 11,14 6,12 0,0 0),(4 3,9 3,10 7,5 8,4 3)) | LINESTRING(0 0,2 9,9 11,14 6,12 0,0 0)

For a MultiPolygon, dump the component Polygons before extracting their exterior rings. Both component Polygons in this example have holes.

    WITH input(geom) AS (VALUES (
      'MULTIPOLYGON(
        ((0 0,2 9,9 11,14 6,12 0,0 0),(4 3,9 3,10 7,5 8,4 3)),
        ((18 1,18 10,29 10,31 4,25 0,18 1),(21 3,25 2,28 5,25 8,21 7,21 3))
      )'::geometry
    ))
    SELECT part.geom AS input_polygon,
           ST_ExteriorRing(part.geom) AS exterior_ring
    FROM input
    CROSS JOIN LATERAL ST_Dump(geom) AS part
    ORDER BY part.path;

    POLYGON((0 0,2 9,9 11,14 6,12 0,0 0),(4 3,9 3,10 7,5 8,4 3)) | LINESTRING(0 0,2 9,9 11,14 6,12 0,0 0)
    POLYGON((18 1,18 10,29 10,31 4,25 0,18 1),(21 3,25 2,28 5,25 8,21 7,21 3)) | LINESTRING(18 1,18 10,29 10,31 4,25 0,18 1)

Extract exterior rings from a table of Polygons.

    SELECT gid, ST_ExteriorRing(geom) AS ering
    FROM sometable;

For a table of MultiPolygons, dump the component Polygons and collect their exterior rings into a MultiLineString.

    SELECT gid, ST_Collect(ST_ExteriorRing(geom)) AS erings
    FROM (
      SELECT gid, (ST_Dump(geom)).geom AS geom
      FROM sometable
    ) AS foo
    GROUP BY gid;

This example returns the 3D exterior ring of a Polygon.

    SELECT ST_ExteriorRing(
        'POLYGON Z ((0 0 5,4 0 5,4 3 5,0 3 5,0 0 5))'
        );

    LINESTRING(0 0 5,4 0 5,4 3 5,0 3 5,0 0 5)

### See Also

ST_InteriorRingN, ST_Boundary, ST_NumInteriorRings

ST_GeometryN

Return an element of a geometry collection.

    			geometry ST_GeometryN
    			geometry  geomA
    			integer  n

### Description

Returns the 1-based Nth element of a GEOMETRYCOLLECTION, MULTIPOINT, MULTILINESTRING, MULTICURVE, or MULTIPOLYGON. For a unitary geometry, including a TIN or PolyhedralSurface, an index of 1 returns the input geometry and any other index returns NULL. Use ST_PatchN and ST_NumPatches to access and count the faces of a TIN or PolyhedralSurface.

Index is 1-based as for OGC specs since version 0.8.0. Previous versions implemented this as 0-based instead.

To extract all elements of a geometry, ST_Dump is more efficient and works for atomic geometries.

Enhanced: 2.0.0 support for Polyhedral surfaces, Triangles and TIN was introduced.

Changed: 2.0.0 Prior versions would return NULL for singular geometries. This was changed to return the geometry for ST_GeometryN(..,1) case.

Changed: 3.6.0 TIN and PolyhedralSurface are treated as unitary geometries and are not decomposed into patches; use ST_PatchN to access faces.

&sfs_compliant;

&sqlmm_compliant; SQL-MM 3: 9.1.5

&Z_support;

&curve_support;

&P_support;

&T_support;

### Standard Examples

Extracting a subset of points from a 3D multipoint.

    SELECT n, ST_GeometryN(geom, n) As geomewkt
    FROM (
    VALUES
        (1, 'MULTIPOINT((1 2 7), (3 4 7), (5 6 7), (8 9 10))'::geometry ),
        (2, 'MULTICURVE(CIRCULARSTRING(2.5 2.5,4.5 2.5, 3.5 3.5), (10 11, 12 11))'::geometry )
        ) As foo(id, geom)
        CROSS JOIN generate_series(1,100) n
    WHERE n <= ST_NumGeometries(geom)
    ORDER BY id, n;

     n |               geomewkt
    ---+-----------------------------------------
     1 | POINT(1 2 7)
     2 | POINT(3 4 7)
     3 | POINT(5 6 7)
     4 | POINT(8 9 10)
     1 | CIRCULARSTRING(2.5 2.5,4.5 2.5,3.5 3.5)
     2 | LINESTRING(10 11,12 11)

Extracting all geometries (useful when you want to assign an id).

    SELECT gid, n, ST_GeometryN(geom, n)
    FROM sometable CROSS JOIN generate_series(1,100) n
    WHERE n <= ST_NumGeometries(geom);

### Polyhedral Surfaces, TIN and Triangle Examples

A PolyhedralSurface or TIN is treated as a single geometry, not as a collection of faces. `ST_GeometryN` does not decompose the surface into patches, so an index greater than 1 returns `NULL`. Use ST_PatchN and ST_NumPatches to access individual faces.

This example requests the third element of a PolyhedralSurface.

    SELECT ST_GeometryN(p_geom, 3) As geom_ewkt
      FROM (SELECT 'POLYHEDRALSURFACE(
    ((0 0 0,0 0 1,0 1 1,0 1 0,0 0 0)),
    ((0 0 0,0 1 0,1 1 0,1 0 0,0 0 0)),
    ((0 0 0,1 0 0,1 0 1,0 0 1,0 0 0)),
    ((1 1 0,1 1 1,1 0 1,1 0 0,1 1 0)),
    ((0 1 0,0 1 1,1 1 1,1 1 0,0 1 0)),
    ((0 0 1,1 0 1,1 1 1,0 1 1,0 0 1))
    )'::geometry  AS p_geom )  AS a;

    NULL

This example requests the second element of a TIN.

    SELECT ST_GeometryN(geom, 2) as wkt
      FROM
        (SELECT
           'TIN (((
                    0 0 0,
                    0 0 1,
                    0 1 0,
                    0 0 0
                )),((
                    0 0 0,
                    0 1 0,
                    1 1 0,
                    0 0 0
                ))
                )'::geometry  AS geom
        ) AS g;

    NULL

### See Also

ST_Dump, ST_NumGeometries, ST_PatchN, ST_NumPatches

ST_GeometryType

Returns the SQL-MM type of a geometry as text.

    			text ST_GeometryType
    			geometry  g1

### Description

Returns the type of the geometry as a string. EG: 'ST_LineString', 'ST_Polygon','ST_MultiPolygon' etc. This function differs from GeometryType(geometry) in the case of the string and ST in front that is returned, as well as the fact that it will not indicate whether the geometry is measured.

Enhanced: 2.0.0 support for Polyhedral surfaces was introduced.

&sqlmm_compliant; SQL-MM 3: 5.1.4

&Z_support;

&P_support;

### Examples

    SELECT ST_GeometryType('LINESTRING(77.29 29.07,77.42 29.26,77.27 29.31,77.29 29.07)'::geometry);

    ST_LineString

    SELECT ST_GeometryType('POLYHEDRALSURFACE( ((0 0 0,0 0 1,0 1 1,0 1 0,0 0 0)),
    ((0 0 0,0 1 0,1 1 0,1 0 0,0 0 0)),((0 0 0,1 0 0,1 0 1,0 0 1,0 0 0)),
    ((1 1 0,1 1 1,1 0 1,1 0 0,1 1 0)),
    ((0 1 0,0 1 1,1 1 1,1 1 0,0 1 0)),((0 0 1,1 0 1,1 1 1,0 1 1,0 0 1)) )'::geometry);

    ST_PolyhedralSurface

    SELECT ST_GeometryType(geom) AS result
    FROM
      (SELECT
         'TIN (((
                  0 0 0,
                  0 0 1,
                  0 1 0,
                  0 0 0
              )),((
                  0 0 0,
                  0 1 0,
                  1 1 0,
                  0 0 0
              ))
              )'::geometry AS geom
      ) AS g;

    ST_Tin

### See Also

GeometryType

ST_HasArc

Tests if a geometry contains a circular arc

    			boolean ST_HasArc
    			geometry  geomA

### Description

Returns true if a geometry or geometry collection contains a circular string

Availability: 1.2.3?

&Z_support;

&curve_support;

### Examples

    SELECT ST_HasArc(ST_Collect('LINESTRING(1 2,3 4,5 6)', 'CIRCULARSTRING(1 1,2 3,4 5,6 7,5 6)'));

    t

### See Also

ST_CurveToLine, ST_LineToCurve

ST_InteriorRingN

Returns the Nth interior ring (hole) of a Polygon.

    			geometry ST_InteriorRingN
    			geometry  a_polygon
    			integer  n

### Description

Returns the Nth interior ring (hole) of a POLYGON geometry as a LINESTRING. The index starts at 1. Returns NULL if the geometry is not a polygon or the index is out of range.

This function does not support MULTIPOLYGONs. For MULTIPOLYGONs use in conjunction with ST_GeometryN or ST_Dump

&sfs_compliant;

&sqlmm_compliant; SQL-MM 3: 8.2.6, 8.3.5

&Z_support;

### Examples

    WITH data AS (
      SELECT ST_BuildArea(ST_Collect(
        ST_Buffer(ST_Point(1, 2), 20, 3),
        ST_Buffer(ST_Point(1, 2), 10, 3)
      )) AS geom
    )
    SELECT geom AS input_polygon,
           ST_InteriorRingN(geom, 1) AS ring
    FROM data;

    POLYGON((21 2,18.320508075688775 -7.999999999999998,11.000000000000002 -15.320508075688771,1 -18,-8.999999999999996 -15.320508075688775,-16.32050807568877 -8.000000000000007,-19 2,-16.320508075688778 11.999999999999995,-9.000000000000009 19.320508075688767,1 22,10.999999999999986 19.32050807568878,18.320508075688767 12.000000000000009,21 2),(11 2,9.660254037844384 7.000000000000004,5.999999999999993 10.66025403784439,1 12,-4.000000000000004 10.660254037844384,-7.660254037844389 6.999999999999997,-9 2,-7.660254037844386 -3.000000000000004,-3.999999999999998 -6.660254037844387,1 -8,6.000000000000001 -6.660254037844386,9.660254037844387 -2.999999999999999,11 2)) | LINESTRING(11 2,9.660254037844384 7.000000000000004,5.999999999999993 10.66025403784439,1 12,-4.000000000000004 10.660254037844384,-7.660254037844389 6.999999999999997,-9 2,-7.660254037844386 -3.000000000000004,-3.999999999999998 -6.660254037844387,1 -8,6.000000000000001 -6.660254037844386,9.660254037844387 -2.999999999999999,11 2)

### See Also

ST_ExteriorRing, ST_BuildArea, ST_Collect, ST_Dump, ST_NumInteriorRing, ST_NumInteriorRings

ST_NumCurves

Return the number of component curves in a CompoundCurve.

                integer ST_NumCurves
                geometry  a_compoundcurve

### Description

Return the number of component curves in a CompoundCurve, zero for an empty CompoundCurve, or NULL for a non-CompoundCurve input.

&sqlmm_compliant; SQL-MM 3: 8.2.6, 8.3.5

&Z_support;

### Examples

This CompoundCurve contains three component curves.

    SELECT ST_NumCurves('COMPOUNDCURVE(
        (2 2,2.5 2.5),
        CIRCULARSTRING(2.5 2.5,4.5 2.5,3.5 3.5),
        (3.5 3.5,2.5 4.5,3 5,2 2)
      )');

    3

An empty CompoundCurve has no component curves.

    SELECT ST_NumCurves('COMPOUNDCURVE EMPTY');

    0

### See Also

ST_CurveN, ST_Dump, ST_ExteriorRing, ST_NumInteriorRings, ST_NumGeometries

ST_CurveN

Returns the Nth component curve geometry of a CompoundCurve.

                geometry ST_CurveN
                geometry  a_compoundcurve
                integer  index

### Description

Returns the Nth component curve geometry of a CompoundCurve. The index starts at 1. Returns NULL if the geometry is not a CompoundCurve or the index is out of range.

&sqlmm_compliant; SQL-MM 3: 8.2.6, 8.3.5

&Z_support;

### Examples

This example extracts the second component curve, a CircularString, from a CompoundCurve.

    SELECT ST_CurveN(
      'COMPOUNDCURVE(
        (0 0,2 0),
        CIRCULARSTRING(2 0,3 1,4 0),
        (4 0,6 1)
      )',
      2) AS curve;

    CIRCULARSTRING(2 0,3 1,4 0)

### See Also

ST_NumCurves, ST_Dump, ST_ExteriorRing, ST_NumInteriorRings, ST_NumGeometries

ST_IsClosed

Tests if a LineStrings's start and end points are coincident. For a PolyhedralSurface tests if it is closed (volumetric).

    			boolean ST_IsClosed

    			geometry  g

### Description

Returns `TRUE` if the `LINESTRING`'s start and end points are coincident. For Polyhedral Surfaces, reports if the surface is areal (open) or volumetric (closed).

&sfs_compliant;

&sqlmm_compliant; SQL-MM 3: 7.1.5, 9.3.3

SQL-MM defines the result of `ST_IsClosed(NULL)` to be 0, while PostGIS returns `NULL`.

&Z_support;

&curve_support;

Enhanced: 2.0.0 support for Polyhedral surfaces was introduced.

&P_support;

### Line String and Point Examples

    SELECT ST_IsClosed('LINESTRING(0 0,1 1)'::geometry);

    f

    SELECT ST_IsClosed('LINESTRING(0 0,0 1,1 1,0 0)'::geometry);

    t

    SELECT ST_IsClosed('MULTILINESTRING((0 0,0 1,1 1,0 0),(0 0,1 1))'::geometry);

    f

    SELECT ST_IsClosed('POINT(0 0)'::geometry);

    t

    SELECT ST_IsClosed('MULTIPOINT((0 0),(1 1))'::geometry);

    t

### Polyhedral Surface Examples

This example uses a cube.

    SELECT ST_IsClosed('POLYHEDRALSURFACE( ((0 0 0,0 0 1,0 1 1,0 1 0,0 0 0)),
    ((0 0 0,0 1 0,1 1 0,1 0 0,0 0 0)),((0 0 0,1 0 0,1 0 1,0 0 1,0 0 0)),
    ((1 1 0,1 1 1,1 0 1,1 0 0,1 1 0)),
    ((0 1 0,0 1 1,1 1 1,1 1 0,0 1 0)),((0 0 1,1 0 1,1 1 1,0 1 1,0 0 1)) )');

    t

This example uses the same cube with one side missing.

    SELECT ST_IsClosed('POLYHEDRALSURFACE( ((0 0 0,0 0 1,0 1 1,0 1 0,0 0 0)),
           ((0 0 0,0 1 0,1 1 0,1 0 0,0 0 0)),((0 0 0,1 0 0,1 0 1,0 0 1,0 0 0)),
           ((1 1 0,1 1 1,1 0 1,1 0 0,1 1 0)),
           ((0 1 0,0 1 1,1 1 1,1 1 0,0 1 0)) )');

    f

### See Also

ST_IsRing

ST_IsCollection

Tests if a geometry is a geometry collection type.

    			boolean ST_IsCollection
    			geometry  g

### Description

Returns `TRUE` if the geometry type of the argument a geometry collection type. Collection types are the following:

- GEOMETRYCOLLECTION

- MULTI{POINT,POLYGON,LINESTRING,CURVE,SURFACE}

- COMPOUNDCURVE

This function analyzes the type of the geometry. This means that it will return `TRUE` on collections that are empty or that contain a single element.

&Z_support;

&curve_support;

### Examples

    SELECT ST_IsCollection('LINESTRING(0 0,1 1)'::geometry);

    f

    SELECT ST_IsCollection('MULTIPOINT EMPTY'::geometry);

    t

    SELECT ST_IsCollection('MULTIPOINT((0 0))'::geometry);

    t

    SELECT ST_IsCollection('MULTIPOINT((0 0),(42 42))'::geometry);

    t

    SELECT ST_IsCollection('GEOMETRYCOLLECTION(POINT(0 0))'::geometry);

    t

### See Also

ST_NumGeometries

ST_IsEmpty

Tests if a geometry is empty.

    			boolean ST_IsEmpty
    			geometry  geomA

### Description

Returns true if this Geometry is an empty geometry. If true, then this Geometry represents an empty geometry collection, polygon, point etc.

SQL-MM defines the result of ST_IsEmpty(NULL) to be 0, while PostGIS returns NULL.

&sfs_compliant; s2.1.1.1

&sqlmm_compliant; SQL-MM 3: 5.1.7

&curve_support;

Changed: 2.0.0 In prior versions of PostGIS ST_GeomFromText('GEOMETRYCOLLECTION(EMPTY)') was allowed. This is now illegal in PostGIS 2.0.0 to better conform with SQL/MM standards

### Examples

    SELECT ST_IsEmpty('GEOMETRYCOLLECTION EMPTY'::geometry);

    t

    SELECT ST_IsEmpty('POLYGON EMPTY'::geometry);

    t

    SELECT ST_IsEmpty('POLYGON((1 2,3 4,5 6,1 2))'::geometry);

    f

    SELECT ST_IsEmpty('POLYGON((1 2,3 4,5 6,1 2))'::geometry) = false;

     t
    (1 row)

    SELECT ST_IsEmpty('CIRCULARSTRING EMPTY'::geometry);

    t

ST_IsPolygonCCW

Tests if Polygons have exterior rings oriented counter-clockwise and interior rings oriented clockwise.

    					boolean ST_IsPolygonCCW
    					geometry geom

### Description

Returns true if all polygonal components of the input geometry use a counter-clockwise orientation for their exterior ring, and a clockwise direction for all interior rings.

Returns true if the geometry has no polygonal components.

Closed linestrings are not considered polygonal components, so you would still get a true return by passing a single closed linestring no matter its orientation.

If a polygonal geometry does not use reversed orientation for interior rings (i.e., if one or more interior rings are oriented in the same direction as an exterior ring) then both ST_IsPolygonCW and ST_IsPolygonCCW will return false.

Availability: 2.4.0

&Z_support;

&M_support;

### See Also

ST_ForcePolygonCW, ST_ForcePolygonCCW, ST_IsPolygonCW

ST_IsPolygonCW

Tests if Polygons have exterior rings oriented clockwise and interior rings oriented counter-clockwise.

    					boolean ST_IsPolygonCW
    					geometry geom

### Description

Returns true if all polygonal components of the input geometry use a clockwise orientation for their exterior ring, and a counter-clockwise direction for all interior rings.

Returns true if the geometry has no polygonal components.

Closed linestrings are not considered polygonal components, so you would still get a true return by passing a single closed linestring no matter its orientation.

If a polygonal geometry does not use reversed orientation for interior rings (i.e., if one or more interior rings are oriented in the same direction as an exterior ring) then both ST_IsPolygonCW and ST_IsPolygonCCW will return false.

Availability: 2.4.0

&Z_support;

&M_support;

### See Also

ST_ForcePolygonCW, ST_ForcePolygonCCW, ST_IsPolygonCW

ST_IsRing

Tests if a LineString is closed and simple.

    		  boolean ST_IsRing

    		  geometry  g

### Description

Returns `TRUE` if this `LINESTRING` is both ST_IsClosed (`ST_StartPoint(g) ~= ST_EndPoint(g)`) and ST_IsSimple (does not self intersect).

&sfs_compliant; 2.1.5.1

&sqlmm_compliant; SQL-MM 3: 7.1.6

SQL-MM defines the result of `ST_IsRing(NULL)` to be 0, while PostGIS returns `NULL`.

### Examples

    SELECT ST_IsRing(geom), ST_IsClosed(geom), ST_IsSimple(geom)
    FROM (SELECT 'LINESTRING(0 0,0 1,1 1,1 0,0 0)'::geometry AS geom) AS foo;

     st_isring | st_isclosed | st_issimple
    -----------+-------------+-------------
     t         | t           | t
    (1 row)

    SELECT ST_IsRing(geom), ST_IsClosed(geom), ST_IsSimple(geom)
    FROM (SELECT 'LINESTRING(0 0,0 1,1 0,1 1,0 0)'::geometry AS geom) AS foo;

     st_isring | st_isclosed | st_issimple
    -----------+-------------+-------------
     f         | t           | f
    (1 row)

### See Also

ST_IsClosed, ST_IsSimple, ST_StartPoint, ST_EndPoint

ST_IsSimple

Tests if a geometry has no points of self-intersection or self-tangency.

    			boolean ST_IsSimple
    			geometry  geomA

### Description

Returns true if this Geometry has no anomalous geometric points, such as self-intersection or self-tangency. For more information on the OGC's definition of geometry simplicity and validity, refer to "Ensuring OpenGIS compliance of geometries"

SQL-MM defines the result of ST_IsSimple(NULL) to be 0, while PostGIS returns NULL.

&sfs_compliant; s2.1.1.1

&sqlmm_compliant; SQL-MM 3: 5.1.8

&Z_support;

### Examples

    SELECT ST_IsSimple('POLYGON((1 2,3 4,5 6,1 2))');

    f

    SELECT ST_IsSimple('LINESTRING(1 1,2 2,2 3.5,1 3,1 2,2 1)');

    f

### See Also

ST_IsValid

ST_M

Returns the M coordinate of a Point.

    			float ST_M
    			geometry  a_point

### Description

Return the M coordinate of a Point, or NULL if not available. Input must be a Point.

This is not (yet) part of the OGC spec, but is listed here to complete the point coordinate extractor function list.

&sfs_compliant;

&sqlmm_compliant;

&Z_support;

### Examples

    SELECT ST_M('POINT(1 2 3 4)');

    4

### See Also

ST_GeomFromEWKT, ST_X, ST_Y, ST_Z

ST_MemSize

Returns the amount of memory space a geometry takes.

    			integer ST_MemSize
    			geometry  geomA

### Description

Returns the amount of memory space (in bytes) the geometry takes.

This complements the PostgreSQL built-in database object functions pg_column_size, pg_size_pretty, pg_relation_size, pg_total_relation_size.

pg_relation_size which gives the byte size of a table may return byte size lower than ST_MemSize. This is because pg_relation_size does not add toasted table contribution and large geometries are stored in TOAST tables.

pg_total_relation_size - includes, the table, the toasted tables, and the indexes.

pg_column_size returns how much space a geometry would take in a column considering compression, so may be lower than ST_MemSize

&Z_support;

&curve_support;

&P_support;

&T_support;

Changed: 2.2.0 name changed to ST_MemSize to follow naming convention.

### Examples

Compare the memory used by all geometries in a Massachusetts town dataset with the subset for Boston.

    SELECT pg_size_pretty(sum(ST_MemSize(geom))) AS totgeomsum,
           pg_size_pretty(sum(CASE WHEN town = 'BOSTON' THEN ST_MemSize(geom) ELSE 0 END)) AS bossum,
           cast(
               sum(CASE WHEN town = 'BOSTON' THEN ST_MemSize(geom) ELSE 0 END) * 100.0
               / sum(ST_MemSize(geom)) AS numeric(10, 2)
           ) AS perbos
    FROM towns;

     totgeomsum | bossum | perbos
    ------------+--------+--------
     1522 kB    | 30 kB  |   1.99
    (1 row)

Return the memory size of a CircularString in bytes.

    SELECT ST_MemSize('CIRCULARSTRING(220268 150415,220227 150505,220227 150406)'::geometry);

     st_memsize
    ------------
             80
    (1 row)

Calculate the percentage of a table's total size used by geometry data.

    SELECT pg_total_relation_size('public.neighborhoods') AS fulltable_size,
           sum(ST_MemSize(geom)) AS geomsize,
           sum(ST_MemSize(geom)) * 100.0
               / pg_total_relation_size('public.neighborhoods') AS pergeom
    FROM neighborhoods;

     fulltable_size | geomsize |         pergeom
    ----------------+----------+--------------------------
             262144 |    96238 | 36.71188354492187500000
    (1 row)

ST_NDims

Returns the coordinate dimension of a geometry.

    			integer ST_NDims
    			geometry  g1

### Description

Returns the coordinate dimension of the geometry. PostGIS supports 2 - (x,y) , 3 - (x,y,z) or 2D with measure - x,y,m, and 4 - 3D with measure space x,y,z,m

&Z_support;

### Examples

    SELECT ST_NDims('POINT(1 1)') As d2point,
    ST_NDims('POINT(1 1 2)') As d3point,
    ST_NDims('POINTM(1 1 0.5)') As d2pointm;

     d2point | d3point | d2pointm
    ---------+---------+----------
           2 |       3 |        3

### See Also

ST_CoordDim, ST_Dimension, ST_GeomFromEWKT

ST_NPoints

Returns the number of points (vertices) in a geometry.

    			integer ST_NPoints
    			geometry  g1

### Description

Return the number of points in a geometry. Works for all geometries.

Enhanced: 2.0.0 support for Polyhedral surfaces was introduced.

Prior to 1.3.4, this function crashes if used with geometries that contain CURVES. This is fixed in 1.3.4+

&Z_support;

&curve_support;

&P_support;

### Examples

Count the points in a 2D LineString.

    SELECT ST_NPoints('LINESTRING(77.29 29.07,77.42 29.26,77.27 29.31,77.29 29.07)');

     st_npoints
    ------------
              4
    (1 row)

Count the points in a 3D LineString.

    SELECT ST_NPoints('LINESTRING(77.29 29.07 1,77.42 29.26 0,77.27 29.31 -1,77.29 29.07 3)');

     st_npoints
    ------------
              4
    (1 row)

### See Also

ST_NumPoints

ST_NRings

Returns the number of rings in a polygonal geometry.

    			integer ST_NRings
    			geometry  geomA

### Description

If the geometry is a polygon or multi-polygon returns the number of rings. Unlike NumInteriorRings, it counts the outer rings as well.

&Z_support;

&curve_support;

### Examples

    SELECT ST_NRings(geom) As Nrings, ST_NumInteriorRings(geom) As ninterrings
    FROM (SELECT 'POLYGON((1 2,3 4,5 6,1 2))'::geometry As geom) As foo;

     nrings | ninterrings
    --------+-------------
          1 |           0
    (1 row)

### See Also

ST_NumInteriorRings

ST_NumGeometries

Returns the number of elements in a geometry collection.

    			integer ST_NumGeometries
    			geometry  geom

### Description

Returns the number of elements in a geometry collection (GEOMETRYCOLLECTION or MULTI*). For non-empty atomic geometries returns 1. For empty geometries returns 0.

Enhanced: 2.0.0 support for Polyhedral surfaces, Triangles and TIN was introduced.

Changed: 2.0.0 In prior versions this would return NULL if the geometry was not a collection/MULTI type. 2.0.0+ now returns 1 for single geometries e.g POLYGON, LINESTRING, POINT.

Changed: 3.6.0 TIN and PolyhedralSurface are treated as unitary geometries and return 1; use ST_NumPatches to count faces.

&sqlmm_compliant; SQL-MM 3: 9.1.4

&Z_support;

&P_support;

&T_support;

### Examples

This example returns 1; prior versions would have returned NULL.

    SELECT ST_NumGeometries('LINESTRING(77.29 29.07,77.42 29.26,77.27 29.31,77.29 29.07)');

     st_numgeometries
    ------------------
                    1
    (1 row)

A MultiPoint counts as one geometry within a GeometryCollection.

    SELECT ST_NumGeometries('GEOMETRYCOLLECTION(MULTIPOINT((-2 3),(-2 2)),
    LINESTRING(5 5,10 10),
    POLYGON((-7 4.2,-7.1 5,-7.1 4.3,-7 4.2)))');

     st_numgeometries
    ------------------
                    3
    (1 row)

### See Also

ST_GeometryN, ST_Multi

ST_NumInteriorRings

Returns the number of interior rings (holes) of a Polygon.

    			integer ST_NumInteriorRings
    			geometry  a_polygon

### Description

Return the number of interior rings of a polygon geometry. Return NULL if the geometry is not a polygon.

&sqlmm_compliant; SQL-MM 3: 8.2.5

Changed: 2.0.0 - in prior versions it would allow passing a MULTIPOLYGON, returning the number of interior rings of first POLYGON.

### Examples

Count the interior rings of a Polygon.

    SELECT gid, field1, field2, ST_NumInteriorRings(geom) AS numholes
    FROM sometable;

For a MultiPolygon, dump its component Polygons and sum their interior ring counts.

    SELECT gid, field1, field2, SUM(ST_NumInteriorRings(geom)) AS numholes
    FROM (
        SELECT gid, field1, field2, (ST_Dump(geom)).geom AS geom
        FROM sometable
    ) AS foo
    GROUP BY gid, field1, field2;

### See Also

ST_NumInteriorRing, ST_InteriorRingN

ST_NumInteriorRing

Returns the number of interior rings (holes) of a Polygon. Alias for ST_NumInteriorRings.

    			integer ST_NumInteriorRing
    			geometry  a_polygon

### Description

This function is an alias for ST_NumInteriorRings.

Availability: 1.2.2

### See Also

ST_NumInteriorRings, ST_InteriorRingN

ST_NumPatches

Returns the number of faces in a PolyhedralSurface or TIN.

    			integer ST_NumPatches
    			geometry  g1

### Description

Returns the number of faces in a PolyhedralSurface or TIN. Returns NULL for other geometries. Unlike ST_NumGeometries, this function counts individual faces.

Availability: 2.0.0

&Z_support;

&sfs_compliant;

&sqlmm_compliant; SQL-MM ISO/IEC 13249-3: 8.5

&P_support;

### Examples

    SELECT ST_NumPatches('POLYHEDRALSURFACE( ((0 0 0,0 0 1,0 1 1,0 1 0,0 0 0)),
    ((0 0 0,0 1 0,1 1 0,1 0 0,0 0 0)),((0 0 0,1 0 0,1 0 1,0 0 1,0 0 0)),
    ((1 1 0,1 1 1,1 0 1,1 0 0,1 1 0)),
    ((0 1 0,0 1 1,1 1 1,1 1 0,0 1 0)),((0 0 1,1 0 1,1 1 1,0 1 1,0 0 1)) )');

     st_numpatches
    ---------------
                 6
    (1 row)

### See Also

ST_GeomFromEWKT, ST_NumGeometries, ST_PatchN

ST_NumPoints

Returns the number of points in a LineString or CircularString.

    			integer ST_NumPoints
    			geometry  g1

### Description

Return the number of points in an ST_LineString or ST_CircularString value. Prior to 1.4 only works with linestrings as the specs state. From 1.4 forward this is an alias for ST_NPoints which returns number of vertices for not just linestrings. Consider using ST_NPoints instead which is multi-purpose and works with many geometry types.

&sfs_compliant;

&sqlmm_compliant; SQL-MM 3: 7.2.4

### Examples

    SELECT ST_NumPoints('LINESTRING(77.29 29.07,77.42 29.26,77.27 29.31,77.29 29.07)');

     st_numpoints
    --------------
                4
    (1 row)

### See Also

ST_NPoints

ST_PatchN

Returns the Nth face of a PolyhedralSurface or TIN.

    			geometry ST_PatchN
    			geometry  geomA
    			integer  n

### Description

Returns the 1-based Nth face of a PolyhedralSurface or TIN. Returns NULL for other geometries or an out-of-range index. Use this function to access faces, because ST_GeometryN treats PolyhedralSurface and TIN as unitary geometries.

Index is 1-based.

If you want to extract all elements of a geometry ST_Dump is more efficient.

Availability: 2.0.0

&sqlmm_compliant; SQL-MM ISO/IEC 13249-3: 8.5

&Z_support;

&P_support;

&T_support;

### Examples

Extract the 2nd face of the polyhedral surface.

    SELECT ST_PatchN(geom, 2) As geomewkt
    FROM (
    VALUES ('POLYHEDRALSURFACE( ((0 0 0,0 0 1,0 1 1,0 1 0,0 0 0)),
        ((0 0 0,0 1 0,1 1 0,1 0 0,0 0 0)),((0 0 0,1 0 0,1 0 1,0 0 1,0 0 0)),
        ((1 1 0,1 1 1,1 0 1,1 0 0,1 1 0)),
        ((0 1 0,0 1 1,1 1 1,1 1 0,0 1 0)),((0 0 1,1 0 1,1 1 1,0 1 1,0 0 1)) )'::geometry) ) As foo(geom);

    POLYGON((0 0 0,0 1 0,1 1 0,1 0 0,0 0 0))

### See Also

ST_AsEWKT, ST_GeomFromEWKT, ST_Dump, ST_GeometryN, ST_NumGeometries, ST_NumPatches

ST_PointN

Returns the Nth point in the first LineString or circular LineString in a geometry.

    			geometry ST_PointN
    			geometry  a_linestring
    			integer  n

### Description

Return the Nth point in a single linestring or circular linestring in the geometry. Negative values are counted backwards from the end of the LineString, so that -1 is the last point. Returns NULL if there is no linestring in the geometry.

Index is 1-based as for OGC specs since version 0.8.0. Backward indexing (negative index) is not in OGC. Previous versions implemented this as 0-based instead.

If you want to get the Nth point of each LineString in a MultiLineString, use in conjunction with ST_Dump

&sfs_compliant;

&sqlmm_compliant; SQL-MM 3: 7.2.5, 7.3.5

&Z_support;

&curve_support;

Changed: 2.0.0 no longer works with single geometry multilinestrings. In older versions of PostGIS -- a single line multilinestring would work happily with this function and return the start point. In 2.0.0 it just returns NULL like any other multilinestring.

Changed: 2.3.0 : negative indexing available (-1 is last point)

### Examples

This example extracts all POINT geometries from a LineString.

    SELECT ST_PointN(
          column1,
          generate_series(1, ST_NPoints(column1))
       )
    FROM ( VALUES ('LINESTRING(0 0,1 1,2 2)'::geometry) ) AS foo;

     POINT(0 0)
     POINT(1 1)
     POINT(2 2)
    (3 rows)

This example uses a CircularString.

    SELECT ST_PointN('CIRCULARSTRING(1 2,3 2,1 2)', 2);

    POINT(3 2)

The index is 1-based. A negative index counts backward from the end of the LineString.

    SELECT f
    FROM ST_GeomFromText('LINESTRING(0 0 0,1 1 1,2 2 2)') AS g
      CROSS JOIN ST_PointN(g, -2) AS f;

    POINT Z (1 1 1)

### See Also

ST_NPoints

ST_Points

Returns a MultiPoint containing the coordinates of a geometry.

    					geometry ST_Points

    						geometry
    						geom

### Description

Returns a MultiPoint containing all the coordinates of a geometry. Duplicate points are preserved, including the start and end points of ring geometries. (If desired, duplicate points can be removed by calling ST_RemoveRepeatedPoints on the result).

To obtain information about the position of each coordinate in the parent geometry use ST_DumpPoints.

M and Z coordinates are preserved if present.

&curve_support;

&Z_support;

Availability: 2.3.0

### Examples

    SELECT ST_Points('POLYGON Z ((30 10 4,10 30 5,40 40 6,30 10 4))');

    MULTIPOINT Z ((30 10 4),(10 30 5),(40 40 6),(30 10 4))

### See Also

ST_RemoveRepeatedPoints, ST_DumpPoints

ST_StartPoint

Returns the first point of a LineString, CircularLineString, or NURBSCurve.

    		  geometry ST_StartPoint

    		  geometry  geomA

### Description

Returns the first point of a `LINESTRING`, `CIRCULARLINESTRING`, or `NURBSCURVE` geometry as a `POINT`. For other geometries, returns the first point in coordinate order.

&sqlmm_compliant; SQL-MM 3: 7.1.3

&Z_support;

&curve_support;

Enhanced: 3.2.0 returns a point for all geometries. Prior behavior returns NULLs if input was not a LineString.

Changed: 2.0.0 no longer works with single geometry MultiLineStrings. In older versions of PostGIS a single-line MultiLineString would work happily with this function and return the start point. In 2.0.0 it just returns NULL like any other MultiLineString. The old behavior was an undocumented feature, but people who assumed they had their data stored as LINESTRING may experience these returning NULL in 2.0.0.

### Examples

Start point of a LineString

    SELECT ST_StartPoint('LINESTRING(0 1,0 2)'::geometry);

    POINT(0 1)

Start point of a Point is the Point itself

    SELECT ST_StartPoint('POINT(0 1)'::geometry);

    POINT(0 1)

Start point of a 3D LineString

    SELECT ST_StartPoint('LINESTRING(0 1 1,0 2 2)'::geometry);

    POINT(0 1 1)

Start point of a CircularString

    SELECT ST_StartPoint('CIRCULARSTRING(5 2,-3 2,-2 1,-4 2,6 3)'::geometry);

    POINT(5 2)

Start point of a NURBSCurve

    SELECT ST_StartPoint('NURBSCURVE(2, (0 0, 1 1, 2 0))'::geometry);

    POINT(0 0)

Build edge node references from the start and end points of a LineString table. The example uses exact endpoint equality, so linework with nearly coincident endpoints should be snapped or otherwise cleaned first.

    WITH roads(road_id, geom) AS (
      VALUES
        (1, 'LINESTRING(0 0, 1 0)'::geometry),
        (2, 'LINESTRING(1 0, 1 1)'::geometry),
        (3, 'LINESTRING(1 0, 2 0)'::geometry)
    ),
    endpoints AS (
      SELECT road_id, 'from' AS end_name, ST_StartPoint(geom) AS geom,
             ST_AsEWKB(ST_StartPoint(geom)) AS endpoint_key
      FROM roads
      UNION ALL
      SELECT road_id, 'to' AS end_name, ST_EndPoint(geom) AS geom,
             ST_AsEWKB(ST_EndPoint(geom)) AS endpoint_key
      FROM roads
    ),
    nodes AS (
      SELECT dense_rank() OVER (ORDER BY ST_X(geom), ST_Y(geom), endpoint_key) AS node_id,
             endpoint_key
      FROM (
        SELECT DISTINCT ON (endpoint_key) endpoint_key, geom
        FROM endpoints
        ORDER BY endpoint_key
      ) AS distinct_endpoints
    )
    SELECT e.road_id,
           max(n.node_id) FILTER (WHERE e.end_name = 'from') AS from_node,
           max(n.node_id) FILTER (WHERE e.end_name = 'to') AS to_node
    FROM endpoints AS e
    JOIN nodes AS n USING (endpoint_key)
    GROUP BY e.road_id
    ORDER BY e.road_id;

     road_id | from_node | to_node
    ---------+-----------+---------
         1 |         1 |       2
         2 |         2 |       3
         3 |         2 |       4

### See Also

ST_EndPoint, ST_PointN

ST_StartM

Returns the M coordinate of the first point of a LineString, CircularLineString, or NURBSCurve.

    		  float8 ST_StartM

    		  geometry  geom

### Description

Returns the M coordinate of the first point of a `LINESTRING`, `CIRCULARLINESTRING`, or `NURBSCURVE` geometry. Returns `NULL` if the input geometry does not have an M dimension or is not a `LINESTRING`, `CIRCULARLINESTRING`, or `NURBSCURVE`.

&curve_support;

### Examples

Start M value of a LineString

    SELECT ST_StartM('LINESTRING M(0 0 10,1 1 20,2 0 30)'::geometry);

    10

Start M value of a CircularString

    SELECT ST_StartM('CIRCULARSTRING M(0 0 5,1 1 10,2 0 15)'::geometry);

    5

Start M value of a NURBSCurve

    SELECT ST_StartM('NURBSCURVE M(2, (0 0 100, 1 1 200, 2 0 300))'::geometry);

    100

Geometry without M dimension returns NULL

    SELECT ST_StartM('LINESTRING(0 0,1 1)'::geometry) IS NULL AS is_null;

    t

### See Also

ST_EndM, ST_SetStartM, ST_StartPoint

ST_EndM

Returns the M coordinate of the last point of a LineString, CircularLineString, or NURBSCurve.

    		  float8 ST_EndM

    		  geometry  geom

### Description

Returns the M coordinate of the last point of a `LINESTRING`, `CIRCULARLINESTRING`, or `NURBSCURVE` geometry. Returns `NULL` if the input geometry does not have an M dimension or is not a `LINESTRING`, `CIRCULARLINESTRING`, or `NURBSCURVE`.

&curve_support;

### Examples

End M value of a LineString

    SELECT ST_EndM('LINESTRING M(0 0 10,1 1 20,2 0 30)'::geometry);

    30

End M value of a CircularString

    SELECT ST_EndM('CIRCULARSTRING M(0 0 5,1 1 10,2 0 15)'::geometry);

    15

End M value of a NURBSCurve

    SELECT ST_EndM('NURBSCURVE M(2, (0 0 100, 1 1 200, 2 0 300))'::geometry);

    300

Geometry without M dimension returns NULL

    SELECT ST_EndM('LINESTRING(0 0,1 1)'::geometry) IS NULL AS is_null;

    t

### See Also

ST_StartM, ST_SetEndM, ST_EndPoint

ST_SetStartM

Sets the M coordinate of the first point of a LineString, CircularLineString, or NURBSCurve.

    		  geometry ST_SetStartM

    		  geometry  geom
    		  float8  m

### Description

Returns a copy of the input `LINESTRING`, `CIRCULARLINESTRING`, or `NURBSCURVE` geometry with the M coordinate of the first point set to the specified value. If the input geometry does not have an M dimension, it will be added. Returns `NULL` if the input is not a `LINESTRING`, `CIRCULARLINESTRING`, or `NURBSCURVE`.

&curve_support;

### Examples

Set start M value of a LineString

    SELECT ST_SetStartM('LINESTRING M(0 0 10,1 1 20,2 0 30)'::geometry, 100);

    LINESTRING M (0 0 100,1 1 20,2 0 30)

Add M dimension and set start M value

    SELECT ST_SetStartM('LINESTRING(0 0,1 1,2 0)'::geometry, 50);

    LINESTRING M (0 0 50,1 1 0,2 0 0)

Set start M value of a CircularString

    SELECT ST_SetStartM('CIRCULARSTRING M(0 0 5,1 1 10,2 0 15)'::geometry, 99);

    CIRCULARSTRING M (0 0 99,1 1 10,2 0 15)

Set start M value of a NURBSCurve

    SELECT ST_SetStartM('NURBSCURVE M(2, (0 0 100, 1 1 200, 2 0 300))'::geometry, 500);

    NURBSCURVE M (DEGREE 2,CONTROLPOINTS M (NURBSPOINT(WEIGHTEDPOINT M (0 0 500),WEIGHT 1), NURBSPOINT(WEIGHTEDPOINT M (1 1 200),WEIGHT 1), NURBSPOINT(WEIGHTEDPOINT M (2 0 300),WEIGHT 1)),KNOTS (KNOT(0,3), KNOT(1,3)))

### See Also

ST_SetEndM, ST_StartM, ST_StartPoint

ST_SetEndM

Sets the M coordinate of the last point of a LineString, CircularLineString, or NURBSCurve.

    		  geometry ST_SetEndM

    		  geometry  geom
    		  float8  m

### Description

Returns a copy of the input `LINESTRING`, `CIRCULARLINESTRING`, or `NURBSCURVE` geometry with the M coordinate of the last point set to the specified value. If the input geometry does not have an M dimension, it will be added. Returns `NULL` if the input is not a `LINESTRING`, `CIRCULARLINESTRING`, or `NURBSCURVE`.

&curve_support;

### Examples

Set end M value of a LineString

    SELECT ST_SetEndM('LINESTRING M(0 0 10,1 1 20,2 0 30)'::geometry, 999);

    LINESTRING M (0 0 10,1 1 20,2 0 999)

Add M dimension and set end M value

    SELECT ST_SetEndM('LINESTRING(0 0,1 1,2 0)'::geometry, 75);

    LINESTRING M (0 0 0,1 1 0,2 0 75)

Set end M value of a CircularString

    SELECT ST_SetEndM('CIRCULARSTRING M(0 0 5,1 1 10,2 0 15)'::geometry, 88);

    CIRCULARSTRING M (0 0 5,1 1 10,2 0 88)

Set end M value of a NURBSCurve

    SELECT ST_SetEndM('NURBSCURVE M(2, (0 0 100, 1 1 200, 2 0 300))'::geometry, 999);

    NURBSCURVE M (DEGREE 2,CONTROLPOINTS M (NURBSPOINT(WEIGHTEDPOINT M (0 0 100),WEIGHT 1), NURBSPOINT(WEIGHTEDPOINT M (1 1 200),WEIGHT 1), NURBSPOINT(WEIGHTEDPOINT M (2 0 999),WEIGHT 1)),KNOTS (KNOT(0,3), KNOT(1,3)))

### See Also

ST_SetStartM, ST_EndM, ST_EndPoint

ST_Summary

Returns a text summary of the contents of a geometry.

    			text ST_Summary
    			geometry  g

    			text ST_Summary
    			geography  g

### Description

Returns a text summary of the contents of the geometry.

Flags shown square brackets after the geometry type have the following meaning:

- M: has M coordinate

- Z: has Z coordinate

- B: has a cached bounding box

- G: is geodetic (geography)

- S: has spatial reference system

&curve_support;

&P_support;

&T_support;

Availability: 1.2.2

Enhanced: 2.0.0 added support for geography

Enhanced: 2.1.0 S flag to denote if has a known spatial reference system

Enhanced: 2.2.0 Added support for TIN and Curves

### Examples

    SELECT ST_Summary('LINESTRING(0 0,1 1)'::geometry) as geom,
    ST_Summary('POLYGON((0 0,1 1,1 2,1 1,0 0))'::geography) geog;

                geom             |          geog
    -----------------------------+--------------------------
     LineString[B] with 2 points | Polygon[BGS] with 1 rings
                                 | ring 0 has 5 points
                                 :
    (1 row)

    SELECT ST_Summary('LINESTRING(0 0 1,1 1 1)'::geography) As geog_line,
    ST_Summary('SRID=4326;POLYGON((0 0 1,1 1 2,1 2 3,1 1 1,0 0 1))'::geometry) As geom_poly;

              geog_line             |        geom_poly
    -------------------------------- +--------------------------
     LineString[ZBGS] with 2 points | Polygon[ZBS] with 1 rings
                                    :    ring 0 has 5 points
                                    :
    (1 row)

### See Also

PostGIS_DropBBox, PostGIS_AddBBox, ST_Force_3DM, ST_Force_3DZ, ST_Force2D, geography

ST_IsValid, ST_IsValid, ST_IsValidReason, ST_IsValidDetail

ST_X

Returns the X coordinate of a Point.

    			float ST_X
    			geometry  a_point

### Description

Return the X coordinate of the point, or NULL if not available. Input must be a point.

To get the minimum and maximum X value of geometry coordinates use the functions ST_XMin and ST_XMax.

&sqlmm_compliant; SQL-MM 3: 6.1.3

&Z_support;

### Examples

    SELECT ST_X('POINT(1 2 3 4)');

    1

    SELECT ST_Y(ST_Centroid('LINESTRING(1 2 3 4,1 1 1 1)'::geometry));

    1.5

### See Also

ST_Centroid, ST_GeomFromEWKT, ST_M, ST_XMax, ST_XMin, ST_Y, ST_Z

ST_Y

Returns the Y coordinate of a Point.

    			float ST_Y
    			geometry  a_point

### Description

Return the Y coordinate of the point, or NULL if not available. Input must be a point.

To get the minimum and maximum Y value of geometry coordinates use the functions ST_YMin and ST_YMax.

&sfs_compliant;

&sqlmm_compliant; SQL-MM 3: 6.1.4

&Z_support;

### Examples

    SELECT ST_Y('POINT(1 2 3 4)');

    2

    SELECT ST_Y(ST_Centroid('LINESTRING(1 2 3 4,1 1 1 1)'::geometry));

    1.5

### See Also

ST_Centroid, ST_GeomFromEWKT, ST_M, ST_X, ST_YMax, ST_YMin, ST_Z

ST_Z

Returns the Z coordinate of a Point.

    			float ST_Z
    			geometry  a_point

### Description

Return the Z coordinate of the point, or NULL if not available. Input must be a point.

To get the minimum and maximum Z value of geometry coordinates use the functions ST_ZMin and ST_ZMax.

&sqlmm_compliant;

&Z_support;

### Examples

    SELECT ST_Z('POINT(1 2 3 4)');

    3

### See Also

ST_GeomFromEWKT, ST_M, ST_X, ST_Y, ST_ZMax, ST_ZMin

ST_ZMFlag

Returns a code indicating the ZM coordinate dimension of a geometry.

    			smallint ST_ZMFlag
    			geometry  geomA

### Description

Returns a code indicating the ZM coordinate dimension of a geometry.

Values are: 0 = 2D, 1 = 3D-M, 2 = 3D-Z, 3 = 4D.

&Z_support;

&curve_support;

### Examples

    SELECT ST_ZMFlag('LINESTRING(1 2,3 4)');

    0

    SELECT ST_ZMFlag('LINESTRINGM(1 2 3, 3 4 3)');

    1

    SELECT ST_ZMFlag('CIRCULARSTRING(1 2 3,3 4 3,5 6 3)');

    2

    SELECT ST_ZMFlag('POINT(1 2 3 4)');

    3

### See Also

ST_CoordDim, ST_NDims, ST_Dimension

ST_HasZ

Checks if a geometry has a Z dimension.

            boolean ST_HasZ
            geometry geom

### Description

Checks if the input geometry has a Z dimension and returns a boolean value. If the geometry has a Z dimension, it returns true; otherwise, it returns false.

Geometry objects with a Z dimension typically represent three-dimensional (3D) geometries, while those without it are two-dimensional (2D) geometries.

This function is useful for determining if a geometry has elevation or height information.

Availability: 3.5.0

&Z_support;

&M_support;

### Examples

    SELECT ST_HasZ('POINT(1 2 3)');

    t

    SELECT ST_HasZ('LINESTRING(0 0,1 1)');

    f

### See Also

ST_ZMFlag

ST_HasM

ST_HasM

Checks if a geometry has an M (measure) dimension.

            boolean ST_HasM
            geometry geom

### Description

Checks if the input geometry has an M (measure) dimension and returns a boolean value. If the geometry has an M dimension, it returns true; otherwise, it returns false.

Geometry objects with an M dimension typically represent measurements or additional data associated with spatial features.

This function is useful for determining if a geometry includes measure information.

Availability: 3.5.0

&Z_support;

&M_support;

### Examples

    SELECT ST_HasM('POINTM(1 2 3)');

    t

    SELECT ST_HasM('LINESTRING(0 0,1 1)');

    f

### See Also

ST_ZMFlag

ST_HasZ

ST_ControlPoints

Returns the control points of a NURBS curve as a MULTIPOINT geometry.

    					geometry ST_ControlPoints
    					geometry nurbscurve

### Description

Extracts the control points from a NURBS curve and returns them as a MULTIPOINT geometry. Control points define the control polygon that influences the shape of the NURBS curve.

The function raises an error if the input is not a NURBS curve. Returns NULL if the input is NULL.

Availability: 3.7.0

### Examples

This example extracts control points from a NURBS curve.

    SELECT ST_ControlPoints('NURBSCURVE(2, (0 0, 5 10, 10 0))'::geometry);

    MULTIPOINT((0 0),(5 10),(10 0))

This example counts the control points.

    SELECT ST_NPoints(ST_ControlPoints('NURBSCURVE(2, (0 0, 5 10, 10 0))'::geometry));

    3

### See Also

ST_MakeNurbsCurve, ST_NumControlPoints, ST_Weights

ST_Degree

Returns the polynomial degree of a NURBS curve.

    					integer ST_Degree
    					geometry nurbscurve

### Description

Returns the polynomial degree of a NURBS curve as an integer. The degree determines the curve's smoothness and flexibility. Higher degrees produce smoother curves but require more control points.

The function raises an error if the input is not a NURBS curve. Returns NULL if the input is NULL.

Availability: 3.7.0

### Examples

This example returns the degree of a NURBS curve.

    SELECT ST_Degree('NURBSCURVE(2, (0 0, 5 10, 10 0))'::geometry);

    2

This example checks whether a NURBS curve is cubic.

    SELECT ST_Degree('NURBSCURVE(3, (0 0, 2 5, 5 8, 10 0))'::geometry) = 3;

    t

### See Also

ST_MakeNurbsCurve, ST_NumControlPoints

ST_Weights

Returns the weight array of a rational NURBS curve.

    					float8[] ST_Weights
    					geometry nurbscurve

### Description

Returns the weight values of a rational NURBS curve as an array of double precision values. Weights control the influence of each control point on the curve shape. Higher weights pull the curve closer to the corresponding control point.

Returns NULL if the curve has no weights (non-rational B-spline) or if the input is NULL. Raises an error if the input is not a NURBS curve.

Availability: 3.7.0

### Examples

This example returns weights from a rational NURBS curve.

    SELECT ST_Weights(ST_MakeNurbsCurve(2, 'LINESTRING(0 0,5 10,10 0)'::geometry, ARRAY[1.0, 2.0, 1.0]));

    {1,2,1}

This example checks the weights of a non-rational curve.

    SELECT ST_Weights('NURBSCURVE(2, (0 0, 5 10, 10 0))'::geometry);

    null

### See Also

ST_MakeNurbsCurve, ST_NurbsCurveIsRational, ST_ControlPoints

ST_Knots

Returns the knot vector of a NURBS curve.

    					float8[] ST_Knots
    					geometry nurbscurve

### Description

Returns the knot vector of a NURBS curve as an array of double precision values. The knot vector defines the parameter space and controls where and how the control points affect the curve. It must be a non-decreasing sequence with length equal to (number of control points + degree + 1).

Returns NULL if the curve uses the default uniform clamped knot vector or if the input is NULL. Raises an error if the input is not a NURBS curve.

Availability: 3.7.0

### Examples

This example returns knots from a NURBS curve with a custom knot vector.

    SELECT ST_Knots(ST_MakeNurbsCurve(
            2,
            'LINESTRING(0 0,5 10,10 0)'::geometry,
            ARRAY[1.0, 2.0, 1.0],
            ARRAY[0, 0, 0, 1, 1, 1]));

    {0,0,0,1,1,1}

This example checks the knots of a curve using the default knot vector.

    SELECT ST_Knots('NURBSCURVE(2, (0 0, 5 10, 10 0))'::geometry);

    null

### See Also

ST_MakeNurbsCurve, ST_Degree, ST_NumControlPoints

ST_NumControlPoints

Returns the number of control points in a NURBS curve.

    					integer ST_NumControlPoints
    					geometry nurbscurve

### Description

Returns the number of control points in a NURBS curve. The number of control points must be at least (degree + 1) for a valid NURBS curve.

Raises an error if the input is not a NURBS curve. Returns NULL if the input is NULL.

Availability: 3.7.0

### Examples

This example returns the number of control points.

    SELECT ST_NumControlPoints('NURBSCURVE(2, (0 0, 5 10, 10 0))'::geometry);

    3

This example verifies that a curve has enough control points for its degree.

    SELECT ST_NumControlPoints(curve) >= ST_Degree(curve) + 1 AS valid
    FROM (SELECT 'NURBSCURVE(2, (0 0, 5 10, 10 0))'::geometry AS curve) AS t;

    t

### See Also

ST_MakeNurbsCurve, ST_ControlPoints, ST_Degree

ST_NurbsCurveIsRational

Checks if a NURBS curve is rational (has weights).

    					boolean ST_NurbsCurveIsRational
    					geometry nurbscurve

### Description

Returns TRUE if the NURBS curve has weights assigned to its control points (rational NURBS), FALSE if it uses uniform weights (non-rational B-spline).

Rational NURBS curves provide more flexibility in curve shape control through variable weights. Non-rational B-splines use uniform weights and are a special case of NURBS curves.

Raises an error if the input is not a NURBS curve. Returns NULL if the input is NULL.

Availability: 3.7.0

### Examples

This example checks whether a curve is rational.

    SELECT ST_NurbsCurveIsRational(ST_MakeNurbsCurve(
            2,
            'LINESTRING(0 0,5 10,10 0)'::geometry,
            ARRAY[1.0, 2.0, 1.0]));

    t

This example checks a non-rational curve.

    SELECT ST_NurbsCurveIsRational('NURBSCURVE(2, (0 0, 5 10, 10 0))'::geometry);

    f

### See Also

ST_MakeNurbsCurve, ST_Weights, ST_IsNurbsCurve

ST_IsNurbsCurve

Checks if a geometry is a NURBS curve.

    					boolean ST_IsNurbsCurve
    					geometry geom

### Description

Returns TRUE if the geometry is a NURBS curve, FALSE otherwise. This function can be used to test geometry types before applying NURBS-specific functions.

Returns NULL if the input is NULL.

Availability: 3.7.0

### Examples

This example checks whether a geometry is a NURBS curve.

    SELECT ST_IsNurbsCurve('NURBSCURVE(2, (0 0, 5 10, 10 0))'::geometry);

    t

This example tests a regular LineString.

    SELECT ST_IsNurbsCurve('LINESTRING(0 0,10 10)'::geometry);

    f

### See Also

ST_MakeNurbsCurve, ST_GeometryType, ST_NurbsCurveIsRational

ST_Evaluate

Evaluates a NURBS curve at a specific parameter value and returns the resulting point.

    					geometry ST_Evaluate
    					geometry nurbscurve
    					float8 parameter

### Description

Evaluates a NURBS curve at the specified parameter value and returns a POINT geometry representing the position on the curve. The parameter typically ranges from 0.0 (start of curve) to 1.0 (end of curve), though the actual range depends on the knot vector.

Raises an error if the input is not a NURBS curve or if evaluation fails. Returns NULL if either input is NULL.

Availability: 3.7.0

### Examples

This example returns the midpoint of a NURBS curve.

    SELECT ST_Evaluate('NURBSCURVE(2, (0 0, 5 10, 10 0))'::geometry, 0.5);

This example samples multiple points along a curve.

    SELECT t, ST_Evaluate(curve, t) AS point
    FROM (SELECT 'NURBSCURVE(2, (0 0, 5 10, 10 0))'::geometry AS curve) AS c,
             generate_series(0, 1, 0.25) AS t;

### See Also

ST_MakeNurbsCurve, ST_NurbsToLineString

ST_NurbsToLineString

Converts a NURBS curve to a LINESTRING by uniform sampling.

    					geometry ST_NurbsToLineString
    					geometry nurbscurve
    					integer num_segments=32

### Description

Converts a NURBS curve to a LINESTRING geometry by creating a piecewise linear approximation. The curve is sampled at uniformly distributed parameter values and the resulting points are connected with straight line segments.

The optional `num_segments` parameter specifies the number of line segments in the output (default: 32, range: 2-10000). Higher values produce smoother approximations but increase geometry complexity.

Raises an error if the input is not a NURBS curve. Returns NULL if the input is NULL.

Availability: 3.7.0

### Examples

This example converts a NURBS curve to a LineString using the default quality.

    SELECT ST_NurbsToLineString('NURBSCURVE(2, (0 0, 5 10, 10 0))'::geometry);

    LINESTRING(0 0,0.3125 0.60546875,0.625 1.171875,0.9375 1.69921875,1.25 2.1875,1.5625 2.63671875,1.875 3.046875,2.1875 3.41796875,2.5 3.75,2.8125 4.04296875,3.125 4.296875,3.4375 4.51171875,3.75 4.6875,4.0625 4.82421875,4.375 4.921875,4.6875 4.98046875,5 5,5.3125 4.98046875,5.625 4.921875,5.9375 4.82421875,6.25 4.6875,6.5625 4.51171875,6.875 4.296875,7.1875 4.04296875,7.5 3.75,7.8125 3.41796875,8.125 3.046875,8.4375 2.63671875,8.75 2.1875,9.0625 1.69921875,9.375 1.171875,9.6875 0.60546875,10 0)

This example creates a high-quality approximation with 64 segments.

    SELECT ST_NurbsToLineString('NURBSCURVE(2, (0 0, 5 10, 10 0))'::geometry, 64);

    LINESTRING(0 0,0.15625 0.3076171875,0.3125 0.60546875,0.46875 0.8935546875,0.625 1.171875,0.78125 1.4404296875,0.9375 1.69921875,1.09375 1.9482421875,1.25 2.1875,1.40625 2.4169921875,1.5625 2.63671875,1.71875 2.8466796875,1.875 3.046875,2.03125 3.2373046875,2.1875 3.41796875,2.34375 3.5888671875,2.5 3.75,2.65625 3.9013671875,2.8125 4.04296875,2.96875 4.1748046875,3.125 4.296875,3.28125 4.4091796875,3.4375 4.51171875,3.59375 4.6044921875,3.75 4.6875,3.90625 4.7607421875,4.0625 4.82421875,4.21875 4.8779296875,4.375 4.921875,4.53125 4.9560546875,4.6875 4.98046875,4.84375 4.9951171875,5 5,5.15625 4.9951171875,5.3125 4.98046875,5.46875 4.9560546875,5.625 4.921875,5.78125 4.8779296875,5.9375 4.82421875,6.09375 4.7607421875,6.25 4.6875,6.40625 4.6044921875,6.5625 4.51171875,6.71875 4.4091796875,6.875 4.296875,7.03125 4.1748046875,7.1875 4.04296875,7.34375 3.9013671875,7.5 3.75,7.65625 3.5888671875,7.8125 3.41796875,7.96875 3.2373046875,8.125 3.046875,8.28125 2.8466796875,8.4375 2.63671875,8.59375 2.4169921875,8.75 2.1875,8.90625 1.9482421875,9.0625 1.69921875,9.21875 1.4404296875,9.375 1.171875,9.53125 0.8935546875,9.6875 0.60546875,9.84375 0.3076171875,10 0)

This example creates a lower-quality, faster approximation with 16 segments.

    SELECT ST_NurbsToLineString('NURBSCURVE(2, (0 0, 5 10, 10 0))'::geometry, 16);

    LINESTRING(0 0,0.625 1.171875,1.25 2.1875,1.875 3.046875,2.5 3.75,3.125 4.296875,3.75 4.6875,4.375 4.921875,5 5,5.625 4.921875,6.25 4.6875,6.875 4.296875,7.5 3.75,8.125 3.046875,8.75 2.1875,9.375 1.171875,10 0)

### See Also

ST_MakeNurbsCurve, ST_Evaluate, ST_Segmentize