Relational functions use predicates to test for different types of spatial relationships. The tests achieve this by comparing the relationships between the following:
- The exteriors (E) of the geometries, which is all of the space not occupied by a geometry
- The interior (I) of the geometries, which is the space occupied by a geometry
- The boundary (B) of the geometries, which is the interface between a geometry's interior and exterior
Predicates test relationships. They return 1 or t (TRUE) if a comparison meets the function's criteria; otherwise, they return 0 or f (FALSE). Predicates that test for a spatial relationship compare pairs of geometry that can be a different type or dimension.
Predicates compare the x- and y-coordinates of the submitted geometries. The z-coordinates and measure values, if they exist, are ignored. Geometries that have z-coordinates or measures can be compared with those that do not.
The Dimensionally Extended 9 Intersection Model (DE-9IM) developed by Clementini, et al. dimensionally extends the 9 Intersection Model of Egenhofer and Herring. DE-9IM is a mathematical approach that defines the pair-wise spatial relationship between geometries of different types and dimensions. This model expresses spatial relationships among all types of geometry as pair-wise intersections of their interior, boundary, and exterior with consideration for the dimension of the resulting intersections.
Given geometries a and b, I(a), B(a), and E(a) represent the interior, boundary, and exterior of a, and I(b), B(b), and E(b) represent the interior, boundary, and exterior of b. The intersections of I(a), B(a), and E(a) with I(b), B(b), and E(b) produce a three-by-three matrix. Each intersection can result in geometries of different dimensions. For example, the intersection of the boundaries of two polygons could consist of a point and a linestring, in which case the dim (dimension) function would return the maximum dimension of 1.
The dim function returns a value of -1, 0, 1, or 2. The -1 corresponds to the null set that is returned when no intersection is found or dim(Ãƒ˜).
Interior | Boundary | Exterior | |
---|---|---|---|
Interior | dim(I(a) intersects I(b)) | dim(I(a) intersects B(b)) | dim(I(a) intersects E(b)) |
Boundary | dim(B(a) intersects I(b)) | dim(B(a) intersects B(b)) | dim(B(a) intersects E(b)) |
Exterior | dim(E(a) intersects I(b)) | dim(E(a) intersects B(b)) | dim(E(a) intersects E(b)) |
The results of the spatial relationship predicates can be understood or verified by comparing the results of the predicate with a pattern matrix that represents the acceptable values for the DE-9IM.
The pattern matrix contains the acceptable values for each of the intersection matrix cells. The possible pattern values are as follows:
T—An intersection must exist; dim = 0, 1, or 2
F—An intersection must not exist; dim = -1
*—It does not matter if an intersection exists or not; dim = -1, 0, 1, or 2
0—An intersection must exist and its maximum dimension must be 0; dim = 0
1—An intersection must exist and its maximum dimension must be 1; dim = 1
2—An intersection must exist and its maximum dimension must be 2; dim = 2
Each predicate has at least one pattern matrix, but some require more than one to describe the relationships of various geometry type combinations.
The pattern matrix of the ST_Within predicate for geometry combinations has the following form:
b | ||||
Interior | Boundary | Exterior | ||
Interior | T | * | F | |
a | Boundary | * | * | F |
Exterior | * | * | * |
Simply put, the ST_Within predicate returns TRUE when the interiors of both geometries intersect, and the interior and boundary of a does not intersect the exterior of b. All other conditions do not matter.
The sections below describe different predicates used for spatial relationships. In the diagrams in these sections, the first input geometry listed is shown in black and the second is depicted in orange.
ST_Contains
ST_Contains returns 1 or t (TRUE) if the second geometry is completely contained by the first geometry. The ST_Contains predicate returns the exact opposite result of the ST_Within predicate.
The pattern matrix of the ST_Contains predicate states that the interiors of both geometries must intersect and that the interior and boundary of the secondary (geometry b) must not intersect the exterior of the primary (geometry a).
b | ||||
Interior | Boundary | Exterior | ||
Interior | T | * | * | |
a | Boundary | * | * | * |
Exterior | F | F | * |
Using ST_Within or ST_Contains identifies only those geometries that fall entirely inside another geometry. This helps to eliminate features from your selection that could skew your results. In the example below, a traveling ice cream vendor wants to determine which neighborhoods contain the largest number of children (potential customers) so he can be sure to restrict his route to those areas. He compares polygons of designated neighborhoods to census tracts, which possess an attribute of total number of children under the age of 16.
Unless all the children living in census tract 1 and census tract 3 live in the slivers of land that fall within Westside, including these tracts in the selection could erroneously elevate the count of children in the Westside neighborhood. By specifying that only census tracts entirely within neighborhoods be included (ST_Within = 1), the ice cream man saves himself from potentially wasting his time in those portions of Westside and consequently losing money.
See ST_Contains for syntax and example.
ST_Crosses
ST_Crosses returns 1 or t (TRUE) if the intersection results in a geometry that has a dimension that is one less than the maximum dimension of the two source geometries and the intersection set is interior to both source geometries. ST_Crosses returns 1 or t (TRUE) for only ST_MultiPoint/ST_Polygon, ST_MultiPoint/ST_LineString, ST_Linestring/ST_LineString, ST_LineString/ST_Polygon, and ST_LineString/ST_MultiPolygon comparisons.
This ST_Crosses predicate pattern matrix applies to ST_MultiPoint/ST_LineString, ST_MultiPoint/ST_MultiLineString, ST_MultiPoint/ST_Polygon, ST_MultiPoint/ST_MultiPolygon, ST_LineString/ST_Polygon, and ST_LineString/ST_MultiPolygon. The matrix states that the interiors must intersect and that at least the interior of the primary (geometry a) must intersect the exterior of the secondary (geometry b).
b | ||||
Interior | Boundary | Exterior | ||
Interior | T | * | T | |
a | Boundary | * | * | * |
Exterior | * | * | * |
This ST_Crosses predicate matrix applies to ST_LineString/ST_LineString, ST_LineString/ST_MultiLineString, and ST_MultiLineString/ST_MultiLineString. The matrix states that the dimension of the intersection of the interiors must be 0 (intersect at a point). If the dimension of this intersection was 1 (intersect at a linestring), the ST_Crosses predicate would return FALSE, but the ST_Overlaps predicate would return TRUE.
b | ||||
Interior | Boundary | Exterior | ||
Interior | 0 | * | * | |
a | Boundary | * | * | * |
Exterior | * | * | * |
See ST_Crosses for syntax and example.
ST_Disjoint
Disjoint returns 1 or t (TRUE) if the intersection of the two geometries is an empty set. In other words, geometries are disjoint if they do not intersect one another.
The ST_Disjoint predicate's pattern matrix simply states that neither the interiors nor the boundaries of either geometry intersect.
b | ||||
Interior | Boundary | Exterior | ||
Interior | F | F | * | |
a | Boundary | F | F | * |
Exterior | * | * | * |
See ST_Disjoint for syntax and example.
ST_Equals
ST_Equals returns 1 or t (TRUE) if two geometries of the same type have identical x,y coordinate values. The first and second floors of an office building could have identical x,y coordinates and, therefore, be equal. ST_Equals can also identify whether two features were mistakenly placed one on top of the other.
The DE-9IM pattern matrix for equality ensures that the interiors intersect and that no part of the interior or boundary of either geometry intersects the exterior of the other.
b | ||||
Interior | Boundary | Exterior | ||
Interior | T | * | F | |
a | Boundary | * | * | F |
Exterior | F | F | * |
See ST_Equals for syntax and example.
ST_Intersects
ST_Intersects returns 1 or t (TRUE) if the intersection does not result in an empty set. ST_Intersects returns the exact opposite result of ST_Disjoint.
The ST_Intersects predicate will return TRUE if the conditions of any of the following pattern matrices returns TRUE.
The ST_Intersects predicate returns TRUE if the interiors of both geometries intersect.
b | ||||
Interior | Boundary | Exterior | ||
Interior | T | * | * | |
a | Boundary | * | * | * |
Exterior | * | * | * |
The ST_Intersects predicate returns TRUE if the interior of the first geometry intersects the boundary of the second geometry.
b | ||||
Interior | Boundary | Exterior | ||
Interior | * | T | * | |
a | Boundary | * | * | * |
Exterior | * | * | * |
The ST_Intersects predicate returns TRUE if the boundary of the first geometry intersects the interior of the second.
b | ||||
Interior | Boundary | Exterior | ||
Interior | * | * | * | |
a | Boundary | T | * | * |
Exterior | * | * | * |
The ST_Intersects predicate returns TRUE if the boundaries of either geometry intersect.
b | ||||
Interior | Boundary | Exterior | ||
Interior | * | * | * | |
a | Boundary | * | T | * |
Exterior | * | * | * |
See ST_Intersects for syntax and example.
ST_Overlaps
ST_Overlaps compares two geometries of the same dimension and returns 1 or t (TRUE) if their intersection set results in a geometry different from both but of the same dimension.
ST_Overlaps returns 1 or t (TRUE) only for geometries of the same dimension and only when their intersection set results in a geometry of the same dimension. In other words, if the intersection of two ST_Polygons results in an ST_Polygon, overlap returns 1 or t (TRUE).
This pattern matrix applies to ST_Polygon/ST_Polygon, ST_MultiPoint/ST_MultiPoint, and ST_MultiPolygon/ST_MultiPolygon overlays. For these combinations, the overlap predicate returns TRUE if the interior of both geometries intersects the other's interior and exterior.
b | ||||
Interior | Boundary | Exterior | ||
Interior | T | * | T | |
a | Boundary | * | * | * |
Exterior | T | * | * |
The following pattern matrix applies to ST_LineString/ST_LineString and ST_MultiLineString/ST_MultiLineString overlaps. In this case, the intersection of the geometries must result in a geometry that has a dimension of 1 (another ST_LineString or ST_MultiLineString). If the dimension of the intersection of the interiors had resulted in 0 (a point), the ST_Overlaps predicate would return FALSE; however, the ST_Crosses predicate would have returned TRUE.
b | ||||
Interior | Boundary | Exterior | ||
Interior | 1 | * | T | |
a | Boundary | * | * | * |
Exterior | T | * | * |
See ST_Overlaps for syntax and example.
ST_Relate
ST_Relate returns a value of 1 or t (TRUE) if the spatial relationship specified by the pattern matrix is valid. A value of 1 or t (TRUE) indicates that some sort of spatial relationship exists between the geometries.
If the interiors or boundaries of geometries a and b are related in any way, ST_Relate is true. Whether or not the exteriors of one geometry intersect the interior or boundary of the other is irrelevant.
b | ||||
Interior | Boundary | Exterior | ||
Interior | T | T | * | |
a | Boundary | T | T | * |
Exterior | * | * | * |
See ST_Relate for syntax and example.
ST_Touches
ST_Touches returns 1 or t (TRUE) if none of the points common to both geometries intersect the interiors of both geometries. At least one geometry must be an ST_LineString, ST_Polygon, ST_MultiLineString, or ST_MultiPolygon.
The pattern matrices show that the ST_Touches predicate returns TRUE when the interiors of the geometry do not intersect and the boundary of either geometry intersects the other's interior or boundary.
The ST_Touches predicate returns TRUE if the boundary of geometry b intersects the interior of a, but the interiors do not intersect.
b | ||||
Interior | Boundary | Exterior | ||
Interior | F | T | * | |
a | Boundary | * | * | * |
Exterior | * | * | * |
The ST_Touches predicate returns TRUE if the boundary of geometry a intersects the interior of b, but the interiors do not intersect.
b | ||||
Interior | Boundary | Exterior | ||
Interior | F | * | * | |
a | Boundary | T | * | * |
Exterior | * | * | * |
The ST_Touches predicate returns TRUE if the boundaries of both geometries intersect, but the interiors do not.
b | ||||
Interior | Boundary | Exterior | ||
Interior | F | * | * | |
a | Boundary | * | T | * |
Exterior | * | * | * |
See ST_Touches for syntax and example.
ST_Within
ST_Within returns 1 or t (TRUE) if the first geometry is completely within the second geometry. ST_Within tests for the exact opposite result of ST_Contains.
The ST_Within predicate pattern matrix states that the interiors of both geometries must intersect and that the interior and boundary of the primary geometry (geometry a) must not intersect the exterior of the secondary (geometry b).
b | ||||
Interior | Boundary | Exterior | ||
Interior | T | * | F | |
a | Boundary | * | * | F |
Exterior | * | * | * |
See ST_Within for syntax and example.