<title>See Also</title>
<para><xref linkend="ST_BuildArea" />, <xref linkend="ST_BdPolyFromText" /></para>
</refsection>
- </refentry>
-
- <refentry id="ST_Buffer">
- <refnamediv>
- <refname>ST_Buffer</refname>
-
- <refpurpose>Returns a geometry that represents all points whose distance
- from this Geometry is less than or equal to distance. Calculations
- are in the Spatial Reference System of this Geometry. The optional
- third parameter sets the number of segments used to approximate a
- quarter circle (defaults to 8).</refpurpose>
- </refnamediv>
-
- <refsynopsisdiv>
- <funcsynopsis>
- <funcprototype>
- <funcdef>geometry <function>ST_Buffer</function></funcdef>
- <paramdef><type>geometry </type> <parameter>g1</parameter></paramdef>
- <paramdef><type>float </type> <parameter>radius_of_buffer</parameter></paramdef>
- </funcprototype>
-
- <funcprototype>
- <funcdef>geometry <function>ST_Buffer</function></funcdef>
- <paramdef><type>geometry </type> <parameter>g1</parameter></paramdef>
- <paramdef><type>float </type> <parameter>radius_of_buffer</parameter></paramdef>
- <paramdef><type>integer </type> <parameter>num_seg_quarter_circle</parameter></paramdef>
- </funcprototype>
-
- </funcsynopsis>
- </refsynopsisdiv>
-
- <refsection>
- <title>Description</title>
-
- <para>Returns a geometry that represents all points whose distance
- from this Geometry is less than or equal to distance. Calculations
- are in the Spatial Reference System of this Geometry. The optional
- third parameter sets the number of segments used to approximate a
- quarter circle (defaults to 8).
- </para>
- <para>Units are always measured in units of the spatial reference system.</para>
- <para>The inputs can be POINTS, MULTIPOINTS, LINESTRINGS, MULTILINESTRINGS, POLYGONS, MULTIPOLYGONS, and GeometryCollections.</para>
- <note><para>This function ignores the third dimension (z) and will always give a 2-d buffer even when presented with a 3d-geometry.</para></note>
-
- <para>Performed by the GEOS module.</para>
-
- <!-- Optionally mention OpenGIS compliancy if appropriate -->
- <para><inlinemediaobject>
- <imageobject>
- <imagedata fileref="images/check.png" />
- </imageobject>
- </inlinemediaobject> This method implements the <ulink
- url="http://www.opengeospatial.org/standards/sfs">OpenGIS Simple Features
- Implementation Specification for SQL.</ulink>
- OGC SPEC s2.1.1.3</para>
-
- <!-- Optionally mention SQL/MM compliancy if appropriate -->
- <para><inlinemediaobject>
- <imageobject>
- <imagedata fileref="images/check.png" />
- </imageobject>
- </inlinemediaobject> This method implements the SQL/MM specification:
- SQL-MM 3: 5.1.17</para>
-
- <note><para>People often make the mistake of using this function to try to do radius searches. Creating a
- buffer to to a radius search is slow and pointless. Use <xref linkend="ST_DWithin" /> instead.</para></note>
- </refsection>
-
- <refsection>
- <title>Examples</title>
-
-<programlisting>--A buffered point approximates a circle
--- A buffered point forcing approximation of
--- 4 points per circle is poly with 16 sides
-SELECT ST_NPoints(ST_Buffer(ST_GeomFromText('POINT(1 2)'), 10)) As promisingcircle_pcount,
-ST_NPoints(ST_Buffer(ST_GeomFromText('POINT(1 2)'), 10, 4)) As lamecircle_pcount;
-
-promisingcircle_pcount | lamecircle_pcount
-------------------------+-------------------
- 33 | 17
-
---A lighter but lamer circle
--- only 2 points per quarter circle is an octagon
---Below is a 100 meter octagon
--- Note coordinates are in NAD 83 long lat which we transform
-to Mass state plane meter and then buffer to get measurements in meters;
-SELECT ST_AsText(ST_Buffer(
-ST_Transform(
-ST_SetSRID(ST_MakePoint(-71.063526, 42.35785),4269), 26986)
-,100,2)) As octagon;
-----------------------
-POLYGON((236057.59057465 900908.759918696,236028.301252769 900838.049240578,235
-957.59057465 900808.759918696,235886.879896532 900838.049240578,235857.59057465
-900908.759918696,235886.879896532 900979.470596815,235957.59057465 901008.759918
-696,236028.301252769 900979.470596815,236057.59057465 900908.759918696))
-
---Buffer is often also used as a poor man's polygon fixer or a sometimes speedier unioner
---Sometimes able to fix invalid polygons - using below
--- using below on anything but a polygon will result in empty geometry
--- and for geometry collections kill anything in the collection that is not a polygon
---Poor man's bad poly fixer
-SELECT ST_IsValid(foo.invalidpoly) as isvalid, ST_IsValid(ST_Buffer(foo.invalidpoly,0.0)) as bufferisvalid,
-ST_AsText(ST_Buffer(foo.invalidpoly,0.0)) As newpolytextrep
-FROM (SELECT ST_GeomFromText('POLYGON((-1 2, 3 4, 5 6, -1 2, 5 6, -1 2))') as invalidpoly) As foo
-NOTICE: Self-intersection at or near point -1 2
-isvalid | bufferisvalid | newpolytextrep
----------+---------------+------------------------------
-f | t | POLYGON((-1 2,5 6,3 4,-1 2))
-
---Poor man's polygon unioner
-SELECT ST_AsText(the_geom) as textorig, ST_AsText(ST_Buffer(foo.the_geom,0.0)) As textbuffer
-FROM (SELECT ST_Collect('POLYGON((-1 2, 3 4, 5 6, -1 2))', 'POLYGON((-1 2, 2 3, 5 6, -1 2))') As the_geom) as foo;
- textorig | textbuffer
------------------------------------------------------------+--------------------
-MULTIPOLYGON(((-1 2,3 4,5 6,-1 2)),((-1 2,2 3,5 6,-1 2))) | POLYGON((-1 2,5 6,3 4,2 3,-1 2))
-
-
- </programlisting>
- </refsection>
-
- <refsection>
- <title>See Also</title>
-
- <para><xref linkend="ST_Collect" />, <xref linkend="ST_DWithin" />, <xref linkend="ST_SetSRID" />, <xref linkend="ST_Transform" />, <xref linkend="ST_Union" /></para>
- </refsection>
- </refentry>
-
- <refentry id="ST_BuildArea">
- <refnamediv>
- <refname>ST_BuildArea</refname>
-
- <refpurpose>Creates an areal geometry formed by the constituent linework
- of given geometry</refpurpose>
- </refnamediv>
-
- <refsynopsisdiv>
- <funcsynopsis>
- <funcprototype>
- <funcdef>boolean <function>ST_BuildArea</function></funcdef>
- <paramdef><type>geometry </type> <parameter>A</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- </refsynopsisdiv>
-
- <refsection>
- <title>Description</title>
-
- <para>Creates an areal geometry formed by the constituent linework
- of given geometry. The return type can be a Polygon or
- MultiPolygon, depending on input. If the input lineworks do not
- form polygons NULL is returned. The inputs can be LINESTRINGS, MULTILINESTRINGS, POLYGONS, MULTIPOLYGONS, and GeometryCollections.
- </para>
- <para>This function will assume all inner geometries represent holes</para>
- <para>Availability: 1.1.0 - requires GEOS >= 2.1.0.</para>
- </refsection>
-
- <refsection>
- <title>Examples</title>
-
- <programlisting>--This will create a donut
-SELECT ST_BuildArea(ST_Collect(smallc,bigc))
-FROM (SELECT ST_Buffer(ST_GeomFromText('POINT(1 2)'), 10) As smallc,
- ST_Buffer(ST_GeomFromText('POINT(1 2)'), 20) As bigc) As foo
-
---This will create a gaping hole
---inside the circle with prongs sticking out
-SELECT ST_BuildArea(ST_Collect(line,circle))
-FROM (SELECT ST_Buffer(ST_MakeLine(ST_MakePoint(21, 22),ST_MakePoint(-19, -18)),1) As line,
- ST_Buffer(ST_GeomFromText('POINT(1 2)'), 20) As circle) As foo;
-
---this creates the same gaping hole
---but using linestrings instead of polygons
-SELECT ST_AsBinary(ST_BuildArea(ST_Collect(ST_ExteriorRing(line),ST_ExteriorRing(circle))))
-FROM (SELECT ST_Buffer(ST_MakeLine(ST_MakePoint(21, 22),ST_MakePoint(-19, -18)),1) As line,
- ST_Buffer(ST_GeomFromText('POINT(1 2)'), 20) As circle) As foo</programlisting>
- </refsection>
-
- <refsection>
- <title>See Also</title>
-
- <para>
- <xref linkend="ST_BdPolyFromText" />,
- <xref linkend="ST_BdMPolyFromText" />wrappers to
- this function with standard OGC interface</para>
- </refsection>
</refentry>
- <refentry id="ST_Collect">
+
+ <refentry id="ST_GeomFromEWKB">
<refnamediv>
- <refname>ST_Collect</refname>
- <refpurpose>Return a specified ST_Geometry value from a collection of other geometries.</refpurpose>
+ <refname>ST_GeomFromEWKB</refname>
+ <refpurpose>Return a specified ST_Geometry value from Extended Well-Known Binary representation (EWKB).</refpurpose>
</refnamediv>
<refsynopsisdiv>
<funcsynopsis>
<funcprototype>
- <funcdef>geometry <function>ST_Collect</function></funcdef>
- <paramdef><type>geometry set</type> <parameter>g1field</parameter></paramdef>
- </funcprototype>
- <funcprototype>
- <funcdef>geometry <function>ST_Collect</function></funcdef>
- <paramdef><type>geometry</type> <parameter>g1</parameter></paramdef>
- <paramdef><type>geometry</type> <parameter>g2</parameter></paramdef>
+ <funcdef>geometry <function>ST_GeomFromEWKB</function></funcdef>
+ <paramdef><type>bytea </type> <parameter>EWKB</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsection>
<title>Description</title>
- <para> Output type can be a MULTI* or a
- GEOMETRYCOLLECTION. Comes in 2 variants. Variant 1 collects 2 geometries. Variant 2 is an aggregate function that takes a set of geometries and collects
- them into a single ST_Geometry.</para>
-
- <para>Aggregate version: This function returns a GEOMETRYCOLLECTION or a MULTI object
- from a set of geometries. The ST_Collect() 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" will return a separate GEOMETRYCOLLECTION for
- each distinct value of ATTRCOLUMN.</para>
-
- <para>Non-Aggregate version: This function returns a geometry being a collection of two
- input geometries. Output type can be a MULTI* or a
- GEOMETRYCOLLECTION.</para>
-
- <note><para>ST_Collect and ST_Union are often interchangeable.
- ST_Collect is in general orders of magnitude faster than ST_Union
- because it does not try to dissolve boundaries or validate that a constructed MultiPolgon doesn't
- have overlapping regions. It merely rolls up
- single geometries into MULTI and MULTI or mixed geometry types
- into Geometry Collections. Unfortunately geometry collections are
- not well-supported by GIS tools. To prevent ST_Collect from
- returning a Geometry Collection when collecting MULTI geometries,
- one can use the below trick that utilizes <xref linkend="ST_Dump" /> to expand the
- MULTIs out to singles and then regroup them.</para></note>
- </refsection>
-
- <refsection>
- <title>Examples</title>
- <para>Aggregate example</para>
- <programlisting>Thread ref: http://postgis.refractions.net/pipermail/postgis-users/2008-June/020331.html
-SELECT stusps,
- ST_Multi(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>Thread ref: http://postgis.refractions.net/pipermail/postgis-users/2008-June/020331.html
-SELECT ST_AsText(ST_Collect(ST_GeomFromText('POINT(1 2)'),
- ST_GeomFromText('POINT(-2 3)') ));
-
-st_astext
-----------
-MULTIPOINT(1 2,-2 3)
-
-SELECT ST_AsText(ST_Collect(ST_GeomFromText('POINT(1 2)'),
- ST_GeomFromText('POINT(1 2)') ) );
-
-st_astext
-----------
-MULTIPOINT(1 2,1 2)</programlisting>
- </refsection>
- <refsection>
- <title>See Also</title>
- <para><xref linkend="ST_Dump" />, <xref linkend="ST_Union" /></para>
- </refsection>
- </refentry>
-
- <refentry id="ST_Dump">
- <refnamediv>
- <refname>ST_Dump</refname>
- <refpurpose>Returns a set of
- geometry_dump rows, formed by a geometry (geom).</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>This is a set-returning function (SRF). It returns a set of
- geometry_dump rows, formed by a geometry (geom) and an array of
- integers (path). When the input geometry is a simple type
- (POINT,LINESTRING,POLYGON) a single record will be returned with
- an empty path array and the input geometry as geom. When the input
- geometry is a collection or multi it will return a record for each
- of the collection components, and the path will express the
- position of the component inside the collection.</para>
-
- <para>ST_Dump is useful for expanding geometries. It is the
- reverse of a GROUP BY in that it creates new rows. For example it
- can be use to expand MULTIPOLYGONS into POLYGONS.</para>
-
- <para>Availability: PostGIS 1.0.0RC1. Requires PostgreSQL 7.3 or
- higher.</para>
- </refsection>
-
- <refsection>
- <title>Examples</title>
- <programlisting>SELECT sometable.field1, sometable.field1,
- (ST_Dump(sometable.the_geom)).geom As the_geom
-FROM sometable</programlisting>
- </refsection>
- <refsection>
- <title>See Also</title>
- <para><xref linkend="ST_Collect" /></para>
- </refsection>
- </refentry>
-
- <refentry id="ST_GeomFromEWKB">
- <refnamediv>
- <refname>ST_GeomFromEWKB</refname>
- <refpurpose>Return a specified ST_Geometry value from Extended Well-Known Binary representation (EWKB).</refpurpose>
- </refnamediv>
-
- <refsynopsisdiv>
- <funcsynopsis>
- <funcprototype>
- <funcdef>geometry <function>ST_GeomFromEWKB</function></funcdef>
- <paramdef><type>bytea </type> <parameter>EWKB</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- </refsynopsisdiv>
-
- <refsection>
- <title>Description</title>
- <para>Constructs a PostGIS ST_Geometry object from the OGC Extended Well-Known binary (EWKT) representation.</para>
- <note>
- <para>The EWKB format is not an OGC standard, but a PostGIS specific format that includes the spatial reference system (SRID)
- identifier</para>
- </note>
+ <para>Constructs a PostGIS ST_Geometry object from the OGC Extended Well-Known binary (EWKT) representation.</para>
+ <note>
+ <para>The EWKB format is not an OGC standard, but a PostGIS specific format that includes the spatial reference system (SRID)
+ identifier</para>
+ </note>
</refsection>
<refsection>
<para><xref linkend="ST_AsEWKT" />, <xref linkend="ST_MakePoint" />, <xref linkend="ST_SetSRID" /></para>
</refsection>
</refentry>
-
- <refentry id="ST_MakePolygon">
- <refnamediv>
- <refname>ST_MakePolygon</refname>
-
- <refpurpose>Creates a Polygon formed by the given shell. Input
- geometries must be closed LINESTRINGS.</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 ST_Accum or the PostgreSQL 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>
-
- </refsection>
-
- <refsection>
- <title>Examples: Single closed LINESTRING</title>
- <programlisting>
-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
- </programlisting>
- </refsection>
- <refsection>
- <title>Examples: Outter 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 line strings
- this is an example of using PostGIS ST_Accum
- <note><para>The use of CASE because feeding a null array into
- ST_MakePolygon results in NULL</para></note>
- <note><para>the use of left join 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
- ST_Accum(w.the_geom) IS NULL THEN p.the_geom
- ELSE ST_MakePolygon(ST_LineMerge(ST_Boundary(p.the_geom)), ST_Accum(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_Accum" />, <xref linkend="ST_AddPoint" />, <xref linkend="ST_GeometryType" />, <xref linkend="ST_IsClosed" />, <xref linkend="ST_LineMerge" /></para>
- </refsection>
- </refentry>
+
<refentry id="ST_PointFromText">
<refnamediv>
<refname>ST_PointFromText</refname>
<para><xref linkend="ST_GeomFromText" />, <xref linkend="ST_MakePoint" />, <xref linkend="ST_SRID" /></para>
</refsection>
</refentry>
- <refentry id="ST_Union">
- <refnamediv>
- <refname>ST_Union</refname>
- <refpurpose>Returns a geometry that represents the point set union of
- the Geometries.</refpurpose>
- </refnamediv>
-
- <refsynopsisdiv>
- <funcsynopsis>
- <funcprototype>
- <funcdef>geometry <function>ST_Union</function></funcdef>
- <paramdef><type>geometry set</type> <parameter>g1field</parameter></paramdef>
- </funcprototype>
- <funcprototype>
- <funcdef>geometry <function>ST_Union</function></funcdef>
- <paramdef><type>geometry</type> <parameter>g1</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- </refsynopsisdiv>
- <refsection>
- <title>Description</title>
- <para> Output type can be a MULTI* , single geometry, or Geometry Collection. Comes in 2 variants. Variant 1 unions 2 geometries resulting in a new geomety with no intersecting regions.
- Variant 2 is an aggregate function that takes a set of geometries and unions
- them into a single ST_Geometry resulting in no intersecting regions.</para>
-
- <para>Aggregate version: This function returns a MULTI geometry or NON-MULTI geometry
- from a set of geometries. The ST_Union() 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.</para>
-
- <para>Non-Aggregate version: This function returns a geometry being a union of two
- input geometries. Output type can be a MULTI* ,NON-MULTI or
- GEOMETRYCOLLECTION.</para>
-
- <note><para>ST_Collect and ST_Union are often interchangeable.
- ST_Union is in general orders of magnitude slower than ST_Collect
- because it tries to dissolve boundaries and reorder geometries to ensure that a constructed Multi* doesn't
- have intersecting regions.</para></note>
-
- <para>Performed by the GEOS module.</para>
- <para>NOTE: this function was formerly called GeomUnion(), which
- was renamed from "Union" because UNION is an SQL reserved
- word.</para>
-
- <para><inlinemediaobject>
- <imageobject>
- <imagedata fileref="images/check.png" />
- </imageobject>
- </inlinemediaobject> This method implements the <ulink
- url="http://www.opengeospatial.org/standards/sfs">OpenGIS Simple Features
- Implementation Specification for SQL: OGC SPEC s2.1.1.3</ulink></para>
-
- <para><inlinemediaobject>
- <imageobject>
- <imagedata fileref="images/check.png" />
- </imageobject>
- </inlinemediaobject> This method implements the SQL/MM specification:
- SQL-MM 3: 5.1.19</para>
-
- <note><para>Aggregate version is not explicitly defined in OGC SPEC.</para></note>
- </refsection>
-
- <refsection>
- <title>Examples</title>
- <para>Aggregate example</para>
- <programlisting>
-SELECT stusps,
- ST_Multi(ST_Union(f.the_geom)) as singlegeom
- FROM sometable As f
-GROUP BY stusps
- </programlisting>
- <para>Non-Aggregate example</para>
- <programlisting>
-SELECT ST_AsText(ST_Union(ST_GeomFromText('POINT(1 2)'),
- ST_GeomFromText('POINT(-2 3)') ) )
-
-st_astext
-----------
-MULTIPOINT(-2 3,1 2)
-
-
-SELECT ST_AsText(ST_Union(ST_GeomFromText('POINT(1 2)'),
- ST_GeomFromText('POINT(1 2)') ) );
-st_astext
-----------
-POINT(1 2)
- </programlisting>
- </refsection>
- <refsection>
- <title>See Also</title>
- <para><xref linkend="ST_Collect" /></para>
- </refsection>
- </refentry>
- <refentry id="ST_WKTToSQL">
- <refnamediv>
- <refname>ST_WKTToSQL</refname>
- <refpurpose>Return a specified ST_Geometry value from Well-Known Text representation (WKT). This is an alias name for ST_GeomFromText</refpurpose>
- </refnamediv>
- <refsynopsisdiv>
- <funcsynopsis>
- <funcprototype>
- <funcdef>geometry <function>ST_WKTToSQL</function></funcdef>
- <paramdef><type>text </type> <parameter>WKT</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- </refsynopsisdiv>
- <refsection>
- <title>Description</title>
- <!-- Optionally mention OpenGIS compliancy if appropriate -->
+ <refentry id="ST_WKTToSQL">
+ <refnamediv>
+ <refname>ST_WKTToSQL</refname>
+ <refpurpose>Return a specified ST_Geometry value from Well-Known Text representation (WKT). This is an alias name for ST_GeomFromText</refpurpose>
+ </refnamediv>
+ <refsynopsisdiv>
+ <funcsynopsis>
+ <funcprototype>
+ <funcdef>geometry <function>ST_WKTToSQL</function></funcdef>
+ <paramdef><type>text </type> <parameter>WKT</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ </refsynopsisdiv>
+ <refsection>
+ <title>Description</title>
+ <!-- Optionally mention OpenGIS compliancy if appropriate -->
<para><inlinemediaobject>
<imageobject>
<imagedata fileref="images/check.png" />
<sect1>
<title>Geometry Processing Functions</title>
- <refentry id="ST_Intersection">
+ <refentry id="ST_Buffer">
<refnamediv>
- <refname>ST_Intersection</refname>
-
- <refpurpose>Returns a geometry that represents the shared portion of geomA and geomB
- </refpurpose>
+ <refname>ST_Buffer</refname>
+
+ <refpurpose>Returns a geometry that represents all points whose distance
+ from this Geometry is less than or equal to distance. Calculations
+ are in the Spatial Reference System of this Geometry. The optional
+ third parameter sets the number of segments used to approximate a
+ quarter circle (defaults to 8).</refpurpose>
</refnamediv>
+
<refsynopsisdiv>
<funcsynopsis>
- <funcprototype>
- <funcdef>geometry <function>ST_Intersection</function></funcdef>
- <paramdef>
- <type>geometry</type>
- <parameter>geomA</parameter>
- </paramdef>
- <paramdef>
- <type>geometry</type>
- <parameter>geomB</parameter>
- </paramdef>
- </funcprototype>
+ <funcprototype>
+ <funcdef>geometry <function>ST_Buffer</function></funcdef>
+ <paramdef><type>geometry </type> <parameter>g1</parameter></paramdef>
+ <paramdef><type>float </type> <parameter>radius_of_buffer</parameter></paramdef>
+ </funcprototype>
+
+ <funcprototype>
+ <funcdef>geometry <function>ST_Buffer</function></funcdef>
+ <paramdef><type>geometry </type> <parameter>g1</parameter></paramdef>
+ <paramdef><type>float </type> <parameter>radius_of_buffer</parameter></paramdef>
+ <paramdef><type>integer </type> <parameter>num_seg_quarter_circle</parameter></paramdef>
+ </funcprototype>
+
</funcsynopsis>
</refsynopsisdiv>
- <refsection>
+
+ <refsection>
<title>Description</title>
- <para>Returns a geometry that represents the point set
- intersection of the Geometries.</para>
-
- <para>In other words - that portion of geometry A and geometry B
- that is shared between the two geometries.</para>
-
- <para>If the geometries do not share any space (are disjoint), then an empty geometry collection
- is returned.</para>
- <para>ST_Intersection in conjunction with ST_Intersects is very useful for clipping geometries such as in bounding box, buffer, region
- queries where you only want to return that portion of a geometry that sits in a country or region of interest.</para>
-
- <important>
- <para>Do not call with a <varname>GEOMETRYCOLLECTION</varname> as an argument</para>
- </important>
-
- <para>Performed by the GEOS module</para>
-
-
- <para>
- <inlinegraphic fileref="images/check.png" />
- This method implements the
- <ulink url="http://www.opengeospatial.org/standards/sfs">OpenGIS Simple
- Features Implementation Specification for SQL</ulink> OGC SPEC s2.1.1.3
+
+ <para>Returns a geometry that represents all points whose distance
+ from this Geometry is less than or equal to distance. Calculations
+ are in the Spatial Reference System of this Geometry. The optional
+ third parameter sets the number of segments used to approximate a
+ quarter circle (defaults to 8).
</para>
+ <para>Units are always measured in units of the spatial reference system.</para>
+ <para>The inputs can be POINTS, MULTIPOINTS, LINESTRINGS, MULTILINESTRINGS, POLYGONS, MULTIPOLYGONS, and GeometryCollections.</para>
+ <note><para>This function ignores the third dimension (z) and will always give a 2-d buffer even when presented with a 3d-geometry.</para></note>
+
+ <para>Performed by the GEOS module.</para>
+
+ <!-- Optionally mention OpenGIS compliancy if appropriate -->
+ <para><inlinemediaobject>
+ <imageobject>
+ <imagedata fileref="images/check.png" />
+ </imageobject>
+ </inlinemediaobject> This method implements the <ulink
+ url="http://www.opengeospatial.org/standards/sfs">OpenGIS Simple Features
+ Implementation Specification for SQL.</ulink>
+ OGC SPEC s2.1.1.3</para>
<!-- Optionally mention SQL/MM compliancy if appropriate -->
<para><inlinemediaobject>
<imageobject>
<imagedata fileref="images/check.png" />
</imageobject>
- </inlinemediaobject> This method implements the SQL/MM specification: SQL-MM 3: 5.1.18</para>
+ </inlinemediaobject> This method implements the SQL/MM specification:
+ SQL-MM 3: 5.1.17</para>
+
+ <note><para>People often make the mistake of using this function to try to do radius searches. Creating a
+ buffer to to a radius search is slow and pointless. Use <xref linkend="ST_DWithin" /> instead.</para></note>
</refsection>
- <refsection>
+
+ <refsection>
+ <title>Examples</title>
+
+<programlisting>--A buffered point approximates a circle
+-- A buffered point forcing approximation of
+-- 4 points per circle is poly with 16 sides
+SELECT ST_NPoints(ST_Buffer(ST_GeomFromText('POINT(1 2)'), 10)) As promisingcircle_pcount,
+ST_NPoints(ST_Buffer(ST_GeomFromText('POINT(1 2)'), 10, 4)) As lamecircle_pcount;
+
+promisingcircle_pcount | lamecircle_pcount
+------------------------+-------------------
+ 33 | 17
+
+--A lighter but lamer circle
+-- only 2 points per quarter circle is an octagon
+--Below is a 100 meter octagon
+-- Note coordinates are in NAD 83 long lat which we transform
+to Mass state plane meter and then buffer to get measurements in meters;
+SELECT ST_AsText(ST_Buffer(
+ST_Transform(
+ST_SetSRID(ST_MakePoint(-71.063526, 42.35785),4269), 26986)
+,100,2)) As octagon;
+----------------------
+POLYGON((236057.59057465 900908.759918696,236028.301252769 900838.049240578,235
+957.59057465 900808.759918696,235886.879896532 900838.049240578,235857.59057465
+900908.759918696,235886.879896532 900979.470596815,235957.59057465 901008.759918
+696,236028.301252769 900979.470596815,236057.59057465 900908.759918696))
+
+--Buffer is often also used as a poor man's polygon fixer or a sometimes speedier unioner
+--Sometimes able to fix invalid polygons - using below
+-- using below on anything but a polygon will result in empty geometry
+-- and for geometry collections kill anything in the collection that is not a polygon
+--Poor man's bad poly fixer
+SELECT ST_IsValid(foo.invalidpoly) as isvalid, ST_IsValid(ST_Buffer(foo.invalidpoly,0.0)) as bufferisvalid,
+ST_AsText(ST_Buffer(foo.invalidpoly,0.0)) As newpolytextrep
+FROM (SELECT ST_GeomFromText('POLYGON((-1 2, 3 4, 5 6, -1 2, 5 6, -1 2))') as invalidpoly) As foo
+NOTICE: Self-intersection at or near point -1 2
+isvalid | bufferisvalid | newpolytextrep
+---------+---------------+------------------------------
+f | t | POLYGON((-1 2,5 6,3 4,-1 2))
+
+--Poor man's polygon unioner
+SELECT ST_AsText(the_geom) as textorig, ST_AsText(ST_Buffer(foo.the_geom,0.0)) As textbuffer
+FROM (SELECT ST_Collect('POLYGON((-1 2, 3 4, 5 6, -1 2))', 'POLYGON((-1 2, 2 3, 5 6, -1 2))') As the_geom) as foo;
+ textorig | textbuffer
+-----------------------------------------------------------+--------------------
+MULTIPOLYGON(((-1 2,3 4,5 6,-1 2)),((-1 2,2 3,5 6,-1 2))) | POLYGON((-1 2,5 6,3 4,2 3,-1 2))
+
+
+ </programlisting>
+ </refsection>
+
+ <refsection>
+ <title>See Also</title>
+
+ <para><xref linkend="ST_Collect" />, <xref linkend="ST_DWithin" />, <xref linkend="ST_SetSRID" />, <xref linkend="ST_Transform" />, <xref linkend="ST_Union" /></para>
+ </refsection>
+ </refentry>
+
+ <refentry id="ST_BuildArea">
+ <refnamediv>
+ <refname>ST_BuildArea</refname>
+
+ <refpurpose>Creates an areal geometry formed by the constituent linework
+ of given geometry</refpurpose>
+ </refnamediv>
+
+ <refsynopsisdiv>
+ <funcsynopsis>
+ <funcprototype>
+ <funcdef>boolean <function>ST_BuildArea</function></funcdef>
+ <paramdef><type>geometry </type> <parameter>A</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ </refsynopsisdiv>
+
+ <refsection>
+ <title>Description</title>
+
+ <para>Creates an areal geometry formed by the constituent linework
+ of given geometry. The return type can be a Polygon or
+ MultiPolygon, depending on input. If the input lineworks do not
+ form polygons NULL is returned. The inputs can be LINESTRINGS, MULTILINESTRINGS, POLYGONS, MULTIPOLYGONS, and GeometryCollections.
+ </para>
+ <para>This function will assume all inner geometries represent holes</para>
+ <para>Availability: 1.1.0 - requires GEOS >= 2.1.0.</para>
+ </refsection>
+
+ <refsection>
<title>Examples</title>
-<programlisting>SELECT ST_AsText(ST_Intersection('POINT(0 0)'::geometry, 'LINESTRING ( 2 0, 0 2 )'::geometry));
- st_astext
- ---------------
- GEOMETRYCOLLECTION EMPTY
- (1 row)
- SELECT ST_AsText(ST_Intersection('POINT(0 0)'::geometry, 'LINESTRING ( 0 0, 0 2 )'::geometry));
- st_astext
- ---------------
- POINT(0 0)
- (1 row)
+
+ <programlisting>--This will create a donut
+SELECT ST_BuildArea(ST_Collect(smallc,bigc))
+FROM (SELECT ST_Buffer(ST_GeomFromText('POINT(1 2)'), 10) As smallc,
+ ST_Buffer(ST_GeomFromText('POINT(1 2)'), 20) As bigc) As foo
- ---Clip all lines (trails) by country (here we assume country geom are POLYGON or MULTIPOLYGONS)
- -- NOTE: we are only keeping intersections that result in a LINESTRING or MULTILINESTRING because we don't
- -- care about trails that just share a point
- -- the dump is needed to expand a geometry collection into individual single MULT* parts
- -- the below is fairly generic and will work for polys, etc. by just changing the where clause
- SELECT clipped.gid, clipped.f_name, clipped_geom
- FROM (SELECT trails.gid, trails.f_name, (ST_Dump(ST_Intersection(country.the_geom, trails.the_geom))).geom As clipped_geom
- FROM country
- INNER JOIN trails
- ON ST_Intersects(country.the_geom, trails.the_geom)) As clipped
- WHERE ST_Dimension(clipped.clipped_geom) = 1 ;
-
- --For polys e.g. polygon landmarks, you can also use the sometimes faster hack that buffering anything by 0.0
- -- except a polygon results in an empty geometry collection
- --(so a geometry collection containing polys, lines and points)
- -- buffered by 0.0 would only leave the polygons and dissolve the collection shell
- SELECT poly.gid, ST_Multi(ST_Buffer(
- ST_Intersection(country.the_geom, poly.the_geom),
- 0.0)
- ) As clipped_geom
- FROM country
- INNER JOIN poly
- ON ST_Intersects(country.the_geom, poly.the_geom)
- WHERE Not ST_IsEmpty(ST_Buffer(ST_Intersection(country.the_geom, poly.the_geom),0.0));
- </programlisting>
- </refsection>
- <refsection>
- <title>See Also</title>
- <para><xref linkend="ST_Dimension"/>, <xref linkend="ST_Dump"/>, <xref linkend="ST_Intersects"/>, <xref linkend="ST_Multi"/></para>
- </refsection>
- </refentry>
- </sect1>
+--This will create a gaping hole
+--inside the circle with prongs sticking out
+SELECT ST_BuildArea(ST_Collect(line,circle))
+FROM (SELECT ST_Buffer(ST_MakeLine(ST_MakePoint(21, 22),ST_MakePoint(-19, -18)),1) As line,
+ ST_Buffer(ST_GeomFromText('POINT(1 2)'), 20) As circle) As foo;
+
+--this creates the same gaping hole
+--but using linestrings instead of polygons
+SELECT ST_AsBinary(ST_BuildArea(ST_Collect(ST_ExteriorRing(line),ST_ExteriorRing(circle))))
+FROM (SELECT ST_Buffer(ST_MakeLine(ST_MakePoint(21, 22),ST_MakePoint(-19, -18)),1) As line,
+ ST_Buffer(ST_GeomFromText('POINT(1 2)'), 20) As circle) As foo</programlisting>
+ </refsection>
+
+ <refsection>
+ <title>See Also</title>
+
+ <para>
+ <xref linkend="ST_BdPolyFromText" />,
+ <xref linkend="ST_BdMPolyFromText" />wrappers to
+ this function with standard OGC interface</para>
+ </refsection>
+ </refentry>
+ <refentry id="ST_Collect">
+ <refnamediv>
+ <refname>ST_Collect</refname>
+ <refpurpose>Return a specified ST_Geometry value from a collection of other geometries.</refpurpose>
+ </refnamediv>
+
+ <refsynopsisdiv>
+ <funcsynopsis>
+ <funcprototype>
+ <funcdef>geometry <function>ST_Collect</function></funcdef>
+ <paramdef><type>geometry set</type> <parameter>g1field</parameter></paramdef>
+ </funcprototype>
+ <funcprototype>
+ <funcdef>geometry <function>ST_Collect</function></funcdef>
+ <paramdef><type>geometry</type> <parameter>g1</parameter></paramdef>
+ <paramdef><type>geometry</type> <parameter>g2</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ </refsynopsisdiv>
+
+ <refsection>
+ <title>Description</title>
+ <para> Output type can be a MULTI* or a
+ GEOMETRYCOLLECTION. Comes in 2 variants. Variant 1 collects 2 geometries. Variant 2 is an aggregate function that takes a set of geometries and collects
+ them into a single ST_Geometry.</para>
+
+ <para>Aggregate version: This function returns a GEOMETRYCOLLECTION or a MULTI object
+ from a set of geometries. The ST_Collect() 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" will return a separate GEOMETRYCOLLECTION for
+ each distinct value of ATTRCOLUMN.</para>
+
+ <para>Non-Aggregate version: This function returns a geometry being a collection of two
+ input geometries. Output type can be a MULTI* or a
+ GEOMETRYCOLLECTION.</para>
+
+ <note><para>ST_Collect and ST_Union are often interchangeable.
+ ST_Collect is in general orders of magnitude faster than ST_Union
+ because it does not try to dissolve boundaries or validate that a constructed MultiPolgon doesn't
+ have overlapping regions. It merely rolls up
+ single geometries into MULTI and MULTI or mixed geometry types
+ into Geometry Collections. Unfortunately geometry collections are
+ not well-supported by GIS tools. To prevent ST_Collect from
+ returning a Geometry Collection when collecting MULTI geometries,
+ one can use the below trick that utilizes <xref linkend="ST_Dump" /> to expand the
+ MULTIs out to singles and then regroup them.</para></note>
+ </refsection>
+
+ <refsection>
+ <title>Examples</title>
+ <para>Aggregate example</para>
+ <programlisting>Thread ref: http://postgis.refractions.net/pipermail/postgis-users/2008-June/020331.html
+SELECT stusps,
+ ST_Multi(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>Thread ref: http://postgis.refractions.net/pipermail/postgis-users/2008-June/020331.html
+SELECT ST_AsText(ST_Collect(ST_GeomFromText('POINT(1 2)'),
+ ST_GeomFromText('POINT(-2 3)') ));
+
+st_astext
+----------
+MULTIPOINT(1 2,-2 3)
+
+SELECT ST_AsText(ST_Collect(ST_GeomFromText('POINT(1 2)'),
+ ST_GeomFromText('POINT(1 2)') ) );
+
+st_astext
+----------
+MULTIPOINT(1 2,1 2)</programlisting>
+ </refsection>
+ <refsection>
+ <title>See Also</title>
+ <para><xref linkend="ST_Dump" />, <xref linkend="ST_Union" /></para>
+ </refsection>
+ </refentry>
+
+ <refentry id="ST_Dump">
+ <refnamediv>
+ <refname>ST_Dump</refname>
+ <refpurpose>Returns a set of
+ geometry_dump rows, formed by a geometry (geom).</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>This is a set-returning function (SRF). It returns a set of
+ geometry_dump rows, formed by a geometry (geom) and an array of
+ integers (path). When the input geometry is a simple type
+ (POINT,LINESTRING,POLYGON) a single record will be returned with
+ an empty path array and the input geometry as geom. When the input
+ geometry is a collection or multi it will return a record for each
+ of the collection components, and the path will express the
+ position of the component inside the collection.</para>
+
+ <para>ST_Dump is useful for expanding geometries. It is the
+ reverse of a GROUP BY in that it creates new rows. For example it
+ can be use to expand MULTIPOLYGONS into POLYGONS.</para>
+
+ <para>Availability: PostGIS 1.0.0RC1. Requires PostgreSQL 7.3 or
+ higher.</para>
+ </refsection>
+
+ <refsection>
+ <title>Examples</title>
+ <programlisting>SELECT sometable.field1, sometable.field1,
+ (ST_Dump(sometable.the_geom)).geom As the_geom
+FROM sometable</programlisting>
+ </refsection>
+ <refsection>
+ <title>See Also</title>
+ <para><xref linkend="ST_Collect" /></para>
+ </refsection>
+ </refentry>
+
+ <refentry id="ST_MakePolygon">
+ <refnamediv>
+ <refname>ST_MakePolygon</refname>
+
+ <refpurpose>Creates a Polygon formed by the given shell. Input
+ geometries must be closed LINESTRINGS.</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 ST_Accum or the PostgreSQL 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>
+
+ </refsection>
+
+ <refsection>
+ <title>Examples: Single closed LINESTRING</title>
+ <programlisting>
+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
+ </programlisting>
+ </refsection>
+ <refsection>
+ <title>Examples: Outter 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 line strings
+ this is an example of using PostGIS ST_Accum
+ <note><para>The use of CASE because feeding a null array into
+ ST_MakePolygon results in NULL</para></note>
+ <note><para>the use of left join 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
+ ST_Accum(w.the_geom) IS NULL THEN p.the_geom
+ ELSE ST_MakePolygon(ST_LineMerge(ST_Boundary(p.the_geom)), ST_Accum(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_Accum" />, <xref linkend="ST_AddPoint" />, <xref linkend="ST_GeometryType" />, <xref linkend="ST_IsClosed" />, <xref linkend="ST_LineMerge" /></para>
+ </refsection>
+ </refentry>
+
+ <refentry id="ST_Intersection">
+ <refnamediv>
+ <refname>ST_Intersection</refname>
+
+ <refpurpose>Returns a geometry that represents the shared portion of geomA and geomB
+ </refpurpose>
+ </refnamediv>
+ <refsynopsisdiv>
+ <funcsynopsis>
+ <funcprototype>
+ <funcdef>geometry <function>ST_Intersection</function></funcdef>
+ <paramdef>
+ <type>geometry</type>
+ <parameter>geomA</parameter>
+ </paramdef>
+ <paramdef>
+ <type>geometry</type>
+ <parameter>geomB</parameter>
+ </paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ </refsynopsisdiv>
+ <refsection>
+ <title>Description</title>
+ <para>Returns a geometry that represents the point set
+ intersection of the Geometries.</para>
+
+ <para>In other words - that portion of geometry A and geometry B
+ that is shared between the two geometries.</para>
+
+ <para>If the geometries do not share any space (are disjoint), then an empty geometry collection
+ is returned.</para>
+ <para>ST_Intersection in conjunction with ST_Intersects is very useful for clipping geometries such as in bounding box, buffer, region
+ queries where you only want to return that portion of a geometry that sits in a country or region of interest.</para>
+
+ <important>
+ <para>Do not call with a <varname>GEOMETRYCOLLECTION</varname> as an argument</para>
+ </important>
+
+ <para>Performed by the GEOS module</para>
+
+
+ <para>
+ <inlinegraphic fileref="images/check.png" />
+ This method implements the
+ <ulink url="http://www.opengeospatial.org/standards/sfs">OpenGIS Simple
+ Features Implementation Specification for SQL</ulink> OGC SPEC s2.1.1.3
+ </para>
+
+ <!-- Optionally mention SQL/MM compliancy if appropriate -->
+ <para><inlinemediaobject>
+ <imageobject>
+ <imagedata fileref="images/check.png" />
+ </imageobject>
+ </inlinemediaobject> This method implements the SQL/MM specification: SQL-MM 3: 5.1.18</para>
+ </refsection>
+ <refsection>
+ <title>Examples</title>
+<programlisting>SELECT ST_AsText(ST_Intersection('POINT(0 0)'::geometry, 'LINESTRING ( 2 0, 0 2 )'::geometry));
+ st_astext
+---------------
+GEOMETRYCOLLECTION EMPTY
+(1 row)
+SELECT ST_AsText(ST_Intersection('POINT(0 0)'::geometry, 'LINESTRING ( 0 0, 0 2 )'::geometry));
+ st_astext
+---------------
+POINT(0 0)
+(1 row)
+
+---Clip all lines (trails) by country (here we assume country geom are POLYGON or MULTIPOLYGONS)
+-- NOTE: we are only keeping intersections that result in a LINESTRING or MULTILINESTRING because we don't
+-- care about trails that just share a point
+-- the dump is needed to expand a geometry collection into individual single MULT* parts
+-- the below is fairly generic and will work for polys, etc. by just changing the where clause
+SELECT clipped.gid, clipped.f_name, clipped_geom
+FROM (SELECT trails.gid, trails.f_name, (ST_Dump(ST_Intersection(country.the_geom, trails.the_geom))).geom As clipped_geom
+FROM country
+ INNER JOIN trails
+ ON ST_Intersects(country.the_geom, trails.the_geom)) As clipped
+ WHERE ST_Dimension(clipped.clipped_geom) = 1 ;
+
+--For polys e.g. polygon landmarks, you can also use the sometimes faster hack that buffering anything by 0.0
+-- except a polygon results in an empty geometry collection
+--(so a geometry collection containing polys, lines and points)
+-- buffered by 0.0 would only leave the polygons and dissolve the collection shell
+SELECT poly.gid, ST_Multi(ST_Buffer(
+ ST_Intersection(country.the_geom, poly.the_geom),
+ 0.0)
+ ) As clipped_geom
+FROM country
+ INNER JOIN poly
+ ON ST_Intersects(country.the_geom, poly.the_geom)
+ WHERE Not ST_IsEmpty(ST_Buffer(ST_Intersection(country.the_geom, poly.the_geom),0.0));
+ </programlisting>
+ </refsection>
+ <refsection>
+ <title>See Also</title>
+ <para><xref linkend="ST_Dimension"/>, <xref linkend="ST_Dump"/>, <xref linkend="ST_Intersects"/>, <xref linkend="ST_Multi"/></para>
+ </refsection>
+ </refentry>
+
+ <refentry id="ST_Union">
+ <refnamediv>
+ <refname>ST_Union</refname>
+ <refpurpose>Returns a geometry that represents the point set union of
+ the Geometries.</refpurpose>
+ </refnamediv>
+
+ <refsynopsisdiv>
+ <funcsynopsis>
+ <funcprototype>
+ <funcdef>geometry <function>ST_Union</function></funcdef>
+ <paramdef><type>geometry set</type> <parameter>g1field</parameter></paramdef>
+ </funcprototype>
+ <funcprototype>
+ <funcdef>geometry <function>ST_Union</function></funcdef>
+ <paramdef><type>geometry</type> <parameter>g1</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ </refsynopsisdiv>
+
+ <refsection>
+ <title>Description</title>
+ <para> Output type can be a MULTI* , single geometry, or Geometry Collection. Comes in 2 variants. Variant 1 unions 2 geometries resulting in a new geomety with no intersecting regions.
+ Variant 2 is an aggregate function that takes a set of geometries and unions
+ them into a single ST_Geometry resulting in no intersecting regions.</para>
+
+ <para>Aggregate version: This function returns a MULTI geometry or NON-MULTI geometry
+ from a set of geometries. The ST_Union() 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.</para>
+
+ <para>Non-Aggregate version: This function returns a geometry being a union of two
+ input geometries. Output type can be a MULTI* ,NON-MULTI or
+ GEOMETRYCOLLECTION.</para>
+
+ <note><para>ST_Collect and ST_Union are often interchangeable.
+ ST_Union is in general orders of magnitude slower than ST_Collect
+ because it tries to dissolve boundaries and reorder geometries to ensure that a constructed Multi* doesn't
+ have intersecting regions.</para></note>
+
+ <para>Performed by the GEOS module.</para>
+ <para>NOTE: this function was formerly called GeomUnion(), which
+ was renamed from "Union" because UNION is an SQL reserved
+ word.</para>
+
+ <para><inlinemediaobject>
+ <imageobject>
+ <imagedata fileref="images/check.png" />
+ </imageobject>
+ </inlinemediaobject> This method implements the <ulink
+ url="http://www.opengeospatial.org/standards/sfs">OpenGIS Simple Features
+ Implementation Specification for SQL: OGC SPEC s2.1.1.3</ulink></para>
+
+ <para><inlinemediaobject>
+ <imageobject>
+ <imagedata fileref="images/check.png" />
+ </imageobject>
+ </inlinemediaobject> This method implements the SQL/MM specification:
+ SQL-MM 3: 5.1.19</para>
+
+ <note><para>Aggregate version is not explicitly defined in OGC SPEC.</para></note>
+ </refsection>
+
+ <refsection>
+ <title>Examples</title>
+ <para>Aggregate example</para>
+ <programlisting>
+SELECT stusps,
+ ST_Multi(ST_Union(f.the_geom)) as singlegeom
+ FROM sometable As f
+GROUP BY stusps
+ </programlisting>
+ <para>Non-Aggregate example</para>
+ <programlisting>
+SELECT ST_AsText(ST_Union(ST_GeomFromText('POINT(1 2)'),
+ ST_GeomFromText('POINT(-2 3)') ) )
+
+st_astext
+----------
+MULTIPOINT(-2 3,1 2)
+
+
+SELECT ST_AsText(ST_Union(ST_GeomFromText('POINT(1 2)'),
+ ST_GeomFromText('POINT(1 2)') ) );
+st_astext
+----------
+POINT(1 2)
+ </programlisting>
+ </refsection>
+ <refsection>
+ <title>See Also</title>
+ <para><xref linkend="ST_Collect" /></para>
+ </refsection>
+ </refentry>
+</sect1>
<sect1>
<title>Linear Referencing</title>
projects / postgis / commitdiff