[postgis-tickets] r17431 - Improve doc Reference Constructors
Martin Davis
mtnclimb at gmail.com
Fri May 3 03:05:27 PDT 2019
Author: mdavis
Date: 2019-05-03 15:05:26 -0700 (Fri, 03 May 2019)
New Revision: 17431
Modified:
trunk/doc/reference_constructor.xml
Log:
Improve doc Reference Constructors
Modified: trunk/doc/reference_constructor.xml
===================================================================
--- trunk/doc/reference_constructor.xml 2019-05-02 17:34:38 UTC (rev 17430)
+++ trunk/doc/reference_constructor.xml 2019-05-03 22:05:26 UTC (rev 17431)
@@ -5,7 +5,7 @@
<refentry id="ST_Collect">
<refnamediv>
<refname>ST_Collect</refname>
- <refpurpose>Creates a GeometryCollection or Multi* value from a set of other geometries.</refpurpose>
+ <refpurpose>Creates a GeometryCollection or Multi* geometry from a set of geometries.</refpurpose>
</refnamediv>
<refsynopsisdiv>
@@ -28,40 +28,27 @@
<refsection>
<title>Description</title>
- <para> Collects geometries into an appropriate geometry collection type.
- The output geometry is either a MULTI* or a
- GEOMETRYCOLLECTION, depending on whether the input geometries have the same or different types
+ <para> Collects geometries into a geometry collection.
+ The result is either a Multi* or a
+ GeometryCollection, depending on whether the input geometries have the same or different types
(homogeneous or heterogeneous).
The input geometries are left unchanged within the collection.
</para>
- <para>
- Comes in 3 variants.
- Variant 1 collects 2 geometries.
- Variant 2 takes an array of geometries.
- Variant 3 is an aggregate function that takes a set of geometries.
- </para>
- <para>Two-argument and array variants: Returns a geometry which is a collection of the
- input geometries. </para>
+ <para><emphasis role="bold">Variant 1:</emphasis> accepts two input geometries</para>
+ <para><emphasis role="bold">Variant 2:</emphasis> accepts an array of geometries</para>
+ <para><emphasis role="bold">Variant 3:</emphasis> aggregate function accepting a rowset of geometries.</para>
- <para>Aggregate variant: Returns a GEOMETRYCOLLECTION or a MULTI geometry
- from a set of geometries. The function is an "aggregate"
- function in the terminology of PostgreSQL. That means that it
- operates on rows of data, in the same way the SUM() and AVG()
- functions do. For example, "SELECT ST_Collect(GEOM) FROM GEOMTABLE
- GROUP BY ATTRCOLUMN" returns a separate collection geometry for
- each distinct value of ATTRCOLUMN.</para>
-
<note><para>
- If any of the input geometries are collections (MULTI* or GEOMETRYCOLLECTION)
- ST_Collect will return a GEOMETRYCOLLECTION (since that is the only type
- which can contain nested collections).
- To prevent this, use <xref linkend="ST_Dump" /> to expand the
- input collections to their elements, and then collect the atomic geometries (see example below).
- </para></note>
+ If any of the input geometries are collections (Multi* or GeometryCollection)
+ ST_Collect returns a GeometryCollection (since that is the only type
+ which can contain nested collections).
+ To prevent this, use <xref linkend="ST_Dump" /> in a subquery to expand the
+ input collections to their atomic elements (see example below).
+ </para></note>
- <note><para>ST_Collect and ST_Union are superficially similar, but in fact operate very differently.
- ST_Collect simply aggregates geometries into a collection without changing them in any way.
+ <note><para>ST_Collect and <xref linkend="ST_Union" /> appear similar, but in fact operate quite differently.
+ ST_Collect aggregates geometries into a collection without changing them in any way.
ST_Union geometrically merges geometries where they overlap,
and splits linestrings at intersections.
It may return single geometries when it dissolves boundaries.
@@ -68,62 +55,70 @@
</para></note>
<para>Availability: 1.4.0 - ST_Collect(geomarray) was introduced. ST_Collect was enhanced to handle more geometries faster.</para>
- <para>&Z_support;</para>
- <para>&curve_support; This method supports Circular Strings
- and Curves, but will never return a MULTICURVE or MULTI as one
- would expect and PostGIS does not currently support those.</para>
+ <para>&Z_support;</para>
+ <para>&curve_support;</para>
</refsection>
<refsection>
- <title>Examples</title>
- <para>Aggregate example</para>
- <programlisting>SELECT stusps, ST_Collect(f.the_geom) as singlegeom
- FROM (SELECT stusps, (ST_Dump(the_geom)).geom As the_geom
- FROM
- somestatetable ) As f
-GROUP BY stusps</programlisting>
- <para>Non-Aggregate example</para>
- <programlisting>SELECT ST_AsText(ST_Collect(ST_GeomFromText('POINT(1 2)'),
+ <title>Examples - Two-input variant</title>
+ <para>Collect 2D points.</para>
+<programlisting>
+SELECT ST_AsText( ST_Collect( ST_GeomFromText('POINT(1 2)'),
ST_GeomFromText('POINT(-2 3)') ));
st_astext
----------
MULTIPOINT(1 2,-2 3)
+</programlisting>
---Collect 2 d points
-SELECT ST_AsText(ST_Collect(ST_GeomFromText('POINT(1 2)'),
- ST_GeomFromText('POINT(1 2)') ) );
-
-st_astext
-----------
-MULTIPOINT(1 2,1 2)
-
---Collect 3d points
-SELECT ST_AsEWKT(ST_Collect(ST_GeomFromEWKT('POINT(1 2 3)'),
+<para>Collect 3D points.</para>
+<programlisting>
+SELECT ST_AsEWKT( ST_Collect( ST_GeomFromEWKT('POINT(1 2 3)'),
ST_GeomFromEWKT('POINT(1 2 4)') ) );
st_asewkt
-------------------------
MULTIPOINT(1 2 3,1 2 4)
+ </programlisting>
- --Example with curves
-SELECT ST_AsText(ST_Collect(ST_GeomFromText('CIRCULARSTRING(220268 150415,220227 150505,220227 150406)'),
-ST_GeomFromText('CIRCULARSTRING(220227 150406,2220227 150407,220227 150406)')));
- st_astext
+<para>Collect curves.</para>
+ <programlisting>
+SELECT ST_AsText( ST_Collect( 'CIRCULARSTRING(220268 150415,220227 150505,220227 150406)',
+ 'CIRCULARSTRING(220227 150406,2220227 150407,220227 150406)'));
+
+ st_astext
------------------------------------------------------------------------------------
- GEOMETRYCOLLECTION(CIRCULARSTRING(220268 150415,220227 150505,220227 150406),
+MULTICURVE(CIRCULARSTRING(220268 150415,220227 150505,220227 150406),
CIRCULARSTRING(220227 150406,2220227 150407,220227 150406))
+</programlisting>
+ </refsection>
+ <refsection>
+<title>Examples - Array variant</title>
+<para>Using an array constructor for a subquery.</para>
+<programlisting>
+SELECT ST_Collect( ARRAY( SELECT the_geom FROM sometable ) );
+</programlisting>
+<para>Using an array constructor for values.</para>
+<programlisting>
+SELECT ST_AsText( ST_Collect(
+ ARRAY[ ST_GeomFromText('LINESTRING(1 2, 3 4)'),
+ ST_GeomFromText('LINESTRING(3 4, 4 5)') ] )) As wktcollect;
---New ST_Collect array construct
-SELECT ST_Collect(ARRAY(SELECT the_geom FROM sometable));
-
-SELECT ST_AsText(ST_Collect(ARRAY[ST_GeomFromText('LINESTRING(1 2, 3 4)'),
- ST_GeomFromText('LINESTRING(3 4, 4 5)')])) As wktcollect;
-
--wkt collect --
MULTILINESTRING((1 2,3 4),(3 4,4 5))
+</programlisting>
+ </refsection>
+ <refsection>
+ <title>Examples - Aggregate variant</title>
+ <para>Creating multiple collections by grouping geometries in a table.</para>
+<programlisting>
+SELECT stusps, ST_Collect(f.the_geom) as geom
+ FROM (SELECT stusps, (ST_Dump(the_geom)).geom As the_geom
+ FROM
+ somestatetable ) As f
+ GROUP BY stusps
+</programlisting>
-</programlisting>
</refsection>
<refsection>
<title>See Also</title>
@@ -151,6 +146,9 @@
<title>Description</title>
<para>Creates a LineString from a MultiPoint geometry.</para>
+
+ <para>Use <xref linkend="ST_MakeLine" /> to create lines from Point or LineString inputs.</para>
+
<para>&Z_support;</para>
</refsection>
@@ -157,13 +155,13 @@
<refsection>
<title>Examples</title>
+ <para>Create a 3D line string from a 3D MultiPoint</para>
+ <programlisting>
+SELECT ST_AsEWKT( ST_LineFromMultiPoint('MULTIPOINT(1 2 3, 4 5 6, 7 8 9)') ));
- <programlisting>
---Create a 3d line string from a 3d multipoint
-SELECT ST_AsEWKT(ST_LineFromMultiPoint(ST_GeomFromEWKT('MULTIPOINT(1 2 3, 4 5 6, 7 8 9)')));
--result--
LINESTRING(1 2 3,4 5 6,7 8 9)
- </programlisting>
+</programlisting>
</refsection>
<!-- Optionally add a "See Also" section -->
@@ -170,10 +168,58 @@
<refsection>
<title>See Also</title>
- <para><xref linkend="ST_AsEWKT" />, <xref linkend="ST_Collect" />, <xref linkend="ST_MakeLine" /></para>
+ <para><xref linkend="ST_AsEWKT" />, <xref linkend="ST_MakeLine" /></para>
</refsection>
</refentry>
+ <refentry id="ST_MakeEnvelope">
+ <refnamediv>
+ <refname>ST_MakeEnvelope</refname>
+
+ <refpurpose>Creates a rectangular Polygon from minimum and maximum coordinates.</refpurpose>
+ </refnamediv>
+
+ <refsynopsisdiv>
+ <funcsynopsis>
+ <funcprototype>
+ <funcdef>geometry <function>ST_MakeEnvelope</function></funcdef>
+ <paramdef><type>float</type> <parameter>xmin</parameter></paramdef>
+ <paramdef><type>float</type> <parameter>ymin</parameter></paramdef>
+ <paramdef><type>float</type> <parameter>xmax</parameter></paramdef>
+ <paramdef><type>float</type> <parameter>ymax</parameter></paramdef>
+ <paramdef choice="opt"><type>integer</type> <parameter>srid=unknown</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ </refsynopsisdiv>
+
+ <refsection>
+ <title>Description</title>
+
+ <para>Creates a rectangular Polygon from the minimum and maximum values for X and Y.
+ Input values must be in the spatial reference system specified by the SRID.
+ If no SRID is specified the unknown spatial reference system (SRID 0) is used.</para>
+
+ <para>Availability: 1.5</para>
+ <para>Enhanced: 2.0: Ability to specify an envelope without specifying an SRID was introduced.</para>
+
+ </refsection>
+
+ <refsection>
+ <title>Example: Building a bounding box polygon</title>
+ <programlisting>
+SELECT ST_AsText( ST_MakeEnvelope(10, 10, 11, 11, 4326) );
+
+st_asewkt
+-----------
+POLYGON((10 10, 10 11, 11 11, 11 10, 10 10))
+</programlisting>
+ </refsection>
+ <refsection>
+ <title>See Also</title>
+ <para><xref linkend="ST_MakePoint" />, <xref linkend="ST_MakeLine" />, <xref linkend="ST_MakePolygon" /></para>
+ </refsection>
+ </refentry>
+
<refentry id="ST_MakeLine">
<refnamediv>
<refname>ST_MakeLine</refname>
@@ -185,18 +231,18 @@
<funcsynopsis>
<funcprototype>
<funcdef>geometry <function>ST_MakeLine</function></funcdef>
- <paramdef><type>geometry set</type> <parameter>geoms</parameter></paramdef>
+ <paramdef><type>geometry</type> <parameter>geom1</parameter></paramdef>
+ <paramdef><type>geometry</type> <parameter>geom2</parameter></paramdef>
</funcprototype>
<funcprototype>
<funcdef>geometry <function>ST_MakeLine</function></funcdef>
- <paramdef><type>geometry</type> <parameter>geom1</parameter></paramdef>
- <paramdef><type>geometry</type> <parameter>geom2</parameter></paramdef>
+ <paramdef><type>geometry[]</type> <parameter>geoms_array</parameter></paramdef>
</funcprototype>
<funcprototype>
<funcdef>geometry <function>ST_MakeLine</function></funcdef>
- <paramdef><type>geometry[]</type> <parameter>geoms_array</parameter></paramdef>
+ <paramdef><type>geometry set</type> <parameter>geoms</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
@@ -204,16 +250,19 @@
<refsection>
<title>Description</title>
- <para>ST_MakeLine comes in 3 forms: a spatial aggregate that takes
- rows of point, multipoint, or line geometries and returns a line string, a
- function that takes an array of point, multipoint, or line, and a regular
- function that takes two point, multipoint, or line geometries. You
- might want to use a subselect to order points before feeding them
- to the aggregate version of this function.</para>
+ <para>Creates a LineString containing the points of Point, MultiPoint, or LineString geometries.
+ Other geometry types cause an error.
+ </para>
+ <para><emphasis role="bold">Variant 1:</emphasis> accepts two input geometries</para>
+ <para><emphasis role="bold">Variant 2:</emphasis> accepts an array of geometries</para>
+ <para><emphasis role="bold">Variant 3:</emphasis> aggregate function accepting a rowset of geometries.
+ To ensure the order of the input geometries use <varname>ORDER BY</varname> in the function call,
+ or a subquery with an <varname>ORDER BY</varname> clause.</para>
- <para>Inputs other than point, multipoint, or lines are ignored.</para>
<para>
- When adding line components common nodes at the beginning of lines are removed from the output. Common nodes in point and multipoint inputs are not removed.
+ Repeated nodes at the beginning of input LineStrings are collapsed to a single point.
+ Repeated points in Point and MultiPoint inputs are not collapsed.
+ <xref linkend="ST_RemoveRepeatedPoints" /> can be used to collapse repeated points from the output LineString.
</para>
<para>&Z_support;</para>
@@ -225,248 +274,83 @@
</refsection>
<refsection>
- <title>Examples: Spatial Aggregate version</title>
- <para>This example takes a sequence of GPS points and creates one record for each
- gps travel where the geometry field is a line string composed of the gps points
- in the order of the travel.</para>
+ <title>Examples: Two-input variant</title>
- <programlisting>
--- For pre-PostgreSQL 9.0 - this usually works,
--- but the planner may on occasion choose not to respect the order of the subquery
-SELECT gps.gps_track, ST_MakeLine(gps.the_geom) As newgeom
- FROM (SELECT gps_track, gps_time, the_geom
- FROM gps_points ORDER BY gps_track, gps_time) As gps
- GROUP BY gps.gps_track;</programlisting>
+<para>Create a line composed of two points.</para>
+<programlisting>
+SELECT ST_AsText( ST_MakeLine(ST_MakePoint(1,2), ST_MakePoint(3,4)) );
- <programlisting>
--- If you are using PostgreSQL 9.0+
--- (you can use the new ORDER BY support for aggregates)
--- this is a guaranteed way to get a correctly ordered linestring
--- Your order by part can order by more than one column if needed
-SELECT gps.gps_track, ST_MakeLine(gps.the_geom ORDER BY gps_time) As newgeom
- FROM gps_points As gps
- GROUP BY gps.gps_track;</programlisting>
- </refsection>
- <refsection>
- <title>Examples: Non-Spatial Aggregate version</title>
-
- <para>First example is a simple one off line string composed of 2 points. The second formulates
- line strings from 2 points a user draws. The third is a one-off that joins 2 3d points to create a line in 3d space.</para>
- <programlisting>
-SELECT ST_AsText(ST_MakeLine(ST_MakePoint(1,2), ST_MakePoint(3,4)));
st_astext
---------------------
LINESTRING(1 2,3 4)
+</programlisting>
-SELECT userpoints.id, ST_MakeLine(startpoint, endpoint) As drawn_line
- FROM userpoints ;
+<para>Create a 3D line from two 3D points.</para>
+<programlisting>
+SELECT ST_AsEWKT( ST_MakeLine(ST_MakePoint(1,2,3), ST_MakePoint(3,4,5) ));
-SELECT ST_AsEWKT(ST_MakeLine(ST_MakePoint(1,2,3), ST_MakePoint(3,4,5)));
st_asewkt
-------------------------
LINESTRING(1 2 3,3 4 5)
- </programlisting>
+</programlisting>
+
+<para>Create a line from two disjoint LineStrings.</para>
+<programlisting>
+ select ST_AsText( ST_MakeLine( 'LINESTRING(0 0, 1 1)', 'LINESTRING(2 2, 3 3)' ) );
+
+ st_astext
+-----------------------------
+ LINESTRING(0 0,1 1,2 2,3 3)
+</programlisting>
</refsection>
<refsection>
- <title>Examples: Using Array version</title>
+ <title>Examples: Array variant</title>
- <programlisting>
-SELECT ST_MakeLine(ARRAY(SELECT ST_Centroid(the_geom) FROM visit_locations ORDER BY visit_time));
+ <para>Create a line from an array formed by a subquery with ordering.</para>
+<programlisting>
+SELECT ST_MakeLine( ARRAY( SELECT ST_Centroid(the_geom) FROM visit_locations ORDER BY visit_time) );
+</programlisting>
---Making a 3d line with 3 3-d points
-SELECT ST_AsEWKT(ST_MakeLine(ARRAY[ST_MakePoint(1,2,3),
- ST_MakePoint(3,4,5), ST_MakePoint(6,6,6)]));
+ <para>Create a 3D line from an array of 3D points</para>
+<programlisting>
+SELECT ST_AsEWKT( ST_MakeLine(
+ ARRAY[ ST_MakePoint(1,2,3), ST_MakePoint(3,4,5), ST_MakePoint(6,6,6) ] ));
+
st_asewkt
-------------------------
LINESTRING(1 2 3,3 4 5,6 6 6)
- </programlisting>
+</programlisting>
</refsection>
- <!-- TODO: add an example using lines -->
-
<refsection>
- <title>See Also</title>
- <para><xref linkend="ST_AsEWKT" />, <xref linkend="ST_AsText" />, <xref linkend="ST_GeomFromText" />, <xref linkend="ST_MakePoint" /></para>
- </refsection>
- </refentry>
+ <title>Examples: Aggregate variant</title>
+ <para>This example queries time-based sequences of GPS points from a set of tracks
+ and creates one record for each track.
+ The result geometries are LineStrings composed of the GPS track points in the order of travel.</para>
+<para>Using aggregate <varname>ORDER BY</varname> provides a correctly-ordered linestring.</para>
+ <programlisting>
+SELECT gps.track_id, ST_MakeLine(gps.geom ORDER BY gps_time) As geom
+ FROM gps_points As gps
+ GROUP BY track_id;</programlisting>
- <refentry id="ST_MakeEnvelope">
- <refnamediv>
- <refname>ST_MakeEnvelope</refname>
-
- <refpurpose>Creates a rectangular Polygon from the given minimum and maximum ordinates.</refpurpose>
- </refnamediv>
-
- <refsynopsisdiv>
- <funcsynopsis>
- <funcprototype>
- <funcdef>geometry <function>ST_MakeEnvelope</function></funcdef>
- <paramdef><type>double precision</type> <parameter>xmin</parameter></paramdef>
- <paramdef><type>double precision</type> <parameter>ymin</parameter></paramdef>
- <paramdef><type>double precision</type> <parameter>xmax</parameter></paramdef>
- <paramdef><type>double precision</type> <parameter>ymax</parameter></paramdef>
- <paramdef choice="opt"><type>integer </type> <parameter>srid=unknown</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- </refsynopsisdiv>
-
- <refsection>
- <title>Description</title>
-
- <para>Creates a rectangular Polygon formed from the minima and maxima. by the given shell. Input
- values must be in SRS specified by the SRID. If no SRID is specified the unknown spatial reference system is assumed</para>
-
- <para>Availability: 1.5</para>
- <para>Enhanced: 2.0: Ability to specify an envelope without specifying an SRID was introduced.</para>
-
+<para>Prior to PostgreSQL 9, ordering in a subquery can be used.
+However, sometimes the query plan may not respect the order of the subquery.</para>
+ <programlisting>
+SELECT gps.track_id, ST_MakeLine(gps.geom) As geom
+ FROM ( SELECT track_id, gps_time, geom
+ FROM gps_points ORDER BY track_id, gps_time ) As gps
+ GROUP BY track_id;</programlisting>
</refsection>
<refsection>
- <title>Example: Building a bounding box polygon</title>
- <programlisting>
-SELECT ST_AsText(ST_MakeEnvelope(10, 10, 11, 11, 4326));
-
-st_asewkt
------------
-POLYGON((10 10, 10 11, 11 11, 11 10, 10 10))
- </programlisting>
- </refsection>
- <refsection>
<title>See Also</title>
- <para><xref linkend="ST_MakePoint" />, <xref linkend="ST_MakeLine" />, <xref linkend="ST_MakePolygon" /></para>
+ <para><xref linkend="ST_RemoveRepeatedPoints" />, <xref linkend="ST_AsEWKT" />, <xref linkend="ST_AsText" />, <xref linkend="ST_GeomFromText" />, <xref linkend="ST_MakePoint" /></para>
</refsection>
</refentry>
- <refentry id="ST_MakePolygon">
- <refnamediv>
- <refname>ST_MakePolygon</refname>
- <refpurpose>Creates a Polygon from a shell and optional list of holes.</refpurpose>
- </refnamediv>
-
- <refsynopsisdiv>
- <funcsynopsis>
- <funcprototype>
- <funcdef>geometry <function>ST_MakePolygon</function></funcdef>
- <paramdef><type>geometry</type> <parameter>linestring</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- <funcsynopsis>
- <funcprototype>
- <funcdef>geometry <function>ST_MakePolygon</function></funcdef>
- <paramdef><type>geometry</type> <parameter>outerlinestring</parameter></paramdef>
- <paramdef><type>geometry[]</type> <parameter>interiorlinestrings</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- </refsynopsisdiv>
-
- <refsection>
- <title>Description</title>
-
- <para>Creates a Polygon formed by the given shell. Input
- geometries must be closed LINESTRINGS. Comes in 2 variants.</para>
- <para>Variant 1: Takes one closed linestring.</para>
- <para>Variant 2: Creates a Polygon formed by the given shell and array of
- holes. You can construct a geometry array using the PostgreSQL array_agg, ARRAY[] and
- ARRAY() constructs. Input geometries must be closed LINESTRINGS.</para>
- <note>
- <para>This function will not accept a MULTILINESTRING. Use <xref linkend="ST_LineMerge" /> or <xref linkend="ST_Dump" /> to generate line strings.</para>
- </note>
-
- <para>&Z_support;</para>
- </refsection>
-
- <refsection>
- <title>Examples: Single closed LINESTRING</title>
- <programlisting>
---2d line
-SELECT ST_MakePolygon(ST_GeomFromText('LINESTRING(75.15 29.53,77 29,77.6 29.5, 75.15 29.53)'));
---If linestring is not closed
---you can add the start point to close it
-SELECT ST_MakePolygon(ST_AddPoint(foo.open_line, ST_StartPoint(foo.open_line)))
-FROM (
-SELECT ST_GeomFromText('LINESTRING(75.15 29.53,77 29,77.6 29.5)') As open_line) As foo;
-
---3d closed line
-SELECT ST_MakePolygon(ST_GeomFromText('LINESTRING(75.15 29.53 1,77 29 1,77.6 29.5 1, 75.15 29.53 1)'));
-
-st_asewkt
------------
-POLYGON((75.15 29.53 1,77 29 1,77.6 29.5 1,75.15 29.53 1))
-
---measured line --
-SELECT ST_MakePolygon(ST_GeomFromText('LINESTRINGM(75.15 29.53 1,77 29 1,77.6 29.5 2, 75.15 29.53 2)'));
-
-st_asewkt
-----------
-POLYGONM((75.15 29.53 1,77 29 1,77.6 29.5 2,75.15 29.53 2))
- </programlisting>
- </refsection>
- <refsection>
- <title>Examples: Outer shell with inner shells</title>
-
- <para>Build a donut with an ant hole</para>
- <programlisting>
-SELECT ST_MakePolygon(
- ST_ExteriorRing(ST_Buffer(foo.line,10)),
- ARRAY[ST_Translate(foo.line,1,1),
- ST_ExteriorRing(ST_Buffer(ST_MakePoint(20,20),1)) ]
- )
-FROM
- (SELECT ST_ExteriorRing(ST_Buffer(ST_MakePoint(10,10),10,10))
- As line )
- As foo;
- </programlisting>
- <para>Build province boundaries with holes
- representing lakes in the province from a set of
- province polygons/multipolygons and water linestrings.
- <note><para>The CASE construct is used because feeding a null array into
- ST_MakePolygon results in NULL.</para></note>
- <note><para>A left join is used to guarantee we get all provinces back even if they have no lakes.</para></note></para>
- <programlisting>
- SELECT p.gid, p.province_name,
- CASE WHEN
- array_agg(w.the_geom) IS NULL THEN p.the_geom
- ELSE ST_MakePolygon(ST_LineMerge(ST_Boundary(p.the_geom)), array_agg(w.the_geom)) END
- FROM
- provinces p LEFT JOIN waterlines w
- ON (ST_Within(w.the_geom, p.the_geom) AND ST_IsClosed(w.the_geom))
- GROUP BY p.gid, p.province_name, p.the_geom;
-
- --Same example above but utilizing a correlated subquery
- --and PostgreSQL built-in ARRAY() function that converts a row set to an array
-
- SELECT p.gid, p.province_name, CASE WHEN
- EXISTS(SELECT w.the_geom
- FROM waterlines w
- WHERE ST_Within(w.the_geom, p.the_geom)
- AND ST_IsClosed(w.the_geom))
- THEN
- ST_MakePolygon(ST_LineMerge(ST_Boundary(p.the_geom)),
- ARRAY(SELECT w.the_geom
- FROM waterlines w
- WHERE ST_Within(w.the_geom, p.the_geom)
- AND ST_IsClosed(w.the_geom)))
- ELSE p.the_geom END As the_geom
- FROM
- provinces p;
- </programlisting>
- </refsection>
- <refsection>
- <title>See Also</title>
- <para>
- <xref linkend="ST_Boundary" />,
- <xref linkend="ST_AddPoint" />,
- <xref linkend="ST_GeometryType" />,
- <xref linkend="ST_IsClosed" />,
- <xref linkend="ST_LineMerge" />,
- <xref linkend="ST_BuildArea" />
- </para>
- </refsection>
- </refentry>
-
<refentry id="ST_MakePoint">
<refnamediv>
<refname>ST_MakePoint</refname>
@@ -478,25 +362,25 @@
<funcsynopsis>
<funcprototype>
<funcdef>geometry <function>ST_MakePoint</function></funcdef>
- <paramdef><type>double precision</type> <parameter>x</parameter></paramdef>
- <paramdef><type>double precision</type> <parameter>y</parameter></paramdef>
+ <paramdef><type>float</type> <parameter>x</parameter></paramdef>
+ <paramdef><type>float</type> <parameter>y</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<funcsynopsis>
<funcprototype>
<funcdef>geometry <function>ST_MakePoint</function></funcdef>
- <paramdef><type>double precision</type> <parameter>x</parameter></paramdef>
- <paramdef><type>double precision</type> <parameter>y</parameter></paramdef>
- <paramdef><type>double precision</type> <parameter>z</parameter></paramdef>
+ <paramdef><type>float</type> <parameter>x</parameter></paramdef>
+ <paramdef><type>float</type> <parameter>y</parameter></paramdef>
+ <paramdef><type>float</type> <parameter>z</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<funcsynopsis>
<funcprototype>
<funcdef>geometry <function>ST_MakePoint</function></funcdef>
- <paramdef><type>double precision</type> <parameter>x</parameter></paramdef>
- <paramdef><type>double precision</type> <parameter>y</parameter></paramdef>
- <paramdef><type>double precision</type> <parameter>z</parameter></paramdef>
- <paramdef><type>double precision</type> <parameter>m</parameter></paramdef>
+ <paramdef><type>float</type> <parameter>x</parameter></paramdef>
+ <paramdef><type>float</type> <parameter>y</parameter></paramdef>
+ <paramdef><type>float</type> <parameter>z</parameter></paramdef>
+ <paramdef><type>float</type> <parameter>m</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
@@ -504,18 +388,19 @@
<refsection>
<title>Description</title>
- <para>Creates a 2D, 3DZ or 4D point geometry (geometry with measure).
- <varname>ST_MakePoint</varname> while not being OGC compliant is
- generally faster and more precise than <xref linkend="ST_GeomFromText" />
- and <xref linkend="ST_PointFromText" />. It is also easier to use if
- you have raw coordinates rather than WKT.</para>
+ <para>Creates a 2D, 3D Z or 4D ZM Point geometry.</para>
- <note><para>For geodetic coordinates, <varname>x</varname> is longitude and <varname>y</varname> is latitude</para></note>
+ <para>Use <xref linkend="ST_MakePointM" /> to make points with XYM coordinates.</para>
- <note><para>Use <xref linkend="ST_MakePointM" /> if you need to make a point with x, y and m.</para></note>
+ <para>
+ While not OGC-compliant, <varname>ST_MakePoint</varname> is
+ faster and more precise than <xref linkend="ST_GeomFromText" />
+ and <xref linkend="ST_PointFromText" />.
+ It is also easier to use for numeric coordinate values.</para>
+ <note><para>For geodetic coordinates, <varname>X</varname> is longitude and <varname>Y</varname> is latitude</para></note>
+
<para>&Z_support;</para>
-
</refsection>
<refsection>
@@ -562,39 +447,45 @@
<refsection>
<title>Description</title>
- <para>Creates a point with x, y and measure coordinates. </para>
- <note><para>Note x is longitude and y is latitude.</para></note>
+ <para>Creates a point with X, Y and M (measure) coordinates. </para>
+
+ <para>Use <xref linkend="ST_MakePoint" /> to make points with XY, XYZ, or XYZM coordinates.</para>
+
+ <note><para>For geodetic coordinates, <varname>X</varname> is longitude and <varname>Y</varname> is latitude</para></note>
+
</refsection>
<refsection>
<title>Examples</title>
- <para>We use ST_AsEWKT in these examples to show the text representation instead of ST_AsText because ST_AsText does not
- support returning M.</para>
+ <note><para><xref linkend="ST_AsEWKT" /> is used for text output
+ because <xref linkend="ST_AsText" /> does not support M values.</para></note>
+
+ <para>Create point with unknown SRID.</para>
<programlisting>
---Return EWKT representation of point with unknown SRID
-SELECT ST_AsEWKT(ST_MakePointM(-71.1043443253471, 42.3150676015829, 10));
+SELECT ST_AsEWKT( ST_MakePointM(-71.1043443253471, 42.3150676015829, 10) );
---result
st_asewkt
-----------------------------------------------
POINTM(-71.1043443253471 42.3150676015829 10)
+</programlisting>
---Return EWKT representation of point with measure marked as WGS 84 long lat
-SELECT ST_AsEWKT(ST_SetSRID(ST_MakePointM(-71.1043443253471, 42.3150676015829,10),4326));
+<para>Create point with a measure in the WGS 84 geodetic coordinate system.</para>
+<programlisting>
+SELECT ST_AsEWKT( ST_SetSRID( ST_MakePointM(-71.104, 42.315, 10), 4326));
st_asewkt
---------------------------------------------------------
-SRID=4326;POINTM(-71.1043443253471 42.3150676015829 10)
+SRID=4326;POINTM(-71.104 42.315 10)
+</programlisting>
---Return a 3d point (e.g. has altitude)
-SELECT ST_MakePoint(1, 2,1.5);
+<para>Get measure of created point.</para>
+<programlisting>
+SELECT ST_M( ST_MakePointM(-71.104, 42.315, 10) );
---Get m of point
-SELECT ST_M(ST_MakePointM(-71.1043443253471, 42.3150676015829,10));
result
-------
10
- </programlisting>
+</programlisting>
</refsection>
<refsection>
<title>See Also</title>
@@ -602,11 +493,148 @@
</refsection>
</refentry>
+ <refentry id="ST_MakePolygon">
+ <refnamediv>
+ <refname>ST_MakePolygon</refname>
+
+ <refpurpose>Creates a Polygon from a shell and optional list of holes.</refpurpose>
+ </refnamediv>
+
+ <refsynopsisdiv>
+ <funcsynopsis>
+ <funcprototype>
+ <funcdef>geometry <function>ST_MakePolygon</function></funcdef>
+ <paramdef><type>geometry</type> <parameter>linestring</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ <funcsynopsis>
+ <funcprototype>
+ <funcdef>geometry <function>ST_MakePolygon</function></funcdef>
+ <paramdef><type>geometry</type> <parameter>outerlinestring</parameter></paramdef>
+ <paramdef><type>geometry[]</type> <parameter>interiorlinestrings</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ </refsynopsisdiv>
+
+ <refsection>
+ <title>Description</title>
+
+ <para>Creates a Polygon formed by the given shell and optional array of holes.
+ Input geometries must be closed LineStrings (rings).</para>
+
+ <para><emphasis role="bold">Variant 1:</emphasis> Accepts one shell LineString.</para>
+ <para><emphasis role="bold">Variant 2:</emphasis> Accepts a shell LineString and an array of
+ inner (hole) LineStrings. A geometry array can be constructed using the PostgreSQL array_agg(), ARRAY[] or
+ ARRAY() constructs.</para>
+
+ <note><para>This function does not accept MultiLineStrings.
+ Use <xref linkend="ST_LineMerge" /> to generate a LineString, or <xref linkend="ST_Dump" /> to extract LineStrings.</para>
+ </note>
+
+ <para>&Z_support;</para>
+ </refsection>
+
+ <refsection>
+ <title>Examples: Single input variant</title>
+ <para>Create a Polygon from a 2D LineString.</para>
+ <programlisting>
+SELECT ST_MakePolygon( ST_GeomFromText('LINESTRING(75 29,77 29,77 29, 75 29)'));
+</programlisting>
+
+<para>Create a Polygon from an open LineString,
+using <xref linkend="ST_StartPoint" /> and <xref linkend="ST_AddPoint" /> to close it.</para>
+<programlisting>
+SELECT ST_MakePolygon( ST_AddPoint(foo.open_line, ST_StartPoint(foo.open_line)) )
+FROM (
+ SELECT ST_GeomFromText('LINESTRING(75 29,77 29,77 29, 75 29)') As open_line) As foo;
+</programlisting>
+
+<para>Create a Polygon from a 3D LineString</para>
+<programlisting>
+SELECT ST_AsEWKT( ST_MakePolygon( 'LINESTRING(75.15 29.53 1,77 29 1,77.6 29.5 1, 75.15 29.53 1)'));
+
+st_asewkt
+-----------
+POLYGON((75.15 29.53 1,77 29 1,77.6 29.5 1,75.15 29.53 1))
+</programlisting>
+<para>Create a Polygon from a LineString with measures</para>
+<programlisting>
+SELECT ST_AsEWKT( ST_MakePolygon( 'LINESTRINGM(75.15 29.53 1,77 29 1,77.6 29.5 2, 75.15 29.53 2)' ));
+
+st_asewkt
+----------
+POLYGONM((75.15 29.53 1,77 29 1,77.6 29.5 2,75.15 29.53 2))
+</programlisting>
+ </refsection>
+ <refsection>
+ <title>Examples: Outer shell with inner holes variant</title>
+
+ <para>Create a donut Polygon with an extra hole</para>
+ <programlisting>
+SELECT ST_MakePolygon( ST_ExteriorRing( ST_Buffer(ring.line,10)),
+ ARRAY[ ST_Translate(ring.line, 1, 1),
+ ST_ExteriorRing(ST_Buffer(ST_MakePoint(20,20),1)) ]
+ )
+FROM (SELECT ST_ExteriorRing(
+ ST_Buffer(ST_MakePoint(10,10),10,10)) AS line ) AS ring;
+</programlisting>
+ <para>Create a set of province boundaries with holes
+ representing lakes. The input is a table of
+ province Polygons/MultiPolygons and a table of water linestrings.
+ Using a LEFT JOIN ensures all provinces are included even if they have no lakes.
+ </para>
+
+ <note><para>The CASE construct is used because passing a null array into
+ ST_MakePolygon results in a NULL return value.</para></note>
+
+ <programlisting>
+ SELECT p.gid, p.province_name,
+ CASE WHEN array_agg(w.the_geom) IS NULL
+ THEN p.the_geom
+ ELSE ST_MakePolygon( ST_LineMerge(ST_Boundary(p.the_geom)), array_agg(w.the_geom)) END
+ FROM
+ provinces p LEFT JOIN waterlines w
+ ON (ST_Within(w.the_geom, p.the_geom) AND ST_IsClosed(w.the_geom))
+ GROUP BY p.gid, p.province_name, p.the_geom;
+</programlisting>
+
+ <para>Another technique is to utilize a correlated subquery
+ and the ARRAY() constructor that converts a row set to an array.</para>
+<programlisting>
+ SELECT p.gid, p.province_name,
+ CASE WHEN EXISTS( SELECT w.the_geom
+ FROM waterlines w
+ WHERE ST_Within(w.the_geom, p.the_geom)
+ AND ST_IsClosed(w.the_geom))
+ THEN ST_MakePolygon(
+ ST_LineMerge(ST_Boundary(p.the_geom)),
+ ARRAY( SELECT w.the_geom
+ FROM waterlines w
+ WHERE ST_Within(w.the_geom, p.the_geom)
+ AND ST_IsClosed(w.the_geom)))
+ ELSE p.the_geom
+ END AS the_geom
+ FROM provinces p;
+</programlisting>
+ </refsection>
+ <refsection>
+ <title>See Also</title>
+ <para>
+ <xref linkend="ST_Boundary" />,
+ <xref linkend="ST_AddPoint" />,
+ <xref linkend="ST_IsClosed" />,
+ <xref linkend="ST_LineMerge" />,
+ <xref linkend="ST_StartPoint" />,
+ <xref linkend="ST_BuildArea" />
+ </para>
+ </refsection>
+ </refentry>
+
<refentry id="ST_Point">
<refnamediv>
<refname>ST_Point</refname>
- <refpurpose>Creates a Point with the given coordinate values. OGC alias for ST_MakePoint.</refpurpose>
+ <refpurpose>Creates a Point with the given coordinate values. Alias for ST_MakePoint.</refpurpose>
</refnamediv>
<refsynopsisdiv>
@@ -613,8 +641,8 @@
<funcsynopsis>
<funcprototype>
<funcdef>geometry <function>ST_Point</function></funcdef>
- <paramdef><type>float </type> <parameter>x_lon</parameter></paramdef>
- <paramdef><type>float </type> <parameter>y_lat</parameter></paramdef>
+ <paramdef><type>float</type> <parameter>x</parameter></paramdef>
+ <paramdef><type>float</type> <parameter>y</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
@@ -622,8 +650,9 @@
<refsection>
<title>Description</title>
- <para>Returns an Point with the given coordinate values. SQL-MM alias for ST_MakePoint that takes just an x and y.</para>
+ <para>Returns an Point with the given X and Y coordinate values. This is the SQL-MM alias for <xref linkend="ST_MakePoint" /> that takes just X and Y.</para>
+ <note><para>For geodetic coordinates, <varname>X</varname> is longitude and <varname>Y</varname> is latitude</para></note>
<para>&sqlmm_compliant; SQL-MM 3: 6.1.2</para>
@@ -633,19 +662,24 @@
<refsection>
<title>Examples: Geometry</title>
- <programlisting>SELECT ST_SetSRID(ST_Point(-71.1043443253471, 42.3150676015829),4326)</programlisting>
+ <programlisting>SELECT ST_SetSRID( ST_Point( -71.104, 42.315), 4326)</programlisting>
</refsection>
<refsection>
<title>Examples: Geography</title>
- <programlisting>SELECT CAST(ST_SetSRID(ST_Point(-71.1043443253471, 42.3150676015829),4326) As geography);</programlisting>
- <programlisting>-- the :: is PostgreSQL short-hand for casting.
-SELECT ST_SetSRID(ST_Point(-71.1043443253471, 42.3150676015829),4326)::geography;</programlisting>
+ <programlisting>SELECT CAST(ST_SetSRID( ST_Point( -71.104, 42.315), 4326) AS geography);</programlisting>
- <programlisting>--If your point coordinates are in a different spatial reference from WGS-84 long lat, then you need to transform before casting
--- This example we convert a point in Pennsylvania State Plane feet to WGS 84 and then geography
-SELECT ST_Transform(ST_SetSRID(ST_Point(3637510, 3014852),2273),4326)::geography;</programlisting>
+ <para>PostgreSQL also provides the <varname>::</varname> short-hand for casting</para>
+ <programlisting>
+SELECT ST_SetSRID( ST_Point( -71.104, 42.315), 4326)::geography;</programlisting>
+
+<para>If the point coordinates are not in a geodetic coordinate system (such as WGS84),
+then they must be reprojected before casting to a geography.
+In this example a point in Pennsylvania State Plane feet (SRID 2273)
+is projected to WGS84 (SRID 4326).</para>
+<programlisting>
+SELECT ST_Transform(ST_SetSRID( ST_Point( 3637510, 3014852 ), 2273), 4326)::geography;</programlisting>
</refsection>
<!-- Optionally add a "See Also" section -->
@@ -660,7 +694,7 @@
<refnamediv>
<refname>ST_Polygon</refname>
- <refpurpose>Creates a Polygon from a LineString, with a specified SRID.</refpurpose>
+ <refpurpose>Creates a Polygon from a LineString with a specified SRID.</refpurpose>
</refnamediv>
<refsynopsisdiv>
@@ -667,7 +701,7 @@
<funcsynopsis>
<funcprototype>
<funcdef>geometry <function>ST_Polygon</function></funcdef>
- <paramdef><type>geometry </type> <parameter>aLineString</parameter></paramdef>
+ <paramdef><type>geometry </type> <parameter>lineString</parameter></paramdef>
<paramdef><type>integer </type> <parameter>srid</parameter></paramdef>
</funcprototype>
</funcsynopsis>
@@ -676,12 +710,17 @@
<refsection>
<title>Description</title>
- <para>Returns a polygon built from the specified linestring and SRID.</para>
+ <para>Returns a polygon built from the given LineString
+ and sets the spatial reference system from the <varname>srid</varname>.</para>
- <!-- optionally mention that this function uses indexes if appropriate -->
- <note>
- <para>ST_Polygon is similar to first version of ST_MakePolygon except it also sets the spatial ref sys (SRID) of the polygon. Will not work with MULTILINESTRINGS
- so use LineMerge to merge multilines. Also does not create polygons with holes. Use ST_MakePolygon for that.</para>
+ <para>ST_Polygon is similar to <xref linkend="ST_MakePolygon" /> Variant 1
+ with the addition of setting the SRID.</para>
+ <para>To create polygons with holes
+ use <xref linkend="ST_MakePolygon" /> Variant 2 and then <xref linkend="ST_SetSRID" />.
+ </para>
+
+ <note><para>This function does not accept MultiLineStrings.
+ Use <xref linkend="ST_LineMerge" /> to generate a LineString, or <xref linkend="ST_Dump" /> to extract LineStrings.</para>
</note>
<para>&sfs_compliant;</para>
@@ -690,23 +729,23 @@
</refsection>
-
<refsection>
<title>Examples</title>
+<para>Create a 2D polygon.</para>
<programlisting>
---a 2d polygon
-SELECT ST_Polygon(ST_GeomFromText('LINESTRING(75.15 29.53,77 29,77.6 29.5, 75.15 29.53)'), 4326);
+SELECT ST_AsText( ST_Polygon('LINESTRING(75 29, 77 29, 77 29, 75 29)'::geometry, 4326) );
---result--
-POLYGON((75.15 29.53,77 29,77.6 29.5,75.15 29.53))
---a 3d polygon
-SELECT ST_AsEWKT(ST_Polygon(ST_GeomFromEWKT('LINESTRING(75.15 29.53 1,77 29 1,77.6 29.5 1, 75.15 29.53 1)'), 4326));
+-- result --
+POLYGON((75 29, 77 29, 77 29, 75 29))
+</programlisting>
+<para>Create a 3D polygon.</para>
+<programlisting>
+SELECT ST_AsEWKT( ST_Polygon( ST_GeomFromEWKT('LINESTRING(75 29 1, 77 29 2, 77 29 3, 75 29 1)'), 4326) );
-result
-------
-SRID=4326;POLYGON((75.15 29.53 1,77 29 1,77.6 29.5 1,75.15 29.53 1))
- </programlisting>
+-- result --
+SRID=4326;POLYGON((75 29 1, 77 29 2, 77 29 3, 75 29 1))
+</programlisting>
</refsection>
<!-- Optionally add a "See Also" section -->
More information about the postgis-tickets
mailing list