From: Regina Obe Date: Wed, 1 Oct 2008 21:53:01 +0000 (+0000) Subject: Moved some functions to Geometry Processing section X-Git-Tag: 1.4.0b1~677 X-Git-Url: https://granicus.if.org/sourcecode?a=commitdiff_plain;h=4ff152c69b7618fb672c7fee3c7b41ca0615f94b;p=postgis Moved some functions to Geometry Processing section git-svn-id: http://svn.osgeo.org/postgis/trunk@3038 b70326c6-7e19-0410-871a-916f4a2858ee --- diff --git a/doc/reference_new.xml b/doc/reference_new.xml index f597b47b3..0fb24fb2b 100644 --- a/doc/reference_new.xml +++ b/doc/reference_new.xml @@ -812,343 +812,30 @@ Check constraints: See Also , - - - - - ST_Buffer - - 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). - - - - - - geometry ST_Buffer - geometry g1 - float radius_of_buffer - - - - geometry ST_Buffer - geometry g1 - float radius_of_buffer - integer num_seg_quarter_circle - - - - - - - Description - - 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). - - Units are always measured in units of the spatial reference system. - The inputs can be POINTS, MULTIPOINTS, LINESTRINGS, MULTILINESTRINGS, POLYGONS, MULTIPOLYGONS, and GeometryCollections. - This function ignores the third dimension (z) and will always give a 2-d buffer even when presented with a 3d-geometry. - - Performed by the GEOS module. - - - - - - - This method implements the OpenGIS Simple Features - Implementation Specification for SQL. - OGC SPEC s2.1.1.3 - - - - - - - This method implements the SQL/MM specification: - SQL-MM 3: 5.1.17 - - 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 instead. - - - - Examples - ---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)) - - - - - - - See Also - - , , , , - - - - - - ST_BuildArea - - Creates an areal geometry formed by the constituent linework - of given geometry - - - - - - boolean ST_BuildArea - geometry A - - - - - - Description - - 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. - - This function will assume all inner geometries represent holes - Availability: 1.1.0 - requires GEOS >= 2.1.0. - - - - Examples - - --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 - - - - See Also - - - , - wrappers to - this function with standard OGC interface - - + + - ST_Collect - Return a specified ST_Geometry value from a collection of other geometries. + ST_GeomFromEWKB + Return a specified ST_Geometry value from Extended Well-Known Binary representation (EWKB). - geometry ST_Collect - geometry set g1field - - - geometry ST_Collect - geometry g1 - geometry g2 + geometry ST_GeomFromEWKB + bytea EWKB Description - 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. - - 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. - - Non-Aggregate version: This function returns a geometry being a collection of two - input geometries. Output type can be a MULTI* or a - GEOMETRYCOLLECTION. - - 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 to expand the - MULTIs out to singles and then regroup them. - - - - Examples - Aggregate example - 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 - Non-Aggregate example - 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) - - - See Also - , - - - - - - ST_Dump - Returns a set of - geometry_dump rows, formed by a geometry (geom). - - - - - - geometry_dump[]ST_Dump - geometry g1 - - - - - - Description - 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. - - 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. - - Availability: PostGIS 1.0.0RC1. Requires PostgreSQL 7.3 or - higher. - - - - Examples - SELECT sometable.field1, sometable.field1, - (ST_Dump(sometable.the_geom)).geom As the_geom -FROM sometable - - - See Also - - - - - - - ST_GeomFromEWKB - Return a specified ST_Geometry value from Extended Well-Known Binary representation (EWKB). - - - - - - geometry ST_GeomFromEWKB - bytea EWKB - - - - - - Description - Constructs a PostGIS ST_Geometry object from the OGC Extended Well-Known binary (EWKT) representation. - - The EWKB format is not an OGC standard, but a PostGIS specific format that includes the spatial reference system (SRID) - identifier - + Constructs a PostGIS ST_Geometry object from the OGC Extended Well-Known binary (EWKT) representation. + + The EWKB format is not an OGC standard, but a PostGIS specific format that includes the spatial reference system (SRID) + identifier + @@ -1553,113 +1240,7 @@ result , , - - - - ST_MakePolygon - - Creates a Polygon formed by the given shell. Input - geometries must be closed LINESTRINGS. - - - - - - geometry ST_MakePolygon - geometry linestring - - - - - geometry ST_MakePolygon - geometry outerlinestring - geometry[] interiorlinestrings - - - - - - Description - - Creates a Polygon formed by the given shell. Input - geometries must be closed LINESTRINGS. Comes in 2 variants. - Variant 1: takes one closed linestring. - 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. - - This function will not accept a MULTILINESTRING. Use or to generate line strings. - - - - - - Examples: Single closed LINESTRING - -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 - - - - Examples: Outter shell with inner shells - - Build a donut with an ant hole - -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; - - 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 - The use of CASE because feeding a null array into - ST_MakePolygon results in NULL - the use of left join to guarantee we get all provinces back even if they have no lakes - - 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; - - - - See Also - , , , , - - + ST_PointFromText @@ -1729,117 +1310,23 @@ SELECT ST_PointFromText('POINT(-71.064544 42.28787)', 4326); , , - - - ST_Union - Returns a geometry that represents the point set union of - the Geometries. - - - - - - geometry ST_Union - geometry set g1field - - - geometry ST_Union - geometry g1 - - - - - Description - 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. - - 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. - - 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. - - 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. - - Performed by the GEOS module. - NOTE: this function was formerly called GeomUnion(), which - was renamed from "Union" because UNION is an SQL reserved - word. - - - - - - This method implements the OpenGIS Simple Features - Implementation Specification for SQL: OGC SPEC s2.1.1.3 - - - - - - This method implements the SQL/MM specification: - SQL-MM 3: 5.1.19 - - Aggregate version is not explicitly defined in OGC SPEC. - - - - Examples - Aggregate example - -SELECT stusps, - ST_Multi(ST_Union(f.the_geom)) as singlegeom - FROM sometable As f -GROUP BY stusps - - Non-Aggregate example - -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) - - - - See Also - - - - - - ST_WKTToSQL - Return a specified ST_Geometry value from Well-Known Text representation (WKT). This is an alias name for ST_GeomFromText - - - - - geometry ST_WKTToSQL - text WKT - - - - - Description - + + + ST_WKTToSQL + Return a specified ST_Geometry value from Well-Known Text representation (WKT). This is an alias name for ST_GeomFromText + + + + + geometry ST_WKTToSQL + text WKT + + + + + Description + @@ -5117,107 +4604,623 @@ FROM (SELECT ST_Buffer(ST_GeomFromText('POINT(1 2)'), 10) As smallc, Geometry Processing Functions - + - ST_Intersection - - Returns a geometry that represents the shared portion of geomA and geomB - + ST_Buffer + + 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). + - - geometry ST_Intersection - - geometry - geomA - - - geometry - geomB - - + + geometry ST_Buffer + geometry g1 + float radius_of_buffer + + + + geometry ST_Buffer + geometry g1 + float radius_of_buffer + integer num_seg_quarter_circle + + - + + Description - Returns a geometry that represents the point set - intersection of the Geometries. - - In other words - that portion of geometry A and geometry B - that is shared between the two geometries. - - If the geometries do not share any space (are disjoint), then an empty geometry collection - is returned. - 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. - - - Do not call with a GEOMETRYCOLLECTION as an argument - - - Performed by the GEOS module - - - - - This method implements the - OpenGIS Simple - Features Implementation Specification for SQL OGC SPEC s2.1.1.3 + + 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). + Units are always measured in units of the spatial reference system. + The inputs can be POINTS, MULTIPOINTS, LINESTRINGS, MULTILINESTRINGS, POLYGONS, MULTIPOLYGONS, and GeometryCollections. + This function ignores the third dimension (z) and will always give a 2-d buffer even when presented with a 3d-geometry. + + Performed by the GEOS module. + + + + + + + This method implements the OpenGIS Simple Features + Implementation Specification for SQL. + OGC SPEC s2.1.1.3 - This method implements the SQL/MM specification: SQL-MM 3: 5.1.18 + This method implements the SQL/MM specification: + SQL-MM 3: 5.1.17 + + 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 instead. - + + + Examples + +--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)) + + + + + + + See Also + + , , , , + + + + + + ST_BuildArea + + Creates an areal geometry formed by the constituent linework + of given geometry + + + + + + boolean ST_BuildArea + geometry A + + + + + + Description + + 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. + + This function will assume all inner geometries represent holes + Availability: 1.1.0 - requires GEOS >= 2.1.0. + + + Examples -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) + + --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)); - - - - See Also - , , , - - - +--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 + + + + See Also + + + , + wrappers to + this function with standard OGC interface + + + + + ST_Collect + Return a specified ST_Geometry value from a collection of other geometries. + + + + + + geometry ST_Collect + geometry set g1field + + + geometry ST_Collect + geometry g1 + geometry g2 + + + + + + Description + 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. + + 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. + + Non-Aggregate version: This function returns a geometry being a collection of two + input geometries. Output type can be a MULTI* or a + GEOMETRYCOLLECTION. + + 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 to expand the + MULTIs out to singles and then regroup them. + + + + Examples + Aggregate example + 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 + Non-Aggregate example + 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) + + + See Also + , + + + + + + ST_Dump + Returns a set of + geometry_dump rows, formed by a geometry (geom). + + + + + + geometry_dump[]ST_Dump + geometry g1 + + + + + + Description + 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. + + 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. + + Availability: PostGIS 1.0.0RC1. Requires PostgreSQL 7.3 or + higher. + + + + Examples + SELECT sometable.field1, sometable.field1, + (ST_Dump(sometable.the_geom)).geom As the_geom +FROM sometable + + + See Also + + + + + + + ST_MakePolygon + + Creates a Polygon formed by the given shell. Input + geometries must be closed LINESTRINGS. + + + + + + geometry ST_MakePolygon + geometry linestring + + + + + geometry ST_MakePolygon + geometry outerlinestring + geometry[] interiorlinestrings + + + + + + Description + + Creates a Polygon formed by the given shell. Input + geometries must be closed LINESTRINGS. Comes in 2 variants. + Variant 1: takes one closed linestring. + 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. + + This function will not accept a MULTILINESTRING. Use or to generate line strings. + + + + + + Examples: Single closed LINESTRING + +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 + + + + Examples: Outter shell with inner shells + + Build a donut with an ant hole + +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; + + 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 + The use of CASE because feeding a null array into + ST_MakePolygon results in NULL + the use of left join to guarantee we get all provinces back even if they have no lakes + + 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; + + + + See Also + , , , , + + + + + + ST_Intersection + + Returns a geometry that represents the shared portion of geomA and geomB + + + + + + geometry ST_Intersection + + geometry + geomA + + + geometry + geomB + + + + + + Description + Returns a geometry that represents the point set + intersection of the Geometries. + + In other words - that portion of geometry A and geometry B + that is shared between the two geometries. + + If the geometries do not share any space (are disjoint), then an empty geometry collection + is returned. + 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. + + + Do not call with a GEOMETRYCOLLECTION as an argument + + + Performed by the GEOS module + + + + + This method implements the + OpenGIS Simple + Features Implementation Specification for SQL OGC SPEC s2.1.1.3 + + + + + + + + This method implements the SQL/MM specification: SQL-MM 3: 5.1.18 + + + Examples +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)); + + + + See Also + , , , + + + + + + ST_Union + Returns a geometry that represents the point set union of + the Geometries. + + + + + + geometry ST_Union + geometry set g1field + + + geometry ST_Union + geometry g1 + + + + + + Description + 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. + + 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. + + 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. + + 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. + + Performed by the GEOS module. + NOTE: this function was formerly called GeomUnion(), which + was renamed from "Union" because UNION is an SQL reserved + word. + + + + + + This method implements the OpenGIS Simple Features + Implementation Specification for SQL: OGC SPEC s2.1.1.3 + + + + + + This method implements the SQL/MM specification: + SQL-MM 3: 5.1.19 + + Aggregate version is not explicitly defined in OGC SPEC. + + + + Examples + Aggregate example + +SELECT stusps, + ST_Multi(ST_Union(f.the_geom)) as singlegeom + FROM sometable As f +GROUP BY stusps + + Non-Aggregate example + +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) + + + + See Also + + + + Linear Referencing