ST_Within
Précédent  7.11.1. Relations topologiques  Suivant

Nom

ST_Within — Tests si chaque point de A se trouve dans B, et que leurs intérieurs ont un point commun

Synopsis

boolean ST_Within(geometry A, geometry B);

Description

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

Pour que cette fonction ait un sens, les géométries sources doivent toutes deux avoir la même projection de coordonnées et le même SRID.

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

La relation within est réflexive : toute géométrie est à l'intérieur d'elle-même. La relation est antisymétrique : si ST_Within(A,B) = true et ST_Within(B,A) = true, alors les deux géométries doivent être topologiquement égales (ST_Equals(A,B) = true).

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

[Note]

Comme les intérieurs doivent avoir un point commun, une subtilité de la définition est que les lignes et les points situés entièrement dans la limite des polygones ou des lignes ne sont pas à l'intérieur de la géométrie. Pour plus de détails, voir Subtleties of OGC Covers, Contains, Within. Le prédicat ST_CoveredBy 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_Within.

Effectué par le module GEOS

Amélioration : 2.3.0 Amélioration du court-circuit PIP pour la géométrie étendue à 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 - a.Relate(b, 'T*F**F***')

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

Exemples

This example defines two concentric circles once in a CTE so the same inputs can be rendered and then reused in related predicate checks.

Code
WITH circles AS (
  SELECT ST_Buffer(center, 20) AS smallc,
         ST_Buffer(center, 40) AS bigc
  FROM (SELECT 'POINT(50 50)'::geometry AS center) AS p
)
SELECT smallc AS small_circle,
       bigc AS big_circle
FROM circles;
Export de raster
POLYGON((70 50,69.616 46.098,68.478 42.346,66.629 38.889,64.142 35.858,61.111 33.371,57.654 31.522,53.902 30.384,50 30,46.098 30.384,42.346 31.522,38.889 33.371,35.858 35.858,33.371 38.889,31.522 42.346,30.384 46.098,30 50,30.384 53.902,31.522 57.654,33.371 61.111,35.858 64.142,38.889 66.629,42.346 68.478,46.098 69.616,50 70,53.902 69.616,57.654 68.478,61.111 66.629,64.142 64.142,66.629 61.111,68.478 57.654,69.616 53.902,70 50)) | POLYGON((90 50,89.231 42.196,86.955 34.693,83.259 27.777,78.284 21.716,72.223 16.741,65.307 13.045,57.804 10.769,50 10,42.196 10.769,34.693 13.045,27.777 16.741,21.716 21.716,16.741 27.777,13.045 34.693,10.769 42.196,10 50,10.769 57.804,13.045 65.307,16.741 72.223,21.716 78.284,27.777 83.259,34.693 86.955,42.196 89.231,50 90,57.804 89.231,65.307 86.955,72.223 83.259,78.284 78.284,83.259 72.223,86.955 65.307,89.231 57.804,90 50))
Figure
Geometry figure for visual-st-within-01

Using the same circles, ST_Within is reflexive on each circle, false from the larger circle into the smaller one, and true for ST_Union only when the union does not extend beyond the larger circle.

Code
WITH circles AS (
  SELECT ST_Buffer(center, 20) AS smallc,
         ST_Buffer(center, 40) AS bigc
  FROM (SELECT 'POINT(50 50)'::geometry AS center) AS p
)
SELECT
  ST_Within(smallc, smallc) AS smallinsmall,
  ST_Within(smallc, bigc) AS smallinbig,
  ST_Within(bigc, smallc) AS biginsmall,
  ST_Within(ST_Union(smallc, bigc), bigc) AS unioninbig,
  ST_Within(bigc, ST_Union(smallc, bigc)) AS biginunion,
  ST_Equals(bigc, ST_Union(smallc, bigc)) AS bigisunion
FROM circles;
Export de raster
t | t | f | t | t | t
Figure
Geometry figure for visual-st-within-02