gContains {rgeos} | R Documentation

## Geometry Relationships - Contains and Within

### Description

Functions for testing whether one geometry contains or is contained within another geometry

### Usage

    gContains(spgeom1, spgeom2 = NULL, byid = FALSE, prepared=TRUE,
     returnDense=TRUE, STRsubset=FALSE, checkValidity=FALSE)
    gContainsProperly(spgeom1, spgeom2 = NULL, byid = FALSE, returnDense=TRUE,
     checkValidity=FALSE)
    gCovers(spgeom1, spgeom2 = NULL, byid = FALSE, returnDense=TRUE, checkValidity=FALSE)
    gCoveredBy(spgeom1, spgeom2 = NULL, byid = FALSE, returnDense=TRUE, checkValidity=FALSE)
    gWithin(spgeom1, spgeom2 = NULL, byid = FALSE, returnDense=TRUE, checkValidity=FALSE)

### Arguments

`spgeom1, spgeom2` | sp objects as defined in package sp. If spgeom2 is NULL then spgeom1 is compared to itself.
`byid` | Logical vector determining if the function should be applied across ids (TRUE) or the entire object (FALSE) for spgeom1 and spgeom2
`prepared` | Logical determining if prepared geometry (spatially indexed) version of the GEOS function should be used. In general prepared geometries should be faster than the alternative.
`returnDense` | default TRUE, if false returns a list of the length of spgeom1 of integer vectors listing the `1:length(spgeom2)` indices which would be TRUE in the dense logical matrix representation; useful when the sizes of the byid=TRUE returned matrix is very large and it is sparse; essential when the returned matrix would be too large
`checkValidity` | default FALSE; error meesages from GEOS do not say clearly which object fails if a topology exception is encountered. If this argument is TRUE, `gIsValid` is run on each in turn in an environment in which object names are available. If objects are invalid, this is reported and those affected are named
`STRsubset` | logical argument for future use

### Value

`gContains` returns TRUE if none of the point of `spgeom2` is outside of `spgeom1` and at least one point of `spgeom2` falls within `spgeom1`.

`gContainsProperly` returns TRUE under the same conditions as `gContains` with the additional requirement that `spgeom2` does not intersect with the boundary of `spgeom1`. As such any given geometry will Contain itself but will not ContainProperly itself.

`gCovers` returns TRUE if no point in `spgeom2` is outside of `spgeom1`. This is slightly different from `gContains` as it does not require a point within `spgeom1` which can be an issue as boundaries are not considered to be "within" a geometry, see `gBoundary` for specifics of geometry boundaries.

`gCoveredBy` is the converse of `gCovers` and is equivalent to swapping `spgeom1` and `spgeom2`.

`gWithin` is the converse of `gContains` and is equivalent to swapping `spgeom1` and `spgeom2`.

### Note

Error messages from GEOS, in particular topology exceptions, report 0-based object order, so geom 0 is spgeom1, and geom 1 is spgeom2.

### Author(s)

Roger Bivand & Colin Rundel

### References

Helpful information on the subtle differences between these functions: http://lin-ear-th-inking.blogspot.com/2007/06/subtleties-of-ogc-covers-spatial.html

### See Also

`gCrosses` `gDisjoint` `gEquals` `gEqualsExact` `gIntersects` `gOverlaps` `gRelate` `gTouches`

### Examples

    	l1 = readWKT("LINESTRING(0 3,1 1,2 2,3 0)")
    	l2 = readWKT("LINESTRING(1 3.5,3 3,2 1)")
    	l3 = readWKT("LINESTRING(1 3.5,3 3,4 1)")

    	pt1 = readWKT("MULTIPOINT(1 1,3 0)")
    	pt2 = readWKT("MULTIPOINT(0 3,3 0)")
    	pt3 = readWKT("MULTIPOINT(1 1,2 2,3 1)")

    	p1 = readWKT("POLYGON((0 0,0 2,1 3.5,3 3,4 1,3 0,0 0))")
    	p2 = readWKT("POLYGON((1 1,1 2,2 2,2 1,1 1))")

    	par(mfrow=c(2,3))
    	plot(l1,col='blue');plot(pt1,add=TRUE,pch=16)
    	title(paste("Contains:",gContains(l1,pt1),
    				"\nContainsProperly:",gContainsProperly(l1,pt1),
    				"\nCovers:",gCovers(l1,pt1)))

    	plot(l1,col='blue');plot(pt2,add=TRUE,pch=16)
    	title(paste("Contains:",gContains(l1,pt2),
    				"\nContainsProperly:",gContainsProperly(l1,pt2),
    				"\nCovers:",gCovers(l1,pt2)))

    	plot(p1,col='blue',border='blue');plot(pt3,add=TRUE,pch=16)
    	title(paste("Contains:",gContains(p1,pt3),
    				"\nContainsProperly:",gContainsProperly(p1,pt3),
    				"\nCovers:",gCovers(p1,pt3)))

    	plot(p1,col='blue',border='blue');plot(l2,lwd=2,add=TRUE,pch=16)
    	title(paste("Contains:",gContains(p1,l2),
    				"\nContainsProperly:",gContainsProperly(p1,l2),
    				"\nCovers:",gCovers(p1,l2)))

    	plot(p1,col='blue',border='blue');plot(l3,lwd=2,add=TRUE,pch=16)
    	title(paste("Contains:",gContains(p1,l3),
    				"\nContainsProperly:",gContainsProperly(p1,l3),
    				"\nCovers:",gCovers(p1,l3)))

    	plot(p1,col='blue',border='blue');plot(p2,col='black',add=TRUE,pch=16)
    	title(paste("Contains:",gContains(p1,p2),
    				"\nContainsProperly:",gContainsProperly(p1,p2),
    				"\nCovers:",gCovers(p1,p2)))

[Package rgeos version 0.5-1 Index]