ST_Contains
上一页  7.11.1. 拓扑关系  下一页

名称

ST_Contains — 测试 B 的每个点是否都位于 A 中，并且它们的内部是否有一个共同点

大纲

boolean ST_Contains(geometry geomA, geometry geomB);

描述

如果几何图形 A 包含几何图形 B，则返回 TRUE。当且仅当 B 的所有点都位于 A 内部（即在 A 的内部或边界中）时，A 包含 B（或者等效地，B 中没有点位于 A 的外部），并且 A 和 B 的内部至少有一个共同点。

用数学术语来说： ST_Contains(A, B) ⇔ (A ⋂ B = B) ∧ (Int(A) ⋂ Int(B) ≠ ∅)

包含关系是自反的：每个几何图形都包含其自身。 （相反，在ST_ContainsProperly谓词中，几何图形未正确包含自身。）该关系是反对称的：如果 ST_Contains(A,B) = true 且 ST_Contains(B,A) = true，则两个几何图形必须在拓扑上相等 ( ST_Equals(A,B) = true)。

ST_Contains 与 ST_Within相反。 因此，ST_Contains(A,B) = ST_Within(B,A)。

[注意]

因为内部必须有一个公共点，所以定义的一个微妙之处是多边形和线不包含完全位于其边界内的线和点。 有关更多详细信息，请参阅 OGC涵盖、包含、内部的微妙之处。 ST_Covers 谓词提供了更具包容性的关系。

[注意]

此功能自动包括利用几何上可用的任何空间索引的边界框比较。 要避免使用索引，请使用函数 _ST_Contains。

它是通过GEOS模块实现的

增强：2.3.0 PIP 短路（快速判断仅限于多边形和点）已得到增强，以支持具有更少点的多点。 以前的版本仅支持面和点组合。

增强：3.0.0 启用了对 GEOMETRYCOLLECTION 的支持

[重要]

请勿将此函数用于无效的几何图形。 你会得到意想不到的结果。

注意：这是返回布尔值而不是整数的“允许”版本。

此方法实现了 SQL 1.1 的 OGC 简单功能规范。 s2.1.1.2 // s2.1.13.3 - 与内部相同（几何 B、几何 A）

该方法实现了SQL/MM规范。 SQL-MM 3: 5.1.31

示例

ST_Contains 在以下情况下返回 TRUE：

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;
栅格输出
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;
栅格输出
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;
栅格输出
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;
栅格输出
t
Figure
Geometry figure for visual-st-contains-04

ST_Contains 在以下情况下返回 FALSE：

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;
栅格输出
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;
栅格输出
f
Figure
Geometry figure for visual-st-contains-06

由于内部相交条件，ST_Contains 在以下情况下返回 FALSE（而 ST_Covers 返回 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;
栅格输出
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;
栅格输出
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;
栅格输出
-[ 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);
栅格输出
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