sf (version 0.5-5)

geos_binary_pred: Geometric binary predicates on pairs of simple feature geometry sets

Description

Geometric binary predicates on pairs of simple feature geometry sets

Usage

st_intersects(x, y, sparse = TRUE, prepared = 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)
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)
st_covered_by(x, y, sparse = TRUE, prepared = TRUE)
st_equals_exact(x, y, par, sparse = TRUE, prepared = FALSE)
st_is_within_distance(x, y, dist, sparse = TRUE, prepared = FALSE)

Arguments

x

object of class sf, sfc or sfg

y

object of class sf, sfc or sfg

sparse

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

prepared

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

par

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

dist

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

Value

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 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 a numeric vector with the indices j for which predicate(x[i],y[j]) is TRUE (and hence integer(0) 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.

Details

For most predicates, a spatial index is built on argument x; see http://r-spatial.org/r/2017/06/22/spatial-index.html. 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 st_is_within_distance do not.

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

`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 https://en.wikipedia.org/wiki/DE-9IM 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.

st_is_within_distance returns a sparse matrix only, and can only be used for non-geographic (Cartesian) coordinates; use st_distance(x,y) <= dist to obtain the corresponding dense logical matrix.

Examples

# NOT RUN {
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))
(mat = st_intersects(pts, pol, sparse = 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]]
# }