% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/spatial.R
\name{spatial_snap}
\alias{spatial_snap}
\title{Snap a streamed layer toward a resident reference layer}
\usage{
spatial_snap(
  x,
  y,
  tolerance,
  geom = "geometry",
  coords = NULL,
  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{y}{An \code{sf} or \code{sfc} object: the resident reference layer to snap toward.}

\item{tolerance}{Snapping distance in CRS units (a positive number). Vertices
and edges of \code{x} within this distance of \code{y} are moved onto \code{y}.}

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

\item{coords}{Optional length-2 character vector naming the x and y
coordinate columns to assemble point geometry from (e.g. \code{c("x", "y")}),
for inputs such as \code{\link[=tiff_extract_points]{tiff_extract_points()}} output. The coordinate columns
are retained.}

\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} of the snapped geometry with \code{x}'s attributes, 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 snaps each batch's vertices
toward a small resident reference layer \code{y} when they lie within \code{tolerance}
(in CRS units), one batch at a time (the QGIS "snap geometries to layer").
Vertices and edges of \code{x} closer than \code{tolerance} to \code{y} are pulled onto \code{y},
which closes the small gaps and overshoots between two layers that should
share a boundary. The reference layer stays resident while the billion-row
left stream flows past; the snap itself is \pkg{sf}'s \code{\link[sf:st_snap]{sf::st_snap()}}.
}
\details{
Geometry travels through the engine as hex-encoded WKB in a string column and
the CRS is carried on the returned node; use \code{\link[=collect_sf]{collect_sf()}} to materialize.
When \code{y} 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}
ref <- sf::st_sfc(sf::st_linestring(rbind(c(0, 0), c(10, 0))))
line <- sf::st_linestring(rbind(c(0, 0.2), c(5, 0.1), c(10, 0.2)))
f <- tempfile(fileext = ".vtr")
write_vtr(data.frame(
  id = 1L, geometry = sf::st_as_binary(sf::st_sfc(line), hex = TRUE)
), f)

# Pull the near-zero vertices down onto the reference line.
tbl(f) |> spatial_snap(ref, tolerance = 0.5) |> collect_sf()
unlink(f)
\dontshow{\}) # examplesIf}
}
\seealso{
\code{\link[=spatial_snap_grid]{spatial_snap_grid()}} to snap to a grid instead of a layer,
\code{\link[=spatial_clip]{spatial_clip()}} for the resident-mask streaming pattern, \code{\link[=collect_sf]{collect_sf()}}.
}
