ST_Within
戻る  7.11.1. トポロジ関係関数  次へ

名前

ST_Within — Aの全てのポイントがB内にあり、かつ両方の内部が共有点を持つかどうかをテストします。

概要

boolean ST_Within(geometry A, geometry B);

説明

ジオメトリAがジオメトリB内にある場合にTRUEを返します。Aの全ての点がBの内側 (内部または境界)にあり、Aの内部とBの内部に少なくとも一つの共有点がある場合に限って、AはB内にあると言います。

渡すジオメトリが両方とも同じSRIDでなければ、この関数は意味がありません。

数学用語では: ST_Within(A, B) ⇔ (A ⋂ B = A) ∧ (Int(A) ⋂ Int(B) ≠ ∅)

内にある、という関係性には反射性があります。全てのジオメトリは、自分の内にあると言えます。また、非対称性を持ちます。ST_Within(A,B) = trueかつST_Within(B,A) = trueの場合には、二つのジオメトリは必ずトポロジ的に等価 (ST_Equals(A,B) = true)になります。

ST_WithinはST_Containsの反対です。ST_Within(A,B) = ST_Contains(B,A)となります。

[注記]

内部が必ず共有点を持つので、定義は、ポリゴンまたはラインの境界上にあるラインまたはポイントはジオメトリの内にないという微妙なものになります。詳細については、Subtleties of OGC Covers, Contains, Withinをご覧下さい。ST_CoveredBy述語はより包括的な関係を提供します。

[注記]

この関数を実行すると、対象ジオメトリにおいて使用できるインデックスを使用したバウンディングボックスによる比較が自動的に行われます。 インデックスの使用を避けるには_ST_Within関数を使います。

GEOSモジュールで実現しています。

Enhanced: 2.3.0 ジオメトリについて、PIP short-circuit (ポリゴンとポイントに限定した高速判定)を少ないポイントからなるマルチポイントに対応することができるよう拡張しました。以前の版ではポリゴンとポイントの組み合わせにだけ対応していました。

Enhanced: 3.0.0 GEOMETRYCOLLECTIONへの対応が可能となりました

[重要]

この関数を不正なジオメトリで呼ばないでください。予期しない結果が返されます。

ご注意: これは論理値を返して整数を返さないのが「許される」版です。

このメソッドはOGC Simple Features Implementation Specification for SQL 1.1の実装です。 s2.1.1.2 // s2.1.13.3 - a.Relate(b, 'T*F**F***')

このメソッドはSQL/MM仕様の実装です。 SQL-MM 3: 5.1.30

例

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;
出力:
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;
出力:
t | t | f | t | t | t
Figure
Geometry figure for visual-st-within-02