postgis/postgis
postgis/postgis
2
6
Fork 4
Code Issues Pull Requests Releases Activity
postgis/doc/reference_accessor.xml
Regina Obe 5cc346ae80 More SQL-MM cleanup
2022-07-13 22:05:45 -04:00

3128 lines
91 KiB
XML
Raw Permalink Blame History

<?xml version="1.0" encoding="UTF-8"?>
<sect1 id="Geometry_Accessors">
<title>Geometry Accessors</title>
<refentry id="GeometryType">
<refnamediv>
<refname>GeometryType</refname>
<refpurpose>Returns the type of a geometry as text.</refpurpose>
</refnamediv>
<refsynopsisdiv>
<funcsynopsis>
<funcprototype>
<funcdef>text <function>GeometryType</function></funcdef>
<paramdef><type>geometry </type> <parameter>geomA</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsection>
<title>Description</title>
<para>Returns the type of the geometry as a string. Eg:
'LINESTRING', 'POLYGON', 'MULTIPOINT', etc.</para>
<para>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.</para>
<note>
<para>This function also indicates if the geometry is measured,
by returning a string of the form 'POINTM'.</para>
</note>
<para>Enhanced: 2.0.0 support for Polyhedral surfaces, Triangles and TIN was introduced.</para>
<para>&sfs_compliant;</para>
<para>&curve_support;</para>
<para>&Z_support;</para>
<para>&P_support;</para>
<para>&T_support;</para>
</refsection>
<refsection>
<title>Examples</title>
<programlisting>SELECT GeometryType(ST_GeomFromText('LINESTRING(77.29 29.07,77.42 29.26,77.27 29.31,77.29 29.07)'));
geometrytype
--------------
LINESTRING
</programlisting>
<programlisting>SELECT ST_GeometryType(ST_GeomFromEWKT('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)) )'));
--result
POLYHEDRALSURFACE
</programlisting>
<programlisting>SELECT GeometryType(geom) as result
FROM
(SELECT
ST_GeomFromEWKT('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 geom
) AS g;
result
--------
TIN </programlisting>
</refsection>
<!-- Optionally add a "See Also" section -->
<refsection>
<title>See Also</title>
<para><xref linkend="ST_GeometryType" /></para>
</refsection>
</refentry>
<refentry id="ST_Boundary">
<refnamediv>
<refname>ST_Boundary</refname>
<refpurpose>Returns the boundary of a geometry.</refpurpose>
</refnamediv>
<refsynopsisdiv>
<funcsynopsis>
<funcprototype>
<funcdef>geometry <function>ST_Boundary</function></funcdef>
<paramdef><type>geometry </type> <parameter>geomA</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsection>
<title>Description</title>
<para>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.</para>
<para>Performed by the GEOS module</para>
<note> <para>Prior to 2.0.0, this function throws an exception if used with <varname>GEOMETRYCOLLECTION</varname>. From 2.0.0 up it will return NULL instead (unsupported input).</para></note>
<para>&sfs_compliant; OGC SPEC s2.1.1.1</para>
<para>&sqlmm_compliant; SQL-MM IEC 13249-3: 5.1.17</para>
<para>&Z_support;</para>
<para>Enhanced: 2.1.0 support for Triangle was introduced</para>
<para>Changed: 3.2.0 support for TIN, does not use geos, does not linearize curves</para>
</refsection>
<refsection>
<title>Examples</title>
<informaltable>
<tgroup cols="2">
<tbody>
<row>
<entry><para><informalfigure>
<mediaobject>
<imageobject>
<imagedata fileref="images/st_boundary01.png" />
</imageobject>
<caption><para>Linestring with boundary points overlaid</para></caption>
</mediaobject>
</informalfigure>
<programlisting>SELECT ST_Boundary(geom)
FROM (SELECT 'LINESTRING(100 150,50 60, 70 80, 160 170)'::geometry As geom) As f;
</programlisting>
<screen>-- ST_AsText output
MULTIPOINT((100 150),(160 170))
</screen>
</para></entry>
<entry><para><informalfigure>
<mediaobject>
<imageobject>
<imagedata fileref="images/st_boundary02.png" />
</imageobject>
<caption><para>polygon holes with boundary multilinestring</para></caption>
</mediaobject>
</informalfigure>
<programlisting>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;
</programlisting>
<screen>-- ST_AsText output
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))
</screen>
</para></entry>
</row>
</tbody>
</tgroup>
</informaltable>
<programlisting>SELECT ST_AsText(ST_Boundary(ST_GeomFromText('LINESTRING(1 1,0 0, -1 1)')));
st_astext
-----------
MULTIPOINT((1 1),(-1 1))
SELECT ST_AsText(ST_Boundary(ST_GeomFromText('POLYGON((1 1,0 0, -1 1, 1 1))')));
st_astext
----------
LINESTRING(1 1,0 0,-1 1,1 1)
--Using a 3d polygon
SELECT ST_AsEWKT(ST_Boundary(ST_GeomFromEWKT('POLYGON((1 1 1,0 0 1, -1 1 1, 1 1 1))')));
st_asewkt
-----------------------------------
LINESTRING(1 1 1,0 0 1,-1 1 1,1 1 1)
--Using a 3d multilinestring
SELECT ST_AsEWKT(ST_Boundary(ST_GeomFromEWKT('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) )')));
st_asewkt
----------
MULTIPOINT((-1 1 1),(1 1 0.75))
</programlisting>
</refsection>
<refsection>
<title>See Also</title>
<para><xref linkend="ST_AsText" />, <xref linkend="ST_ExteriorRing" />, <xref linkend="ST_MakePolygon" /></para>
</refsection>
</refentry>
<refentry id="ST_BoundingDiagonal">
<refnamediv>
<refname>ST_BoundingDiagonal</refname>
<refpurpose>Returns the diagonal of a geometry's bounding box.</refpurpose>
</refnamediv>
<refsynopsisdiv>
<funcsynopsis>
<funcprototype>
<funcdef>geometry <function>ST_BoundingDiagonal</function></funcdef>
<paramdef><type>geometry </type> <parameter>geom</parameter></paramdef>
<paramdef choice="opt"><type>boolean </type> <parameter>fits=false</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsection>
<title>Description</title>
<para>
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.
</para>
<para>
The optional <varname>fits</varname> 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.
</para>
<para>
The returned geometry retains the SRID and dimensionality
(Z and M presence) of the input geometry.
</para>
<note><para>
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.
</para></note>
<para>Availability: 2.2.0</para>
<para>&Z_support;</para>
<para>&M_support;</para>
</refsection>
<refsection>
<title>Examples</title>
<programlisting>
-- Get the minimum X in a buffer around a point
SELECT ST_X(ST_StartPoint(ST_BoundingDiagonal(
ST_Buffer(ST_Point(0,0),10)
)));
st_x
------
-10
</programlisting>
</refsection>
<refsection>
<title>See Also</title>
<para>
<xref linkend="ST_StartPoint" />,
<xref linkend="ST_EndPoint" />,
<xref linkend="ST_X" />,
<xref linkend="ST_Y" />,
<xref linkend="ST_Z" />,
<xref linkend="ST_M" />,
<xref linkend="ST_Envelope" />
</para>
</refsection>
</refentry>
<refentry id="ST_CoordDim">
<refnamediv>
<refname>ST_CoordDim</refname>
<refpurpose>Return the coordinate dimension of a geometry.</refpurpose>
</refnamediv>
<refsynopsisdiv>
<funcsynopsis>
<funcprototype>
<funcdef>integer <function>ST_CoordDim</function></funcdef>
<paramdef><type>geometry </type> <parameter>geomA</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsection>
<title>Description</title>
<para>Return the coordinate dimension of the ST_Geometry value.</para>
<para>This is the MM compliant alias name for <xref linkend="ST_NDims" /></para>
<para>&sfs_compliant;</para>
<para>&sqlmm_compliant; SQL-MM 3: 5.1.3</para>
<para>&curve_support;</para>
<para>&Z_support;</para>
<para>&P_support;</para>
<para>&T_support;</para>
</refsection>
<refsection>
<title>Examples</title>
<programlisting>SELECT ST_CoordDim('CIRCULARSTRING(1 2 3, 1 3 4, 5 6 7, 8 9 10, 11 12 13)');
---result--
3
SELECT ST_CoordDim(ST_Point(1,2));
--result--
2
</programlisting>
</refsection>
<!-- Optionally add a "See Also" section -->
<refsection>
<title>See Also</title>
<para><xref linkend="ST_NDims" /></para>
</refsection>
</refentry>
<refentry id="ST_Dimension">
<refnamediv>
<refname>ST_Dimension</refname>
<refpurpose>Returns the topological dimension of a geometry. </refpurpose>
</refnamediv>
<refsynopsisdiv>
<funcsynopsis>
<funcprototype>
<funcdef>integer <function>ST_Dimension</function></funcdef>
<paramdef><type>geometry </type> <parameter>g</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsection>
<title>Description</title>
<para>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 <varname>POINT</varname>, 1 for <varname>LINESTRING</varname>, 2 for <varname>POLYGON</varname>, and
the largest dimension of the components of a
<varname>GEOMETRYCOLLECTION</varname>.
If the dimension is unknown (e.g. for an empty <varname>GEOMETRYCOLLECTION</varname>) 0 is returned.
</para>
<para>&sqlmm_compliant; SQL-MM 3: 5.1.2</para>
<para>Enhanced: 2.0.0 support for Polyhedral surfaces and TINs was introduced. No longer throws an exception if given empty geometry.</para>
<note> <para>Prior to 2.0.0, this function throws an exception if used with empty geometry. </para></note>
<para>&P_support;</para>
<para>&T_support;</para>
</refsection>
<refsection>
<title>Examples</title>
<programlisting>SELECT ST_Dimension('GEOMETRYCOLLECTION(LINESTRING(1 1,0 0),POINT(0 0))');
ST_Dimension
-----------
1
</programlisting>
</refsection>
<refsection>
<title>See Also</title>
<para><xref linkend="ST_NDims" /></para>
</refsection>
</refentry>
<refentry id="ST_Dump">
<refnamediv>
<refname>ST_Dump</refname>
<refpurpose>Returns a set of <varname>geometry_dump</varname> rows for the components of a geometry.</refpurpose>
</refnamediv>
<refsynopsisdiv>
<funcsynopsis>
<funcprototype>
<funcdef>geometry_dump[] <function>ST_Dump</function></funcdef>
<paramdef><type>geometry </type> <parameter>g1</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsection>
<title>Description</title>
<para>A set-returning function (SRF) that extracts the components of a geometry.
It returns a set of
<xref linkend="geometry_dump" /> rows,
each containing a geometry (<parameter>geom</parameter> field)
and an array of integers (<parameter>path</parameter> field).
</para>
<para>For an atomic geometry type
(POINT,LINESTRING,POLYGON) a single record is returned with
an empty <parameter>path</parameter> array and the input geometry as <parameter>geom</parameter>.
For a collection or multi-geometry a record is returned for each
of the collection components, and the <parameter>path</parameter> denotes the
position of the component inside the collection.</para>
<para>ST_Dump is useful for expanding geometries. It is the
inverse of a <xref linkend="ST_Collect" /> / GROUP BY, in that it creates new rows.
For example it can be use to expand MULTIPOLYGONS into POLYGONS.</para>
<para>Enhanced: 2.0.0 support for Polyhedral surfaces, Triangles and TIN was introduced.</para>
<para>Availability: PostGIS 1.0.0RC1. Requires PostgreSQL 7.3 or higher.</para>
<note><para>Prior to 1.3.4, this function crashes if used with geometries that contain CURVES. This is fixed in 1.3.4+</para></note>
<para>&curve_support;</para>
<para>&P_support;</para>
<para>&T_support;</para>
<para>&Z_support;</para>
</refsection>
<refsection>
<title>Standard Examples</title>
<programlisting>SELECT sometable.field1, sometable.field1,
(ST_Dump(sometable.geom)).geom AS geom
FROM sometable;
-- Break a compound curve into its constituent linestrings and circularstrings
SELECT ST_AsEWKT(a.geom), ST_HasArc(a.geom)
FROM ( SELECT (ST_Dump(p_geom)).geom AS geom
FROM (SELECT ST_GeomFromEWKT('COMPOUNDCURVE(CIRCULARSTRING(0 0, 1 1, 1 0),(1 0, 0 1))') 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)</programlisting>
</refsection>
<refsection><title>Polyhedral Surfaces, TIN and Triangle Examples</title>
<programlisting>-- Polyhedral surface example
-- Break a Polyhedral surface into its faces
SELECT (a.p_geom).path[1] As path, ST_AsEWKT((a.p_geom).geom) As geom_ewkt
FROM (SELECT ST_Dump(ST_GeomFromEWKT('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))</programlisting>
<programlisting>-- TIN --
SELECT (g.gdump).path, ST_AsEWKT((g.gdump).geom) as wkt
FROM
(SELECT
ST_Dump( ST_GeomFromEWKT('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;
-- result --
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))
</programlisting>
</refsection>
<refsection>
<title>See Also</title>
<para><xref linkend="geometry_dump" />, <xref linkend="PostGIS_Geometry_DumpFunctions" />, <xref linkend="ST_Collect" />, <xref linkend="ST_GeometryN" /></para>
</refsection>
</refentry>
<refentry id="ST_DumpPoints">
<refnamediv>
<refname>ST_DumpPoints</refname>
<refpurpose>Returns a set of <varname>geometry_dump</varname> rows for the coordinates in a geometry.</refpurpose>
</refnamediv>
<refsynopsisdiv>
<funcsynopsis>
<funcprototype>
<funcdef>geometry_dump[] <function>ST_DumpPoints</function></funcdef>
<paramdef><type>geometry </type> <parameter>geom</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsection>
<title>Description</title>
<para>A set-returning function (SRF) that extracts the coordinates (vertices) of a geometry.
It returns a set of
<xref linkend="geometry_dump" /> rows,
each containing a geometry (<parameter>geom</parameter> field)
and an array of integers (<parameter>path</parameter> field).
</para>
<itemizedlist>
<listitem>
<para>the <parameter>geom</parameter> field
<varname>POINT</varname>s represent the coordinates of the supplied geometry.
</para>
</listitem>
<listitem>
<para>the <parameter>path</parameter> field (an <varname>integer[]</varname>)
is an index enumerating the coordinate positions in the elements of the supplied geometry.
The indices are 1-based.
For example, for a <varname>LINESTRING</varname> the paths are <varname>{i}</varname>
where <varname>i</varname> is the <varname>nth</varname>
coordinate in the <varname>LINESTRING</varname>.
For a <varname>POLYGON</varname> the paths are <varname>{i,j}</varname> where
<varname>i</varname> is the ring number (1 is outer; inner rings follow)
and <varname>j</varname> is the coordinate position in the ring.
</para>
</listitem>
</itemizedlist>
<para>
To obtain a single geometry containing the coordinates use <xref linkend="ST_Points" />.
</para>
<para>Enhanced: 2.1.0 Faster speed. Reimplemented as native-C.</para>
<para>Enhanced: 2.0.0 support for Polyhedral surfaces, Triangles and TIN was introduced.</para>
<para>Availability: 1.5.0</para>
<para>&curve_support;</para>
<para>&P_support;</para>
<para>&T_support;</para>
<para>&Z_support;</para>
</refsection>
<refsection><title>Classic Explode a Table of LineStrings into nodes</title>
<programlisting>SELECT edge_id, (dp).path[1] As index, ST_AsText((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)</programlisting>
</refsection>
<refsection>
<title>Standard Geometry Examples</title>
<informalfigure>
<mediaobject>
<imageobject>
<imagedata fileref="images/st_dumppoints01.png" />
</imageobject>
</mediaobject>
</informalfigure>
<programlisting>SELECT path, ST_AsText(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)</programlisting>
</refsection>
<refsection>
<title>Polyhedral Surfaces, TIN and Triangle Examples</title>
<programlisting>-- Polyhedral surface cube --
SELECT (g.gdump).path, ST_AsEWKT((g.gdump).geom) as wkt
FROM
(SELECT
ST_DumpPoints(ST_GeomFromEWKT('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;
-- result --
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)</programlisting>
<programlisting>-- Triangle --
SELECT (g.gdump).path, ST_AsText((g.gdump).geom) as wkt
FROM
(SELECT
ST_DumpPoints( ST_GeomFromEWKT('TRIANGLE ((
0 0,
0 9,
9 0,
0 0
))') ) AS gdump
) AS g;
-- result --
path | wkt
------+------------
{1} | POINT(0 0)
{2} | POINT(0 9)
{3} | POINT(9 0)
{4} | POINT(0 0)
</programlisting>
<programlisting>-- TIN --
SELECT (g.gdump).path, ST_AsEWKT((g.gdump).geom) as wkt
FROM
(SELECT
ST_DumpPoints( ST_GeomFromEWKT('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;
-- result --
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)
</programlisting>
</refsection>
<refsection>
<title>See Also</title>
<para><xref linkend="geometry_dump" />, <xref linkend="PostGIS_Geometry_DumpFunctions" />,
<xref linkend="ST_Dump" />, <xref linkend="ST_DumpRings" />, <xref linkend="ST_Points" /></para>
</refsection>
</refentry>
<refentry id="ST_DumpSegments">
<refnamediv>
<refname>ST_DumpSegments</refname>
<refpurpose>Returns a set of <varname>geometry_dump</varname> rows for the segments in a geometry.</refpurpose>
</refnamediv>
<refsynopsisdiv>
<funcsynopsis>
<funcprototype>
<funcdef>geometry_dump[] <function>ST_DumpSegments</function></funcdef>
<paramdef><type>geometry </type> <parameter>geom</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsection>
<title>Description</title>
<para>A set-returning function (SRF) that extracts the segments of a geometry.
It returns a set of
<xref linkend="geometry_dump" /> rows,
each containing a geometry (<parameter>geom</parameter> field)
and an array of integers (<parameter>path</parameter> field).
</para>
<itemizedlist>
<listitem>
<para>the <parameter>geom</parameter> field
<varname>LINESTRING</varname>s represent the segments of the supplied geometry.
</para>
</listitem>
<listitem>
<para>the <parameter>path</parameter> field (an <varname>integer[]</varname>)
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 <varname>LINESTRING</varname> the paths are <varname>{i}</varname>
where <varname>i</varname> is the <varname>nth</varname>
segment start point in the <varname>LINESTRING</varname>.
For a <varname>POLYGON</varname> the paths are <varname>{i,j}</varname> where
<varname>i</varname> is the ring number (1 is outer; inner rings follow)
and <varname>j</varname> is the segment start point position in the ring.
</para>
</listitem>
</itemizedlist>
<para>Availability: 3.2.0</para>
<para>&T_support;</para>
<para>&Z_support;</para>
</refsection>
<refsection>
<title>Standard Geometry Examples</title>
<programlisting>SELECT path, ST_AsText(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)</programlisting>
</refsection>
<refsection>
<title>TIN and Triangle Examples</title>
<programlisting>-- Triangle --
SELECT path, ST_AsText(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)
</programlisting>
<programlisting>-- TIN --
SELECT path, ST_AsEWKT(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)
</programlisting>
</refsection>
<refsection>
<title>See Also</title>
<para><xref linkend="geometry_dump" />, <xref linkend="PostGIS_Geometry_DumpFunctions" />,
<xref linkend="ST_Dump" />, <xref linkend="ST_DumpRings" /></para>
</refsection>
</refentry>
<refentry id="ST_DumpRings">
<refnamediv>
<refname>ST_DumpRings</refname>
<refpurpose>Returns a set of <varname>geometry_dump</varname> rows for
the exterior and interior rings of a Polygon.</refpurpose>
</refnamediv>
<refsynopsisdiv>
<funcsynopsis>
<funcprototype>
<funcdef>geometry_dump[] <function>ST_DumpRings</function></funcdef>
<paramdef><type>geometry </type> <parameter>a_polygon</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsection>
<title>Description</title>
<para>A set-returning function (SRF) that extracts the rings of a polygon.
It returns a set of <xref linkend="geometry_dump" /> rows,
each containing a geometry (<parameter>geom</parameter> field)
and an array of integers (<parameter>path</parameter> field).
</para>
<para>
The <parameter>geom</parameter> field contains each ring as a POLYGON.
The <parameter>path</parameter> 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.
</para>
<note><para>This only works for POLYGON geometries. It does not work for MULTIPOLYGONS</para></note>
<para>Availability: PostGIS 1.1.3. Requires PostgreSQL 7.3 or higher.</para>
<para>&Z_support;</para>
</refsection>
<refsection>
<title>Examples</title>
<para>General form of query.</para>
<programlisting>SELECT polyTable.field1, polyTable.field1,
(ST_DumpRings(polyTable.geom)).geom As geom
FROM polyTable;
</programlisting>
<para>A polygon with a single hole.</para>
<programlisting>SELECT path, ST_AsEWKT(geom) As geom
FROM ST_DumpRings(
ST_GeomFromEWKT('POLYGON((-8149064 5133092 1,-8149064 5132986 1,-8148996 5132839 1,-8148972 5132767 1,-8148958 5132508 1,-8148941 5132466 1,-8148924 5132394 1,
-8148903 5132210 1,-8148930 5131967 1,-8148992 5131978 1,-8149237 5132093 1,-8149404 5132211 1,-8149647 5132310 1,-8149757 5132394 1,
-8150305 5132788 1,-8149064 5133092 1),
(-8149362 5132394 1,-8149446 5132501 1,-8149548 5132597 1,-8149695 5132675 1,-8149362 5132394 1))')
) as foo;
path | geom
----------------------------------------------------------------------------------------------------------------
{0} | POLYGON((-8149064 5133092 1,-8149064 5132986 1,-8148996 5132839 1,-8148972 5132767 1,-8148958 5132508 1,
| -8148941 5132466 1,-8148924 5132394 1,
| -8148903 5132210 1,-8148930 5131967 1,
| -8148992 5131978 1,-8149237 5132093 1,
| -8149404 5132211 1,-8149647 5132310 1,-8149757 5132394 1,-8150305 5132788 1,-8149064 5133092 1))
{1} | POLYGON((-8149362 5132394 1,-8149446 5132501 1,
| -8149548 5132597 1,-8149695 5132675 1,-8149362 5132394 1))</programlisting>
</refsection>
<!-- Optionally add a "See Also" section -->
<refsection>
<title>See Also</title>
<para><xref linkend="geometry_dump" />, <xref linkend="PostGIS_Geometry_DumpFunctions" />, <xref linkend="ST_Dump" />, <xref linkend="ST_ExteriorRing" />, <xref linkend="ST_InteriorRingN" /></para>
</refsection>
</refentry>
<refentry id="ST_EndPoint">
<refnamediv>
<refname>ST_EndPoint</refname>
<refpurpose>Returns the last point of a LineString or CircularLineString.</refpurpose>
</refnamediv>
<refsynopsisdiv>
<funcsynopsis>
<funcprototype>
<funcdef>geometry <function>ST_EndPoint</function></funcdef>
<paramdef><type>geometry </type> <parameter>g</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsection>
<title>Description</title>
<para>Returns the last point of a <varname>LINESTRING</varname>
or <varname>CIRCULARLINESTRING</varname> geometry
as a <varname>POINT</varname>.
Returns <varname>NULL</varname> if the input
is not a <varname>LINESTRING</varname> or <varname>CIRCULARLINESTRING</varname>.</para>
<para>&sqlmm_compliant; SQL-MM 3: 7.1.4</para>
<para>&Z_support;</para>
<para>&curve_support;</para>
<note><para>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.</para></note>
</refsection>
<refsection>
<title>Examples</title>
<para>End point of a LineString</para>
<programlisting>postgis=# SELECT ST_AsText(ST_EndPoint('LINESTRING(1 1, 2 2, 3 3)'::geometry));
st_astext
------------
POINT(3 3)
</programlisting>
<para>End point of a non-LineString is NULL</para>
<programlisting>
SELECT ST_EndPoint('POINT(1 1)'::geometry) IS NULL AS is_null;
is_null
----------
t
</programlisting>
<para>End point of a 3D LineString</para>
<programlisting>
--3d endpoint
SELECT ST_AsEWKT(ST_EndPoint('LINESTRING(1 1 2, 1 2 3, 0 0 5)'));
st_asewkt
--------------
POINT(0 0 5)
</programlisting>
<para>End point of a CircularString</para>
<programlisting>
SELECT ST_AsText(ST_EndPoint('CIRCULARSTRING(5 2,-3 1.999999, -2 1, -4 2, 6 3)'::geometry));
st_astext
------------
POINT(6 3)
</programlisting>
</refsection>
<refsection>
<title>See Also</title>
<para><xref linkend="ST_PointN" />, <xref
linkend="ST_StartPoint" /></para>
</refsection>
</refentry>
<refentry id="ST_Envelope">
<refnamediv>
<refname>ST_Envelope</refname>
<refpurpose>Returns a geometry representing the bounding box of a geometry.</refpurpose>
</refnamediv>
<refsynopsisdiv>
<funcsynopsis>
<funcprototype>
<funcdef>geometry <function>ST_Envelope</function></funcdef>
<paramdef><type>geometry </type> <parameter>g1</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsection>
<title>Description</title>
<para>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
((<varname>MINX</varname>, <varname>MINY</varname>),
(<varname>MINX</varname>, <varname>MAXY</varname>),
(<varname>MAXX</varname>, <varname>MAXY</varname>),
(<varname>MAXX</varname>, <varname>MINY</varname>),
(<varname>MINX</varname>, <varname>MINY</varname>)). (PostGIS will add a
<varname>ZMIN</varname>/<varname>ZMAX</varname> coordinate as
well).</para>
<para>Degenerate cases (vertical lines, points) will return a geometry of
lower dimension than <varname>POLYGON</varname>, ie.
<varname>POINT</varname> or <varname>LINESTRING</varname>.</para>
<para>Availability: 1.5.0 behavior changed to output double precision instead of float4</para>
<para>&sfs_compliant; s2.1.1.1</para>
<para>&sqlmm_compliant; SQL-MM 3: 5.1.19</para>
</refsection>
<refsection>
<title>Examples</title>
<programlisting>
SELECT ST_AsText(ST_Envelope('POINT(1 3)'::geometry));
st_astext
------------
POINT(1 3)
(1 row)
SELECT ST_AsText(ST_Envelope('LINESTRING(0 0, 1 3)'::geometry));
st_astext
--------------------------------
POLYGON((0 0,0 3,1 3,1 0,0 0))
(1 row)
SELECT ST_AsText(ST_Envelope('POLYGON((0 0, 0 1, 1.0000001 1, 1.0000001 0, 0 0))'::geometry));
st_astext
--------------------------------------------------------------
POLYGON((0 0,0 1,1.00000011920929 1,1.00000011920929 0,0 0))
(1 row)
SELECT ST_AsText(ST_Envelope('POLYGON((0 0, 0 1, 1.0000000001 1, 1.0000000001 0, 0 0))'::geometry));
st_astext
--------------------------------------------------------------
POLYGON((0 0,0 1,1.00000011920929 1,1.00000011920929 0,0 0))
(1 row)
SELECT Box3D(geom), Box2D(geom), ST_AsText(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;
<!-- TODO: Fix examples to reflect new behavior -->
</programlisting>
<informalfigure>
<mediaobject>
<imageobject>
<imagedata fileref="images/st_envelope01.png" />
</imageobject>
<caption><para>Envelope of a point and linestring.</para></caption>
</mediaobject>
</informalfigure>
<programlisting>
SELECT ST_AsText(ST_Envelope(
ST_Collect(
ST_GeomFromText('LINESTRING(55 75,125 150)'),
ST_Point(20, 80))
)) As wktenv;
wktenv
-----------
POLYGON((20 75,20 150,125 150,125 75,20 75))</programlisting>
</refsection>
<refsection>
<title>See Also</title>
<para><xref linkend="Box2D" />, <xref linkend="Box3D" />, <xref linkend="ST_OrientedEnvelope" /></para>
</refsection>
</refentry>
<refentry id="ST_ExteriorRing">
<refnamediv>
<refname>ST_ExteriorRing</refname>
<refpurpose>Returns a LineString representing the exterior ring of a Polygon. </refpurpose>
</refnamediv>
<refsynopsisdiv>
<funcsynopsis>
<funcprototype>
<funcdef>geometry <function>ST_ExteriorRing</function></funcdef>
<paramdef><type>geometry </type> <parameter>a_polygon</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsection>
<title>Description</title>
<para>Returns a LINESTRING representing the exterior ring (shell) of a POLYGON.
Returns NULL if the geometry is not a polygon.</para>
<note>
<para>This function does not support MULTIPOLYGONs.
For MULTIPOLYGONs use in conjunction with <xref linkend="ST_GeometryN" /> or <xref linkend="ST_Dump" /> </para>
</note>
<para>&sfs_compliant; 2.1.5.1</para>
<para>&sqlmm_compliant; SQL-MM 3: 8.2.3, 8.3.3</para>
<para>&Z_support;</para>
</refsection>
<refsection>
<title>Examples</title>
<programlisting>
--If you have a table of polygons
SELECT gid, ST_ExteriorRing(geom) AS ering
FROM sometable;
--If you have a table of MULTIPOLYGONs
--and want to return a MULTILINESTRING composed of the exterior rings of each polygon
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;
--3d Example
SELECT ST_AsEWKT(
ST_ExteriorRing(
ST_GeomFromEWKT('POLYGON((0 0 1, 1 1 1, 1 2 1, 1 1 1, 0 0 1))')
)
);
st_asewkt
---------
LINESTRING(0 0 1,1 1 1,1 2 1,1 1 1,0 0 1)
</programlisting>
</refsection>
<refsection>
<title>See Also</title>
<para>
<xref linkend="ST_InteriorRingN" />,
<xref linkend="ST_Boundary" />,
<xref linkend="ST_NumInteriorRings" />
</para>
</refsection>
</refentry>
<refentry id="ST_GeometryN">
<refnamediv>
<refname>ST_GeometryN</refname>
<refpurpose>Return an element of a geometry collection.</refpurpose>
</refnamediv>
<refsynopsisdiv>
<funcsynopsis>
<funcprototype>
<funcdef>geometry <function>ST_GeometryN</function></funcdef>
<paramdef><type>geometry </type> <parameter>geomA</parameter></paramdef>
<paramdef><type>integer </type> <parameter>n</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsection>
<title>Description</title>
<para>Return the 1-based Nth element geometry of an input geometry which is a
GEOMETRYCOLLECTION, MULTIPOINT, MULTILINESTRING, MULTICURVE, MULTI)POLYGON, or POLYHEDRALSURFACE.
Otherwise, returns NULL.</para>
<note>
<para>Index is 1-based as for OGC specs since version 0.8.0.
Previous versions implemented this as 0-based instead.</para>
</note>
<note>
<para>To extract all elements of a geometry, <xref linkend="ST_Dump" /> is more efficient and works for atomic geometries.</para>
</note>
<para>Enhanced: 2.0.0 support for Polyhedral surfaces, Triangles and TIN was introduced.</para>
<para>Changed: 2.0.0 Prior versions would return NULL for singular geometries. This was changed to return the geometry for ST_GeometryN(..,1) case.</para>
<para>&sfs_compliant;</para>
<para>&sqlmm_compliant; SQL-MM 3: 9.1.5</para>
<para>&Z_support;</para>
<para>&curve_support;</para>
<para>&P_support;</para>
<para>&T_support;</para>
</refsection>
<refsection>
<title>Standard Examples</title>
<programlisting>--Extracting a subset of points from a 3d multipoint
SELECT n, ST_AsEWKT(ST_GeometryN(geom, n)) As geomewkt
FROM (
VALUES (ST_GeomFromEWKT('MULTIPOINT((1 2 7), (3 4 7), (5 6 7), (8 9 10))') ),
( ST_GeomFromEWKT('MULTICURVE(CIRCULARSTRING(2.5 2.5,4.5 2.5, 3.5 3.5), (10 11, 12 11))') )
)As foo(geom)
CROSS JOIN generate_series(1,100) n
WHERE n &lt;= ST_NumGeometries(geom);
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 &lt;= ST_NumGeometries(geom);</programlisting>
</refsection>
<refsection><title>Polyhedral Surfaces, TIN and Triangle Examples</title>
<programlisting>-- Polyhedral surface example
-- Break a Polyhedral surface into its faces
SELECT ST_AsEWKT(ST_GeometryN(p_geom,3)) As geom_ewkt
FROM (SELECT ST_GeomFromEWKT('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;
geom_ewkt
------------------------------------------
POLYGON((0 0 0,1 0 0,1 0 1,0 0 1,0 0 0))</programlisting>
<programlisting>-- TIN --
SELECT ST_AsEWKT(ST_GeometryN(geom,2)) as wkt
FROM
(SELECT
ST_GeomFromEWKT('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 geom
) AS g;
-- result --
wkt
-------------------------------------
TRIANGLE((0 0 0,0 1 0,1 1 0,0 0 0))</programlisting>
</refsection>
<!-- Optionally add a "See Also" section -->
<refsection>
<title>See Also</title>
<para><xref linkend="ST_Dump" />, <xref linkend="ST_NumGeometries" /></para>
</refsection>
</refentry>
<refentry id="ST_GeometryType">
<refnamediv>
<refname>ST_GeometryType</refname>
<refpurpose>Returns the SQL-MM type of a geometry as text.</refpurpose>
</refnamediv>
<refsynopsisdiv>
<funcsynopsis>
<funcprototype>
<funcdef>text <function>ST_GeometryType</function></funcdef>
<paramdef><type>geometry </type> <parameter>g1</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsection>
<title>Description</title>
<para>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.</para>
<para>Enhanced: 2.0.0 support for Polyhedral surfaces was introduced.</para>
<para>&sqlmm_compliant; SQL-MM 3: 5.1.4</para>
<para>&Z_support;</para>
<para>&P_support;</para>
</refsection>
<refsection>
<title>Examples</title>
<programlisting>SELECT ST_GeometryType(ST_GeomFromText('LINESTRING(77.29 29.07,77.42 29.26,77.27 29.31,77.29 29.07)'));
--result
ST_LineString</programlisting>
<programlisting>SELECT ST_GeometryType(ST_GeomFromEWKT('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)) )'));
--result
ST_PolyhedralSurface</programlisting>
<programlisting>SELECT ST_GeometryType(ST_GeomFromEWKT('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)) )'));
--result
ST_PolyhedralSurface</programlisting>
<programlisting>SELECT ST_GeometryType(geom) as result
FROM
(SELECT
ST_GeomFromEWKT('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 geom
) AS g;
result
--------
ST_Tin </programlisting>
</refsection>
<refsection>
<title>See Also</title>
<para><xref linkend="GeometryType" /></para>
</refsection>
</refentry>
<refentry id="ST_HasArc">
<refnamediv>
<refname>ST_HasArc</refname>
<refpurpose>Tests if a geometry contains a circular arc</refpurpose>
</refnamediv>
<refsynopsisdiv>
<funcsynopsis>
<funcprototype>
<funcdef>boolean <function>ST_HasArc</function></funcdef>
<paramdef><type>geometry </type> <parameter>geomA</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsection>
<title>Description</title>
<para>Returns true if a geometry or geometry collection contains a circular string</para>
<para>Availability: 1.2.3?</para>
<para>&Z_support;</para>
<para>&curve_support;</para>
</refsection>
<refsection>
<title>Examples</title>
<programlisting>SELECT ST_HasArc(ST_Collect('LINESTRING(1 2, 3 4, 5 6)', 'CIRCULARSTRING(1 1, 2 3, 4 5, 6 7, 5 6)'));
st_hasarc
--------
t
</programlisting>
</refsection>
<!-- Optionally add a "See Also" section -->
<refsection>
<title>See Also</title>
<para><xref linkend="ST_CurveToLine" />, <xref linkend="ST_LineToCurve" /></para>
</refsection>
</refentry>
<refentry id="ST_InteriorRingN">
<refnamediv>
<refname>ST_InteriorRingN</refname>
<refpurpose>Returns the Nth interior ring (hole) of a Polygon.</refpurpose>
</refnamediv>
<refsynopsisdiv>
<funcsynopsis>
<funcprototype>
<funcdef>geometry <function>ST_InteriorRingN</function></funcdef>
<paramdef><type>geometry </type> <parameter>a_polygon</parameter></paramdef>
<paramdef><type>integer </type> <parameter>n</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsection>
<title>Description</title>
<para>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. </para>
<!-- optionally mention that this function uses indexes if appropriate -->
<note>
<para>This function does not support MULTIPOLYGONs.
For MULTIPOLYGONs use in conjunction with <xref linkend="ST_GeometryN" /> or <xref linkend="ST_Dump" /> </para>
</note>
<para>&sfs_compliant;</para>
<para>&sqlmm_compliant; SQL-MM 3: 8.2.6, 8.3.5</para>
<para>&Z_support;</para>
</refsection>
<refsection>
<title>Examples</title>
<programlisting>
SELECT ST_AsText(ST_InteriorRingN(geom, 1)) As geom
FROM (SELECT ST_BuildArea(
ST_Collect(ST_Buffer(ST_Point(1,2), 20,3),
ST_Buffer(ST_Point(1, 2), 10,3))) As geom
) as foo;
</programlisting>
</refsection>
<!-- Optionally add a "See Also" section -->
<refsection>
<title>See Also</title>
<para>
<xref linkend="ST_ExteriorRing" />,
<xref linkend="ST_BuildArea" />,
<xref linkend="ST_Collect" />,
<xref linkend="ST_Dump" />,
<xref linkend="ST_NumInteriorRing" />,
<xref linkend="ST_NumInteriorRings" />
</para>
</refsection>
</refentry>
<refentry id="ST_IsClosed">
<refnamediv>
<refname>ST_IsClosed</refname>
<refpurpose>Tests if a LineStrings's start and end points are coincident. For a PolyhedralSurface tests if it is closed (volumetric).
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<funcsynopsis>
<funcprototype>
<funcdef>boolean <function>ST_IsClosed</function></funcdef>
<paramdef><type>geometry </type> <parameter>g</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsection>
<title>Description</title>
<para>Returns <varname>TRUE</varname> if the <varname>LINESTRING</varname>'s
start and end points are coincident.
For Polyhedral Surfaces, reports if the surface is areal (open) or volumetric (closed).</para>
<para>&sfs_compliant;</para>
<para>&sqlmm_compliant; SQL-MM 3: 7.1.5, 9.3.3</para>
<note>
<para>SQL-MM defines the result of
<function>ST_IsClosed(<varname>NULL</varname>)</function> to be 0, while
PostGIS returns <varname>NULL</varname>.</para>
</note>
<para>&Z_support;</para>
<para>&curve_support;</para>
<para>Enhanced: 2.0.0 support for Polyhedral surfaces was introduced.</para>
<para>&P_support;</para>
</refsection>
<refsection>
<title>Line String and Point Examples</title>
<programlisting>postgis=# SELECT ST_IsClosed('LINESTRING(0 0, 1 1)'::geometry);
st_isclosed
-------------
f
(1 row)
postgis=# SELECT ST_IsClosed('LINESTRING(0 0, 0 1, 1 1, 0 0)'::geometry);
st_isclosed
-------------
t
(1 row)
postgis=# SELECT ST_IsClosed('MULTILINESTRING((0 0, 0 1, 1 1, 0 0),(0 0, 1 1))'::geometry);
st_isclosed
-------------
f
(1 row)
postgis=# SELECT ST_IsClosed('POINT(0 0)'::geometry);
st_isclosed
-------------
t
(1 row)
postgis=# SELECT ST_IsClosed('MULTIPOINT((0 0), (1 1))'::geometry);
st_isclosed
-------------
t
(1 row)</programlisting>
</refsection>
<refsection>
<title>Polyhedral Surface Examples</title>
<programlisting>
-- A cube --
SELECT ST_IsClosed(ST_GeomFromEWKT('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_isclosed
-------------
t
-- Same as cube but missing a side --
SELECT ST_IsClosed(ST_GeomFromEWKT('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)) )'));
st_isclosed
-------------
f
</programlisting>
</refsection>
<refsection>
<title>See Also</title>
<para><xref linkend="ST_IsRing" /></para>
</refsection>
</refentry>
<refentry id="ST_IsCollection">
<refnamediv>
<refname>ST_IsCollection</refname>
<refpurpose>Tests if a geometry is a geometry collection type.</refpurpose>
</refnamediv>
<refsynopsisdiv>
<funcsynopsis>
<funcprototype>
<funcdef>boolean <function>ST_IsCollection</function></funcdef>
<paramdef><type>geometry </type> <parameter>g</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsection>
<title>Description</title>
<para>Returns <varname>TRUE</varname> if the geometry type of
the argument a geometry collection type. Collection types are the following:
<itemizedlist>
<listitem><para>GEOMETRYCOLLECTION</para></listitem>
<listitem><para>MULTI{POINT,POLYGON,LINESTRING,CURVE,SURFACE}</para></listitem>
<listitem><para>COMPOUNDCURVE</para></listitem>
</itemizedlist>
</para>
<note>
<para>
This function analyzes the type of the geometry. This means
that it will return <varname>TRUE</varname> on collections
that are empty or that contain a single element.
</para>
</note>
<para>&Z_support;</para>
<para>&curve_support;</para>
</refsection>
<refsection>
<title>Examples</title>
<programlisting>postgis=# SELECT ST_IsCollection('LINESTRING(0 0, 1 1)'::geometry);
st_iscollection
-------------
f
(1 row)
postgis=# SELECT ST_IsCollection('MULTIPOINT EMPTY'::geometry);
st_iscollection
-------------
t
(1 row)
postgis=# SELECT ST_IsCollection('MULTIPOINT((0 0))'::geometry);
st_iscollection
-------------
t
(1 row)
postgis=# SELECT ST_IsCollection('MULTIPOINT((0 0), (42 42))'::geometry);
st_iscollection
-------------
t
(1 row)
postgis=# SELECT ST_IsCollection('GEOMETRYCOLLECTION(POINT(0 0))'::geometry);
st_iscollection
-------------
t
(1 row)</programlisting>
</refsection>
<refsection>
<title>See Also</title>
<para><xref linkend="ST_NumGeometries" /></para>
</refsection>
</refentry>
<refentry id="ST_IsEmpty">
<refnamediv>
<refname>ST_IsEmpty</refname>
<refpurpose>Tests if a geometry is empty.</refpurpose>
</refnamediv>
<refsynopsisdiv>
<funcsynopsis>
<funcprototype>
<funcdef>boolean <function>ST_IsEmpty</function></funcdef>
<paramdef><type>geometry </type> <parameter>geomA</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsection>
<title>Description</title>
<para>Returns true if this Geometry is an empty geometry. If
true, then this Geometry represents an empty geometry collection, polygon, point etc.</para>
<note>
<para>SQL-MM defines the result of ST_IsEmpty(NULL) to be 0, while
PostGIS returns NULL.</para>
</note>
<para>&sfs_compliant; s2.1.1.1</para>
<para>&sqlmm_compliant; SQL-MM 3: 5.1.7</para>
<para>&curve_support;</para>
<warning><para>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</para></warning>
</refsection>
<refsection>
<title>Examples</title>
<programlisting>
SELECT ST_IsEmpty(ST_GeomFromText('GEOMETRYCOLLECTION EMPTY'));
st_isempty
------------
t
(1 row)
SELECT ST_IsEmpty(ST_GeomFromText('POLYGON EMPTY'));
st_isempty
------------
t
(1 row)
SELECT ST_IsEmpty(ST_GeomFromText('POLYGON((1 2, 3 4, 5 6, 1 2))'));
st_isempty
------------
f
(1 row)
SELECT ST_IsEmpty(ST_GeomFromText('POLYGON((1 2, 3 4, 5 6, 1 2))')) = false;
?column?
----------
t
(1 row)
SELECT ST_IsEmpty(ST_GeomFromText('CIRCULARSTRING EMPTY'));
st_isempty
------------
t
(1 row)
</programlisting>
</refsection>
</refentry>
<refentry id="ST_IsPolygonCCW">
<refnamediv>
<refname>
ST_IsPolygonCCW
</refname>
<refpurpose>Tests if Polygons have exterior rings oriented counter-clockwise and interior rings oriented clockwise.
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<funcsynopsis>
<funcprototype>
<funcdef>
boolean
<function>ST_IsPolygonCCW</function>
</funcdef>
<paramdef>
<type>geometry</type>
<parameter>geom</parameter>
</paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsection>
<title>Description</title>
<para>
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.
</para>
<para>
Returns true if the geometry has no polygonal components.
</para>
<note>
<para>
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.
</para>
</note>
<note>
<para>
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.
</para>
</note>
<para>Availability: 2.4.0</para>
<para>&Z_support;</para>
<para>&M_support;</para>
</refsection>
<refsection>
<title>See Also</title>
<para>
<xref linkend="ST_ForcePolygonCW" />,
<xref linkend="ST_ForcePolygonCCW" />,
<xref linkend="ST_IsPolygonCW" />
</para>
</refsection>
</refentry>
<refentry id="ST_IsPolygonCW">
<refnamediv>
<refname>
ST_IsPolygonCW
</refname>
<refpurpose>Tests if Polygons have exterior rings oriented clockwise and interior rings oriented counter-clockwise.
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<funcsynopsis>
<funcprototype>
<funcdef>
boolean
<function>ST_IsPolygonCW</function>
</funcdef>
<paramdef>
<type>geometry</type>
<parameter>geom</parameter>
</paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsection>
<title>Description</title>
<para>
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.
</para>
<para>
Returns true if the geometry has no polygonal components.
</para>
<note>
<para>
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.
</para>
</note>
<note>
<para>
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.
</para>
</note>
<para>Availability: 2.4.0</para>
<para>&Z_support;</para>
<para>&M_support;</para>
</refsection>
<refsection>
<title>See Also</title>
<para>
<xref linkend="ST_ForcePolygonCW" />,
<xref linkend="ST_ForcePolygonCCW" />,
<xref linkend="ST_IsPolygonCW" />
</para>
</refsection>
</refentry>
<refentry id="ST_IsRing">
<refnamediv>
<refname>ST_IsRing</refname>
<refpurpose>Tests if a LineString is closed and simple.</refpurpose>
</refnamediv>
<refsynopsisdiv>
<funcsynopsis>
<funcprototype>
<funcdef>boolean <function>ST_IsRing</function></funcdef>
<paramdef><type>geometry </type> <parameter>g</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsection>
<title>Description</title>
<para>Returns <varname>TRUE</varname> if this
<varname>LINESTRING</varname> is both <xref linkend="ST_IsClosed" />
(<function>ST_StartPoint(<parameter>g</parameter>)</function>
<function>~=</function>
<function>ST_Endpoint(<parameter>g</parameter>)</function>) and <xref
linkend="ST_IsSimple" /> (does not self intersect).</para>
<para>&sfs_compliant; 2.1.5.1</para>
<para>&sqlmm_compliant; SQL-MM 3: 7.1.6</para>
<note>
<para>SQL-MM defines the result of
<function>ST_IsRing(<varname>NULL</varname>)</function> to be 0, while
PostGIS returns <varname>NULL</varname>.</para>
</note>
</refsection>
<refsection>
<title>Examples</title>
<programlisting>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)</programlisting>
</refsection>
<refsection>
<title>See Also</title>
<para><xref linkend="ST_IsClosed" />, <xref linkend="ST_IsSimple" />, <xref linkend="ST_StartPoint" />,
<xref linkend="ST_EndPoint" /></para>
</refsection>
</refentry>
<refentry id="ST_IsSimple">
<refnamediv>
<refname>ST_IsSimple</refname>
<refpurpose>Tests if a geometry has no points of self-intersection or self-tangency.</refpurpose>
</refnamediv>
<refsynopsisdiv>
<funcsynopsis>
<funcprototype>
<funcdef>boolean <function>ST_IsSimple</function></funcdef>
<paramdef><type>geometry </type> <parameter>geomA</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsection>
<title>Description</title>
<para>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 <link linkend="OGC_Validity">"Ensuring OpenGIS compliancy of geometries"</link></para>
<note>
<para>SQL-MM defines the result of ST_IsSimple(NULL) to be 0,
while PostGIS returns NULL.</para>
</note>
<para>&sfs_compliant; s2.1.1.1</para>
<para>&sqlmm_compliant; SQL-MM 3: 5.1.8</para>
<para>&Z_support;</para>
</refsection>
<refsection>
<title>Examples</title>
<programlisting> SELECT ST_IsSimple(ST_GeomFromText('POLYGON((1 2, 3 4, 5 6, 1 2))'));
st_issimple
-------------
t
(1 row)
SELECT ST_IsSimple(ST_GeomFromText('LINESTRING(1 1,2 2,2 3.5,1 3,1 2,2 1)'));
st_issimple
-------------
f
(1 row)</programlisting>
</refsection>
<refsection>
<title>See Also</title>
<para><xref linkend="ST_IsValid" /></para>
</refsection>
</refentry>
<refentry id="ST_M">
<refnamediv>
<refname>ST_M</refname>
<refpurpose>Returns the M coordinate of a Point.</refpurpose>
</refnamediv>
<refsynopsisdiv>
<funcsynopsis>
<funcprototype>
<funcdef>float <function>ST_M</function></funcdef>
<paramdef><type>geometry </type> <parameter>a_point</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsection>
<title>Description</title>
<para>Return the M coordinate of a Point, or NULL if not
available. Input must be a Point.</para>
<note>
<para>This is not (yet) part of the OGC spec, but is listed here
to complete the point coordinate extractor function list.</para>
</note>
<para>&sfs_compliant;</para>
<para>&sqlmm_compliant;</para>
<para>&Z_support;</para>
</refsection>
<refsection>
<title>Examples</title>
<programlisting>SELECT ST_M(ST_GeomFromEWKT('POINT(1 2 3 4)'));
st_m
------
4
(1 row)
</programlisting>
</refsection>
<!-- Optionally add a "See Also" section -->
<refsection>
<title>See Also</title>
<para><xref linkend="ST_GeomFromEWKT" />, <xref linkend="ST_X" />, <xref linkend="ST_Y" />, <xref linkend="ST_Z" /></para>
</refsection>
</refentry>
<refentry id="ST_MemSize">
<refnamediv>
<refname>ST_MemSize</refname>
<refpurpose>Returns the amount of memory space a geometry takes.</refpurpose>
</refnamediv>
<refsynopsisdiv>
<funcsynopsis>
<funcprototype>
<funcdef>integer <function>ST_MemSize</function></funcdef>
<paramdef><type>geometry </type> <parameter>geomA</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsection>
<title>Description</title>
<para>Returns the amount of memory space (in bytes) the geometry takes. </para>
<para>This complements the PostgreSQL built-in <ulink url="https://www.postgresql.org/docs/current/functions-admin.html#FUNCTIONS-ADMIN-DBOBJECT">database object functions</ulink>
pg_column_size, pg_size_pretty, pg_relation_size, pg_total_relation_size.</para>
<note><para>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.</para>
<para>pg_total_relation_size - includes, the table, the toasted tables, and the indexes.</para>
<para>pg_column_size returns how much space a geometry would take in a column considering compression, so may be lower than ST_MemSize</para>
</note>
<para>&Z_support;</para>
<para>&curve_support;</para>
<para>&P_support;</para>
<para>&T_support;</para>
<para>Changed: 2.2.0 name changed to ST_MemSize to follow naming convention.</para>
</refsection>
<refsection>
<title>Examples</title>
<programlisting>
--Return how much byte space Boston takes up in our Mass data set
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)*1.00 /
SUM(ST_MemSize(geom))*100 As numeric(10,2)) As perbos
FROM towns;
totgeomsum bossum perbos
---------- ------ ------
1522 kB 30 kB 1.99
SELECT ST_MemSize(ST_GeomFromText('CIRCULARSTRING(220268 150415,220227 150505,220227 150406)'));
---
73
--What percentage of our table is taken up by just the geometry
SELECT pg_total_relation_size('public.neighborhoods') As fulltable_size, sum(ST_MemSize(geom)) As geomsize,
sum(ST_MemSize(geom))*1.00/pg_total_relation_size('public.neighborhoods')*100 As pergeom
FROM neighborhoods;
fulltable_size geomsize pergeom
------------------------------------------------
262144 96238 36.71188354492187500000
</programlisting>
</refsection>
</refentry>
<refentry id="ST_NDims">
<refnamediv>
<refname>ST_NDims</refname>
<refpurpose>Returns the coordinate dimension of a geometry.</refpurpose>
</refnamediv>
<refsynopsisdiv>
<funcsynopsis>
<funcprototype>
<funcdef>integer <function>ST_NDims</function></funcdef>
<paramdef><type>geometry </type> <parameter>g1</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsection>
<title>Description</title>
<para>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</para>
<para>&Z_support;</para>
</refsection>
<refsection>
<title>Examples</title>
<programlisting>SELECT ST_NDims(ST_GeomFromText('POINT(1 1)')) As d2point,
ST_NDims(ST_GeomFromEWKT('POINT(1 1 2)')) As d3point,
ST_NDims(ST_GeomFromEWKT('POINTM(1 1 0.5)')) As d2pointm;
d2point | d3point | d2pointm
---------+---------+----------
2 | 3 | 3
</programlisting>
</refsection>
<refsection>
<title>See Also</title>
<para><xref linkend="ST_CoordDim" />, <xref linkend="ST_Dimension" />, <xref linkend="ST_GeomFromEWKT" /></para>
</refsection>
</refentry>
<refentry id="ST_NPoints">
<refnamediv>
<refname>ST_NPoints</refname>
<refpurpose>Returns the number of points (vertices) in a geometry.</refpurpose>
</refnamediv>
<refsynopsisdiv>
<funcsynopsis>
<funcprototype>
<funcdef>integer <function>ST_NPoints</function></funcdef>
<paramdef><type>geometry </type> <parameter>g1</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsection>
<title>Description</title>
<para>Return the number of points in a geometry. Works for all geometries.</para>
<para>Enhanced: 2.0.0 support for Polyhedral surfaces was introduced.</para>
<note><para>Prior to 1.3.4, this function crashes if used with geometries that contain CURVES. This is fixed in 1.3.4+</para></note>
<para>&Z_support;</para>
<para>&curve_support;</para>
<para>&P_support;</para>
</refsection>
<refsection>
<title>Examples</title>
<programlisting>SELECT ST_NPoints(ST_GeomFromText('LINESTRING(77.29 29.07,77.42 29.26,77.27 29.31,77.29 29.07)'));
--result
4
--Polygon in 3D space
SELECT ST_NPoints(ST_GeomFromEWKT('LINESTRING(77.29 29.07 1,77.42 29.26 0,77.27 29.31 -1,77.29 29.07 3)'))
--result
4</programlisting>
</refsection>
<refsection>
<title>See Also</title>
<para><xref linkend="ST_NumPoints" /></para>
</refsection>
</refentry>
<refentry id="ST_NRings">
<refnamediv>
<refname>ST_NRings</refname>
<refpurpose>Returns the number of rings in a polygonal geometry.</refpurpose>
</refnamediv>
<refsynopsisdiv>
<funcsynopsis>
<funcprototype>
<funcdef>integer <function>ST_NRings</function></funcdef>
<paramdef><type>geometry </type> <parameter>geomA</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsection>
<title>Description</title>
<para>If the geometry is a polygon or multi-polygon returns the number of rings. Unlike NumInteriorRings, it counts
the outer rings as well.</para>
<para>&Z_support;</para>
<para>&curve_support;</para>
</refsection>
<refsection>
<title>Examples</title>
<programlisting>SELECT ST_NRings(geom) As Nrings, ST_NumInteriorRings(geom) As ninterrings
FROM (SELECT ST_GeomFromText('POLYGON((1 2, 3 4, 5 6, 1 2))') As geom) As foo;
nrings | ninterrings
--------+-------------
1 | 0
(1 row)
</programlisting>
</refsection>
<!-- Optionally add a "See Also" section -->
<refsection>
<title>See Also</title>
<para><xref linkend="ST_NumInteriorRings" /></para>
</refsection>
</refentry>
<refentry id="ST_NumGeometries">
<refnamediv>
<refname>ST_NumGeometries</refname>
<refpurpose>Returns the number of elements in a geometry collection.</refpurpose>
</refnamediv>
<refsynopsisdiv>
<funcsynopsis>
<funcprototype>
<funcdef>integer <function>ST_NumGeometries</function></funcdef>
<paramdef><type>geometry </type> <parameter>geom</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsection>
<title>Description</title>
<para>Returns the number of Geometries. If geometry is a GEOMETRYCOLLECTION (or MULTI*) return the
number of geometries, for single geometries will return 1, otherwise return NULL.</para>
<para>Enhanced: 2.0.0 support for Polyhedral surfaces, Triangles and TIN was introduced.</para>
<para>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.</para>
<para>&sqlmm_compliant; SQL-MM 3: 9.1.4</para>
<para>&Z_support;</para>
<para>&P_support;</para>
<para>&T_support;</para>
</refsection>
<refsection>
<title>Examples</title>
<programlisting>
--Prior versions would have returned NULL for this -- in 2.0.0 this returns 1
SELECT ST_NumGeometries(ST_GeomFromText('LINESTRING(77.29 29.07,77.42 29.26,77.27 29.31,77.29 29.07)'));
--result
1
--Geometry Collection Example - multis count as one geom in a collection
SELECT ST_NumGeometries(ST_GeomFromEWKT('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)))'));
--result
3
</programlisting>
</refsection>
<refsection>
<title>See Also</title>
<para><xref linkend="ST_GeometryN" />, <xref linkend="ST_Multi" /></para>
</refsection>
</refentry>
<refentry id="ST_NumInteriorRings">
<refnamediv>
<refname>ST_NumInteriorRings</refname>
<refpurpose>Returns the number of interior rings (holes) of a Polygon.</refpurpose>
</refnamediv>
<refsynopsisdiv>
<funcsynopsis>
<funcprototype>
<funcdef>integer <function>ST_NumInteriorRings</function></funcdef>
<paramdef><type>geometry </type> <parameter>a_polygon</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsection>
<title>Description</title>
<para>
Return the number of interior rings of a polygon geometry.
Return NULL if the geometry is not a polygon.
</para>
<para>&sqlmm_compliant; SQL-MM 3: 8.2.5</para>
<para>Changed: 2.0.0 - in prior versions it would allow passing a MULTIPOLYGON, returning the number of interior rings of first POLYGON.</para>
</refsection>
<refsection>
<title>Examples</title>
<programlisting>
--If you have a regular polygon
SELECT gid, field1, field2, ST_NumInteriorRings(geom) AS numholes
FROM sometable;
--If you have multipolygons
--And you want to know the total number of interior rings in the MULTIPOLYGON
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;
</programlisting>
</refsection>
<refsection>
<title>See Also</title>
<para><xref linkend="ST_NumInteriorRing" />, <xref linkend="ST_InteriorRingN" /></para>
</refsection>
</refentry>
<refentry id="ST_NumInteriorRing">
<refnamediv>
<refname>ST_NumInteriorRing</refname>
<refpurpose>Returns the number of interior rings (holes) of a Polygon. Aias for ST_NumInteriorRings</refpurpose>
</refnamediv>
<refsynopsisdiv>
<funcsynopsis>
<funcprototype>
<funcdef>integer <function>ST_NumInteriorRing</function></funcdef>
<paramdef><type>geometry </type> <parameter>a_polygon</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsection>
<title>See Also</title>
<para><xref linkend="ST_NumInteriorRings" />, <xref linkend="ST_InteriorRingN" /></para>
</refsection>
</refentry>
<refentry id="ST_NumPatches">
<refnamediv>
<refname>ST_NumPatches</refname>
<refpurpose>Return the number of faces on a Polyhedral Surface. Will return null for non-polyhedral geometries.</refpurpose>
</refnamediv>
<refsynopsisdiv>
<funcsynopsis>
<funcprototype>
<funcdef>integer <function>ST_NumPatches</function></funcdef>
<paramdef><type>geometry </type> <parameter>g1</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsection>
<title>Description</title>
<para>Return the number of faces on a Polyhedral Surface. Will return null for non-polyhedral geometries. This is
an alias for ST_NumGeometries to support MM naming. Faster to use ST_NumGeometries if you don't care about MM convention.</para>
<para>Availability: 2.0.0</para>
<para>&Z_support;</para>
<para>&sfs_compliant;</para>
<para>&sqlmm_compliant; SQL-MM ISO/IEC 13249-3: 8.5</para>
<para>&P_support;</para>
</refsection>
<refsection>
<title>Examples</title>
<programlisting>SELECT ST_NumPatches(ST_GeomFromEWKT('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)) )'));
--result
6
</programlisting>
</refsection>
<refsection>
<title>See Also</title>
<para><xref linkend="ST_GeomFromEWKT" />, <xref linkend="ST_NumGeometries" /></para>
</refsection>
</refentry>
<refentry id="ST_NumPoints">
<refnamediv>
<refname>ST_NumPoints</refname>
<refpurpose>Returns the number of points in a LineString or CircularString.</refpurpose>
</refnamediv>
<refsynopsisdiv>
<funcsynopsis>
<funcprototype>
<funcdef>integer <function>ST_NumPoints</function></funcdef>
<paramdef><type>geometry </type> <parameter>g1</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsection>
<title>Description</title>
<para>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 vertexes for
not just linestrings.
Consider using ST_NPoints instead which is multi-purpose
and works with many geometry types.</para>
<para>&sfs_compliant;</para>
<para>&sqlmm_compliant; SQL-MM 3: 7.2.4</para>
</refsection>
<refsection>
<title>Examples</title>
<programlisting>SELECT ST_NumPoints(ST_GeomFromText('LINESTRING(77.29 29.07,77.42 29.26,77.27 29.31,77.29 29.07)'));
--result
4
</programlisting>
</refsection>
<refsection>
<title>See Also</title>
<para><xref linkend="ST_NPoints" /></para>
</refsection>
</refentry>
<refentry id="ST_PatchN">
<refnamediv>
<refname>ST_PatchN</refname>
<refpurpose>Returns the Nth geometry (face) of a PolyhedralSurface.</refpurpose>
</refnamediv>
<refsynopsisdiv>
<funcsynopsis>
<funcprototype>
<funcdef>geometry <function>ST_PatchN</function></funcdef>
<paramdef><type>geometry </type> <parameter>geomA</parameter></paramdef>
<paramdef><type>integer </type> <parameter>n</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsection>
<title>Description</title>
<para>Returns the 1-based Nth geometry (face) if the geometry is a
POLYHEDRALSURFACE or POLYHEDRALSURFACEM.
Otherwise, returns NULL.
This returns the same answer as ST_GeometryN for PolyhedralSurfaces.
Using ST_GeometryN is faster.</para>
<note>
<para>Index is 1-based.</para>
</note>
<note>
<para>If you want to extract all elements of a geometry <xref linkend="ST_Dump" /> is more efficient.</para>
</note>
<para>Availability: 2.0.0</para>
<para>&sqlmm_compliant; SQL-MM ISO/IEC 13249-3: 8.5</para>
<para>&Z_support;</para>
<para>&P_support;</para>
</refsection>
<refsection>
<title>Examples</title>
<programlisting>
--Extract the 2nd face of the polyhedral surface
SELECT ST_AsEWKT(ST_PatchN(geom, 2)) As geomewkt
FROM (
VALUES (ST_GeomFromEWKT('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 foo(geom);
geomewkt
---+-----------------------------------------
POLYGON((0 0 0,0 1 0,1 1 0,1 0 0,0 0 0))
</programlisting>
</refsection>
<!-- Optionally add a "See Also" section -->
<refsection>
<title>See Also</title>
<para><xref linkend="ST_AsEWKT" />, <xref linkend="ST_GeomFromEWKT" />, <xref linkend="ST_Dump" />, <xref linkend="ST_GeometryN" />, <xref linkend="ST_NumGeometries" /></para>
</refsection>
</refentry>
<refentry id="ST_PointN">
<refnamediv>
<refname>ST_PointN</refname>
<refpurpose>Returns the Nth point in the first LineString or circular LineString in a
geometry. </refpurpose>
</refnamediv>
<refsynopsisdiv>
<funcsynopsis>
<funcprototype>
<funcdef>geometry <function>ST_PointN</function></funcdef>
<paramdef><type>geometry </type> <parameter>a_linestring</parameter></paramdef>
<paramdef><type>integer </type> <parameter>n</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsection>
<title>Description</title>
<para>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.</para>
<note>
<para>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.</para>
</note>
<note>
<para>If you want to get the Nth point of each LineString in a MultiLineString, use in conjunction
with ST_Dump</para>
</note>
<para>&sfs_compliant;</para>
<para>&sqlmm_compliant; SQL-MM 3: 7.2.5, 7.3.5</para>
<para>&Z_support;</para>
<para>&curve_support;</para>
<note><para>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.</para>
<para> Changed: 2.3.0 : negative indexing available (-1 is last point)
</para>
</note>
</refsection>
<refsection>
<title>Examples</title>
<programlisting>-- Extract all POINTs from a LINESTRING
SELECT ST_AsText(
ST_PointN(
column1,
generate_series(1, ST_NPoints(column1))
))
FROM ( VALUES ('LINESTRING(0 0, 1 1, 2 2)'::geometry) ) AS foo;
st_astext
------------
POINT(0 0)
POINT(1 1)
POINT(2 2)
(3 rows)
--Example circular string
SELECT ST_AsText(ST_PointN(ST_GeomFromText('CIRCULARSTRING(1 2, 3 2, 1 2)'), 2));
st_astext
------------
POINT(3 2)
(1 row)
SELECT ST_AsText(f)
FROM ST_GeomFromText('LINESTRING(0 0 0, 1 1 1, 2 2 2)') AS g
,ST_PointN(g, -2) AS f; -- 1 based index
st_astext
-----------------
POINT Z (1 1 1)
(1 row)
</programlisting>
</refsection>
<refsection>
<title>See Also</title>
<para><xref linkend="ST_NPoints" /></para>
</refsection>
</refentry>
<refentry id="ST_Points">
<refnamediv>
<refname>ST_Points</refname>
<refpurpose>Returns a MultiPoint containing the coordinates of a geometry.
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<funcsynopsis>
<funcprototype>
<funcdef>geometry <function>ST_Points</function></funcdef>
<paramdef>
<type>geometry</type>
<parameter>geom</parameter>
</paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsection>
<title>Description</title>
<para>
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
<xref linkend="ST_RemoveRepeatedPoints" /> on the result).
</para>
<para>
To obtain information about the position of each coordinate in the parent geometry
use <xref linkend="ST_DumpPoints" />.
</para>
<para>
M and Z coordinates are preserved if present.
</para>
<para>&curve_support;</para>
<para>&Z_support;</para>
<para>Availability: 2.3.0</para>
</refsection>
<refsection>
<title>Examples</title>
<programlisting>SELECT ST_AsText(ST_Points('POLYGON Z ((30 10 4,10 30 5,40 40 6, 30 10))'));
--result
MULTIPOINT Z ((30 10 4),(10 30 5),(40 40 6),(30 10 4))
</programlisting>
</refsection>
<refsection>
<title>See Also</title>
<para><xref linkend="ST_RemoveRepeatedPoints" />, <xref linkend="ST_DumpPoints" /></para>
</refsection>
</refentry>
<refentry id="ST_StartPoint">
<refnamediv>
<refname>ST_StartPoint</refname>
<refpurpose>Returns the first point of a LineString.</refpurpose>
</refnamediv>
<refsynopsisdiv>
<funcsynopsis>
<funcprototype>
<funcdef>geometry <function>ST_StartPoint</function></funcdef>
<paramdef><type>geometry </type> <parameter>geomA</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsection>
<title>Description</title>
<para>Returns the first point of a <varname>LINESTRING</varname>
or <varname>CIRCULARLINESTRING</varname> geometry
as a <varname>POINT</varname>.
Returns <varname>NULL</varname> if the input
is not a <varname>LINESTRING</varname> or <varname>CIRCULARLINESTRING</varname>.</para>
<para>&sqlmm_compliant; SQL-MM 3: 7.1.3</para>
<para>&Z_support;</para>
<para>&curve_support;</para>
<note>
<para>Enhanced: 3.2.0 returns a point for all geometries. Prior behavior returns NULLs if input was not a LineString.</para>
<para>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.</para>
</note>
</refsection>
<refsection>
<title>Examples</title>
<para>Start point of a LineString</para>
<programlisting>SELECT ST_AsText(ST_StartPoint('LINESTRING(0 1, 0 2)'::geometry));
st_astext
------------
POINT(0 1)
</programlisting>
<para>Start point of a non-LineString is NULL</para>
<programlisting>
SELECT ST_StartPoint('POINT(0 1)'::geometry) IS NULL AS is_null;
is_null
----------
t
</programlisting>
<para>Start point of a 3D LineString</para>
<programlisting>
SELECT ST_AsEWKT(ST_StartPoint('LINESTRING(0 1 1, 0 2 2)'::geometry));
st_asewkt
------------
POINT(0 1 1)
</programlisting>
<para>Start point of a CircularString</para>
<programlisting>
SELECT ST_AsText(ST_StartPoint('CIRCULARSTRING(5 2,-3 1.999999, -2 1, -4 2, 6 3)'::geometry));
st_astext
------------
POINT(5 2)
</programlisting>
</refsection>
<refsection>
<title>See Also</title>
<para><xref linkend="ST_EndPoint" />, <xref linkend="ST_PointN" /></para>
</refsection>
</refentry>
<refentry id="ST_Summary">
<refnamediv>
<refname>ST_Summary</refname>
<refpurpose>Returns a text summary of the contents of a geometry.
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<funcsynopsis>
<funcprototype>
<funcdef>text <function>ST_Summary</function></funcdef>
<paramdef><type>geometry </type> <parameter>g</parameter></paramdef>
</funcprototype>
<funcprototype>
<funcdef>text <function>ST_Summary</function></funcdef>
<paramdef><type>geography </type> <parameter>g</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsection>
<title>Description</title>
<para>Returns a text summary of the contents of the geometry.</para>
<para>
Flags shown square brackets after the geometry type
have the following meaning:
<itemizedlist>
<listitem><para>M: has M coordinate</para></listitem>
<listitem><para>Z: has Z coordinate</para></listitem>
<listitem><para>B: has a cached bounding box</para></listitem>
<listitem><para>G: is geodetic (geography)</para></listitem>
<listitem><para>S: has spatial reference system</para></listitem>
</itemizedlist>
</para>
<!-- Optionally mention Circular String Support -->
<para>&curve_support;</para>
<!-- Optionally mention supports Polyhedral Surface -->
<para>&P_support;</para>
<!-- Optionally mention support for Triangles and TINS -->
<para>&T_support;</para>
<para>Availability: 1.2.2</para>
<para>Enhanced: 2.0.0 added support for geography</para>
<para>Enhanced: 2.1.0 S flag to denote if has a known spatial reference system</para>
<para>Enhanced: 2.2.0 Added support for TIN and Curves</para>
</refsection>
<refsection>
<title>Examples</title>
<programlisting>
=# SELECT ST_Summary(ST_GeomFromText('LINESTRING(0 0, 1 1)')) as geom,
ST_Summary(ST_GeogFromText('POLYGON((0 0, 1 1, 1 2, 1 1, 0 0))')) geog;
geom | geog
-----------------------------+--------------------------
LineString[B] with 2 points | Polygon[BGS] with 1 rings
| ring 0 has 5 points
:
(1 row)
=# SELECT ST_Summary(ST_GeogFromText('LINESTRING(0 0 1, 1 1 1)')) As geog_line,
ST_Summary(ST_GeomFromText('SRID=4326;POLYGON((0 0 1, 1 1 2, 1 2 3, 1 1 1, 0 0 1))')) As geom_poly;
;
geog_line | geom_poly
-------------------------------- +--------------------------
LineString[ZBGS] with 2 points | Polygon[ZBS] with 1 rings
: ring 0 has 5 points
:
(1 row)
</programlisting>
</refsection>
<refsection>
<title>See Also</title>
<para>
<xref linkend="PostGIS_DropBBox" />,
<xref linkend="PostGIS_AddBBox" />,
<xref linkend="ST_Force_3DM" />,
<xref linkend="ST_Force_3DZ" />,
<xref linkend="ST_Force2D" />,
<xref linkend="geography" />
</para>
<para>
<xref linkend="ST_IsValid" />,
<xref linkend="ST_IsValid" />,
<xref linkend="ST_IsValidReason" />,
<xref linkend="ST_IsValidDetail" />
</para>
</refsection>
</refentry>
<refentry id="ST_X">
<refnamediv>
<refname>ST_X</refname>
<refpurpose>Returns the X coordinate of a Point.</refpurpose>
</refnamediv>
<refsynopsisdiv>
<funcsynopsis>
<funcprototype>
<funcdef>float <function>ST_X</function></funcdef>
<paramdef><type>geometry </type> <parameter>a_point</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsection>
<title>Description</title>
<para>Return the X coordinate of the point, or NULL if not
available. Input must be a point.</para>
<note><para>To get the minimum and maximum X value of geometry coordinates use the functions
<xref linkend="ST_XMin" /> and <xref linkend="ST_XMax" />.</para></note>
<para>&sqlmm_compliant; SQL-MM 3: 6.1.3</para>
<para>&Z_support;</para>
</refsection>
<refsection>
<title>Examples</title>
<programlisting>SELECT ST_X(ST_GeomFromEWKT('POINT(1 2 3 4)'));
st_x
------
1
(1 row)
SELECT ST_Y(ST_Centroid(ST_GeomFromEWKT('LINESTRING(1 2 3 4, 1 1 1 1)')));
st_y
------
1.5
(1 row)
</programlisting>
</refsection>
<!-- Optionally add a "See Also" section -->
<refsection>
<title>See Also</title>
<para><xref linkend="ST_Centroid" />, <xref linkend="ST_GeomFromEWKT" />, <xref linkend="ST_M" />, <xref linkend="ST_XMax" />, <xref linkend="ST_XMin" />, <xref linkend="ST_Y" />, <xref linkend="ST_Z" /></para>
</refsection>
</refentry>
<refentry id="ST_Y">
<refnamediv>
<refname>ST_Y</refname>
<refpurpose>Returns the Y coordinate of a Point.</refpurpose>
</refnamediv>
<refsynopsisdiv>
<funcsynopsis>
<funcprototype>
<funcdef>float <function>ST_Y</function></funcdef>
<paramdef><type>geometry </type> <parameter>a_point</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsection>
<title>Description</title>
<para>Return the Y coordinate of the point, or NULL if not
available. Input must be a point.</para>
<note><para>To get the minimum and maximum Y value of geometry coordinates use the functions
<xref linkend="ST_YMin" /> and <xref linkend="ST_YMax" />.</para></note>
<para>&sfs_compliant;</para>
<para>&sqlmm_compliant; SQL-MM 3: 6.1.4</para>
<para>&Z_support;</para>
</refsection>
<refsection>
<title>Examples</title>
<programlisting>SELECT ST_Y(ST_GeomFromEWKT('POINT(1 2 3 4)'));
st_y
------
2
(1 row)
SELECT ST_Y(ST_Centroid(ST_GeomFromEWKT('LINESTRING(1 2 3 4, 1 1 1 1)')));
st_y
------
1.5
(1 row)
</programlisting>
</refsection>
<!-- Optionally add a "See Also" section -->
<refsection>
<title>See Also</title>
<para><xref linkend="ST_Centroid" />, <xref linkend="ST_GeomFromEWKT" />, <xref linkend="ST_M" />, <xref linkend="ST_X" />, <xref linkend="ST_YMax" />, <xref linkend="ST_YMin" />, <xref linkend="ST_Z" /></para>
</refsection>
</refentry>
<refentry id="ST_Z">
<refnamediv>
<refname>ST_Z</refname>
<refpurpose>Returns the Z coordinate of a Point.</refpurpose>
</refnamediv>
<refsynopsisdiv>
<funcsynopsis>
<funcprototype>
<funcdef>float <function>ST_Z</function></funcdef>
<paramdef><type>geometry </type> <parameter>a_point</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsection>
<title>Description</title>
<para>Return the Z coordinate of the point, or NULL if not
available. Input must be a point.</para>
<note><para>To get the minimum and maximum Z value of geometry coordinates use the functions
<xref linkend="ST_ZMin" /> and <xref linkend="ST_ZMax" />.</para></note>
<para>&sqlmm_compliant;</para>
<para>&Z_support;</para>
</refsection>
<refsection>
<title>Examples</title>
<programlisting>SELECT ST_Z(ST_GeomFromEWKT('POINT(1 2 3 4)'));
st_z
------
3
(1 row)
</programlisting>
</refsection>
<!-- Optionally add a "See Also" section -->
<refsection>
<title>See Also</title>
<para><xref linkend="ST_GeomFromEWKT" />, <xref linkend="ST_M" />, <xref linkend="ST_X" />, <xref linkend="ST_Y" />, <xref linkend="ST_ZMax" />, <xref linkend="ST_ZMin" /> </para>
</refsection>
</refentry>
<refentry id="ST_Zmflag">
<refnamediv>
<refname>ST_Zmflag</refname>
<refpurpose>Returns a code indicating the ZM coordinate dimension of a geometry.</refpurpose>
</refnamediv>
<refsynopsisdiv>
<funcsynopsis>
<funcprototype>
<funcdef>smallint <function>ST_Zmflag</function></funcdef>
<paramdef><type>geometry </type> <parameter>geomA</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsection>
<title>Description</title>
<para>Returns a code indicating the ZM coordinate dimension of a geometry. </para>
<para>Values are: 0 = 2D, 1 = 3D-M, 2 = 3D-Z, 3 = 4D.</para>
<para>&Z_support;</para>
<para>&curve_support;</para>
</refsection>
<refsection>
<title>Examples</title>
<programlisting>SELECT ST_Zmflag(ST_GeomFromEWKT('LINESTRING(1 2, 3 4)'));
st_zmflag
-----------
0
SELECT ST_Zmflag(ST_GeomFromEWKT('LINESTRINGM(1 2 3, 3 4 3)'));
st_zmflag
-----------
1
SELECT ST_Zmflag(ST_GeomFromEWKT('CIRCULARSTRING(1 2 3, 3 4 3, 5 6 3)'));
st_zmflag
-----------
2
SELECT ST_Zmflag(ST_GeomFromEWKT('POINT(1 2 3 4)'));
st_zmflag
-----------
3
</programlisting>
</refsection>
<!-- Optionally add a "See Also" section -->
<refsection>
<title>See Also</title>
<para><xref linkend="ST_CoordDim" />, <xref linkend="ST_NDims" />, <xref linkend="ST_Dimension" /></para>
</refsection>
</refentry>
</sect1>
View Git Blame Copy Permalink