R: Geometric binary predicates on pairs of simple feature...

geos_binary_pred {sf} | R Documentation

## 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, ...)

    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")

    st_covered_by(
      x,
      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, ...)

### Arguments

`x` | object of class `sf`, `sfc` or `sfg`
`y` | object of class `sf`, `sfc` or `sfg`; 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.
`s2_model` | character; polygon/polyline model; one of "open", "semi-open" or "closed"; see Details.
`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.

### 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://www.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 `s2_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.

### 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.

### 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))
    (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]]

[Package sf version 0.9-7 Index]