
Geometric binary predicates on pairs of simple feature geometry sets
Source:R/geom-predicates.R
geos_binary_pred.Rd
Geometric binary predicates on pairs of simple feature geometry sets
Usage
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, ..., 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,
...,
retain_unique = FALSE,
remove_self = FALSE
)
st_covers(x, y, sparse = TRUE, prepared = TRUE, ..., model = "closed")
st_covered_by(x, y = x, sparse = TRUE, prepared = TRUE, ..., model = "closed")
st_equals_exact(x, y, par, sparse = TRUE, prepared = FALSE, ...)
st_is_within_distance(x, y = x, dist, sparse = TRUE, ...)
Arguments
- x
object of class
sf
,sfc
orsfg
- y
object of class
sf
,sfc
orsfg
; if missing,x
is used- sparse
logical; should a sparse index list be returned (TRUE) or a dense logical matrix? See below.
- ...
passed on to s2_options
- prepared
logical; prepare geometry for x, before looping over y? See Details.
- model
character; polygon/polyline model; one of "open", "semi-open" or "closed"; see Details.
- retain_unique
logical; if TRUE (and y is missing) return only indexes of points larger than the current index; this can be used to select unique geometries, see examples. This argument can be used for all geometry predictates; see als distinct.sf to find records where geometries AND attributes are distinct.
- remove_self
logical; if TRUE (and y is missing) return only indexes of geometries different from the current index; this can be used to omit self-intersections; see examples. This argument can be used for all geometry predictates
- 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 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.
Details
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 https://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 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: region.id
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 model
, see https://github.com/r-spatial/s2/issues/32
`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.
Note
For intersection on pairs of simple feature geometries, use
the function st_intersection
instead of st_intersects
.
Examples
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)
#> [1] TRUE TRUE FALSE
lengths(lst) > 0
#> [1] TRUE TRUE FALSE
# which points fall inside the first polygon?
st_intersects(pol, pts)[[1]]
#> [1] 1 2
# remove duplicate geometries:
p1 = st_point(0:1)
p2 = st_point(2:1)
p = st_sf(a = letters[1:8], geom = st_sfc(p1, p1, p2, p1, p1, p2, p2, p1))
st_equals(p)
#> Sparse geometry binary predicate list of length 8, where the predicate
#> was `equals'
#> 1: 1, 2, 4, 5, 8
#> 2: 1, 2, 4, 5, 8
#> 3: 3, 6, 7
#> 4: 1, 2, 4, 5, 8
#> 5: 1, 2, 4, 5, 8
#> 6: 3, 6, 7
#> 7: 3, 6, 7
#> 8: 1, 2, 4, 5, 8
st_equals(p, remove_self = TRUE)
#> Sparse geometry binary predicate list of length 8, where the predicate
#> was `equals', with remove_self = TRUE
#> 1: 2, 4, 5, 8
#> 2: 1, 4, 5, 8
#> 3: 6, 7
#> 4: 1, 2, 5, 8
#> 5: 1, 2, 4, 8
#> 6: 3, 7
#> 7: 3, 6
#> 8: 1, 2, 4, 5
(u = st_equals(p, retain_unique = TRUE))
#> Sparse geometry binary predicate list of length 8, where the predicate
#> was `equals', with retain_unique = TRUE
#> 1: 2, 4, 5, 8
#> 2: 4, 5, 8
#> 3: 6, 7
#> 4: 5, 8
#> 5: 8
#> 6: 7
#> 7: (empty)
#> 8: (empty)
# retain the records with unique geometries:
p[-unlist(u),]
#> Simple feature collection with 2 features and 1 field
#> Geometry type: POINT
#> Dimension: XY
#> Bounding box: xmin: 0 ymin: 1 xmax: 2 ymax: 1
#> CRS: NA
#> a geom
#> 1 a POINT (0 1)
#> 3 c POINT (2 1)