ST_Relate

Description

These functions allow testing and evaluating the spatial (topological) relationship between two geometries, as defined by the Dimensionally Extended 9-Intersection Model (DE-9IM).

The DE-9IM is specified as a 9-element matrix indicating the dimension of the intersections between the Interior, Boundary and Exterior of two geometries. It is represented by a 9-character text string using the symbols 'F', '0', '1', '2' (e.g. 'FF1FF0102' ).

A specific kind of spatial relationships is evaluated by comparing the intersection matrix to an intersection matrix pattern . A pattern can include the additional symbols 'T' and '*'. Common spatial relationships are provided by the named functions ST_Contains , ST_ContainsProperly , ST_Covers , ST_CoveredBy , ST_Crosses , ST_Disjoint , ST_Equals , ST_Intersects , ST_Overlaps , ST_Touches , and ST_Within . Using an explicit pattern allows testing multiple conditions of intersects, crosses, etc in one step. It also allows testing spatial relationships which do not have a named spatial relationship function. For example, the relationship "Interior-Intersects" has the DE-9IM pattern T******** , which is not evaluated by any named predicate.

For more information refer to Section 4.2.1, “Determining Spatial Relationships” .

Variant 1: Tests if two geometries are spatially related according to the given intersectionMatrixPattern .

Variant 2: Returns the DE-9IM matrix string for the spatial relationship between the two input geometries. The matrix string can be tested for matching a DE-9IM pattern using ST_RelateMatch .

Variant 3: Like variant 2, but allows specifying a Boundary Node Rule . A boundary node rule allows finer control over whether geometry boundary points are considered to lie in the DE-9IM Interior or Boundary. The boundaryNodeRule code is: 1: OGC/MOD2, 2: Endpoint, 3: MultivalentEndpoint, 4: MonovalentEndpoint.

This function is not in the OGC spec, but is implied. see s2.1.13.2

This method implements the OpenGIS Simple Features Implementation Specification for SQL 1.1. s2.1.1.2 // s2.1.13.3

This method implements the SQL/MM specification. SQL-MM 3: 5.1.25

Performed by the GEOS module

Enhanced: 2.0.0 - added support for specifying boundary node rule.

Examples

Using the boolean-valued function to test spatial relationships.

SELECT ST_Relate('POINT(1 2)', ST_Buffer( 'POINT(1 2)', 2), '0FFFFF212');
st_relate
-----------
t

SELECT ST_Relate(POINT(1 2)', ST_Buffer( 'POINT(1 2)', 2), '*FF*FF212');
st_relate
-----------
t

Testing a custom spatial relationship pattern as a query condition, with && to enable using a spatial index.

-- Find compounds that properly intersect (not just touch) a poly (Interior Intersects)

SELECT c.* , p.name As poly_name
    FROM polys AS p
    INNER JOIN compounds As c
          ON c.geom && p.geom
             AND ST_Relate(p.geom, c.geom,'T********');

Computing the intersection matrix for spatial relationships.

SELECT ST_Relate( 'POINT(1 2)',
                  ST_Buffer( 'POINT(1 2)', 2));
st_relate
-----------
0FFFFF212

SELECT ST_Relate( 'LINESTRING(1 2, 3 4)',
                  'LINESTRING(5 6, 7 8)' );
st_relate
-----------
FF1FF0102

See Also

Section 4.2.1, “Determining Spatial Relationships” , ST_RelateMatch , ST_Contains , ST_ContainsProperly , ST_Covers , ST_CoveredBy , ST_Crosses , ST_Disjoint , ST_Equals , ST_Intersects , ST_Overlaps , ST_Touches , ST_Within