From: Regina Obe Date: Mon, 20 Oct 2008 17:25:00 +0000 (+0000) Subject: Move over ST_Covers and ST_CoveredBy and provide examples, update ST_Contains example... X-Git-Tag: 1.4.0b1~596 X-Git-Url: https://granicus.if.org/sourcecode?a=commitdiff_plain;h=5c25a01749fb550bfd42d8e0447b6cc5689fe653;p=postgis Move over ST_Covers and ST_CoveredBy and provide examples, update ST_Contains example to show distinction between ST_Covers, ST_Contains etc. git-svn-id: http://svn.osgeo.org/postgis/trunk@3154 b70326c6-7e19-0410-871a-916f4a2858ee --- diff --git a/doc/reference.xml b/doc/reference.xml index 0d4487ae3..34dd4d02a 100644 --- a/doc/reference.xml +++ b/doc/reference.xml @@ -23,37 +23,6 @@ Geometry Relationship Functions - - ST_Covers(geometry A, geometry B) - - - Returns 1 (TRUE) if no point in Geometry B is outside - Geometry A - - Refer to - http://lin-ear-th-inking.blogspot.com/2007/06/subtleties-of-ogc-covers-spatial.html - for an explanation of the need of this function. - - This function call will automatically include a bounding box - comparison that will make use of any indexes that are available on - the geometries. To avoid index use, use the function - _ST_Covers. - - - - - ST_CoveredBy(geometry A, geometry B) - - - Returns 1 (TRUE) if no point in Geometry A is outside - Geometry B - - Refer to - http://lin-ear-th-inking.blogspot.com/2007/06/subtleties-of-ogc-covers-spatial.html - for an explanation of the need of this function. - - - ST_Relate(geometry, geometry, intersectionPatternMatrix) diff --git a/doc/reference_new.xml b/doc/reference_new.xml index b2d61cc51..8ff83164d 100644 --- a/doc/reference_new.xml +++ b/doc/reference_new.xml @@ -4967,11 +4967,11 @@ degaz degazrev - + ST_Contains - Returns true if the geometry B is completely inside geometry A + Returns true if the geometry B is completely inside geometry A. @@ -4980,10 +4980,10 @@ degaz degazrev boolean ST_Contains geometry - A + geomA geometry - B + geomB @@ -5033,33 +5033,186 @@ degaz degazrev This method implements the SQL/MM specification: SQL-MM 3: 5.1.31 + + There are certain subtleties to ST_Contains and ST_Within that are not intuitively obvious. + For details check out Subtleties of OGC Covers, Contains, Within Examples --a circle within a circle - SELECT ST_Contains(smallc,smallc) As smallinsmall, - ST_Contains(smallc, bigc) As smallcontainsbig, + SELECT ST_Contains(smallc, bigc) As smallcontainsbig, ST_Contains(bigc,smallc) As bigcontainssmall, - ST_Contains(ST_Union(smallc, bigc), bigc) as unioncontainsbig, ST_Contains(bigc, ST_Union(smallc, bigc)) as bigcontainsunion, - ST_Equals(bigc, ST_Union(smallc, bigc)) as bigisunion + ST_Equals(bigc, ST_Union(smallc, bigc)) as bigisunion, + ST_Covers(bigc, ST_ExteriorRing(bigc)) As bigcoversexterior, + ST_Contains(bigc, ST_ExteriorRing(bigc)) As bigcontainsexterior FROM (SELECT ST_Buffer(ST_GeomFromText('POINT(1 2)'), 10) As smallc, ST_Buffer(ST_GeomFromText('POINT(1 2)'), 20) As bigc) As foo; --Result - smallinsmall | smallcontainsbig | bigcontainssmall | unioncontainsbig | bigcontainsunion | bigisunion ---------------+------------------+------------------+------------------+------------------+------------ - t | f | t | t | t | t - + smallcontainsbig | bigcontainssmall | bigcontainsunion | bigisunion | bigcoversexterior | bigcontainsexterior +------------------+------------------+------------------+------------+-------------------+--------------------- + f | t | t | t | t | f See Also - , + ,, , - - + + + + + ST_Covers + + Returns 1 (TRUE) if no point in Geometry B is outside + Geometry A + + + + + + boolean ST_Covers + + geometry + geomA + + geometry + geomB + + + + + + Description + + Returns 1 (TRUE) if no point in Geometry B is outside + Geometry A + + Performed by the GEOS module + + + Do not call with a GEOMETRYCOLLECTION as an argument + + + + Do not use this function with invalid geometries. You will get unexpected results. + + + This function call will automatically include a bounding box + comparison that will make use of any indexes that are available on + the geometries. To avoid index use, use the function + _ST_Covers. + + Availability: 1.2.2 + + NOTE: this is the "allowable" version that returns a + boolean, not an integer. + + Not an OGC standard, but Oracle has it too. + There are certain subtleties to ST_Contains and ST_Within that are not intuitively obvious. + For details check out Subtleties of OGC Covers, Contains, Within + + + + Examples + + --a circle covering a circle +SELECT ST_Covers(smallc,smallc) As smallinsmall, + ST_Covers(smallc, bigc) As smallcoversbig, + ST_Covers(bigc, ST_ExteriorRing(bigc)) As bigcoversexterior, + ST_Contains(bigc, ST_ExteriorRing(bigc)) As bigcontainsexterior +FROM (SELECT ST_Buffer(ST_GeomFromText('POINT(1 2)'), 10) As smallc, + ST_Buffer(ST_GeomFromText('POINT(1 2)'), 20) As bigc) As foo; + --Result + smallinsmall | smallcoversbig | bigcoversexterior | bigcontainsexterior +--------------+----------------+-------------------+--------------------- + t | f | t | f +(1 row) + + + + See Also + , , + + + + + + ST_CoveredBy + + Returns 1 (TRUE) if no point in Geometry B is outside + Geometry A + + + + + + boolean ST_CoveredBy + + geometry + geomA + + geometry + geomB + + + + + + Description + + Returns 1 (TRUE) if no point in Geometry A is outside + Geometry B + + Performed by the GEOS module + + + Do not call with a GEOMETRYCOLLECTION as an argument + + + + Do not use this function with invalid geometries. You will get unexpected results. + + Availability: 1.2.2 + + This function call will automatically include a bounding box + comparison that will make use of any indexes that are available on + the geometries. To avoid index use, use the function + _ST_CoveredBy. + + NOTE: this is the "allowable" version that returns a + boolean, not an integer. + + Not an OGC standard, but Oracle has it too. + There are certain subtleties to ST_Contains and ST_Within that are not intuitively obvious. + For details check out Subtleties of OGC Covers, Contains, Within + + + + Examples + + --a circle coveredby a circle +SELECT ST_CoveredBy(smallc,smallc) As smallinsmall, + ST_CoveredBy(smallc, bigc) As smallcoveredbybig, + ST_CoveredBy(ST_ExteriorRing(bigc), bigc) As exteriorcoveredbybig, + ST_Within(ST_ExteriorRing(bigc),bigc) As exeriorwithinbig +FROM (SELECT ST_Buffer(ST_GeomFromText('POINT(1 2)'), 10) As smallc, + ST_Buffer(ST_GeomFromText('POINT(1 2)'), 20) As bigc) As foo; + --Result + smallinsmall | smallcoveredbybig | exteriorcoveredbybig | exeriorwithinbig +--------------+-------------------+----------------------+------------------ + t | t | t | f +(1 row) + + + + See Also + , , , + + + ST_Crosses