PostGIS
Description
Returns TRUE if geometry A contains geometry B. A contains B if and only if all points of B lie inside (i.e. in the interior or boundary of) A (or equivalently, no points of B lie in the exterior of A), and the interiors of A and B have at least one point in common.
In mathematical terms: [.emphasis]#ST_Contains(A, B) ⇔ (A ⋂ B = B) ∧ (Int(A) ⋂ Int(B) ≠ ∅) #
The contains relationship is reflexive: every geometry contains itself.
(In contrast, in the ST_ContainsProperly
predicate a geometry does not properly contain itself.)
The relationship is antisymmetric: if ST_Contains(A,B) = true and
ST_Contains(B,A) = true, then the two geometries must be
topologically equal (ST_Equals(A,B) = true).
ST_Contains is the converse of ST_Within. So,
ST_Contains(A,B) = ST_Within(B,A).
|
|
Performed by the GEOS module
Enhanced: 2.3.0 Enhancement to PIP short-circuit extended to support MultiPoints with few points. Prior versions only supported point in polygon.
|
|
| this is the "allowable" version that returns a boolean, not an integer. |
[.inlinemediaobject]
This method implements the
OGC Simple Features
Implementation Specification for SQL 1.1.
s2.1.1.2 // s2.1.13.3 - same as within(geometry B, geometry A)
This
method implements the SQL/MM specification.
SQL-MM 3: 5.1.31
Examples
ST_Contains returns TRUE in the following situations:
|
|
|
|
ST_Contains returns FALSE in the following situations:
|
|
Due to the interior intersection condition ST_Contains returns
FALSE in the following situations (whereas ST_Covers returns
TRUE):
|
|
-- A circle within a circle
SELECT ST_Contains(smallc, bigc) As smallcontainsbig,
ST_Contains(bigc,smallc) As bigcontainssmall,
ST_Contains(bigc, ST_Union(smallc, bigc)) as bigcontainsunion,
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
smallcontainsbig | bigcontainssmall | bigcontainsunion | bigisunion | bigcoversexterior | bigcontainsexterior
------------------+------------------+------------------+------------+-------------------+---------------------
f | t | t | t | t | f
-- Example demonstrating difference between contains and contains properly
SELECT ST_GeometryType(geomA) As geomtype, ST_Contains(geomA,geomA) AS acontainsa, ST_ContainsProperly(geomA, geomA) AS acontainspropa,
ST_Contains(geomA, ST_Boundary(geomA)) As acontainsba, ST_ContainsProperly(geomA, ST_Boundary(geomA)) As acontainspropba
FROM (VALUES ( ST_Buffer(ST_Point(1,1), 5,1) ),
( ST_MakeLine(ST_Point(1,1), ST_Point(-1,-1) ) ),
( ST_Point(1,1) )
) As foo(geomA);
geomtype | acontainsa | acontainspropa | acontainsba | acontainspropba
--------------+------------+----------------+-------------+-----------------
ST_Polygon | t | f | f | f
ST_LineString | t | f | f | f
ST_Point | t | t | f | f