% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/spatial.R
\name{spatial_map}
\alias{spatial_map}
\title{Stream a query through an sf transform}
\usage{
spatial_map(
  x,
  fn,
  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{fn}{A function (or purrr-style formula such as \code{~ sf::st_buffer(.x, 1000)}) taking one \code{sf} batch and returning an \code{sf} object, \code{sfc}, or plain
data.frame. The active geometry of the return becomes the output geometry.}

\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} backed by temporary \code{.vtr} spills (removed when the
node is garbage-collected), carrying the output CRS for \code{\link[=collect_sf]{collect_sf()}}.
}
\description{
Applies a per-feature \pkg{sf} operation (buffer, centroid, area, CRS
transform, simplify, ...) to a lazy vectra query one batch at a time and
returns a new lazy node. The engine pulls one batch, hands it to \code{fn} as an
\code{sf} object, encodes the result back into the stream, and spills to disk, so
peak memory is one batch regardless of result size. This is the streaming,
larger-than-RAM counterpart to running the same \code{sf} call on a whole
in-memory table.
}
\details{
Geometry travels through the engine as hex-encoded WKB in an ordinary string
column (vectra has no native geometry type), and the coordinate reference
system is carried on the returned node rather than in the \code{.vtr} file. Use
\code{\link[=collect_sf]{collect_sf()}} to materialize the result as an \code{sf} object, or \code{\link[=collect]{collect()}}
to get the underlying data.frame with the WKB string column.

Topology is delegated entirely to \pkg{sf}/GEOS; vectra only supplies the
streaming. The \code{sf} package is an optional dependency (Suggests).
}
\examples{
\dontshow{if (requireNamespace("sf", quietly = TRUE)) withAutoprint(\{ # examplesIf}
nc <- sf::st_read(system.file("shape/nc.shp", package = "sf"), quiet = TRUE)
f <- tempfile(fileext = ".vtr")
write_vtr(data.frame(
  NAME = nc$NAME,
  geometry = sf::st_as_binary(sf::st_centroid(sf::st_geometry(nc)),
                              hex = TRUE)
), f)

# Buffer every county centroid by 0.1 degree, streaming.
buffered <- tbl(f) |>
  spatial_map(~ sf::st_buffer(.x, 0.1), crs = sf::st_crs(nc))
collect_sf(buffered)
unlink(f)
\dontshow{\}) # examplesIf}
}
\seealso{
\code{\link[=spatial_join]{spatial_join()}} to join a streamed side against a resident \code{sf}
object, \code{\link[=collect_sf]{collect_sf()}} to materialize as \code{sf}.
}
