% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/spatial.R
\name{spatial_split}
\alias{spatial_split}
\title{Split a streamed layer by a resident blade, or return its crossing points}
\usage{
spatial_split(
  x,
  blade,
  extract = c("pieces", "points"),
  geom = "geometry",
  crs = NA,
  out_geom = NULL,
  flush_rows = NULL
)
}
\arguments{
\item{x}{A \code{vectra_node} (from \code{\link[=tbl]{tbl()}}, \code{\link[=tbl_tiff]{tbl_tiff()}}, any verb chain, ...).
It is consumed by the stream.}

\item{blade}{An \code{sf} or \code{sfc} object whose geometry cuts the stream (typically
lines, but any geometry whose boundary can node \code{x}).}

\item{extract}{\code{"pieces"} (default) to emit the split pieces, or \code{"points"}
to emit the intersection points of each feature with the blade.}

\item{geom}{Name of the input geometry column holding hex-WKB or WKT strings.
Default \code{"geometry"}. Ignored when \code{coords} is given.}

\item{crs}{Coordinate reference system of the input geometry, in any form
\code{\link[sf:st_crs]{sf::st_crs()}} accepts (EPSG integer, WKT, proj string). Defaults to the
CRS the upstream node carries, or unknown.}

\item{out_geom}{Name of the output geometry column. Defaults to \code{geom}
(or \code{"geometry"} when \code{coords} is used).}

\item{flush_rows}{Transformed rows buffered before a spill flush. Larger
values mean fewer, bigger temporary files. Defaults to
\code{getOption("vectra.spatial_flush", 5e5)}.}
}
\value{
A \code{vectra_node}: with \code{extract = "pieces"}, one row per piece carrying
\code{x}'s attributes; with \code{extract = "points"}, one row per crossing feature
carrying its intersection points. Backed by temporary \code{.vtr} spills (removed
when the node is garbage-collected) and carrying the input CRS.
}
\description{
Streams a large layer \code{x} through the engine and cuts each batch's geometry
against a small resident \code{blade} layer (the QGIS "split with lines"), one
batch at a time. With \code{extract = "pieces"} (the default) every feature is
divided where the blade crosses it -- a polygon into the faces the blade carves
out, a line into the arcs between crossings -- and each piece is emitted as its
own row with the source attributes copied; a feature the blade does not cross
passes through as a single piece. With \code{extract = "points"} the verb instead
returns, per feature, the points where it meets the blade (the "line
intersections" tool), dropping features that do not cross.
}
\details{
The split is built from \pkg{sf}/GEOS noding and polygonization, so it expects
projected or unprojected planar data; geographic coordinates are best
projected first. The blade is dissolved to one geometry once and held resident
while the left stream flows past. Geometry travels through the engine as
hex-encoded WKB in a string column and the CRS is carried on the returned
node; when \code{blade} carries no CRS it inherits the stream's. The \pkg{sf}
package is an optional dependency (Suggests).
}
\examples{
\dontshow{if (requireNamespace("sf", quietly = TRUE)) withAutoprint(\{ # examplesIf}
sq <- sf::st_polygon(list(rbind(c(0, 0), c(4, 0), c(4, 4), c(0, 4), c(0, 0))))
blade <- sf::st_sfc(sf::st_linestring(rbind(c(2, -1), c(2, 5))))
f <- tempfile(fileext = ".vtr")
write_vtr(data.frame(
  id = 1L, geometry = sf::st_as_binary(sf::st_sfc(sq), hex = TRUE)
), f)

# Split the square into two halves along the blade.
tbl(f) |> spatial_split(blade) |> collect_sf()
unlink(f)
\dontshow{\}) # examplesIf}
}
\seealso{
\code{\link[=spatial_clip]{spatial_clip()}} to cut against a mask without dividing into pieces,
\code{\link[=spatial_overlay]{spatial_overlay()}} to node two polygon layers into a partition,
\code{\link[=collect_sf]{collect_sf()}} to materialize as \code{sf}.
}
