1% Generated by roxygen2: do not edit by hand 2% Please edit documentation in R/geom-transformers.R 3\name{geos_unary} 4\alias{geos_unary} 5\alias{st_buffer} 6\alias{st_boundary} 7\alias{st_convex_hull} 8\alias{st_simplify} 9\alias{st_triangulate} 10\alias{st_inscribed_circle} 11\alias{st_voronoi} 12\alias{st_polygonize} 13\alias{st_line_merge} 14\alias{st_centroid} 15\alias{st_point_on_surface} 16\alias{st_reverse} 17\alias{st_node} 18\alias{st_segmentize} 19\title{Geometric unary operations on simple feature geometry sets} 20\usage{ 21st_buffer( 22 x, 23 dist, 24 nQuadSegs = 30, 25 endCapStyle = "ROUND", 26 joinStyle = "ROUND", 27 mitreLimit = 1, 28 singleSide = FALSE, 29 ... 30) 31 32st_boundary(x) 33 34st_convex_hull(x) 35 36st_simplify(x, preserveTopology, dTolerance = 0) 37 38st_triangulate(x, dTolerance = 0, bOnlyEdges = FALSE) 39 40st_inscribed_circle(x, dTolerance, ...) 41 42st_voronoi(x, envelope, dTolerance = 0, bOnlyEdges = FALSE) 43 44st_polygonize(x) 45 46st_line_merge(x) 47 48st_centroid(x, ..., of_largest_polygon = FALSE) 49 50st_point_on_surface(x) 51 52st_reverse(x) 53 54st_node(x) 55 56st_segmentize(x, dfMaxLength, ...) 57} 58\arguments{ 59\item{x}{object of class \code{sfg}, \code{sfc} or \code{sf}} 60 61\item{dist}{numeric; buffer distance for all, or for each of the elements in \code{x}; in case 62\code{dist} is a \code{units} object, it should be convertible to \code{arc_degree} if 63\code{x} has geographic coordinates, and to \code{st_crs(x)$units} otherwise} 64 65\item{nQuadSegs}{integer; number of segments per quadrant (fourth of a circle), for all or per-feature} 66 67\item{endCapStyle}{character; style of line ends, one of 'ROUND', 'FLAT', 'SQUARE'} 68 69\item{joinStyle}{character; style of line joins, one of 'ROUND', 'MITRE', 'BEVEL'} 70 71\item{mitreLimit}{numeric; limit of extension for a join if \code{joinStyle} 'MITRE' is used (default 1.0, minimum 0.0)} 72 73\item{singleSide}{logical; if \code{TRUE}, single-sided buffers are returned for linear geometries, 74in which case negative \code{dist} values give buffers on the right-hand side, positive on the left.} 75 76\item{...}{ignored} 77 78\item{preserveTopology}{logical; carry out topology preserving 79simplification? May be specified for each, or for all feature geometries. 80Note that topology is preserved only for single feature geometries, not for 81sets of them. If not specified (i.e. the default), then it is internally 82set equal to \code{FALSE} when the input data is specified with projected 83coordinates or \code{sf_use_s2()} returns \code{FALSE}. Ignored in all the 84other cases (with a warning when set equal to \code{FALSE}) since the 85function implicitly calls \code{s2::s2_simplify} which always preserve 86topological relationships (per single feature).} 87 88\item{dTolerance}{numeric; tolerance parameter, specified for all or for each 89feature geometry. If you run \code{st_simplify}, the input data is 90specified with long-lat coordinates and \code{sf_use_s2()} returns 91\code{TRUE}, then the value of \code{dTolerance} must be specified in 92meters.} 93 94\item{bOnlyEdges}{logical; if TRUE, return lines, else return polygons} 95 96\item{envelope}{object of class \code{sfc} or \code{sfg} containing a \code{POLYGON} with the envelope for a voronoi diagram; this only takes effect when it is larger than the default envelope, chosen when \code{envelope} is an empty polygon} 97 98\item{of_largest_polygon}{logical; for \code{st_centroid}: if \code{TRUE}, return centroid of the largest (sub)polygon of a \code{MULTIPOLYGON} rather than of the whole \code{MULTIPOLYGON}} 99 100\item{dfMaxLength}{maximum length of a line segment. If \code{x} has geographical coordinates (long/lat), \code{dfMaxLength} is either a numeric expressed in meter, or an object of class \code{units} with length units \code{rad} or \code{degree}; segmentation in the long/lat case takes place along the great circle, using \link[lwgeom:geod]{st_geod_segmentize}.} 101} 102\value{ 103an object of the same class of \code{x}, with manipulated geometry. 104} 105\description{ 106Geometric unary operations on simple feature geometries. These are all generics, with methods for \code{sfg}, \code{sfc} and \code{sf} objects, returning an object of the same class. All operations work on a per-feature basis, ignoring all other features. 107} 108\details{ 109\code{st_buffer} computes a buffer around this geometry/each geometry. If any of \code{endCapStyle}, 110\code{joinStyle}, or \code{mitreLimit} are set to non-default values ('ROUND', 'ROUND', 1.0 respectively) then 111the underlying 'buffer with style' GEOS function is used. 112See \href{https://postgis.net/docs/ST_Buffer.html}{postgis.net/docs/ST_Buffer.html} for details. 113 114\code{st_boundary} returns the boundary of a geometry 115 116\code{st_convex_hull} creates the convex hull of a set of points 117 118\code{st_simplify} simplifies lines by removing vertices. 119 120\code{st_triangulate} triangulates set of points (not constrained). \code{st_triangulate} requires GEOS version 3.4 or above 121 122\code{st_inscribed_circle} returns the maximum inscribed circle for polygon geometries. 123For \code{st_inscribed_circle}, if \code{nQuadSegs} is 0 a 2-point LINESTRING is returned with the 124center point and a boundary point of every circle, otherwise a circle (buffer) is returned where 125\code{nQuadSegs} controls the number of points per quadrant to approximate the circle. 126\code{st_inscribed_circle} requires GEOS version 3.9 or above 127 128\code{st_voronoi} creates voronoi tesselation. \code{st_voronoi} requires GEOS version 3.5 or above 129 130\code{st_polygonize} creates polygon from lines that form a closed ring. In case of \code{st_polygonize}, \code{x} must be an object of class \code{LINESTRING} or \code{MULTILINESTRING}, or an \code{sfc} geometry list-column object containing these 131 132\code{st_line_merge} merges lines. In case of \code{st_line_merge}, \code{x} must be an object of class \code{MULTILINESTRING}, or an \code{sfc} geometry list-column object containing these 133 134\code{st_centroid} gives the centroid of a geometry 135 136\code{st_point_on_surface} returns a point guaranteed to be on the (multi)surface. 137 138\code{st_reverse} reverses the nodes in a line 139 140\code{st_node} adds nodes to linear geometries at intersections without a node, and only works on individual linear geometries 141 142\code{st_segmentize} adds points to straight lines 143} 144\examples{ 145 146## st_buffer, style options (taken from rgeos gBuffer) 147l1 = st_as_sfc("LINESTRING(0 0,1 5,4 5,5 2,8 2,9 4,4 6.5)") 148op = par(mfrow=c(2,3)) 149plot(st_buffer(l1, dist = 1, endCapStyle="ROUND"), reset = FALSE, main = "endCapStyle: ROUND") 150plot(l1,col='blue',add=TRUE) 151plot(st_buffer(l1, dist = 1, endCapStyle="FLAT"), reset = FALSE, main = "endCapStyle: FLAT") 152plot(l1,col='blue',add=TRUE) 153plot(st_buffer(l1, dist = 1, endCapStyle="SQUARE"), reset = FALSE, main = "endCapStyle: SQUARE") 154plot(l1,col='blue',add=TRUE) 155plot(st_buffer(l1, dist = 1, nQuadSegs=1), reset = FALSE, main = "nQuadSegs: 1") 156plot(l1,col='blue',add=TRUE) 157plot(st_buffer(l1, dist = 1, nQuadSegs=2), reset = FALSE, main = "nQuadSegs: 2") 158plot(l1,col='blue',add=TRUE) 159plot(st_buffer(l1, dist = 1, nQuadSegs= 5), reset = FALSE, main = "nQuadSegs: 5") 160plot(l1,col='blue',add=TRUE) 161par(op) 162 163 164l2 = st_as_sfc("LINESTRING(0 0,1 5,3 2)") 165op = par(mfrow = c(2, 3)) 166plot(st_buffer(l2, dist = 1, joinStyle="ROUND"), reset = FALSE, main = "joinStyle: ROUND") 167plot(l2, col = 'blue', add = TRUE) 168plot(st_buffer(l2, dist = 1, joinStyle="MITRE"), reset = FALSE, main = "joinStyle: MITRE") 169plot(l2, col= 'blue', add = TRUE) 170plot(st_buffer(l2, dist = 1, joinStyle="BEVEL"), reset = FALSE, main = "joinStyle: BEVEL") 171plot(l2, col= 'blue', add=TRUE) 172plot(st_buffer(l2, dist = 1, joinStyle="MITRE" , mitreLimit=0.5), reset = FALSE, 173 main = "mitreLimit: 0.5") 174plot(l2, col = 'blue', add = TRUE) 175plot(st_buffer(l2, dist = 1, joinStyle="MITRE",mitreLimit=1), reset = FALSE, 176 main = "mitreLimit: 1") 177plot(l2, col = 'blue', add = TRUE) 178plot(st_buffer(l2, dist = 1, joinStyle="MITRE",mitreLimit=3), reset = FALSE, 179 main = "mitreLimit: 3") 180plot(l2, col = 'blue', add = TRUE) 181par(op) 182nc = st_read(system.file("shape/nc.shp", package="sf")) 183nc_g = st_geometry(nc) 184plot(st_convex_hull(nc_g)) 185plot(nc_g, border = grey(.5), add = TRUE) 186 187# st_simplify examples: 188op = par(mfrow = c(2, 3), mar = rep(0, 4)) 189plot(nc_g[1]) 190plot(st_simplify(nc_g[1], dTolerance = 1e3)) # 1000m 191plot(st_simplify(nc_g[1], dTolerance = 5e3)) # 5000m 192nc_g_planar = st_transform(nc_g, 2264) # planar coordinates, US foot 193plot(nc_g_planar[1]) 194plot(st_simplify(nc_g_planar[1], dTolerance = 1e3)) # 1000 foot 195plot(st_simplify(nc_g_planar[1], dTolerance = 5e3)) # 5000 foot 196par(op) 197 198if (compareVersion(sf_extSoftVersion()[["GEOS"]], "3.9.0") > -1) { 199 nc_t = st_transform(nc, 'EPSG:2264') 200 x = st_inscribed_circle(st_geometry(nc_t)) 201 plot(st_geometry(nc_t), asp = 1, col = grey(.9)) 202 plot(x, add = TRUE, col = '#ff9999') 203} 204set.seed(1) 205x = st_multipoint(matrix(runif(10),,2)) 206box = st_polygon(list(rbind(c(0,0),c(1,0),c(1,1),c(0,1),c(0,0)))) 207if (compareVersion(sf_extSoftVersion()[["GEOS"]], "3.5.0") > -1) { 208 v = st_sfc(st_voronoi(x, st_sfc(box))) 209 plot(v, col = 0, border = 1, axes = TRUE) 210 plot(box, add = TRUE, col = 0, border = 1) # a larger box is returned, as documented 211 plot(x, add = TRUE, col = 'red', cex=2, pch=16) 212 plot(st_intersection(st_cast(v), box)) # clip to smaller box 213 plot(x, add = TRUE, col = 'red', cex=2, pch=16) 214 # matching Voronoi polygons to data points: 215 # https://github.com/r-spatial/sf/issues/1030 216 # generate 50 random unif points: 217 n = 100 218 pts = st_as_sf(data.frame(matrix(runif(n), , 2), id = 1:(n/2)), coords = c("X1", "X2")) 219 # compute Voronoi polygons: 220 pols = st_collection_extract(st_voronoi(do.call(c, st_geometry(pts)))) 221 # match them to points: 222 pts$pols = pols[unlist(st_intersects(pts, pols))] 223 plot(pts["id"], pch = 16) # ID is color 224 plot(st_set_geometry(pts, "pols")["id"], xlim = c(0,1), ylim = c(0,1), reset = FALSE) 225 plot(st_geometry(pts), add = TRUE) 226 layout(matrix(1)) # reset plot layout 227} 228mls = st_multilinestring(list(matrix(c(0,0,0,1,1,1,0,0),,2,byrow=TRUE))) 229st_polygonize(st_sfc(mls)) 230mls = st_multilinestring(list(rbind(c(0,0), c(1,1)), rbind(c(2,0), c(1,1)))) 231st_line_merge(st_sfc(mls)) 232plot(nc_g, axes = TRUE) 233plot(st_centroid(nc_g), add = TRUE, pch = 3, col = 'red') 234mp = st_combine(st_buffer(st_sfc(lapply(1:3, function(x) st_point(c(x,x)))), 0.2 * 1:3)) 235plot(mp) 236plot(st_centroid(mp), add = TRUE, col = 'red') # centroid of combined geometry 237plot(st_centroid(mp, of_largest_polygon = TRUE), add = TRUE, col = 'blue', pch = 3) 238plot(nc_g, axes = TRUE) 239plot(st_point_on_surface(nc_g), add = TRUE, pch = 3, col = 'red') 240if (compareVersion(sf_extSoftVersion()[["GEOS"]], "3.7.0") > -1) { 241 st_reverse(st_linestring(rbind(c(1,1), c(2,2), c(3,3)))) 242} 243(l = st_linestring(rbind(c(0,0), c(1,1), c(0,1), c(1,0), c(0,0)))) 244st_polygonize(st_node(l)) 245st_node(st_multilinestring(list(rbind(c(0,0), c(1,1), c(0,1), c(1,0), c(0,0))))) 246sf = st_sf(a=1, geom=st_sfc(st_linestring(rbind(c(0,0),c(1,1)))), crs = 4326) 247seg = st_segmentize(sf, units::set_units(100, km)) 248seg = st_segmentize(sf, units::set_units(0.01, rad)) 249nrow(seg$geom[[1]]) 250} 251