Geometric binary predicates on pairs of simple feature geometry sets

st_intersects(x, y, sparse = TRUE, ...)

st_disjoint(x, y = x, sparse = TRUE, prepared = TRUE)

st_touches(x, y, sparse = TRUE, prepared = TRUE, ...)

st_crosses(x, y, sparse = TRUE, prepared = TRUE, ...)

st_within(x, y, sparse = TRUE, prepared = TRUE, ...)

st_contains(x, y, sparse = TRUE, prepared = TRUE, ..., s2_model = "open")

st_contains_properly(x, y, sparse = TRUE, prepared = TRUE, ...)

st_overlaps(x, y, sparse = TRUE, prepared = TRUE, ...)

st_equals(x, y, sparse = TRUE, prepared = FALSE, ...)

st_covers(x, y, sparse = TRUE, prepared = TRUE, ..., s2_model = "closed")

  y = x,
  sparse = TRUE,
  prepared = TRUE,
  s2_model = "closed"

st_equals_exact(x, y, par, sparse = TRUE, prepared = FALSE, ...)

st_is_within_distance(x, y = x, dist, sparse = TRUE, ...)



object of class sf, sfc or sfg


object of class sf, sfc or sfg; if missing, x is used


logical; should a sparse index list be returned (TRUE) or a dense logical matrix? See below.


passed on to s2_options


logical; prepare geometry for x, before looping over y? See Details.


character; polygon/polylin model; one of "OPEN", "SEMI_OPEN", and "CLOSED"; see Details.


numeric; parameter used for "equals_exact" (margin);


distance threshold; geometry indexes with distances smaller or equal to this value are returned; numeric value or units value having distance units.


If sparse=FALSE, st_predicate (with predicate e.g. "intersects") returns a dense logical matrix with element i,j TRUE when predicate(x[i], y[j]) (e.g., when geometry of feature i and j intersect); if sparse=TRUE, an object of class sgbp with a sparse list representation of the same matrix, with list element i an integer vector with all indices j for which predicate(x[i],y[j]) is TRUE (and hence a zero-length integer vector if none of them is TRUE). From the dense matrix, one can find out if one or more elements intersect by apply(mat, 1, any), and from the sparse list by lengths(lst) > 0, see examples below.


If prepared is TRUE, and x contains POINT geometries and y contains polygons, then the polygon geometries are prepared, rather than the points.

For most predicates, a spatial index is built on argument x; see Specifically, st_intersects, st_disjoint, st_touches st_crosses, st_within, st_contains, st_contains_properly, st_overlaps, st_equals, st_covers and st_covered_by all build spatial indexes for more efficient geometry calculations. st_relate, st_equals_exact, and do not; st_is_within_distance uses a spatial index for geographic coordinates when sf_use_s2() is true.

If y is missing, `st_predicate(x, x)` is effectively called, and a square matrix is returned with diagonal elements `st_predicate(x[i], x[i])`.

Sparse geometry binary predicate (sgbp) lists have the following attributes: with the row.names of x (if any, else 1:n), ncol with the number of features in y, and predicate with the name of the predicate used.

for s2_model, see

`st_contains_properly(A,B)` is true if A intersects B's interior, but not its edges or exterior; A contains A, but A does not properly contain A.

See also st_relate and for a more detailed description of the underlying algorithms.

st_equals_exact returns true for two geometries of the same type and their vertices corresponding by index are equal up to a specified tolerance.


For intersection on pairs of simple feature geometries, use the function st_intersection instead of st_intersects.


pts = st_sfc(st_point(c(.5,.5)), st_point(c(1.5, 1.5)), st_point(c(2.5, 2.5))) pol = st_polygon(list(rbind(c(0,0), c(2,0), c(2,2), c(0,2), c(0,0)))) (lst = st_intersects(pts, pol))
#> Sparse geometry binary predicate list of length 3, where the predicate was `intersects' #> 1: 1 #> 2: 1 #> 3: (empty)
(mat = st_intersects(pts, pol, sparse = FALSE))
#> [,1] #> [1,] TRUE #> [2,] TRUE #> [3,] FALSE
# which points fall inside a polygon? apply(mat, 1, any)
lengths(lst) > 0
# which points fall inside the first polygon? st_intersects(pol, pts)[[1]]
#> [1] 1 2