ST_Contains
Précédent  7.11.1. Relations topologiques  Suivant

Nom

ST_Contains — Tests si chaque point de B est situé dans A, et que leurs intérieurs ont un point commun

Synopsis

boolean ST_Contains(geometry geomA, geometry geomB);

Description

Renvoie TRUE si la géométrie A contient la géométrie B. A contient B si et seulement si tous les points de B se trouvent à l'intérieur (c'est-à-dire à l'intérieur ou à la limite) de A (ou, de manière équivalente, si aucun point de B ne se trouve à l'extérieur de A), et si les intérieurs de A et de B ont au moins un point en commun.

En termes mathématiques : ST_Contains(A, B) ⇔ (A ⋂ B = B) ∧ (Int(A) ⋂ Int(B) ≠ ∅).

La relation contains est réflexive : toute géométrie se contient elle-même. (En revanche, dans le prédicat ST_ContainsProperly, une géométrie ne se contientpas elle-même correctement). La relation est antisymétrique : si ST_Contains(A,B) = true et ST_Contains(B,A) = true, alors les deux géométries doivent être topologiquement égales (ST_Equals(A,B) = true).

ST_Contains est le contraire de ST_Within. Ainsi, ST_Contains(A,B) = ST_Within(B,A).

[Note]

Comme les intérieurs doivent avoir un point commun, une subtilité de la définition est que les polygones et les lignes ne contiennent pas de lignes et de points se trouvant entièrement dans leur limite. Pour plus de détails, voir Subtleties of OGC Covers, Contains, Within. Le prédicat ST_Covers fournit une relation plus inclusive.

[Note]

Cette fonction inclut une comparaison de la boîte englobante qui utilise tous les index disponibles sur les géométries. Pour éviter l'utilisation d'un index, utilisez la fonction _ST_Contains.

Effectué par le module GEOS

Amélioré : 2.3.0 Amélioration du court-circuit PIP étendu à la prise en charge des multipoints avec peu de points. Les versions précédentes ne prenaient en charge que les points dans les polygones.

Amélioration : 3.0.0 a permis la prise en charge de GEOMETRYCOLLECTION

[Important]

N'utilisez pas cette fonction avec des géométries non valides. Vous obtiendrez des résultats inattendus.

NOTE : il s'agit de la version "autorisée" qui renvoie un booléen et non un entier.

Cette méthode implémente la spécification OGC Simple Features Implementation Specification for SQL 1.1. s2.1.1.2 // s2.1.13.3 - identique à within(geometry B, geometry A)

Cette méthode implémente la spécification SQL/MM. SQL-MM 3: 5.1.31

Exemples

ST_Contains renvoie TRUE dans les situations suivantes :

A LineString contains a MultiPoint whose points lie in its interior or boundary.

Code
SELECT ST_Contains(a, b)
FROM (SELECT
  'LINESTRING (10 190,60 80,130 120,190 10)'::geometry AS a,
  'MULTIPOINT (60 80,190 10)'::geometry AS b
) AS example;
Export de raster
t
Figure
Geometry figure for visual-st-contains-01

A Polygon contains a Point in its interior.

Code
SELECT ST_Contains(a, b)
FROM (SELECT
  'POLYGON ((10 130,50 190,110 190,140 150,150 80,100 10,20 40,10 130))'::geometry AS a,
  'POINT (99 130)'::geometry AS b
) AS example;
Export de raster
t
Figure
Geometry figure for visual-st-contains-02

A Polygon contains a LineString with interior points inside the Polygon.

Code
SELECT ST_Contains(a, b)
FROM (SELECT
  'POLYGON ((10 130,50 190,110 190,140 150,150 80,100 10,20 40,10 130))'::geometry AS a,
  'LINESTRING (50 190,110 190,99 130)'::geometry AS b
) AS example;
Export de raster
t
Figure
Geometry figure for visual-st-contains-03

A Polygon contains another Polygon in its interior.

Code
SELECT ST_Contains(a, b)
FROM (SELECT
  'POLYGON ((10 130,50 190,110 190,140 150,150 80,100 10,20 40,10 130))'::geometry AS a,
  'POLYGON ((70 40,100 50,120 80,80 110,50 90,70 40))'::geometry AS b
) AS example;
Export de raster
t
Figure
Geometry figure for visual-st-contains-04

La ST_Contains renvoie FALSE dans les situations suivantes :

A Polygon does not contain a MultiPoint when one point lies in a hole.

Code
SELECT ST_Contains(a, b)
FROM (SELECT
  'POLYGON ((10 130,50 190,110 190,140 150,150 80,100 10,20 40,10 130),(70 40,100 50,120 80,80 110,50 90,70 40))'::geometry AS a,
  'MULTIPOINT (99 130,87 70)'::geometry AS b
) AS example;
Export de raster
f
Figure
Geometry figure for visual-st-contains-05

A Polygon does not contain a LineString extending outside it.

Code
SELECT ST_Contains(a, b)
FROM (SELECT
  'POLYGON ((10 130,50 190,110 190,140 150,150 80,100 10,20 40,10 130))'::geometry AS a,
  'LINESTRING (99 130,170 131)'::geometry AS b
) AS example;
Export de raster
f
Figure
Geometry figure for visual-st-contains-06

En raison de la condition d'intersection intérieure, la ST_Contains renvoie FALSE dans les situations suivantes (alors que la ST_Covers renvoie TRUE) :

A LineString does not contain a Point lying only on its boundary.

Code
SELECT ST_Contains(a, b), ST_Covers(a, b)
FROM (SELECT
  'LINESTRING (10 190,60 80,130 120,190 10)'::geometry AS a,
  'POINT (190 10)'::geometry AS b
) AS example;
Export de raster
f | t
Figure
Geometry figure for visual-st-contains-07

A Polygon does not contain a LineString lying entirely on its boundary.

Code
SELECT ST_Contains(a, b), ST_Covers(a, b)
FROM (SELECT
  'POLYGON ((10 130,50 190,110 190,140 150,150 80,100 10,20 40,10 130))'::geometry AS a,
  'LINESTRING (80 190,110 190,140 150,150 80)'::geometry AS b
) AS example;
Export de raster
f | t
Figure
Geometry figure for visual-st-contains-08

This example tests a circle within another circle.

Code
WITH circles AS (
  SELECT ST_Buffer(center, 10) AS smallc,
         ST_Buffer(center, 20) AS bigc
  FROM (SELECT 'POINT(1 2)'::geometry AS center) AS p
)
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 circles;
Export de raster
-[ RECORD 1 ]-----
smallcontainsbig   | f
bigcontainssmall   | t
bigcontainsunion   | t
bigisunion         | t
bigcoversexterior  | t
bigcontainsexterior | f
Figure
Geometry figure for visual-st-contains-09

This example demonstrates the difference between contains and contains-properly predicates.

Code
SELECT
  ST_GeometryType(geom_a) AS geomtype,
  ST_Contains(geom_a, geom_a) AS acontainsa,
  ST_ContainsProperly(geom_a, geom_a) AS acontainspropa,
  ST_Contains(geom_a, ST_Boundary(geom_a)) AS acontainsba,
  ST_ContainsProperly(geom_a, ST_Boundary(geom_a)) 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(geom_a);
Export de raster
geomtype    | acontainsa | acontainspropa | acontainsba | acontainspropba
--------------+------------+----------------+-------------+-----------------
ST_Polygon    | t          | f              | f           | f
ST_LineString | t          | f              | f           | f
ST_Point      | t          | t              | f           | f
Figure
Geometry figure for visual-st-contains-10