R: relate

relate {terra} | R Documentation

## relate

### Description

Get a matrix indicating the presence or absence of spatial relationships between geometries.

### Usage

    ## S4 method for signature 'SpatVector,SpatVector'
    relate(x, y, relation)

    ## S4 method for signature 'SpatVector,missing'
    relate(x, y, relation, pairs=FALSE, symmetrical=FALSE)

### Arguments

`x` | SpatVector or any object for which vect returns a SpatVector or else for which `ext` returns a SpatExtent
`y` | missing or as for `x`
`relation` | character. One of "intersects", "touches", "crosses", "overlaps", "within", "contains", "covers", "coveredby", "disjoint". Or a "DE-9IM" string such as "FF*FF****". See wikipedia or geotools doc
`pairs` | logical. If `TRUE` a "from", "to" matrix is returned for the cases where the requested relation is `TRUE`
`symmetrical` | logical. If `TRUE` and `pairs=TRUE`, the relation between a pair is only included once. For example, the relation between geometry 1 and 3 is included, but the relation between 3 and 1 is not. Note that whole some relationships are symmetrical (e.g. "touches", other are not (e.g. "within")

### Value

matrix

### See Also

`adjacent`, `nearby`, `intersect`, `crop`

### Examples

    # polygons
    p1 <- vect("POLYGON ((0 0, 8 0, 8 9, 0 9, 0 0))")
    p2 <- vect("POLYGON ((5 6, 15 6, 15 15, 5 15, 5 6))")
    p3 <- vect("POLYGON ((8 2, 9 2, 9 3, 8 3, 8 2))")
    p4 <- vect("POLYGON ((2 6, 3 6, 3 8, 2 8, 2 6))")
    p5 <- vect("POLYGON ((2 12, 3 12, 3 13, 2 13, 2 12))")
    p6 <- vect("POLYGON ((10 4, 12 4, 12 7, 11 7, 11 6, 10 6, 10 4))")

    p <- rbind(p1, p2, p3, p4, p5, p6)
    plot(p, col=rainbow(6, alpha=.5))
    lines(p, lwd=2)
    text(p)

    ## relate SpatVectors
    relate(p1, p2, "intersects")
    relate(p1, p3, "touches")
    relate(p1, p5, "disjoint")
    relate(rbind(p1, p2), p4, "disjoint")

    ## relate geometries within SpatVectors
    # which are completely separated?
    relate(p, relation="disjoint")

    # which touch (not overlap or within)?
    relate(p, relation="touches")
    # which overlap (not merely touch, and not within)?
    relate(p, relation="overlaps")
    # which are within (not merely overlap)?
    relate(p, relation="within")

    # do they touch or overlap or are within?
    relate(p, relation="intersects")

    all(relate(p, relation="intersects") ==
      (relate(p, relation="overlaps") |
       relate(p, relation="touches") |
       relate(p, relation="within")))

    #for polygons, "coveredby" is "within"
    relate(p, relation="coveredby")

    # polygons, lines, and points

    pp <- rbind(p1, p2)
    L1 <- vect("LINESTRING(1 11, 4 6, 10 6)")
    L2 <- vect("LINESTRING(8 14, 12 10)")
    L3 <- vect("LINESTRING(1 8, 12 14)")
    lns <- rbind(L1, L2, L3)
    pts <- vect(cbind(c(7,10,10), c(3,5,6)))

    plot(pp, col=rainbow(2, alpha=.5))
    text(pp, paste0("POL", 1:2), halo=TRUE)
    lines(pp, lwd=2)
    lines(lns, col=rainbow(3), lwd=4)
    text(lns, paste0("L", 1:3), halo=TRUE)
    points(pts, cex=1.5)
    text(pts, paste0("PT", 1:3), halo=TRUE, pos=4)

    relate(lns, relation="crosses")
    relate(lns, pp, relation="crosses")
    relate(lns, pp, relation="touches")
    relate(lns, pp, relation="intersects")

    relate(lns, pp, relation="within")
    # polygons can contain lines or points, not the other way around
    relate(lns, pp, relation="contains")
    relate(pp, lns, relation="contains")
    # points and lines can be covered by polygons
    relate(lns, pp, relation="coveredby")

    relate(pts, pp, "within")
    relate(pts, pp, "touches")
    relate(pts, lns, "touches")

[Package terra version 1.4-22 Index]