[postgis-tickets] [SCM] PostGIS branch master updated. 3.1.0alpha3-6-g4bc68f2
git at osgeo.org
git at osgeo.org
Fri Nov 27 17:40:34 PST 2020
This is an automated email from the git hooks/post-receive script. It was
generated because a ref change was pushed to the repository containing
the project "PostGIS".
The branch, master has been updated
via 4bc68f2bdcde272fd0db6e4bb304b6c325933a75 (commit)
from 3768f5ece1fc6f57611b74e988fde2f3eba5cd67 (commit)
Those revisions listed above that are new to this repository have
not appeared on any other notification email; so we list those
revisions in full, below.
- Log -----------------------------------------------------------------
commit 4bc68f2bdcde272fd0db6e4bb304b6c325933a75
Author: Martin Davis <mtnclimb at gmail.com>
Date: Fri Nov 27 17:40:16 2020 -0800
Add Ref Guide Overlay Function section
diff --git a/doc/Makefile.in b/doc/Makefile.in
index b4f8788..80150a1 100644
--- a/doc/Makefile.in
+++ b/doc/Makefile.in
@@ -138,6 +138,7 @@ XML_SOURCES = \
reference_sfcgal.xml \
reference_operator.xml \
reference_output.xml \
+ reference_overlay.xml \
reference_processing.xml \
reference_raster.xml \
reference_relationship.xml \
@@ -480,4 +481,3 @@ requirements_not_met_imagemagick:
@echo
@echo " http://postgis.net/documentation"
@echo
-
diff --git a/doc/postgis.xml b/doc/postgis.xml
index 3760ab0..64e3856 100644
--- a/doc/postgis.xml
+++ b/doc/postgis.xml
@@ -43,6 +43,7 @@
<!ENTITY reference_measure SYSTEM "reference_measure.xml">
<!ENTITY reference_relationship SYSTEM "reference_relationship.xml">
<!ENTITY reference_sfcgal SYSTEM "reference_sfcgal.xml">
+<!ENTITY reference_overlay SYSTEM "reference_overlay.xml">
<!ENTITY reference_processing SYSTEM "reference_processing.xml">
<!ENTITY reference_lrs SYSTEM "reference_lrs.xml">
<!ENTITY reference_srs SYSTEM "reference_srs.xml">
diff --git a/doc/reference.xml b/doc/reference.xml
index 345f0c2..a742810 100644
--- a/doc/reference.xml
+++ b/doc/reference.xml
@@ -28,6 +28,7 @@
&reference_operator;
&reference_relationship;
&reference_measure;
+ &reference_overlay;
&reference_processing;
&reference_transformation;
&reference_cluster;
diff --git a/doc/reference_overlay.xml b/doc/reference_overlay.xml
new file mode 100644
index 0000000..7188f67
--- /dev/null
+++ b/doc/reference_overlay.xml
@@ -0,0 +1,1013 @@
+<?xml version="1.0" encoding="UTF-8"?>
+ <sect1 id="Overlay_Functions">
+ <sect1info>
+ <abstract>
+ <para>These functions compute results arising from the overlay of two geometries.
+ These are also known as point-set theoretic boolean operations.
+ Some related functions are also provided.
+ </para>
+ </abstract>
+ </sect1info>
+
+ <title>Overlay Functions</title>
+
+ <refentry id="ST_ClipByBox2D">
+ <refnamediv>
+ <refname>ST_ClipByBox2D</refname>
+ <refpurpose>Returns the portion of a geometry falling within a rectangle.</refpurpose>
+ </refnamediv>
+
+ <refsynopsisdiv>
+ <funcsynopsis>
+ <funcprototype>
+ <funcdef>geometry <function>ST_ClipByBox2D</function></funcdef>
+ <paramdef><type>geometry</type> <parameter>geom</parameter></paramdef>
+ <paramdef><type>box2d</type> <parameter>box</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ </refsynopsisdiv>
+
+ <refsection>
+ <title>Description</title>
+
+ <para>
+ Clips a geometry by a 2D box in a fast but possibly dirty way.
+ The output geometry is not guaranteed to be valid (self-intersections for a polygon may be introduced).
+ Topologically invalid input geometries do not result in exceptions being thrown.
+ </para>
+
+ <para>Performed by the GEOS module.</para>
+
+ <para>Availability: 2.2.0</para>
+
+ </refsection>
+
+ <refsection>
+ <title>Examples</title>
+ <programlisting>
+-- Rely on implicit cast from geometry to box2d for the second parameter
+SELECT ST_ClipByBox2D(the_geom, ST_MakeEnvelope(0,0,10,10)) FROM mytab;
+ </programlisting>
+ </refsection>
+ <refsection>
+ <title>See Also</title>
+ <para>
+<xref linkend="ST_Intersection" />,
+<xref linkend="ST_MakeBox2D" />,
+<xref linkend="ST_MakeEnvelope" />
+ </para>
+ </refsection>
+ </refentry>
+
+ <refentry id="ST_Difference">
+ <refnamediv>
+ <refname>ST_Difference</refname>
+
+ <refpurpose>Returns a geometry that represents that part of geometry A
+ that does not intersect with geometry B.</refpurpose>
+ </refnamediv>
+
+ <refsynopsisdiv>
+ <funcsynopsis>
+ <funcprototype>
+ <funcdef>geometry <function>ST_Difference</function></funcdef>
+ <paramdef><type>geometry </type> <parameter>geomA</parameter></paramdef>
+ <paramdef><type>geometry </type> <parameter>geomB</parameter></paramdef>
+ <paramdef choice="opt"><type>float8 </type> <parameter>gridSize</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ </refsynopsisdiv>
+
+ <refsection>
+ <title>Description</title>
+
+ <para>Returns a geometry that represents that part of geometry A
+ that does not intersect with geometry B. One can think of this as GeometryA - ST_Intersection(A,B). If A is completely contained in B
+ then an empty geometry collection is returned.</para>
+ <note><para>Order matters. B - A will always return a portion of B</para></note>
+
+ <para>
+If a gridSize argument is provided, the inputs are
+snapped to a grid of the given size and all intersections are computed
+on that same grid. This method requires GEOS-3.9.0 or higher.
+ </para>
+
+ <para>Performed by the GEOS module</para>
+ <para>Enhanced: 3.1.0 accept a gridSize parameter - requires GEOS >= 3.9.0</para>
+
+ <para>&sfs_compliant; s2.1.1.3</para>
+ <para>&sqlmm_compliant; SQL-MM 3: 5.1.20</para>
+ <para>&Z_support; However it seems to only consider x y when
+ doing the difference and tacks back on the Z-Index</para>
+ </refsection>
+
+ <refsection>
+ <title>Examples</title>
+ <informaltable>
+ <tgroup cols="2">
+ <tbody>
+ <row>
+ <entry>
+ <para>
+ <informalfigure>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/st_symdifference01.png" />
+ </imageobject>
+ <caption><para>The original linestrings shown together. </para></caption>
+ </mediaobject>
+ </informalfigure>
+ </para>
+ </entry>
+
+ <entry>
+ <para><informalfigure>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/st_difference01.png" />
+ </imageobject>
+ <caption><para>The difference of the two linestrings</para></caption>
+ </mediaobject>
+ </informalfigure>
+ </para>
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+</informaltable>
+<para>Safe for 2D. This is same geometries as what is shown for st_symdifference</para>
+<programlisting>SELECT ST_AsText(
+ ST_Difference(
+ 'LINESTRING(50 100, 50 200)'::geometry,
+ 'LINESTRING(50 50, 50 150)'::geometry
+ )
+ );
+
+st_astext
+---------
+LINESTRING(50 150,50 200)
+</programlisting>
+
+<para>When used in 3d doesn't quite do the right thing.</para>
+<programlisting>select ST_AsEWKT(
+ ST_Difference(
+ 'MULTIPOINT(-118.58 38.38 5,-118.60 38.329 6,-118.614 38.281 7)' :: geometry,
+ 'POINT(-118.614 38.281 5)' :: geometry
+ )
+ );
+st_asewkt
+---------
+MULTIPOINT(-118.6 38.329 6,-118.58 38.38 5)</programlisting>
+ </refsection>
+
+ <refsection>
+ <title>See Also</title>
+
+ <para><xref linkend="ST_SymDifference" />, <xref linkend="ST_Intersection" />, <xref linkend="ST_Union" /></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>
+ <paramdef choice="opt">
+ <type>float8</type>
+ <parameter>gridSize</parameter>
+ </paramdef>
+ </funcprototype>
+ <funcprototype>
+ <funcdef>geography <function>ST_Intersection</function></funcdef>
+ <paramdef>
+ <type>geography</type>
+ <parameter>geogA</parameter>
+ </paramdef>
+ <paramdef>
+ <type>geography</type>
+ <parameter>geogB</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>
+
+ <para>
+If a gridSize argument is provided, the inputs are
+snapped to a grid of the given size and all intersections are computed
+on that same grid. This method requires GEOS-3.9.0 or higher.
+ </para>
+
+ <note><para>Geography: For geography this is really a thin wrapper around the geometry implementation. It first determines the best SRID that
+ fits the bounding box of the 2 geography objects (if geography objects are within one half zone UTM but not same UTM will pick one of those) (favoring UTM or Lambert Azimuthal Equal Area (LAEA) north/south pole, and falling back on mercator in worst case scenario) and then intersection in that best fit planar spatial ref and retransforms back to WGS84 geography.</para></note>
+
+ <warning><para>This function will drop the M coordinate values if present.</para></warning>
+
+ <warning><para>If working with 3D geometries, you may want to use SFGCAL based <xref linkend="ST_3DIntersection" /> which does a proper 3D intersection for 3D geometries. Although this function works with Z-coordinate, it does an averaging of Z-Coordinate.</para></warning>
+
+ <para>Performed by the GEOS module</para>
+
+ <para>Enhanced: 3.1.0 accept a gridSize parameter - requires GEOS >= 3.9.0</para>
+ <para>Changed: 3.0.0 does not depend on SFCGAL.</para>
+ <para>Availability: 1.5 support for geography data type was introduced.</para>
+
+ <para>&sfs_compliant; s2.1.1.3</para>
+ <para>&sqlmm_compliant; 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
+
+SELECT ST_AsText(ST_Intersection('POINT(0 0)'::geometry, 'LINESTRING ( 0 0, 0 2 )'::geometry));
+ st_astext
+---------------
+POINT(0 0)</programlisting>
+<para>
+Clip all lines (trails) by country. Hhere 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.</para>
+<programlisting>select clipped.gid, clipped.f_name, clipped_geom
+from (
+ select trails.gid, trails.f_name,
+ (ST_Dump(ST_Intersection(country.geom, trails.geom))).geom clipped_geom
+ from country
+ inner join trails on ST_Intersects(country.geom, trails.geom)
+ ) as clipped
+where ST_Dimension(clipped.clipped_geom) = 1;</programlisting>
+<para>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.)</para>
+<programlisting>select poly.gid,
+ ST_Multi(
+ ST_Buffer(
+ ST_Intersection(country.geom, poly.geom),
+ 0.0
+ )
+ ) clipped_geom
+from country
+ inner join poly on ST_Intersects(country.geom, poly.geom)
+where not ST_IsEmpty(ST_Buffer(ST_Intersection(country.geom, poly.geom), 0.0));</programlisting>
+ </refsection>
+
+ <refsection>
+ <title>Examples: 2.5Dish</title>
+ <para>Note this is not a true intersection, compare to the same example using <xref linkend="ST_3DIntersection" />.</para>
+ <programlisting>
+select ST_AsText(ST_Intersection(linestring, polygon)) As wkt
+from ST_GeomFromText('LINESTRING Z (2 2 6,1.5 1.5 7,1 1 8,0.5 0.5 8,0 0 10)') AS linestring
+ CROSS JOIN ST_GeomFromText('POLYGON((0 0 8, 0 1 8, 1 1 8, 1 0 8, 0 0 8))') AS polygon;
+
+ st_astext
+---------------------------------------
+ LINESTRING Z (1 1 8,0.5 0.5 8,0 0 10)
+ </programlisting>
+ </refsection>
+ <refsection>
+ <title>See Also</title>
+ <para><xref linkend="ST_3DIntersection" />, <xref linkend="ST_Difference"/>, <xref linkend="ST_Union"/>, <xref linkend="ST_Dimension"/>, <xref linkend="ST_Dump"/>, <xref linkend="ST_Force2D" />, <xref linkend="ST_SymDifference"/>, <xref linkend="ST_Intersects"/>, <xref linkend="ST_Multi"/></para>
+ </refsection>
+ </refentry>
+
+
+ <refentry id="ST_MemUnion">
+ <refnamediv>
+ <refname>ST_MemUnion</refname>
+
+ <refpurpose>Same as ST_Union, only memory-friendly (uses less memory
+ and more processor time).</refpurpose>
+ </refnamediv>
+
+ <refsynopsisdiv>
+ <funcsynopsis>
+ <funcprototype>
+ <funcdef>geometry <function>ST_MemUnion</function></funcdef>
+ <paramdef><type>geometry set</type> <parameter>geomfield</parameter></paramdef>
+ </funcprototype>
+
+ </funcsynopsis>
+ </refsynopsisdiv>
+
+ <refsection>
+ <title>Description</title>
+
+ <para>Some useful description here.</para>
+
+ <!-- optionally mention that this function uses indexes if appropriate -->
+ <note>
+ <para>Same as ST_Union, only memory-friendly (uses less memory
+ and more processor time). This aggregate function works by unioning the geometries one at a time to previous result as opposed to
+ ST_Union aggregate which first creates an array and then unions</para>
+ </note>
+
+ <para>&Z_support;</para>
+ </refsection>
+
+
+ <refsection>
+ <title>Examples</title>
+
+ <programlisting>See ST_Union</programlisting>
+ </refsection>
+
+ <!-- Optionally add a "See Also" section -->
+ <refsection>
+ <title>See Also</title>
+
+ <para><xref linkend="ST_Union" /></para>
+ </refsection>
+ </refentry>
+
+ <refentry id="ST_Node">
+ <refnamediv>
+ <refname>ST_Node</refname>
+
+ <refpurpose>
+Nodes a set of linestrings.
+ </refpurpose>
+ </refnamediv>
+
+ <refsynopsisdiv>
+ <funcsynopsis>
+ <funcprototype>
+ <funcdef>geometry <function>ST_Node</function></funcdef>
+ <paramdef><type>geometry </type> <parameter>geom</parameter></paramdef>
+ </funcprototype>
+
+ </funcsynopsis>
+ </refsynopsisdiv>
+
+ <refsection>
+ <title>Description</title>
+
+ <para>
+Fully node a set of linestrings using the least possible number of nodes
+while preserving all of the input ones.
+ </para>
+
+ <para>&Z_support;</para>
+ <para>Performed by the GEOS module.</para>
+ <para>Availability: 2.0.0</para>
+
+ <para>
+Changed: 2.4.0 this function uses GEOSNode internally instead of GEOSUnaryUnion.
+This may cause the resulting linestrings to have a different order and direction compared to Postgis < 2.4.
+ </para>
+ </refsection>
+ <refsection>
+ <title>Examples</title>
+ <programlisting>
+SELECT ST_AsText(
+ ST_Node('LINESTRINGZ(0 0 0, 10 10 10, 0 10 5, 10 0 3)'::geometry)
+ ) As output;
+output
+-----------
+MULTILINESTRING Z ((0 0 0,5 5 4.5),(5 5 4.5,10 10 10,0 10 5,5 5 4.5),(5 5 4.5,10 0 3))
+ </programlisting>
+ </refsection>
+
+ <!-- Optionally add a "See Also" section -->
+ <refsection>
+ <title>See Also</title>
+
+ <para>
+ <xref linkend="ST_UnaryUnion" />
+ </para>
+ </refsection>
+ </refentry>
+
+ <refentry id="ST_Split">
+ <refnamediv>
+ <refname>ST_Split</refname>
+ <refpurpose>Returns a collection of geometries resulting by splitting a geometry.</refpurpose>
+ </refnamediv>
+
+ <refsynopsisdiv>
+ <funcsynopsis>
+ <funcprototype>
+ <funcdef>geometry <function>ST_Split</function></funcdef>
+ <paramdef><type>geometry</type> <parameter>input</parameter></paramdef>
+ <paramdef><type>geometry</type> <parameter>blade</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ </refsynopsisdiv>
+
+ <refsection>
+ <title>Description</title>
+ <para>
+ The function supports splitting a line by (multi)point, (multi)line or (multi)polygon boundary, a (multi)polygon by line. The returned geometry is always a collection.
+ </para>
+
+ <para>
+ Think of this function as the opposite of ST_Union.
+ Theoretically applying ST_Union to the elements of the returned collection
+ should always yield the original geometry.
+ </para>
+
+ <para>Availability: 2.0.0 requires GEOS</para>
+ <para>Enhanced: 2.2.0 support for splitting a line by a multiline, a multipoint or (multi)polygon boundary was introduced.</para>
+ <para>Enhanced: 2.5.0 support for splitting a polygon by a multiline was introduced.</para>
+
+ <note><para>To improve the robustness of ST_Split it may be convenient to <xref linkend="ST_Snap"/> the input to the blade in advance using a very low tolerance. Otherwise the internally used coordinate grid may cause tolerance problems, where coordinates of input and blade do not fall onto each other and the input is not being split correctly (see <ulink url="http://trac.osgeo.org/postgis/ticket/2192">#2192</ulink>).</para></note>
+
+ <note><para>
+When a (multi)polygon is passed as as the blade, its linear component
+(the boundary) is used for cutting the input.
+ </para></note>
+
+ </refsection>
+ <refsection>
+ <title>Examples</title>
+ <para>Polygon Cut by Line</para>
+ <informaltable>
+ <tgroup cols="2">
+ <tbody>
+ <row>
+ <entry>
+ <para>
+ <informalfigure>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/st_split01.png" />
+ </imageobject>
+ <caption><para>Before Split</para></caption>
+ </mediaobject>
+ </informalfigure>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ <informalfigure>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/st_split02.png" />
+ </imageobject>
+ <caption><para>After split</para></caption>
+ </mediaobject>
+ </informalfigure>
+ </para>
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+ <programlisting>
+-- this creates a geometry collection consisting of the 2 halves of the polygon
+-- this is similar to the example we demonstrated in ST_BuildArea
+SELECT ST_Split(circle, line)
+FROM (SELECT
+ ST_MakeLine(ST_MakePoint(10, 10),ST_MakePoint(190, 190)) As line,
+ ST_Buffer(ST_GeomFromText('POINT(100 90)'), 50) As circle) As foo;
+
+-- result --
+ GEOMETRYCOLLECTION(POLYGON((150 90,149.039264020162 80.2454838991936,146.193976625564 70.8658283817455,..), POLYGON(..)))
+
+-- To convert to individual polygons, you can use ST_Dump or ST_GeometryN
+SELECT ST_AsText((ST_Dump(ST_Split(circle, line))).geom) As wkt
+FROM (SELECT
+ ST_MakeLine(ST_MakePoint(10, 10),ST_MakePoint(190, 190)) As line,
+ ST_Buffer(ST_GeomFromText('POINT(100 90)'), 50) As circle) As foo;
+
+-- result --
+wkt
+---------------
+POLYGON((150 90,149.039264020162 80.2454838991936,..))
+POLYGON((60.1371179574584 60.1371179574584,58.4265193848728 62.2214883490198,53.8060233744357 ..))
+ </programlisting>
+ <para>Multilinestring Cut by point</para>
+ <informaltable>
+ <tgroup cols="2">
+ <tbody>
+ <row>
+ <entry>
+ <para>
+ <informalfigure>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/st_split03.png" />
+ </imageobject>
+ <caption><para>Before Split</para></caption>
+ </mediaobject>
+ </informalfigure>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ <informalfigure>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/st_split04.png" />
+ </imageobject>
+ <caption><para>After split</para></caption>
+ </mediaobject>
+ </informalfigure>
+ </para>
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+ <programlisting>
+SELECT ST_AsText(ST_Split(mline, pt)) As wktcut
+ FROM (SELECT
+ ST_GeomFromText('MULTILINESTRING((10 10, 190 190), (15 15, 30 30, 100 90))') As mline,
+ ST_Point(30,30) As pt) As foo;
+
+wktcut
+------
+GEOMETRYCOLLECTION(
+ LINESTRING(10 10,30 30),
+ LINESTRING(30 30,190 190),
+ LINESTRING(15 15,30 30),
+ LINESTRING(30 30,100 90)
+)
+ </programlisting>
+ </refsection>
+ <refsection>
+ <title>See Also</title>
+ <para>
+<xref linkend="ST_AsText" />,
+<xref linkend="ST_BuildArea" />,
+<xref linkend="ST_CollectionExtract" />,
+<xref linkend="ST_Dump" />,
+<xref linkend="ST_GeometryN" />,
+<xref linkend="ST_Subdivide" />,
+<xref linkend="ST_Union" />
+ </para>
+ </refsection>
+ </refentry>
+
+ <refentry id="ST_Subdivide">
+ <refnamediv>
+ <refname>ST_Subdivide</refname>
+ <refpurpose>Computes a rectilinear subdivision of a geometry with each part smaller than a given vertex count.</refpurpose>
+ </refnamediv>
+
+ <refsynopsisdiv>
+ <funcsynopsis>
+ <funcprototype>
+ <funcdef>setof geometry <function>ST_Subdivide</function></funcdef>
+ <paramdef><type>geometry</type> <parameter>geom</parameter></paramdef>
+ <paramdef><type>integer</type> <parameter>max_vertices=256</parameter></paramdef>
+ <paramdef choice="opt"><type>float8</type> <parameter>gridSize</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ </refsynopsisdiv>
+
+ <refsection>
+ <title>Description</title>
+
+ <para>
+ Divides geometry into parts until a part can be represented using no more than <code>max_vertices</code>.
+ Point-in-polygon and other overlay operations are normally faster for indexed subdivided dataset:
+ "miss" cases are faster to check as boxes for all parts typically cover smaller area than original geometry box,
+ "hit" cases are faster because recheck operates on less points.
+ <code>max_vertices</code> must be 5 or more, as 5 points are needed to represent a closed box.
+ <code>gridSize</code> can be specified to have clipping work in fixed-precision space (requires GEOS-3.9.0+).
+ </para>
+ <para>Performed by the GEOS module.</para>
+ <para>Availability: 2.2.0</para>
+ <para>Enhanced: 2.5.0 reuses existing points on polygon split, vertex count is lowered from 8 to 5.</para>
+ <para>Enhanced: 3.1.0 accept a gridSize parameter, requires GEOS >= 3.9.0 to use this new feature.</para>
+ </refsection>
+
+ <refsection>
+ <title>Examples</title>
+ <programlisting>-- Subdivide complex geometries in table, in place
+with complex_areas_to_subdivide as (
+ delete from polygons_table
+ where ST_NPoints(geom) > 255
+ returning id, column1, column2, column3, geom
+)
+insert into polygons_table (fid, column1, column2, column3, geom)
+ select
+ fid, column1, column2, column3,
+ ST_Subdivide(geom, 255) as geom
+ from complex_areas_to_subdivide;
+ </programlisting>
+
+ <programlisting>-- Create a new subdivided table suitable for joining to the original
+CREATE TABLE subdivided_geoms AS
+SELECT pkey, ST_Subdivide(geom) AS geom
+FROM original_geoms;
+ </programlisting>
+
+ <informaltable>
+ <tgroup cols="1">
+ <tbody>
+ <row>
+ <entry><para><informalfigure>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/st_subdivide01.png" />
+ </imageobject>
+ <caption><para>Subdivide max 10 vertices</para></caption>
+ </mediaobject>
+ </informalfigure>
+ <programlisting>SELECT row_number() OVER() As rn, ST_AsText(geom) As wkt
+FROM ( SELECT ST_SubDivide('POLYGON((132 10,119 23,85 35,68 29,66 28,49 42,32 56,22 64,32 110,40 119,36 150,
+57 158,75 171,92 182,114 184,132 186,146 178,176 184,179 162,184 141,190 122,
+190 100,185 79,186 56,186 52,178 34,168 18,147 13,132 10))'::geometry,10)) As f(geom);</programlisting>
+<screen> rn │ wkt
+────┼────────────────────────────────────────────────────────────────────────────────────────────────────────────────
+ 1 │ POLYGON((119 23,85 35,68 29,66 28,32 56,22 64,29.8260869565217 100,119 100,119 23))
+ 2 │ POLYGON((132 10,119 23,119 56,186 56,186 52,178 34,168 18,147 13,132 10))
+ 3 │ POLYGON((119 56,119 100,190 100,185 79,186 56,119 56))
+ 4 │ POLYGON((29.8260869565217 100,32 110,40 119,36 150,57 158,75 171,92 182,114 184,114 100,29.8260869565217 100))
+ 5 │ POLYGON((114 184,132 186,146 178,176 184,179 162,184 141,190 122,190 100,114 100,114 184))</screen>
+ </para></entry>
+ </row>
+ <row>
+ <entry><para><informalfigure>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/st_subdivide02.png" />
+ </imageobject>
+ <caption><para>Useful in conjunction with ST_Segmentize(geography) to create additional vertices that can then be used for splitting.</para></caption>
+ </mediaobject>
+ </informalfigure>
+ <programlisting>SELECT ST_AsText(ST_Subdivide(ST_Segmentize('LINESTRING(0 0, 85 85)'::geography,1200000)::geometry,8));</programlisting>
+ <screen>
+LINESTRING(0 0,0.487578359029357 5.57659056746196,0.984542144675897 11.1527721155093,1.50101059639722 16.7281035483571,1.94532113630331 21.25)
+LINESTRING(1.94532113630331 21.25,2.04869538062779 22.3020741387339,2.64204641967673 27.8740533545155,3.29994062412787 33.443216802941,4.04836719489742 39.0084282520239,4.59890468420694 42.5)
+LINESTRING(4.59890468420694 42.5,4.92498503922732 44.5680389206321,5.98737409390639 50.1195229244701,7.3290919767674 55.6587646879025,8.79638749938413 60.1969505994924)
+LINESTRING(8.79638749938413 60.1969505994924,9.11375579533779 61.1785363177625,11.6558166691368 66.6648504160202,15.642041247655 72.0867690601745,22.8716627200212 77.3609628116894,24.6991785131552 77.8939011989848)
+LINESTRING(24.6991785131552 77.8939011989848,39.4046096622744 82.1822848017636,44.7994523421035 82.5156766227011)
+LINESTRING(44.7994523421035 82.5156766227011,85 85)</screen>
+ </para></entry>
+ </row>
+ </tbody></tgroup></informaltable>
+ </refsection>
+ <refsection>
+ <title>See Also</title>
+ <para>
+<xref linkend="ST_AsText" />,
+<xref linkend="ST_ClipByBox2D" />,
+<xref linkend="ST_Segmentize" />,
+<xref linkend="ST_Split" />,
+<xref linkend="ST_NPoints" />
+ </para>
+ </refsection>
+ </refentry>
+
+ <refentry id="ST_SymDifference">
+ <refnamediv>
+ <refname>ST_SymDifference</refname>
+
+ <refpurpose>Returns a geometry that represents the portions of A and B
+ that do not intersect.</refpurpose>
+ </refnamediv>
+
+ <refsynopsisdiv>
+ <funcsynopsis>
+ <funcprototype>
+ <funcdef>geometry <function>ST_SymDifference</function></funcdef>
+ <paramdef><type>geometry </type> <parameter>geomA</parameter></paramdef>
+ <paramdef><type>geometry </type> <parameter>geomB</parameter></paramdef>
+ <paramdef choice="opt"><type>float8 </type> <parameter>gridSize</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ </refsynopsisdiv>
+
+ <refsection>
+ <title>Description</title>
+
+ <para>Returns a geometry that represents the portions of A and B
+ that do not intersect. It is called a symmetric difference because
+ ST_SymDifference(A,B) = ST_SymDifference(B,A). One can think of this as ST_Union(geomA,geomB) - ST_Intersection(A,B).
+ </para>
+
+ <para>
+If a gridSize argument is provided, the inputs are
+snapped to a grid of the given size and all intersections are computed
+on that same grid. This method requires GEOS-3.9.0 or higher.
+ </para>
+
+ <para>Performed by the GEOS module</para>
+
+ <para>Enhanced: 3.1.0 accept a gridSize parameter - requires GEOS >= 3.9.0</para>
+
+ <para>&sfs_compliant; s2.1.1.3</para>
+ <para>&sqlmm_compliant; SQL-MM 3: 5.1.21</para>
+ <para>&Z_support; However it seems to only consider x y when
+ doing the difference and tacks back on the Z-Index</para>
+ </refsection>
+
+
+ <refsection>
+ <title>Examples</title>
+
+ <informaltable>
+ <tgroup cols="2">
+ <tbody>
+ <row>
+ <entry>
+ <para>
+ <informalfigure>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/st_symdifference01.png" />
+ </imageobject>
+ <caption><para>The original linestrings shown together</para></caption>
+ </mediaobject>
+ </informalfigure>
+ </para>
+ </entry>
+
+ <entry>
+ <para><informalfigure>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/st_symdifference02.png" />
+ </imageobject>
+ <caption><para>The symmetric difference of the two linestrings</para></caption>
+ </mediaobject>
+ </informalfigure>
+ </para>
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+</informaltable>
+<programlisting>
+--Safe for 2d - symmetric difference of 2 linestrings
+SELECT ST_AsText(
+ ST_SymDifference(
+ ST_GeomFromText('LINESTRING(50 100, 50 200)'),
+ ST_GeomFromText('LINESTRING(50 50, 50 150)')
+ )
+);
+
+st_astext
+---------
+MULTILINESTRING((50 150,50 200),(50 50,50 100))
+</programlisting>
+
+<programlisting>
+
+--When used in 3d doesn't quite do the right thing
+SELECT ST_AsEWKT(ST_SymDifference(ST_GeomFromEWKT('LINESTRING(1 2 1, 1 4 2)'),
+ ST_GeomFromEWKT('LINESTRING(1 1 3, 1 3 4)')))
+
+st_astext
+------------
+MULTILINESTRING((1 3 2.75,1 4 2),(1 1 3,1 2 2.25))
+ </programlisting>
+ </refsection>
+
+ <!-- Optionally add a "See Also" section -->
+ <refsection>
+ <title>See Also</title>
+
+ <para><xref linkend="ST_Difference" />, <xref linkend="ST_Intersection" />, <xref linkend="ST_Union" /></para>
+ </refsection>
+</refentry>
+
+
+<refentry id="ST_Union">
+ <refnamediv>
+ <refname>ST_Union</refname>
+ <refpurpose>Returns a geometry that represents the point-set union of
+ the input 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>
+ <paramdef><type>geometry</type> <parameter>g2</parameter></paramdef>
+ </funcprototype>
+ <funcprototype>
+ <funcdef>geometry <function>ST_Union</function></funcdef>
+ <paramdef><type>geometry</type> <parameter>g1</parameter></paramdef>
+ <paramdef><type>geometry</type> <parameter>g2</parameter></paramdef>
+ <paramdef><type>float8</type> <parameter>gridSize</parameter></paramdef>
+ </funcprototype>
+ <funcprototype>
+ <funcdef>geometry <function>ST_Union</function></funcdef>
+ <paramdef><type>geometry[]</type> <parameter>g1_array</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 geometry 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 and like most aggregates, it also ignores NULL geometries.</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. If any are NULL, then NULL is returned.</para>
+
+ <para>
+ For non-aggregate version, <code>gridSize</code> can be specified
+ to work in fixed-precision space (requires GEOS-3.9.0+).
+ </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>ST_Union will use the faster Cascaded Union algorithm described in <ulink
+ url="http://blog.cleverelephant.ca/2009/01/must-faster-unions-in-postgis-14.html">http://blog.cleverelephant.ca/2009/01/must-faster-unions-in-postgis-14.html</ulink></para>
+
+ <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>Enhanced: 3.1.0 accept a gridSize parameter - requires GEOS >= 3.9.0</para>
+ <para>Changed: 3.0.0 does not depend on SFCGAL.</para>
+ <para>Availability: 1.4.0 - ST_Union was enhanced. ST_Union(geomarray) was introduced and also faster aggregate collection in PostgreSQL.</para>
+
+ <para>&sfs_compliant; s2.1.1.3</para>
+ <note><para>Aggregate version is not explicitly defined in OGC SPEC.</para></note>
+ <para>&sqlmm_compliant; SQL-MM 3: 5.1.19
+ the z-index (elevation) when polygons are involved.</para>
+ </refsection>
+
+ <refsection>
+ <title>Examples</title>
+ <para>Aggregate example</para>
+ <programlisting>
+SELECT stusps,
+ ST_Union(f.geom) as singlegeom
+FROM sometable f
+GROUP BY stusps
+ </programlisting>
+ <para>Non-Aggregate example</para>
+ <programlisting>
+select ST_AsText(ST_Union('POINT(1 2)' :: geometry, 'POINT(-2 3)' :: geometry))
+
+st_astext
+----------
+MULTIPOINT(-2 3,1 2)
+
+select ST_AsText(ST_Union('POINT(1 2)' :: geometry, 'POINT(1 2)' :: geometry))
+
+st_astext
+----------
+POINT(1 2)</programlisting>
+<para>3D example - sort of supports 3D (and with mixed dimensions!)</para>
+<programlisting>select ST_AsEWKT(ST_Union(geom))
+from (
+ select 'POLYGON((-7 4.2,-7.1 4.2,-7.1 4.3, -7 4.2))'::geometry geom
+ union all
+ select 'POINT(5 5 5)'::geometry geom
+ union all
+ select 'POINT(-2 3 1)'::geometry geom
+ union all
+ select 'LINESTRING(5 5 5, 10 10 10)'::geometry geom
+ ) as foo;
+
+st_asewkt
+---------
+GEOMETRYCOLLECTION(POINT(-2 3 1),LINESTRING(5 5 5,10 10 10),POLYGON((-7 4.2 5,-7.1 4.2 5,-7.1 4.3 5,-7 4.2 5)));
+</programlisting>
+<para>3d example not mixing dimensions</para>
+<programlisting>select ST_AsEWKT(ST_Union(geom))
+from (
+ select 'POLYGON((-7 4.2 2,-7.1 4.2 3,-7.1 4.3 2, -7 4.2 2))'::geometry geom
+ union all
+ select 'POINT(5 5 5)'::geometry geom
+ union all
+ select 'POINT(-2 3 1)'::geometry geom
+ union all
+ select 'LINESTRING(5 5 5, 10 10 10)'::geometry geom
+ ) as foo;
+
+st_asewkt
+---------
+GEOMETRYCOLLECTION(POINT(-2 3 1),LINESTRING(5 5 5,10 10 10),POLYGON((-7 4.2 2,-7.1 4.2 3,-7.1 4.3 2,-7 4.2 2)))
+
+--Examples using new Array construct
+SELECT ST_Union(ARRAY(SELECT the_geom FROM sometable));
+
+SELECT ST_AsText(ST_Union(ARRAY[ST_GeomFromText('LINESTRING(1 2, 3 4)'),
+ ST_GeomFromText('LINESTRING(3 4, 4 5)')])) As wktunion;
+
+--wktunion---
+MULTILINESTRING((3 4,4 5),(1 2,3 4))
+
+ </programlisting>
+ </refsection>
+ <refsection>
+ <title>See Also</title>
+ <para>
+ <xref linkend="ST_Collect" />,
+ <xref linkend="ST_UnaryUnion" />,
+ <xref linkend="ST_Intersection" />,
+ <xref linkend="ST_Difference" />
+ <xref linkend="ST_SymDifference" />
+ </para>
+ </refsection>
+ </refentry>
+
+ <refentry id="ST_UnaryUnion">
+ <refnamediv>
+ <refname>ST_UnaryUnion</refname>
+
+ <refpurpose>Like ST_Union, but working at the geometry component level.</refpurpose>
+ </refnamediv>
+
+ <refsynopsisdiv>
+ <funcsynopsis>
+ <funcprototype>
+ <funcdef>geometry <function>ST_UnaryUnion</function></funcdef>
+ <paramdef><type>geometry </type> <parameter>geom</parameter></paramdef>
+ <paramdef choice="opt"><type>float8 </type> <parameter>gridSize</parameter></paramdef>
+ </funcprototype>
+
+ </funcsynopsis>
+ </refsynopsisdiv>
+
+ <refsection>
+ <title>Description</title>
+
+ <para>
+ Unlike ST_Union, ST_UnaryUnion does dissolve boundaries
+ between components of a multipolygon (invalid)
+ and does perform union between the components of a
+ geometrycollection.
+ Each components of the input geometry is assumed to be
+ valid, so you won't get a valid multipolygon out of a
+ bow-tie polygon (invalid).
+ </para>
+
+ <para>
+ You may use this function to node a set of linestrings.
+ You may mix ST_UnaryUnion with ST_Collect to fine-tune
+ how many geometries at once you want to dissolve to
+ be nice on both memory size and CPU time, finding the
+ balance between ST_Union and ST_MemUnion.
+ </para>
+
+ <para>
+If a gridSize argument is provided, the inputs are
+snapped to a grid of the given size and all intersections are computed
+on that same grid. This method requires GEOS-3.9.0 or higher.
+ </para>
+
+ <para>&Z_support;</para>
+ <para>Enhanced: 3.1.0 accept a gridSize parameter - requires GEOS >= 3.9.0</para>
+ <para>Availability: 2.0.0</para>
+
+ </refsection>
+
+
+ <!-- Optionally add a "See Also" section -->
+ <refsection>
+ <title>See Also</title>
+
+ <para>
+ <xref linkend="ST_Union" />,
+ <xref linkend="ST_MemUnion" />,
+ <xref linkend="ST_Collect" />,
+ <xref linkend="ST_Node" />
+ </para>
+ </refsection>
+ </refentry>
+
+
+</sect1>
diff --git a/doc/reference_processing.xml b/doc/reference_processing.xml
index 63e8add..58707d8 100644
--- a/doc/reference_processing.xml
+++ b/doc/reference_processing.xml
@@ -1,6 +1,15 @@
<?xml version="1.0" encoding="UTF-8"?>
<sect1 id="Geometry_Processing">
- <title>Geometry Processing</title>
+ <sect1info>
+ <abstract>
+ <para>These functions compute geometric constructions,
+ or alter geometry size or shape.
+ </para>
+ </abstract>
+ </sect1info>
+
+ <title>Geometry Processing</title>
+
<refentry id="ST_Buffer">
<refnamediv>
<refname>ST_Buffer</refname>
@@ -359,7 +368,7 @@ POLYGON((236057.59057465 900908.759918696,236028.301252769 900838.049240578,235
<refname>ST_BuildArea</refname>
<refpurpose>Creates an areal geometry formed by the constituent linework
- of given geometry</refpurpose>
+ of given geometry.</refpurpose>
</refnamediv>
<refsynopsisdiv>
@@ -431,8 +440,8 @@ FROM (SELECT
<xref linkend="ST_MakePolygon" />,
<xref linkend="ST_MakeValid" />,
<xref linkend="ST_BdPolyFromText" />,
- <xref linkend="ST_BdMPolyFromText" />wrappers to
- this function with standard OGC interface</para>
+ <xref linkend="ST_BdMPolyFromText" /> (wrappers to
+ this function with standard OGC interface)</para>
</refsection>
</refentry>
@@ -580,55 +589,6 @@ POINT(0.5 1)
</refsection>
</refentry>
- <refentry id="ST_ClipByBox2D">
- <refnamediv>
- <refname>ST_ClipByBox2D</refname>
- <refpurpose>Returns the portion of a geometry falling within a rectangle.</refpurpose>
- </refnamediv>
-
- <refsynopsisdiv>
- <funcsynopsis>
- <funcprototype>
- <funcdef>geometry <function>ST_ClipByBox2D</function></funcdef>
- <paramdef><type>geometry</type> <parameter>geom</parameter></paramdef>
- <paramdef><type>box2d</type> <parameter>box</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- </refsynopsisdiv>
-
- <refsection>
- <title>Description</title>
-
- <para>
- Clips a geometry by a 2D box in a fast but possibly dirty way.
- The output geometry is not guaranteed to be valid (self-intersections for a polygon may be introduced).
- Topologically invalid input geometries do not result in exceptions being thrown.
- </para>
-
- <para>Performed by the GEOS module.</para>
-
- <para>Availability: 2.2.0</para>
-
- </refsection>
-
- <refsection>
- <title>Examples</title>
- <programlisting>
--- Rely on implicit cast from geometry to box2d for the second parameter
-SELECT ST_ClipByBox2D(the_geom, ST_MakeEnvelope(0,0,10,10)) FROM mytab;
- </programlisting>
- </refsection>
- <refsection>
- <title>See Also</title>
- <para>
-<xref linkend="ST_Intersection" />,
-<xref linkend="ST_MakeBox2D" />,
-<xref linkend="ST_MakeEnvelope" />
- </para>
- </refsection>
- </refentry>
-
-
<refentry id="ST_ConcaveHull">
<refnamediv>
<refname>ST_ConcaveHull</refname>
@@ -1217,114 +1177,6 @@ GEOMETRYCOLLECTION Z (POLYGON Z ((14 14 10,20 10 150,34 6 25,14 14 10))
</refsection>
</refentry>
- <refentry id="ST_Difference">
- <refnamediv>
- <refname>ST_Difference</refname>
-
- <refpurpose>Returns a geometry that represents that part of geometry A
- that does not intersect with geometry B.</refpurpose>
- </refnamediv>
-
- <refsynopsisdiv>
- <funcsynopsis>
- <funcprototype>
- <funcdef>geometry <function>ST_Difference</function></funcdef>
- <paramdef><type>geometry </type> <parameter>geomA</parameter></paramdef>
- <paramdef><type>geometry </type> <parameter>geomB</parameter></paramdef>
- <paramdef choice="opt"><type>float8 </type> <parameter>gridSize</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- </refsynopsisdiv>
-
- <refsection>
- <title>Description</title>
-
- <para>Returns a geometry that represents that part of geometry A
- that does not intersect with geometry B. One can think of this as GeometryA - ST_Intersection(A,B). If A is completely contained in B
- then an empty geometry collection is returned.</para>
- <note><para>Order matters. B - A will always return a portion of B</para></note>
-
- <para>
-If a gridSize argument is provided, the inputs are
-snapped to a grid of the given size and all intersections are computed
-on that same grid. This method requires GEOS-3.9.0 or higher.
- </para>
-
- <para>Performed by the GEOS module</para>
- <para>Enhanced: 3.1.0 accept a gridSize parameter - requires GEOS >= 3.9.0</para>
-
- <para>&sfs_compliant; s2.1.1.3</para>
- <para>&sqlmm_compliant; SQL-MM 3: 5.1.20</para>
- <para>&Z_support; However it seems to only consider x y when
- doing the difference and tacks back on the Z-Index</para>
- </refsection>
-
- <refsection>
- <title>Examples</title>
- <informaltable>
- <tgroup cols="2">
- <tbody>
- <row>
- <entry>
- <para>
- <informalfigure>
- <mediaobject>
- <imageobject>
- <imagedata fileref="images/st_symdifference01.png" />
- </imageobject>
- <caption><para>The original linestrings shown together. </para></caption>
- </mediaobject>
- </informalfigure>
- </para>
- </entry>
-
- <entry>
- <para><informalfigure>
- <mediaobject>
- <imageobject>
- <imagedata fileref="images/st_difference01.png" />
- </imageobject>
- <caption><para>The difference of the two linestrings</para></caption>
- </mediaobject>
- </informalfigure>
- </para>
- </entry>
- </row>
- </tbody>
- </tgroup>
-</informaltable>
-<para>Safe for 2D. This is same geometries as what is shown for st_symdifference</para>
-<programlisting>SELECT ST_AsText(
- ST_Difference(
- 'LINESTRING(50 100, 50 200)'::geometry,
- 'LINESTRING(50 50, 50 150)'::geometry
- )
- );
-
-st_astext
----------
-LINESTRING(50 150,50 200)
-</programlisting>
-
-<para>When used in 3d doesn't quite do the right thing.</para>
-<programlisting>select ST_AsEWKT(
- ST_Difference(
- 'MULTIPOINT(-118.58 38.38 5,-118.60 38.329 6,-118.614 38.281 7)' :: geometry,
- 'POINT(-118.614 38.281 5)' :: geometry
- )
- );
-st_asewkt
----------
-MULTIPOINT(-118.6 38.329 6,-118.58 38.38 5)</programlisting>
- </refsection>
-
- <refsection>
- <title>See Also</title>
-
- <para><xref linkend="ST_SymDifference" />, <xref linkend="ST_Intersection" />, <xref linkend="ST_Union" /></para>
- </refsection>
- </refentry>
-
<refentry id="ST_FilterByM">
<refnamediv>
<refname>ST_FilterByM</refname>
@@ -1646,136 +1498,6 @@ FROM test;
</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>
- <paramdef choice="opt">
- <type>float8</type>
- <parameter>gridSize</parameter>
- </paramdef>
- </funcprototype>
- <funcprototype>
- <funcdef>geography <function>ST_Intersection</function></funcdef>
- <paramdef>
- <type>geography</type>
- <parameter>geogA</parameter>
- </paramdef>
- <paramdef>
- <type>geography</type>
- <parameter>geogB</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>
-
- <para>
-If a gridSize argument is provided, the inputs are
-snapped to a grid of the given size and all intersections are computed
-on that same grid. This method requires GEOS-3.9.0 or higher.
- </para>
-
- <note><para>Geography: For geography this is really a thin wrapper around the geometry implementation. It first determines the best SRID that
- fits the bounding box of the 2 geography objects (if geography objects are within one half zone UTM but not same UTM will pick one of those) (favoring UTM or Lambert Azimuthal Equal Area (LAEA) north/south pole, and falling back on mercator in worst case scenario) and then intersection in that best fit planar spatial ref and retransforms back to WGS84 geography.</para></note>
-
- <warning><para>This function will drop the M coordinate values if present.</para></warning>
-
- <warning><para>If working with 3D geometries, you may want to use SFGCAL based <xref linkend="ST_3DIntersection" /> which does a proper 3D intersection for 3D geometries. Although this function works with Z-coordinate, it does an averaging of Z-Coordinate.</para></warning>
-
- <para>Performed by the GEOS module</para>
-
- <para>Enhanced: 3.1.0 accept a gridSize parameter - requires GEOS >= 3.9.0</para>
- <para>Changed: 3.0.0 does not depend on SFCGAL.</para>
- <para>Availability: 1.5 support for geography data type was introduced.</para>
-
- <para>&sfs_compliant; s2.1.1.3</para>
- <para>&sqlmm_compliant; 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
-
-SELECT ST_AsText(ST_Intersection('POINT(0 0)'::geometry, 'LINESTRING ( 0 0, 0 2 )'::geometry));
- st_astext
----------------
-POINT(0 0)</programlisting>
-<para>
-Clip all lines (trails) by country. Hhere 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.</para>
-<programlisting>select clipped.gid, clipped.f_name, clipped_geom
-from (
- select trails.gid, trails.f_name,
- (ST_Dump(ST_Intersection(country.geom, trails.geom))).geom clipped_geom
- from country
- inner join trails on ST_Intersects(country.geom, trails.geom)
- ) as clipped
-where ST_Dimension(clipped.clipped_geom) = 1;</programlisting>
-<para>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.)</para>
-<programlisting>select poly.gid,
- ST_Multi(
- ST_Buffer(
- ST_Intersection(country.geom, poly.geom),
- 0.0
- )
- ) clipped_geom
-from country
- inner join poly on ST_Intersects(country.geom, poly.geom)
-where not ST_IsEmpty(ST_Buffer(ST_Intersection(country.geom, poly.geom), 0.0));</programlisting>
- </refsection>
-
- <refsection>
- <title>Examples: 2.5Dish</title>
- <para>Note this is not a true intersection, compare to the same example using <xref linkend="ST_3DIntersection" />.</para>
- <programlisting>
-select ST_AsText(ST_Intersection(linestring, polygon)) As wkt
-from ST_GeomFromText('LINESTRING Z (2 2 6,1.5 1.5 7,1 1 8,0.5 0.5 8,0 0 10)') AS linestring
- CROSS JOIN ST_GeomFromText('POLYGON((0 0 8, 0 1 8, 1 1 8, 1 0 8, 0 0 8))') AS polygon;
-
- st_astext
----------------------------------------
- LINESTRING Z (1 1 8,0.5 0.5 8,0 0 10)
- </programlisting>
- </refsection>
- <refsection>
- <title>See Also</title>
- <para><xref linkend="ST_3DIntersection" />, <xref linkend="ST_Difference"/>, <xref linkend="ST_Union"/>, <xref linkend="ST_Dimension"/>, <xref linkend="ST_Dump"/>, <xref linkend="ST_Force2D" />, <xref linkend="ST_SymDifference"/>, <xref linkend="ST_Intersects"/>, <xref linkend="ST_Multi"/></para>
- </refsection>
- </refentry>
-
<refentry id="ST_LineToCurve">
<refnamediv>
<refname>ST_LineToCurve</refname>
@@ -1964,54 +1686,6 @@ FROM (SELECT 'MULTIPOLYGON(((186 194,187 194,188 195,189 195,190 195,
</refsection>
</refentry>
- <refentry id="ST_MemUnion">
- <refnamediv>
- <refname>ST_MemUnion</refname>
-
- <refpurpose>Same as ST_Union, only memory-friendly (uses less memory
- and more processor time).</refpurpose>
- </refnamediv>
-
- <refsynopsisdiv>
- <funcsynopsis>
- <funcprototype>
- <funcdef>geometry <function>ST_MemUnion</function></funcdef>
- <paramdef><type>geometry set</type> <parameter>geomfield</parameter></paramdef>
- </funcprototype>
-
- </funcsynopsis>
- </refsynopsisdiv>
-
- <refsection>
- <title>Description</title>
-
- <para>Some useful description here.</para>
-
- <!-- optionally mention that this function uses indexes if appropriate -->
- <note>
- <para>Same as ST_Union, only memory-friendly (uses less memory
- and more processor time). This aggregate function works by unioning the geometries one at a time to previous result as opposed to
- ST_Union aggregate which first creates an array and then unions</para>
- </note>
-
- <para>&Z_support;</para>
- </refsection>
-
-
- <refsection>
- <title>Examples</title>
-
- <programlisting>See ST_Union</programlisting>
- </refsection>
-
- <!-- Optionally add a "See Also" section -->
- <refsection>
- <title>See Also</title>
-
- <para><xref linkend="ST_Union" /></para>
- </refsection>
- </refentry>
-
<refentry id="ST_MaximumInscribedCircle">
<refnamediv>
<refname>ST_MaximumInscribedCircle</refname>
@@ -2334,64 +2008,6 @@ geomtextrep
</refsection>
</refentry>
- <refentry id="ST_Node">
- <refnamediv>
- <refname>ST_Node</refname>
-
- <refpurpose>
-Nodes a set of linestrings.
- </refpurpose>
- </refnamediv>
-
- <refsynopsisdiv>
- <funcsynopsis>
- <funcprototype>
- <funcdef>geometry <function>ST_Node</function></funcdef>
- <paramdef><type>geometry </type> <parameter>geom</parameter></paramdef>
- </funcprototype>
-
- </funcsynopsis>
- </refsynopsisdiv>
-
- <refsection>
- <title>Description</title>
-
- <para>
-Fully node a set of linestrings using the least possible number of nodes
-while preserving all of the input ones.
- </para>
-
- <para>&Z_support;</para>
- <para>Performed by the GEOS module.</para>
- <para>Availability: 2.0.0</para>
-
- <para>
-Changed: 2.4.0 this function uses GEOSNode internally instead of GEOSUnaryUnion.
-This may cause the resulting linestrings to have a different order and direction compared to Postgis < 2.4.
- </para>
- </refsection>
- <refsection>
- <title>Examples</title>
- <programlisting>
-SELECT ST_AsText(
- ST_Node('LINESTRINGZ(0 0 0, 10 10 10, 0 10 5, 10 0 3)'::geometry)
- ) As output;
-output
------------
-MULTILINESTRING Z ((0 0 0,5 5 4.5),(5 5 4.5,10 10 10,0 10 5,5 5 4.5),(5 5 4.5,10 0 3))
- </programlisting>
- </refsection>
-
- <!-- Optionally add a "See Also" section -->
- <refsection>
- <title>See Also</title>
-
- <para>
- <xref linkend="ST_UnaryUnion" />
- </para>
- </refsection>
- </refentry>
-
<refentry id="ST_OffsetCurve">
<refnamediv>
<refname>ST_OffsetCurve</refname>
@@ -3311,611 +2927,6 @@ LINESTRING M (5 2 3.40282346638529e+38,3 8 29,6 20 1.5,7 25 49.5,10 10 3.4028234
</refsection>
</refentry>
- <refentry id="ST_Split">
- <refnamediv>
- <refname>ST_Split</refname>
- <refpurpose>Returns a collection of geometries resulting by splitting a geometry.</refpurpose>
- </refnamediv>
-
- <refsynopsisdiv>
- <funcsynopsis>
- <funcprototype>
- <funcdef>geometry <function>ST_Split</function></funcdef>
- <paramdef><type>geometry</type> <parameter>input</parameter></paramdef>
- <paramdef><type>geometry</type> <parameter>blade</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- </refsynopsisdiv>
-
- <refsection>
- <title>Description</title>
- <para>
- The function supports splitting a line by (multi)point, (multi)line or (multi)polygon boundary, a (multi)polygon by line. The returned geometry is always a collection.
- </para>
-
- <para>
- Think of this function as the opposite of ST_Union.
- Theoretically applying ST_Union to the elements of the returned collection
- should always yield the original geometry.
- </para>
-
- <para>Availability: 2.0.0 requires GEOS</para>
- <para>Enhanced: 2.2.0 support for splitting a line by a multiline, a multipoint or (multi)polygon boundary was introduced.</para>
- <para>Enhanced: 2.5.0 support for splitting a polygon by a multiline was introduced.</para>
-
- <note><para>To improve the robustness of ST_Split it may be convenient to <xref linkend="ST_Snap"/> the input to the blade in advance using a very low tolerance. Otherwise the internally used coordinate grid may cause tolerance problems, where coordinates of input and blade do not fall onto each other and the input is not being split correctly (see <ulink url="http://trac.osgeo.org/postgis/ticket/2192">#2192</ulink>).</para></note>
-
- <note><para>
-When a (multi)polygon is passed as as the blade, its linear component
-(the boundary) is used for cutting the input.
- </para></note>
-
- </refsection>
- <refsection>
- <title>Examples</title>
- <para>Polygon Cut by Line</para>
- <informaltable>
- <tgroup cols="2">
- <tbody>
- <row>
- <entry>
- <para>
- <informalfigure>
- <mediaobject>
- <imageobject>
- <imagedata fileref="images/st_split01.png" />
- </imageobject>
- <caption><para>Before Split</para></caption>
- </mediaobject>
- </informalfigure>
- </para>
- </entry>
- <entry>
- <para>
- <informalfigure>
- <mediaobject>
- <imageobject>
- <imagedata fileref="images/st_split02.png" />
- </imageobject>
- <caption><para>After split</para></caption>
- </mediaobject>
- </informalfigure>
- </para>
- </entry>
- </row>
- </tbody>
- </tgroup>
- </informaltable>
- <programlisting>
--- this creates a geometry collection consisting of the 2 halves of the polygon
--- this is similar to the example we demonstrated in ST_BuildArea
-SELECT ST_Split(circle, line)
-FROM (SELECT
- ST_MakeLine(ST_MakePoint(10, 10),ST_MakePoint(190, 190)) As line,
- ST_Buffer(ST_GeomFromText('POINT(100 90)'), 50) As circle) As foo;
-
--- result --
- GEOMETRYCOLLECTION(POLYGON((150 90,149.039264020162 80.2454838991936,146.193976625564 70.8658283817455,..), POLYGON(..)))
-
--- To convert to individual polygons, you can use ST_Dump or ST_GeometryN
-SELECT ST_AsText((ST_Dump(ST_Split(circle, line))).geom) As wkt
-FROM (SELECT
- ST_MakeLine(ST_MakePoint(10, 10),ST_MakePoint(190, 190)) As line,
- ST_Buffer(ST_GeomFromText('POINT(100 90)'), 50) As circle) As foo;
-
--- result --
-wkt
----------------
-POLYGON((150 90,149.039264020162 80.2454838991936,..))
-POLYGON((60.1371179574584 60.1371179574584,58.4265193848728 62.2214883490198,53.8060233744357 ..))
- </programlisting>
- <para>Multilinestring Cut by point</para>
- <informaltable>
- <tgroup cols="2">
- <tbody>
- <row>
- <entry>
- <para>
- <informalfigure>
- <mediaobject>
- <imageobject>
- <imagedata fileref="images/st_split03.png" />
- </imageobject>
- <caption><para>Before Split</para></caption>
- </mediaobject>
- </informalfigure>
- </para>
- </entry>
- <entry>
- <para>
- <informalfigure>
- <mediaobject>
- <imageobject>
- <imagedata fileref="images/st_split04.png" />
- </imageobject>
- <caption><para>After split</para></caption>
- </mediaobject>
- </informalfigure>
- </para>
- </entry>
- </row>
- </tbody>
- </tgroup>
- </informaltable>
- <programlisting>
-SELECT ST_AsText(ST_Split(mline, pt)) As wktcut
- FROM (SELECT
- ST_GeomFromText('MULTILINESTRING((10 10, 190 190), (15 15, 30 30, 100 90))') As mline,
- ST_Point(30,30) As pt) As foo;
-
-wktcut
-------
-GEOMETRYCOLLECTION(
- LINESTRING(10 10,30 30),
- LINESTRING(30 30,190 190),
- LINESTRING(15 15,30 30),
- LINESTRING(30 30,100 90)
-)
- </programlisting>
- </refsection>
- <refsection>
- <title>See Also</title>
- <para>
-<xref linkend="ST_AsText" />,
-<xref linkend="ST_BuildArea" />,
-<xref linkend="ST_CollectionExtract" />,
-<xref linkend="ST_Dump" />,
-<xref linkend="ST_GeometryN" />,
-<xref linkend="ST_Subdivide" />,
-<xref linkend="ST_Union" />
- </para>
- </refsection>
- </refentry>
-
- <refentry id="ST_SymDifference">
- <refnamediv>
- <refname>ST_SymDifference</refname>
-
- <refpurpose>Returns a geometry that represents the portions of A and B
- that do not intersect.</refpurpose>
- </refnamediv>
-
- <refsynopsisdiv>
- <funcsynopsis>
- <funcprototype>
- <funcdef>geometry <function>ST_SymDifference</function></funcdef>
- <paramdef><type>geometry </type> <parameter>geomA</parameter></paramdef>
- <paramdef><type>geometry </type> <parameter>geomB</parameter></paramdef>
- <paramdef choice="opt"><type>float8 </type> <parameter>gridSize</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- </refsynopsisdiv>
-
- <refsection>
- <title>Description</title>
-
- <para>Returns a geometry that represents the portions of A and B
- that do not intersect. It is called a symmetric difference because
- ST_SymDifference(A,B) = ST_SymDifference(B,A). One can think of this as ST_Union(geomA,geomB) - ST_Intersection(A,B).
- </para>
-
- <para>
-If a gridSize argument is provided, the inputs are
-snapped to a grid of the given size and all intersections are computed
-on that same grid. This method requires GEOS-3.9.0 or higher.
- </para>
-
- <para>Performed by the GEOS module</para>
-
- <para>Enhanced: 3.1.0 accept a gridSize parameter - requires GEOS >= 3.9.0</para>
-
- <para>&sfs_compliant; s2.1.1.3</para>
- <para>&sqlmm_compliant; SQL-MM 3: 5.1.21</para>
- <para>&Z_support; However it seems to only consider x y when
- doing the difference and tacks back on the Z-Index</para>
- </refsection>
-
-
- <refsection>
- <title>Examples</title>
-
- <informaltable>
- <tgroup cols="2">
- <tbody>
- <row>
- <entry>
- <para>
- <informalfigure>
- <mediaobject>
- <imageobject>
- <imagedata fileref="images/st_symdifference01.png" />
- </imageobject>
- <caption><para>The original linestrings shown together</para></caption>
- </mediaobject>
- </informalfigure>
- </para>
- </entry>
-
- <entry>
- <para><informalfigure>
- <mediaobject>
- <imageobject>
- <imagedata fileref="images/st_symdifference02.png" />
- </imageobject>
- <caption><para>The symmetric difference of the two linestrings</para></caption>
- </mediaobject>
- </informalfigure>
- </para>
- </entry>
- </row>
- </tbody>
- </tgroup>
-</informaltable>
-<programlisting>
---Safe for 2d - symmetric difference of 2 linestrings
-SELECT ST_AsText(
- ST_SymDifference(
- ST_GeomFromText('LINESTRING(50 100, 50 200)'),
- ST_GeomFromText('LINESTRING(50 50, 50 150)')
- )
-);
-
-st_astext
----------
-MULTILINESTRING((50 150,50 200),(50 50,50 100))
-</programlisting>
-
-<programlisting>
-
---When used in 3d doesn't quite do the right thing
-SELECT ST_AsEWKT(ST_SymDifference(ST_GeomFromEWKT('LINESTRING(1 2 1, 1 4 2)'),
- ST_GeomFromEWKT('LINESTRING(1 1 3, 1 3 4)')))
-
-st_astext
-------------
-MULTILINESTRING((1 3 2.75,1 4 2),(1 1 3,1 2 2.25))
- </programlisting>
- </refsection>
-
- <!-- Optionally add a "See Also" section -->
- <refsection>
- <title>See Also</title>
-
- <para><xref linkend="ST_Difference" />, <xref linkend="ST_Intersection" />, <xref linkend="ST_Union" /></para>
- </refsection>
-</refentry>
-
-
- <refentry id="ST_Subdivide">
- <refnamediv>
- <refname>ST_Subdivide</refname>
- <refpurpose>Returns a set of geometry where no geometry in the set has more than the specified number of vertices.</refpurpose>
- </refnamediv>
-
- <refsynopsisdiv>
- <funcsynopsis>
- <funcprototype>
- <funcdef>setof geometry <function>ST_Subdivide</function></funcdef>
- <paramdef><type>geometry</type> <parameter>geom</parameter></paramdef>
- <paramdef><type>integer</type> <parameter>max_vertices=256</parameter></paramdef>
- <paramdef choice="opt"><type>float8</type> <parameter>gridSize</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- </refsynopsisdiv>
-
- <refsection>
- <title>Description</title>
-
- <para>
- Divides geometry into parts until a part can be represented using no more than <code>max_vertices</code>.
- Point-in-polygon and other overlay operations are normally faster for indexed subdivided dataset:
- "miss" cases are faster to check as boxes for all parts typically cover smaller area than original geometry box,
- "hit" cases are faster because recheck operates on less points.
- <code>max_vertices</code> must be 5 or more, as 5 points are needed to represent a closed box.
- <code>gridSize</code> can be specified to have clipping work in fixed-precision space (requires GEOS-3.9.0+).
- </para>
- <para>Performed by the GEOS module.</para>
- <para>Availability: 2.2.0</para>
- <para>Enhanced: 2.5.0 reuses existing points on polygon split, vertex count is lowered from 8 to 5.</para>
- <para>Enhanced: 3.1.0 accept a gridSize parameter, requires GEOS >= 3.9.0 to use this new feature.</para>
- </refsection>
-
- <refsection>
- <title>Examples</title>
- <programlisting>-- Subdivide complex geometries in table, in place
-with complex_areas_to_subdivide as (
- delete from polygons_table
- where ST_NPoints(geom) > 255
- returning id, column1, column2, column3, geom
-)
-insert into polygons_table (fid, column1, column2, column3, geom)
- select
- fid, column1, column2, column3,
- ST_Subdivide(geom, 255) as geom
- from complex_areas_to_subdivide;
- </programlisting>
-
- <programlisting>-- Create a new subdivided table suitable for joining to the original
-CREATE TABLE subdivided_geoms AS
-SELECT pkey, ST_Subdivide(geom) AS geom
-FROM original_geoms;
- </programlisting>
-
- <informaltable>
- <tgroup cols="1">
- <tbody>
- <row>
- <entry><para><informalfigure>
- <mediaobject>
- <imageobject>
- <imagedata fileref="images/st_subdivide01.png" />
- </imageobject>
- <caption><para>Subdivide max 10 vertices</para></caption>
- </mediaobject>
- </informalfigure>
- <programlisting>SELECT row_number() OVER() As rn, ST_AsText(geom) As wkt
-FROM ( SELECT ST_SubDivide('POLYGON((132 10,119 23,85 35,68 29,66 28,49 42,32 56,22 64,32 110,40 119,36 150,
-57 158,75 171,92 182,114 184,132 186,146 178,176 184,179 162,184 141,190 122,
-190 100,185 79,186 56,186 52,178 34,168 18,147 13,132 10))'::geometry,10)) As f(geom);</programlisting>
-<screen> rn │ wkt
-────┼────────────────────────────────────────────────────────────────────────────────────────────────────────────────
- 1 │ POLYGON((119 23,85 35,68 29,66 28,32 56,22 64,29.8260869565217 100,119 100,119 23))
- 2 │ POLYGON((132 10,119 23,119 56,186 56,186 52,178 34,168 18,147 13,132 10))
- 3 │ POLYGON((119 56,119 100,190 100,185 79,186 56,119 56))
- 4 │ POLYGON((29.8260869565217 100,32 110,40 119,36 150,57 158,75 171,92 182,114 184,114 100,29.8260869565217 100))
- 5 │ POLYGON((114 184,132 186,146 178,176 184,179 162,184 141,190 122,190 100,114 100,114 184))</screen>
- </para></entry>
- </row>
- <row>
- <entry><para><informalfigure>
- <mediaobject>
- <imageobject>
- <imagedata fileref="images/st_subdivide02.png" />
- </imageobject>
- <caption><para>Useful in conjunction with ST_Segmentize(geography) to create additional vertices that can then be used for splitting.</para></caption>
- </mediaobject>
- </informalfigure>
- <programlisting>SELECT ST_AsText(ST_Subdivide(ST_Segmentize('LINESTRING(0 0, 85 85)'::geography,1200000)::geometry,8));</programlisting>
- <screen>
-LINESTRING(0 0,0.487578359029357 5.57659056746196,0.984542144675897 11.1527721155093,1.50101059639722 16.7281035483571,1.94532113630331 21.25)
-LINESTRING(1.94532113630331 21.25,2.04869538062779 22.3020741387339,2.64204641967673 27.8740533545155,3.29994062412787 33.443216802941,4.04836719489742 39.0084282520239,4.59890468420694 42.5)
-LINESTRING(4.59890468420694 42.5,4.92498503922732 44.5680389206321,5.98737409390639 50.1195229244701,7.3290919767674 55.6587646879025,8.79638749938413 60.1969505994924)
-LINESTRING(8.79638749938413 60.1969505994924,9.11375579533779 61.1785363177625,11.6558166691368 66.6648504160202,15.642041247655 72.0867690601745,22.8716627200212 77.3609628116894,24.6991785131552 77.8939011989848)
-LINESTRING(24.6991785131552 77.8939011989848,39.4046096622744 82.1822848017636,44.7994523421035 82.5156766227011)
-LINESTRING(44.7994523421035 82.5156766227011,85 85)</screen>
- </para></entry>
- </row>
- </tbody></tgroup></informaltable>
- </refsection>
- <refsection>
- <title>See Also</title>
- <para>
-<xref linkend="ST_AsText" />,
-<xref linkend="ST_ClipByBox2D" />,
-<xref linkend="ST_Segmentize" />,
-<xref linkend="ST_Split" />,
-<xref linkend="ST_NPoints" />
- </para>
- </refsection>
- </refentry>
-
-<refentry id="ST_Union">
- <refnamediv>
- <refname>ST_Union</refname>
- <refpurpose>Returns a geometry that represents the point-set union of
- the input 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>
- <paramdef><type>geometry</type> <parameter>g2</parameter></paramdef>
- </funcprototype>
- <funcprototype>
- <funcdef>geometry <function>ST_Union</function></funcdef>
- <paramdef><type>geometry</type> <parameter>g1</parameter></paramdef>
- <paramdef><type>geometry</type> <parameter>g2</parameter></paramdef>
- <paramdef><type>float8</type> <parameter>gridSize</parameter></paramdef>
- </funcprototype>
- <funcprototype>
- <funcdef>geometry <function>ST_Union</function></funcdef>
- <paramdef><type>geometry[]</type> <parameter>g1_array</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 geometry 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 and like most aggregates, it also ignores NULL geometries.</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. If any are NULL, then NULL is returned.</para>
-
- <para>
- For non-aggregate version, <code>gridSize</code> can be specified
- to work in fixed-precision space (requires GEOS-3.9.0+).
- </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>ST_Union will use the faster Cascaded Union algorithm described in <ulink
- url="http://blog.cleverelephant.ca/2009/01/must-faster-unions-in-postgis-14.html">http://blog.cleverelephant.ca/2009/01/must-faster-unions-in-postgis-14.html</ulink></para>
-
- <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>Enhanced: 3.1.0 accept a gridSize parameter - requires GEOS >= 3.9.0</para>
- <para>Changed: 3.0.0 does not depend on SFCGAL.</para>
- <para>Availability: 1.4.0 - ST_Union was enhanced. ST_Union(geomarray) was introduced and also faster aggregate collection in PostgreSQL.</para>
-
- <para>&sfs_compliant; s2.1.1.3</para>
- <note><para>Aggregate version is not explicitly defined in OGC SPEC.</para></note>
- <para>&sqlmm_compliant; SQL-MM 3: 5.1.19
- the z-index (elevation) when polygons are involved.</para>
- </refsection>
-
- <refsection>
- <title>Examples</title>
- <para>Aggregate example</para>
- <programlisting>
-SELECT stusps,
- ST_Union(f.geom) as singlegeom
-FROM sometable f
-GROUP BY stusps
- </programlisting>
- <para>Non-Aggregate example</para>
- <programlisting>
-select ST_AsText(ST_Union('POINT(1 2)' :: geometry, 'POINT(-2 3)' :: geometry))
-
-st_astext
-----------
-MULTIPOINT(-2 3,1 2)
-
-select ST_AsText(ST_Union('POINT(1 2)' :: geometry, 'POINT(1 2)' :: geometry))
-
-st_astext
-----------
-POINT(1 2)</programlisting>
-<para>3D example - sort of supports 3D (and with mixed dimensions!)</para>
-<programlisting>select ST_AsEWKT(ST_Union(geom))
-from (
- select 'POLYGON((-7 4.2,-7.1 4.2,-7.1 4.3, -7 4.2))'::geometry geom
- union all
- select 'POINT(5 5 5)'::geometry geom
- union all
- select 'POINT(-2 3 1)'::geometry geom
- union all
- select 'LINESTRING(5 5 5, 10 10 10)'::geometry geom
- ) as foo;
-
-st_asewkt
----------
-GEOMETRYCOLLECTION(POINT(-2 3 1),LINESTRING(5 5 5,10 10 10),POLYGON((-7 4.2 5,-7.1 4.2 5,-7.1 4.3 5,-7 4.2 5)));
-</programlisting>
-<para>3d example not mixing dimensions</para>
-<programlisting>select ST_AsEWKT(ST_Union(geom))
-from (
- select 'POLYGON((-7 4.2 2,-7.1 4.2 3,-7.1 4.3 2, -7 4.2 2))'::geometry geom
- union all
- select 'POINT(5 5 5)'::geometry geom
- union all
- select 'POINT(-2 3 1)'::geometry geom
- union all
- select 'LINESTRING(5 5 5, 10 10 10)'::geometry geom
- ) as foo;
-
-st_asewkt
----------
-GEOMETRYCOLLECTION(POINT(-2 3 1),LINESTRING(5 5 5,10 10 10),POLYGON((-7 4.2 2,-7.1 4.2 3,-7.1 4.3 2,-7 4.2 2)))
-
---Examples using new Array construct
-SELECT ST_Union(ARRAY(SELECT the_geom FROM sometable));
-
-SELECT ST_AsText(ST_Union(ARRAY[ST_GeomFromText('LINESTRING(1 2, 3 4)'),
- ST_GeomFromText('LINESTRING(3 4, 4 5)')])) As wktunion;
-
---wktunion---
-MULTILINESTRING((3 4,4 5),(1 2,3 4))
-
- </programlisting>
- </refsection>
- <refsection>
- <title>See Also</title>
- <para>
- <xref linkend="ST_Collect" />,
- <xref linkend="ST_UnaryUnion" />,
- <xref linkend="ST_Intersection" />,
- <xref linkend="ST_Difference" />
- <xref linkend="ST_SymDifference" />
- </para>
- </refsection>
- </refentry>
-
- <refentry id="ST_UnaryUnion">
- <refnamediv>
- <refname>ST_UnaryUnion</refname>
-
- <refpurpose>Like ST_Union, but working at the geometry component level.</refpurpose>
- </refnamediv>
-
- <refsynopsisdiv>
- <funcsynopsis>
- <funcprototype>
- <funcdef>geometry <function>ST_UnaryUnion</function></funcdef>
- <paramdef><type>geometry </type> <parameter>geom</parameter></paramdef>
- <paramdef choice="opt"><type>float8 </type> <parameter>gridSize</parameter></paramdef>
- </funcprototype>
-
- </funcsynopsis>
- </refsynopsisdiv>
-
- <refsection>
- <title>Description</title>
-
- <para>
- Unlike ST_Union, ST_UnaryUnion does dissolve boundaries
- between components of a multipolygon (invalid)
- and does perform union between the components of a
- geometrycollection.
- Each components of the input geometry is assumed to be
- valid, so you won't get a valid multipolygon out of a
- bow-tie polygon (invalid).
- </para>
-
- <para>
- You may use this function to node a set of linestrings.
- You may mix ST_UnaryUnion with ST_Collect to fine-tune
- how many geometries at once you want to dissolve to
- be nice on both memory size and CPU time, finding the
- balance between ST_Union and ST_MemUnion.
- </para>
-
- <para>
-If a gridSize argument is provided, the inputs are
-snapped to a grid of the given size and all intersections are computed
-on that same grid. This method requires GEOS-3.9.0 or higher.
- </para>
-
- <para>&Z_support;</para>
- <para>Enhanced: 3.1.0 accept a gridSize parameter - requires GEOS >= 3.9.0</para>
- <para>Availability: 2.0.0</para>
-
- </refsection>
-
-
- <!-- Optionally add a "See Also" section -->
- <refsection>
- <title>See Also</title>
-
- <para>
- <xref linkend="ST_Union" />,
- <xref linkend="ST_MemUnion" />,
- <xref linkend="ST_Collect" />,
- <xref linkend="ST_Node" />
- </para>
- </refsection>
- </refentry>
-
<refentry id="ST_VoronoiLines">
<refnamediv>
<refname>ST_VoronoiLines</refname>
-----------------------------------------------------------------------
Summary of changes:
doc/Makefile.in | 2 +-
doc/postgis.xml | 1 +
doc/reference.xml | 1 +
doc/reference_overlay.xml | 1013 +++++++++++++++++++++++++++++++++++++++++
doc/reference_processing.xml | 1015 +-----------------------------------------
5 files changed, 1029 insertions(+), 1003 deletions(-)
create mode 100644 doc/reference_overlay.xml
hooks/post-receive
--
PostGIS
More information about the postgis-tickets
mailing list