sf (version 0.4-3)

geos: Geometric operations on (pairs of) simple feature geometry sets

Description

Geometric operations on (pairs of) simple feature geometry sets

Usage

st_dimension(x, NA_if_empty = TRUE)
st_area(x)
st_length(x, dist_fun = geosphere::distGeo)
st_is_simple(x)
st_distance(x, y, dist_fun)
st_relate(x, y, pattern = NA_character_, sparse = !is.na(pattern))
st_intersects(x, y, sparse = TRUE, prepared = TRUE)
st_disjoint(x, y, 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_buffer(x, dist, nQuadSegs = 30)
st_boundary(x)
st_convex_hull(x)
st_simplify(x, preserveTopology = FALSE, dTolerance = 0)
st_triangulate(x, dTolerance = 0, bOnlyEdges = FALSE)
st_voronoi(x, envelope, dTolerance = 0, bOnlyEdges = FALSE)
st_polygonize(x)
st_line_merge(x)
st_centroid(x)
st_segmentize(x, dfMaxLength, ...)
st_combine(x)
st_intersection(x, y)
st_difference(x, y)
st_sym_difference(x, y)
st_union(x, y, ..., by_feature = FALSE)
st_line_sample(x, n, density, type = "regular", sample = NULL)

Arguments

x

object of class sf, sfc or sfg

NA_if_empty

logical; if TRUE, return NA for empty geometries

dist_fun

function to be used for great circle distances of geographical coordinates; for unprojected (long/lat) data, this should be a distance function of package geosphere, or compatible to that; it defaults to distGeo in that case; for other data metric lengths are computed.

y

object of class sf, sfc or sfg

pattern

character; define the pattern to match to, see details.

sparse

logical; should a sparse matrix be returned (TRUE) or a dense matrix?

prepared

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

par

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

dist

numeric; buffer distance for all, or for each of the elements in x

nQuadSegs

integer; number of segments per quadrant (fourth of a circle)

preserveTopology

logical; carry out topology preserving simplification?

dTolerance

numeric; tolerance parameter

bOnlyEdges

logical; if TRUE, return lines, else return polygons

envelope

object of class sfc or sfg with the envelope for a voronoi diagram

dfMaxLength

maximum length of a line segment. If x has geographical coordinates (long/lat), dfMaxLength is a numeric with length with unit metre, or an object of class units with length units; in this case, segmentation takes place along the great circle, using gcIntermediate.

...

ignored

by_feature

logical; if TRUE, union each feature, if FALSE return a single feature with the union the set of features

n

integer; number of points to choose per geometry; if missing, n will be computed as round(density * st_length(geom)).

density

numeric; density (points per distance unit) of the sampling, possibly a vector of length equal to the number of features (otherwise recycled); density may be of class units.

type

character; indicate the sampling type, either "regular" or "random"

sample

numeric; a vector of numbers between 0 and 1 indicating the points to sample - if defined sample overrules n, density and type.

Value

vector, matrix, or if sparse=TRUE a list representing a sparse logical matrix; if dense: matrix of type character for st_relate, of type numeric for st_distance, and logical for all others; matrix has dimension NROW(x) by NROW(y); if sparse (only for logical predicates): a list of length NROW(x), with entry i an integer vector with the TRUE indices for that row (if m is the dense matrix, list entry l[[i]] is identical to which(m[i,])).

st_dimension returns a numeric vector with 0 for points, 1 for lines, 2 for surfaces, and, if NA_if_empty is TRUE, NA for empty geometries.

st_area returns the area of a geometry, in the coordinate reference system used; in case x is in degrees longitude/latitude, areaPolygon is used for area calculation.

st_length returns the length of a LINESTRING or MULTILINESTRING geometry, using the coordinate reference system used; if the coordinate reference system of x was set, the returned value has a unit of measurement. POINT or MULTIPOINT geometries return zero, POLYGON or MULTIPOLYGON are converted into LINESTRING or MULTILINESTRING, respectively.

st_is_simple returns a logical vector

st_distance returns a dense numeric matrix of dimension length(x) by length(y)

in case pattern is not given, st_relate returns a dense character matrix; element [i,j] has nine characters, refering to the DE9-IM relationship between x[i] and y[j], encoded as IxIy,IxBy,IxEy,BxIy,BxBy,BxEy,ExIy,ExBy,ExEy where I refers to interior, B to boundary, and E to exterior, and e.g. BxIy the dimensionality of the intersection of the the boundary of x[i] and the interior of y[j], which is one of 0,1,2,F, digits denoting dimensionality, F denoting not intersecting. When pattern is given, returns a dense logical or sparse index list with matches to the given pattern; see also https://en.wikipedia.org/wiki/DE-9IM.

the binary logical functions (st_intersects up to st_equals_exact) return a sparse or dense logical matrix with rows and columns corresponding to the number of geometries (or rows) in x and y, respectively

st_buffer, st_boundary, st_convex_hull, st_simplify, st_triangulate, st_voronoi, st_polygonize, st_line_merge, st_centroid and st_segmentize return an sfc or an sf object with the same number of geometries as in x

All functions (or methods) returning a geometry return an object of the same class as that of the first argument (x). st_intersection, st_union, st_difference and st_sym_difference return the non-empty geometries resulting from applying the operation to all geometry pairs in x and y, and return an object of class sfg, sfc or sf, where in the latter case the matching attributes of the original object(s) are added. The sfc geometry list-column returned carries an attribute idx, which is an n x 2 matrix with every row the index of the corresponding entries of x and y, respectively. st_union has in addition the ability to work on a single argument x (y missing): in this case, if by_feature is FALSE all geometries are unioned together and an sfg or single-geometry sfc object is returned, if by_feature is TRUE each feature geometry is unioned; this can for instance be used to resolve internal boundaries after polygons were combined using st_combine.

st_union(x) unions geometries. Unioning a set of overlapping polygons has the effect of merging the areas (i.e. the same effect as iteratively unioning all individual polygons together). Unioning a set of LineStrings has the effect of fully noding and dissolving the input linework. In this context "fully noded" means that there will be a node or endpoint in the output for every endpoint or line segment crossing in the input. "Dissolved" means that any duplicate (e.g. coincident) line segments or portions of line segments will be reduced to a single line segment in the output. Unioning a set of Points has the effect of merging al identical points (producing a set with no duplicates).

Details

function dist_fun should follow the pattern of the distance function distGeo: the first two arguments must be 2-column point matrices, the third the semi major axis (radius, in m), the third the ellipsoid flattening.

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

st_triangulate requires GEOS version 3.4 or above

st_voronoi requires GEOS version 3.4 or above

in case of st_polygonize, x must be an object of class LINESTRING or MULTILINESTRING, or an sfc geometry list-column object containing these

in case of st_line_merge, x must be an object of class MULTILINESTRING, or an sfc geometry list-column object containing these

st_combine combines geometries without resolving borders, using c.sfg; see st_union for resolving boundaries.

Examples

x = st_sfc(
	st_point(0:1), 
	st_linestring(rbind(c(0,0),c(1,1))), 
	st_polygon(list(rbind(c(0,0),c(1,0),c(0,1),c(0,0)))),
	st_multipoint(),
	st_linestring(),
	st_geometrycollection())
st_dimension(x)
st_dimension(x, FALSE)
dist_vincenty = function(p1, p2, a, f) geosphere::distVincentyEllipsoid(p1, p2, a, a * (1-f), f)
line = st_sfc(st_linestring(rbind(c(30,30), c(40,40))), crs = 4326)
st_length(line)
st_length(line, dist_fun = dist_vincenty)
p1 = st_point(c(0,0))
p2 = st_point(c(2,2))
pol1 = st_polygon(list(rbind(c(0,0),c(1,0),c(1,1),c(0,1),c(0,0)))) - 0.5
pol2 = pol1 + 1
pol3 = pol1 + 2
st_relate(st_sfc(p1, p2), st_sfc(pol1, pol2, pol3))
sfc = st_sfc(st_point(c(0,0)), st_point(c(3,3)))
grd = st_make_grid(sfc, n = c(3,3))
st_intersects(grd)
st_relate(grd, pattern = "****1****") # sides, not corners, internals
st_relate(grd, pattern = "****0****") # only corners touch
st_rook = function(a, b = a) st_relate(a, b, pattern = "F***1****")
st_rook(grd)
# queen neighbours, see https://github.com/edzer/sfr/issues/234#issuecomment-300511129
st_queen <- function(a, b = a) st_relate(a, b, pattern = "F***T****")
nc = st_read(system.file("shape/nc.shp", package="sf"))
plot(st_convex_hull(nc))
plot(nc, border = grey(.5))
set.seed(1)
x = st_multipoint(matrix(runif(10),,2))
box = st_polygon(list(rbind(c(0,0),c(1,0),c(1,1),c(0,1),c(0,0))))
if (sf_extSoftVersion()["GEOS"] >= "3.5.0") {
 v = st_sfc(st_voronoi(x, st_sfc(box)))
 plot(v, col = 0, border = 1, axes = TRUE)
 plot(box, add = TRUE, col = 0, border = 1) # a larger box is returned, as documented
 plot(x, add = TRUE, col = 'red', cex=2, pch=16)
 plot(st_intersection(st_cast(v), box)) # clip to smaller box
 plot(x, add = TRUE, col = 'red', cex=2, pch=16)
}
mls = st_multilinestring(list(matrix(c(0,0,0,1,1,1,0,0),,2,byrow=TRUE)))
st_polygonize(st_sfc(mls))
mls = st_multilinestring(list(rbind(c(0,0), c(1,1)), rbind(c(2,0), c(1,1))))
st_line_merge(st_sfc(mls))
plot(nc, axes = TRUE)
plot(st_centroid(nc), add = TRUE, pch = 3)
sf = st_sf(a=1, geom=st_sfc(st_linestring(rbind(c(0,0),c(1,1)))), crs = 4326)
seg = st_segmentize(sf, units::set_units(100, km))
nrow(seg$geom[[1]])
st_combine(nc)
plot(st_union(nc))
ls = st_sfc(st_linestring(rbind(c(0,0),c(0,1))),
	st_linestring(rbind(c(0,0),c(10,0))))
st_line_sample(ls, density = 1)
ls = st_sfc(st_linestring(rbind(c(0,0),c(0,1))),
 st_linestring(rbind(c(0,0),c(.1,0))), crs = 4326)
try(st_line_sample(ls, density = 1/1000)) # error
st_line_sample(st_transform(ls, 3857), n = 5) # five points for each line
st_line_sample(st_transform(ls, 3857), n = c(1, 3)) # one and three points
st_line_sample(st_transform(ls, 3857), density = 1/1000) # one per km
st_line_sample(st_transform(ls, 3857), density = c(1/1000, 1/10000)) # one per km, one per 10 km
st_line_sample(st_transform(ls, 3857), density = units::set_units(1, 1/km)) # one per km
# five equidistant points including start and end:
st_line_sample(st_transform(ls, 3857), sample = c(0, 0.25, 0.5, 0.75, 1))